diff options
Diffstat (limited to 'Documentation')
676 files changed, 35065 insertions, 13624 deletions
diff --git a/Documentation/ABI/obsolete/sysfs-selinux-disable b/Documentation/ABI/obsolete/sysfs-selinux-disable new file mode 100644 index 000000000000..c340278e3cf8 --- /dev/null +++ b/Documentation/ABI/obsolete/sysfs-selinux-disable @@ -0,0 +1,26 @@ +What: /sys/fs/selinux/disable +Date: April 2005 (predates git) +KernelVersion: 2.6.12-rc2 (predates git) +Contact: selinux@vger.kernel.org +Description: + + 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/stable/sysfs-class-tpm b/Documentation/ABI/stable/sysfs-class-tpm index c0e23830f56a..58e94e7d55be 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,7 +29,7 @@ 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: @@ -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 @@ -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,7 +86,7 @@ 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 @@ -109,7 +109,7 @@ 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 @@ -161,7 +161,7 @@ Description: The "pubek" property will return the TPM's public endorsement 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 deactivated, usually until the next power cycle. Whether a warm boot (reboot) will clear a TPM chip @@ -170,7 +170,7 @@ Description: The "temp_deactivated" property returns a '1' if the chip has 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 @@ -183,3 +183,14 @@ Description: The "timeouts" property shows the 4 vendor-specific values 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 diff --git a/Documentation/ABI/stable/sysfs-driver-dma-idxd b/Documentation/ABI/stable/sysfs-driver-dma-idxd new file mode 100644 index 000000000000..f4be46cc6cb6 --- /dev/null +++ b/Documentation/ABI/stable/sysfs-driver-dma-idxd @@ -0,0 +1,171 @@ +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. + +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_tokens +Date: Oct 25, 2019 +KernelVersion: 5.6.0 +Contact: dmaengine@vger.kernel.org +Description: The total number of bandwidth tokens supported by this device. + The bandwidth tokens represent resources within the DSA + implementation, and these resources are allocated by engines to + support operations. + +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>/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>/token_limit +Date: Oct 25, 2019 +KernelVersion: 5.6.0 +Contact: dmaengine@vger.kernel.org +Description: The maximum number of bandwidth tokens that may be in use at + one time by operations that access low bandwidth memory in the + device. + +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 vlue 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/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. diff --git a/Documentation/ABI/stable/sysfs-driver-mlxreg-io b/Documentation/ABI/stable/sysfs-driver-mlxreg-io index 8ca498447aeb..b0d90cc696a8 100644 --- a/Documentation/ABI/stable/sysfs-driver-mlxreg-io +++ b/Documentation/ABI/stable/sysfs-driver-mlxreg-io @@ -1,5 +1,4 @@ What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/asic_health - Date: June 2018 KernelVersion: 4.19 Contact: Vadim Pasternak <vadimpmellanox.com> @@ -19,7 +18,6 @@ Description: These files show with which CPLD versions have been burned 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 <vadimpmellanox.com> @@ -29,18 +27,16 @@ Description: This file shows the system fans direction: The files are read only. -What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/jtag_enable - +What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/cpld3_version Date: November 2018 KernelVersion: 5.0 Contact: Vadim Pasternak <vadimpmellanox.com> Description: These files show with which CPLD versions have been burned - on LED board. + 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 <vadimpmellanox.com> @@ -108,7 +104,6 @@ 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 <vadimpmellanox.com> @@ -121,6 +116,21 @@ Description: These files show the system reset cause, as following: ComEx 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 <vadimpmellanox.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 <vadimpmellanox.com> @@ -134,9 +144,65 @@ Description: These files show the system reset cause, as following: 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 +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 <vadimpmellanox.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 <vadimpmellanox.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 <vadimpmellanox.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 <vadimpmellanox.com> +Description: This file allows to overwrite system VPD hardware wrtie + 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 <vadimpmellanox.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 <vadimpmellanox.com> +Description: This file exposes the firmware version of burnable voltage + regulator devices. + + The file is read only. diff --git a/Documentation/ABI/testing/configfs-usb-gadget b/Documentation/ABI/testing/configfs-usb-gadget index 95a36589a66b..4594cc2435e8 100644 --- a/Documentation/ABI/testing/configfs-usb-gadget +++ b/Documentation/ABI/testing/configfs-usb-gadget @@ -16,6 +16,10 @@ Description: 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 diff --git a/Documentation/ABI/testing/ima_policy b/Documentation/ABI/testing/ima_policy index 29aaedf33246..cd572912c593 100644 --- a/Documentation/ABI/testing/ima_policy +++ b/Documentation/ABI/testing/ima_policy @@ -25,11 +25,11 @@ Description: lsm: [[subj_user=] [subj_role=] [subj_type=] [obj_user=] [obj_role=] [obj_type=]] option: [[appraise_type=]] [template=] [permit_directio] - [appraise_flag=] + [appraise_flag=] [keyrings=] base: func:= [BPRM_CHECK][MMAP_CHECK][CREDS_CHECK][FILE_CHECK][MODULE_CHECK] [FIRMWARE_CHECK] [KEXEC_KERNEL_CHECK] [KEXEC_INITRAMFS_CHECK] - [KEXEC_CMDLINE] + [KEXEC_CMDLINE] [KEY_CHECK] mask:= [[^]MAY_READ] [[^]MAY_WRITE] [[^]MAY_APPEND] [[^]MAY_EXEC] fsmagic:= hex value @@ -42,6 +42,9 @@ Description: appraise_flag:= [check_blacklist] Currently, blacklist check is only for files signed with appended signature. + 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 @@ -113,3 +116,12 @@ Description: 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 diff --git a/Documentation/ABI/testing/rtc-cdev b/Documentation/ABI/testing/rtc-cdev index 97447283f13b..25910c3c3d7e 100644 --- a/Documentation/ABI/testing/rtc-cdev +++ b/Documentation/ABI/testing/rtc-cdev @@ -33,6 +33,14 @@ Description: 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 diff --git a/Documentation/ABI/testing/sysfs-bus-iio b/Documentation/ABI/testing/sysfs-bus-iio index faaa2166d741..d3e53a6d8331 100644 --- a/Documentation/ABI/testing/sysfs-bus-iio +++ b/Documentation/ABI/testing/sysfs-bus-iio @@ -1726,3 +1726,16 @@ 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. 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-mdio b/Documentation/ABI/testing/sysfs-bus-mdio new file mode 100644 index 000000000000..da86efc7781b --- /dev/null +++ b/Documentation/ABI/testing/sysfs-bus-mdio @@ -0,0 +1,63 @@ +What: /sys/bus/mdio_bus/devices/.../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 +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 +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 +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 +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> +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> +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> +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> +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-class-devfreq b/Documentation/ABI/testing/sysfs-class-devfreq index 01196e19afca..9758eb85ade3 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> @@ -48,12 +55,15 @@ What: /sys/class/devfreq/.../trans_stat Date: October 2012 Contact: MyungJoo Ham <myungjoo.ham@samsung.com> Description: - 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. + 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: + echo 0 > /sys/class/devfreq/.../trans_stat What: /sys/class/devfreq/.../userspace/set_freq Date: September 2011 diff --git a/Documentation/ABI/testing/sysfs-class-power b/Documentation/ABI/testing/sysfs-class-power index 27edc06e2495..bf3b48f022dc 100644 --- a/Documentation/ABI/testing/sysfs-class-power +++ b/Documentation/ABI/testing/sysfs-class-power @@ -189,7 +189,8 @@ Description: Access: Read Valid values: "Unknown", "Good", "Overheat", "Dead", "Over voltage", "Unspecified failure", "Cold", - "Watchdog timer expire", "Safety timer expire" + "Watchdog timer expire", "Safety timer expire", + "Over current" What: /sys/class/power_supply/<supply_name>/precharge_current Date: June 2017 diff --git a/Documentation/ABI/testing/sysfs-devices-system-cpu b/Documentation/ABI/testing/sysfs-devices-system-cpu index fc20cde63d1e..2e0e3b45d02a 100644 --- a/Documentation/ABI/testing/sysfs-devices-system-cpu +++ b/Documentation/ABI/testing/sysfs-devices-system-cpu @@ -196,6 +196,12 @@ Description: 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/stateN/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/stateN/residency Date: March 2014 diff --git a/Documentation/ABI/testing/sysfs-driver-pciback b/Documentation/ABI/testing/sysfs-driver-pciback index 6a733bfa37e6..73308c2b81b0 100644 --- a/Documentation/ABI/testing/sysfs-driver-pciback +++ b/Documentation/ABI/testing/sysfs-driver-pciback @@ -11,3 +11,16 @@ Description: #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-xen-blkback b/Documentation/ABI/testing/sysfs-driver-xen-blkback index 4e7babb3ba1f..ecb7942ff146 100644 --- a/Documentation/ABI/testing/sysfs-driver-xen-blkback +++ b/Documentation/ABI/testing/sysfs-driver-xen-blkback @@ -25,3 +25,13 @@ Description: 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: SeongJae Park <sjpark@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. diff --git a/Documentation/ABI/testing/sysfs-fs-f2fs b/Documentation/ABI/testing/sysfs-fs-f2fs index aedeae1e8ec1..1a6cd5397129 100644 --- a/Documentation/ABI/testing/sysfs-fs-f2fs +++ b/Documentation/ABI/testing/sysfs-fs-f2fs @@ -1,37 +1,40 @@ 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. 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. - -What: /sys/fs/f2fs/<disk>/max_blkaddr +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: @@ -40,227 +43,278 @@ Description: 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: + 0x01: F2FS_IPU_FORCE, 0x02: F2FS_IPU_SSR, + 0x04: F2FS_IPU_UTIL, 0x08: F2FS_IPU_SSR_UTIL, + 0x10: F2FS_IPU_FSYNC, 0x20: F2FS_IPU_ASYNC, + 0x40: F2FS_IPU_NOCACHE. + 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. - +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. +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 fee section threshold to trigger SSR allocation. +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 until + checkpoint is triggered, and issued during the checkpoint. + By default, it is disabled with 0. -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 +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, now only support configuring in range - of [1, 512]. + The unit size is one block(4KB), now only support configuring + in range of [1, 512]. Default value is 4(=16KB). -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>/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>/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. +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>/batched_trim_sections Date: February 2015 Contact: "Jaegeuk Kim" <jaegeuk@kernel.org> -Description: - Controls the trimming rate in batch mode. - <deprecated> +Description: Controls the trimming rate in batch mode. + <deprecated> What: /sys/fs/f2fs/<disk>/cp_interval Date: October 2015 Contact: "Jaegeuk Kim" <jaegeuk@kernel.org> -Description: - Controls the checkpoint timing. +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 for all paths other than - discard and gc path. +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" <stummala@codeaurora.org> -Description: - Controls the idle timing for discard path. +Description: Controls the idle timing of discard thread given + this time interval. + Default is 5 secs. What: /sys/fs/f2fs/<disk>/gc_idle_interval Date: September 2018 Contact: "Chao Yu" <yuchao0@huawei.com> Contact: "Sahitya Tummala" <stummala@codeaurora.org> -Description: - Controls the idle timing for gc path. +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. +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. +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. +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. +Description: Shows total written kbytes issued to disk. What: /sys/fs/f2fs/<disk>/features Date: July 2017 Contact: "Jaegeuk Kim" <jaegeuk@kernel.org> -Description: - Shows all enabled features in current device. +Description: Shows all enabled features in current device. What: /sys/fs/f2fs/<disk>/inject_rate Date: May 2016 Contact: "Sheng Yong" <shengyong1@huawei.com> -Description: - Controls the injection rate. +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. +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. +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. +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 agressively +Description: Do background GC agressively when set. When gc_urgent = 1, + background thread starts to do GC by given gc_urgent_sleep_time + interval. It is set to 0 by default. 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 +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. +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. What: /sys/fs/f2fs/<disk>/extension_list Date: Feburary 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 +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 enumber of blocks that would be unusable - if checkpoint=disable were to be set. +Description: If checkpoint=disable, it displays the number of blocks that + are unusable. + If checkpoint=enable it displays the enumber 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) +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. diff --git a/Documentation/ABI/testing/sysfs-platform-asus-wmi b/Documentation/ABI/testing/sysfs-platform-asus-wmi index 9e99f2909612..1efac0ddb417 100644 --- a/Documentation/ABI/testing/sysfs-platform-asus-wmi +++ b/Documentation/ABI/testing/sysfs-platform-asus-wmi @@ -46,3 +46,13 @@ Description: * 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 diff --git a/Documentation/ABI/testing/sysfs-power b/Documentation/ABI/testing/sysfs-power index 6f87b9dd384b..5e6ead29124c 100644 --- a/Documentation/ABI/testing/sysfs-power +++ b/Documentation/ABI/testing/sysfs-power @@ -407,3 +407,16 @@ 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/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. diff --git a/Documentation/ABI/testing/usb-charger-uevent b/Documentation/ABI/testing/usb-charger-uevent new file mode 100644 index 000000000000..419a92dd0d86 --- /dev/null +++ b/Documentation/ABI/testing/usb-charger-uevent @@ -0,0 +1,46 @@ +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/PCI/msi-howto.rst b/Documentation/PCI/msi-howto.rst index 994cbb660ade..aa2046af69f7 100644 --- a/Documentation/PCI/msi-howto.rst +++ b/Documentation/PCI/msi-howto.rst @@ -283,5 +283,5 @@ 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_irq_alloc_vectors() with the +For example, it may contain calls to pci_alloc_irq_vectors() with the PCI_IRQ_MSI or PCI_IRQ_MSIX flags. diff --git a/Documentation/RCU/NMI-RCU.txt b/Documentation/RCU/NMI-RCU.rst index 881353fd5bff..180958388ff9 100644 --- a/Documentation/RCU/NMI-RCU.txt +++ b/Documentation/RCU/NMI-RCU.rst @@ -1,4 +1,7 @@ +.. _NMI_rcu_doc: + Using RCU to Protect Dynamic NMI Handlers +========================================= Although RCU is usually used to protect read-mostly data structures, @@ -9,7 +12,7 @@ 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. +brief explanation:: static int dummy_nmi_callback(struct pt_regs *regs, int cpu) { @@ -18,12 +21,12 @@ brief explanation. 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. +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. +NMI handler:: void do_nmi(struct pt_regs * regs, long error_code) { @@ -53,11 +56,12 @@ 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? +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... +Back to the discussion of NMI and RCU:: void set_nmi_callback(nmi_callback_t callback) { @@ -68,7 +72,7 @@ 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. +initialized values:: void unset_nmi_callback(void) { @@ -82,7 +86,7 @@ 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: +follows:: unset_nmi_callback(); synchronize_rcu(); @@ -98,24 +102,23 @@ 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? +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. + 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. + 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. + 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/arrayRCU.txt b/Documentation/RCU/arrayRCU.rst index f05a9afb2c39..4051ea3871ef 100644 --- a/Documentation/RCU/arrayRCU.txt +++ b/Documentation/RCU/arrayRCU.rst @@ -1,19 +1,21 @@ -Using RCU to Protect Read-Mostly Arrays +.. _array_rcu_doc: +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 +1. :ref:`Hash Tables <hash_tables>` -2. Static Arrays +2. :ref:`Static Arrays <static_arrays>` -3. Resizeable Arrays +3. :ref:`Resizable Arrays <resizable_arrays>` Each of these three situations involves an RCU-protected pointer to an array that is separately indexed. It might be tempting to consider use of RCU to instead protect the index into an array, however, this use -case is -not- supported. The problem with RCU-protected indexes into +case is **not** supported. The problem with RCU-protected indexes into arrays is that compilers can play way too many optimization games with integers, which means that the rules governing handling of these indexes are far more trouble than they are worth. If RCU-protected indexes into @@ -24,16 +26,20 @@ to be safely used. That aside, each of the three RCU-protected pointer situations are described in the following sections. +.. _hash_tables: 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. +.. _static_arrays: 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, @@ -41,13 +47,17 @@ 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? +Quick Quiz: + Why is it so important that updates be rare when using seqlock? + +:ref:`Answer to Quick Quiz <answer_quick_quiz_seqlock>` +.. _resizable_arrays: -Situation 3: Resizeable Arrays +Situation 3: Resizable Arrays +------------------------------ -Use of RCU for resizeable arrays is demonstrated by the grow_ary() +Use of RCU for resizable arrays is demonstrated by the grow_ary() function formerly 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() @@ -60,7 +70,7 @@ 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. +you are running on:: static int grow_ary(struct ipc_ids* ids, int newsize) { @@ -112,7 +122,7 @@ 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. +deleted, and, if not, the pointer is returned:: struct kern_ipc_perm* ipc_lock(struct ipc_ids* ids, int id) { @@ -144,8 +154,10 @@ deleted, and, if not, the pointer is returned. return out; } +.. _answer_quick_quiz_seqlock: Answer to Quick Quiz: + Why is it so important that updates be rare when using seqlock? The reason that it is important that updates be rare when using seqlock is that frequent updates can livelock readers. diff --git a/Documentation/RCU/index.rst b/Documentation/RCU/index.rst index 5c99185710fa..81a0a1e5f767 100644 --- a/Documentation/RCU/index.rst +++ b/Documentation/RCU/index.rst @@ -7,8 +7,13 @@ RCU concepts .. toctree:: :maxdepth: 3 + arrayRCU + rcubarrier + rcu_dereference + whatisRCU rcu listRCU + NMI-RCU UP Design/Memory-Ordering/Tree-RCU-Memory-Ordering diff --git a/Documentation/RCU/lockdep-splat.txt b/Documentation/RCU/lockdep-splat.txt index 9c015976b174..b8096316fd11 100644 --- a/Documentation/RCU/lockdep-splat.txt +++ b/Documentation/RCU/lockdep-splat.txt @@ -99,7 +99,7 @@ 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 +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: diff --git a/Documentation/RCU/rcu_dereference.txt b/Documentation/RCU/rcu_dereference.rst index bf699e8cfc75..c9667eb0d444 100644 --- a/Documentation/RCU/rcu_dereference.txt +++ b/Documentation/RCU/rcu_dereference.rst @@ -1,4 +1,7 @@ +.. _rcu_dereference_doc: + 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 "*"), @@ -8,7 +11,7 @@ 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 +- 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. @@ -25,24 +28,24 @@ o You must use one of the rcu_dereference() family of primitives for an example where the compiler can in fact deduce the exact value of the pointer, and thus cause misordering. -o You are only permitted to use rcu_dereference on pointer values. +- 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: - o Set bits and clear bits down in the must-be-zero low-order + - 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. - o XOR bits to translate pointers, as is done in some + - 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. -o Avoid cancellation when using the "+" and "-" infix arithmetic +- 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 @@ -54,16 +57,16 @@ o Avoid cancellation when using the "+" and "-" infix arithmetic "p+a-b" is safe because its value still necessarily depends on the rcu_dereference(), thus maintaining proper ordering. -o If you are using RCU to protect JITed functions, so that the +- 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 relational operators ("==", "!=", +- Do not use the results from relational operators ("==", "!=", ">", ">=", "<", or "<=") when dereferencing. For example, - the following (quite strange) code is buggy: + the following (quite strange) code is buggy:: int *p; int *q; @@ -81,11 +84,11 @@ o Do not use the results from relational operators ("==", "!=", after such branches, but can speculate loads, which can again result in misordering bugs. -o Be very careful about comparing pointers obtained from +- 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: + obtained from rcu_dereference(). For example:: p = rcu_dereference(gp); if (p == &default_struct) @@ -93,7 +96,7 @@ o Be very careful about comparing pointers obtained from 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: + transform this code into the following:: p = rcu_dereference(gp); if (p == &default_struct) @@ -105,14 +108,14 @@ o Be very careful about comparing pointers obtained from However, comparisons are OK in the following cases: - o The comparison was against the NULL pointer. If the + - 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. + - 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. @@ -124,31 +127,31 @@ o Be very careful about comparing pointers obtained from dereferenced, rcu_access_pointer() should be used in place of rcu_dereference(). - o The comparison is against a pointer that references memory + - 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. + - Compile time. - o Boot time. + - Boot time. - o Module-init time for module code. + - Module-init time for module code. - o Prior to kthread creation for kthread code. + - Prior to kthread creation for kthread code. - o During some prior acquisition of the lock that + - During some prior acquisition of the lock that we now hold. - o Before mod_timer() time for a timer handler. + - 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 + - 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. @@ -159,13 +162,13 @@ o Be very careful about comparing pointers obtained from 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, + - 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 + - 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. @@ -175,7 +178,7 @@ o Be very careful about comparing pointers obtained from comparison will provide exactly the information that the compiler needs to deduce the value of the pointer. -o Disable any value-speculation optimizations that your compiler +- 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. @@ -188,11 +191,12 @@ o Disable any value-speculation optimizations that your compiler 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: +precautions. To see this, consider the following code fragment:: struct foo { int a; @@ -244,7 +248,7 @@ 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: +Then one approach is to use locking, for example, as follows:: struct foo { int a; @@ -299,6 +303,7 @@ 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 @@ -308,7 +313,7 @@ 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: +expect. Consider the following code fragment:: struct foo { int a; @@ -354,6 +359,7 @@ 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 @@ -370,7 +376,7 @@ member of the rcu_dereference() to use in various situations: 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: + use rcu_dereference_check(), for example:: p1 = rcu_dereference_check(p->rcu_protected_pointer, lockdep_is_held(&my_lock)); @@ -378,14 +384,14 @@ member of the rcu_dereference() to use in various situations: 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: + 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(): + by my_lock, use rcu_dereference_protected():: p1 = rcu_dereference_protected(p->rcu_protected_pointer, lockdep_is_held(&my_lock)); @@ -410,18 +416,19 @@ member of the rcu_dereference() to use in various situations: SPARSE CHECKING OF RCU-PROTECTED POINTERS +----------------------------------------- The sparse static-analysis tool checks for direct 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: +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: +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); @@ -435,7 +442,7 @@ 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: +read as follows:: p = rcu_dereference(q->rcu_protected_pointer); do_something_with(p->a); @@ -448,7 +455,7 @@ 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: +follows:: struct foo __rcu *rcu_protected_pointer; diff --git a/Documentation/RCU/rcubarrier.txt b/Documentation/RCU/rcubarrier.rst index a2782df69732..f64f4413a47c 100644 --- a/Documentation/RCU/rcubarrier.txt +++ b/Documentation/RCU/rcubarrier.rst @@ -1,4 +1,7 @@ +.. _rcu_barrier: + RCU and Unloadable Modules +========================== [Originally published in LWN Jan. 14, 2007: http://lwn.net/Articles/217484/] @@ -21,7 +24,7 @@ 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: +appropriate lock, of course:: list_del_rcu(p); synchronize_rcu(); @@ -32,13 +35,13 @@ 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: +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: +IRQ context. The function p_callback() might be defined as follows:: static void p_callback(struct rcu_head *rp) { @@ -49,6 +52,7 @@ IRQ context. The function p_callback() might be defined as follows: Unloading Modules That Use call_rcu() +------------------------------------- But what if p_callback is defined in an unloadable module? @@ -69,10 +73,11 @@ 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 +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. @@ -88,79 +93,79 @@ 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(), 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: +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); The rcutorture module makes use of rcu_barrier() in its exit function -as follows: +as follows:: - 1 static void - 2 rcu_torture_cleanup(void) - 3 { - 4 int i; + 1 static void + 2 rcu_torture_cleanup(void) + 3 { + 4 int i; 5 - 6 fullstop = 1; - 7 if (shuffler_task != NULL) { + 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 } + 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 @@ -176,9 +181,14 @@ 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 +.. _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 cancel all the timers, and only then invoke rcu_barrier() to wait for any remaining @@ -188,11 +198,12 @@ Of course, if you 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 you will need to invoke rcu_barrier() -and- +**and** call_srcu(), then 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 @@ -200,19 +211,19 @@ 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: +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 } + 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 @@ -226,18 +237,18 @@ 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: +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; + 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 } + 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 @@ -248,20 +259,25 @@ 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: +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); + 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 +.. _rcubarrier_quiz_2: + +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? +:ref:`Answer to Quick Quiz #2 <answer_rcubarrier_quiz_2>` + 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. @@ -269,6 +285,7 @@ However, the code above illustrates the concepts. 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 @@ -277,8 +294,12 @@ 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 +Quick Quiz #1: + Is there any other situation where rcu_barrier() might be required? Answer: Interestingly enough, rcu_barrier() was not originally @@ -292,7 +313,12 @@ Answer: Interestingly enough, rcu_barrier() was not originally 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 +:ref:`Back to Quick Quiz #1 <rcubarrier_quiz_1>` + +.. _answer_rcubarrier_quiz_2: + +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 @@ -323,3 +349,5 @@ Answer: This cannot happen. The reason is that on_each_cpu() has its last 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! + +:ref:`Back to Quick Quiz #2 <rcubarrier_quiz_2>` diff --git a/Documentation/RCU/stallwarn.txt b/Documentation/RCU/stallwarn.txt index f48f4621ccbc..a360a8796710 100644 --- a/Documentation/RCU/stallwarn.txt +++ b/Documentation/RCU/stallwarn.txt @@ -225,18 +225,13 @@ an estimate of the total number of RCU callbacks queued across all CPUs In kernels with CONFIG_RCU_FAST_NO_HZ, more information is printed for each CPU: - 0: (64628 ticks this GP) idle=dd5/3fffffffffffffff/0 softirq=82/543 last_accelerate: a345/d342 Nonlazy posted: ..D + 0: (64628 ticks this GP) idle=dd5/3fffffffffffffff/0 softirq=82/543 last_accelerate: a345/d342 dyntick_enabled: 1 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:" indicates lazy-callback -status, so that an "l" indicates that all callbacks were lazy at the start -of the last idle period and an "L" indicates that there are currently -no non-lazy callbacks (in both cases, "." 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). +rcu_prepare_for_idle(). "dyntick_enabled: 1" indicates that dyntick-idle +processing is enabled. If the grace period ends just as the stall warning starts printing, there will be a spurious stall-warning message, which will include diff --git a/Documentation/RCU/whatisRCU.txt b/Documentation/RCU/whatisRCU.rst index 58ba05c4d97f..c7f147b8034f 100644 --- a/Documentation/RCU/whatisRCU.txt +++ b/Documentation/RCU/whatisRCU.rst @@ -1,15 +1,18 @@ +.. _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? 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/ - 2010 Big API Table http://lwn.net/Articles/419086/ -5. The RCU API, 2014 Edition http://lwn.net/Articles/609904/ - 2014 Big API Table http://lwn.net/Articles/609973/ +| 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/ +| 2010 Big API Table http://lwn.net/Articles/419086/ +| 5. The RCU API, 2014 Edition http://lwn.net/Articles/609904/ +| 2014 Big API Table http://lwn.net/Articles/609973/ What is RCU? @@ -24,14 +27,21 @@ 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 +: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. FULL LIST OF RCU APIs <7_whatisRCU>` + +:ref:`8. ANSWERS TO QUICK QUIZZES <8_whatisRCU>` People who prefer starting with a conceptual overview should focus on Section 1, though most readers will profit by reading this section at @@ -49,8 +59,10 @@ 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 @@ -116,8 +128,10 @@ 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: @@ -136,7 +150,7 @@ 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 @@ -150,7 +164,7 @@ rcu_read_lock() 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 @@ -158,15 +172,15 @@ rcu_read_unlock() 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 + 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: + For example, consider the following sequence of events:: CPU 0 CPU 1 CPU 2 ----------------- ------------------------- --------------- @@ -182,7 +196,7 @@ synchronize_rcu() 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 + **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 @@ -211,10 +225,10 @@ synchronize_rcu() checklist.txt 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 + 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.) @@ -231,7 +245,7 @@ rcu_assign_pointer() 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 @@ -248,13 +262,13 @@ rcu_dereference() 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: + 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: + into one statement:: return rcu_dereference(head.next)->data; @@ -266,8 +280,8 @@ rcu_dereference() 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: + 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); @@ -290,9 +304,9 @@ rcu_dereference() 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]. + primitives, such as list_for_each_entry_rcu() [2]_. - [1] The variant rcu_dereference_protected() can be used outside +.. [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 @@ -305,7 +319,7 @@ rcu_dereference() a lockdep splat is emitted. See Documentation/RCU/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 +.. [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, @@ -315,6 +329,7 @@ rcu_dereference() The following diagram shows how each API communicates among the reader, updater, and reclaimer. +:: rcu_assign_pointer() @@ -375,12 +390,16 @@ 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_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.txt, arrayRCU.txt, and NMI-RCU.txt. +uses of RCU may be found in :ref:`listRCU.rst <list_rcu_doc>`, +:ref:`arrayRCU.rst <array_rcu_doc>`, and :ref:`NMI-RCU.rst <NMI_rcu_doc>`. +:: struct foo { int a; @@ -440,40 +459,43 @@ uses of RCU may be found in listRCU.txt, arrayRCU.txt, and NMI-RCU.txt. So, to sum up: -o Use rcu_read_lock() and rcu_read_unlock() to guard RCU +- 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() +- 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 +- 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. +- 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 + **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 +- 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. +And again, more-typical uses of RCU may be found in :ref:`listRCU.rst +<list_rcu_doc>`, :ref:`arrayRCU.rst <array_rcu_doc>`, and :ref:`NMI-RCU.rst +<NMI_rcu_doc>`. +.. _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: +The call_rcu() API is as follows:: void call_rcu(struct rcu_head * head, void (*func)(struct rcu_head *head)); @@ -481,7 +503,7 @@ The call_rcu() API is as follows: 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: +have an rcu_head structure added, perhaps as follows:: struct foo { int a; @@ -490,7 +512,7 @@ have an rcu_head structure added, perhaps as follows: struct rcu_head rcu; }; -The foo_update_a() function might then be written as follows: +The foo_update_a() function might then be written as follows:: /* * Create a new struct foo that is the same as the one currently @@ -520,7 +542,7 @@ The foo_update_a() function might then be written as follows: call_rcu(&old_fp->rcu, foo_reclaim); } -The foo_reclaim() function might appear as follows: +The foo_reclaim() function might appear as follows:: void foo_reclaim(struct rcu_head *rp) { @@ -544,7 +566,7 @@ 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 +- 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 @@ -552,14 +574,16 @@ o Use call_rcu() -after- removing a data element from an 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: +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_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 @@ -579,7 +603,7 @@ 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 @@ -591,7 +615,7 @@ 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: +It is extremely simple:: static DEFINE_RWLOCK(rcu_gp_mutex); @@ -614,7 +638,7 @@ It is extremely simple: [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!] +don't forget about them when submitting patches making use of RCU!]:: #define rcu_assign_pointer(p, v) \ ({ \ @@ -647,18 +671,23 @@ 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 +.. _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 <8_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_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) { } @@ -683,14 +712,14 @@ 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-! +"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 +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 @@ -698,19 +727,32 @@ 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-. +.. _quiz_2: + +Quick Quiz #2: + Give an example where Classic RCU's read-side + overhead is **negative**. + +:ref:`Answers to Quick Quiz <8_whatisRCU>` -Quick Quiz #3: If it is illegal to block in an RCU read-side +.. _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 PREEMPT_RT, where normal spinlocks can block??? +:ref:`Answers to Quick Quiz <8_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; @@ -762,7 +804,7 @@ diff shows how closely related RCU and reader-writer locking can be. return 0; } -Or, for those who prefer a side-by-side listing: +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; @@ -774,40 +816,44 @@ Or, for those who prefer a side-by-side listing: 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 } +:: + + 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 @@ -825,22 +871,27 @@ 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. 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: +RCU list traversal:: list_entry_rcu + list_entry_lockless list_first_entry_rcu list_next_rcu list_for_each_entry_rcu list_for_each_entry_continue_rcu list_for_each_entry_from_rcu + list_first_or_null_rcu + list_next_or_null_rcu hlist_first_rcu hlist_next_rcu hlist_pprev_rcu @@ -854,7 +905,7 @@ RCU list traversal: hlist_bl_first_rcu hlist_bl_for_each_entry_rcu -RCU pointer/list update: +RCU pointer/list update:: rcu_assign_pointer list_add_rcu @@ -864,10 +915,12 @@ RCU pointer/list update: 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 - list_splice_init_rcu() + list_splice_init_rcu + list_splice_tail_init_rcu hlist_nulls_del_init_rcu hlist_nulls_del_rcu hlist_nulls_add_head_rcu @@ -876,7 +929,9 @@ RCU pointer/list update: hlist_bl_del_rcu hlist_bl_set_first_rcu -RCU: Critical sections Grace period Barrier +RCU:: + + Critical sections Grace period Barrier rcu_read_lock synchronize_net rcu_barrier rcu_read_unlock synchronize_rcu @@ -885,7 +940,9 @@ RCU: Critical sections Grace period Barrier rcu_dereference_check kfree_rcu rcu_dereference_protected -bh: Critical sections Grace period Barrier +bh:: + + Critical sections Grace period Barrier rcu_read_lock_bh call_rcu rcu_barrier rcu_read_unlock_bh synchronize_rcu @@ -896,7 +953,9 @@ bh: Critical sections Grace period Barrier rcu_dereference_bh_protected rcu_read_lock_bh_held -sched: Critical sections Grace period Barrier +sched:: + + Critical sections Grace period Barrier rcu_read_lock_sched call_rcu rcu_barrier rcu_read_unlock_sched synchronize_rcu @@ -910,7 +969,9 @@ sched: Critical sections Grace period Barrier rcu_read_lock_sched_held -SRCU: Critical sections Grace period Barrier +SRCU:: + + Critical sections Grace period Barrier srcu_read_lock call_srcu srcu_barrier srcu_read_unlock synchronize_srcu @@ -918,13 +979,14 @@ SRCU: Critical sections Grace period Barrier srcu_dereference_check srcu_read_lock_held -SRCU: Initialization/cleanup +SRCU: Initialization/cleanup:: + DEFINE_SRCU DEFINE_STATIC_SRCU init_srcu_struct cleanup_srcu_struct -All: lockdep-checked RCU-protected pointer access +All: lockdep-checked RCU-protected pointer access:: rcu_access_pointer rcu_dereference_raw @@ -974,15 +1036,19 @@ 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_whatisRCU: 8. ANSWERS TO QUICK QUIZZES +---------------------------- -Quick Quiz #1: Why is this argument naive? How could a deadlock +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: +Answer: + Consider the following sequence of events: 1. CPU 0 acquires some unrelated lock, call it "problematic_lock", disabling irq via @@ -1021,10 +1087,14 @@ Answer: Consider the following sequence of events: 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-. +: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_PREEMPT +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 @@ -1046,11 +1116,15 @@ Answer: Imagine a single-CPU system with a non-CONFIG_PREEMPT 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 +: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 PREEMPT_RT, where normal spinlocks can block??? -Answer: Just as PREEMPT_RT permits preemption of spinlock +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 @@ -1069,6 +1143,7 @@ Answer: Just as PREEMPT_RT permits preemption of spinlock Besides, how does the computer know what pizza parlor the human being went to??? +:ref:`Back to Quick Quiz #3 <quiz_3>` ACKNOWLEDGEMENTS 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..21d233ca50d8 --- /dev/null +++ b/Documentation/admin-guide/acpi/fan_performance_states.rst @@ -0,0 +1,62 @@ +.. 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. diff --git a/Documentation/admin-guide/acpi/index.rst b/Documentation/admin-guide/acpi/index.rst index 4d13eeea1eca..71277689ad97 100644 --- a/Documentation/admin-guide/acpi/index.rst +++ b/Documentation/admin-guide/acpi/index.rst @@ -12,3 +12,4 @@ the Linux ACPI support. dsdt-override ssdt-overlays cppc_sysfs + fan_performance_states diff --git a/Documentation/admin-guide/blockdev/zram.rst b/Documentation/admin-guide/blockdev/zram.rst index 6eccf13219ff..27c77d853028 100644 --- a/Documentation/admin-guide/blockdev/zram.rst +++ b/Documentation/admin-guide/blockdev/zram.rst @@ -1,15 +1,15 @@ ======================================== -zram: Compressed RAM based block devices +zram: Compressed RAM-based block devices ======================================== Introduction ============ -The zram module creates RAM based block devices named /dev/zram<id> +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 usecases include /tmp storage, -use as swap disks, various caches under /var and maybe many more :) +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>/ @@ -43,17 +43,17 @@ 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; + the device has been initialised. Please reset device first. -ENOMEM zram was not able to allocate enough memory to fulfil your - needs; + needs. -EINVAL invalid input has been provided. ======== ============================================================= -If you use 'echo', the returned value that is changed by 'echo' utility, +If you use 'echo', the returned value is set by the 'echo' utility, and, in general case, something like:: echo 3 > /sys/block/zram0/max_comp_streams - if [ $? -ne 0 ]; + if [ $? -ne 0 ]; then handle_error fi @@ -65,7 +65,8 @@ should suffice. :: modprobe zram num_devices=4 - This creates 4 devices: /dev/zram{0,1,2,3} + +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. @@ -73,12 +74,12 @@ pre-created. Default: 1. 2) Set max number of compression streams ======================================== -Regardless the value passed to this attribute, ZRAM will always -allocate multiple compression streams - one per online CPUs - thus +Regardless of the value passed to this attribute, ZRAM will always +allocate multiple compression streams - one per online CPU - thus allowing several concurrent compression operations. The number of allocated compression streams goes down when some of the CPUs become offline. There is no single-compression-stream mode anymore, -unless you are running a UP system or has only 1 CPU online. +unless you are running a UP system or have only 1 CPU online. To find out how many streams are currently available:: @@ -89,7 +90,7 @@ To find out how many streams are currently available:: Using comp_algorithm device attribute one can see available and currently selected (shown in square brackets) compression algorithms, -change selected compression algorithm (once the device is initialised +or change the selected compression algorithm (once the device is initialised there is no way to change compression algorithm). Examples:: @@ -167,9 +168,9 @@ Examples:: zram provides a control interface, which enables dynamic (on-demand) device addition and removal. -In order to add a new /dev/zramX device, perform read operation on hot_add -attribute. This will return either new device's device id (meaning that you -can use /dev/zram<id>) or error code. +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:: @@ -186,8 +187,8 @@ execute:: Per-device statistics are exported as various nodes under /sys/block/zram<id>/ -A brief description of exported device attributes. For more details please -read Documentation/ABI/testing/sysfs-block-zram. +A brief description of exported device attributes follows. For more details +please read Documentation/ABI/testing/sysfs-block-zram. ====================== ====== =============================================== Name access description @@ -245,7 +246,7 @@ whitespace: File /sys/block/zram<id>/mm_stat -The stat file represents device's mm statistics. It consists of a single +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: ================ ============================================================= @@ -261,7 +262,7 @@ line of text and contains the following stats separated by whitespace: 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 have consumed to + 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. @@ -271,7 +272,7 @@ line of text and contains the following stats separated by whitespace: File /sys/block/zram<id>/bd_stat -The stat file represents device's backing device statistics. It consists of +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: ============== ============================================================= @@ -316,9 +317,9 @@ 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 partition at this moment. -If admin want to use incompressible page writeback, they could do via:: +If admin wants to use incompressible page writeback, they could do via:: - echo huge > /sys/block/zramX/write + echo huge > /sys/block/zramX/writeback To use idle page writeback, first, user need to declare zram pages as idle:: @@ -326,7 +327,7 @@ as idle:: echo all > /sys/block/zramX/idle From now on, any pages on zram are idle pages. The idle mark -will be removed until someone request access of the block. +will be removed until someone requests access of the block. IOW, unless there is access request, those pages are still idle pages. Admin can request writeback of those idle pages at right timing via:: @@ -341,16 +342,16 @@ to guarantee storage health for entire product life. To overcome the concern, zram supports "writeback_limit" feature. The "writeback_limit_enable"'s default value is 0 so that it doesn't limit -any writeback. IOW, if admin want to apply writeback budget, he should +any writeback. IOW, if admin wants to apply writeback budget, he 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 set the budget via /sys/block/zramX/writeback_limit. +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 meaninless.) +assigned via /sys/block/zramX/writeback_limit is meaningless.) If admin want to limit writeback as per-day 400M, he could do it like below:: @@ -361,13 +362,13 @@ like below:: /sys/block/zram0/writeback_limit. $ echo 1 > /sys/block/zram0/writeback_limit_enable -If admin want to allow further write again once the bugdet is exausted, +If admins want to allow further write again once the bugdet is exhausted, he could do it like below:: $ echo $((400<<MB_SHIFT>>4K_SHIFT)) > \ /sys/block/zram0/writeback_limit -If admin want to see remaining writeback budget since he set:: +If admin wants to see remaining writeback budget since last set:: $ cat /sys/block/zramX/writeback_limit @@ -375,12 +376,12 @@ If admin want to disable writeback limit, he could do:: $ echo 0 > /sys/block/zramX/writeback_limit_enable -The writeback_limit count will reset whenever you reset zram(e.g., +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 want to measure writeback count in a certain period, he could +If admin wants to measure writeback count in a certain period, he could know it via /sys/block/zram0/bd_stat's 3rd column. memory tracking diff --git a/Documentation/admin-guide/cgroup-v2.rst b/Documentation/admin-guide/cgroup-v2.rst index 0636bcb60b5a..3f801461f0f3 100644 --- a/Documentation/admin-guide/cgroup-v2.rst +++ b/Documentation/admin-guide/cgroup-v2.rst @@ -61,6 +61,8 @@ v1 is available under Documentation/admin-guide/cgroup-v1/. 5-6. Device 5-7. RDMA 5-7-1. RDMA Interface Files + 5-8. HugeTLB + 5.8-1. HugeTLB Interface Files 5-8. Misc 5-8-1. perf_event 5-N. Non-normative information @@ -2056,6 +2058,33 @@ RDMA Interface Files mlx4_0 hca_handle=1 hca_object=20 ocrdma1 hca_handle=1 hca_object=23 +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. Misc ---- diff --git a/Documentation/admin-guide/device-mapper/dm-raid.rst b/Documentation/admin-guide/device-mapper/dm-raid.rst index f6344675e395..695a2ea1d1ae 100644 --- a/Documentation/admin-guide/device-mapper/dm-raid.rst +++ b/Documentation/admin-guide/device-mapper/dm-raid.rst @@ -419,3 +419,5 @@ Version History rebuild errors. 1.15.0 Fix size extensions not being synchronized in case of new MD bitmap pages allocated; also fix those not occuring 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/devices.txt b/Documentation/admin-guide/devices.txt index 1c5d2281efc9..2a97aaec8b12 100644 --- a/Documentation/admin-guide/devices.txt +++ b/Documentation/admin-guide/devices.txt @@ -319,7 +319,7 @@ 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 shapshot of process state data + 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 diff --git a/Documentation/admin-guide/ext4.rst b/Documentation/admin-guide/ext4.rst index 9bc93f0ce0c9..9443fcef1876 100644 --- a/Documentation/admin-guide/ext4.rst +++ b/Documentation/admin-guide/ext4.rst @@ -92,6 +92,8 @@ Currently Available * 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. diff --git a/Documentation/admin-guide/index.rst b/Documentation/admin-guide/index.rst index 9e0f1e3fd152..f1d0ccffbe72 100644 --- a/Documentation/admin-guide/index.rst +++ b/Documentation/admin-guide/index.rst @@ -77,6 +77,7 @@ configure specific aspects of kernel behavior to your liking. device-mapper/index efi-stub ext4 + nfs/index gpio/index highuid hw_random diff --git a/Documentation/admin-guide/kernel-parameters.txt b/Documentation/admin-guide/kernel-parameters.txt index b48c70ba9841..dbc22d684627 100644 --- a/Documentation/admin-guide/kernel-parameters.txt +++ b/Documentation/admin-guide/kernel-parameters.txt @@ -517,7 +517,7 @@ 1 -- check protection requested by application. Default value is set via a kernel config option. Value can be changed at runtime via - /selinux/checkreqprot. + /sys/fs/selinux/checkreqprot. cio_ignore= [S390] See Documentation/s390/common_io.rst for details. @@ -840,6 +840,18 @@ dump out devices still on the deferred probe list after retrying. + dfltcc= [HW,S390] + Format: { on | off | def_only | inf_only | always } + on: s390 zlib hardware support for compression on + level 1 and decompression (default) + off: No s390 zlib hardware support + def_only: s390 zlib hardware support for deflate + only (compression on level 1) + inf_only: s390 zlib hardware support for inflate + only (decompression) + always: Same as 'on' but ignores the selected compression + level always using hardware support (used for debugging) + dhash_entries= [KNL] Set number of hash buckets for dentry cache. @@ -1171,10 +1183,10 @@ efi= [EFI] Format: { "old_map", "nochunk", "noruntime", "debug", - "nosoftreserve" } + "nosoftreserve", "disable_early_pci_dma", + "no_disable_early_pci_dma" } old_map [X86-64]: switch to the old ioremap-based EFI - runtime services mapping. 32-bit still uses this one by - default. + runtime services mapping. [Needs CONFIG_X86_UV=y] nochunk: disable reading files in "chunks" in the EFI boot stub, as chunking can cause problems with some firmware implementations. @@ -1186,6 +1198,10 @@ claim. Specify efi=nosoftreserve to disable this reservation and treat the memory by its base type (i.e. EFI_CONVENTIONAL_MEMORY / "System RAM"). + disable_early_pci_dma: Disable the busmaster bit on all + PCI bridges while in the EFI boot stub + no_disable_early_pci_dma: Leave the busmaster bit set + on all PCI bridges while in the EFI boot stub efi_no_storage_paranoia [EFI; X86] Using this parameter you can use more than 50% of @@ -1251,7 +1267,8 @@ 0 -- permissive (log only, no denials). 1 -- enforcing (deny and log). Default value is 0. - Value can be changed at runtime via /selinux/enforce. + Value can be changed at runtime via + /sys/fs/selinux/enforce. erst_disable [ACPI] Disable Error Record Serialization Table (ERST) @@ -1939,9 +1956,31 @@ <cpu number> begins at 0 and the maximum value is "number of CPUs in system - 1". - The format of <cpu-list> is described above. - + managed_irq + + Isolate from being targeted by managed interrupts + which have an interrupt mask containing isolated + CPUs. The affinity of managed interrupts is + handled by the kernel and cannot be changed via + the /proc/irq/* interfaces. + + This isolation is best effort and only effective + if the automatically assigned interrupt mask of a + device queue contains isolated and housekeeping + CPUs. If housekeeping CPUs are online then such + interrupts are directed to the housekeeping CPU + so that IO submitted on the housekeeping CPU + cannot disturb the isolated CPU. + + If a queue's affinity mask contains only isolated + CPUs then this parameter has no effect on the + interrupt routing decision, though interrupts are + only delivered when tasks running on those + isolated CPUs submit IO. IO submitted on + housekeeping CPUs has no influence on those + queues. + The format of <cpu-list> is described above. iucv= [HW,NET] @@ -3984,6 +4023,19 @@ test until boot completes in order to avoid interference. + rcuperf.kfree_rcu_test= [KNL] + Set to measure performance of kfree_rcu() flooding. + + rcuperf.kfree_nthreads= [KNL] + The number of threads running loops of kfree_rcu(). + + rcuperf.kfree_alloc_num= [KNL] + Number of allocations and frees done in an iteration. + + rcuperf.kfree_loops= [KNL] + Number of loops doing rcuperf.kfree_alloc_num number + of allocations and frees. + rcuperf.nreaders= [KNL] Set number of RCU readers. The value -1 selects N, where N is the number of CPUs. A value @@ -4354,9 +4406,7 @@ See security/selinux/Kconfig help text. 0 -- disable. 1 -- enable. - Default value is set via kernel config option. - If enabled at boot time, /selinux/disable can be used - later to disable prior to initial policy load. + Default value is 1. apparmor= [APPARMOR] Disable or enable AppArmor at boot time Format: { "0" | "1" } diff --git a/Documentation/filesystems/nfs/fault_injection.txt b/Documentation/admin-guide/nfs/fault_injection.rst index f3a5b0a8ac05..eb029c0c15ce 100644 --- a/Documentation/filesystems/nfs/fault_injection.txt +++ b/Documentation/admin-guide/nfs/fault_injection.rst @@ -1,6 +1,7 @@ +=================== +NFS Fault Injection +=================== -Fault Injection -=============== Fault injection is a method for forcing errors that may not normally occur, or may be difficult to reproduce. Forcing these errors in a controlled environment can help the developer find and fix bugs before their code is shipped in a diff --git a/Documentation/admin-guide/nfs/index.rst b/Documentation/admin-guide/nfs/index.rst new file mode 100644 index 000000000000..6b5a3c90fac5 --- /dev/null +++ b/Documentation/admin-guide/nfs/index.rst @@ -0,0 +1,15 @@ +============= +NFS +============= + +.. toctree:: + :maxdepth: 1 + + nfs-client + nfsroot + nfs-rdma + nfsd-admin-interfaces + nfs-idmapper + pnfs-block-server + pnfs-scsi-server + fault_injection diff --git a/Documentation/filesystems/nfs/nfs.txt b/Documentation/admin-guide/nfs/nfs-client.rst index f2571c8bef74..c4b777c7584b 100644 --- a/Documentation/filesystems/nfs/nfs.txt +++ b/Documentation/admin-guide/nfs/nfs-client.rst @@ -1,3 +1,6 @@ +========== +NFS Client +========== The NFS client ============== @@ -59,10 +62,11 @@ The DNS resolver NFSv4 allows for one server to refer the NFS client to data that has been migrated onto another server by means of the special "fs_locations" -attribute. See - http://tools.ietf.org/html/rfc3530#section-6 -and - http://tools.ietf.org/html/draft-ietf-nfsv4-referrals-00 +attribute. See `RFC3530 Section 6: Filesystem Migration and Replication`_ and +`Implementation Guide for Referrals in NFSv4`_. + +.. _RFC3530 Section 6\: Filesystem Migration and Replication: http://tools.ietf.org/html/rfc3530#section-6 +.. _Implementation Guide for Referrals in NFSv4: http://tools.ietf.org/html/draft-ietf-nfsv4-referrals-00 The fs_locations information can take the form of either an ip address and a path, or a DNS hostname and a path. The latter requires the NFS client to @@ -78,8 +82,8 @@ Assuming that the user has the 'rpc_pipefs' filesystem mounted in the usual (2) If no valid entry exists, the helper script '/sbin/nfs_cache_getent' (may be changed using the 'nfs.cache_getent' kernel boot parameter) is run, with two arguments: - - the cache name, "dns_resolve" - - the hostname to resolve + - the cache name, "dns_resolve" + - the hostname to resolve (3) After looking up the corresponding ip address, the helper script writes the result into the rpc_pipefs pseudo-file @@ -94,43 +98,44 @@ Assuming that the user has the 'rpc_pipefs' filesystem mounted in the usual script, and <ttl> is the 'time to live' of this cache entry (in units of seconds). - Note: If <ip address> is invalid, say the string "0", then a negative - entry is created, which will cause the kernel to treat the hostname - as having no valid DNS translation. + .. note:: + If <ip address> is invalid, say the string "0", then a negative + entry is created, which will cause the kernel to treat the hostname + as having no valid DNS translation. A basic sample /sbin/nfs_cache_getent ===================================== - -#!/bin/bash -# -ttl=600 -# -cut=/usr/bin/cut -getent=/usr/bin/getent -rpc_pipefs=/var/lib/nfs/rpc_pipefs -# -die() -{ - echo "Usage: $0 cache_name entry_name" - exit 1 -} - -[ $# -lt 2 ] && die -cachename="$1" -cache_path=${rpc_pipefs}/cache/${cachename}/channel - -case "${cachename}" in - dns_resolve) - name="$2" - result="$(${getent} hosts ${name} | ${cut} -f1 -d\ )" - [ -z "${result}" ] && result="0" - ;; - *) - die - ;; -esac -echo "${result} ${name} ${ttl}" >${cache_path} - +.. code-block:: sh + + #!/bin/bash + # + ttl=600 + # + cut=/usr/bin/cut + getent=/usr/bin/getent + rpc_pipefs=/var/lib/nfs/rpc_pipefs + # + die() + { + echo "Usage: $0 cache_name entry_name" + exit 1 + } + + [ $# -lt 2 ] && die + cachename="$1" + cache_path=${rpc_pipefs}/cache/${cachename}/channel + + case "${cachename}" in + dns_resolve) + name="$2" + result="$(${getent} hosts ${name} | ${cut} -f1 -d\ )" + [ -z "${result}" ] && result="0" + ;; + *) + die + ;; + esac + echo "${result} ${name} ${ttl}" >${cache_path} diff --git a/Documentation/filesystems/nfs/idmapper.txt b/Documentation/admin-guide/nfs/nfs-idmapper.rst index b86831acd583..58b8e63412d5 100644 --- a/Documentation/filesystems/nfs/idmapper.txt +++ b/Documentation/admin-guide/nfs/nfs-idmapper.rst @@ -1,7 +1,7 @@ +============= +NFS ID Mapper +============= -========= -ID Mapper -========= Id mapper is used by NFS to translate user and group ids into names, and to translate user and group names into ids. Part of this translation involves performing an upcall to userspace to request the information. There are two @@ -20,22 +20,24 @@ legacy rpc.idmap daemon for the id mapping. This result will be stored in a custom NFS idmap cache. -=========== Configuring =========== + The file /etc/request-key.conf will need to be modified so /sbin/request-key can direct the upcall. The following line should be added: -#OP TYPE DESCRIPTION CALLOUT INFO PROGRAM ARG1 ARG2 ARG3 ... -#====== ======= =============== =============== =============================== -create id_resolver * * /usr/sbin/nfs.idmap %k %d 600 +``#OP TYPE DESCRIPTION CALLOUT INFO PROGRAM ARG1 ARG2 ARG3 ...`` +``#====== ======= =============== =============== ===============================`` +``create id_resolver * * /usr/sbin/nfs.idmap %k %d 600`` + This will direct all id_resolver requests to the program /usr/sbin/nfs.idmap. The last parameter, 600, defines how many seconds into the future the key will expire. This parameter is optional for /usr/sbin/nfs.idmap. When the timeout is not specified, nfs.idmap will default to 600 seconds. -id mapper uses for key descriptions: +id mapper uses for key descriptions:: + uid: Find the UID for the given user gid: Find the GID for the given group user: Find the user name for the given UID @@ -45,23 +47,24 @@ You can handle any of these individually, rather than using the generic upcall program. If you would like to use your own program for a uid lookup then you would edit your request-key.conf so it look similar to this: -#OP TYPE DESCRIPTION CALLOUT INFO PROGRAM ARG1 ARG2 ARG3 ... -#====== ======= =============== =============== =============================== -create id_resolver uid:* * /some/other/program %k %d 600 -create id_resolver * * /usr/sbin/nfs.idmap %k %d 600 +``#OP TYPE DESCRIPTION CALLOUT INFO PROGRAM ARG1 ARG2 ARG3 ...`` +``#====== ======= =============== =============== ===============================`` +``create id_resolver uid:* * /some/other/program %k %d 600`` +``create id_resolver * * /usr/sbin/nfs.idmap %k %d 600`` + Notice that the new line was added above the line for the generic program. request-key will find the first matching line and corresponding program. In this case, /some/other/program will handle all uid lookups and /usr/sbin/nfs.idmap will handle gid, user, and group lookups. -See <file:Documentation/security/keys/request-key.rst> for more information +See Documentation/security/keys/request-key.rst for more information about the request-key function. -========= nfs.idmap ========= + nfs.idmap is designed to be called by request-key, and should not be run "by hand". This program takes two arguments, a serialized key and a key description. The serialized key is first converted into a key_serial_t, and diff --git a/Documentation/admin-guide/nfs/nfs-rdma.rst b/Documentation/admin-guide/nfs/nfs-rdma.rst new file mode 100644 index 000000000000..ef0f3678b1fb --- /dev/null +++ b/Documentation/admin-guide/nfs/nfs-rdma.rst @@ -0,0 +1,292 @@ +=================== +Setting up NFS/RDMA +=================== + +:Author: + NetApp and Open Grid Computing (May 29, 2008) + +.. warning:: + This document is probably obsolete. + +Overview +======== + +This document describes how to install and setup the Linux NFS/RDMA client +and server software. + +The NFS/RDMA client was first included in Linux 2.6.24. The NFS/RDMA server +was first included in the following release, Linux 2.6.25. + +In our testing, we have obtained excellent performance results (full 10Gbit +wire bandwidth at minimal client CPU) under many workloads. The code passes +the full Connectathon test suite and operates over both Infiniband and iWARP +RDMA adapters. + +Getting Help +============ + +If you get stuck, you can ask questions on the +nfs-rdma-devel@lists.sourceforge.net mailing list. + +Installation +============ + +These instructions are a step by step guide to building a machine for +use with NFS/RDMA. + +- Install an RDMA device + + Any device supported by the drivers in drivers/infiniband/hw is acceptable. + + Testing has been performed using several Mellanox-based IB cards, the + Ammasso AMS1100 iWARP adapter, and the Chelsio cxgb3 iWARP adapter. + +- Install a Linux distribution and tools + + The first kernel release to contain both the NFS/RDMA client and server was + Linux 2.6.25 Therefore, a distribution compatible with this and subsequent + Linux kernel release should be installed. + + The procedures described in this document have been tested with + distributions from Red Hat's Fedora Project (http://fedora.redhat.com/). + +- Install nfs-utils-1.1.2 or greater on the client + + An NFS/RDMA mount point can be obtained by using the mount.nfs command in + nfs-utils-1.1.2 or greater (nfs-utils-1.1.1 was the first nfs-utils + version with support for NFS/RDMA mounts, but for various reasons we + recommend using nfs-utils-1.1.2 or greater). To see which version of + mount.nfs you are using, type: + + .. code-block:: sh + + $ /sbin/mount.nfs -V + + If the version is less than 1.1.2 or the command does not exist, + you should install the latest version of nfs-utils. + + Download the latest package from: http://www.kernel.org/pub/linux/utils/nfs + + Uncompress the package and follow the installation instructions. + + If you will not need the idmapper and gssd executables (you do not need + these to create an NFS/RDMA enabled mount command), the installation + process can be simplified by disabling these features when running + configure: + + .. code-block:: sh + + $ ./configure --disable-gss --disable-nfsv4 + + To build nfs-utils you will need the tcp_wrappers package installed. For + more information on this see the package's README and INSTALL files. + + After building the nfs-utils package, there will be a mount.nfs binary in + the utils/mount directory. This binary can be used to initiate NFS v2, v3, + or v4 mounts. To initiate a v4 mount, the binary must be called + mount.nfs4. The standard technique is to create a symlink called + mount.nfs4 to mount.nfs. + + This mount.nfs binary should be installed at /sbin/mount.nfs as follows: + + .. code-block:: sh + + $ sudo cp utils/mount/mount.nfs /sbin/mount.nfs + + In this location, mount.nfs will be invoked automatically for NFS mounts + by the system mount command. + + .. note:: + mount.nfs and therefore nfs-utils-1.1.2 or greater is only needed + on the NFS client machine. You do not need this specific version of + nfs-utils on the server. Furthermore, only the mount.nfs command from + nfs-utils-1.1.2 is needed on the client. + +- Install a Linux kernel with NFS/RDMA + + The NFS/RDMA client and server are both included in the mainline Linux + kernel version 2.6.25 and later. This and other versions of the Linux + kernel can be found at: https://www.kernel.org/pub/linux/kernel/ + + Download the sources and place them in an appropriate location. + +- Configure the RDMA stack + + Make sure your kernel configuration has RDMA support enabled. Under + Device Drivers -> InfiniBand support, update the kernel configuration + to enable InfiniBand support [NOTE: the option name is misleading. Enabling + InfiniBand support is required for all RDMA devices (IB, iWARP, etc.)]. + + Enable the appropriate IB HCA support (mlx4, mthca, ehca, ipath, etc.) or + iWARP adapter support (amso, cxgb3, etc.). + + If you are using InfiniBand, be sure to enable IP-over-InfiniBand support. + +- Configure the NFS client and server + + Your kernel configuration must also have NFS file system support and/or + NFS server support enabled. These and other NFS related configuration + options can be found under File Systems -> Network File Systems. + +- Build, install, reboot + + The NFS/RDMA code will be enabled automatically if NFS and RDMA + are turned on. The NFS/RDMA client and server are configured via the hidden + SUNRPC_XPRT_RDMA config option that depends on SUNRPC and INFINIBAND. The + value of SUNRPC_XPRT_RDMA will be: + + #. N if either SUNRPC or INFINIBAND are N, in this case the NFS/RDMA client + and server will not be built + + #. M if both SUNRPC and INFINIBAND are on (M or Y) and at least one is M, + in this case the NFS/RDMA client and server will be built as modules + + #. Y if both SUNRPC and INFINIBAND are Y, in this case the NFS/RDMA client + and server will be built into the kernel + + Therefore, if you have followed the steps above and turned no NFS and RDMA, + the NFS/RDMA client and server will be built. + + Build a new kernel, install it, boot it. + +Check RDMA and NFS Setup +======================== + +Before configuring the NFS/RDMA software, it is a good idea to test +your new kernel to ensure that the kernel is working correctly. +In particular, it is a good idea to verify that the RDMA stack +is functioning as expected and standard NFS over TCP/IP and/or UDP/IP +is working properly. + +- Check RDMA Setup + + If you built the RDMA components as modules, load them at + this time. For example, if you are using a Mellanox Tavor/Sinai/Arbel + card: + + .. code-block:: sh + + $ modprobe ib_mthca + $ modprobe ib_ipoib + + If you are using InfiniBand, make sure there is a Subnet Manager (SM) + running on the network. If your IB switch has an embedded SM, you can + use it. Otherwise, you will need to run an SM, such as OpenSM, on one + of your end nodes. + + If an SM is running on your network, you should see the following: + + .. code-block:: sh + + $ cat /sys/class/infiniband/driverX/ports/1/state + 4: ACTIVE + + where driverX is mthca0, ipath5, ehca3, etc. + + To further test the InfiniBand software stack, use IPoIB (this + assumes you have two IB hosts named host1 and host2): + + .. code-block:: sh + + host1$ ip link set dev ib0 up + host1$ ip address add dev ib0 a.b.c.x + host2$ ip link set dev ib0 up + host2$ ip address add dev ib0 a.b.c.y + host1$ ping a.b.c.y + host2$ ping a.b.c.x + + For other device types, follow the appropriate procedures. + +- Check NFS Setup + + For the NFS components enabled above (client and/or server), + test their functionality over standard Ethernet using TCP/IP or UDP/IP. + +NFS/RDMA Setup +============== + +We recommend that you use two machines, one to act as the client and +one to act as the server. + +One time configuration: +----------------------- + +- On the server system, configure the /etc/exports file and start the NFS/RDMA server. + + Exports entries with the following formats have been tested:: + + /vol0 192.168.0.47(fsid=0,rw,async,insecure,no_root_squash) + /vol0 192.168.0.0/255.255.255.0(fsid=0,rw,async,insecure,no_root_squash) + + The IP address(es) is(are) the client's IPoIB address for an InfiniBand + HCA or the client's iWARP address(es) for an RNIC. + + .. note:: + The "insecure" option must be used because the NFS/RDMA client does + not use a reserved port. + +Each time a machine boots: +-------------------------- + +- Load and configure the RDMA drivers + + For InfiniBand using a Mellanox adapter: + + .. code-block:: sh + + $ modprobe ib_mthca + $ modprobe ib_ipoib + $ ip li set dev ib0 up + $ ip addr add dev ib0 a.b.c.d + + .. note:: + Please use unique addresses for the client and server! + +- Start the NFS server + + If the NFS/RDMA server was built as a module (CONFIG_SUNRPC_XPRT_RDMA=m in + kernel config), load the RDMA transport module: + + .. code-block:: sh + + $ modprobe svcrdma + + Regardless of how the server was built (module or built-in), start the + server: + + .. code-block:: sh + + $ /etc/init.d/nfs start + + or + + .. code-block:: sh + + $ service nfs start + + Instruct the server to listen on the RDMA transport: + + .. code-block:: sh + + $ echo rdma 20049 > /proc/fs/nfsd/portlist + +- On the client system + + If the NFS/RDMA client was built as a module (CONFIG_SUNRPC_XPRT_RDMA=m in + kernel config), load the RDMA client module: + + .. code-block:: sh + + $ modprobe xprtrdma.ko + + Regardless of how the client was built (module or built-in), use this + command to mount the NFS/RDMA server: + + .. code-block:: sh + + $ mount -o rdma,port=20049 <IPoIB-server-name-or-address>:/<export> /mnt + + To verify that the mount is using RDMA, run "cat /proc/mounts" and check + the "proto" field for the given mount. + + Congratulations! You're using NFS/RDMA! diff --git a/Documentation/filesystems/nfs/nfsd-admin-interfaces.txt b/Documentation/admin-guide/nfs/nfsd-admin-interfaces.rst index 56a96fb08a73..c05926f79054 100644 --- a/Documentation/filesystems/nfs/nfsd-admin-interfaces.txt +++ b/Documentation/admin-guide/nfs/nfsd-admin-interfaces.rst @@ -1,5 +1,6 @@ +================================== Administrative interfaces for nfsd -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +================================== Note that normally these interfaces are used only by the utilities in nfs-utils. @@ -13,18 +14,16 @@ nfsd/threads. Before doing that, NFSD can be told which sockets to listen on by writing to nfsd/portlist; that write may be: - - an ascii-encoded file descriptor, which should refer to a - bound (and listening, for tcp) socket, or - - "transportname port", where transportname is currently either - "udp", "tcp", or "rdma". + - an ascii-encoded file descriptor, which should refer to a + bound (and listening, for tcp) socket, or + - "transportname port", where transportname is currently either + "udp", "tcp", or "rdma". If nfsd is started without doing any of these, then it will create one udp and one tcp listener at port 2049 (see nfsd_init_socks). -On startup, nfsd and lockd grace periods start. - -nfsd is shut down by a write of 0 to nfsd/threads. All locks and state -are thrown away at that point. +On startup, nfsd and lockd grace periods start. nfsd is shut down by a write of +0 to nfsd/threads. All locks and state are thrown away at that point. Between startup and shutdown, the number of threads may be adjusted up or down by additional writes to nfsd/threads or by writes to @@ -34,7 +33,7 @@ For more detail about files under nfsd/ and what they control, see fs/nfsd/nfsctl.c; most of them have detailed comments. Implementation notes -^^^^^^^^^^^^^^^^^^^^ +==================== Note that the rpc server requires the caller to serialize addition and removal of listening sockets, and startup and shutdown of the server. diff --git a/Documentation/filesystems/nfs/nfsroot.txt b/Documentation/admin-guide/nfs/nfsroot.rst index ae4332464560..82a4fda057f9 100644 --- a/Documentation/filesystems/nfs/nfsroot.txt +++ b/Documentation/admin-guide/nfs/nfsroot.rst @@ -1,27 +1,34 @@ +=============================================== Mounting the root filesystem via NFS (nfsroot) =============================================== -Written 1996 by Gero Kuhlmann <gero@gkminix.han.de> -Updated 1997 by Martin Mares <mj@atrey.karlin.mff.cuni.cz> -Updated 2006 by Nico Schottelius <nico-kernel-nfsroot@schottelius.org> -Updated 2006 by Horms <horms@verge.net.au> -Updated 2018 by Chris Novakovic <chris@chrisn.me.uk> +:Authors: + Written 1996 by Gero Kuhlmann <gero@gkminix.han.de> + + Updated 1997 by Martin Mares <mj@atrey.karlin.mff.cuni.cz> + + Updated 2006 by Nico Schottelius <nico-kernel-nfsroot@schottelius.org> + + Updated 2006 by Horms <horms@verge.net.au> + Updated 2018 by Chris Novakovic <chris@chrisn.me.uk> -In order to use a diskless system, such as an X-terminal or printer server -for example, it is necessary for the root filesystem to be present on a -non-disk device. This may be an initramfs (see Documentation/filesystems/ -ramfs-rootfs-initramfs.txt), a ramdisk (see Documentation/admin-guide/initrd.rst) or a -filesystem mounted via NFS. The following text describes on how to use NFS -for the root filesystem. For the rest of this text 'client' means the -diskless system, and 'server' means the NFS server. +In order to use a diskless system, such as an X-terminal or printer server for +example, it is necessary for the root filesystem to be present on a non-disk +device. This may be an initramfs (see +Documentation/filesystems/ramfs-rootfs-initramfs.txt), a ramdisk (see +Documentation/admin-guide/initrd.rst) or a filesystem mounted via NFS. The +following text describes on how to use NFS for the root filesystem. For the rest +of this text 'client' means the diskless system, and 'server' means the NFS +server. -1.) Enabling nfsroot capabilities - ----------------------------- + +Enabling nfsroot capabilities +============================= In order to use nfsroot, NFS client support needs to be selected as built-in during configuration. Once this has been selected, the nfsroot @@ -34,8 +41,8 @@ DHCP, BOOTP and RARP is safe. -2.) Kernel command line - ------------------- +Kernel command line +=================== When the kernel has been loaded by a boot loader (see below) it needs to be told what root fs device to use. And in the case of nfsroot, where to find @@ -44,19 +51,17 @@ This can be established using the following kernel command line parameters: root=/dev/nfs - This is necessary to enable the pseudo-NFS-device. Note that it's not a real device but just a synonym to tell the kernel to use NFS instead of a real device. nfsroot=[<server-ip>:]<root-dir>[,<nfs-options>] - If the `nfsroot' parameter is NOT given on the command line, - the default "/tftpboot/%s" will be used. + the default ``"/tftpboot/%s"`` will be used. <server-ip> Specifies the IP address of the NFS server. - The default address is determined by the `ip' parameter + The default address is determined by the ip parameter (see below). This parameter allows the use of different servers for IP autoconfiguration and NFS. @@ -66,7 +71,8 @@ nfsroot=[<server-ip>:]<root-dir>[,<nfs-options>] IP address. <nfs-options> Standard NFS options. All options are separated by commas. - The following defaults are used: + The following defaults are used:: + port = as given by server portmap daemon rsize = 4096 wsize = 4096 @@ -79,13 +85,11 @@ nfsroot=[<server-ip>:]<root-dir>[,<nfs-options>] flags = hard, nointr, noposix, cto, ac -ip=<client-ip>:<server-ip>:<gw-ip>:<netmask>:<hostname>:<device>:<autoconf>: - <dns0-ip>:<dns1-ip>:<ntp0-ip> - +ip=<client-ip>:<server-ip>:<gw-ip>:<netmask>:<hostname>:<device>:<autoconf>:<dns0-ip>:<dns1-ip>:<ntp0-ip> This parameter tells the kernel how to configure IP addresses of devices and also how to set up the IP routing table. It was originally called - `nfsaddrs', but now the boot-time IP configuration works independently of - NFS, so it was renamed to `ip' and the old name remained as an alias for + nfsaddrs, but now the boot-time IP configuration works independently of + NFS, so it was renamed to ip and the old name remained as an alias for compatibility reasons. If this parameter is missing from the kernel command line, all fields are @@ -93,17 +97,17 @@ ip=<client-ip>:<server-ip>:<gw-ip>:<netmask>:<hostname>:<device>:<autoconf>: this means that the kernel tries to configure everything using autoconfiguration. - The <autoconf> parameter can appear alone as the value to the `ip' + The <autoconf> parameter can appear alone as the value to the ip parameter (without all the ':' characters before). If the value is "ip=off" or "ip=none", no autoconfiguration will take place, otherwise autoconfiguration will take place. The most common way to use this is "ip=dhcp". <client-ip> IP address of the client. - Default: Determined using autoconfiguration. - <server-ip> IP address of the NFS server. If RARP is used to determine + <server-ip> IP address of the NFS server. + If RARP is used to determine the client address and this parameter is NOT empty only replies from the specified server are accepted. @@ -115,19 +119,19 @@ ip=<client-ip>:<server-ip>:<gw-ip>:<netmask>:<hostname>:<device>:<autoconf>: (see below). Default: Determined using autoconfiguration. - The address of the autoconfiguration server is used. + The address of the autoconfiguration server is used. <gw-ip> IP address of a gateway if the server is on a different subnet. - Default: Determined using autoconfiguration. - <netmask> Netmask for local network interface. If unspecified - the netmask is derived from the client IP address assuming - classful addressing. + <netmask> Netmask for local network interface. + If unspecified the netmask is derived from the client IP address + assuming classful addressing. Default: Determined using autoconfiguration. - <hostname> Name of the client. If a '.' character is present, anything + <hostname> Name of the client. + If a '.' character is present, anything before the first '.' is used as the client's hostname, and anything after it is used as its NIS domain name. May be supplied by autoconfiguration, but its absence will not trigger autoconfiguration. @@ -138,21 +142,21 @@ ip=<client-ip>:<server-ip>:<gw-ip>:<netmask>:<hostname>:<device>:<autoconf>: Default: Client IP address is used in ASCII notation. <device> Name of network device to use. - Default: If the host only has one device, it is used. - Otherwise the device is determined using - autoconfiguration. This is done by sending - autoconfiguration requests out of all devices, - and using the device that received the first reply. - - <autoconf> Method to use for autoconfiguration. In the case of options - which specify multiple autoconfiguration protocols, + Otherwise the device is determined using + autoconfiguration. This is done by sending + autoconfiguration requests out of all devices, + and using the device that received the first reply. + + <autoconf> Method to use for autoconfiguration. + In the case of options + which specify multiple autoconfiguration protocols, requests are sent using all protocols, and the first one to reply is used. Only autoconfiguration protocols that have been compiled into the kernel will be used, regardless of the value of - this option. + this option:: off or none: don't use autoconfiguration (do static IP assignment instead) @@ -221,7 +225,6 @@ ip=<client-ip>:<server-ip>:<gw-ip>:<netmask>:<hostname>:<device>:<autoconf>: nfsrootdebug - This parameter enables debugging messages to appear in the kernel log at boot time so that administrators can verify that the correct NFS mount options, server address, and root path are passed to the @@ -229,36 +232,32 @@ nfsrootdebug rdinit=<executable file> - To specify which file contains the program that starts system initialization, administrators can use this command line parameter. The default value of this parameter is "/init". If the specified file exists and the kernel can execute it, root filesystem related - kernel command line parameters, including `nfsroot=', are ignored. + kernel command line parameters, including 'nfsroot=', are ignored. A description of the process of mounting the root file system can be - found in: - - Documentation/driver-api/early-userspace/early_userspace_support.rst - - + found in Documentation/driver-api/early-userspace/early_userspace_support.rst -3.) Boot Loader - ---------- +Boot Loader +=========== To get the kernel into memory different approaches can be used. They depend on various facilities being available: -3.1) Booting from a floppy using syslinux +- Booting from a floppy using syslinux When building kernels, an easy way to create a boot floppy that uses syslinux is to use the zdisk or bzdisk make targets which use zimage and bzimage images respectively. Both targets accept the FDARGS parameter which can be used to set the kernel command line. - e.g. + e.g:: + make bzdisk FDARGS="root=/dev/nfs" Note that the user running this command will need to have @@ -267,32 +266,36 @@ They depend on various facilities being available: For more information on syslinux, including how to create bootdisks for prebuilt kernels, see http://syslinux.zytor.com/ - N.B: Previously it was possible to write a kernel directly to - a floppy using dd, configure the boot device using rdev, and - boot using the resulting floppy. Linux no longer supports this - method of booting. + .. note:: + Previously it was possible to write a kernel directly to + a floppy using dd, configure the boot device using rdev, and + boot using the resulting floppy. Linux no longer supports this + method of booting. -3.2) Booting from a cdrom using isolinux +- Booting from a cdrom using isolinux When building kernels, an easy way to create a bootable cdrom that uses isolinux is to use the isoimage target which uses a bzimage image. Like zdisk and bzdisk, this target accepts the FDARGS parameter which can be used to set the kernel command line. - e.g. + e.g:: + make isoimage FDARGS="root=/dev/nfs" The resulting iso image will be arch/<ARCH>/boot/image.iso This can be written to a cdrom using a variety of tools including cdrecord. - e.g. + e.g:: + cdrecord dev=ATAPI:1,0,0 arch/x86/boot/image.iso For more information on isolinux, including how to create bootdisks for prebuilt kernels, see http://syslinux.zytor.com/ -3.2) Using LILO +- Using LILO + When using LILO all the necessary command line parameters may be specified using the 'append=' directive in the LILO configuration file. @@ -300,15 +303,19 @@ They depend on various facilities being available: However, to use the 'root=' directive you also need to create a dummy root device, which may be removed after LILO is run. - mknod /dev/boot255 c 0 255 + e.g:: + + mknod /dev/boot255 c 0 255 For information on configuring LILO, please refer to its documentation. -3.3) Using GRUB +- Using GRUB + When using GRUB, kernel parameter are simply appended after the kernel specification: kernel <kernel> <parameters> -3.4) Using loadlin +- Using loadlin + loadlin may be used to boot Linux from a DOS command prompt without requiring a local hard disk to mount as root. This has not been thoroughly tested by the authors of this document, but in general @@ -317,7 +324,8 @@ They depend on various facilities being available: Please refer to the loadlin documentation for further information. -3.5) Using a boot ROM +- Using a boot ROM + This is probably the most elegant way of booting a diskless client. With a boot ROM the kernel is loaded using the TFTP protocol. The authors of this document are not aware of any no commercial boot @@ -326,7 +334,8 @@ They depend on various facilities being available: etherboot, both of which are available on sunsite.unc.edu, and both of which contain everything you need to boot a diskless Linux client. -3.6) Using pxelinux +- Using pxelinux + Pxelinux may be used to boot linux using the PXE boot loader which is present on many modern network cards. @@ -342,8 +351,8 @@ They depend on various facilities being available: -4.) Credits - ------- +Credits +======= The nfsroot code in the kernel and the RARP support have been written by Gero Kuhlmann <gero@gkminix.han.de>. diff --git a/Documentation/filesystems/nfs/pnfs-block-server.txt b/Documentation/admin-guide/nfs/pnfs-block-server.rst index 2143673cf154..b00a2e705cc4 100644 --- a/Documentation/filesystems/nfs/pnfs-block-server.txt +++ b/Documentation/admin-guide/nfs/pnfs-block-server.rst @@ -1,4 +1,6 @@ +=================================== pNFS block layout server user guide +=================================== The Linux NFS server now supports the pNFS block layout extension. In this case the NFS server acts as Metadata Server (MDS) for pNFS, which in addition @@ -22,16 +24,19 @@ If the nfsd server needs to fence a non-responding client it calls /sbin/nfsd-recall-failed with the first argument set to the IP address of the client, and the second argument set to the device node without the /dev prefix for the file system to be fenced. Below is an example file that shows -how to translate the device into a serial number from SCSI EVPD 0x80: +how to translate the device into a serial number from SCSI EVPD 0x80:: -cat > /sbin/nfsd-recall-failed << EOF -#!/bin/sh + cat > /sbin/nfsd-recall-failed << EOF -CLIENT="$1" -DEV="/dev/$2" -EVPD=`sg_inq --page=0x80 ${DEV} | \ - grep "Unit serial number:" | \ - awk -F ': ' '{print $2}'` +.. code-block:: sh -echo "fencing client ${CLIENT} serial ${EVPD}" >> /var/log/pnfsd-fence.log -EOF + #!/bin/sh + + CLIENT="$1" + DEV="/dev/$2" + EVPD=`sg_inq --page=0x80 ${DEV} | \ + grep "Unit serial number:" | \ + awk -F ': ' '{print $2}'` + + echo "fencing client ${CLIENT} serial ${EVPD}" >> /var/log/pnfsd-fence.log + EOF diff --git a/Documentation/filesystems/nfs/pnfs-scsi-server.txt b/Documentation/admin-guide/nfs/pnfs-scsi-server.rst index 5bef7268bd9f..d2f6ee558071 100644 --- a/Documentation/filesystems/nfs/pnfs-scsi-server.txt +++ b/Documentation/admin-guide/nfs/pnfs-scsi-server.rst @@ -1,4 +1,5 @@ +================================== pNFS SCSI layout server user guide ================================== diff --git a/Documentation/admin-guide/pm/cpuidle.rst b/Documentation/admin-guide/pm/cpuidle.rst index e70b365dbc60..6a06dc473dd6 100644 --- a/Documentation/admin-guide/pm/cpuidle.rst +++ b/Documentation/admin-guide/pm/cpuidle.rst @@ -506,6 +506,9 @@ object corresponding to it, as follows: ``disable`` Whether or not this idle state is disabled. +``default_status`` + The default status of this state, "enabled" or "disabled". + ``latency`` Exit latency of the idle state in microseconds. @@ -629,16 +632,16 @@ class priority list and destroyed. If that happens, the priority list mechanism will be used, again, to determine the new effective value for the whole list and that value will become the new real constraint. -In turn, for each CPU there is only one resume latency PM QoS request -associated with the :file:`power/pm_qos_resume_latency_us` file under +In turn, for each CPU there is one resume latency PM QoS request associated with +the :file:`power/pm_qos_resume_latency_us` file under :file:`/sys/devices/system/cpu/cpu<N>/` in ``sysfs`` and writing to it causes this single PM QoS request to be updated regardless of which user space process does that. In other words, this PM QoS request is shared by the entire user space, so access to the file associated with it needs to be arbitrated to avoid confusion. [Arguably, the only legitimate use of this mechanism in practice is to pin a process to the CPU in question and let it use the -``sysfs`` interface to control the resume latency constraint for it.] It -still only is a request, however. It is a member of a priority list used to +``sysfs`` interface to control the resume latency constraint for it.] It is +still only a request, however. It is an entry in a priority list used to determine the effective value to be set as the resume latency constraint for the CPU in question every time the list of requests is updated this way or another (there may be other requests coming from kernel code in that list). diff --git a/Documentation/admin-guide/pm/intel_idle.rst b/Documentation/admin-guide/pm/intel_idle.rst new file mode 100644 index 000000000000..89309e1b0e48 --- /dev/null +++ b/Documentation/admin-guide/pm/intel_idle.rst @@ -0,0 +1,268 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. include:: <isonum.txt> + +============================================== +``intel_idle`` CPU Idle Time Management Driver +============================================== + +:Copyright: |copy| 2020 Intel Corporation + +:Author: Rafael J. Wysocki <rafael.j.wysocki@intel.com> + + +General Information +=================== + +``intel_idle`` is a part of the +:doc:`CPU idle time management subsystem <cpuidle>` in the Linux kernel +(``CPUIdle``). It is the default CPU idle time management driver for the +Nehalem and later generations of Intel processors, but the level of support for +a particular processor model in it depends on whether or not it recognizes that +processor model and may also depend on information coming from the platform +firmware. [To understand ``intel_idle`` it is necessary to know how ``CPUIdle`` +works in general, so this is the time to get familiar with :doc:`cpuidle` if you +have not done that yet.] + +``intel_idle`` uses the ``MWAIT`` instruction to inform the processor that the +logical CPU executing it is idle and so it may be possible to put some of the +processor's functional blocks into low-power states. That instruction takes two +arguments (passed in the ``EAX`` and ``ECX`` registers of the target CPU), the +first of which, referred to as a *hint*, can be used by the processor to +determine what can be done (for details refer to Intel Software Developer’s +Manual [1]_). Accordingly, ``intel_idle`` refuses to work with processors in +which the support for the ``MWAIT`` instruction has been disabled (for example, +via the platform firmware configuration menu) or which do not support that +instruction at all. + +``intel_idle`` is not modular, so it cannot be unloaded, which means that the +only way to pass early-configuration-time parameters to it is via the kernel +command line. + + +.. _intel-idle-enumeration-of-states: + +Enumeration of Idle States +========================== + +Each ``MWAIT`` hint value is interpreted by the processor as a license to +reconfigure itself in a certain way in order to save energy. The processor +configurations (with reduced power draw) resulting from that are referred to +as C-states (in the ACPI terminology) or idle states. The list of meaningful +``MWAIT`` hint values and idle states (i.e. low-power configurations of the +processor) corresponding to them depends on the processor model and it may also +depend on the configuration of the platform. + +In order to create a list of available idle states required by the ``CPUIdle`` +subsystem (see :ref:`idle-states-representation` in :doc:`cpuidle`), +``intel_idle`` can use two sources of information: static tables of idle states +for different processor models included in the driver itself and the ACPI tables +of the system. The former are always used if the processor model at hand is +recognized by ``intel_idle`` and the latter are used if that is required for +the given processor model (which is the case for all server processor models +recognized by ``intel_idle``) or if the processor model is not recognized. +[There is a module parameter that can be used to make the driver use the ACPI +tables with any processor model recognized by it; see +`below <intel-idle-parameters_>`_.] + +If the ACPI tables are going to be used for building the list of available idle +states, ``intel_idle`` first looks for a ``_CST`` object under one of the ACPI +objects corresponding to the CPUs in the system (refer to the ACPI specification +[2]_ for the description of ``_CST`` and its output package). Because the +``CPUIdle`` subsystem expects that the list of idle states supplied by the +driver will be suitable for all of the CPUs handled by it and ``intel_idle`` is +registered as the ``CPUIdle`` driver for all of the CPUs in the system, the +driver looks for the first ``_CST`` object returning at least one valid idle +state description and such that all of the idle states included in its return +package are of the FFH (Functional Fixed Hardware) type, which means that the +``MWAIT`` instruction is expected to be used to tell the processor that it can +enter one of them. The return package of that ``_CST`` is then assumed to be +applicable to all of the other CPUs in the system and the idle state +descriptions extracted from it are stored in a preliminary list of idle states +coming from the ACPI tables. [This step is skipped if ``intel_idle`` is +configured to ignore the ACPI tables; see `below <intel-idle-parameters_>`_.] + +Next, the first (index 0) entry in the list of available idle states is +initialized to represent a "polling idle state" (a pseudo-idle state in which +the target CPU continuously fetches and executes instructions), and the +subsequent (real) idle state entries are populated as follows. + +If the processor model at hand is recognized by ``intel_idle``, there is a +(static) table of idle state descriptions for it in the driver. In that case, +the "internal" table is the primary source of information on idle states and the +information from it is copied to the final list of available idle states. If +using the ACPI tables for the enumeration of idle states is not required +(depending on the processor model), all of the listed idle state are enabled by +default (so all of them will be taken into consideration by ``CPUIdle`` +governors during CPU idle state selection). Otherwise, some of the listed idle +states may not be enabled by default if there are no matching entries in the +preliminary list of idle states coming from the ACPI tables. In that case user +space still can enable them later (on a per-CPU basis) with the help of +the ``disable`` idle state attribute in ``sysfs`` (see +:ref:`idle-states-representation` in :doc:`cpuidle`). This basically means that +the idle states "known" to the driver may not be enabled by default if they have +not been exposed by the platform firmware (through the ACPI tables). + +If the given processor model is not recognized by ``intel_idle``, but it +supports ``MWAIT``, the preliminary list of idle states coming from the ACPI +tables is used for building the final list that will be supplied to the +``CPUIdle`` core during driver registration. For each idle state in that list, +the description, ``MWAIT`` hint and exit latency are copied to the corresponding +entry in the final list of idle states. The name of the idle state represented +by it (to be returned by the ``name`` idle state attribute in ``sysfs``) is +"CX_ACPI", where X is the index of that idle state in the final list (note that +the minimum value of X is 1, because 0 is reserved for the "polling" state), and +its target residency is based on the exit latency value. Specifically, for +C1-type idle states the exit latency value is also used as the target residency +(for compatibility with the majority of the "internal" tables of idle states for +various processor models recognized by ``intel_idle``) and for the other idle +state types (C2 and C3) the target residency value is 3 times the exit latency +(again, that is because it reflects the target residency to exit latency ratio +in the majority of cases for the processor models recognized by ``intel_idle``). +All of the idle states in the final list are enabled by default in this case. + + +.. _intel-idle-initialization: + +Initialization +============== + +The initialization of ``intel_idle`` starts with checking if the kernel command +line options forbid the use of the ``MWAIT`` instruction. If that is the case, +an error code is returned right away. + +The next step is to check whether or not the processor model is known to the +driver, which determines the idle states enumeration method (see +`above <intel-idle-enumeration-of-states_>`_), and whether or not the processor +supports ``MWAIT`` (the initialization fails if that is not the case). Then, +the ``MWAIT`` support in the processor is enumerated through ``CPUID`` and the +driver initialization fails if the level of support is not as expected (for +example, if the total number of ``MWAIT`` substates returned is 0). + +Next, if the driver is not configured to ignore the ACPI tables (see +`below <intel-idle-parameters_>`_), the idle states information provided by the +platform firmware is extracted from them. + +Then, ``CPUIdle`` device objects are allocated for all CPUs and the list of +available idle states is created as explained +`above <intel-idle-enumeration-of-states_>`_. + +Finally, ``intel_idle`` is registered with the help of cpuidle_register_driver() +as the ``CPUIdle`` driver for all CPUs in the system and a CPU online callback +for configuring individual CPUs is registered via cpuhp_setup_state(), which +(among other things) causes the callback routine to be invoked for all of the +CPUs present in the system at that time (each CPU executes its own instance of +the callback routine). That routine registers a ``CPUIdle`` device for the CPU +running it (which enables the ``CPUIdle`` subsystem to operate that CPU) and +optionally performs some CPU-specific initialization actions that may be +required for the given processor model. + + +.. _intel-idle-parameters: + +Kernel Command Line Options and Module Parameters +================================================= + +The *x86* architecture support code recognizes three kernel command line +options related to CPU idle time management: ``idle=poll``, ``idle=halt``, +and ``idle=nomwait``. If any of them is present in the kernel command line, the +``MWAIT`` instruction is not allowed to be used, so the initialization of +``intel_idle`` will fail. + +Apart from that there are four module parameters recognized by ``intel_idle`` +itself that can be set via the kernel command line (they cannot be updated via +sysfs, so that is the only way to change their values). + +The ``max_cstate`` parameter value is the maximum idle state index in the list +of idle states supplied to the ``CPUIdle`` core during the registration of the +driver. It is also the maximum number of regular (non-polling) idle states that +can be used by ``intel_idle``, so the enumeration of idle states is terminated +after finding that number of usable idle states (the other idle states that +potentially might have been used if ``max_cstate`` had been greater are not +taken into consideration at all). Setting ``max_cstate`` can prevent +``intel_idle`` from exposing idle states that are regarded as "too deep" for +some reason to the ``CPUIdle`` core, but it does so by making them effectively +invisible until the system is shut down and started again which may not always +be desirable. In practice, it is only really necessary to do that if the idle +states in question cannot be enabled during system startup, because in the +working state of the system the CPU power management quality of service (PM +QoS) feature can be used to prevent ``CPUIdle`` from touching those idle states +even if they have been enumerated (see :ref:`cpu-pm-qos` in :doc:`cpuidle`). +Setting ``max_cstate`` to 0 causes the ``intel_idle`` initialization to fail. + +The ``no_acpi`` and ``use_acpi`` module parameters (recognized by ``intel_idle`` +if the kernel has been configured with ACPI support) can be set to make the +driver ignore the system's ACPI tables entirely or use them for all of the +recognized processor models, respectively (they both are unset by default and +``use_acpi`` has no effect if ``no_acpi`` is set). + +The value of the ``states_off`` module parameter (0 by default) represents a +list of idle states to be disabled by default in the form of a bitmask. + +Namely, the positions of the bits that are set in the ``states_off`` value are +the indices of idle states to be disabled by default (as reflected by the names +of the corresponding idle state directories in ``sysfs``, :file:`state0`, +:file:`state1` ... :file:`state<i>` ..., where ``<i>`` is the index of the given +idle state; see :ref:`idle-states-representation` in :doc:`cpuidle`). + +For example, if ``states_off`` is equal to 3, the driver will disable idle +states 0 and 1 by default, and if it is equal to 8, idle state 3 will be +disabled by default and so on (bit positions beyond the maximum idle state index +are ignored). + +The idle states disabled this way can be enabled (on a per-CPU basis) from user +space via ``sysfs``. + + +.. _intel-idle-core-and-package-idle-states: + +Core and Package Levels of Idle States +====================================== + +Typically, in a processor supporting the ``MWAIT`` instruction there are (at +least) two levels of idle states (or C-states). One level, referred to as +"core C-states", covers individual cores in the processor, whereas the other +level, referred to as "package C-states", covers the entire processor package +and it may also involve other components of the system (GPUs, memory +controllers, I/O hubs etc.). + +Some of the ``MWAIT`` hint values allow the processor to use core C-states only +(most importantly, that is the case for the ``MWAIT`` hint value corresponding +to the ``C1`` idle state), but the majority of them give it a license to put +the target core (i.e. the core containing the logical CPU executing ``MWAIT`` +with the given hint value) into a specific core C-state and then (if possible) +to enter a specific package C-state at the deeper level. For example, the +``MWAIT`` hint value representing the ``C3`` idle state allows the processor to +put the target core into the low-power state referred to as "core ``C3``" (or +``CC3``), which happens if all of the logical CPUs (SMT siblings) in that core +have executed ``MWAIT`` with the ``C3`` hint value (or with a hint value +representing a deeper idle state), and in addition to that (in the majority of +cases) it gives the processor a license to put the entire package (possibly +including some non-CPU components such as a GPU or a memory controller) into the +low-power state referred to as "package ``C3``" (or ``PC3``), which happens if +all of the cores have gone into the ``CC3`` state and (possibly) some additional +conditions are satisfied (for instance, if the GPU is covered by ``PC3``, it may +be required to be in a certain GPU-specific low-power state for ``PC3`` to be +reachable). + +As a rule, there is no simple way to make the processor use core C-states only +if the conditions for entering the corresponding package C-states are met, so +the logical CPU executing ``MWAIT`` with a hint value that is not core-level +only (like for ``C1``) must always assume that this may cause the processor to +enter a package C-state. [That is why the exit latency and target residency +values corresponding to the majority of ``MWAIT`` hint values in the "internal" +tables of idle states in ``intel_idle`` reflect the properties of package +C-states.] If using package C-states is not desirable at all, either +:ref:`PM QoS <cpu-pm-qos>` or the ``max_cstate`` module parameter of +``intel_idle`` described `above <intel-idle-parameters_>`_ must be used to +restrict the range of permissible idle states to the ones with core-level only +``MWAIT`` hint values (like ``C1``). + + +References +========== + +.. [1] *Intel® 64 and IA-32 Architectures Software Developer’s Manual Volume 2B*, + https://www.intel.com/content/www/us/en/architecture-and-technology/64-ia-32-architectures-software-developer-vol-2b-manual.html + +.. [2] *Advanced Configuration and Power Interface (ACPI) Specification*, + https://uefi.org/specifications diff --git a/Documentation/admin-guide/pm/sleep-states.rst b/Documentation/admin-guide/pm/sleep-states.rst index cd3a28cb81f4..ee55a460c639 100644 --- a/Documentation/admin-guide/pm/sleep-states.rst +++ b/Documentation/admin-guide/pm/sleep-states.rst @@ -153,8 +153,11 @@ for the given CPU architecture includes the low-level code for system resume. Basic ``sysfs`` Interfaces for System Suspend and Hibernation ============================================================= -The following files located in the :file:`/sys/power/` directory can be used by -user space for sleep states control. +The power management subsystem provides userspace with a unified ``sysfs`` +interface for system sleep regardless of the underlying system architecture or +platform. That interface is located in the :file:`/sys/power/` directory +(assuming that ``sysfs`` is mounted at :file:`/sys`) and it consists of the +following attributes (files): ``state`` This file contains a list of strings representing sleep states supported @@ -162,9 +165,9 @@ user space for sleep states control. to start a transition of the system into the sleep state represented by that string. - In particular, the strings "disk", "freeze" and "standby" represent the + In particular, the "disk", "freeze" and "standby" strings represent the :ref:`hibernation <hibernation>`, :ref:`suspend-to-idle <s2idle>` and - :ref:`standby <standby>` sleep states, respectively. The string "mem" + :ref:`standby <standby>` sleep states, respectively. The "mem" string is interpreted in accordance with the contents of the ``mem_sleep`` file described below. @@ -177,7 +180,7 @@ user space for sleep states control. associated with the "mem" string in the ``state`` file described above. The strings that may be present in this file are "s2idle", "shallow" - and "deep". The string "s2idle" always represents :ref:`suspend-to-idle + and "deep". The "s2idle" string always represents :ref:`suspend-to-idle <s2idle>` and, by convention, "shallow" and "deep" represent :ref:`standby <standby>` and :ref:`suspend-to-RAM <s2ram>`, respectively. @@ -185,15 +188,17 @@ user space for sleep states control. Writing one of the listed strings into this file causes the system suspend variant represented by it to be associated with the "mem" string in the ``state`` file. The string representing the suspend variant - currently associated with the "mem" string in the ``state`` file - is listed in square brackets. + currently associated with the "mem" string in the ``state`` file is + shown in square brackets. If the kernel does not support system suspend, this file is not present. ``disk`` - This file contains a list of strings representing different operations - that can be carried out after the hibernation image has been saved. The - possible options are as follows: + This file controls the operating mode of hibernation (Suspend-to-Disk). + Specifically, it tells the kernel what to do after creating a + hibernation image. + + Reading from it returns a list of supported options encoded as: ``platform`` Put the system into a special low-power state (e.g. ACPI S4) to @@ -201,6 +206,11 @@ user space for sleep states control. platform firmware to take a simplified initialization path after wakeup. + It is only available if the platform provides a special + mechanism to put the system to sleep after creating a + hibernation image (platforms with ACPI do that as a rule, for + example). + ``shutdown`` Power off the system. @@ -214,22 +224,53 @@ user space for sleep states control. the hibernation image and continue. Otherwise, use the image to restore the previous state of the system. + It is available if system suspend is supported. + ``test_resume`` Diagnostic operation. Load the image as though the system had just woken up from hibernation and the currently running kernel instance was a restore kernel and follow up with full system resume. - Writing one of the listed strings into this file causes the option + Writing one of the strings listed above into this file causes the option represented by it to be selected. - The currently selected option is shown in square brackets which means + The currently selected option is shown in square brackets, which means that the operation represented by it will be carried out after creating - and saving the image next time hibernation is triggered by writing - ``disk`` to :file:`/sys/power/state`. + and saving the image when hibernation is triggered by writing ``disk`` + to :file:`/sys/power/state`. If the kernel does not support hibernation, this file is not present. +``image_size`` + This file controls the size of hibernation images. + + It can be written a string representing a non-negative integer that will + be used as a best-effort upper limit of the image size, in bytes. The + hibernation core will do its best to ensure that the image size will not + exceed that number, but if that turns out to be impossible to achieve, a + hibernation image will still be created and its size will be as small as + possible. In particular, writing '0' to this file causes the size of + hibernation images to be minimum. + + Reading from it returns the current image size limit, which is set to + around 2/5 of the available RAM size by default. + +``pm_trace`` + This file controls the "PM trace" mechanism saving the last suspend + or resume event point in the RTC memory across reboots. It helps to + debug hard lockups or reboots due to device driver failures that occur + during system suspend or resume (which is more common) more effectively. + + If it contains "1", the fingerprint of each suspend/resume event point + in turn will be stored in the RTC memory (overwriting the actual RTC + information), so it will survive a system crash if one occurs right + after storing it and it can be used later to identify the driver that + caused the crash to happen. + + It contains "0" by default, which may be changed to "1" by writing a + string representing a nonzero integer into it. + According to the above, there are two ways to make the system go into the :ref:`suspend-to-idle <s2idle>` state. The first one is to write "freeze" directly to :file:`/sys/power/state`. The second one is to write "s2idle" to @@ -244,6 +285,7 @@ system go into the :ref:`suspend-to-RAM <s2ram>` state (write "deep" into The default suspend variant (ie. the one to be used without writing anything into :file:`/sys/power/mem_sleep`) is either "deep" (on the majority of systems supporting :ref:`suspend-to-RAM <s2ram>`) or "s2idle", but it can be overridden -by the value of the "mem_sleep_default" parameter in the kernel command line. -On some ACPI-based systems, depending on the information in the ACPI tables, the -default may be "s2idle" even if :ref:`suspend-to-RAM <s2ram>` is supported. +by the value of the ``mem_sleep_default`` parameter in the kernel command line. +On some systems with ACPI, depending on the information in the ACPI tables, the +default may be "s2idle" even if :ref:`suspend-to-RAM <s2ram>` is supported in +principle. diff --git a/Documentation/admin-guide/pm/working-state.rst b/Documentation/admin-guide/pm/working-state.rst index fc298eb1234b..88f717e59a42 100644 --- a/Documentation/admin-guide/pm/working-state.rst +++ b/Documentation/admin-guide/pm/working-state.rst @@ -8,6 +8,7 @@ Working-State Power Management :maxdepth: 2 cpuidle + intel_idle cpufreq intel_pstate intel_epb diff --git a/Documentation/admin-guide/thunderbolt.rst b/Documentation/admin-guide/thunderbolt.rst index 898ad78f3cc7..10c4f0ce2ad0 100644 --- a/Documentation/admin-guide/thunderbolt.rst +++ b/Documentation/admin-guide/thunderbolt.rst @@ -1,6 +1,28 @@ -============= - Thunderbolt -============= +.. SPDX-License-Identifier: GPL-2.0 + +====================== + USB4 and Thunderbolt +====================== +USB4 is the public specification based on Thunderbolt 3 protocol with +some differences at the register level among other things. Connection +manager is an entity running on the host router (host controller) +responsible for enumerating routers and establishing tunnels. A +connection manager can be implemented either in firmware or software. +Typically PCs come with a firmware connection manager for Thunderbolt 3 +and early USB4 capable systems. Apple systems on the other hand use +software connection manager and the later USB4 compliant devices follow +the suit. + +The Linux Thunderbolt driver supports both and can detect at runtime which +connection manager implementation is to be used. To be on the safe side the +software connection manager in Linux also advertises security level +``user`` which means PCIe tunneling is disabled by default. The +documentation below applies to both implementations with the exception that +the software connection manager only supports ``user`` security level and +is expected to be accompanied with an IOMMU based DMA protection. + +Security levels and how to use them +----------------------------------- The interface presented here is not meant for end users. Instead there should be a userspace tool that handles all the low-level details, keeps a database of the authorized devices and prompts users for new connections. @@ -18,8 +40,6 @@ This will authorize all devices automatically when they appear. However, keep in mind that this bypasses the security levels and makes the system vulnerable to DMA attacks. -Security levels and how to use them ------------------------------------ Starting with Intel Falcon Ridge Thunderbolt controller there are 4 security levels available. Intel Titan Ridge added one more security level (usbonly). The reason for these is the fact that the connected devices can diff --git a/Documentation/arm/microchip.rst b/Documentation/arm/microchip.rst index 1adf53dfc494..05e5f2dfb814 100644 --- a/Documentation/arm/microchip.rst +++ b/Documentation/arm/microchip.rst @@ -92,6 +92,12 @@ the Microchip website: http://www.microchip.com. http://ww1.microchip.com/downloads/en/DeviceDoc/DS60001517A.pdf + - sam9x60 + + * Datasheet + + http://ww1.microchip.com/downloads/en/DeviceDoc/SAM9X60-Data-Sheet-DS60001579A.pdf + * ARM Cortex-A5 based SoCs - sama5d3 family diff --git a/Documentation/arm64/cpu-feature-registers.rst b/Documentation/arm64/cpu-feature-registers.rst index b6e44884e3ad..41937a8091aa 100644 --- a/Documentation/arm64/cpu-feature-registers.rst +++ b/Documentation/arm64/cpu-feature-registers.rst @@ -117,6 +117,8 @@ infrastructure: +------------------------------+---------+---------+ | Name | bits | visible | +------------------------------+---------+---------+ + | RNDR | [63-60] | y | + +------------------------------+---------+---------+ | TS | [55-52] | y | +------------------------------+---------+---------+ | FHM | [51-48] | y | @@ -200,6 +202,12 @@ infrastructure: +------------------------------+---------+---------+ | Name | bits | visible | +------------------------------+---------+---------+ + | I8MM | [55-52] | y | + +------------------------------+---------+---------+ + | DGH | [51-48] | y | + +------------------------------+---------+---------+ + | BF16 | [47-44] | y | + +------------------------------+---------+---------+ | SB | [39-36] | y | +------------------------------+---------+---------+ | FRINTTS | [35-32] | y | @@ -234,10 +242,18 @@ infrastructure: +------------------------------+---------+---------+ | Name | bits | visible | +------------------------------+---------+---------+ + | F64MM | [59-56] | y | + +------------------------------+---------+---------+ + | F32MM | [55-52] | y | + +------------------------------+---------+---------+ + | I8MM | [47-44] | y | + +------------------------------+---------+---------+ | SM4 | [43-40] | y | +------------------------------+---------+---------+ | SHA3 | [35-32] | y | +------------------------------+---------+---------+ + | BF16 | [23-20] | y | + +------------------------------+---------+---------+ | BitPerm | [19-16] | y | +------------------------------+---------+---------+ | AES | [7-4] | y | diff --git a/Documentation/arm64/elf_hwcaps.rst b/Documentation/arm64/elf_hwcaps.rst index 7fa3d215ae6a..7dfb97dfe416 100644 --- a/Documentation/arm64/elf_hwcaps.rst +++ b/Documentation/arm64/elf_hwcaps.rst @@ -204,6 +204,37 @@ HWCAP2_FRINT Functionality implied by ID_AA64ISAR1_EL1.FRINTTS == 0b0001. +HWCAP2_SVEI8MM + + Functionality implied by ID_AA64ZFR0_EL1.I8MM == 0b0001. + +HWCAP2_SVEF32MM + + Functionality implied by ID_AA64ZFR0_EL1.F32MM == 0b0001. + +HWCAP2_SVEF64MM + + Functionality implied by ID_AA64ZFR0_EL1.F64MM == 0b0001. + +HWCAP2_SVEBF16 + + Functionality implied by ID_AA64ZFR0_EL1.BF16 == 0b0001. + +HWCAP2_I8MM + + Functionality implied by ID_AA64ISAR1_EL1.I8MM == 0b0001. + +HWCAP2_BF16 + + Functionality implied by ID_AA64ISAR1_EL1.BF16 == 0b0001. + +HWCAP2_DGH + + Functionality implied by ID_AA64ISAR1_EL1.DGH == 0b0001. + +HWCAP2_RNG + + Functionality implied by ID_AA64ISAR0_EL1.RNDR == 0b0001. 4. Unused AT_HWCAP bits ----------------------- diff --git a/Documentation/arm64/memory.rst b/Documentation/arm64/memory.rst index 02e02175e6f5..cf03b3290800 100644 --- a/Documentation/arm64/memory.rst +++ b/Documentation/arm64/memory.rst @@ -129,7 +129,7 @@ this logic. As a single binary will need to support both 48-bit and 52-bit VA spaces, the VMEMMAP must be sized large enough for 52-bit VAs and -also must be sized large enought to accommodate a fixed PAGE_OFFSET. +also must be sized large enough to accommodate a fixed PAGE_OFFSET. Most code in the kernel should not need to consider the VA_BITS, for code that does need to know the VA size the variables are diff --git a/Documentation/arm64/silicon-errata.rst b/Documentation/arm64/silicon-errata.rst index 99b2545455ff..9120e59578dc 100644 --- a/Documentation/arm64/silicon-errata.rst +++ b/Documentation/arm64/silicon-errata.rst @@ -88,6 +88,8 @@ stable kernels. +----------------+-----------------+-----------------+-----------------------------+ | ARM | Cortex-A76 | #1463225 | ARM64_ERRATUM_1463225 | +----------------+-----------------+-----------------+-----------------------------+ +| ARM | Cortex-A55 | #1530923 | ARM64_ERRATUM_1530923 | ++----------------+-----------------+-----------------+-----------------------------+ | ARM | Neoverse-N1 | #1188873,1418040| ARM64_ERRATUM_1418040 | +----------------+-----------------+-----------------+-----------------------------+ | ARM | Neoverse-N1 | #1349291 | N/A | diff --git a/Documentation/arm64/tagged-address-abi.rst b/Documentation/arm64/tagged-address-abi.rst index d4a85d535bf9..4a9d9c794ee5 100644 --- a/Documentation/arm64/tagged-address-abi.rst +++ b/Documentation/arm64/tagged-address-abi.rst @@ -44,8 +44,15 @@ The AArch64 Tagged Address ABI has two stages of relaxation depending how the user addresses are used by the kernel: 1. User addresses not accessed by the kernel but used for address space - management (e.g. ``mmap()``, ``mprotect()``, ``madvise()``). The use - of valid tagged pointers in this context is always allowed. + management (e.g. ``mprotect()``, ``madvise()``). The use of valid + tagged pointers in this context is allowed with the exception of + ``brk()``, ``mmap()`` and the ``new_address`` argument to + ``mremap()`` as these have the potential to alias with existing + user addresses. + + NOTE: This behaviour changed in v5.6 and so some earlier kernels may + incorrectly accept valid tagged pointers for the ``brk()``, + ``mmap()`` and ``mremap()`` system calls. 2. User addresses accessed by the kernel (e.g. ``write()``). This ABI relaxation is disabled by default and the application thread needs to diff --git a/Documentation/asm-annotations.rst b/Documentation/asm-annotations.rst index f55c2bb74d00..32ea57483378 100644 --- a/Documentation/asm-annotations.rst +++ b/Documentation/asm-annotations.rst @@ -73,10 +73,11 @@ The new macros are prefixed with the ``SYM_`` prefix and can be divided into three main groups: 1. ``SYM_FUNC_*`` -- to annotate C-like functions. This means functions with - standard C calling conventions, i.e. the stack contains a return address at - the predefined place and a return from the function can happen in a - standard way. When frame pointers are enabled, save/restore of frame - pointer shall happen at the start/end of a function, respectively, too. + standard C calling conventions. For example, on x86, this means that the + stack contains a return address at the predefined place and a return from + the function can happen in a standard way. When frame pointers are enabled, + save/restore of frame pointer shall happen at the start/end of a function, + respectively, too. Checking tools like ``objtool`` should ensure such marked functions conform to these rules. The tools can also easily annotate these functions with diff --git a/Documentation/block/biovecs.rst b/Documentation/block/biovecs.rst index 86fa66c87172..ad303a2569d3 100644 --- a/Documentation/block/biovecs.rst +++ b/Documentation/block/biovecs.rst @@ -47,7 +47,7 @@ Having a real iterator, and making biovecs immutable, has a number of advantages: * Before, iterating over bios was very awkward when you weren't processing - exactly one bvec at a time - for example, bio_copy_data() in fs/bio.c, + exactly one bvec at a time - for example, bio_copy_data() in block/bio.c, which copies the contents of one bio into another. Because the biovecs wouldn't necessarily be the same size, the old code was tricky convoluted - it had to walk two different bios at the same time, keeping both bi_idx and diff --git a/Documentation/core-api/index.rst b/Documentation/core-api/index.rst index ab0eae1c153a..a501dc1c90d0 100644 --- a/Documentation/core-api/index.rst +++ b/Documentation/core-api/index.rst @@ -31,6 +31,7 @@ Core utilities generic-radix-tree memory-allocation mm-api + pin_user_pages gfp_mask-from-fs-io timekeeping boot-time-mm @@ -39,6 +40,8 @@ Core utilities ../RCU/index gcc-plugins symbol-namespaces + padata + ioctl Interfaces for kernel debugging diff --git a/Documentation/core-api/ioctl.rst b/Documentation/core-api/ioctl.rst new file mode 100644 index 000000000000..c455db0e1627 --- /dev/null +++ b/Documentation/core-api/ioctl.rst @@ -0,0 +1,253 @@ +====================== +ioctl based interfaces +====================== + +ioctl() is the most common way for applications to interface +with device drivers. It is flexible and easily extended by adding new +commands and can be passed through character devices, block devices as +well as sockets and other special file descriptors. + +However, it is also very easy to get ioctl command definitions wrong, +and hard to fix them later without breaking existing applications, +so this documentation tries to help developers get it right. + +Command number definitions +========================== + +The command number, or request number, is the second argument passed to +the ioctl system call. While this can be any 32-bit number that uniquely +identifies an action for a particular driver, there are a number of +conventions around defining them. + +``include/uapi/asm-generic/ioctl.h`` provides four macros for defining +ioctl commands that follow modern conventions: ``_IO``, ``_IOR``, +``_IOW``, and ``_IOWR``. These should be used for all new commands, +with the correct parameters: + +_IO/_IOR/_IOW/_IOWR + The macro name specifies how the argument will be used.  It may be a + pointer to data to be passed into the kernel (_IOW), out of the kernel + (_IOR), or both (_IOWR).  _IO can indicate either commands with no + argument or those passing an integer value instead of a pointer. + It is recommended to only use _IO for commands without arguments, + and use pointers for passing data. + +type + An 8-bit number, often a character literal, specific to a subsystem + or driver, and listed in :doc:`../userspace-api/ioctl/ioctl-number` + +nr + An 8-bit number identifying the specific command, unique for a give + value of 'type' + +data_type + The name of the data type pointed to by the argument, the command number + encodes the ``sizeof(data_type)`` value in a 13-bit or 14-bit integer, + leading to a limit of 8191 bytes for the maximum size of the argument. + Note: do not pass sizeof(data_type) type into _IOR/_IOW/IOWR, as that + will lead to encoding sizeof(sizeof(data_type)), i.e. sizeof(size_t). + _IO does not have a data_type parameter. + + +Interface versions +================== + +Some subsystems use version numbers in data structures to overload +commands with different interpretations of the argument. + +This is generally a bad idea, since changes to existing commands tend +to break existing applications. + +A better approach is to add a new ioctl command with a new number. The +old command still needs to be implemented in the kernel for compatibility, +but this can be a wrapper around the new implementation. + +Return code +=========== + +ioctl commands can return negative error codes as documented in errno(3); +these get turned into errno values in user space. On success, the return +code should be zero. It is also possible but not recommended to return +a positive 'long' value. + +When the ioctl callback is called with an unknown command number, the +handler returns either -ENOTTY or -ENOIOCTLCMD, which also results in +-ENOTTY being returned from the system call. Some subsystems return +-ENOSYS or -EINVAL here for historic reasons, but this is wrong. + +Prior to Linux 5.5, compat_ioctl handlers were required to return +-ENOIOCTLCMD in order to use the fallback conversion into native +commands. As all subsystems are now responsible for handling compat +mode themselves, this is no longer needed, but it may be important to +consider when backporting bug fixes to older kernels. + +Timestamps +========== + +Traditionally, timestamps and timeout values are passed as ``struct +timespec`` or ``struct timeval``, but these are problematic because of +incompatible definitions of these structures in user space after the +move to 64-bit time_t. + +The ``struct __kernel_timespec`` type can be used instead to be embedded +in other data structures when separate second/nanosecond values are +desired, or passed to user space directly. This is still not ideal though, +as the structure matches neither the kernel's timespec64 nor the user +space timespec exactly. The get_timespec64() and put_timespec64() helper +functions can be used to ensure that the layout remains compatible with +user space and the padding is treated correctly. + +As it is cheap to convert seconds to nanoseconds, but the opposite +requires an expensive 64-bit division, a simple __u64 nanosecond value +can be simpler and more efficient. + +Timeout values and timestamps should ideally use CLOCK_MONOTONIC time, +as returned by ktime_get_ns() or ktime_get_ts64(). Unlike +CLOCK_REALTIME, this makes the timestamps immune from jumping backwards +or forwards due to leap second adjustments and clock_settime() calls. + +ktime_get_real_ns() can be used for CLOCK_REALTIME timestamps that +need to be persistent across a reboot or between multiple machines. + +32-bit compat mode +================== + +In order to support 32-bit user space running on a 64-bit machine, each +subsystem or driver that implements an ioctl callback handler must also +implement the corresponding compat_ioctl handler. + +As long as all the rules for data structures are followed, this is as +easy as setting the .compat_ioctl pointer to a helper function such as +compat_ptr_ioctl() or blkdev_compat_ptr_ioctl(). + +compat_ptr() +------------ + +On the s390 architecture, 31-bit user space has ambiguous representations +for data pointers, with the upper bit being ignored. When running such +a process in compat mode, the compat_ptr() helper must be used to +clear the upper bit of a compat_uptr_t and turn it into a valid 64-bit +pointer. On other architectures, this macro only performs a cast to a +``void __user *`` pointer. + +In an compat_ioctl() callback, the last argument is an unsigned long, +which can be interpreted as either a pointer or a scalar depending on +the command. If it is a scalar, then compat_ptr() must not be used, to +ensure that the 64-bit kernel behaves the same way as a 32-bit kernel +for arguments with the upper bit set. + +The compat_ptr_ioctl() helper can be used in place of a custom +compat_ioctl file operation for drivers that only take arguments that +are pointers to compatible data structures. + +Structure layout +---------------- + +Compatible data structures have the same layout on all architectures, +avoiding all problematic members: + +* ``long`` and ``unsigned long`` are the size of a register, so + they can be either 32-bit or 64-bit wide and cannot be used in portable + data structures. Fixed-length replacements are ``__s32``, ``__u32``, + ``__s64`` and ``__u64``. + +* Pointers have the same problem, in addition to requiring the + use of compat_ptr(). The best workaround is to use ``__u64`` + in place of pointers, which requires a cast to ``uintptr_t`` in user + space, and the use of u64_to_user_ptr() in the kernel to convert + it back into a user pointer. + +* On the x86-32 (i386) architecture, the alignment of 64-bit variables + is only 32-bit, but they are naturally aligned on most other + architectures including x86-64. This means a structure like:: + + struct foo { + __u32 a; + __u64 b; + __u32 c; + }; + + has four bytes of padding between a and b on x86-64, plus another four + bytes of padding at the end, but no padding on i386, and it needs a + compat_ioctl conversion handler to translate between the two formats. + + To avoid this problem, all structures should have their members + naturally aligned, or explicit reserved fields added in place of the + implicit padding. The ``pahole`` tool can be used for checking the + alignment. + +* On ARM OABI user space, structures are padded to multiples of 32-bit, + making some structs incompatible with modern EABI kernels if they + do not end on a 32-bit boundary. + +* On the m68k architecture, struct members are not guaranteed to have an + alignment greater than 16-bit, which is a problem when relying on + implicit padding. + +* Bitfields and enums generally work as one would expect them to, + but some properties of them are implementation-defined, so it is better + to avoid them completely in ioctl interfaces. + +* ``char`` members can be either signed or unsigned, depending on + the architecture, so the __u8 and __s8 types should be used for 8-bit + integer values, though char arrays are clearer for fixed-length strings. + +Information leaks +================= + +Uninitialized data must not be copied back to user space, as this can +cause an information leak, which can be used to defeat kernel address +space layout randomization (KASLR), helping in an attack. + +For this reason (and for compat support) it is best to avoid any +implicit padding in data structures.  Where there is implicit padding +in an existing structure, kernel drivers must be careful to fully +initialize an instance of the structure before copying it to user +space.  This is usually done by calling memset() before assigning to +individual members. + +Subsystem abstractions +====================== + +While some device drivers implement their own ioctl function, most +subsystems implement the same command for multiple drivers. Ideally the +subsystem has an .ioctl() handler that copies the arguments from and +to user space, passing them into subsystem specific callback functions +through normal kernel pointers. + +This helps in various ways: + +* Applications written for one driver are more likely to work for + another one in the same subsystem if there are no subtle differences + in the user space ABI. + +* The complexity of user space access and data structure layout is done + in one place, reducing the potential for implementation bugs. + +* It is more likely to be reviewed by experienced developers + that can spot problems in the interface when the ioctl is shared + between multiple drivers than when it is only used in a single driver. + +Alternatives to ioctl +===================== + +There are many cases in which ioctl is not the best solution for a +problem. Alternatives include: + +* System calls are a better choice for a system-wide feature that + is not tied to a physical device or constrained by the file system + permissions of a character device node + +* netlink is the preferred way of configuring any network related + objects through sockets. + +* debugfs is used for ad-hoc interfaces for debugging functionality + that does not need to be exposed as a stable interface to applications. + +* sysfs is a good way to expose the state of an in-kernel object + that is not tied to a file descriptor. + +* configfs can be used for more complex configuration than sysfs + +* A custom file system can provide extra flexibility with a simple + user interface but adds a lot of complexity to the implementation. diff --git a/Documentation/core-api/padata.rst b/Documentation/core-api/padata.rst new file mode 100644 index 000000000000..9a24c111781d --- /dev/null +++ b/Documentation/core-api/padata.rst @@ -0,0 +1,169 @@ +.. SPDX-License-Identifier: GPL-2.0 + +======================================= +The padata parallel execution mechanism +======================================= + +:Date: December 2019 + +Padata is a mechanism by which the kernel can farm jobs out to be done in +parallel on multiple CPUs while retaining their ordering. It was developed for +use with the IPsec code, which needs to be able to perform encryption and +decryption on large numbers of packets without reordering those packets. The +crypto developers made a point of writing padata in a sufficiently general +fashion that it could be put to other uses as well. + +Usage +===== + +Initializing +------------ + +The first step in using padata is to set up a padata_instance structure for +overall control of how jobs are to be run:: + + #include <linux/padata.h> + + struct padata_instance *padata_alloc_possible(const char *name); + +'name' simply identifies the instance. + +There are functions for enabling and disabling the instance:: + + int padata_start(struct padata_instance *pinst); + void padata_stop(struct padata_instance *pinst); + +These functions are setting or clearing the "PADATA_INIT" flag; if that flag is +not set, other functions will refuse to work. padata_start() returns zero on +success (flag set) or -EINVAL if the padata cpumask contains no active CPU +(flag not set). padata_stop() clears the flag and blocks until the padata +instance is unused. + +Finally, complete padata initialization by allocating a padata_shell:: + + struct padata_shell *padata_alloc_shell(struct padata_instance *pinst); + +A padata_shell is used to submit a job to padata and allows a series of such +jobs to be serialized independently. A padata_instance may have one or more +padata_shells associated with it, each allowing a separate series of jobs. + +Modifying cpumasks +------------------ + +The CPUs used to run jobs can be changed in two ways, programatically with +padata_set_cpumask() or via sysfs. The former is defined:: + + int padata_set_cpumask(struct padata_instance *pinst, int cpumask_type, + cpumask_var_t cpumask); + +Here cpumask_type is one of PADATA_CPU_PARALLEL or PADATA_CPU_SERIAL, where a +parallel cpumask describes which processors will be used to execute jobs +submitted to this instance in parallel and a serial cpumask defines which +processors are allowed to be used as the serialization callback processor. +cpumask specifies the new cpumask to use. + +There may be sysfs files for an instance's cpumasks. For example, pcrypt's +live in /sys/kernel/pcrypt/<instance-name>. Within an instance's directory +there are two files, parallel_cpumask and serial_cpumask, and either cpumask +may be changed by echoing a bitmask into the file, for example:: + + echo f > /sys/kernel/pcrypt/pencrypt/parallel_cpumask + +Reading one of these files shows the user-supplied cpumask, which may be +different from the 'usable' cpumask. + +Padata maintains two pairs of cpumasks internally, the user-supplied cpumasks +and the 'usable' cpumasks. (Each pair consists of a parallel and a serial +cpumask.) The user-supplied cpumasks default to all possible CPUs on instance +allocation and may be changed as above. The usable cpumasks are always a +subset of the user-supplied cpumasks and contain only the online CPUs in the +user-supplied masks; these are the cpumasks padata actually uses. So it is +legal to supply a cpumask to padata that contains offline CPUs. Once an +offline CPU in the user-supplied cpumask comes online, padata is going to use +it. + +Changing the CPU masks are expensive operations, so it should not be done with +great frequency. + +Running A Job +------------- + +Actually submitting work to the padata instance requires the creation of a +padata_priv structure, which represents one job:: + + struct padata_priv { + /* Other stuff here... */ + void (*parallel)(struct padata_priv *padata); + void (*serial)(struct padata_priv *padata); + }; + +This structure will almost certainly be embedded within some larger +structure specific to the work to be done. Most of its fields are private to +padata, but the structure should be zeroed at initialisation time, and the +parallel() and serial() functions should be provided. Those functions will +be called in the process of getting the work done as we will see +momentarily. + +The submission of the job is done with:: + + int padata_do_parallel(struct padata_shell *ps, + struct padata_priv *padata, int *cb_cpu); + +The ps and padata structures must be set up as described above; cb_cpu +points to the preferred CPU to be used for the final callback when the job is +done; it must be in the current instance's CPU mask (if not the cb_cpu pointer +is updated to point to the CPU actually chosen). The return value from +padata_do_parallel() is zero on success, indicating that the job is in +progress. -EBUSY means that somebody, somewhere else is messing with the +instance's CPU mask, while -EINVAL is a complaint about cb_cpu not being in the +serial cpumask, no online CPUs in the parallel or serial cpumasks, or a stopped +instance. + +Each job submitted to padata_do_parallel() will, in turn, be passed to +exactly one call to the above-mentioned parallel() function, on one CPU, so +true parallelism is achieved by submitting multiple jobs. parallel() runs with +software interrupts disabled and thus cannot sleep. The parallel() +function gets the padata_priv structure pointer as its lone parameter; +information about the actual work to be done is probably obtained by using +container_of() to find the enclosing structure. + +Note that parallel() has no return value; the padata subsystem assumes that +parallel() will take responsibility for the job from this point. The job +need not be completed during this call, but, if parallel() leaves work +outstanding, it should be prepared to be called again with a new job before +the previous one completes. + +Serializing Jobs +---------------- + +When a job does complete, parallel() (or whatever function actually finishes +the work) should inform padata of the fact with a call to:: + + void padata_do_serial(struct padata_priv *padata); + +At some point in the future, padata_do_serial() will trigger a call to the +serial() function in the padata_priv structure. That call will happen on +the CPU requested in the initial call to padata_do_parallel(); it, too, is +run with local software interrupts disabled. +Note that this call may be deferred for a while since the padata code takes +pains to ensure that jobs are completed in the order in which they were +submitted. + +Destroying +---------- + +Cleaning up a padata instance predictably involves calling the three free +functions that correspond to the allocation in reverse:: + + void padata_free_shell(struct padata_shell *ps); + void padata_stop(struct padata_instance *pinst); + void padata_free(struct padata_instance *pinst); + +It is the user's responsibility to ensure all outstanding jobs are complete +before any of the above are called. + +Interface +========= + +.. kernel-doc:: include/linux/padata.h +.. kernel-doc:: kernel/padata.c diff --git a/Documentation/core-api/pin_user_pages.rst b/Documentation/core-api/pin_user_pages.rst new file mode 100644 index 000000000000..1d490155ecd7 --- /dev/null +++ b/Documentation/core-api/pin_user_pages.rst @@ -0,0 +1,232 @@ +.. SPDX-License-Identifier: GPL-2.0 + +==================================================== +pin_user_pages() and related calls +==================================================== + +.. contents:: :local: + +Overview +======== + +This document describes the following functions:: + + pin_user_pages() + pin_user_pages_fast() + pin_user_pages_remote() + +Basic description of FOLL_PIN +============================= + +FOLL_PIN and FOLL_LONGTERM are flags that can be passed to the get_user_pages*() +("gup") family of functions. FOLL_PIN has significant interactions and +interdependencies with FOLL_LONGTERM, so both are covered here. + +FOLL_PIN is internal to gup, meaning that it should not appear at the gup call +sites. This allows the associated wrapper functions (pin_user_pages*() and +others) to set the correct combination of these flags, and to check for problems +as well. + +FOLL_LONGTERM, on the other hand, *is* allowed to be set at the gup call sites. +This is in order to avoid creating a large number of wrapper functions to cover +all combinations of get*(), pin*(), FOLL_LONGTERM, and more. Also, the +pin_user_pages*() APIs are clearly distinct from the get_user_pages*() APIs, so +that's a natural dividing line, and a good point to make separate wrapper calls. +In other words, use pin_user_pages*() for DMA-pinned pages, and +get_user_pages*() for other cases. There are four cases described later on in +this document, to further clarify that concept. + +FOLL_PIN and FOLL_GET are mutually exclusive for a given gup call. However, +multiple threads and call sites are free to pin the same struct pages, via both +FOLL_PIN and FOLL_GET. It's just the call site that needs to choose one or the +other, not the struct page(s). + +The FOLL_PIN implementation is nearly the same as FOLL_GET, except that FOLL_PIN +uses a different reference counting technique. + +FOLL_PIN is a prerequisite to FOLL_LONGTERM. Another way of saying that is, +FOLL_LONGTERM is a specific case, more restrictive case of FOLL_PIN. + +Which flags are set by each wrapper +=================================== + +For these pin_user_pages*() functions, FOLL_PIN is OR'd in with whatever gup +flags the caller provides. The caller is required to pass in a non-null struct +pages* array, and the function then pin pages by incrementing each by a special +value. For now, that value is +1, just like get_user_pages*().:: + + Function + -------- + pin_user_pages FOLL_PIN is always set internally by this function. + pin_user_pages_fast FOLL_PIN is always set internally by this function. + pin_user_pages_remote FOLL_PIN is always set internally by this function. + +For these get_user_pages*() functions, FOLL_GET might not even be specified. +Behavior is a little more complex than above. If FOLL_GET was *not* specified, +but the caller passed in a non-null struct pages* array, then the function +sets FOLL_GET for you, and proceeds to pin pages by incrementing the refcount +of each page by +1.:: + + Function + -------- + get_user_pages FOLL_GET is sometimes set internally by this function. + get_user_pages_fast FOLL_GET is sometimes set internally by this function. + get_user_pages_remote FOLL_GET is sometimes set internally by this function. + +Tracking dma-pinned pages +========================= + +Some of the key design constraints, and solutions, for tracking dma-pinned +pages: + +* An actual reference count, per struct page, is required. This is because + multiple processes may pin and unpin a page. + +* False positives (reporting that a page is dma-pinned, when in fact it is not) + are acceptable, but false negatives are not. + +* struct page may not be increased in size for this, and all fields are already + used. + +* Given the above, we can overload the page->_refcount field by using, sort of, + the upper bits in that field for a dma-pinned count. "Sort of", means that, + rather than dividing page->_refcount into bit fields, we simple add a medium- + large value (GUP_PIN_COUNTING_BIAS, initially chosen to be 1024: 10 bits) to + page->_refcount. This provides fuzzy behavior: if a page has get_page() called + on it 1024 times, then it will appear to have a single dma-pinned count. + And again, that's acceptable. + +This also leads to limitations: there are only 31-10==21 bits available for a +counter that increments 10 bits at a time. + +TODO: for 1GB and larger huge pages, this is cutting it close. That's because +when pin_user_pages() follows such pages, it increments the head page by "1" +(where "1" used to mean "+1" for get_user_pages(), but now means "+1024" for +pin_user_pages()) for each tail page. So if you have a 1GB huge page: + +* There are 256K (18 bits) worth of 4 KB tail pages. +* There are 21 bits available to count up via GUP_PIN_COUNTING_BIAS (that is, + 10 bits at a time) +* There are 21 - 18 == 3 bits available to count. Except that there aren't, + because you need to allow for a few normal get_page() calls on the head page, + as well. Fortunately, the approach of using addition, rather than "hard" + bitfields, within page->_refcount, allows for sharing these bits gracefully. + But we're still looking at about 8 references. + +This, however, is a missing feature more than anything else, because it's easily +solved by addressing an obvious inefficiency in the original get_user_pages() +approach of retrieving pages: stop treating all the pages as if they were +PAGE_SIZE. Retrieve huge pages as huge pages. The callers need to be aware of +this, so some work is required. Once that's in place, this limitation mostly +disappears from view, because there will be ample refcounting range available. + +* Callers must specifically request "dma-pinned tracking of pages". In other + words, just calling get_user_pages() will not suffice; a new set of functions, + pin_user_page() and related, must be used. + +FOLL_PIN, FOLL_GET, FOLL_LONGTERM: when to use which flags +========================================================== + +Thanks to Jan Kara, Vlastimil Babka and several other -mm people, for describing +these categories: + +CASE 1: Direct IO (DIO) +----------------------- +There are GUP references to pages that are serving +as DIO buffers. These buffers are needed for a relatively short time (so they +are not "long term"). No special synchronization with page_mkclean() or +munmap() is provided. Therefore, flags to set at the call site are: :: + + FOLL_PIN + +...but rather than setting FOLL_PIN directly, call sites should use one of +the pin_user_pages*() routines that set FOLL_PIN. + +CASE 2: RDMA +------------ +There are GUP references to pages that are serving as DMA +buffers. These buffers are needed for a long time ("long term"). No special +synchronization with page_mkclean() or munmap() is provided. Therefore, flags +to set at the call site are: :: + + FOLL_PIN | FOLL_LONGTERM + +NOTE: Some pages, such as DAX pages, cannot be pinned with longterm pins. That's +because DAX pages do not have a separate page cache, and so "pinning" implies +locking down file system blocks, which is not (yet) supported in that way. + +CASE 3: Hardware with page faulting support +------------------------------------------- +Here, a well-written driver doesn't normally need to pin pages at all. However, +if the driver does choose to do so, it can register MMU notifiers for the range, +and will be called back upon invalidation. Either way (avoiding page pinning, or +using MMU notifiers to unpin upon request), there is proper synchronization with +both filesystem and mm (page_mkclean(), munmap(), etc). + +Therefore, neither flag needs to be set. + +In this case, ideally, neither get_user_pages() nor pin_user_pages() should be +called. Instead, the software should be written so that it does not pin pages. +This allows mm and filesystems to operate more efficiently and reliably. + +CASE 4: Pinning for struct page manipulation only +------------------------------------------------- +Here, normal GUP calls are sufficient, so neither flag needs to be set. + +page_dma_pinned(): the whole point of pinning +============================================= + +The whole point of marking pages as "DMA-pinned" or "gup-pinned" is to be able +to query, "is this page DMA-pinned?" That allows code such as page_mkclean() +(and file system writeback code in general) to make informed decisions about +what to do when a page cannot be unmapped due to such pins. + +What to do in those cases is the subject of a years-long series of discussions +and debates (see the References at the end of this document). It's a TODO item +here: fill in the details once that's worked out. Meanwhile, it's safe to say +that having this available: :: + + static inline bool page_dma_pinned(struct page *page) + +...is a prerequisite to solving the long-running gup+DMA problem. + +Another way of thinking about FOLL_GET, FOLL_PIN, and FOLL_LONGTERM +=================================================================== + +Another way of thinking about these flags is as a progression of restrictions: +FOLL_GET is for struct page manipulation, without affecting the data that the +struct page refers to. FOLL_PIN is a *replacement* for FOLL_GET, and is for +short term pins on pages whose data *will* get accessed. As such, FOLL_PIN is +a "more severe" form of pinning. And finally, FOLL_LONGTERM is an even more +restrictive case that has FOLL_PIN as a prerequisite: this is for pages that +will be pinned longterm, and whose data will be accessed. + +Unit testing +============ +This file:: + + tools/testing/selftests/vm/gup_benchmark.c + +has the following new calls to exercise the new pin*() wrapper functions: + +* PIN_FAST_BENCHMARK (./gup_benchmark -a) +* PIN_BENCHMARK (./gup_benchmark -b) + +You can monitor how many total dma-pinned pages have been acquired and released +since the system was booted, via two new /proc/vmstat entries: :: + + /proc/vmstat/nr_foll_pin_requested + /proc/vmstat/nr_foll_pin_requested + +Those are both going to show zero, unless CONFIG_DEBUG_VM is set. This is +because there is a noticeable performance drop in unpin_user_page(), when they +are activated. + +References +========== + +* `Some slow progress on get_user_pages() (Apr 2, 2019) <https://lwn.net/Articles/784574/>`_ +* `DMA and get_user_pages() (LPC: Dec 12, 2018) <https://lwn.net/Articles/774411/>`_ +* `The trouble with get_user_pages() (Apr 30, 2018) <https://lwn.net/Articles/753027/>`_ + +John Hubbard, October, 2019 diff --git a/Documentation/core-api/xarray.rst b/Documentation/core-api/xarray.rst index fcedc5349ace..640934b6f7b4 100644 --- a/Documentation/core-api/xarray.rst +++ b/Documentation/core-api/xarray.rst @@ -25,10 +25,6 @@ good performance with large indices. If your index can be larger than ``ULONG_MAX`` then the XArray is not the data type for you. The most important user of the XArray is the page cache. -Each non-``NULL`` entry in the array has three bits associated with -it called marks. Each mark may be set or cleared independently of -the others. You can iterate over entries which are marked. - Normal pointers may be stored in the XArray directly. They must be 4-byte aligned, which is true for any pointer returned from kmalloc() and alloc_page(). It isn't true for arbitrary user-space pointers, @@ -41,12 +37,11 @@ When you retrieve an entry from the XArray, you can check whether it is a value entry by calling xa_is_value(), and convert it back to an integer by calling xa_to_value(). -Some users want to store tagged pointers instead of using the marks -described above. They can call xa_tag_pointer() to create an -entry with a tag, xa_untag_pointer() to turn a tagged entry -back into an untagged pointer and xa_pointer_tag() to retrieve -the tag of an entry. Tagged pointers use the same bits that are used -to distinguish value entries from normal pointers, so each user must +Some users want to tag the pointers they store in the XArray. You can +call xa_tag_pointer() to create an entry with a tag, xa_untag_pointer() +to turn a tagged entry back into an untagged pointer and xa_pointer_tag() +to retrieve the tag of an entry. Tagged pointers use the same bits that +are used to distinguish value entries from normal pointers, so you must decide whether they want to store value entries or tagged pointers in any particular XArray. @@ -56,10 +51,9 @@ conflict with value entries or internal entries. An unusual feature of the XArray is the ability to create entries which occupy a range of indices. Once stored to, looking up any index in the range will return the same entry as looking up any other index in -the range. Setting a mark on one index will set it on all of them. -Storing to any index will store to all of them. Multi-index entries can -be explicitly split into smaller entries, or storing ``NULL`` into any -entry will cause the XArray to forget about the range. +the range. Storing to any index will store to all of them. Multi-index +entries can be explicitly split into smaller entries, or storing ``NULL`` +into any entry will cause the XArray to forget about the range. Normal API ========== @@ -87,17 +81,11 @@ If you want to only store a new entry to an index if the current entry at that index is ``NULL``, you can use xa_insert() which returns ``-EBUSY`` if the entry is not empty. -You can enquire whether a mark is set on an entry by using -xa_get_mark(). If the entry is not ``NULL``, you can set a mark -on it by using xa_set_mark() and remove the mark from an entry by -calling xa_clear_mark(). You can ask whether any entry in the -XArray has a particular mark set by calling xa_marked(). - You can copy entries out of the XArray into a plain array by calling -xa_extract(). Or you can iterate over the present entries in -the XArray by calling xa_for_each(). You may prefer to use -xa_find() or xa_find_after() to move to the next present -entry in the XArray. +xa_extract(). Or you can iterate over the present entries in the XArray +by calling xa_for_each(), xa_for_each_start() or xa_for_each_range(). +You may prefer to use xa_find() or xa_find_after() to move to the next +present entry in the XArray. Calling xa_store_range() stores the same entry in a range of indices. If you do this, some of the other operations will behave @@ -124,6 +112,31 @@ xa_destroy(). If the XArray entries are pointers, you may wish to free the entries first. You can do this by iterating over all present entries in the XArray using the xa_for_each() iterator. +Search Marks +------------ + +Each entry in the array has three bits associated with it called marks. +Each mark may be set or cleared independently of the others. You can +iterate over marked entries by using the xa_for_each_marked() iterator. + +You can enquire whether a mark is set on an entry by using +xa_get_mark(). If the entry is not ``NULL``, you can set a mark on it +by using xa_set_mark() and remove the mark from an entry by calling +xa_clear_mark(). You can ask whether any entry in the XArray has a +particular mark set by calling xa_marked(). Erasing an entry from the +XArray causes all marks associated with that entry to be cleared. + +Setting or clearing a mark on any index of a multi-index entry will +affect all indices covered by that entry. Querying the mark on any +index will return the same result. + +There is no way to iterate over entries which are not marked; the data +structure does not allow this to be implemented efficiently. There are +not currently iterators to search for logical combinations of bits (eg +iterate over all entries which have both ``XA_MARK_1`` and ``XA_MARK_2`` +set, or iterate over all entries which have ``XA_MARK_0`` or ``XA_MARK_2`` +set). It would be possible to add these if a user arises. + Allocating XArrays ------------------ @@ -180,6 +193,8 @@ No lock needed: Takes RCU read lock: * xa_load() * xa_for_each() + * xa_for_each_start() + * xa_for_each_range() * xa_find() * xa_find_after() * xa_extract() @@ -419,10 +434,9 @@ you last processed. If you have interrupts disabled while iterating, then it is good manners to pause the iteration and reenable interrupts every ``XA_CHECK_SCHED`` entries. -The xas_get_mark(), xas_set_mark() and -xas_clear_mark() functions require the xa_state cursor to have -been moved to the appropriate location in the xarray; they will do -nothing if you have called xas_pause() or xas_set() +The xas_get_mark(), xas_set_mark() and xas_clear_mark() functions require +the xa_state cursor to have been moved to the appropriate location in the +XArray; they will do nothing if you have called xas_pause() or xas_set() immediately before. You can call xas_set_update() to have a callback function diff --git a/Documentation/crypto/devel-algos.rst b/Documentation/crypto/devel-algos.rst index f9d288015acc..f225a953ab4b 100644 --- a/Documentation/crypto/devel-algos.rst +++ b/Documentation/crypto/devel-algos.rst @@ -31,33 +31,23 @@ The counterparts to those functions are listed below. :: - int crypto_unregister_alg(struct crypto_alg *alg); - int crypto_unregister_algs(struct crypto_alg *algs, int count); + void crypto_unregister_alg(struct crypto_alg *alg); + void crypto_unregister_algs(struct crypto_alg *algs, int count); -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 < 0 implies an error. +The registration functions return 0 on success, or a negative errno +value on failure. crypto_register_algs() succeeds only if it +successfully registered all the given algorithms; if it fails partway +through, then any changes are rolled back. -The bulk registration/unregistration functions register/unregister each -transformation in the given array of length count. They handle errors as -follows: - -- crypto_register_algs() succeeds if and only if it successfully - registers all the given transformations. If an error occurs partway - through, then it rolls back successful registrations before returning - the error code. Note that if a driver needs to handle registration - errors for individual transformations, then it will need to use the - non-bulk function crypto_register_alg() instead. - -- crypto_unregister_algs() tries to unregister all the given - transformations, continuing on error. It logs errors and always - returns zero. +The unregistration functions always succeed, so they don't have a +return value. Don't try to unregister algorithms that aren't +currently registered. Single-Block Symmetric Ciphers [CIPHER] --------------------------------------- -Example of transformations: aes, arc4, ... +Example of transformations: aes, serpent, ... This section describes the simplest of all transformation implementations, that being the CIPHER type used for symmetric ciphers. @@ -108,7 +98,7 @@ is also valid: Multi-Block Ciphers ------------------- -Example of transformations: cbc(aes), ecb(arc4), ... +Example of transformations: cbc(aes), chacha20, ... This section describes the multi-block cipher transformation implementations. The multi-block ciphers are used for transformations @@ -169,10 +159,10 @@ are as follows: :: - int crypto_unregister_ahash(struct ahash_alg *alg); + void 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); + void crypto_unregister_shash(struct shash_alg *alg); + void crypto_unregister_shashes(struct shash_alg *algs, int count); Cipher Definition With struct shash_alg and ahash_alg diff --git a/Documentation/dev-tools/kasan.rst b/Documentation/dev-tools/kasan.rst index e4d66e7c50de..c652d740735d 100644 --- a/Documentation/dev-tools/kasan.rst +++ b/Documentation/dev-tools/kasan.rst @@ -21,8 +21,8 @@ global variables yet. Tag-based KASAN is only supported in Clang and requires version 7.0.0 or later. -Currently generic KASAN is supported for the x86_64, arm64, xtensa and s390 -architectures, and tag-based KASAN is supported only for arm64. +Currently generic KASAN is supported for the x86_64, arm64, xtensa, s390 and +riscv architectures, and tag-based KASAN is supported only for arm64. Usage ----- diff --git a/Documentation/dev-tools/kunit/faq.rst b/Documentation/dev-tools/kunit/faq.rst index bf2095112d89..ea55b2467653 100644 --- a/Documentation/dev-tools/kunit/faq.rst +++ b/Documentation/dev-tools/kunit/faq.rst @@ -29,7 +29,8 @@ Yes, well, mostly. For the most part, the KUnit core framework (what you use to write the tests) can compile to any architecture; it compiles like just another part of the -kernel and runs when the kernel boots. However, there is some infrastructure, +kernel and runs when the kernel boots, or when built as a module, when the +module is loaded. However, there is some infrastructure, like the KUnit Wrapper (``tools/testing/kunit/kunit.py``) that does not support other architectures. diff --git a/Documentation/dev-tools/kunit/index.rst b/Documentation/dev-tools/kunit/index.rst index c60d760a0eed..d16a4d2c3a41 100644 --- a/Documentation/dev-tools/kunit/index.rst +++ b/Documentation/dev-tools/kunit/index.rst @@ -49,6 +49,9 @@ to a standalone program that can be run like any other program directly inside of a host operating system; to be clear, it does not require any virtualization support; it is just a regular program. +Alternatively, kunit and kunit tests can be built as modules and tests will +run when the test module is loaded. + KUnit is fast. Excluding build time, from invocation to completion KUnit can run several dozen tests in only 10 to 20 seconds; this might not sound like a big deal to some people, but having such fast and easy to run tests fundamentally diff --git a/Documentation/dev-tools/kunit/usage.rst b/Documentation/dev-tools/kunit/usage.rst index b9a065ab681e..607758a66a99 100644 --- a/Documentation/dev-tools/kunit/usage.rst +++ b/Documentation/dev-tools/kunit/usage.rst @@ -539,6 +539,23 @@ Interspersed in the kernel logs you might see the following: Congratulations, you just ran a KUnit test on the x86 architecture! +In a similar manner, kunit and kunit tests can also be built as modules, +so if you wanted to run tests in this way you might add the following config +options to your ``.config``: + +.. code-block:: none + + CONFIG_KUNIT=m + CONFIG_KUNIT_EXAMPLE_TEST=m + +Once the kernel is built and installed, a simple + +.. code-block:: bash + + modprobe example-test + +...will run the tests. + Writing new tests for other architectures ----------------------------------------- diff --git a/Documentation/devicetree/bindings/arm/amlogic.yaml b/Documentation/devicetree/bindings/arm/amlogic.yaml index c6a443352ef8..f74aba48cec1 100644 --- a/Documentation/devicetree/bindings/arm/amlogic.yaml +++ b/Documentation/devicetree/bindings/arm/amlogic.yaml @@ -59,6 +59,7 @@ properties: - friendlyarm,nanopi-k2 - hardkernel,odroid-c2 - nexbox,a95x + - videostrong,kii-pro - wetek,hub - wetek,play2 - const: amlogic,meson-gxbb @@ -104,6 +105,7 @@ properties: - enum: - amlogic,p230 - amlogic,p231 + - libretech,aml-s905d-pc - phicomm,n1 - const: amlogic,s905d - const: amlogic,meson-gxl @@ -115,6 +117,7 @@ properties: - amlogic,q201 - khadas,vim2 - kingnovel,r-box-pro + - libretech,aml-s912-pc - nexbox,a1 - tronsmart,vega-s96 - const: amlogic,s912 diff --git a/Documentation/devicetree/bindings/arm/arm-boards b/Documentation/devicetree/bindings/arm/arm-boards index b2a9f9f8430b..96b1dad58253 100644 --- a/Documentation/devicetree/bindings/arm/arm-boards +++ b/Documentation/devicetree/bindings/arm/arm-boards @@ -121,7 +121,7 @@ Required properties (in root node): Required nodes: - soc: some node of the RealView platforms must be the SoC - node that contain the SoC-specific devices, withe the compatible + node that contain the SoC-specific devices, with the compatible string set to one of these tuples: "arm,realview-eb-soc", "simple-bus" "arm,realview-pb1176-soc", "simple-bus" diff --git a/Documentation/devicetree/bindings/arm/atmel-at91.yaml b/Documentation/devicetree/bindings/arm/atmel-at91.yaml index 6dd8be401673..0357314076bc 100644 --- a/Documentation/devicetree/bindings/arm/atmel-at91.yaml +++ b/Documentation/devicetree/bindings/arm/atmel-at91.yaml @@ -37,6 +37,16 @@ properties: - items: - enum: + - overkiz,kizboxmini-base # Overkiz kizbox Mini Base Board + - overkiz,kizboxmini-mb # Overkiz kizbox Mini Mother Board + - overkiz,kizboxmini-rd # Overkiz kizbox Mini RailDIN + - overkiz,smartkiz # Overkiz SmartKiz Board + - const: atmel,at91sam9g25 + - const: atmel,at91sam9x5 + - const: atmel,at91sam9 + + - items: + - enum: - atmel,at91sam9g15 - atmel,at91sam9g25 - atmel,at91sam9g35 @@ -52,11 +62,32 @@ properties: - const: atmel,sama5d2 - const: atmel,sama5 + - description: Microchip SAMA5D27 WLSOM1 + items: + - const: microchip,sama5d27-wlsom1 + - const: atmel,sama5d27 + - const: atmel,sama5d2 + - const: atmel,sama5 + + - description: Microchip SAMA5D27 WLSOM1 Evaluation Kit + items: + - const: microchip,sama5d27-wlsom1-ek + - const: microchip,sama5d27-wlsom1 + - const: atmel,sama5d27 + - const: atmel,sama5d2 + - const: atmel,sama5 + - items: - const: atmel,sama5d27 - const: atmel,sama5d2 - const: atmel,sama5 + - description: SAM9X60-EK board + items: + - const: microchip,sam9x60ek + - const: microchip,sam9x60 + - const: atmel,at91sam9 + - description: Nattis v2 board with Natte v2 power board items: - const: axentia,nattis-2 diff --git a/Documentation/devicetree/bindings/arm/atmel-sysregs.txt b/Documentation/devicetree/bindings/arm/atmel-sysregs.txt index 9fbde401a090..62cd4e89817c 100644 --- a/Documentation/devicetree/bindings/arm/atmel-sysregs.txt +++ b/Documentation/devicetree/bindings/arm/atmel-sysregs.txt @@ -10,6 +10,12 @@ PIT Timer required properties: - interrupts: Should contain interrupt for the PIT which is the IRQ line shared across all System Controller members. +PIT64B Timer required properties: +- compatible: Should be "microchip,sam9x60-pit64b" +- reg: Should contain registers location and length +- interrupts: Should contain interrupt for PIT64B timer +- clocks: Should contain the available clock sources for PIT64B timer. + System Timer (ST) required properties: - compatible: Should be "atmel,at91rm9200-st", "syscon", "simple-mfd" - reg: Should contain registers location and length @@ -39,6 +45,7 @@ RAMC SDRAM/DDR Controller required properties: "atmel,at91sam9260-sdramc", "atmel,at91sam9g45-ddramc", "atmel,sama5d3-ddramc", + "microchip,sam9x60-ddramc" - reg: Should contain registers location and length Examples: diff --git a/Documentation/devicetree/bindings/arm/cpus.yaml b/Documentation/devicetree/bindings/arm/cpus.yaml index c23c24ff7575..7a9c3ce2dbef 100644 --- a/Documentation/devicetree/bindings/arm/cpus.yaml +++ b/Documentation/devicetree/bindings/arm/cpus.yaml @@ -242,6 +242,21 @@ properties: where voltage is in V, frequency is in MHz. + power-domains: + $ref: '/schemas/types.yaml#/definitions/phandle-array' + description: + List of phandles and PM domain specifiers, as defined by bindings of the + PM domain provider (see also ../power_domain.txt). + + power-domain-names: + $ref: '/schemas/types.yaml#/definitions/string-array' + description: + A list of power domain name strings sorted in the same order as the + power-domains property. + + For PSCI based platforms, the name corresponding to the index of the PSCI + PM domain provider, must be "psci". + qcom,saw: $ref: '/schemas/types.yaml#/definitions/phandle' description: | diff --git a/Documentation/devicetree/bindings/arm/fsl.yaml b/Documentation/devicetree/bindings/arm/fsl.yaml index f79683a628f0..a8e0b4a813ed 100644 --- a/Documentation/devicetree/bindings/arm/fsl.yaml +++ b/Documentation/devicetree/bindings/arm/fsl.yaml @@ -1,7 +1,7 @@ # SPDX-License-Identifier: GPL-2.0 %YAML 1.2 --- -$id: http://devicetree.org/schemas/bindings/arm/fsl.yaml# +$id: http://devicetree.org/schemas/arm/fsl.yaml# $schema: http://devicetree.org/meta-schemas/core.yaml# title: Freescale i.MX Platforms Device Tree Bindings @@ -128,6 +128,27 @@ properties: - variscite,dt6customboard - const: fsl,imx6q + - description: i.MX6Q Gateworks Ventana Boards + items: + - enum: + - gw,imx6q-gw51xx + - gw,imx6q-gw52xx + - gw,imx6q-gw53xx + - gw,imx6q-gw5400-a + - gw,imx6q-gw54xx + - gw,imx6q-gw551x + - gw,imx6q-gw552x + - gw,imx6q-gw553x + - gw,imx6q-gw560x + - gw,imx6q-gw5903 + - gw,imx6q-gw5904 + - gw,imx6q-gw5907 + - gw,imx6q-gw5910 + - gw,imx6q-gw5912 + - gw,imx6q-gw5913 + - const: gw,ventana + - const: fsl,imx6q + - description: i.MX6QP based Boards items: - enum: @@ -154,10 +175,31 @@ properties: - ysoft,imx6dl-yapp4-ursa # i.MX6 Solo Y Soft IOTA Ursa board - const: fsl,imx6dl + - description: i.MX6DL Gateworks Ventana Boards + items: + - enum: + - gw,imx6dl-gw51xx + - gw,imx6dl-gw52xx + - gw,imx6dl-gw53xx + - gw,imx6dl-gw54xx + - gw,imx6dl-gw551x + - gw,imx6dl-gw552x + - gw,imx6dl-gw553x + - gw,imx6dl-gw560x + - gw,imx6dl-gw5903 + - gw,imx6dl-gw5904 + - gw,imx6dl-gw5907 + - gw,imx6dl-gw5910 + - gw,imx6dl-gw5912 + - gw,imx6dl-gw5913 + - const: gw,ventana + - const: fsl,imx6dl + - description: i.MX6SL based Boards items: - enum: - fsl,imx6sl-evk # i.MX6 SoloLite EVK Board + - kobo,tolino-shine3 - const: fsl,imx6sl - description: i.MX6SLL based Boards @@ -172,6 +214,7 @@ properties: - enum: - fsl,imx6sx-sabreauto # i.MX6 SoloX Sabre Auto Board - fsl,imx6sx-sdb # i.MX6 SoloX SDB Board + - fsl,imx6sx-sdb-reva # i.MX6 SoloX SDB Rev-A Board - const: fsl,imx6sx - description: i.MX6UL based Boards @@ -239,6 +282,7 @@ properties: items: - enum: - fsl,imx7d-sdb # i.MX7 SabreSD Board + - fsl,imx7d-sdb-reva # i.MX7 SabreSD Rev-A Board - novtech,imx7d-meerkat96 # i.MX7 Meerkat96 Board - toradex,colibri-imx7d # Colibri iMX7 Dual Module - toradex,colibri-imx7d-emmc # Colibri iMX7 Dual 1GB (eMMC) Module @@ -263,6 +307,7 @@ properties: - description: i.MX7ULP based Boards items: - enum: + - ea,imx7ulp-com # i.MX7ULP Embedded Artists COM Board - fsl,imx7ulp-evk # i.MX7ULP Evaluation Kit - const: fsl,imx7ulp @@ -283,7 +328,9 @@ properties: items: - enum: - boundary,imx8mq-nitrogen8m # i.MX8MQ NITROGEN Board + - einfochips,imx8mq-thor96 # i.MX8MQ Thor96 Board - fsl,imx8mq-evk # i.MX8MQ EVK Board + - google,imx8mq-phanbell # Google Coral Edge TPU - purism,librem5-devkit # Purism Librem5 devkit - solidrun,hummingboard-pulse # SolidRun Hummingboard Pulse - technexion,pico-pi-imx8m # TechNexion PICO-PI-8M evk @@ -385,6 +432,13 @@ properties: - fsl,ls2088a-rdb - const: fsl,ls2088a + - description: LX2160A based Boards + items: + - enum: + - fsl,lx2160a-qds + - fsl,lx2160a-rdb + - const: fsl,lx2160a + - description: S32V234 based Boards items: - enum: diff --git a/Documentation/devicetree/bindings/arm/idle-states.txt b/Documentation/devicetree/bindings/arm/idle-states.txt deleted file mode 100644 index 771f5d20ae18..000000000000 --- a/Documentation/devicetree/bindings/arm/idle-states.txt +++ /dev/null @@ -1,706 +0,0 @@ -========================================== -ARM idle states binding description -========================================== - -========================================== -1 - Introduction -========================================== - -ARM systems contain HW capable of managing power consumption dynamically, -where cores can be put in different low-power states (ranging from simple -wfi to power gating) according to OS PM policies. The CPU states representing -the range of dynamic idle states that a processor can enter at run-time, can be -specified through device tree bindings representing the parameters required -to enter/exit specific idle states on a given processor. - -According to the Server Base System Architecture document (SBSA, [3]), the -power states an ARM CPU can be put into are identified by the following list: - -- Running -- Idle_standby -- Idle_retention -- Sleep -- Off - -The power states described in the SBSA document define the basic CPU states on -top of which ARM platforms implement power management schemes that allow an OS -PM implementation to put the processor in different idle states (which include -states listed above; "off" state is not an idle state since it does not have -wake-up capabilities, hence it is not considered in this document). - -Idle state parameters (e.g. entry latency) are platform specific and need to be -characterized with bindings that provide the required information to OS PM -code so that it can build the required tables and use them at runtime. - -The device tree binding definition for ARM idle states is the subject of this -document. - -=========================================== -2 - idle-states definitions -=========================================== - -Idle states are characterized for a specific system through a set of -timing and energy related properties, that underline the HW behaviour -triggered upon idle states entry and exit. - -The following diagram depicts the CPU execution phases and related timing -properties required to enter and exit an idle state: - -..__[EXEC]__|__[PREP]__|__[ENTRY]__|__[IDLE]__|__[EXIT]__|__[EXEC]__.. - | | | | | - - |<------ entry ------->| - | latency | - |<- exit ->| - | latency | - |<-------- min-residency -------->| - |<------- wakeup-latency ------->| - - Diagram 1: CPU idle state execution phases - -EXEC: Normal CPU execution. - -PREP: Preparation phase before committing the hardware to idle mode - like cache flushing. This is abortable on pending wake-up - event conditions. The abort latency is assumed to be negligible - (i.e. less than the ENTRY + EXIT duration). If aborted, CPU - goes back to EXEC. This phase is optional. If not abortable, - this should be included in the ENTRY phase instead. - -ENTRY: The hardware is committed to idle mode. This period must run - to completion up to IDLE before anything else can happen. - -IDLE: This is the actual energy-saving idle period. This may last - between 0 and infinite time, until a wake-up event occurs. - -EXIT: Period during which the CPU is brought back to operational - mode (EXEC). - -entry-latency: Worst case latency required to enter the idle state. The -exit-latency may be guaranteed only after entry-latency has passed. - -min-residency: Minimum period, including preparation and entry, for a given -idle state to be worthwhile energywise. - -wakeup-latency: Maximum delay between the signaling of a wake-up event and the -CPU being able to execute normal code again. If not specified, this is assumed -to be entry-latency + exit-latency. - -These timing parameters can be used by an OS in different circumstances. - -An idle CPU requires the expected min-residency time to select the most -appropriate idle state based on the expected expiry time of the next IRQ -(i.e. wake-up) that causes the CPU to return to the EXEC phase. - -An operating system scheduler may need to compute the shortest wake-up delay -for CPUs in the system by detecting how long will it take to get a CPU out -of an idle state, e.g.: - -wakeup-delay = exit-latency + max(entry-latency - (now - entry-timestamp), 0) - -In other words, the scheduler can make its scheduling decision by selecting -(e.g. waking-up) the CPU with the shortest wake-up delay. -The wake-up delay must take into account the entry latency if that period -has not expired. The abortable nature of the PREP period can be ignored -if it cannot be relied upon (e.g. the PREP deadline may occur much sooner than -the worst case since it depends on the CPU operating conditions, i.e. caches -state). - -An OS has to reliably probe the wakeup-latency since some devices can enforce -latency constraint guarantees to work properly, so the OS has to detect the -worst case wake-up latency it can incur if a CPU is allowed to enter an -idle state, and possibly to prevent that to guarantee reliable device -functioning. - -The min-residency time parameter deserves further explanation since it is -expressed in time units but must factor in energy consumption coefficients. - -The energy consumption of a cpu when it enters a power state can be roughly -characterised by the following graph: - - | - | - | - e | - n | /--- - e | /------ - r | /------ - g | /----- - y | /------ - | ---- - | /| - | / | - | / | - | / | - | / | - | / | - |/ | - -----|-------+---------------------------------- - 0| 1 time(ms) - - Graph 1: Energy vs time example - -The graph is split in two parts delimited by time 1ms on the X-axis. -The graph curve with X-axis values = { x | 0 < x < 1ms } has a steep slope -and denotes the energy costs incurred while entering and leaving the idle -state. -The graph curve in the area delimited by X-axis values = {x | x > 1ms } has -shallower slope and essentially represents the energy consumption of the idle -state. - -min-residency is defined for a given idle state as the minimum expected -residency time for a state (inclusive of preparation and entry) after -which choosing that state become the most energy efficient option. A good -way to visualise this, is by taking the same graph above and comparing some -states energy consumptions plots. - -For sake of simplicity, let's consider a system with two idle states IDLE1, -and IDLE2: - - | - | - | - | /-- IDLE1 - e | /--- - n | /---- - e | /--- - r | /-----/--------- IDLE2 - g | /-------/--------- - y | ------------ /---| - | / /---- | - | / /--- | - | / /---- | - | / /--- | - | --- | - | / | - | / | - |/ | time - ---/----------------------------+------------------------ - |IDLE1-energy < IDLE2-energy | IDLE2-energy < IDLE1-energy - | - IDLE2-min-residency - - Graph 2: idle states min-residency example - -In graph 2 above, that takes into account idle states entry/exit energy -costs, it is clear that if the idle state residency time (i.e. time till next -wake-up IRQ) is less than IDLE2-min-residency, IDLE1 is the better idle state -choice energywise. - -This is mainly down to the fact that IDLE1 entry/exit energy costs are lower -than IDLE2. - -However, the lower power consumption (i.e. shallower energy curve slope) of -idle state IDLE2 implies that after a suitable time, IDLE2 becomes more energy -efficient. - -The time at which IDLE2 becomes more energy efficient than IDLE1 (and other -shallower states in a system with multiple idle states) is defined -IDLE2-min-residency and corresponds to the time when energy consumption of -IDLE1 and IDLE2 states breaks even. - -The definitions provided in this section underpin the idle states -properties specification that is the subject of the following sections. - -=========================================== -3 - idle-states node -=========================================== - -ARM processor idle states are defined within the idle-states node, which is -a direct child of the cpus node [1] and provides a container where the -processor idle states, defined as device tree nodes, are listed. - -- idle-states node - - Usage: Optional - On ARM systems, it is a container of processor idle - states nodes. If the system does not provide CPU - power management capabilities, or the processor just - supports idle_standby, an idle-states node is not - required. - - Description: idle-states node is a container node, where its - subnodes describe the CPU idle states. - - Node name must be "idle-states". - - The idle-states node's parent node must be the cpus node. - - The idle-states node's child nodes can be: - - - one or more state nodes - - Any other configuration is considered invalid. - - An idle-states node defines the following properties: - - - entry-method - Value type: <stringlist> - Usage and definition depend on ARM architecture version. - # On ARM v8 64-bit this property is required and must - be: - - "psci" - # On ARM 32-bit systems this property is optional - -This assumes that the "enable-method" property is set to "psci" in the cpu -node[6] that is responsible for setting up CPU idle management in the OS -implementation. - -The nodes describing the idle states (state) can only be defined -within the idle-states node, any other configuration is considered invalid -and therefore must be ignored. - -=========================================== -4 - state node -=========================================== - -A state node represents an idle state description and must be defined as -follows: - -- state node - - Description: must be child of the idle-states node - - The state node name shall follow standard device tree naming - rules ([5], 2.2.1 "Node names"), in particular state nodes which - are siblings within a single common parent must be given a unique name. - - The idle state entered by executing the wfi instruction (idle_standby - SBSA,[3][4]) is considered standard on all ARM platforms and therefore - must not be listed. - - With the definitions provided above, the following list represents - the valid properties for a state node: - - - compatible - Usage: Required - Value type: <stringlist> - Definition: Must be "arm,idle-state". - - - local-timer-stop - Usage: See definition - Value type: <none> - Definition: if present the CPU local timer control logic is - lost on state entry, otherwise it is retained. - - - entry-latency-us - Usage: Required - Value type: <prop-encoded-array> - Definition: u32 value representing worst case latency in - microseconds required to enter the idle state. - - - exit-latency-us - Usage: Required - Value type: <prop-encoded-array> - Definition: u32 value representing worst case latency - in microseconds required to exit the idle state. - The exit-latency-us duration may be guaranteed - only after entry-latency-us has passed. - - - min-residency-us - Usage: Required - Value type: <prop-encoded-array> - Definition: u32 value representing minimum residency duration - in microseconds, inclusive of preparation and - entry, for this idle state to be considered - worthwhile energy wise (refer to section 2 of - this document for a complete description). - - - wakeup-latency-us: - Usage: Optional - Value type: <prop-encoded-array> - Definition: u32 value representing maximum delay between the - signaling of a wake-up event and the CPU being - able to execute normal code again. If omitted, - this is assumed to be equal to: - - entry-latency-us + exit-latency-us - - It is important to supply this value on systems - where the duration of PREP phase (see diagram 1, - section 2) is non-neglibigle. - In such systems entry-latency-us + exit-latency-us - will exceed wakeup-latency-us by this duration. - - - status: - Usage: Optional - Value type: <string> - Definition: A standard device tree property [5] that indicates - the operational status of an idle-state. - If present, it shall be: - "okay": to indicate that the idle state is - operational. - "disabled": to indicate that the idle state has - been disabled in firmware so it is not - operational. - If the property is not present the idle-state must - be considered operational. - - - idle-state-name: - Usage: Optional - Value type: <string> - Definition: A string used as a descriptive name for the idle - state. - - In addition to the properties listed above, a state node may require - additional properties specific to the entry-method defined in the - idle-states node. Please refer to the entry-method bindings - documentation for properties definitions. - -=========================================== -4 - Examples -=========================================== - -Example 1 (ARM 64-bit, 16-cpu system, PSCI enable-method): - -cpus { - #size-cells = <0>; - #address-cells = <2>; - - CPU0: cpu@0 { - device_type = "cpu"; - compatible = "arm,cortex-a57"; - reg = <0x0 0x0>; - enable-method = "psci"; - cpu-idle-states = <&CPU_RETENTION_0_0 &CPU_SLEEP_0_0 - &CLUSTER_RETENTION_0 &CLUSTER_SLEEP_0>; - }; - - CPU1: cpu@1 { - device_type = "cpu"; - compatible = "arm,cortex-a57"; - reg = <0x0 0x1>; - enable-method = "psci"; - cpu-idle-states = <&CPU_RETENTION_0_0 &CPU_SLEEP_0_0 - &CLUSTER_RETENTION_0 &CLUSTER_SLEEP_0>; - }; - - CPU2: cpu@100 { - device_type = "cpu"; - compatible = "arm,cortex-a57"; - reg = <0x0 0x100>; - enable-method = "psci"; - cpu-idle-states = <&CPU_RETENTION_0_0 &CPU_SLEEP_0_0 - &CLUSTER_RETENTION_0 &CLUSTER_SLEEP_0>; - }; - - CPU3: cpu@101 { - device_type = "cpu"; - compatible = "arm,cortex-a57"; - reg = <0x0 0x101>; - enable-method = "psci"; - cpu-idle-states = <&CPU_RETENTION_0_0 &CPU_SLEEP_0_0 - &CLUSTER_RETENTION_0 &CLUSTER_SLEEP_0>; - }; - - CPU4: cpu@10000 { - device_type = "cpu"; - compatible = "arm,cortex-a57"; - reg = <0x0 0x10000>; - enable-method = "psci"; - cpu-idle-states = <&CPU_RETENTION_0_0 &CPU_SLEEP_0_0 - &CLUSTER_RETENTION_0 &CLUSTER_SLEEP_0>; - }; - - CPU5: cpu@10001 { - device_type = "cpu"; - compatible = "arm,cortex-a57"; - reg = <0x0 0x10001>; - enable-method = "psci"; - cpu-idle-states = <&CPU_RETENTION_0_0 &CPU_SLEEP_0_0 - &CLUSTER_RETENTION_0 &CLUSTER_SLEEP_0>; - }; - - CPU6: cpu@10100 { - device_type = "cpu"; - compatible = "arm,cortex-a57"; - reg = <0x0 0x10100>; - enable-method = "psci"; - cpu-idle-states = <&CPU_RETENTION_0_0 &CPU_SLEEP_0_0 - &CLUSTER_RETENTION_0 &CLUSTER_SLEEP_0>; - }; - - CPU7: cpu@10101 { - device_type = "cpu"; - compatible = "arm,cortex-a57"; - reg = <0x0 0x10101>; - enable-method = "psci"; - cpu-idle-states = <&CPU_RETENTION_0_0 &CPU_SLEEP_0_0 - &CLUSTER_RETENTION_0 &CLUSTER_SLEEP_0>; - }; - - CPU8: cpu@100000000 { - device_type = "cpu"; - compatible = "arm,cortex-a53"; - reg = <0x1 0x0>; - enable-method = "psci"; - cpu-idle-states = <&CPU_RETENTION_1_0 &CPU_SLEEP_1_0 - &CLUSTER_RETENTION_1 &CLUSTER_SLEEP_1>; - }; - - CPU9: cpu@100000001 { - device_type = "cpu"; - compatible = "arm,cortex-a53"; - reg = <0x1 0x1>; - enable-method = "psci"; - cpu-idle-states = <&CPU_RETENTION_1_0 &CPU_SLEEP_1_0 - &CLUSTER_RETENTION_1 &CLUSTER_SLEEP_1>; - }; - - CPU10: cpu@100000100 { - device_type = "cpu"; - compatible = "arm,cortex-a53"; - reg = <0x1 0x100>; - enable-method = "psci"; - cpu-idle-states = <&CPU_RETENTION_1_0 &CPU_SLEEP_1_0 - &CLUSTER_RETENTION_1 &CLUSTER_SLEEP_1>; - }; - - CPU11: cpu@100000101 { - device_type = "cpu"; - compatible = "arm,cortex-a53"; - reg = <0x1 0x101>; - enable-method = "psci"; - cpu-idle-states = <&CPU_RETENTION_1_0 &CPU_SLEEP_1_0 - &CLUSTER_RETENTION_1 &CLUSTER_SLEEP_1>; - }; - - CPU12: cpu@100010000 { - device_type = "cpu"; - compatible = "arm,cortex-a53"; - reg = <0x1 0x10000>; - enable-method = "psci"; - cpu-idle-states = <&CPU_RETENTION_1_0 &CPU_SLEEP_1_0 - &CLUSTER_RETENTION_1 &CLUSTER_SLEEP_1>; - }; - - CPU13: cpu@100010001 { - device_type = "cpu"; - compatible = "arm,cortex-a53"; - reg = <0x1 0x10001>; - enable-method = "psci"; - cpu-idle-states = <&CPU_RETENTION_1_0 &CPU_SLEEP_1_0 - &CLUSTER_RETENTION_1 &CLUSTER_SLEEP_1>; - }; - - CPU14: cpu@100010100 { - device_type = "cpu"; - compatible = "arm,cortex-a53"; - reg = <0x1 0x10100>; - enable-method = "psci"; - cpu-idle-states = <&CPU_RETENTION_1_0 &CPU_SLEEP_1_0 - &CLUSTER_RETENTION_1 &CLUSTER_SLEEP_1>; - }; - - CPU15: cpu@100010101 { - device_type = "cpu"; - compatible = "arm,cortex-a53"; - reg = <0x1 0x10101>; - enable-method = "psci"; - cpu-idle-states = <&CPU_RETENTION_1_0 &CPU_SLEEP_1_0 - &CLUSTER_RETENTION_1 &CLUSTER_SLEEP_1>; - }; - - idle-states { - entry-method = "psci"; - - CPU_RETENTION_0_0: cpu-retention-0-0 { - compatible = "arm,idle-state"; - arm,psci-suspend-param = <0x0010000>; - entry-latency-us = <20>; - exit-latency-us = <40>; - min-residency-us = <80>; - }; - - CLUSTER_RETENTION_0: cluster-retention-0 { - compatible = "arm,idle-state"; - local-timer-stop; - arm,psci-suspend-param = <0x1010000>; - entry-latency-us = <50>; - exit-latency-us = <100>; - min-residency-us = <250>; - wakeup-latency-us = <130>; - }; - - CPU_SLEEP_0_0: cpu-sleep-0-0 { - compatible = "arm,idle-state"; - local-timer-stop; - arm,psci-suspend-param = <0x0010000>; - entry-latency-us = <250>; - exit-latency-us = <500>; - min-residency-us = <950>; - }; - - CLUSTER_SLEEP_0: cluster-sleep-0 { - compatible = "arm,idle-state"; - local-timer-stop; - arm,psci-suspend-param = <0x1010000>; - entry-latency-us = <600>; - exit-latency-us = <1100>; - min-residency-us = <2700>; - wakeup-latency-us = <1500>; - }; - - CPU_RETENTION_1_0: cpu-retention-1-0 { - compatible = "arm,idle-state"; - arm,psci-suspend-param = <0x0010000>; - entry-latency-us = <20>; - exit-latency-us = <40>; - min-residency-us = <90>; - }; - - CLUSTER_RETENTION_1: cluster-retention-1 { - compatible = "arm,idle-state"; - local-timer-stop; - arm,psci-suspend-param = <0x1010000>; - entry-latency-us = <50>; - exit-latency-us = <100>; - min-residency-us = <270>; - wakeup-latency-us = <100>; - }; - - CPU_SLEEP_1_0: cpu-sleep-1-0 { - compatible = "arm,idle-state"; - local-timer-stop; - arm,psci-suspend-param = <0x0010000>; - entry-latency-us = <70>; - exit-latency-us = <100>; - min-residency-us = <300>; - wakeup-latency-us = <150>; - }; - - CLUSTER_SLEEP_1: cluster-sleep-1 { - compatible = "arm,idle-state"; - local-timer-stop; - arm,psci-suspend-param = <0x1010000>; - entry-latency-us = <500>; - exit-latency-us = <1200>; - min-residency-us = <3500>; - wakeup-latency-us = <1300>; - }; - }; - -}; - -Example 2 (ARM 32-bit, 8-cpu system, two clusters): - -cpus { - #size-cells = <0>; - #address-cells = <1>; - - CPU0: cpu@0 { - device_type = "cpu"; - compatible = "arm,cortex-a15"; - reg = <0x0>; - cpu-idle-states = <&CPU_SLEEP_0_0 &CLUSTER_SLEEP_0>; - }; - - CPU1: cpu@1 { - device_type = "cpu"; - compatible = "arm,cortex-a15"; - reg = <0x1>; - cpu-idle-states = <&CPU_SLEEP_0_0 &CLUSTER_SLEEP_0>; - }; - - CPU2: cpu@2 { - device_type = "cpu"; - compatible = "arm,cortex-a15"; - reg = <0x2>; - cpu-idle-states = <&CPU_SLEEP_0_0 &CLUSTER_SLEEP_0>; - }; - - CPU3: cpu@3 { - device_type = "cpu"; - compatible = "arm,cortex-a15"; - reg = <0x3>; - cpu-idle-states = <&CPU_SLEEP_0_0 &CLUSTER_SLEEP_0>; - }; - - CPU4: cpu@100 { - device_type = "cpu"; - compatible = "arm,cortex-a7"; - reg = <0x100>; - cpu-idle-states = <&CPU_SLEEP_1_0 &CLUSTER_SLEEP_1>; - }; - - CPU5: cpu@101 { - device_type = "cpu"; - compatible = "arm,cortex-a7"; - reg = <0x101>; - cpu-idle-states = <&CPU_SLEEP_1_0 &CLUSTER_SLEEP_1>; - }; - - CPU6: cpu@102 { - device_type = "cpu"; - compatible = "arm,cortex-a7"; - reg = <0x102>; - cpu-idle-states = <&CPU_SLEEP_1_0 &CLUSTER_SLEEP_1>; - }; - - CPU7: cpu@103 { - device_type = "cpu"; - compatible = "arm,cortex-a7"; - reg = <0x103>; - cpu-idle-states = <&CPU_SLEEP_1_0 &CLUSTER_SLEEP_1>; - }; - - idle-states { - CPU_SLEEP_0_0: cpu-sleep-0-0 { - compatible = "arm,idle-state"; - local-timer-stop; - entry-latency-us = <200>; - exit-latency-us = <100>; - min-residency-us = <400>; - wakeup-latency-us = <250>; - }; - - CLUSTER_SLEEP_0: cluster-sleep-0 { - compatible = "arm,idle-state"; - local-timer-stop; - entry-latency-us = <500>; - exit-latency-us = <1500>; - min-residency-us = <2500>; - wakeup-latency-us = <1700>; - }; - - CPU_SLEEP_1_0: cpu-sleep-1-0 { - compatible = "arm,idle-state"; - local-timer-stop; - entry-latency-us = <300>; - exit-latency-us = <500>; - min-residency-us = <900>; - wakeup-latency-us = <600>; - }; - - CLUSTER_SLEEP_1: cluster-sleep-1 { - compatible = "arm,idle-state"; - local-timer-stop; - entry-latency-us = <800>; - exit-latency-us = <2000>; - min-residency-us = <6500>; - wakeup-latency-us = <2300>; - }; - }; - -}; - -=========================================== -5 - References -=========================================== - -[1] ARM Linux Kernel documentation - CPUs bindings - Documentation/devicetree/bindings/arm/cpus.yaml - -[2] ARM Linux Kernel documentation - PSCI bindings - Documentation/devicetree/bindings/arm/psci.yaml - -[3] ARM Server Base System Architecture (SBSA) - http://infocenter.arm.com/help/index.jsp - -[4] ARM Architecture Reference Manuals - http://infocenter.arm.com/help/index.jsp - -[5] Devicetree Specification - https://www.devicetree.org/specifications/ - -[6] ARM Linux Kernel documentation - Booting AArch64 Linux - Documentation/arm64/booting.rst diff --git a/Documentation/devicetree/bindings/arm/idle-states.yaml b/Documentation/devicetree/bindings/arm/idle-states.yaml new file mode 100644 index 000000000000..ea805c1e6b20 --- /dev/null +++ b/Documentation/devicetree/bindings/arm/idle-states.yaml @@ -0,0 +1,661 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/arm/idle-states.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: ARM idle states binding description + +maintainers: + - Lorenzo Pieralisi <lorenzo.pieralisi@arm.com> + +description: |+ + ========================================== + 1 - Introduction + ========================================== + + ARM systems contain HW capable of managing power consumption dynamically, + where cores can be put in different low-power states (ranging from simple wfi + to power gating) according to OS PM policies. The CPU states representing the + range of dynamic idle states that a processor can enter at run-time, can be + specified through device tree bindings representing the parameters required to + enter/exit specific idle states on a given processor. + + According to the Server Base System Architecture document (SBSA, [3]), the + power states an ARM CPU can be put into are identified by the following list: + + - Running + - Idle_standby + - Idle_retention + - Sleep + - Off + + The power states described in the SBSA document define the basic CPU states on + top of which ARM platforms implement power management schemes that allow an OS + PM implementation to put the processor in different idle states (which include + states listed above; "off" state is not an idle state since it does not have + wake-up capabilities, hence it is not considered in this document). + + Idle state parameters (e.g. entry latency) are platform specific and need to + be characterized with bindings that provide the required information to OS PM + code so that it can build the required tables and use them at runtime. + + The device tree binding definition for ARM idle states is the subject of this + document. + + =========================================== + 2 - idle-states definitions + =========================================== + + Idle states are characterized for a specific system through a set of + timing and energy related properties, that underline the HW behaviour + triggered upon idle states entry and exit. + + The following diagram depicts the CPU execution phases and related timing + properties required to enter and exit an idle state: + + ..__[EXEC]__|__[PREP]__|__[ENTRY]__|__[IDLE]__|__[EXIT]__|__[EXEC]__.. + | | | | | + + |<------ entry ------->| + | latency | + |<- exit ->| + | latency | + |<-------- min-residency -------->| + |<------- wakeup-latency ------->| + + Diagram 1: CPU idle state execution phases + + EXEC: Normal CPU execution. + + PREP: Preparation phase before committing the hardware to idle mode + like cache flushing. This is abortable on pending wake-up + event conditions. The abort latency is assumed to be negligible + (i.e. less than the ENTRY + EXIT duration). If aborted, CPU + goes back to EXEC. This phase is optional. If not abortable, + this should be included in the ENTRY phase instead. + + ENTRY: The hardware is committed to idle mode. This period must run + to completion up to IDLE before anything else can happen. + + IDLE: This is the actual energy-saving idle period. This may last + between 0 and infinite time, until a wake-up event occurs. + + EXIT: Period during which the CPU is brought back to operational + mode (EXEC). + + entry-latency: Worst case latency required to enter the idle state. The + exit-latency may be guaranteed only after entry-latency has passed. + + min-residency: Minimum period, including preparation and entry, for a given + idle state to be worthwhile energywise. + + wakeup-latency: Maximum delay between the signaling of a wake-up event and the + CPU being able to execute normal code again. If not specified, this is assumed + to be entry-latency + exit-latency. + + These timing parameters can be used by an OS in different circumstances. + + An idle CPU requires the expected min-residency time to select the most + appropriate idle state based on the expected expiry time of the next IRQ + (i.e. wake-up) that causes the CPU to return to the EXEC phase. + + An operating system scheduler may need to compute the shortest wake-up delay + for CPUs in the system by detecting how long will it take to get a CPU out + of an idle state, e.g.: + + wakeup-delay = exit-latency + max(entry-latency - (now - entry-timestamp), 0) + + In other words, the scheduler can make its scheduling decision by selecting + (e.g. waking-up) the CPU with the shortest wake-up delay. + The wake-up delay must take into account the entry latency if that period + has not expired. The abortable nature of the PREP period can be ignored + if it cannot be relied upon (e.g. the PREP deadline may occur much sooner than + the worst case since it depends on the CPU operating conditions, i.e. caches + state). + + An OS has to reliably probe the wakeup-latency since some devices can enforce + latency constraint guarantees to work properly, so the OS has to detect the + worst case wake-up latency it can incur if a CPU is allowed to enter an + idle state, and possibly to prevent that to guarantee reliable device + functioning. + + The min-residency time parameter deserves further explanation since it is + expressed in time units but must factor in energy consumption coefficients. + + The energy consumption of a cpu when it enters a power state can be roughly + characterised by the following graph: + + | + | + | + e | + n | /--- + e | /------ + r | /------ + g | /----- + y | /------ + | ---- + | /| + | / | + | / | + | / | + | / | + | / | + |/ | + -----|-------+---------------------------------- + 0| 1 time(ms) + + Graph 1: Energy vs time example + + The graph is split in two parts delimited by time 1ms on the X-axis. + The graph curve with X-axis values = { x | 0 < x < 1ms } has a steep slope + and denotes the energy costs incurred while entering and leaving the idle + state. + The graph curve in the area delimited by X-axis values = {x | x > 1ms } has + shallower slope and essentially represents the energy consumption of the idle + state. + + min-residency is defined for a given idle state as the minimum expected + residency time for a state (inclusive of preparation and entry) after + which choosing that state become the most energy efficient option. A good + way to visualise this, is by taking the same graph above and comparing some + states energy consumptions plots. + + For sake of simplicity, let's consider a system with two idle states IDLE1, + and IDLE2: + + | + | + | + | /-- IDLE1 + e | /--- + n | /---- + e | /--- + r | /-----/--------- IDLE2 + g | /-------/--------- + y | ------------ /---| + | / /---- | + | / /--- | + | / /---- | + | / /--- | + | --- | + | / | + | / | + |/ | time + ---/----------------------------+------------------------ + |IDLE1-energy < IDLE2-energy | IDLE2-energy < IDLE1-energy + | + IDLE2-min-residency + + Graph 2: idle states min-residency example + + In graph 2 above, that takes into account idle states entry/exit energy + costs, it is clear that if the idle state residency time (i.e. time till next + wake-up IRQ) is less than IDLE2-min-residency, IDLE1 is the better idle state + choice energywise. + + This is mainly down to the fact that IDLE1 entry/exit energy costs are lower + than IDLE2. + + However, the lower power consumption (i.e. shallower energy curve slope) of + idle state IDLE2 implies that after a suitable time, IDLE2 becomes more energy + efficient. + + The time at which IDLE2 becomes more energy efficient than IDLE1 (and other + shallower states in a system with multiple idle states) is defined + IDLE2-min-residency and corresponds to the time when energy consumption of + IDLE1 and IDLE2 states breaks even. + + The definitions provided in this section underpin the idle states + properties specification that is the subject of the following sections. + + =========================================== + 3 - idle-states node + =========================================== + + ARM processor idle states are defined within the idle-states node, which is + a direct child of the cpus node [1] and provides a container where the + processor idle states, defined as device tree nodes, are listed. + + On ARM systems, it is a container of processor idle states nodes. If the + system does not provide CPU power management capabilities, or the processor + just supports idle_standby, an idle-states node is not required. + + =========================================== + 4 - References + =========================================== + + [1] ARM Linux Kernel documentation - CPUs bindings + Documentation/devicetree/bindings/arm/cpus.yaml + + [2] ARM Linux Kernel documentation - PSCI bindings + Documentation/devicetree/bindings/arm/psci.yaml + + [3] ARM Server Base System Architecture (SBSA) + http://infocenter.arm.com/help/index.jsp + + [4] ARM Architecture Reference Manuals + http://infocenter.arm.com/help/index.jsp + + [6] ARM Linux Kernel documentation - Booting AArch64 Linux + Documentation/arm64/booting.rst + +properties: + $nodename: + const: idle-states + + entry-method: + description: | + Usage and definition depend on ARM architecture version. + + On ARM v8 64-bit this property is required. + On ARM 32-bit systems this property is optional + + This assumes that the "enable-method" property is set to "psci" in the cpu + node[6] that is responsible for setting up CPU idle management in the OS + implementation. + const: psci + +patternProperties: + "^(cpu|cluster)-": + type: object + description: | + Each state node represents an idle state description and must be defined + as follows. + + The idle state entered by executing the wfi instruction (idle_standby + SBSA,[3][4]) is considered standard on all ARM platforms and therefore + must not be listed. + + In addition to the properties listed above, a state node may require + additional properties specific to the entry-method defined in the + idle-states node. Please refer to the entry-method bindings + documentation for properties definitions. + + properties: + compatible: + const: arm,idle-state + + local-timer-stop: + description: + If present the CPU local timer control logic is + lost on state entry, otherwise it is retained. + type: boolean + + entry-latency-us: + description: + Worst case latency in microseconds required to enter the idle state. + + exit-latency-us: + description: + Worst case latency in microseconds required to exit the idle state. + The exit-latency-us duration may be guaranteed only after + entry-latency-us has passed. + + min-residency-us: + description: + Minimum residency duration in microseconds, inclusive of preparation + and entry, for this idle state to be considered worthwhile energy wise + (refer to section 2 of this document for a complete description). + + wakeup-latency-us: + description: | + Maximum delay between the signaling of a wake-up event and the CPU + being able to execute normal code again. If omitted, this is assumed + to be equal to: + + entry-latency-us + exit-latency-us + + It is important to supply this value on systems where the duration of + PREP phase (see diagram 1, section 2) is non-neglibigle. In such + systems entry-latency-us + exit-latency-us will exceed + wakeup-latency-us by this duration. + + idle-state-name: + $ref: /schemas/types.yaml#definitions/string + description: + A string used as a descriptive name for the idle state. + + required: + - compatible + - entry-latency-us + - exit-latency-us + - min-residency-us + +additionalProperties: false + +examples: + - | + + cpus { + #size-cells = <0>; + #address-cells = <2>; + + cpu@0 { + device_type = "cpu"; + compatible = "arm,cortex-a57"; + reg = <0x0 0x0>; + enable-method = "psci"; + cpu-idle-states = <&CPU_RETENTION_0_0 &CPU_SLEEP_0_0 + &CLUSTER_RETENTION_0 &CLUSTER_SLEEP_0>; + }; + + cpu@1 { + device_type = "cpu"; + compatible = "arm,cortex-a57"; + reg = <0x0 0x1>; + enable-method = "psci"; + cpu-idle-states = <&CPU_RETENTION_0_0 &CPU_SLEEP_0_0 + &CLUSTER_RETENTION_0 &CLUSTER_SLEEP_0>; + }; + + cpu@100 { + device_type = "cpu"; + compatible = "arm,cortex-a57"; + reg = <0x0 0x100>; + enable-method = "psci"; + cpu-idle-states = <&CPU_RETENTION_0_0 &CPU_SLEEP_0_0 + &CLUSTER_RETENTION_0 &CLUSTER_SLEEP_0>; + }; + + cpu@101 { + device_type = "cpu"; + compatible = "arm,cortex-a57"; + reg = <0x0 0x101>; + enable-method = "psci"; + cpu-idle-states = <&CPU_RETENTION_0_0 &CPU_SLEEP_0_0 + &CLUSTER_RETENTION_0 &CLUSTER_SLEEP_0>; + }; + + cpu@10000 { + device_type = "cpu"; + compatible = "arm,cortex-a57"; + reg = <0x0 0x10000>; + enable-method = "psci"; + cpu-idle-states = <&CPU_RETENTION_0_0 &CPU_SLEEP_0_0 + &CLUSTER_RETENTION_0 &CLUSTER_SLEEP_0>; + }; + + cpu@10001 { + device_type = "cpu"; + compatible = "arm,cortex-a57"; + reg = <0x0 0x10001>; + enable-method = "psci"; + cpu-idle-states = <&CPU_RETENTION_0_0 &CPU_SLEEP_0_0 + &CLUSTER_RETENTION_0 &CLUSTER_SLEEP_0>; + }; + + cpu@10100 { + device_type = "cpu"; + compatible = "arm,cortex-a57"; + reg = <0x0 0x10100>; + enable-method = "psci"; + cpu-idle-states = <&CPU_RETENTION_0_0 &CPU_SLEEP_0_0 + &CLUSTER_RETENTION_0 &CLUSTER_SLEEP_0>; + }; + + cpu@10101 { + device_type = "cpu"; + compatible = "arm,cortex-a57"; + reg = <0x0 0x10101>; + enable-method = "psci"; + cpu-idle-states = <&CPU_RETENTION_0_0 &CPU_SLEEP_0_0 + &CLUSTER_RETENTION_0 &CLUSTER_SLEEP_0>; + }; + + cpu@100000000 { + device_type = "cpu"; + compatible = "arm,cortex-a53"; + reg = <0x1 0x0>; + enable-method = "psci"; + cpu-idle-states = <&CPU_RETENTION_1_0 &CPU_SLEEP_1_0 + &CLUSTER_RETENTION_1 &CLUSTER_SLEEP_1>; + }; + + cpu@100000001 { + device_type = "cpu"; + compatible = "arm,cortex-a53"; + reg = <0x1 0x1>; + enable-method = "psci"; + cpu-idle-states = <&CPU_RETENTION_1_0 &CPU_SLEEP_1_0 + &CLUSTER_RETENTION_1 &CLUSTER_SLEEP_1>; + }; + + cpu@100000100 { + device_type = "cpu"; + compatible = "arm,cortex-a53"; + reg = <0x1 0x100>; + enable-method = "psci"; + cpu-idle-states = <&CPU_RETENTION_1_0 &CPU_SLEEP_1_0 + &CLUSTER_RETENTION_1 &CLUSTER_SLEEP_1>; + }; + + cpu@100000101 { + device_type = "cpu"; + compatible = "arm,cortex-a53"; + reg = <0x1 0x101>; + enable-method = "psci"; + cpu-idle-states = <&CPU_RETENTION_1_0 &CPU_SLEEP_1_0 + &CLUSTER_RETENTION_1 &CLUSTER_SLEEP_1>; + }; + + cpu@100010000 { + device_type = "cpu"; + compatible = "arm,cortex-a53"; + reg = <0x1 0x10000>; + enable-method = "psci"; + cpu-idle-states = <&CPU_RETENTION_1_0 &CPU_SLEEP_1_0 + &CLUSTER_RETENTION_1 &CLUSTER_SLEEP_1>; + }; + + cpu@100010001 { + device_type = "cpu"; + compatible = "arm,cortex-a53"; + reg = <0x1 0x10001>; + enable-method = "psci"; + cpu-idle-states = <&CPU_RETENTION_1_0 &CPU_SLEEP_1_0 + &CLUSTER_RETENTION_1 &CLUSTER_SLEEP_1>; + }; + + cpu@100010100 { + device_type = "cpu"; + compatible = "arm,cortex-a53"; + reg = <0x1 0x10100>; + enable-method = "psci"; + cpu-idle-states = <&CPU_RETENTION_1_0 &CPU_SLEEP_1_0 + &CLUSTER_RETENTION_1 &CLUSTER_SLEEP_1>; + }; + + cpu@100010101 { + device_type = "cpu"; + compatible = "arm,cortex-a53"; + reg = <0x1 0x10101>; + enable-method = "psci"; + cpu-idle-states = <&CPU_RETENTION_1_0 &CPU_SLEEP_1_0 + &CLUSTER_RETENTION_1 &CLUSTER_SLEEP_1>; + }; + + idle-states { + entry-method = "psci"; + + CPU_RETENTION_0_0: cpu-retention-0-0 { + compatible = "arm,idle-state"; + arm,psci-suspend-param = <0x0010000>; + entry-latency-us = <20>; + exit-latency-us = <40>; + min-residency-us = <80>; + }; + + CLUSTER_RETENTION_0: cluster-retention-0 { + compatible = "arm,idle-state"; + local-timer-stop; + arm,psci-suspend-param = <0x1010000>; + entry-latency-us = <50>; + exit-latency-us = <100>; + min-residency-us = <250>; + wakeup-latency-us = <130>; + }; + + CPU_SLEEP_0_0: cpu-sleep-0-0 { + compatible = "arm,idle-state"; + local-timer-stop; + arm,psci-suspend-param = <0x0010000>; + entry-latency-us = <250>; + exit-latency-us = <500>; + min-residency-us = <950>; + }; + + CLUSTER_SLEEP_0: cluster-sleep-0 { + compatible = "arm,idle-state"; + local-timer-stop; + arm,psci-suspend-param = <0x1010000>; + entry-latency-us = <600>; + exit-latency-us = <1100>; + min-residency-us = <2700>; + wakeup-latency-us = <1500>; + }; + + CPU_RETENTION_1_0: cpu-retention-1-0 { + compatible = "arm,idle-state"; + arm,psci-suspend-param = <0x0010000>; + entry-latency-us = <20>; + exit-latency-us = <40>; + min-residency-us = <90>; + }; + + CLUSTER_RETENTION_1: cluster-retention-1 { + compatible = "arm,idle-state"; + local-timer-stop; + arm,psci-suspend-param = <0x1010000>; + entry-latency-us = <50>; + exit-latency-us = <100>; + min-residency-us = <270>; + wakeup-latency-us = <100>; + }; + + CPU_SLEEP_1_0: cpu-sleep-1-0 { + compatible = "arm,idle-state"; + local-timer-stop; + arm,psci-suspend-param = <0x0010000>; + entry-latency-us = <70>; + exit-latency-us = <100>; + min-residency-us = <300>; + wakeup-latency-us = <150>; + }; + + CLUSTER_SLEEP_1: cluster-sleep-1 { + compatible = "arm,idle-state"; + local-timer-stop; + arm,psci-suspend-param = <0x1010000>; + entry-latency-us = <500>; + exit-latency-us = <1200>; + min-residency-us = <3500>; + wakeup-latency-us = <1300>; + }; + }; + }; + + - | + // Example 2 (ARM 32-bit, 8-cpu system, two clusters): + + cpus { + #size-cells = <0>; + #address-cells = <1>; + + cpu@0 { + device_type = "cpu"; + compatible = "arm,cortex-a15"; + reg = <0x0>; + cpu-idle-states = <&cpu_sleep_0_0 &cluster_sleep_0>; + }; + + cpu@1 { + device_type = "cpu"; + compatible = "arm,cortex-a15"; + reg = <0x1>; + cpu-idle-states = <&cpu_sleep_0_0 &cluster_sleep_0>; + }; + + cpu@2 { + device_type = "cpu"; + compatible = "arm,cortex-a15"; + reg = <0x2>; + cpu-idle-states = <&cpu_sleep_0_0 &cluster_sleep_0>; + }; + + cpu@3 { + device_type = "cpu"; + compatible = "arm,cortex-a15"; + reg = <0x3>; + cpu-idle-states = <&cpu_sleep_0_0 &cluster_sleep_0>; + }; + + cpu@100 { + device_type = "cpu"; + compatible = "arm,cortex-a7"; + reg = <0x100>; + cpu-idle-states = <&cpu_sleep_1_0 &cluster_sleep_1>; + }; + + cpu@101 { + device_type = "cpu"; + compatible = "arm,cortex-a7"; + reg = <0x101>; + cpu-idle-states = <&cpu_sleep_1_0 &cluster_sleep_1>; + }; + + cpu@102 { + device_type = "cpu"; + compatible = "arm,cortex-a7"; + reg = <0x102>; + cpu-idle-states = <&cpu_sleep_1_0 &cluster_sleep_1>; + }; + + cpu@103 { + device_type = "cpu"; + compatible = "arm,cortex-a7"; + reg = <0x103>; + cpu-idle-states = <&cpu_sleep_1_0 &cluster_sleep_1>; + }; + + idle-states { + cpu_sleep_0_0: cpu-sleep-0-0 { + compatible = "arm,idle-state"; + local-timer-stop; + entry-latency-us = <200>; + exit-latency-us = <100>; + min-residency-us = <400>; + wakeup-latency-us = <250>; + }; + + cluster_sleep_0: cluster-sleep-0 { + compatible = "arm,idle-state"; + local-timer-stop; + entry-latency-us = <500>; + exit-latency-us = <1500>; + min-residency-us = <2500>; + wakeup-latency-us = <1700>; + }; + + cpu_sleep_1_0: cpu-sleep-1-0 { + compatible = "arm,idle-state"; + local-timer-stop; + entry-latency-us = <300>; + exit-latency-us = <500>; + min-residency-us = <900>; + wakeup-latency-us = <600>; + }; + + cluster_sleep_1: cluster-sleep-1 { + compatible = "arm,idle-state"; + local-timer-stop; + entry-latency-us = <800>; + exit-latency-us = <2000>; + min-residency-us = <6500>; + wakeup-latency-us = <2300>; + }; + }; + }; + +... diff --git a/Documentation/devicetree/bindings/arm/msm/qcom,llcc.yaml b/Documentation/devicetree/bindings/arm/msm/qcom,llcc.yaml index 558749065b97..79902f470e4b 100644 --- a/Documentation/devicetree/bindings/arm/msm/qcom,llcc.yaml +++ b/Documentation/devicetree/bindings/arm/msm/qcom,llcc.yaml @@ -47,7 +47,7 @@ examples: - | #include <dt-bindings/interrupt-controller/arm-gic.h> - cache-controller@1100000 { + system-cache-controller@1100000 { compatible = "qcom,sdm845-llcc"; reg = <0x1100000 0x200000>, <0x1300000 0x50000> ; reg-names = "llcc_base", "llcc_broadcast_base"; diff --git a/Documentation/devicetree/bindings/arm/psci.yaml b/Documentation/devicetree/bindings/arm/psci.yaml index 7abdf58b335e..8ef85420b2ab 100644 --- a/Documentation/devicetree/bindings/arm/psci.yaml +++ b/Documentation/devicetree/bindings/arm/psci.yaml @@ -102,6 +102,34 @@ properties: [1] Kernel documentation - ARM idle states bindings Documentation/devicetree/bindings/arm/idle-states.txt + "#power-domain-cells": + description: + The number of cells in a PM domain specifier as per binding in [3]. + Must be 0 as to represent a single PM domain. + + ARM systems can have multiple cores, sometimes in an hierarchical + arrangement. This often, but not always, maps directly to the processor + power topology of the system. Individual nodes in a topology have their + own specific power states and can be better represented hierarchically. + + For these cases, the definitions of the idle states for the CPUs and the + CPU topology, must conform to the binding in [3]. The idle states + themselves must conform to the binding in [4] and must specify the + arm,psci-suspend-param property. + + It should also be noted that, in PSCI firmware v1.0 the OS-Initiated + (OSI) CPU suspend mode is introduced. Using a hierarchical representation + helps to implement support for OSI mode and OS implementations may choose + to mandate it. + + [3] Documentation/devicetree/bindings/power/power_domain.txt + [4] Documentation/devicetree/bindings/power/domain-idle-state.txt + + power-domains: + $ref: '/schemas/types.yaml#/definitions/phandle-array' + description: + List of phandles and PM domain specifiers, as defined by bindings of the + PM domain provider. required: - compatible @@ -160,4 +188,80 @@ examples: cpu_on = <0x95c10002>; cpu_off = <0x95c10001>; }; + + - |+ + + // Case 4: CPUs and CPU idle states described using the hierarchical model. + + cpus { + #size-cells = <0>; + #address-cells = <1>; + + CPU0: cpu@0 { + device_type = "cpu"; + compatible = "arm,cortex-a53", "arm,armv8"; + reg = <0x0>; + enable-method = "psci"; + power-domains = <&CPU_PD0>; + power-domain-names = "psci"; + }; + + CPU1: cpu@1 { + device_type = "cpu"; + compatible = "arm,cortex-a57", "arm,armv8"; + reg = <0x100>; + enable-method = "psci"; + power-domains = <&CPU_PD1>; + power-domain-names = "psci"; + }; + + idle-states { + + CPU_PWRDN: cpu-power-down { + compatible = "arm,idle-state"; + arm,psci-suspend-param = <0x0000001>; + entry-latency-us = <10>; + exit-latency-us = <10>; + min-residency-us = <100>; + }; + + CLUSTER_RET: cluster-retention { + compatible = "domain-idle-state"; + arm,psci-suspend-param = <0x1000011>; + entry-latency-us = <500>; + exit-latency-us = <500>; + min-residency-us = <2000>; + }; + + CLUSTER_PWRDN: cluster-power-down { + compatible = "domain-idle-state"; + arm,psci-suspend-param = <0x1000031>; + entry-latency-us = <2000>; + exit-latency-us = <2000>; + min-residency-us = <6000>; + }; + }; + }; + + psci { + compatible = "arm,psci-1.0"; + method = "smc"; + + CPU_PD0: cpu-pd0 { + #power-domain-cells = <0>; + domain-idle-states = <&CPU_PWRDN>; + power-domains = <&CLUSTER_PD>; + }; + + CPU_PD1: cpu-pd1 { + #power-domain-cells = <0>; + domain-idle-states = <&CPU_PWRDN>; + power-domains = <&CLUSTER_PD>; + }; + + CLUSTER_PD: cluster-pd { + #power-domain-cells = <0>; + domain-idle-states = <&CLUSTER_RET>, <&CLUSTER_PWRDN>; + }; + }; ... diff --git a/Documentation/devicetree/bindings/arm/qcom.yaml b/Documentation/devicetree/bindings/arm/qcom.yaml index e39d8f02e33c..5976c0b16b65 100644 --- a/Documentation/devicetree/bindings/arm/qcom.yaml +++ b/Documentation/devicetree/bindings/arm/qcom.yaml @@ -1,7 +1,7 @@ # SPDX-License-Identifier: GPL-2.0 %YAML 1.2 --- -$id: http://devicetree.org/schemas/bindings/arm/qcom.yaml# +$id: http://devicetree.org/schemas/arm/qcom.yaml# $schema: http://devicetree.org/meta-schemas/core.yaml# title: QCOM device tree bindings @@ -24,28 +24,30 @@ description: | The 'SoC' element must be one of the following strings: - apq8016 - apq8074 - apq8084 - apq8096 - msm8916 - msm8974 - msm8992 - msm8994 - msm8996 - mdm9615 - ipq8074 - sdm845 + apq8016 + apq8074 + apq8084 + apq8096 + ipq8074 + mdm9615 + msm8916 + msm8974 + msm8992 + msm8994 + msm8996 + sc7180 + sdm845 The 'board' element must be one of the following strings: - cdp - liquid - dragonboard - mtp - sbc - hk01 - qrd + cdp + dragonboard + hk01 + idp + liquid + mtp + qrd + sbc The 'soc_version' and 'board_version' elements take the form of v<Major>.<Minor> where the minor number may be omitted when it's zero, i.e. v1.0 is the same @@ -144,4 +146,8 @@ properties: - qcom,ipq8074-hk01 - const: qcom,ipq8074 + - items: + - enum: + - qcom,sc7180-idp + - const: qcom,sc7180 ... diff --git a/Documentation/devicetree/bindings/arm/rockchip.yaml b/Documentation/devicetree/bindings/arm/rockchip.yaml index d9847b306b83..874b0eaa2a75 100644 --- a/Documentation/devicetree/bindings/arm/rockchip.yaml +++ b/Documentation/devicetree/bindings/arm/rockchip.yaml @@ -409,6 +409,9 @@ properties: - description: Pine64 RockPro64 items: + - enum: + - pine64,rockpro64-v2.1 + - pine64,rockpro64-v2.0 - const: pine64,rockpro64 - const: rockchip,rk3399 @@ -422,6 +425,12 @@ properties: - const: radxa,rockpi4 - const: rockchip,rk3399 + - description: Radxa ROCK Pi N10 + items: + - const: radxa,rockpi-n10 + - const: vamrs,rk3399pro-vmarc-som + - const: rockchip,rk3399pro + - description: Radxa Rock2 Square items: - const: radxa,rock2-square diff --git a/Documentation/devicetree/bindings/arm/sprd.yaml b/Documentation/devicetree/bindings/arm/sprd/sprd.yaml index c35fb845ccaa..0258a96bfbde 100644 --- a/Documentation/devicetree/bindings/arm/sprd.yaml +++ b/Documentation/devicetree/bindings/arm/sprd/sprd.yaml @@ -2,7 +2,7 @@ # Copyright 2019 Unisoc Inc. %YAML 1.2 --- -$id: http://devicetree.org/schemas/arm/sprd.yaml# +$id: http://devicetree.org/schemas/arm/sprd/sprd.yaml# $schema: http://devicetree.org/meta-schemas/core.yaml# title: Unisoc platforms device tree bindings diff --git a/Documentation/devicetree/bindings/arm/stm32/mlahb.txt b/Documentation/devicetree/bindings/arm/stm32/mlahb.txt deleted file mode 100644 index 25307aa1eb9b..000000000000 --- a/Documentation/devicetree/bindings/arm/stm32/mlahb.txt +++ /dev/null @@ -1,37 +0,0 @@ -ML-AHB interconnect bindings - -These bindings describe the STM32 SoCs ML-AHB interconnect bus which connects -a Cortex-M subsystem with dedicated memories. -The MCU SRAM and RETRAM memory parts can be accessed through different addresses -(see "RAM aliases" in [1]) using different buses (see [2]) : balancing the -Cortex-M firmware accesses among those ports allows to tune the system -performance. - -[1]: https://www.st.com/resource/en/reference_manual/dm00327659.pdf -[2]: https://wiki.st.com/stm32mpu/wiki/STM32MP15_RAM_mapping - -Required properties: -- compatible: should be "simple-bus" -- dma-ranges: describes memory addresses translation between the local CPU and - the remote Cortex-M processor. Each memory region, is declared with - 3 parameters: - - param 1: device base address (Cortex-M processor address) - - param 2: physical base address (local CPU address) - - param 3: size of the memory region. - -The Cortex-M remote processor accessed via the mlahb interconnect is described -by a child node. - -Example: -mlahb { - compatible = "simple-bus"; - #address-cells = <1>; - #size-cells = <1>; - dma-ranges = <0x00000000 0x38000000 0x10000>, - <0x10000000 0x10000000 0x60000>, - <0x30000000 0x30000000 0x60000>; - - m4_rproc: m4@10000000 { - ... - }; -}; diff --git a/Documentation/devicetree/bindings/arm/stm32/st,mlahb.yaml b/Documentation/devicetree/bindings/arm/stm32/st,mlahb.yaml new file mode 100644 index 000000000000..68917bb7c7e8 --- /dev/null +++ b/Documentation/devicetree/bindings/arm/stm32/st,mlahb.yaml @@ -0,0 +1,70 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: "http://devicetree.org/schemas/arm/stm32/st,mlahb.yaml#" +$schema: "http://devicetree.org/meta-schemas/core.yaml#" + +title: STMicroelectronics STM32 ML-AHB interconnect bindings + +maintainers: + - Fabien Dessenne <fabien.dessenne@st.com> + - Arnaud Pouliquen <arnaud.pouliquen@st.com> + +description: | + These bindings describe the STM32 SoCs ML-AHB interconnect bus which connects + a Cortex-M subsystem with dedicated memories. The MCU SRAM and RETRAM memory + parts can be accessed through different addresses (see "RAM aliases" in [1]) + using different buses (see [2]): balancing the Cortex-M firmware accesses + among those ports allows to tune the system performance. + [1]: https://www.st.com/resource/en/reference_manual/dm00327659.pdf + [2]: https://wiki.st.com/stm32mpu/wiki/STM32MP15_RAM_mapping + +allOf: + - $ref: /schemas/simple-bus.yaml# + +properties: + compatible: + contains: + enum: + - st,mlahb + + dma-ranges: + description: | + Describe memory addresses translation between the local CPU and the + remote Cortex-M processor. Each memory region, is declared with + 3 parameters: + - param 1: device base address (Cortex-M processor address) + - param 2: physical base address (local CPU address) + - param 3: size of the memory region. + maxItems: 3 + + '#address-cells': + const: 1 + + '#size-cells': + const: 1 + +required: + - compatible + - '#address-cells' + - '#size-cells' + - dma-ranges + +examples: + - | + mlahb: ahb { + compatible = "st,mlahb", "simple-bus"; + #address-cells = <1>; + #size-cells = <1>; + reg = <0x10000000 0x40000>; + ranges; + dma-ranges = <0x00000000 0x38000000 0x10000>, + <0x10000000 0x10000000 0x60000>, + <0x30000000 0x30000000 0x60000>; + + m4_rproc: m4@10000000 { + reg = <0x10000000 0x40000>; + }; + }; + +... diff --git a/Documentation/devicetree/bindings/arm/stm32/st,stm32-syscon.yaml b/Documentation/devicetree/bindings/arm/stm32/st,stm32-syscon.yaml new file mode 100644 index 000000000000..0dedf94c8578 --- /dev/null +++ b/Documentation/devicetree/bindings/arm/stm32/st,stm32-syscon.yaml @@ -0,0 +1,41 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: "http://devicetree.org/schemas/arm/stm32/st,stm32-syscon.yaml#" +$schema: "http://devicetree.org/meta-schemas/core.yaml#" + +title: STMicroelectronics STM32 Platforms System Controller bindings + +maintainers: + - Alexandre Torgue <alexandre.torgue@st.com> + - Christophe Roullier <christophe.roullier@st.com> + +properties: + compatible: + oneOf: + - items: + - enum: + - st,stm32mp157-syscfg + - const: syscon + + reg: + maxItems: 1 + + clocks: + maxItems: 1 + +required: + - compatible + - reg + - clocks + +examples: + - | + #include <dt-bindings/clock/stm32mp1-clks.h> + syscfg: syscon@50020000 { + compatible = "st,stm32mp157-syscfg", "syscon"; + reg = <0x50020000 0x400>; + clocks = <&rcc SYSCFG>; + }; + +... diff --git a/Documentation/devicetree/bindings/arm/stm32/stm32-syscon.txt b/Documentation/devicetree/bindings/arm/stm32/stm32-syscon.txt deleted file mode 100644 index c92d411fd023..000000000000 --- a/Documentation/devicetree/bindings/arm/stm32/stm32-syscon.txt +++ /dev/null @@ -1,16 +0,0 @@ -STMicroelectronics STM32 Platforms System Controller - -Properties: - - compatible : should contain two values. First value must be : - - " st,stm32mp157-syscfg " - for stm32mp157 based SoCs, - second value must be always "syscon". - - reg : offset and length of the register set. - - clocks: phandle to the syscfg clock - - Example: - syscfg: syscon@50020000 { - compatible = "st,stm32mp157-syscfg", "syscon"; - reg = <0x50020000 0x400>; - clocks = <&rcc SYSCFG>; - }; - diff --git a/Documentation/devicetree/bindings/arm/sunxi.yaml b/Documentation/devicetree/bindings/arm/sunxi.yaml index cffe8bb0bad1..327ce6730823 100644 --- a/Documentation/devicetree/bindings/arm/sunxi.yaml +++ b/Documentation/devicetree/bindings/arm/sunxi.yaml @@ -342,6 +342,16 @@ properties: - const: libretech,all-h3-cc-h5 - const: allwinner,sun50i-h5 + - description: Libre Computer Board ALL-H3-IT H5 + items: + - const: libretech,all-h3-it-h5 + - const: allwinner,sun50i-h5 + + - description: Libre Computer Board ALL-H5-CC H5 + items: + - const: libretech,all-h5-cc-h5 + - const: allwinner,sun50i-h5 + - description: Lichee Pi One items: - const: licheepi,licheepi-one @@ -470,6 +480,12 @@ properties: - const: emlid,neutis-n5 - const: allwinner,sun50i-h5 + - description: Emlid Neutis N5H3 Developper Board + items: + - const: emlid,neutis-n5h3-devboard + - const: emlid,neutis-n5h3 + - const: allwinner,sun8i-h3 + - description: NextThing Co. CHIP items: - const: nextthing,chip @@ -599,11 +615,16 @@ properties: - const: pine64,pine64-plus - const: allwinner,sun50i-a64 - - description: Pine64 PineH64 + - description: Pine64 PineH64 model A items: - const: pine64,pine-h64 - const: allwinner,sun50i-h6 + - description: Pine64 PineH64 model B + items: + - const: pine64,pine-h64-model-b + - const: allwinner,sun50i-h6 + - description: Pine64 LTS items: - const: pine64,pine64-lts diff --git a/Documentation/devicetree/bindings/arm/sunxi/allwinner,sun4i-a10-mbus.yaml b/Documentation/devicetree/bindings/arm/sunxi/allwinner,sun4i-a10-mbus.yaml new file mode 100644 index 000000000000..9370e64992dd --- /dev/null +++ b/Documentation/devicetree/bindings/arm/sunxi/allwinner,sun4i-a10-mbus.yaml @@ -0,0 +1,65 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/arm/sunxi/allwinner,sun4i-a10-mbus.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Allwinner Memory Bus (MBUS) controller + +maintainers: + - Chen-Yu Tsai <wens@csie.org> + - Maxime Ripard <mripard@kernel.org> + +description: | + The MBUS controller drives the MBUS that other devices in the SoC + will use to perform DMA. It also has a register interface that + allows to monitor and control the bandwidth and priorities for + masters on that bus. + + Each device having to perform their DMA through the MBUS must have + the interconnects and interconnect-names properties set to the MBUS + controller and with "dma-mem" as the interconnect name. + +properties: + "#interconnect-cells": + const: 1 + description: + The content of the cell is the MBUS ID. + + compatible: + enum: + - allwinner,sun5i-a13-mbus + - allwinner,sun8i-h3-mbus + + reg: + maxItems: 1 + + clocks: + maxItems: 1 + + dma-ranges: + description: + See section 2.3.9 of the DeviceTree Specification. + +required: + - "#interconnect-cells" + - compatible + - reg + - clocks + - dma-ranges + +additionalProperties: false + +examples: + - | + #include <dt-bindings/clock/sun5i-ccu.h> + + mbus: dram-controller@1c01000 { + compatible = "allwinner,sun5i-a13-mbus"; + reg = <0x01c01000 0x1000>; + clocks = <&ccu CLK_MBUS>; + dma-ranges = <0x00000000 0x40000000 0x20000000>; + #interconnect-cells = <1>; + }; + +... diff --git a/Documentation/devicetree/bindings/arm/sunxi/sunxi-mbus.txt b/Documentation/devicetree/bindings/arm/sunxi/sunxi-mbus.txt deleted file mode 100644 index 2005bb486705..000000000000 --- a/Documentation/devicetree/bindings/arm/sunxi/sunxi-mbus.txt +++ /dev/null @@ -1,37 +0,0 @@ -Allwinner Memory Bus (MBUS) controller - -The MBUS controller drives the MBUS that other devices in the SoC will -use to perform DMA. It also has a register interface that allows to -monitor and control the bandwidth and priorities for masters on that -bus. - -Required properties: - - compatible: Must be one of: - - allwinner,sun5i-a13-mbus - - allwinner,sun8i-h3-mbus - - reg: Offset and length of the register set for the controller - - clocks: phandle to the clock driving the controller - - dma-ranges: See section 2.3.9 of the DeviceTree Specification - - #interconnect-cells: Must be one, with the argument being the MBUS - port ID - -Each device having to perform their DMA through the MBUS must have the -interconnects and interconnect-names properties set to the MBUS -controller and with "dma-mem" as the interconnect name. - -Example: - -mbus: dram-controller@1c01000 { - compatible = "allwinner,sun5i-a13-mbus"; - reg = <0x01c01000 0x1000>; - clocks = <&ccu CLK_MBUS>; - dma-ranges = <0x00000000 0x40000000 0x20000000>; - #interconnect-cells = <1>; -}; - -fe0: display-frontend@1e00000 { - compatible = "allwinner,sun5i-a13-display-frontend"; - ... - interconnects = <&mbus 19>; - interconnect-names = "dma-mem"; -}; diff --git a/Documentation/devicetree/bindings/arm/ux500.yaml b/Documentation/devicetree/bindings/arm/ux500.yaml new file mode 100644 index 000000000000..accaee906050 --- /dev/null +++ b/Documentation/devicetree/bindings/arm/ux500.yaml @@ -0,0 +1,36 @@ +# SPDX-License-Identifier: GPL-2.0-only +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/arm/ux500.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Ux500 platforms device tree bindings + +maintainers: + - Linus Walleij <linus.walleij@linaro.org> + +properties: + $nodename: + const: '/' + compatible: + oneOf: + + - description: ST-Ericsson HREF (pre-v60) + items: + - const: st-ericsson,mop500 + - const: st-ericsson,u8500 + + - description: ST-Ericsson HREF (v60+) + items: + - const: st-ericsson,hrefv60+ + - const: st-ericsson,u8500 + + - description: Calao Systems Snowball + items: + - const: calaosystems,snowball-a9500 + - const: st-ericsson,u9500 + + - description: Samsung Galaxy S III mini (GT-I8190) + items: + - const: samsung,golden + - const: st-ericsson,u8500 diff --git a/Documentation/devicetree/bindings/ata/ahci-platform.txt b/Documentation/devicetree/bindings/ata/ahci-platform.txt index 55c6fab1b373..77091a277642 100644 --- a/Documentation/devicetree/bindings/ata/ahci-platform.txt +++ b/Documentation/devicetree/bindings/ata/ahci-platform.txt @@ -9,8 +9,6 @@ PHYs. Required properties: - compatible : compatible string, one of: - - "allwinner,sun4i-a10-ahci" - - "allwinner,sun8i-r40-ahci" - "brcm,iproc-ahci" - "hisilicon,hisi-ahci" - "cavium,octeon-7130-ahci" @@ -45,8 +43,6 @@ Required properties when using sub-nodes: - #address-cells : number of cells to encode an address - #size-cells : number of cells representing the size of an address -For allwinner,sun8i-r40-ahci, the reset property must be present. - Sub-nodes required properties: - reg : the port number And at least one of the following properties: @@ -60,14 +56,6 @@ Examples: interrupts = <115>; }; - ahci: sata@1c18000 { - compatible = "allwinner,sun4i-a10-ahci"; - reg = <0x01c18000 0x1000>; - interrupts = <56>; - clocks = <&pll6 0>, <&ahb_gates 25>; - target-supply = <®_ahci_5v>; - }; - With sub-nodes: sata@f7e90000 { compatible = "marvell,berlin2q-achi", "generic-ahci"; diff --git a/Documentation/devicetree/bindings/ata/allwinner,sun4i-a10-ahci.yaml b/Documentation/devicetree/bindings/ata/allwinner,sun4i-a10-ahci.yaml new file mode 100644 index 000000000000..cb530b46beff --- /dev/null +++ b/Documentation/devicetree/bindings/ata/allwinner,sun4i-a10-ahci.yaml @@ -0,0 +1,47 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/ata/allwinner,sun4i-a10-ahci.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Allwinner A10 AHCI SATA Controller bindings + +maintainers: + - Chen-Yu Tsai <wens@csie.org> + - Maxime Ripard <mripard@kernel.org> + +properties: + compatible: + const: allwinner,sun4i-a10-ahci + + reg: + maxItems: 1 + + clocks: + items: + - description: AHCI Bus Clock + - description: AHCI Module Clock + + interrupts: + maxItems: 1 + + target-supply: + description: Regulator for SATA target power + +required: + - compatible + - reg + - clocks + - interrupts + +additionalProperties: false + +examples: + - | + ahci: sata@1c18000 { + compatible = "allwinner,sun4i-a10-ahci"; + reg = <0x01c18000 0x1000>; + interrupts = <56>; + clocks = <&pll6 0>, <&ahb_gates 25>; + target-supply = <®_ahci_5v>; + }; diff --git a/Documentation/devicetree/bindings/ata/allwinner,sun8i-r40-ahci.yaml b/Documentation/devicetree/bindings/ata/allwinner,sun8i-r40-ahci.yaml new file mode 100644 index 000000000000..e6b42a113ff1 --- /dev/null +++ b/Documentation/devicetree/bindings/ata/allwinner,sun8i-r40-ahci.yaml @@ -0,0 +1,67 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/ata/allwinner,sun8i-r40-ahci.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Allwinner R40 AHCI SATA Controller bindings + +maintainers: + - Chen-Yu Tsai <wens@csie.org> + - Maxime Ripard <mripard@kernel.org> + +properties: + compatible: + const: allwinner,sun8i-r40-ahci + + reg: + maxItems: 1 + + clocks: + items: + - description: AHCI Bus Clock + - description: AHCI Module Clock + + interrupts: + maxItems: 1 + + resets: + maxItems: 1 + + reset-names: + const: ahci + + ahci-supply: + description: Regulator for the AHCI controller + + phy-supply: + description: Regulator for the SATA PHY power + +required: + - compatible + - reg + - clocks + - interrupts + - resets + - reset-names + +additionalProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/arm-gic.h> + #include <dt-bindings/clock/sun8i-r40-ccu.h> + #include <dt-bindings/reset/sun8i-r40-ccu.h> + + ahci: sata@1c18000 { + compatible = "allwinner,sun8i-r40-ahci"; + reg = <0x01c18000 0x1000>; + interrupts = <GIC_SPI 56 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&ccu CLK_BUS_SATA>, <&ccu CLK_SATA>; + resets = <&ccu RST_BUS_SATA>; + reset-names = "ahci"; + ahci-supply = <®_dldo4>; + phy-supply = <®_eldo3>; + }; + +... diff --git a/Documentation/devicetree/bindings/ata/brcm,sata-brcm.txt b/Documentation/devicetree/bindings/ata/brcm,sata-brcm.txt index 7713a413c6a7..b9ae4ce4a0a0 100644 --- a/Documentation/devicetree/bindings/ata/brcm,sata-brcm.txt +++ b/Documentation/devicetree/bindings/ata/brcm,sata-brcm.txt @@ -5,6 +5,7 @@ Each SATA controller should have its own node. Required properties: - compatible : should be one or more of + "brcm,bcm7216-ahci" "brcm,bcm7425-ahci" "brcm,bcm7445-ahci" "brcm,bcm-nsp-ahci" @@ -14,6 +15,12 @@ Required properties: - reg-names : "ahci" and "top-ctrl" - interrupts : interrupt mapping for SATA IRQ +Optional properties: + +- reset: for "brcm,bcm7216-ahci" must be a valid reset phandle + pointing to the RESCAL reset controller provider node. +- reset-names: for "brcm,bcm7216-ahci", must be "rescal". + Also see ahci-platform.txt. Example: diff --git a/Documentation/devicetree/bindings/ata/faraday,ftide010.txt b/Documentation/devicetree/bindings/ata/faraday,ftide010.txt deleted file mode 100644 index a0c64a29104d..000000000000 --- a/Documentation/devicetree/bindings/ata/faraday,ftide010.txt +++ /dev/null @@ -1,38 +0,0 @@ -* Faraday Technology FTIDE010 PATA controller - -This controller is the first Faraday IDE interface block, used in the -StorLink SL2312 and SL3516, later known as the Cortina Systems Gemini -platform. The controller can do PIO modes 0 through 4, Multi-word DMA -(MWDM)modes 0 through 2 and Ultra DMA modes 0 through 6. - -On the Gemini platform, this PATA block is accompanied by a PATA to -SATA bridge in order to support SATA. This is why a phandle to that -controller is compulsory on that platform. - -The timing properties are unique per-SoC, not per-board. - -Required properties: -- compatible: should be one of - "cortina,gemini-pata", "faraday,ftide010" - "faraday,ftide010" -- interrupts: interrupt for the block -- reg: registers and size for the block - -Optional properties: -- clocks: a SoC clock running the peripheral. -- clock-names: should be set to "PCLK" for the peripheral clock. - -Required properties for "cortina,gemini-pata" compatible: -- sata: a phande to the Gemini PATA to SATA bridge, see - cortina,gemini-sata-bridge.txt for details. - -Example: - -ata@63000000 { - compatible = "cortina,gemini-pata", "faraday,ftide010"; - reg = <0x63000000 0x100>; - interrupts = <4 IRQ_TYPE_EDGE_RISING>; - clocks = <&gcc GEMINI_CLK_GATE_IDE>; - clock-names = "PCLK"; - sata = <&sata>; -}; diff --git a/Documentation/devicetree/bindings/ata/faraday,ftide010.yaml b/Documentation/devicetree/bindings/ata/faraday,ftide010.yaml new file mode 100644 index 000000000000..bfc6357476fd --- /dev/null +++ b/Documentation/devicetree/bindings/ata/faraday,ftide010.yaml @@ -0,0 +1,89 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/ata/faraday,ftide010.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Faraday Technology FTIDE010 PATA controller + +maintainers: + - Linus Walleij <linus.walleij@linaro.org> + +description: | + This controller is the first Faraday IDE interface block, used in the + StorLink SL3512 and SL3516, later known as the Cortina Systems Gemini + platform. The controller can do PIO modes 0 through 4, Multi-word DMA + (MWDM) modes 0 through 2 and Ultra DMA modes 0 through 6. + + On the Gemini platform, this PATA block is accompanied by a PATA to + SATA bridge in order to support SATA. This is why a phandle to that + controller is compulsory on that platform. + + The timing properties are unique per-SoC, not per-board. + +properties: + compatible: + oneOf: + - const: faraday,ftide010 + - items: + - const: cortina,gemini-pata + - const: faraday,ftide010 + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + clocks: + minItems: 1 + + clock-names: + const: PCLK + + sata: + description: + phandle to the Gemini PATA to SATA bridge, if available + $ref: /schemas/types.yaml#/definitions/phandle + +required: + - compatible + - reg + - interrupts + +allOf: + - $ref: pata-common.yaml# + + - if: + properties: + compatible: + contains: + const: cortina,gemini-pata + + then: + required: + - sata + +examples: + - | + #include <dt-bindings/interrupt-controller/irq.h> + #include <dt-bindings/clock/cortina,gemini-clock.h> + + ide@63000000 { + compatible = "cortina,gemini-pata", "faraday,ftide010"; + reg = <0x63000000 0x100>; + interrupts = <4 IRQ_TYPE_EDGE_RISING>; + clocks = <&gcc GEMINI_CLK_GATE_IDE>; + clock-names = "PCLK"; + sata = <&sata>; + #address-cells = <1>; + #size-cells = <0>; + ide-port@0 { + reg = <0>; + }; + ide-port@1 { + reg = <1>; + }; + }; + +... diff --git a/Documentation/devicetree/bindings/ata/pata-common.yaml b/Documentation/devicetree/bindings/ata/pata-common.yaml new file mode 100644 index 000000000000..fc5ebbe7108d --- /dev/null +++ b/Documentation/devicetree/bindings/ata/pata-common.yaml @@ -0,0 +1,50 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/ata/pata-common.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Common Properties for Parallel AT attachment (PATA) controllers + +maintainers: + - Linus Walleij <linus.walleij@linaro.org> + +description: | + This document defines device tree properties common to most Parallel + ATA (PATA, also known as IDE) AT attachment storage devices. + It doesn't constitue a device tree binding specification by itself but is + meant to be referenced by device tree bindings. + + The PATA (IDE) controller-specific device tree bindings are responsible for + defining whether each property is required or optional. + +properties: + $nodename: + pattern: "^ide(@.*)?$" + description: + Specifies the host controller node. PATA host controller nodes are named + "ide". + + "#address-cells": + const: 1 + + "#size-cells": + const: 0 + +patternProperties: + "^ide-port@[0-1]$": + description: | + DT nodes for ports connected on the PATA host. The master drive will have + ID number 0 and the slave drive will have ID number 1. The PATA port + nodes will be named "ide-port". + type: object + + properties: + reg: + minimum: 0 + maximum: 1 + description: + The ID number of the drive port, 0 for the master port and 1 for the + slave port. + +... diff --git a/Documentation/devicetree/bindings/ata/sata-common.yaml b/Documentation/devicetree/bindings/ata/sata-common.yaml new file mode 100644 index 000000000000..6783a4dec6b5 --- /dev/null +++ b/Documentation/devicetree/bindings/ata/sata-common.yaml @@ -0,0 +1,50 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/ata/sata-common.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Common Properties for Serial AT attachment (SATA) controllers + +maintainers: + - Linus Walleij <linus.walleij@linaro.org> + +description: | + This document defines device tree properties common to most Serial + AT attachment (SATA) storage devices. It doesn't constitute a device tree + binding specification by itself but is meant to be referenced by device + tree bindings. + + The SATA controller-specific device tree bindings are responsible for + defining whether each property is required or optional. + +properties: + $nodename: + pattern: "^sata(@.*)?$" + description: + Specifies the host controller node. SATA host controller nodes are named + "sata" + + "#address-cells": + const: 1 + + "#size-cells": + const: 0 + +patternProperties: + "^sata-port@[0-9a-e]$": + description: | + DT nodes for ports connected on the SATA host. The SATA port + nodes will be named "sata-port". + type: object + + properties: + reg: + minimum: 0 + maximum: 14 + description: + The ID number of the drive port SATA can potentially use a port + multiplier making it possible to connect up to 15 disks to a single + SATA port. + +... diff --git a/Documentation/devicetree/bindings/clock/allwinner,sun4i-a10-ahb-clk.yaml b/Documentation/devicetree/bindings/clock/allwinner,sun4i-a10-ahb-clk.yaml new file mode 100644 index 000000000000..558db4b6ed17 --- /dev/null +++ b/Documentation/devicetree/bindings/clock/allwinner,sun4i-a10-ahb-clk.yaml @@ -0,0 +1,108 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/clock/allwinner,sun4i-a10-ahb-clk.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Allwinner A10 AHB Clock Device Tree Bindings + +maintainers: + - Chen-Yu Tsai <wens@csie.org> + - Maxime Ripard <mripard@kernel.org> + +deprecated: true + +properties: + "#clock-cells": + const: 0 + + compatible: + enum: + - allwinner,sun4i-a10-ahb-clk + - allwinner,sun6i-a31-ahb1-clk + - allwinner,sun8i-h3-ahb2-clk + + reg: + maxItems: 1 + + clocks: + minItems: 1 + maxItems: 4 + description: > + The parent order must match the hardware programming order. + + clock-output-names: + maxItems: 1 + +required: + - "#clock-cells" + - compatible + - reg + - clocks + - clock-output-names + +additionalProperties: false + +allOf: + - if: + properties: + compatible: + contains: + const: allwinner,sun4i-a10-ahb-clk + + then: + properties: + clocks: + maxItems: 1 + + - if: + properties: + compatible: + contains: + const: allwinner,sun6i-a31-ahb1-clk + + then: + properties: + clocks: + maxItems: 4 + + - if: + properties: + compatible: + contains: + const: allwinner,sun8i-h3-ahb2-clk + + then: + properties: + clocks: + maxItems: 2 + +examples: + - | + ahb@1c20054 { + #clock-cells = <0>; + compatible = "allwinner,sun4i-a10-ahb-clk"; + reg = <0x01c20054 0x4>; + clocks = <&axi>; + clock-output-names = "ahb"; + }; + + - | + ahb1@1c20054 { + #clock-cells = <0>; + compatible = "allwinner,sun6i-a31-ahb1-clk"; + reg = <0x01c20054 0x4>; + clocks = <&osc32k>, <&osc24M>, <&axi>, <&pll6 0>; + clock-output-names = "ahb1"; + }; + + - | + ahb2_clk@1c2005c { + #clock-cells = <0>; + compatible = "allwinner,sun8i-h3-ahb2-clk"; + reg = <0x01c2005c 0x4>; + clocks = <&ahb1>, <&pll6d2>; + clock-output-names = "ahb2"; + }; + +... diff --git a/Documentation/devicetree/bindings/clock/allwinner,sun4i-a10-apb0-clk.yaml b/Documentation/devicetree/bindings/clock/allwinner,sun4i-a10-apb0-clk.yaml new file mode 100644 index 000000000000..b1e3d739beb2 --- /dev/null +++ b/Documentation/devicetree/bindings/clock/allwinner,sun4i-a10-apb0-clk.yaml @@ -0,0 +1,50 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/clock/allwinner,sun4i-a10-apb0-clk.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Allwinner A10 APB0 Bus Clock Device Tree Bindings + +maintainers: + - Chen-Yu Tsai <wens@csie.org> + - Maxime Ripard <mripard@kernel.org> + +deprecated: true + +properties: + "#clock-cells": + const: 0 + + compatible: + const: allwinner,sun4i-a10-apb0-clk + + reg: + maxItems: 1 + + clocks: + maxItems: 1 + + clock-output-names: + maxItems: 1 + +required: + - "#clock-cells" + - compatible + - reg + - clocks + - clock-output-names + +additionalProperties: false + +examples: + - | + apb0@1c20054 { + #clock-cells = <0>; + compatible = "allwinner,sun4i-a10-apb0-clk"; + reg = <0x01c20054 0x4>; + clocks = <&ahb>; + clock-output-names = "apb0"; + }; + +... diff --git a/Documentation/devicetree/bindings/clock/allwinner,sun4i-a10-apb1-clk.yaml b/Documentation/devicetree/bindings/clock/allwinner,sun4i-a10-apb1-clk.yaml new file mode 100644 index 000000000000..51b7a6d4ea54 --- /dev/null +++ b/Documentation/devicetree/bindings/clock/allwinner,sun4i-a10-apb1-clk.yaml @@ -0,0 +1,52 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/clock/allwinner,sun4i-a10-apb1-clk.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Allwinner A10 APB1 Bus Clock Device Tree Bindings + +maintainers: + - Chen-Yu Tsai <wens@csie.org> + - Maxime Ripard <mripard@kernel.org> + +deprecated: true + +properties: + "#clock-cells": + const: 0 + + compatible: + const: allwinner,sun4i-a10-apb1-clk + + reg: + maxItems: 1 + + clocks: + maxItems: 3 + description: > + The parent order must match the hardware programming order. + + clock-output-names: + maxItems: 1 + +required: + - "#clock-cells" + - compatible + - reg + - clocks + - clock-output-names + +additionalProperties: false + +examples: + - | + clk@1c20058 { + #clock-cells = <0>; + compatible = "allwinner,sun4i-a10-apb1-clk"; + reg = <0x01c20058 0x4>; + clocks = <&osc24M>, <&pll6 1>, <&osc32k>; + clock-output-names = "apb1"; + }; + +... diff --git a/Documentation/devicetree/bindings/clock/allwinner,sun4i-a10-axi-clk.yaml b/Documentation/devicetree/bindings/clock/allwinner,sun4i-a10-axi-clk.yaml new file mode 100644 index 000000000000..d801158e15de --- /dev/null +++ b/Documentation/devicetree/bindings/clock/allwinner,sun4i-a10-axi-clk.yaml @@ -0,0 +1,61 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/clock/allwinner,sun4i-a10-axi-clk.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Allwinner A10 AXI Clock Device Tree Bindings + +maintainers: + - Chen-Yu Tsai <wens@csie.org> + - Maxime Ripard <mripard@kernel.org> + +deprecated: true + +properties: + "#clock-cells": + const: 0 + + compatible: + enum: + - allwinner,sun4i-a10-axi-clk + - allwinner,sun8i-a23-axi-clk + + reg: + maxItems: 1 + + clocks: + maxItems: 1 + + clock-output-names: + maxItems: 1 + +required: + - "#clock-cells" + - compatible + - reg + - clocks + - clock-output-names + +additionalProperties: false + +examples: + - | + axi@1c20054 { + #clock-cells = <0>; + compatible = "allwinner,sun4i-a10-axi-clk"; + reg = <0x01c20054 0x4>; + clocks = <&cpu>; + clock-output-names = "axi"; + }; + + - | + axi_clk@1c20050 { + #clock-cells = <0>; + compatible = "allwinner,sun8i-a23-axi-clk"; + reg = <0x01c20050 0x4>; + clocks = <&cpu>; + clock-output-names = "axi"; + }; + +... diff --git a/Documentation/devicetree/bindings/clock/allwinner,sun4i-a10-cpu-clk.yaml b/Documentation/devicetree/bindings/clock/allwinner,sun4i-a10-cpu-clk.yaml new file mode 100644 index 000000000000..0dfafba1a168 --- /dev/null +++ b/Documentation/devicetree/bindings/clock/allwinner,sun4i-a10-cpu-clk.yaml @@ -0,0 +1,52 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/clock/allwinner,sun4i-a10-cpu-clk.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Allwinner A10 CPU Clock Device Tree Bindings + +maintainers: + - Chen-Yu Tsai <wens@csie.org> + - Maxime Ripard <mripard@kernel.org> + +deprecated: true + +properties: + "#clock-cells": + const: 0 + + compatible: + const: allwinner,sun4i-a10-cpu-clk + + reg: + maxItems: 1 + + clocks: + maxItems: 4 + description: > + The parent order must match the hardware programming order. + + clock-output-names: + maxItems: 1 + +required: + - "#clock-cells" + - compatible + - reg + - clocks + - clock-output-names + +additionalProperties: false + +examples: + - | + cpu@1c20054 { + #clock-cells = <0>; + compatible = "allwinner,sun4i-a10-cpu-clk"; + reg = <0x01c20054 0x4>; + clocks = <&osc32k>, <&osc24M>, <&pll1>, <&dummy>; + clock-output-names = "cpu"; + }; + +... diff --git a/Documentation/devicetree/bindings/clock/allwinner,sun4i-a10-display-clk.yaml b/Documentation/devicetree/bindings/clock/allwinner,sun4i-a10-display-clk.yaml new file mode 100644 index 000000000000..7484a7ab7dea --- /dev/null +++ b/Documentation/devicetree/bindings/clock/allwinner,sun4i-a10-display-clk.yaml @@ -0,0 +1,57 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/clock/allwinner,sun4i-a10-display-clk.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Allwinner A10 Display Clock Device Tree Bindings + +maintainers: + - Chen-Yu Tsai <wens@csie.org> + - Maxime Ripard <mripard@kernel.org> + +deprecated: true + +properties: + "#clock-cells": + const: 0 + + "#reset-cells": + const: 0 + + compatible: + const: allwinner,sun4i-a10-display-clk + + reg: + maxItems: 1 + + clocks: + maxItems: 3 + description: > + The parent order must match the hardware programming order. + + clock-output-names: + maxItems: 1 + +required: + - "#clock-cells" + - "#reset-cells" + - compatible + - reg + - clocks + - clock-output-names + +additionalProperties: false + +examples: + - | + clk@1c20104 { + #clock-cells = <0>; + #reset-cells = <0>; + compatible = "allwinner,sun4i-a10-display-clk"; + reg = <0x01c20104 0x4>; + clocks = <&pll3>, <&pll7>, <&pll5 1>; + clock-output-names = "de-be"; + }; + +... diff --git a/Documentation/devicetree/bindings/clock/allwinner,sun4i-a10-gates-clk.yaml b/Documentation/devicetree/bindings/clock/allwinner,sun4i-a10-gates-clk.yaml new file mode 100644 index 000000000000..ed1b2126a81b --- /dev/null +++ b/Documentation/devicetree/bindings/clock/allwinner,sun4i-a10-gates-clk.yaml @@ -0,0 +1,152 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/clock/allwinner,sun4i-a10-gates-clk.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Allwinner A10 Bus Gates Clock Device Tree Bindings + +maintainers: + - Chen-Yu Tsai <wens@csie.org> + - Maxime Ripard <mripard@kernel.org> + +deprecated: true + +properties: + "#clock-cells": + const: 1 + description: > + This additional argument passed to that clock is the offset of + the bit controlling this particular gate in the register. + + compatible: + oneOf: + - const: allwinner,sun4i-a10-gates-clk + - const: allwinner,sun4i-a10-axi-gates-clk + - const: allwinner,sun4i-a10-ahb-gates-clk + - const: allwinner,sun5i-a10s-ahb-gates-clk + - const: allwinner,sun5i-a13-ahb-gates-clk + - const: allwinner,sun7i-a20-ahb-gates-clk + - const: allwinner,sun6i-a31-ahb1-gates-clk + - const: allwinner,sun8i-a23-ahb1-gates-clk + - const: allwinner,sun9i-a80-ahb0-gates-clk + - const: allwinner,sun9i-a80-ahb1-gates-clk + - const: allwinner,sun9i-a80-ahb2-gates-clk + - const: allwinner,sun4i-a10-apb0-gates-clk + - const: allwinner,sun5i-a10s-apb0-gates-clk + - const: allwinner,sun5i-a13-apb0-gates-clk + - const: allwinner,sun7i-a20-apb0-gates-clk + - const: allwinner,sun9i-a80-apb0-gates-clk + - const: allwinner,sun8i-a83t-apb0-gates-clk + - const: allwinner,sun4i-a10-apb1-gates-clk + - const: allwinner,sun5i-a13-apb1-gates-clk + - const: allwinner,sun5i-a10s-apb1-gates-clk + - const: allwinner,sun6i-a31-apb1-gates-clk + - const: allwinner,sun7i-a20-apb1-gates-clk + - const: allwinner,sun8i-a23-apb1-gates-clk + - const: allwinner,sun9i-a80-apb1-gates-clk + - const: allwinner,sun6i-a31-apb2-gates-clk + - const: allwinner,sun8i-a23-apb2-gates-clk + - const: allwinner,sun8i-a83t-bus-gates-clk + - const: allwinner,sun9i-a80-apbs-gates-clk + - const: allwinner,sun4i-a10-dram-gates-clk + + - items: + - const: allwinner,sun5i-a13-dram-gates-clk + - const: allwinner,sun4i-a10-gates-clk + + - items: + - const: allwinner,sun8i-h3-apb0-gates-clk + - const: allwinner,sun4i-a10-gates-clk + + reg: + maxItems: 1 + + clocks: + maxItems: 1 + + clock-indices: + minItems: 1 + maxItems: 64 + + clock-output-names: + minItems: 1 + maxItems: 64 + +required: + - "#clock-cells" + - compatible + - reg + - clocks + - clock-indices + - clock-output-names + +additionalProperties: false + +examples: + - | + clk@1c2005c { + #clock-cells = <1>; + compatible = "allwinner,sun4i-a10-axi-gates-clk"; + reg = <0x01c2005c 0x4>; + clocks = <&axi>; + clock-indices = <0>; + clock-output-names = "axi_dram"; + }; + + - | + clk@1c20060 { + #clock-cells = <1>; + compatible = "allwinner,sun4i-a10-ahb-gates-clk"; + reg = <0x01c20060 0x8>; + clocks = <&ahb>; + clock-indices = <0>, <1>, + <2>, <3>, + <4>, <5>, <6>, + <7>, <8>, <9>, + <10>, <11>, <12>, + <13>, <14>, <16>, + <17>, <18>, <20>, + <21>, <22>, <23>, + <24>, <25>, <26>, + <32>, <33>, <34>, + <35>, <36>, <37>, + <40>, <41>, <43>, + <44>, <45>, + <46>, <47>, + <50>, <52>; + clock-output-names = "ahb_usb0", "ahb_ehci0", + "ahb_ohci0", "ahb_ehci1", + "ahb_ohci1", "ahb_ss", "ahb_dma", + "ahb_bist", "ahb_mmc0", "ahb_mmc1", + "ahb_mmc2", "ahb_mmc3", "ahb_ms", + "ahb_nand", "ahb_sdram", "ahb_ace", + "ahb_emac", "ahb_ts", "ahb_spi0", + "ahb_spi1", "ahb_spi2", "ahb_spi3", + "ahb_pata", "ahb_sata", "ahb_gps", + "ahb_ve", "ahb_tvd", "ahb_tve0", + "ahb_tve1", "ahb_lcd0", "ahb_lcd1", + "ahb_csi0", "ahb_csi1", "ahb_hdmi", + "ahb_de_be0", "ahb_de_be1", + "ahb_de_fe0", "ahb_de_fe1", + "ahb_mp", "ahb_mali400"; + }; + + + - | + clk@1c20068 { + #clock-cells = <1>; + compatible = "allwinner,sun4i-a10-apb0-gates-clk"; + reg = <0x01c20068 0x4>; + clocks = <&apb0>; + clock-indices = <0>, <1>, + <2>, <3>, + <5>, <6>, + <7>, <10>; + clock-output-names = "apb0_codec", "apb0_spdif", + "apb0_ac97", "apb0_iis", + "apb0_pio", "apb0_ir0", + "apb0_ir1", "apb0_keypad"; + }; + +... diff --git a/Documentation/devicetree/bindings/clock/allwinner,sun4i-a10-mbus-clk.yaml b/Documentation/devicetree/bindings/clock/allwinner,sun4i-a10-mbus-clk.yaml new file mode 100644 index 000000000000..18f131e262b4 --- /dev/null +++ b/Documentation/devicetree/bindings/clock/allwinner,sun4i-a10-mbus-clk.yaml @@ -0,0 +1,63 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/clock/allwinner,sun4i-a10-mbus-clk.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Allwinner A10 MBUS Clock Device Tree Bindings + +maintainers: + - Chen-Yu Tsai <wens@csie.org> + - Maxime Ripard <mripard@kernel.org> + +deprecated: true + +properties: + "#clock-cells": + const: 0 + + compatible: + enum: + - allwinner,sun5i-a13-mbus-clk + - allwinner,sun8i-a23-mbus-clk + + reg: + maxItems: 1 + + clocks: + maxItems: 3 + description: > + The parent order must match the hardware programming order. + + clock-output-names: + maxItems: 1 + +required: + - "#clock-cells" + - compatible + - reg + - clocks + - clock-output-names + +additionalProperties: false + +examples: + - | + clk@1c2015c { + #clock-cells = <0>; + compatible = "allwinner,sun5i-a13-mbus-clk"; + reg = <0x01c2015c 0x4>; + clocks = <&osc24M>, <&pll6 1>, <&pll5 1>; + clock-output-names = "mbus"; + }; + + - | + clk@1c2015c { + #clock-cells = <0>; + compatible = "allwinner,sun8i-a23-mbus-clk"; + reg = <0x01c2015c 0x4>; + clocks = <&osc24M>, <&pll6 1>, <&pll5>; + clock-output-names = "mbus"; + }; + +... diff --git a/Documentation/devicetree/bindings/clock/allwinner,sun4i-a10-mmc-clk.yaml b/Documentation/devicetree/bindings/clock/allwinner,sun4i-a10-mmc-clk.yaml new file mode 100644 index 000000000000..5199285a661a --- /dev/null +++ b/Documentation/devicetree/bindings/clock/allwinner,sun4i-a10-mmc-clk.yaml @@ -0,0 +1,87 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/clock/allwinner,sun4i-a10-mmc-clk.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Allwinner A10 Module 1 Clock Device Tree Bindings + +maintainers: + - Chen-Yu Tsai <wens@csie.org> + - Maxime Ripard <mripard@kernel.org> + +deprecated: true + +properties: + "#clock-cells": + const: 1 + description: > + There is three different outputs: the main clock, with the ID 0, + and the output and sample clocks, with the IDs 1 and 2, + respectively. + + compatible: + enum: + - allwinner,sun4i-a10-mmc-clk + - allwinner,sun9i-a80-mmc-clk + + reg: + maxItems: 1 + + clocks: + minItems: 2 + maxItems: 3 + description: > + The parent order must match the hardware programming order. + + clock-output-names: + maxItems: 3 + +required: + - "#clock-cells" + - compatible + - reg + - clocks + - clock-output-names + +additionalProperties: false + +if: + properties: + compatible: + contains: + const: allwinner,sun4i-a10-mmc-clk + +then: + properties: + clocks: + maxItems: 3 + +else: + properties: + clocks: + maxItems: 2 + +examples: + - | + clk@1c20088 { + #clock-cells = <1>; + compatible = "allwinner,sun4i-a10-mmc-clk"; + reg = <0x01c20088 0x4>; + clocks = <&osc24M>, <&pll6 1>, <&pll5 1>; + clock-output-names = "mmc0", + "mmc0_output", + "mmc0_sample"; + }; + + - | + clk@6000410 { + #clock-cells = <1>; + compatible = "allwinner,sun9i-a80-mmc-clk"; + reg = <0x06000410 0x4>; + clocks = <&osc24M>, <&pll4>; + clock-output-names = "mmc0", "mmc0_output", + "mmc0_sample"; + }; + +... diff --git a/Documentation/devicetree/bindings/clock/allwinner,sun4i-a10-mod0-clk.yaml b/Documentation/devicetree/bindings/clock/allwinner,sun4i-a10-mod0-clk.yaml new file mode 100644 index 000000000000..3e2abe3e67c1 --- /dev/null +++ b/Documentation/devicetree/bindings/clock/allwinner,sun4i-a10-mod0-clk.yaml @@ -0,0 +1,80 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/clock/allwinner,sun4i-a10-mod0-clk.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Allwinner A10 Module 0 Clock Device Tree Bindings + +maintainers: + - Chen-Yu Tsai <wens@csie.org> + - Maxime Ripard <mripard@kernel.org> + +deprecated: true + +select: + properties: + compatible: + contains: + enum: + - allwinner,sun4i-a10-mod0-clk + - allwinner,sun9i-a80-mod0-clk + + # The PRCM on the A31 and A23 will have the reg property missing, + # since it's set at the upper level node, and will be validated by + # PRCM's schema. Make sure we only validate standalone nodes. + required: + - compatible + - reg + +properties: + "#clock-cells": + const: 0 + + compatible: + enum: + - allwinner,sun4i-a10-mod0-clk + - allwinner,sun9i-a80-mod0-clk + + reg: + maxItems: 1 + + clocks: + # On the A80, the PRCM mod0 clocks have 2 parents. + minItems: 2 + maxItems: 3 + description: > + The parent order must match the hardware programming order. + + clock-output-names: + maxItems: 1 + +required: + - "#clock-cells" + - compatible + - reg + - clocks + - clock-output-names + +additionalProperties: false + +examples: + - | + clk@1c20080 { + #clock-cells = <0>; + compatible = "allwinner,sun4i-a10-mod0-clk"; + reg = <0x01c20080 0x4>; + clocks = <&osc24M>, <&pll6 1>, <&pll5 1>; + clock-output-names = "nand"; + }; + + - | + clk@8001454 { + #clock-cells = <0>; + compatible = "allwinner,sun4i-a10-mod0-clk"; + reg = <0x08001454 0x4>; + clocks = <&osc32k>, <&osc24M>; + clock-output-names = "r_ir"; + }; + +... diff --git a/Documentation/devicetree/bindings/clock/allwinner,sun4i-a10-mod1-clk.yaml b/Documentation/devicetree/bindings/clock/allwinner,sun4i-a10-mod1-clk.yaml new file mode 100644 index 000000000000..7ddb55c75cff --- /dev/null +++ b/Documentation/devicetree/bindings/clock/allwinner,sun4i-a10-mod1-clk.yaml @@ -0,0 +1,57 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/clock/allwinner,sun4i-a10-mod1-clk.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Allwinner A10 Module 1 Clock Device Tree Bindings + +maintainers: + - Chen-Yu Tsai <wens@csie.org> + - Maxime Ripard <mripard@kernel.org> + +deprecated: true + +properties: + "#clock-cells": + const: 0 + + compatible: + const: allwinner,sun4i-a10-mod1-clk + + reg: + maxItems: 1 + + clocks: + maxItems: 4 + description: > + The parent order must match the hardware programming order. + + clock-output-names: + maxItems: 1 + +required: + - "#clock-cells" + - compatible + - reg + - clocks + - clock-output-names + +additionalProperties: false + +examples: + - | + #include <dt-bindings/clock/sun4i-a10-pll2.h> + + clk@1c200c0 { + #clock-cells = <0>; + compatible = "allwinner,sun4i-a10-mod1-clk"; + reg = <0x01c200c0 0x4>; + clocks = <&pll2 SUN4I_A10_PLL2_8X>, + <&pll2 SUN4I_A10_PLL2_4X>, + <&pll2 SUN4I_A10_PLL2_2X>, + <&pll2 SUN4I_A10_PLL2_1X>; + clock-output-names = "spdif"; + }; + +... diff --git a/Documentation/devicetree/bindings/clock/allwinner,sun4i-a10-osc-clk.yaml b/Documentation/devicetree/bindings/clock/allwinner,sun4i-a10-osc-clk.yaml new file mode 100644 index 000000000000..69cfa4a3d562 --- /dev/null +++ b/Documentation/devicetree/bindings/clock/allwinner,sun4i-a10-osc-clk.yaml @@ -0,0 +1,51 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/clock/allwinner,sun4i-a10-osc-clk.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Allwinner A10 Gatable Oscillator Clock Device Tree Bindings + +maintainers: + - Chen-Yu Tsai <wens@csie.org> + - Maxime Ripard <mripard@kernel.org> + +deprecated: true + +properties: + "#clock-cells": + const: 0 + + compatible: + const: allwinner,sun4i-a10-osc-clk + + reg: + maxItems: 1 + + clock-frequency: + description: > + Frequency of the main oscillator. + + clock-output-names: + maxItems: 1 + +required: + - "#clock-cells" + - compatible + - reg + - clock-frequency + - clock-output-names + +additionalProperties: false + +examples: + - | + osc24M: clk@01c20050 { + #clock-cells = <0>; + compatible = "allwinner,sun4i-a10-osc-clk"; + reg = <0x01c20050 0x4>; + clock-frequency = <24000000>; + clock-output-names = "osc24M"; + }; + +... diff --git a/Documentation/devicetree/bindings/clock/allwinner,sun4i-a10-pll1-clk.yaml b/Documentation/devicetree/bindings/clock/allwinner,sun4i-a10-pll1-clk.yaml new file mode 100644 index 000000000000..e9c4cf834aa7 --- /dev/null +++ b/Documentation/devicetree/bindings/clock/allwinner,sun4i-a10-pll1-clk.yaml @@ -0,0 +1,71 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/clock/allwinner,sun4i-a10-pll1-clk.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Allwinner A10 CPU PLL Device Tree Bindings + +maintainers: + - Chen-Yu Tsai <wens@csie.org> + - Maxime Ripard <mripard@kernel.org> + +deprecated: true + +properties: + "#clock-cells": + const: 0 + + compatible: + enum: + - allwinner,sun4i-a10-pll1-clk + - allwinner,sun6i-a31-pll1-clk + - allwinner,sun8i-a23-pll1-clk + + reg: + maxItems: 1 + + clocks: + maxItems: 1 + + clock-output-names: + maxItems: 1 + +required: + - "#clock-cells" + - compatible + - reg + - clocks + - clock-output-names + +additionalProperties: false + +examples: + - | + clk@1c20000 { + #clock-cells = <0>; + compatible = "allwinner,sun4i-a10-pll1"; + reg = <0x01c20000 0x4>; + clocks = <&osc24M>; + clock-output-names = "osc24M"; + }; + + - | + clk@1c20000 { + #clock-cells = <0>; + compatible = "allwinner,sun6i-a31-pll1-clk"; + reg = <0x01c20000 0x4>; + clocks = <&osc24M>; + clock-output-names = "pll1"; + }; + + - | + clk@1c20000 { + #clock-cells = <0>; + compatible = "allwinner,sun8i-a23-pll1-clk"; + reg = <0x01c20000 0x4>; + clocks = <&osc24M>; + clock-output-names = "pll1"; + }; + +... diff --git a/Documentation/devicetree/bindings/clock/allwinner,sun4i-a10-pll3-clk.yaml b/Documentation/devicetree/bindings/clock/allwinner,sun4i-a10-pll3-clk.yaml new file mode 100644 index 000000000000..4b80a42fb3da --- /dev/null +++ b/Documentation/devicetree/bindings/clock/allwinner,sun4i-a10-pll3-clk.yaml @@ -0,0 +1,50 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/clock/allwinner,sun4i-a10-pll3-clk.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Allwinner A10 Video PLL Device Tree Bindings + +maintainers: + - Chen-Yu Tsai <wens@csie.org> + - Maxime Ripard <mripard@kernel.org> + +deprecated: true + +properties: + "#clock-cells": + const: 0 + + compatible: + const: allwinner,sun4i-a10-pll3-clk + + reg: + maxItems: 1 + + clocks: + maxItems: 1 + + clock-output-names: + maxItems: 1 + +required: + - "#clock-cells" + - compatible + - reg + - clocks + - clock-output-names + +additionalProperties: false + +examples: + - | + clk@1c20010 { + #clock-cells = <0>; + compatible = "allwinner,sun4i-a10-pll3-clk"; + reg = <0x01c20010 0x4>; + clocks = <&osc3M>; + clock-output-names = "pll3"; + }; + +... diff --git a/Documentation/devicetree/bindings/clock/allwinner,sun4i-a10-pll5-clk.yaml b/Documentation/devicetree/bindings/clock/allwinner,sun4i-a10-pll5-clk.yaml new file mode 100644 index 000000000000..415bd77de53d --- /dev/null +++ b/Documentation/devicetree/bindings/clock/allwinner,sun4i-a10-pll5-clk.yaml @@ -0,0 +1,53 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/clock/allwinner,sun4i-a10-pll5-clk.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Allwinner A10 DRAM PLL Device Tree Bindings + +maintainers: + - Chen-Yu Tsai <wens@csie.org> + - Maxime Ripard <mripard@kernel.org> + +deprecated: true + +properties: + "#clock-cells": + const: 1 + description: > + The first output is the DRAM clock output, the second is meant + for peripherals on the SoC. + + compatible: + const: allwinner,sun4i-a10-pll5-clk + + reg: + maxItems: 1 + + clocks: + maxItems: 1 + + clock-output-names: + maxItems: 2 + +required: + - "#clock-cells" + - compatible + - reg + - clocks + - clock-output-names + +additionalProperties: false + +examples: + - | + clk@1c20020 { + #clock-cells = <1>; + compatible = "allwinner,sun4i-a10-pll5-clk"; + reg = <0x01c20020 0x4>; + clocks = <&osc24M>; + clock-output-names = "pll5_ddr", "pll5_other"; + }; + +... diff --git a/Documentation/devicetree/bindings/clock/allwinner,sun4i-a10-pll6-clk.yaml b/Documentation/devicetree/bindings/clock/allwinner,sun4i-a10-pll6-clk.yaml new file mode 100644 index 000000000000..ec5652f76027 --- /dev/null +++ b/Documentation/devicetree/bindings/clock/allwinner,sun4i-a10-pll6-clk.yaml @@ -0,0 +1,53 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/clock/allwinner,sun4i-a10-pll6-clk.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Allwinner A10 Peripheral PLL Device Tree Bindings + +maintainers: + - Chen-Yu Tsai <wens@csie.org> + - Maxime Ripard <mripard@kernel.org> + +deprecated: true + +properties: + "#clock-cells": + const: 1 + description: > + The first output is the SATA clock output, the second is the + regular PLL output, the third is a PLL output at twice the rate. + + compatible: + const: allwinner,sun4i-a10-pll6-clk + + reg: + maxItems: 1 + + clocks: + maxItems: 1 + + clock-output-names: + maxItems: 3 + +required: + - "#clock-cells" + - compatible + - reg + - clocks + - clock-output-names + +additionalProperties: false + +examples: + - | + clk@1c20028 { + #clock-cells = <1>; + compatible = "allwinner,sun4i-a10-pll6-clk"; + reg = <0x01c20028 0x4>; + clocks = <&osc24M>; + clock-output-names = "pll6_sata", "pll6_other", "pll6"; + }; + +... diff --git a/Documentation/devicetree/bindings/clock/allwinner,sun4i-a10-tcon-ch0-clk.yaml b/Documentation/devicetree/bindings/clock/allwinner,sun4i-a10-tcon-ch0-clk.yaml new file mode 100644 index 000000000000..0a335c615efd --- /dev/null +++ b/Documentation/devicetree/bindings/clock/allwinner,sun4i-a10-tcon-ch0-clk.yaml @@ -0,0 +1,77 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/clock/allwinner,sun4i-a10-tcon-ch0-clk.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Allwinner A10 TCON Channel 0 Clock Device Tree Bindings + +maintainers: + - Chen-Yu Tsai <wens@csie.org> + - Maxime Ripard <mripard@kernel.org> + +deprecated: true + +properties: + "#clock-cells": + const: 0 + + "#reset-cells": + const: 1 + + compatible: + enum: + - allwinner,sun4i-a10-tcon-ch0-clk + - allwinner,sun4i-a10-tcon-ch1-clk + + reg: + maxItems: 1 + + clocks: + maxItems: 4 + description: > + The parent order must match the hardware programming order. + + clock-output-names: + maxItems: 1 + +required: + - "#clock-cells" + - compatible + - reg + - clocks + - clock-output-names + +if: + properties: + compatible: + contains: + const: allwinner,sun4i-a10-tcon-ch0-clk + +then: + required: + - "#reset-cells" + +additionalProperties: false + +examples: + - | + clk@1c20118 { + #clock-cells = <0>; + #reset-cells = <1>; + compatible = "allwinner,sun4i-a10-tcon-ch0-clk"; + reg = <0x01c20118 0x4>; + clocks = <&pll3>, <&pll7>, <&pll3x2>, <&pll7x2>; + clock-output-names = "tcon-ch0-sclk"; + }; + + - | + clk@1c2012c { + #clock-cells = <0>; + compatible = "allwinner,sun4i-a10-tcon-ch1-clk"; + reg = <0x01c2012c 0x4>; + clocks = <&pll3>, <&pll7>, <&pll3x2>, <&pll7x2>; + clock-output-names = "tcon-ch1-sclk"; + }; + +... diff --git a/Documentation/devicetree/bindings/clock/allwinner,sun4i-a10-usb-clk.yaml b/Documentation/devicetree/bindings/clock/allwinner,sun4i-a10-usb-clk.yaml new file mode 100644 index 000000000000..cd95d25bfe7c --- /dev/null +++ b/Documentation/devicetree/bindings/clock/allwinner,sun4i-a10-usb-clk.yaml @@ -0,0 +1,166 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/clock/allwinner,sun4i-a10-usb-clk.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Allwinner A10 USB Clock Device Tree Bindings + +maintainers: + - Chen-Yu Tsai <wens@csie.org> + - Maxime Ripard <mripard@kernel.org> + +deprecated: true + +properties: + "#clock-cells": + const: 1 + description: > + The additional ID argument passed to the clock shall refer to + the index of the output. + + "#reset-cells": + const: 1 + + compatible: + enum: + - allwinner,sun4i-a10-usb-clk + - allwinner,sun5i-a13-usb-clk + - allwinner,sun6i-a31-usb-clk + - allwinner,sun8i-a23-usb-clk + - allwinner,sun8i-h3-usb-clk + + reg: + maxItems: 1 + + clocks: + maxItems: 1 + + clock-output-names: + minItems: 2 + maxItems: 8 + +required: + - "#clock-cells" + - "#reset-cells" + - compatible + - reg + - clocks + - clock-output-names + +additionalProperties: false + +allOf: + - if: + properties: + compatible: + contains: + const: allwinner,sun4i-a10-usb-clk + + then: + properties: + clock-output-names: + maxItems: 3 + + - if: + properties: + compatible: + contains: + const: allwinner,sun5i-a13-usb-clk + + then: + properties: + clock-output-names: + maxItems: 2 + + - if: + properties: + compatible: + contains: + const: allwinner,sun6i-a31-usb-clk + + then: + properties: + clock-output-names: + maxItems: 6 + + - if: + properties: + compatible: + contains: + const: allwinner,sun8i-a23-usb-clk + + then: + properties: + clock-output-names: + maxItems: 5 + + - if: + properties: + compatible: + contains: + const: allwinner,sun8i-h3-usb-clk + + then: + properties: + clock-output-names: + maxItems: 8 + +examples: + - | + clk@1c200cc { + #clock-cells = <1>; + #reset-cells = <1>; + compatible = "allwinner,sun4i-a10-usb-clk"; + reg = <0x01c200cc 0x4>; + clocks = <&pll6 1>; + clock-output-names = "usb_ohci0", "usb_ohci1", "usb_phy"; + }; + + - | + clk@1c200cc { + #clock-cells = <1>; + #reset-cells = <1>; + compatible = "allwinner,sun5i-a13-usb-clk"; + reg = <0x01c200cc 0x4>; + clocks = <&pll6 1>; + clock-output-names = "usb_ohci0", "usb_phy"; + }; + + - | + clk@1c200cc { + #clock-cells = <1>; + #reset-cells = <1>; + compatible = "allwinner,sun6i-a31-usb-clk"; + reg = <0x01c200cc 0x4>; + clocks = <&osc24M>; + clock-output-names = "usb_phy0", "usb_phy1", "usb_phy2", + "usb_ohci0", "usb_ohci1", + "usb_ohci2"; + }; + + - | + clk@1c200cc { + #clock-cells = <1>; + #reset-cells = <1>; + compatible = "allwinner,sun8i-a23-usb-clk"; + reg = <0x01c200cc 0x4>; + clocks = <&osc24M>; + clock-output-names = "usb_phy0", "usb_phy1", "usb_hsic", + "usb_hsic_12M", "usb_ohci0"; + }; + + - | + clk@1c200cc { + #clock-cells = <1>; + #reset-cells = <1>; + compatible = "allwinner,sun8i-h3-usb-clk"; + reg = <0x01c200cc 0x4>; + clocks = <&osc24M>; + clock-output-names = "usb_phy0", "usb_phy1", + "usb_phy2", "usb_phy3", + "usb_ohci0", "usb_ohci1", + "usb_ohci2", "usb_ohci3"; + }; + +... diff --git a/Documentation/devicetree/bindings/clock/allwinner,sun4i-a10-ve-clk.yaml b/Documentation/devicetree/bindings/clock/allwinner,sun4i-a10-ve-clk.yaml new file mode 100644 index 000000000000..5dfd0c1c27b4 --- /dev/null +++ b/Documentation/devicetree/bindings/clock/allwinner,sun4i-a10-ve-clk.yaml @@ -0,0 +1,55 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/clock/allwinner,sun4i-a10-ve-clk.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Allwinner A10 Video Engine Clock Device Tree Bindings + +maintainers: + - Chen-Yu Tsai <wens@csie.org> + - Maxime Ripard <mripard@kernel.org> + +deprecated: true + +properties: + "#clock-cells": + const: 0 + + "#reset-cells": + const: 0 + + compatible: + const: allwinner,sun4i-a10-ve-clk + + reg: + maxItems: 1 + + clocks: + maxItems: 1 + + clock-output-names: + maxItems: 1 + +required: + - "#clock-cells" + - "#reset-cells" + - compatible + - reg + - clocks + - clock-output-names + +additionalProperties: false + +examples: + - | + clk@1c2013c { + #clock-cells = <0>; + #reset-cells = <0>; + compatible = "allwinner,sun4i-a10-ve-clk"; + reg = <0x01c2013c 0x4>; + clocks = <&pll4>; + clock-output-names = "ve"; + }; + +... diff --git a/Documentation/devicetree/bindings/clock/allwinner,sun5i-a13-ahb-clk.yaml b/Documentation/devicetree/bindings/clock/allwinner,sun5i-a13-ahb-clk.yaml new file mode 100644 index 000000000000..99add7991c48 --- /dev/null +++ b/Documentation/devicetree/bindings/clock/allwinner,sun5i-a13-ahb-clk.yaml @@ -0,0 +1,52 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/clock/allwinner,sun5i-a13-ahb-clk.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Allwinner A13 AHB Clock Device Tree Bindings + +maintainers: + - Chen-Yu Tsai <wens@csie.org> + - Maxime Ripard <mripard@kernel.org> + +deprecated: true + +properties: + "#clock-cells": + const: 0 + + compatible: + const: allwinner,sun5i-a13-ahb-clk + + reg: + maxItems: 1 + + clocks: + maxItems: 3 + description: > + The parent order must match the hardware programming order. + + clock-output-names: + maxItems: 1 + +required: + - "#clock-cells" + - compatible + - reg + - clocks + - clock-output-names + +additionalProperties: false + +examples: + - | + ahb@1c20054 { + #clock-cells = <0>; + compatible = "allwinner,sun5i-a13-ahb-clk"; + reg = <0x01c20054 0x4>; + clocks = <&axi>, <&cpu>, <&pll6 1>; + clock-output-names = "ahb"; + }; + +... diff --git a/Documentation/devicetree/bindings/clock/allwinner,sun6i-a31-pll6-clk.yaml b/Documentation/devicetree/bindings/clock/allwinner,sun6i-a31-pll6-clk.yaml new file mode 100644 index 000000000000..5f377205af71 --- /dev/null +++ b/Documentation/devicetree/bindings/clock/allwinner,sun6i-a31-pll6-clk.yaml @@ -0,0 +1,53 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/clock/allwinner,sun6i-a31-pll6-clk.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Allwinner A31 Peripheral PLL Device Tree Bindings + +maintainers: + - Chen-Yu Tsai <wens@csie.org> + - Maxime Ripard <mripard@kernel.org> + +deprecated: true + +properties: + "#clock-cells": + const: 1 + description: > + The first output is the regular PLL output, the second is a PLL + output at twice the rate. + + compatible: + const: allwinner,sun6i-a31-pll6-clk + + reg: + maxItems: 1 + + clocks: + maxItems: 1 + + clock-output-names: + maxItems: 2 + +required: + - "#clock-cells" + - compatible + - reg + - clocks + - clock-output-names + +additionalProperties: false + +examples: + - | + clk@1c20028 { + #clock-cells = <1>; + compatible = "allwinner,sun6i-a31-pll6-clk"; + reg = <0x01c20028 0x4>; + clocks = <&osc24M>; + clock-output-names = "pll6", "pll6x2"; + }; + +... diff --git a/Documentation/devicetree/bindings/clock/allwinner,sun7i-a20-gmac-clk.yaml b/Documentation/devicetree/bindings/clock/allwinner,sun7i-a20-gmac-clk.yaml new file mode 100644 index 000000000000..59e5dce1b65a --- /dev/null +++ b/Documentation/devicetree/bindings/clock/allwinner,sun7i-a20-gmac-clk.yaml @@ -0,0 +1,51 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/clock/allwinner,sun7i-a20-gmac-clk.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Allwinner A20 GMAC TX Clock Device Tree Bindings + +maintainers: + - Chen-Yu Tsai <wens@csie.org> + - Maxime Ripard <mripard@kernel.org> + +properties: + "#clock-cells": + const: 0 + + compatible: + const: allwinner,sun7i-a20-gmac-clk + + reg: + maxItems: 1 + + clocks: + maxItems: 2 + description: > + The parent clocks shall be fixed rate dummy clocks at 25 MHz and + 125 MHz, respectively. + + clock-output-names: + maxItems: 1 + +required: + - "#clock-cells" + - compatible + - reg + - clocks + - clock-output-names + +additionalProperties: false + +examples: + - | + clk@1c20164 { + #clock-cells = <0>; + compatible = "allwinner,sun7i-a20-gmac-clk"; + reg = <0x01c20164 0x4>; + clocks = <&mii_phy_tx_clk>, <&gmac_int_tx_clk>; + clock-output-names = "gmac_tx"; + }; + +... diff --git a/Documentation/devicetree/bindings/clock/allwinner,sun7i-a20-out-clk.yaml b/Documentation/devicetree/bindings/clock/allwinner,sun7i-a20-out-clk.yaml new file mode 100644 index 000000000000..c745733bcf04 --- /dev/null +++ b/Documentation/devicetree/bindings/clock/allwinner,sun7i-a20-out-clk.yaml @@ -0,0 +1,52 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/clock/allwinner,sun7i-a20-out-clk.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Allwinner A20 Output Clock Device Tree Bindings + +maintainers: + - Chen-Yu Tsai <wens@csie.org> + - Maxime Ripard <mripard@kernel.org> + +deprecated: true + +properties: + "#clock-cells": + const: 0 + + compatible: + const: allwinner,sun7i-a20-out-clk + + reg: + maxItems: 1 + + clocks: + maxItems: 3 + description: > + The parent order must match the hardware programming order. + + clock-output-names: + maxItems: 1 + +required: + - "#clock-cells" + - compatible + - reg + - clocks + - clock-output-names + +additionalProperties: false + +examples: + - | + clk@1c201f0 { + #clock-cells = <0>; + compatible = "allwinner,sun7i-a20-out-clk"; + reg = <0x01c201f0 0x4>; + clocks = <&osc24M_32k>, <&osc32k>, <&osc24M>; + clock-output-names = "clk_out_a"; + }; + +... diff --git a/Documentation/devicetree/bindings/clock/allwinner,sun8i-a83t-de2-clk.yaml b/Documentation/devicetree/bindings/clock/allwinner,sun8i-a83t-de2-clk.yaml new file mode 100644 index 000000000000..3f995d2b30eb --- /dev/null +++ b/Documentation/devicetree/bindings/clock/allwinner,sun8i-a83t-de2-clk.yaml @@ -0,0 +1,76 @@ +# SPDX-License-Identifier: GPL-2.0+ +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/clock/allwinner,sun8i-a83t-de2-clk.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Allwinner A83t Display Engine 2/3 Clock Controller Device Tree Bindings + +maintainers: + - Chen-Yu Tsai <wens@csie.org> + - Maxime Ripard <mripard@kernel.org> + +properties: + "#clock-cells": + const: 1 + + "#reset-cells": + const: 1 + + compatible: + oneOf: + - const: allwinner,sun8i-a83t-de2-clk + - const: allwinner,sun8i-h3-de2-clk + - const: allwinner,sun8i-v3s-de2-clk + - const: allwinner,sun50i-a64-de2-clk + - const: allwinner,sun50i-h5-de2-clk + - const: allwinner,sun50i-h6-de2-clk + - items: + - const: allwinner,sun8i-r40-de2-clk + - const: allwinner,sun8i-h3-de2-clk + + reg: + maxItems: 1 + + clocks: + items: + - description: Bus Clock + - description: Module Clock + + clock-names: + items: + - const: bus + - const: mod + + resets: + maxItems: 1 + +required: + - "#clock-cells" + - "#reset-cells" + - compatible + - reg + - clocks + - clock-names + - resets + +additionalProperties: false + +examples: + - | + #include <dt-bindings/clock/sun8i-h3-ccu.h> + #include <dt-bindings/reset/sun8i-h3-ccu.h> + + de2_clocks: clock@1000000 { + compatible = "allwinner,sun8i-h3-de2-clk"; + reg = <0x01000000 0x100000>; + clocks = <&ccu CLK_BUS_DE>, + <&ccu CLK_DE>; + clock-names = "bus", + "mod"; + resets = <&ccu RST_BUS_DE>; + #clock-cells = <1>; + #reset-cells = <1>; + }; + +... diff --git a/Documentation/devicetree/bindings/clock/allwinner,sun8i-h3-bus-gates-clk.yaml b/Documentation/devicetree/bindings/clock/allwinner,sun8i-h3-bus-gates-clk.yaml new file mode 100644 index 000000000000..3eb2bf65b230 --- /dev/null +++ b/Documentation/devicetree/bindings/clock/allwinner,sun8i-h3-bus-gates-clk.yaml @@ -0,0 +1,103 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/clock/allwinner,sun8i-h3-bus-gates-clk.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Allwinner A10 Bus Gates Clock Device Tree Bindings + +maintainers: + - Chen-Yu Tsai <wens@csie.org> + - Maxime Ripard <mripard@kernel.org> + +deprecated: true + +properties: + "#clock-cells": + const: 1 + description: > + This additional argument passed to that clock is the offset of + the bit controlling this particular gate in the register. + + compatible: + const: allwinner,sun8i-h3-bus-gates-clk + + reg: + maxItems: 1 + + clocks: + maxItems: 4 + + clock-names: + maxItems: 4 + description: > + The parent order must match the hardware programming order. + + clock-indices: + minItems: 1 + maxItems: 64 + + clock-output-names: + minItems: 1 + maxItems: 64 + +required: + - "#clock-cells" + - compatible + - reg + - clocks + - clock-indices + - clock-names + - clock-output-names + +additionalProperties: false + +examples: + - | + clk@1c20060 { + #clock-cells = <1>; + compatible = "allwinner,sun8i-h3-bus-gates-clk"; + reg = <0x01c20060 0x14>; + clocks = <&ahb1>, <&ahb2>, <&apb1>, <&apb2>; + clock-names = "ahb1", "ahb2", "apb1", "apb2"; + clock-indices = <5>, <6>, <8>, + <9>, <10>, <13>, + <14>, <17>, <18>, + <19>, <20>, + <21>, <23>, + <24>, <25>, + <26>, <27>, + <28>, <29>, + <30>, <31>, <32>, + <35>, <36>, <37>, + <40>, <41>, <43>, + <44>, <52>, <53>, + <54>, <64>, + <65>, <69>, <72>, + <76>, <77>, <78>, + <96>, <97>, <98>, + <112>, <113>, + <114>, <115>, + <116>, <128>, <135>; + clock-output-names = "bus_ce", "bus_dma", "bus_mmc0", + "bus_mmc1", "bus_mmc2", "bus_nand", + "bus_sdram", "bus_gmac", "bus_ts", + "bus_hstimer", "bus_spi0", + "bus_spi1", "bus_otg", + "bus_otg_ehci0", "bus_ehci1", + "bus_ehci2", "bus_ehci3", + "bus_otg_ohci0", "bus_ohci1", + "bus_ohci2", "bus_ohci3", "bus_ve", + "bus_lcd0", "bus_lcd1", "bus_deint", + "bus_csi", "bus_tve", "bus_hdmi", + "bus_de", "bus_gpu", "bus_msgbox", + "bus_spinlock", "bus_codec", + "bus_spdif", "bus_pio", "bus_ths", + "bus_i2s0", "bus_i2s1", "bus_i2s2", + "bus_i2c0", "bus_i2c1", "bus_i2c2", + "bus_uart0", "bus_uart1", + "bus_uart2", "bus_uart3", + "bus_scr", "bus_ephy", "bus_dbg"; + }; + +... diff --git a/Documentation/devicetree/bindings/clock/allwinner,sun9i-a80-ahb-clk.yaml b/Documentation/devicetree/bindings/clock/allwinner,sun9i-a80-ahb-clk.yaml new file mode 100644 index 000000000000..d178da90aaec --- /dev/null +++ b/Documentation/devicetree/bindings/clock/allwinner,sun9i-a80-ahb-clk.yaml @@ -0,0 +1,52 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/clock/allwinner,sun9i-a80-ahb-clk.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Allwinner A80 AHB Clock Device Tree Bindings + +maintainers: + - Chen-Yu Tsai <wens@csie.org> + - Maxime Ripard <mripard@kernel.org> + +deprecated: true + +properties: + "#clock-cells": + const: 0 + + compatible: + const: allwinner,sun9i-a80-ahb-clk + + reg: + maxItems: 1 + + clocks: + maxItems: 4 + description: > + The parent order must match the hardware programming order. + + clock-output-names: + maxItems: 1 + +required: + - "#clock-cells" + - compatible + - reg + - clocks + - clock-output-names + +additionalProperties: false + +examples: + - | + clk@6000060 { + #clock-cells = <0>; + compatible = "allwinner,sun9i-a80-ahb-clk"; + reg = <0x06000060 0x4>; + clocks = <>_clk>, <&pll4>, <&pll12>, <&pll12>; + clock-output-names = "ahb0"; + }; + +... diff --git a/Documentation/devicetree/bindings/clock/allwinner,sun9i-a80-apb0-clk.yaml b/Documentation/devicetree/bindings/clock/allwinner,sun9i-a80-apb0-clk.yaml new file mode 100644 index 000000000000..0351c79bd221 --- /dev/null +++ b/Documentation/devicetree/bindings/clock/allwinner,sun9i-a80-apb0-clk.yaml @@ -0,0 +1,63 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/clock/allwinner,sun9i-a80-apb0-clk.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Allwinner A80 APB0 Bus Clock Device Tree Bindings + +maintainers: + - Chen-Yu Tsai <wens@csie.org> + - Maxime Ripard <mripard@kernel.org> + +deprecated: true + +properties: + "#clock-cells": + const: 0 + + compatible: + enum: + - allwinner,sun9i-a80-apb0-clk + - allwinner,sun9i-a80-apb1-clk + + reg: + maxItems: 1 + + clocks: + maxItems: 2 + description: > + The parent order must match the hardware programming order. + + clock-output-names: + maxItems: 1 + +required: + - "#clock-cells" + - compatible + - reg + - clocks + - clock-output-names + +additionalProperties: false + +examples: + - | + clk@6000070 { + #clock-cells = <0>; + compatible = "allwinner,sun9i-a80-apb0-clk"; + reg = <0x06000070 0x4>; + clocks = <&osc24M>, <&pll4>; + clock-output-names = "apb0"; + }; + + - | + clk@6000074 { + #clock-cells = <0>; + compatible = "allwinner,sun9i-a80-apb1-clk"; + reg = <0x06000074 0x4>; + clocks = <&osc24M>, <&pll4>; + clock-output-names = "apb1"; + }; + +... diff --git a/Documentation/devicetree/bindings/clock/allwinner,sun9i-a80-cpus-clk.yaml b/Documentation/devicetree/bindings/clock/allwinner,sun9i-a80-cpus-clk.yaml new file mode 100644 index 000000000000..24d5b2f1a314 --- /dev/null +++ b/Documentation/devicetree/bindings/clock/allwinner,sun9i-a80-cpus-clk.yaml @@ -0,0 +1,52 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/clock/allwinner,sun9i-a80-cpus-clk.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Allwinner A80 CPUS Clock Device Tree Bindings + +maintainers: + - Chen-Yu Tsai <wens@csie.org> + - Maxime Ripard <mripard@kernel.org> + +deprecated: true + +properties: + "#clock-cells": + const: 0 + + compatible: + const: allwinner,sun9i-a80-cpus-clk + + reg: + maxItems: 1 + + clocks: + maxItems: 4 + description: > + The parent order must match the hardware programming order. + + clock-output-names: + maxItems: 1 + +required: + - "#clock-cells" + - compatible + - reg + - clocks + - clock-output-names + +additionalProperties: false + +examples: + - | + clk@8001410 { + compatible = "allwinner,sun9i-a80-cpus-clk"; + reg = <0x08001410 0x4>; + #clock-cells = <0>; + clocks = <&osc32k>, <&osc24M>, <&pll4>, <&pll3>; + clock-output-names = "cpus"; + }; + +... diff --git a/Documentation/devicetree/bindings/clock/allwinner,sun9i-a80-de-clks.yaml b/Documentation/devicetree/bindings/clock/allwinner,sun9i-a80-de-clks.yaml new file mode 100644 index 000000000000..a82c7c7e942b --- /dev/null +++ b/Documentation/devicetree/bindings/clock/allwinner,sun9i-a80-de-clks.yaml @@ -0,0 +1,67 @@ +# SPDX-License-Identifier: GPL-2.0+ +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/clock/allwinner,sun9i-a80-de-clks.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Allwinner A80 Display Engine Clock Controller Device Tree Bindings + +maintainers: + - Chen-Yu Tsai <wens@csie.org> + - Maxime Ripard <mripard@kernel.org> + +properties: + "#clock-cells": + const: 1 + + "#reset-cells": + const: 1 + + compatible: + const: allwinner,sun9i-a80-de-clks + + reg: + maxItems: 1 + + clocks: + items: + - description: Bus Clock + - description: RAM Bus Clock + - description: Module Clock + + clock-names: + items: + - const: mod + - const: dram + - const: bus + + resets: + maxItems: 1 + +required: + - "#clock-cells" + - "#reset-cells" + - compatible + - reg + - clocks + - clock-names + - resets + +additionalProperties: false + +examples: + - | + #include <dt-bindings/clock/sun9i-a80-ccu.h> + #include <dt-bindings/reset/sun9i-a80-ccu.h> + + de_clocks: clock@3000000 { + compatible = "allwinner,sun9i-a80-de-clks"; + reg = <0x03000000 0x30>; + clocks = <&ccu CLK_DE>, <&ccu CLK_SDRAM>, <&ccu CLK_BUS_DE>; + clock-names = "mod", "dram", "bus"; + resets = <&ccu RST_BUS_DE>; + #clock-cells = <1>; + #reset-cells = <1>; + }; + +... diff --git a/Documentation/devicetree/bindings/clock/allwinner,sun9i-a80-gt-clk.yaml b/Documentation/devicetree/bindings/clock/allwinner,sun9i-a80-gt-clk.yaml new file mode 100644 index 000000000000..07f38def7dc3 --- /dev/null +++ b/Documentation/devicetree/bindings/clock/allwinner,sun9i-a80-gt-clk.yaml @@ -0,0 +1,52 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/clock/allwinner,sun9i-a80-gt-clk.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Allwinner A80 GT Bus Clock Device Tree Bindings + +maintainers: + - Chen-Yu Tsai <wens@csie.org> + - Maxime Ripard <mripard@kernel.org> + +deprecated: true + +properties: + "#clock-cells": + const: 0 + + compatible: + const: allwinner,sun9i-a80-gt-clk + + reg: + maxItems: 1 + + clocks: + maxItems: 4 + description: > + The parent order must match the hardware programming order. + + clock-output-names: + maxItems: 1 + +required: + - "#clock-cells" + - compatible + - reg + - clocks + - clock-output-names + +additionalProperties: false + +examples: + - | + clk@0600005c { + #clock-cells = <0>; + compatible = "allwinner,sun9i-a80-gt-clk"; + reg = <0x0600005c 0x4>; + clocks = <&osc24M>, <&pll4>, <&pll12>, <&pll12>; + clock-output-names = "gt"; + }; + +... diff --git a/Documentation/devicetree/bindings/clock/allwinner,sun9i-a80-mmc-config-clk.yaml b/Documentation/devicetree/bindings/clock/allwinner,sun9i-a80-mmc-config-clk.yaml new file mode 100644 index 000000000000..20dc115fa211 --- /dev/null +++ b/Documentation/devicetree/bindings/clock/allwinner,sun9i-a80-mmc-config-clk.yaml @@ -0,0 +1,68 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/clock/allwinner,sun9i-a80-mmc-config-clk.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Allwinner A80 MMC Configuration Clock Device Tree Bindings + +maintainers: + - Chen-Yu Tsai <wens@csie.org> + - Maxime Ripard <mripard@kernel.org> + +deprecated: true + +description: > + There is one clock/reset output per mmc controller. The number of + outputs is determined by the size of the address block, which is + related to the overall mmc block. + +properties: + "#clock-cells": + const: 1 + description: > + The additional ID argument passed to the clock shall refer to + the index of the output. + + "#reset-cells": + const: 1 + + compatible: + const: allwinner,sun9i-a80-mmc-config-clk + + reg: + maxItems: 1 + + clocks: + maxItems: 1 + + resets: + maxItems: 1 + + clock-output-names: + maxItems: 4 + +required: + - "#clock-cells" + - "#reset-cells" + - compatible + - reg + - clocks + - clock-output-names + +additionalProperties: false + +examples: + - | + clk@1c13000 { + #clock-cells = <1>; + #reset-cells = <1>; + compatible = "allwinner,sun9i-a80-mmc-config-clk"; + reg = <0x01c13000 0x10>; + clocks = <&ahb0_gates 8>; + resets = <&ahb0_resets 8>; + clock-output-names = "mmc0_config", "mmc1_config", + "mmc2_config", "mmc3_config"; + }; + +... diff --git a/Documentation/devicetree/bindings/clock/allwinner,sun9i-a80-pll4-clk.yaml b/Documentation/devicetree/bindings/clock/allwinner,sun9i-a80-pll4-clk.yaml new file mode 100644 index 000000000000..b76bab6a30e9 --- /dev/null +++ b/Documentation/devicetree/bindings/clock/allwinner,sun9i-a80-pll4-clk.yaml @@ -0,0 +1,50 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/clock/allwinner,sun9i-a80-pll4-clk.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Allwinner A80 Peripheral PLL Device Tree Bindings + +maintainers: + - Chen-Yu Tsai <wens@csie.org> + - Maxime Ripard <mripard@kernel.org> + +deprecated: true + +properties: + "#clock-cells": + const: 0 + + compatible: + const: allwinner,sun9i-a80-pll4-clk + + reg: + maxItems: 1 + + clocks: + maxItems: 1 + + clock-output-names: + maxItems: 1 + +required: + - "#clock-cells" + - compatible + - reg + - clocks + - clock-output-names + +additionalProperties: false + +examples: + - | + clk@600000c { + #clock-cells = <0>; + compatible = "allwinner,sun9i-a80-pll4-clk"; + reg = <0x0600000c 0x4>; + clocks = <&osc24M>; + clock-output-names = "pll4"; + }; + +... diff --git a/Documentation/devicetree/bindings/clock/allwinner,sun9i-a80-usb-clocks.yaml b/Documentation/devicetree/bindings/clock/allwinner,sun9i-a80-usb-clocks.yaml new file mode 100644 index 000000000000..fa0ee03a527f --- /dev/null +++ b/Documentation/devicetree/bindings/clock/allwinner,sun9i-a80-usb-clocks.yaml @@ -0,0 +1,59 @@ +# SPDX-License-Identifier: GPL-2.0+ +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/clock/allwinner,sun9i-a80-usb-clocks.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Allwinner A80 USB Clock Controller Device Tree Bindings + +maintainers: + - Chen-Yu Tsai <wens@csie.org> + - Maxime Ripard <mripard@kernel.org> + +properties: + "#clock-cells": + const: 1 + + "#reset-cells": + const: 1 + + compatible: + const: allwinner,sun9i-a80-usb-clocks + + reg: + maxItems: 1 + + clocks: + items: + - description: Bus Clock + - description: High Frequency Oscillator + + clock-names: + items: + - const: bus + - const: hosc + +required: + - "#clock-cells" + - "#reset-cells" + - compatible + - reg + - clocks + - clock-names + +additionalProperties: false + +examples: + - | + #include <dt-bindings/clock/sun9i-a80-ccu.h> + + usb_clocks: clock@a08000 { + compatible = "allwinner,sun9i-a80-usb-clks"; + reg = <0x00a08000 0x8>; + clocks = <&ccu CLK_BUS_USB>, <&osc24M>; + clock-names = "bus", "hosc"; + #clock-cells = <1>; + #reset-cells = <1>; + }; + +... diff --git a/Documentation/devicetree/bindings/clock/allwinner,sun9i-a80-usb-mod-clk.yaml b/Documentation/devicetree/bindings/clock/allwinner,sun9i-a80-usb-mod-clk.yaml new file mode 100644 index 000000000000..15218d10e78e --- /dev/null +++ b/Documentation/devicetree/bindings/clock/allwinner,sun9i-a80-usb-mod-clk.yaml @@ -0,0 +1,60 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/clock/allwinner,sun9i-a80-usb-mod-clk.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Allwinner A80 USB Module Clock Device Tree Bindings + +maintainers: + - Chen-Yu Tsai <wens@csie.org> + - Maxime Ripard <mripard@kernel.org> + +deprecated: true + +properties: + "#clock-cells": + const: 1 + description: > + The additional ID argument passed to the clock shall refer to + the index of the output. + + "#reset-cells": + const: 1 + + compatible: + const: allwinner,sun9i-a80-usb-mod-clk + + reg: + maxItems: 1 + + clocks: + maxItems: 1 + + clock-output-names: + maxItems: 6 + +required: + - "#clock-cells" + - "#reset-cells" + - compatible + - reg + - clocks + - clock-output-names + +additionalProperties: false + +examples: + - | + clk@a08000 { + #clock-cells = <1>; + #reset-cells = <1>; + compatible = "allwinner,sun9i-a80-usb-mod-clk"; + reg = <0x00a08000 0x4>; + clocks = <&ahb1_gates 1>; + clock-output-names = "usb0_ahb", "usb_ohci0", + "usb1_ahb", "usb_ohci1", + "usb2_ahb", "usb_ohci2"; + }; + +... diff --git a/Documentation/devicetree/bindings/clock/allwinner,sun9i-a80-usb-phy-clk.yaml b/Documentation/devicetree/bindings/clock/allwinner,sun9i-a80-usb-phy-clk.yaml new file mode 100644 index 000000000000..2569041684e6 --- /dev/null +++ b/Documentation/devicetree/bindings/clock/allwinner,sun9i-a80-usb-phy-clk.yaml @@ -0,0 +1,60 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/clock/allwinner,sun9i-a80-usb-phy-clk.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Allwinner A80 USB PHY Clock Device Tree Bindings + +maintainers: + - Chen-Yu Tsai <wens@csie.org> + - Maxime Ripard <mripard@kernel.org> + +deprecated: true + +properties: + "#clock-cells": + const: 1 + description: > + The additional ID argument passed to the clock shall refer to + the index of the output. + + "#reset-cells": + const: 1 + + compatible: + const: allwinner,sun9i-a80-usb-phy-clk + + reg: + maxItems: 1 + + clocks: + maxItems: 1 + + clock-output-names: + maxItems: 6 + +required: + - "#clock-cells" + - "#reset-cells" + - compatible + - reg + - clocks + - clock-output-names + +additionalProperties: false + +examples: + - | + clk@a08004 { + #clock-cells = <1>; + #reset-cells = <1>; + compatible = "allwinner,sun9i-a80-usb-phy-clk"; + reg = <0x00a08004 0x4>; + clocks = <&ahb1_gates 1>; + clock-output-names = "usb_phy0", "usb_hsic1_480M", + "usb_phy1", "usb_hsic2_480M", + "usb_phy2", "usb_hsic_12M"; + }; + +... diff --git a/Documentation/devicetree/bindings/clock/amlogic,meson8-ddr-clkc.yaml b/Documentation/devicetree/bindings/clock/amlogic,meson8-ddr-clkc.yaml new file mode 100644 index 000000000000..4b8669f870ec --- /dev/null +++ b/Documentation/devicetree/bindings/clock/amlogic,meson8-ddr-clkc.yaml @@ -0,0 +1,50 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/clock/amlogic,meson8-ddr-clkc.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Amlogic DDR Clock Controller Device Tree Bindings + +maintainers: + - Martin Blumenstingl <martin.blumenstingl@googlemail.com> + +properties: + compatible: + enum: + - amlogic,meson8-ddr-clkc + - amlogic,meson8b-ddr-clkc + + reg: + maxItems: 1 + + clocks: + maxItems: 1 + + clock-names: + items: + - const: xtal + + "#clock-cells": + const: 1 + +required: + - compatible + - reg + - clocks + - clock-names + - "#clock-cells" + +additionalProperties: false + +examples: + - | + ddr_clkc: clock-controller@400 { + compatible = "amlogic,meson8-ddr-clkc"; + reg = <0x400 0x20>; + clocks = <&xtal>; + clock-names = "xtal"; + #clock-cells = <1>; + }; + +... diff --git a/Documentation/devicetree/bindings/clock/amlogic,meson8b-clkc.txt b/Documentation/devicetree/bindings/clock/amlogic,meson8b-clkc.txt index 4d94091c1d2d..cc51e4746b3b 100644 --- a/Documentation/devicetree/bindings/clock/amlogic,meson8b-clkc.txt +++ b/Documentation/devicetree/bindings/clock/amlogic,meson8b-clkc.txt @@ -11,6 +11,11 @@ Required Properties: - "amlogic,meson8m2-clkc" for Meson8m2 (S812) SoCs - #clock-cells: should be 1. - #reset-cells: should be 1. +- clocks: list of clock phandles, one for each entry in clock-names +- clock-names: should contain the following: + * "xtal": the 24MHz system oscillator + * "ddr_pll": the DDR PLL clock + * "clk_32k": (if present) the 32kHz clock signal from GPIOAO_6 (CLK_32K_IN) Parent node should have the following properties : - compatible: "amlogic,meson-hhi-sysctrl", "simple-mfd", "syscon" diff --git a/Documentation/devicetree/bindings/clock/bitmain,bm1880-clk.yaml b/Documentation/devicetree/bindings/clock/bitmain,bm1880-clk.yaml index e63827399c1a..8559fe8f7efd 100644 --- a/Documentation/devicetree/bindings/clock/bitmain,bm1880-clk.yaml +++ b/Documentation/devicetree/bindings/clock/bitmain,bm1880-clk.yaml @@ -1,7 +1,7 @@ # SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) %YAML 1.2 --- -$id: http://devicetree.org/schemas/bindings/clock/bitmain,bm1880-clk.yaml# +$id: http://devicetree.org/schemas/clock/bitmain,bm1880-clk.yaml# $schema: http://devicetree.org/meta-schemas/core.yaml# title: Bitmain BM1880 Clock Controller diff --git a/Documentation/devicetree/bindings/clock/fsl,plldig.yaml b/Documentation/devicetree/bindings/clock/fsl,plldig.yaml new file mode 100644 index 000000000000..c8350030b374 --- /dev/null +++ b/Documentation/devicetree/bindings/clock/fsl,plldig.yaml @@ -0,0 +1,54 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/clock/fsl,plldig.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: NXP QorIQ Layerscape LS1028A Display PIXEL Clock Binding + +maintainers: + - Wen He <wen.he_1@nxp.com> + +description: | + NXP LS1028A has a clock domain PXLCLK0 used for the Display output + interface in the display core, as implemented in TSMC CLN28HPM PLL. + which generate and offers pixel clocks to Display. + +properties: + compatible: + const: fsl,ls1028a-plldig + + reg: + maxItems: 1 + + '#clock-cells': + const: 0 + + fsl,vco-hz: + description: Optional for VCO frequency of the PLL in Hertz. + The VCO frequency of this PLL cannot be changed during runtime + only at startup. Therefore, the output frequencies are very + limited and might not even closely match the requested frequency. + To work around this restriction the user may specify its own + desired VCO frequency for the PLL. + minimum: 650000000 + maximum: 1300000000 + default: 1188000000 + +required: + - compatible + - reg + - clocks + - '#clock-cells' + +examples: + # Display PIXEL Clock node: + - | + dpclk: clock-display@f1f0000 { + compatible = "fsl,ls1028a-plldig"; + reg = <0x0 0xf1f0000 0x0 0xffff>; + #clock-cells = <0>; + clocks = <&osc_27m>; + }; + +... diff --git a/Documentation/devicetree/bindings/clock/fsl,sai-clock.yaml b/Documentation/devicetree/bindings/clock/fsl,sai-clock.yaml new file mode 100644 index 000000000000..fc3bdfdc091a --- /dev/null +++ b/Documentation/devicetree/bindings/clock/fsl,sai-clock.yaml @@ -0,0 +1,55 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/clock/fsl,sai-clock.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Freescale SAI bitclock-as-a-clock binding + +maintainers: + - Michael Walle <michael@walle.cc> + +description: | + It is possible to use the BCLK pin of a SAI module as a generic clock + output. Some SoC are very constrained in their pin multiplexer + configuration. Eg. pins can only be changed groups. For example, on the + LS1028A SoC you can only enable SAIs in pairs. If you use only one SAI, + the second pins are wasted. Using this binding it is possible to use the + clock of the second SAI as a MCLK clock for an audio codec, for example. + + This is a composite of a gated clock and a divider clock. + +properties: + compatible: + const: fsl,vf610-sai-clock + + reg: + maxItems: 1 + + clocks: + maxItems: 1 + + '#clock-cells': + const: 0 + +required: + - compatible + - reg + - clocks + - '#clock-cells' + +additionalProperties: false + +examples: + - | + soc { + #address-cells = <2>; + #size-cells = <2>; + + mclk: clock-mclk@f130080 { + compatible = "fsl,vf610-sai-clock"; + reg = <0x0 0xf130080 0x0 0x80>; + #clock-cells = <0>; + clocks = <&parentclk>; + }; + }; diff --git a/Documentation/devicetree/bindings/clock/imx8mn-clock.yaml b/Documentation/devicetree/bindings/clock/imx8mn-clock.yaml index 622f3658bd9f..cd0b8a341321 100644 --- a/Documentation/devicetree/bindings/clock/imx8mn-clock.yaml +++ b/Documentation/devicetree/bindings/clock/imx8mn-clock.yaml @@ -1,7 +1,7 @@ # SPDX-License-Identifier: GPL-2.0 %YAML 1.2 --- -$id: http://devicetree.org/schemas/bindings/clock/imx8mn-clock.yaml# +$id: http://devicetree.org/schemas/clock/imx8mn-clock.yaml# $schema: http://devicetree.org/meta-schemas/core.yaml# title: NXP i.MX8M Nano Clock Control Module Binding diff --git a/Documentation/devicetree/bindings/clock/imx8mp-clock.yaml b/Documentation/devicetree/bindings/clock/imx8mp-clock.yaml new file mode 100644 index 000000000000..89aee63c9019 --- /dev/null +++ b/Documentation/devicetree/bindings/clock/imx8mp-clock.yaml @@ -0,0 +1,68 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/clock/imx8mp-clock.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: NXP i.MX8M Plus Clock Control Module Binding + +maintainers: + - Anson Huang <Anson.Huang@nxp.com> + +description: + NXP i.MX8M Plus clock control module is an integrated clock controller, which + generates and supplies to all modules. + +properties: + compatible: + const: fsl,imx8mp-ccm + + reg: + maxItems: 1 + + clocks: + items: + - description: 32k osc + - description: 24m osc + - description: ext1 clock input + - description: ext2 clock input + - description: ext3 clock input + - description: ext4 clock input + + clock-names: + items: + - const: osc_32k + - const: osc_24m + - const: clk_ext1 + - const: clk_ext2 + - const: clk_ext3 + - const: clk_ext4 + + '#clock-cells': + const: 1 + description: + The clock consumer should specify the desired clock by having the clock + ID in its "clocks" phandle cell. See include/dt-bindings/clock/imx8mp-clock.h + for the full list of i.MX8M Plus clock IDs. + +required: + - compatible + - reg + - clocks + - clock-names + - '#clock-cells' + +examples: + # Clock Control Module node: + - | + clk: clock-controller@30380000 { + compatible = "fsl,imx8mp-ccm"; + reg = <0x30380000 0x10000>; + #clock-cells = <1>; + clocks = <&osc_32k>, <&osc_24m>, <&clk_ext1>, + <&clk_ext2>, <&clk_ext3>, <&clk_ext4>; + clock-names = "osc_32k", "osc_24m", "clk_ext1", + "clk_ext2", "clk_ext3", "clk_ext4"; + }; + +... diff --git a/Documentation/devicetree/bindings/clock/milbeaut-clock.yaml b/Documentation/devicetree/bindings/clock/milbeaut-clock.yaml index 5cf0b811821e..f0b804a7f096 100644 --- a/Documentation/devicetree/bindings/clock/milbeaut-clock.yaml +++ b/Documentation/devicetree/bindings/clock/milbeaut-clock.yaml @@ -1,7 +1,7 @@ # SPDX-License-Identifier: GPL-2.0 %YAML 1.2 --- -$id: http://devicetree.org/schemas/bindings/clock/milbeaut-clock.yaml# +$id: http://devicetree.org/schemas/clock/milbeaut-clock.yaml# $schema: http://devicetree.org/meta-schemas/core.yaml# title: Milbeaut SoCs Clock Controller Binding diff --git a/Documentation/devicetree/bindings/clock/qcom,dispcc.txt b/Documentation/devicetree/bindings/clock/qcom,dispcc.txt deleted file mode 100644 index d639e18d0b85..000000000000 --- a/Documentation/devicetree/bindings/clock/qcom,dispcc.txt +++ /dev/null @@ -1,19 +0,0 @@ -Qualcomm Technologies, Inc. Display Clock Controller Binding ------------------------------------------------------------- - -Required properties : - -- compatible : shall contain "qcom,sdm845-dispcc" -- reg : shall contain base register location and length. -- #clock-cells : from common clock binding, shall contain 1. -- #reset-cells : from common reset binding, shall contain 1. -- #power-domain-cells : from generic power domain binding, shall contain 1. - -Example: - dispcc: clock-controller@af00000 { - compatible = "qcom,sdm845-dispcc"; - reg = <0xaf00000 0x100000>; - #clock-cells = <1>; - #reset-cells = <1>; - #power-domain-cells = <1>; - }; diff --git a/Documentation/devicetree/bindings/clock/qcom,gcc-apq8064.yaml b/Documentation/devicetree/bindings/clock/qcom,gcc-apq8064.yaml new file mode 100644 index 000000000000..17f87178f6b8 --- /dev/null +++ b/Documentation/devicetree/bindings/clock/qcom,gcc-apq8064.yaml @@ -0,0 +1,83 @@ +# SPDX-License-Identifier: GPL-2.0-only +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/clock/qcom,gcc-apq8064.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Qualcomm Global Clock & Reset Controller Binding for APQ8064 + +maintainers: + - Stephen Boyd <sboyd@kernel.org> + - Taniya Das <tdas@codeaurora.org> + +description: | + Qualcomm global clock control module which supports the clocks, resets and + power domains on APQ8064. + + See also: + - dt-bindings/clock/qcom,gcc-msm8960.h + - dt-bindings/reset/qcom,gcc-msm8960.h + +properties: + compatible: + const: qcom,gcc-apq8064 + + '#clock-cells': + const: 1 + + '#reset-cells': + const: 1 + + '#power-domain-cells': + const: 1 + + reg: + maxItems: 1 + + nvmem-cells: + minItems: 1 + maxItems: 2 + description: + Qualcomm TSENS (thermal sensor device) on some devices can + be part of GCC and hence the TSENS properties can also be part + of the GCC/clock-controller node. + For more details on the TSENS properties please refer + Documentation/devicetree/bindings/thermal/qcom-tsens.txt + + nvmem-cell-names: + minItems: 1 + maxItems: 2 + items: + - const: calib + - const: calib_backup + + '#thermal-sensor-cells': + const: 1 + + protected-clocks: + description: + Protected clock specifier list as per common clock binding. + +required: + - compatible + - reg + - '#clock-cells' + - '#reset-cells' + - '#power-domain-cells' + - nvmem-cells + - nvmem-cell-names + - '#thermal-sensor-cells' + +examples: + - | + clock-controller@900000 { + compatible = "qcom,gcc-apq8064"; + reg = <0x00900000 0x4000>; + nvmem-cells = <&tsens_calib>, <&tsens_backup>; + nvmem-cell-names = "calib", "calib_backup"; + #clock-cells = <1>; + #reset-cells = <1>; + #power-domain-cells = <1>; + #thermal-sensor-cells = <1>; + }; +... diff --git a/Documentation/devicetree/bindings/clock/qcom,gcc-ipq8074.yaml b/Documentation/devicetree/bindings/clock/qcom,gcc-ipq8074.yaml new file mode 100644 index 000000000000..89c6e070e7ac --- /dev/null +++ b/Documentation/devicetree/bindings/clock/qcom,gcc-ipq8074.yaml @@ -0,0 +1,51 @@ +# SPDX-License-Identifier: GPL-2.0-only +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/clock/qcom,gcc-ipq8074.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Qualcomm Global Clock & Reset Controller Bindingfor IPQ8074 + +maintainers: + - Stephen Boyd <sboyd@kernel.org> + - Taniya Das <tdas@codeaurora.org> + +description: | + Qualcomm global clock control module which supports the clocks, resets and + power domains on IPQ8074. + + See also: + - dt-bindings/clock/qcom,gcc-ipq8074.h + +properties: + compatible: + const: qcom,gcc-ipq8074 + + '#clock-cells': + const: 1 + + '#reset-cells': + const: 1 + + reg: + maxItems: 1 + + protected-clocks: + description: + Protected clock specifier list as per common clock binding. + +required: + - compatible + - reg + - '#clock-cells' + - '#reset-cells' + +examples: + - | + clock-controller@1800000 { + compatible = "qcom,gcc-ipq8074"; + reg = <0x01800000 0x80000>; + #clock-cells = <1>; + #reset-cells = <1>; + }; +... diff --git a/Documentation/devicetree/bindings/clock/qcom,gcc-msm8996.yaml b/Documentation/devicetree/bindings/clock/qcom,gcc-msm8996.yaml new file mode 100644 index 000000000000..18e4e77b8cfa --- /dev/null +++ b/Documentation/devicetree/bindings/clock/qcom,gcc-msm8996.yaml @@ -0,0 +1,68 @@ +# SPDX-License-Identifier: GPL-2.0-only +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/clock/qcom,gcc-msm8996.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Qualcomm Global Clock & Reset Controller Binding for MSM8996 + +maintainers: + - Stephen Boyd <sboyd@kernel.org> + - Taniya Das <tdas@codeaurora.org> + +description: | + Qualcomm global clock control module which supports the clocks, resets and + power domains on MSM8996. + + See also: + - dt-bindings/clock/qcom,gcc-msm8996.h + +properties: + compatible: + const: qcom,gcc-msm8996 + + clocks: + items: + - description: XO source + - description: Second XO source + - description: Sleep clock source + + clock-names: + items: + - const: cxo + - const: cxo2 + - const: sleep_clk + + '#clock-cells': + const: 1 + + '#reset-cells': + const: 1 + + '#power-domain-cells': + const: 1 + + reg: + maxItems: 1 + + protected-clocks: + description: + Protected clock specifier list as per common clock binding. + +required: + - compatible + - reg + - '#clock-cells' + - '#reset-cells' + - '#power-domain-cells' + +examples: + - | + clock-controller@300000 { + compatible = "qcom,gcc-msm8996"; + #clock-cells = <1>; + #reset-cells = <1>; + #power-domain-cells = <1>; + reg = <0x300000 0x90000>; + }; +... diff --git a/Documentation/devicetree/bindings/clock/qcom,gcc-msm8998.yaml b/Documentation/devicetree/bindings/clock/qcom,gcc-msm8998.yaml new file mode 100644 index 000000000000..1d3cae980471 --- /dev/null +++ b/Documentation/devicetree/bindings/clock/qcom,gcc-msm8998.yaml @@ -0,0 +1,93 @@ +# SPDX-License-Identifier: GPL-2.0-only +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/clock/qcom,gcc-msm8998.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Qualcomm Global Clock & Reset Controller Binding for MSM8998 + +maintainers: + - Stephen Boyd <sboyd@kernel.org> + - Taniya Das <tdas@codeaurora.org> + +description: | + Qualcomm global clock control module which supports the clocks, resets and + power domains on MSM8998. + + See also: + - dt-bindings/clock/qcom,gcc-msm8998.h + +properties: + compatible: + const: qcom,gcc-msm8998 + + clocks: + items: + - description: Board XO source + - description: Sleep clock source + - description: USB 3.0 phy pipe clock + - description: UFS phy rx symbol clock for pipe 0 + - description: UFS phy rx symbol clock for pipe 1 + - description: UFS phy tx symbol clock + - description: PCIE phy pipe clock + + clock-names: + items: + - const: xo + - const: sleep_clk + - const: usb3_pipe + - const: ufs_rx_symbol0 + - const: ufs_rx_symbol1 + - const: ufs_tx_symbol0 + - const: pcie0_pipe + + '#clock-cells': + const: 1 + + '#reset-cells': + const: 1 + + '#power-domain-cells': + const: 1 + + reg: + maxItems: 1 + + protected-clocks: + description: + Protected clock specifier list as per common clock binding. + +required: + - compatible + - clocks + - clock-names + - reg + - '#clock-cells' + - '#reset-cells' + - '#power-domain-cells' + +examples: + - | + #include <dt-bindings/clock/qcom,rpmcc.h> + clock-controller@100000 { + compatible = "qcom,gcc-msm8998"; + #clock-cells = <1>; + #reset-cells = <1>; + #power-domain-cells = <1>; + reg = <0x00100000 0xb0000>; + clocks = <&rpmcc RPM_SMD_XO_CLK_SRC>, + <&sleep>, + <0>, + <0>, + <0>, + <0>, + <0>; + clock-names = "xo", + "sleep_clk", + "usb3_pipe", + "ufs_rx_symbol0", + "ufs_rx_symbol1", + "ufs_tx_symbol0", + "pcie0_pipe"; + }; +... diff --git a/Documentation/devicetree/bindings/clock/qcom,gcc-qcs404.yaml b/Documentation/devicetree/bindings/clock/qcom,gcc-qcs404.yaml new file mode 100644 index 000000000000..8cdece395eba --- /dev/null +++ b/Documentation/devicetree/bindings/clock/qcom,gcc-qcs404.yaml @@ -0,0 +1,51 @@ +# SPDX-License-Identifier: GPL-2.0-only +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/clock/qcom,gcc-qcs404.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Qualcomm Global Clock & Reset Controller Bindingfor QCS404 + +maintainers: + - Stephen Boyd <sboyd@kernel.org> + - Taniya Das <tdas@codeaurora.org> + +description: | + Qualcomm global clock control module which supports the clocks, resets and + power domains on QCS404. + + See also: + - dt-bindings/clock/qcom,gcc-qcs404.h + +properties: + compatible: + const: qcom,gcc-qcs404 + + '#clock-cells': + const: 1 + + '#reset-cells': + const: 1 + + reg: + maxItems: 1 + + protected-clocks: + description: + Protected clock specifier list as per common clock binding. + +required: + - compatible + - reg + - '#clock-cells' + - '#reset-cells' + +examples: + - | + clock-controller@1800000 { + compatible = "qcom,gcc-qcs404"; + reg = <0x01800000 0x80000>; + #clock-cells = <1>; + #reset-cells = <1>; + }; +... diff --git a/Documentation/devicetree/bindings/clock/qcom,gcc-sc7180.yaml b/Documentation/devicetree/bindings/clock/qcom,gcc-sc7180.yaml new file mode 100644 index 000000000000..ee4f968e2909 --- /dev/null +++ b/Documentation/devicetree/bindings/clock/qcom,gcc-sc7180.yaml @@ -0,0 +1,75 @@ +# SPDX-License-Identifier: GPL-2.0-only +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/clock/qcom,gcc-sc7180.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Qualcomm Global Clock & Reset Controller Binding for SC7180 + +maintainers: + - Stephen Boyd <sboyd@kernel.org> + - Taniya Das <tdas@codeaurora.org> + +description: | + Qualcomm global clock control module which supports the clocks, resets and + power domains on SC7180. + + See also: + - dt-bindings/clock/qcom,gcc-sc7180.h + +properties: + compatible: + const: qcom,gcc-sc7180 + + clocks: + items: + - description: Board XO source + - description: Board active XO source + - description: Sleep clock source + + clock-names: + items: + - const: bi_tcxo + - const: bi_tcxo_ao + - const: sleep_clk + + '#clock-cells': + const: 1 + + '#reset-cells': + const: 1 + + '#power-domain-cells': + const: 1 + + reg: + maxItems: 1 + + protected-clocks: + description: + Protected clock specifier list as per common clock binding. + +required: + - compatible + - clocks + - clock-names + - reg + - '#clock-cells' + - '#reset-cells' + - '#power-domain-cells' + +examples: + - | + #include <dt-bindings/clock/qcom,rpmh.h> + clock-controller@100000 { + compatible = "qcom,gcc-sc7180"; + reg = <0 0x00100000 0 0x1f0000>; + clocks = <&rpmhcc RPMH_CXO_CLK>, + <&rpmhcc RPMH_CXO_CLK_A>, + <&sleep_clk>; + clock-names = "bi_tcxo", "bi_tcxo_ao", "sleep_clk"; + #clock-cells = <1>; + #reset-cells = <1>; + #power-domain-cells = <1>; + }; +... diff --git a/Documentation/devicetree/bindings/clock/qcom,gcc-sm8150.yaml b/Documentation/devicetree/bindings/clock/qcom,gcc-sm8150.yaml new file mode 100644 index 000000000000..888e9a708390 --- /dev/null +++ b/Documentation/devicetree/bindings/clock/qcom,gcc-sm8150.yaml @@ -0,0 +1,72 @@ +# SPDX-License-Identifier: GPL-2.0-only +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/clock/qcom,gcc-sm8150.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Qualcomm Global Clock & Reset Controller Binding for SM8150 + +maintainers: + - Stephen Boyd <sboyd@kernel.org> + - Taniya Das <tdas@codeaurora.org> + +description: | + Qualcomm global clock control module which supports the clocks, resets and + power domains on SM8150. + + See also: + - dt-bindings/clock/qcom,gcc-sm8150.h + +properties: + compatible: + const: qcom,gcc-sm8150 + + clocks: + items: + - description: Board XO source + - description: Sleep clock source + + clock-names: + items: + - const: bi_tcxo + - const: sleep_clk + + '#clock-cells': + const: 1 + + '#reset-cells': + const: 1 + + '#power-domain-cells': + const: 1 + + reg: + maxItems: 1 + + protected-clocks: + description: + Protected clock specifier list as per common clock binding. + +required: + - compatible + - clocks + - clock-names + - reg + - '#clock-cells' + - '#reset-cells' + - '#power-domain-cells' + +examples: + - | + #include <dt-bindings/clock/qcom,rpmh.h> + clock-controller@100000 { + compatible = "qcom,gcc-sm8150"; + reg = <0 0x00100000 0 0x1f0000>; + clocks = <&rpmhcc RPMH_CXO_CLK>, + <&sleep_clk>; + clock-names = "bi_tcxo", "sleep_clk"; + #clock-cells = <1>; + #reset-cells = <1>; + #power-domain-cells = <1>; + }; +... diff --git a/Documentation/devicetree/bindings/clock/qcom,gcc.yaml b/Documentation/devicetree/bindings/clock/qcom,gcc.yaml index e73a56fb60ca..d18f8ab9eeee 100644 --- a/Documentation/devicetree/bindings/clock/qcom,gcc.yaml +++ b/Documentation/devicetree/bindings/clock/qcom,gcc.yaml @@ -1,7 +1,7 @@ # SPDX-License-Identifier: GPL-2.0-only %YAML 1.2 --- -$id: http://devicetree.org/schemas/bindings/clock/qcom,gcc.yaml# +$id: http://devicetree.org/schemas/clock/qcom,gcc.yaml# $schema: http://devicetree.org/meta-schemas/core.yaml# title: Qualcomm Global Clock & Reset Controller Binding @@ -14,46 +14,42 @@ description: | Qualcomm global clock control module which supports the clocks, resets and power domains. + See also: + - dt-bindings/clock/qcom,gcc-apq8084.h + - dt-bindings/reset/qcom,gcc-apq8084.h + - dt-bindings/clock/qcom,gcc-ipq4019.h + - dt-bindings/clock/qcom,gcc-ipq6018.h + - dt-bindings/reset/qcom,gcc-ipq6018.h + - dt-bindings/clock/qcom,gcc-ipq806x.h (qcom,gcc-ipq8064) + - dt-bindings/reset/qcom,gcc-ipq806x.h (qcom,gcc-ipq8064) + - dt-bindings/clock/qcom,gcc-msm8660.h + - dt-bindings/reset/qcom,gcc-msm8660.h + - dt-bindings/clock/qcom,gcc-msm8974.h + - dt-bindings/reset/qcom,gcc-msm8974.h + - dt-bindings/clock/qcom,gcc-msm8994.h + - dt-bindings/clock/qcom,gcc-mdm9615.h + - dt-bindings/reset/qcom,gcc-mdm9615.h + - dt-bindings/clock/qcom,gcc-sdm660.h (qcom,gcc-sdm630 and qcom,gcc-sdm660) + - dt-bindings/clock/qcom,gcc-sdm845.h + properties: - compatible : + compatible: enum: - - qcom,gcc-apq8064 - - qcom,gcc-apq8084 - - qcom,gcc-ipq8064 - - qcom,gcc-ipq4019 - - qcom,gcc-ipq8074 - - qcom,gcc-msm8660 - - qcom,gcc-msm8916 - - qcom,gcc-msm8960 - - qcom,gcc-msm8974 - - qcom,gcc-msm8974pro - - qcom,gcc-msm8974pro-ac - - qcom,gcc-msm8994 - - qcom,gcc-msm8996 - - qcom,gcc-msm8998 - - qcom,gcc-mdm9615 - - qcom,gcc-qcs404 - - qcom,gcc-sc7180 - - qcom,gcc-sdm630 - - qcom,gcc-sdm660 - - qcom,gcc-sdm845 - - qcom,gcc-sm8150 - - clocks: - minItems: 1 - maxItems: 3 - items: - - description: Board XO source - - description: Board active XO source - - description: Sleep clock source - - clock-names: - minItems: 1 - maxItems: 3 - items: - - const: bi_tcxo - - const: bi_tcxo_ao - - const: sleep_clk + - qcom,gcc-apq8084 + - qcom,gcc-ipq4019 + - qcom,gcc-ipq6018 + - qcom,gcc-ipq8064 + - qcom,gcc-msm8660 + - qcom,gcc-msm8916 + - qcom,gcc-msm8960 + - qcom,gcc-msm8974 + - qcom,gcc-msm8974pro + - qcom,gcc-msm8974pro-ac + - qcom,gcc-msm8994 + - qcom,gcc-mdm9615 + - qcom,gcc-sdm630 + - qcom,gcc-sdm660 + - qcom,gcc-sdm845 '#clock-cells': const: 1 @@ -67,31 +63,9 @@ properties: reg: maxItems: 1 - nvmem-cells: - minItems: 1 - maxItems: 2 - description: - Qualcomm TSENS (thermal sensor device) on some devices can - be part of GCC and hence the TSENS properties can also be part - of the GCC/clock-controller node. - For more details on the TSENS properties please refer - Documentation/devicetree/bindings/thermal/qcom-tsens.txt - - nvmem-cell-names: - minItems: 1 - maxItems: 2 - description: - Names for each nvmem-cells specified. - items: - - const: calib - - const: calib_backup - - 'thermal-sensor-cells': - const: 1 - protected-clocks: description: - Protected clock specifier list as per common clock binding + Protected clock specifier list as per common clock binding. required: - compatible @@ -100,32 +74,6 @@ required: - '#reset-cells' - '#power-domain-cells' -if: - properties: - compatible: - contains: - const: qcom,gcc-apq8064 - -then: - required: - - nvmem-cells - - nvmem-cell-names - - '#thermal-sensor-cells' - -else: - if: - properties: - compatible: - contains: - enum: - - qcom,gcc-sm8150 - - qcom,gcc-sc7180 - then: - required: - - clocks - - clock-names - - examples: # Example for GCC for MSM8960: - | @@ -136,53 +84,4 @@ examples: #reset-cells = <1>; #power-domain-cells = <1>; }; - - - # Example of GCC with TSENS properties: - - | - clock-controller@900000 { - compatible = "qcom,gcc-apq8064"; - reg = <0x00900000 0x4000>; - nvmem-cells = <&tsens_calib>, <&tsens_backup>; - nvmem-cell-names = "calib", "calib_backup"; - #clock-cells = <1>; - #reset-cells = <1>; - #power-domain-cells = <1>; - #thermal-sensor-cells = <1>; - }; - - # Example of GCC with protected-clocks properties: - - | - clock-controller@100000 { - compatible = "qcom,gcc-sdm845"; - reg = <0x100000 0x1f0000>; - protected-clocks = <187>, <188>, <189>, <190>, <191>; - #clock-cells = <1>; - #reset-cells = <1>; - #power-domain-cells = <1>; - }; - - # Example of GCC with clock node properties for SM8150: - - | - clock-controller@100000 { - compatible = "qcom,gcc-sm8150"; - reg = <0x00100000 0x1f0000>; - clocks = <&rpmhcc 0>, <&rpmhcc 1>, <&sleep_clk>; - clock-names = "bi_tcxo", "bi_tcxo_ao", "sleep_clk"; - #clock-cells = <1>; - #reset-cells = <1>; - #power-domain-cells = <1>; - }; - - # Example of GCC with clock nodes properties for SC7180: - - | - clock-controller@100000 { - compatible = "qcom,gcc-sc7180"; - reg = <0x100000 0x1f0000>; - clocks = <&rpmhcc 0>, <&rpmhcc 1>; - clock-names = "bi_tcxo", "bi_tcxo_ao"; - #clock-cells = <1>; - #reset-cells = <1>; - #power-domain-cells = <1>; - }; ... diff --git a/Documentation/devicetree/bindings/clock/qcom,gpucc.txt b/Documentation/devicetree/bindings/clock/qcom,gpucc.txt deleted file mode 100644 index 269afe8a757e..000000000000 --- a/Documentation/devicetree/bindings/clock/qcom,gpucc.txt +++ /dev/null @@ -1,24 +0,0 @@ -Qualcomm Graphics Clock & Reset Controller Binding --------------------------------------------------- - -Required properties : -- compatible : shall contain "qcom,sdm845-gpucc" or "qcom,msm8998-gpucc" -- reg : shall contain base register location and length -- #clock-cells : from common clock binding, shall contain 1 -- #reset-cells : from common reset binding, shall contain 1 -- #power-domain-cells : from generic power domain binding, shall contain 1 -- clocks : shall contain the XO clock - shall contain the gpll0 out main clock (msm8998) -- clock-names : shall be "xo" - shall be "gpll0" (msm8998) - -Example: - gpucc: clock-controller@5090000 { - compatible = "qcom,sdm845-gpucc"; - reg = <0x5090000 0x9000>; - #clock-cells = <1>; - #reset-cells = <1>; - #power-domain-cells = <1>; - clocks = <&rpmhcc RPMH_CXO_CLK>; - clock-names = "xo"; - }; diff --git a/Documentation/devicetree/bindings/clock/qcom,mmcc.txt b/Documentation/devicetree/bindings/clock/qcom,mmcc.txt deleted file mode 100644 index 8b0f7841af8d..000000000000 --- a/Documentation/devicetree/bindings/clock/qcom,mmcc.txt +++ /dev/null @@ -1,28 +0,0 @@ -Qualcomm Multimedia Clock & Reset Controller Binding ----------------------------------------------------- - -Required properties : -- compatible : shall contain only one of the following: - - "qcom,mmcc-apq8064" - "qcom,mmcc-apq8084" - "qcom,mmcc-msm8660" - "qcom,mmcc-msm8960" - "qcom,mmcc-msm8974" - "qcom,mmcc-msm8996" - -- reg : shall contain base register location and length -- #clock-cells : shall contain 1 -- #reset-cells : shall contain 1 - -Optional properties : -- #power-domain-cells : shall contain 1 - -Example: - clock-controller@4000000 { - compatible = "qcom,mmcc-msm8960"; - reg = <0x4000000 0x1000>; - #clock-cells = <1>; - #reset-cells = <1>; - #power-domain-cells = <1>; - }; diff --git a/Documentation/devicetree/bindings/clock/qcom,mmcc.yaml b/Documentation/devicetree/bindings/clock/qcom,mmcc.yaml new file mode 100644 index 000000000000..85518494ce43 --- /dev/null +++ b/Documentation/devicetree/bindings/clock/qcom,mmcc.yaml @@ -0,0 +1,98 @@ +# SPDX-License-Identifier: GPL-2.0-only +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/clock/qcom,mmcc.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Qualcomm Multimedia Clock & Reset Controller Binding + +maintainers: + - Jeffrey Hugo <jhugo@codeaurora.org> + - Taniya Das <tdas@codeaurora.org> + +description: | + Qualcomm multimedia clock control module which supports the clocks, resets and + power domains. + +properties: + compatible : + enum: + - qcom,mmcc-apq8064 + - qcom,mmcc-apq8084 + - qcom,mmcc-msm8660 + - qcom,mmcc-msm8960 + - qcom,mmcc-msm8974 + - qcom,mmcc-msm8996 + - qcom,mmcc-msm8998 + + clocks: + items: + - description: Board XO source + - description: Board sleep source + - description: Global PLL 0 clock + - description: DSI phy instance 0 dsi clock + - description: DSI phy instance 0 byte clock + - description: DSI phy instance 1 dsi clock + - description: DSI phy instance 1 byte clock + - description: HDMI phy PLL clock + - description: DisplayPort phy PLL vco clock + - description: DisplayPort phy PLL link clock + + clock-names: + items: + - const: xo + - const: sleep + - const: gpll0 + - const: dsi0dsi + - const: dsi0byte + - const: dsi1dsi + - const: dsi1byte + - const: hdmipll + - const: dpvco + - const: dplink + + '#clock-cells': + const: 1 + + '#reset-cells': + const: 1 + + '#power-domain-cells': + const: 1 + + reg: + maxItems: 1 + + protected-clocks: + description: + Protected clock specifier list as per common clock binding + +required: + - compatible + - reg + - '#clock-cells' + - '#reset-cells' + - '#power-domain-cells' + +if: + properties: + compatible: + contains: + const: qcom,mmcc-msm8998 + +then: + required: + - clocks + - clock-names + +examples: + # Example for MMCC for MSM8960: + - | + clock-controller@4000000 { + compatible = "qcom,mmcc-msm8960"; + reg = <0x4000000 0x1000>; + #clock-cells = <1>; + #reset-cells = <1>; + #power-domain-cells = <1>; + }; +... diff --git a/Documentation/devicetree/bindings/clock/qcom,msm8998-gpucc.yaml b/Documentation/devicetree/bindings/clock/qcom,msm8998-gpucc.yaml new file mode 100644 index 000000000000..7d853c1a85e5 --- /dev/null +++ b/Documentation/devicetree/bindings/clock/qcom,msm8998-gpucc.yaml @@ -0,0 +1,66 @@ +# SPDX-License-Identifier: GPL-2.0-only +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/clock/qcom,msm8998-gpucc.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Qualcomm Graphics Clock & Reset Controller Binding for MSM8998 + +maintainers: + - Taniya Das <tdas@codeaurora.org> + +description: | + Qualcomm graphics clock control module which supports the clocks, resets and + power domains on MSM8998. + + See also dt-bindings/clock/qcom,gpucc-msm8998.h. + +properties: + compatible: + const: qcom,msm8998-gpucc + + clocks: + items: + - description: Board XO source + - description: GPLL0 main branch source (gcc_gpu_gpll0_clk_src) + + clock-names: + items: + - const: xo + - const: gpll0 + + '#clock-cells': + const: 1 + + '#reset-cells': + const: 1 + + '#power-domain-cells': + const: 1 + + reg: + maxItems: 1 + +required: + - compatible + - reg + - clocks + - clock-names + - '#clock-cells' + - '#reset-cells' + - '#power-domain-cells' + +examples: + - | + #include <dt-bindings/clock/qcom,gcc-msm8998.h> + #include <dt-bindings/clock/qcom,rpmcc.h> + clock-controller@5065000 { + compatible = "qcom,msm8998-gpucc"; + #clock-cells = <1>; + #reset-cells = <1>; + #power-domain-cells = <1>; + reg = <0x05065000 0x9000>; + clocks = <&rpmcc RPM_SMD_XO_CLK_SRC>, <&gcc GPLL0_OUT_MAIN>; + clock-names = "xo", "gpll0"; + }; +... diff --git a/Documentation/devicetree/bindings/clock/qcom,rpmhcc.yaml b/Documentation/devicetree/bindings/clock/qcom,rpmhcc.yaml index 94e2f14eb967..2cd158f13bab 100644 --- a/Documentation/devicetree/bindings/clock/qcom,rpmhcc.yaml +++ b/Documentation/devicetree/bindings/clock/qcom,rpmhcc.yaml @@ -1,7 +1,7 @@ # SPDX-License-Identifier: GPL-2.0-only %YAML 1.2 --- -$id: http://devicetree.org/schemas/bindings/clock/qcom,rpmhcc.yaml# +$id: http://devicetree.org/schemas/clock/qcom,rpmhcc.yaml# $schema: http://devicetree.org/meta-schemas/core.yaml# title: Qualcomm Technologies, Inc. RPMh Clocks Bindings diff --git a/Documentation/devicetree/bindings/clock/qcom,sc7180-dispcc.yaml b/Documentation/devicetree/bindings/clock/qcom,sc7180-dispcc.yaml new file mode 100644 index 000000000000..0429062f1585 --- /dev/null +++ b/Documentation/devicetree/bindings/clock/qcom,sc7180-dispcc.yaml @@ -0,0 +1,84 @@ +# SPDX-License-Identifier: GPL-2.0-only +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/clock/qcom,sc7180-dispcc.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Qualcomm Display Clock & Reset Controller Binding for SC7180 + +maintainers: + - Taniya Das <tdas@codeaurora.org> + +description: | + Qualcomm display clock control module which supports the clocks, resets and + power domains on SC7180. + + See also dt-bindings/clock/qcom,dispcc-sc7180.h. + +properties: + compatible: + const: qcom,sc7180-dispcc + + clocks: + items: + - description: Board XO source + - description: GPLL0 source from GCC + - description: Byte clock from DSI PHY + - description: Pixel clock from DSI PHY + - description: Link clock from DP PHY + - description: VCO DIV clock from DP PHY + + clock-names: + items: + - const: bi_tcxo + - const: gcc_disp_gpll0_clk_src + - const: dsi0_phy_pll_out_byteclk + - const: dsi0_phy_pll_out_dsiclk + - const: dp_phy_pll_link_clk + - const: dp_phy_pll_vco_div_clk + + '#clock-cells': + const: 1 + + '#reset-cells': + const: 1 + + '#power-domain-cells': + const: 1 + + reg: + maxItems: 1 + +required: + - compatible + - reg + - clocks + - clock-names + - '#clock-cells' + - '#reset-cells' + - '#power-domain-cells' + +examples: + - | + #include <dt-bindings/clock/qcom,gcc-sc7180.h> + #include <dt-bindings/clock/qcom,rpmh.h> + clock-controller@af00000 { + compatible = "qcom,sc7180-dispcc"; + reg = <0 0x0af00000 0 0x200000>; + clocks = <&rpmhcc RPMH_CXO_CLK>, + <&gcc GCC_DISP_GPLL0_CLK_SRC>, + <&dsi_phy 0>, + <&dsi_phy 1>, + <&dp_phy 0>, + <&dp_phy 1>; + clock-names = "bi_tcxo", + "gcc_disp_gpll0_clk_src", + "dsi0_phy_pll_out_byteclk", + "dsi0_phy_pll_out_dsiclk", + "dp_phy_pll_link_clk", + "dp_phy_pll_vco_div_clk"; + #clock-cells = <1>; + #reset-cells = <1>; + #power-domain-cells = <1>; + }; +... diff --git a/Documentation/devicetree/bindings/clock/qcom,sc7180-gpucc.yaml b/Documentation/devicetree/bindings/clock/qcom,sc7180-gpucc.yaml new file mode 100644 index 000000000000..5785192cc4be --- /dev/null +++ b/Documentation/devicetree/bindings/clock/qcom,sc7180-gpucc.yaml @@ -0,0 +1,72 @@ +# SPDX-License-Identifier: GPL-2.0-only +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/clock/qcom,sc7180-gpucc.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Qualcomm Graphics Clock & Reset Controller Binding for SC7180 + +maintainers: + - Taniya Das <tdas@codeaurora.org> + +description: | + Qualcomm graphics clock control module which supports the clocks, resets and + power domains on SC7180. + + See also dt-bindings/clock/qcom,gpucc-sc7180.h. + +properties: + compatible: + const: qcom,sc7180-gpucc + + clocks: + items: + - description: Board XO source + - description: GPLL0 main branch source + - description: GPLL0 div branch source + + clock-names: + items: + - const: bi_tcxo + - const: gcc_gpu_gpll0_clk_src + - const: gcc_gpu_gpll0_div_clk_src + + '#clock-cells': + const: 1 + + '#reset-cells': + const: 1 + + '#power-domain-cells': + const: 1 + + reg: + maxItems: 1 + +required: + - compatible + - reg + - clocks + - clock-names + - '#clock-cells' + - '#reset-cells' + - '#power-domain-cells' + +examples: + - | + #include <dt-bindings/clock/qcom,gcc-sc7180.h> + #include <dt-bindings/clock/qcom,rpmh.h> + clock-controller@5090000 { + compatible = "qcom,sc7180-gpucc"; + reg = <0 0x05090000 0 0x9000>; + clocks = <&rpmhcc RPMH_CXO_CLK>, + <&gcc GCC_GPU_GPLL0_CLK_SRC>, + <&gcc GCC_GPU_GPLL0_DIV_CLK_SRC>; + clock-names = "bi_tcxo", + "gcc_gpu_gpll0_clk_src", + "gcc_gpu_gpll0_div_clk_src"; + #clock-cells = <1>; + #reset-cells = <1>; + #power-domain-cells = <1>; + }; +... diff --git a/Documentation/devicetree/bindings/clock/qcom,sc7180-videocc.yaml b/Documentation/devicetree/bindings/clock/qcom,sc7180-videocc.yaml new file mode 100644 index 000000000000..31df901884ac --- /dev/null +++ b/Documentation/devicetree/bindings/clock/qcom,sc7180-videocc.yaml @@ -0,0 +1,63 @@ +# SPDX-License-Identifier: GPL-2.0-only +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/clock/qcom,sc7180-videocc.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Qualcomm Video Clock & Reset Controller Binding for SC7180 + +maintainers: + - Taniya Das <tdas@codeaurora.org> + +description: | + Qualcomm video clock control module which supports the clocks, resets and + power domains on SC7180. + + See also dt-bindings/clock/qcom,videocc-sc7180.h. + +properties: + compatible: + const: qcom,sc7180-videocc + + clocks: + items: + - description: Board XO source + + clock-names: + items: + - const: bi_tcxo + + '#clock-cells': + const: 1 + + '#reset-cells': + const: 1 + + '#power-domain-cells': + const: 1 + + reg: + maxItems: 1 + +required: + - compatible + - reg + - clocks + - clock-names + - '#clock-cells' + - '#reset-cells' + - '#power-domain-cells' + +examples: + - | + #include <dt-bindings/clock/qcom,rpmh.h> + clock-controller@ab00000 { + compatible = "qcom,sc7180-videocc"; + reg = <0 0x0ab00000 0 0x10000>; + clocks = <&rpmhcc RPMH_CXO_CLK>; + clock-names = "bi_tcxo"; + #clock-cells = <1>; + #reset-cells = <1>; + #power-domain-cells = <1>; + }; +... diff --git a/Documentation/devicetree/bindings/clock/qcom,sdm845-dispcc.yaml b/Documentation/devicetree/bindings/clock/qcom,sdm845-dispcc.yaml new file mode 100644 index 000000000000..89269ddfbdcd --- /dev/null +++ b/Documentation/devicetree/bindings/clock/qcom,sdm845-dispcc.yaml @@ -0,0 +1,99 @@ +# SPDX-License-Identifier: GPL-2.0-only +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/clock/qcom,sdm845-dispcc.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Qualcomm Display Clock & Reset Controller Binding for SDM845 + +maintainers: + - Taniya Das <tdas@codeaurora.org> + +description: | + Qualcomm display clock control module which supports the clocks, resets and + power domains on SDM845. + + See also dt-bindings/clock/qcom,dispcc-sdm845.h. + +properties: + compatible: + const: qcom,sdm845-dispcc + + # NOTE: sdm845.dtsi existed for quite some time and specified no clocks. + # The code had to use hardcoded mechanisms to find the input clocks. + # New dts files should have these clocks. + clocks: + items: + - description: Board XO source + - description: GPLL0 source from GCC + - description: GPLL0 div source from GCC + - description: Byte clock from DSI PHY0 + - description: Pixel clock from DSI PHY0 + - description: Byte clock from DSI PHY1 + - description: Pixel clock from DSI PHY1 + - description: Link clock from DP PHY + - description: VCO DIV clock from DP PHY + + clock-names: + items: + - const: bi_tcxo + - const: gcc_disp_gpll0_clk_src + - const: gcc_disp_gpll0_div_clk_src + - const: dsi0_phy_pll_out_byteclk + - const: dsi0_phy_pll_out_dsiclk + - const: dsi1_phy_pll_out_byteclk + - const: dsi1_phy_pll_out_dsiclk + - const: dp_link_clk_divsel_ten + - const: dp_vco_divided_clk_src_mux + + '#clock-cells': + const: 1 + + '#reset-cells': + const: 1 + + '#power-domain-cells': + const: 1 + + reg: + maxItems: 1 + +required: + - compatible + - reg + - clocks + - clock-names + - '#clock-cells' + - '#reset-cells' + - '#power-domain-cells' + +examples: + - | + #include <dt-bindings/clock/qcom,gcc-sdm845.h> + #include <dt-bindings/clock/qcom,rpmh.h> + clock-controller@af00000 { + compatible = "qcom,sdm845-dispcc"; + reg = <0 0x0af00000 0 0x10000>; + clocks = <&rpmhcc RPMH_CXO_CLK>, + <&gcc GCC_DISP_GPLL0_CLK_SRC>, + <&gcc GCC_DISP_GPLL0_DIV_CLK_SRC>, + <&dsi0_phy 0>, + <&dsi0_phy 1>, + <&dsi1_phy 0>, + <&dsi1_phy 1>, + <&dp_phy 0>, + <&dp_phy 1>; + clock-names = "bi_tcxo", + "gcc_disp_gpll0_clk_src", + "gcc_disp_gpll0_div_clk_src", + "dsi0_phy_pll_out_byteclk", + "dsi0_phy_pll_out_dsiclk", + "dsi1_phy_pll_out_byteclk", + "dsi1_phy_pll_out_dsiclk", + "dp_link_clk_divsel_ten", + "dp_vco_divided_clk_src_mux"; + #clock-cells = <1>; + #reset-cells = <1>; + #power-domain-cells = <1>; + }; +... diff --git a/Documentation/devicetree/bindings/clock/qcom,sdm845-gpucc.yaml b/Documentation/devicetree/bindings/clock/qcom,sdm845-gpucc.yaml new file mode 100644 index 000000000000..bac04f1c5d79 --- /dev/null +++ b/Documentation/devicetree/bindings/clock/qcom,sdm845-gpucc.yaml @@ -0,0 +1,72 @@ +# SPDX-License-Identifier: GPL-2.0-only +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/clock/qcom,sdm845-gpucc.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Qualcomm Graphics Clock & Reset Controller Binding for SDM845 + +maintainers: + - Taniya Das <tdas@codeaurora.org> + +description: | + Qualcomm graphics clock control module which supports the clocks, resets and + power domains on SDM845. + + See also dt-bindings/clock/qcom,gpucc-sdm845.h. + +properties: + compatible: + const: qcom,sdm845-gpucc + + clocks: + items: + - description: Board XO source + - description: GPLL0 main branch source + - description: GPLL0 div branch source + + clock-names: + items: + - const: bi_tcxo + - const: gcc_gpu_gpll0_clk_src + - const: gcc_gpu_gpll0_div_clk_src + + '#clock-cells': + const: 1 + + '#reset-cells': + const: 1 + + '#power-domain-cells': + const: 1 + + reg: + maxItems: 1 + +required: + - compatible + - reg + - clocks + - clock-names + - '#clock-cells' + - '#reset-cells' + - '#power-domain-cells' + +examples: + - | + #include <dt-bindings/clock/qcom,gcc-sdm845.h> + #include <dt-bindings/clock/qcom,rpmh.h> + clock-controller@5090000 { + compatible = "qcom,sdm845-gpucc"; + reg = <0 0x05090000 0 0x9000>; + clocks = <&rpmhcc RPMH_CXO_CLK>, + <&gcc GCC_GPU_GPLL0_CLK_SRC>, + <&gcc GCC_GPU_GPLL0_DIV_CLK_SRC>; + clock-names = "bi_tcxo", + "gcc_gpu_gpll0_clk_src", + "gcc_gpu_gpll0_div_clk_src"; + #clock-cells = <1>; + #reset-cells = <1>; + #power-domain-cells = <1>; + }; +... diff --git a/Documentation/devicetree/bindings/clock/qcom,sdm845-videocc.yaml b/Documentation/devicetree/bindings/clock/qcom,sdm845-videocc.yaml new file mode 100644 index 000000000000..9d216c0f11d4 --- /dev/null +++ b/Documentation/devicetree/bindings/clock/qcom,sdm845-videocc.yaml @@ -0,0 +1,63 @@ +# SPDX-License-Identifier: GPL-2.0-only +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/clock/qcom,sdm845-videocc.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Qualcomm Video Clock & Reset Controller Binding for SDM845 + +maintainers: + - Taniya Das <tdas@codeaurora.org> + +description: | + Qualcomm video clock control module which supports the clocks, resets and + power domains on SDM845. + + See also dt-bindings/clock/qcom,videocc-sdm845.h. + +properties: + compatible: + const: qcom,sdm845-videocc + + clocks: + items: + - description: Board XO source + + clock-names: + items: + - const: bi_tcxo + + '#clock-cells': + const: 1 + + '#reset-cells': + const: 1 + + '#power-domain-cells': + const: 1 + + reg: + maxItems: 1 + +required: + - compatible + - reg + - clocks + - clock-names + - '#clock-cells' + - '#reset-cells' + - '#power-domain-cells' + +examples: + - | + #include <dt-bindings/clock/qcom,rpmh.h> + clock-controller@ab00000 { + compatible = "qcom,sdm845-videocc"; + reg = <0 0x0ab00000 0 0x10000>; + clocks = <&rpmhcc RPMH_CXO_CLK>; + clock-names = "bi_tcxo"; + #clock-cells = <1>; + #reset-cells = <1>; + #power-domain-cells = <1>; + }; +... diff --git a/Documentation/devicetree/bindings/clock/qcom,videocc.txt b/Documentation/devicetree/bindings/clock/qcom,videocc.txt deleted file mode 100644 index 8a8622c65c5a..000000000000 --- a/Documentation/devicetree/bindings/clock/qcom,videocc.txt +++ /dev/null @@ -1,18 +0,0 @@ -Qualcomm Video Clock & Reset Controller Binding ------------------------------------------------ - -Required properties : -- compatible : shall contain "qcom,sdm845-videocc" -- reg : shall contain base register location and length -- #clock-cells : from common clock binding, shall contain 1. -- #power-domain-cells : from generic power domain binding, shall contain 1. -- #reset-cells : from common reset binding, shall contain 1. - -Example: - videocc: clock-controller@ab00000 { - compatible = "qcom,sdm845-videocc"; - reg = <0xab00000 0x10000>; - #clock-cells = <1>; - #power-domain-cells = <1>; - #reset-cells = <1>; - }; diff --git a/Documentation/devicetree/bindings/clock/renesas,cpg-mssr.txt b/Documentation/devicetree/bindings/clock/renesas,cpg-mssr.txt index c7674d0267a3..f4d153f24a0f 100644 --- a/Documentation/devicetree/bindings/clock/renesas,cpg-mssr.txt +++ b/Documentation/devicetree/bindings/clock/renesas,cpg-mssr.txt @@ -19,7 +19,7 @@ Required Properties: - "renesas,r8a7745-cpg-mssr" for the r8a7745 SoC (RZ/G1E) - "renesas,r8a77470-cpg-mssr" for the r8a77470 SoC (RZ/G1C) - "renesas,r8a774a1-cpg-mssr" for the r8a774a1 SoC (RZ/G2M) - - "renesas,r8a774b1-cpg-mssr" for the r8a774a1 SoC (RZ/G2N) + - "renesas,r8a774b1-cpg-mssr" for the r8a774b1 SoC (RZ/G2N) - "renesas,r8a774c0-cpg-mssr" for the r8a774c0 SoC (RZ/G2E) - "renesas,r8a7790-cpg-mssr" for the r8a7790 SoC (R-Car H2) - "renesas,r8a7791-cpg-mssr" for the r8a7791 SoC (R-Car M2-W) diff --git a/Documentation/devicetree/bindings/clock/st,stm32mp1-rcc.txt b/Documentation/devicetree/bindings/clock/st,stm32mp1-rcc.txt deleted file mode 100644 index fb9495ea582c..000000000000 --- a/Documentation/devicetree/bindings/clock/st,stm32mp1-rcc.txt +++ /dev/null @@ -1,60 +0,0 @@ -STMicroelectronics STM32 Peripheral Reset Clock Controller -========================================================== - -The RCC IP is both a reset and a clock controller. - -RCC makes also power management (resume/supend and wakeup interrupt). - -Please also refer to reset.txt for common reset controller binding usage. - -Please also refer to clock-bindings.txt for common clock controller -binding usage. - - -Required properties: -- compatible: "st,stm32mp1-rcc", "syscon" -- reg: should be register base and length as documented in the datasheet -- #clock-cells: 1, device nodes should specify the clock in their - "clocks" property, containing a phandle to the clock device node, - an index specifying the clock to use. -- #reset-cells: Shall be 1 -- interrupts: Should contain a general interrupt line and a interrupt line - to the wake-up of processor (CSTOP). - -Example: - rcc: rcc@50000000 { - compatible = "st,stm32mp1-rcc", "syscon"; - reg = <0x50000000 0x1000>; - #clock-cells = <1>; - #reset-cells = <1>; - interrupts = <GIC_SPI 5 IRQ_TYPE_NONE>, - <GIC_SPI 145 IRQ_TYPE_NONE>; - }; - -Specifying clocks -================= - -All available clocks are defined as preprocessor macros in -dt-bindings/clock/stm32mp1-clks.h header and can be used in device -tree sources. - -Specifying softreset control of devices -======================================= - -Device nodes should specify the reset channel required in their "resets" -property, containing a phandle to the reset device node and an index specifying -which channel to use. -The index is the bit number within the RCC registers bank, starting from RCC -base address. -It is calculated as: index = register_offset / 4 * 32 + bit_offset. -Where bit_offset is the bit offset within the register. - -For example on STM32MP1, for LTDC reset: - ltdc = APB4_RSTSETR_offset / 4 * 32 + LTDC_bit_offset - = 0x180 / 4 * 32 + 0 = 3072 - -The list of valid indices for STM32MP1 is available in: -include/dt-bindings/reset-controller/stm32mp1-resets.h - -This file implements defines like: -#define LTDC_R 3072 diff --git a/Documentation/devicetree/bindings/clock/st,stm32mp1-rcc.yaml b/Documentation/devicetree/bindings/clock/st,stm32mp1-rcc.yaml new file mode 100644 index 000000000000..4e385508f516 --- /dev/null +++ b/Documentation/devicetree/bindings/clock/st,stm32mp1-rcc.yaml @@ -0,0 +1,79 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/clock/st,stm32mp1-rcc.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Reset Clock Controller Binding + +maintainers: + - Gabriel Fernandez <gabriel.fernandez@st.com> + +description: | + The RCC IP is both a reset and a clock controller. + RCC makes also power management (resume/supend and wakeup interrupt). + Please also refer to reset.txt for common reset controller binding usage. + + This binding uses common clock bindings + Documentation/devicetree/bindings/clock/clock-bindings.txt + + Specifying clocks + ================= + + All available clocks are defined as preprocessor macros in + dt-bindings/clock/stm32mp1-clks.h header and can be used in device + tree sources. + + Specifying softreset control of devices + ======================================= + + Device nodes should specify the reset channel required in their "resets" + property, containing a phandle to the reset device node and an index specifying + which channel to use. + The index is the bit number within the RCC registers bank, starting from RCC + base address. + It is calculated as: index = register_offset / 4 * 32 + bit_offset. + Where bit_offset is the bit offset within the register. + + For example on STM32MP1, for LTDC reset: + ltdc = APB4_RSTSETR_offset / 4 * 32 + LTDC_bit_offset + = 0x180 / 4 * 32 + 0 = 3072 + + The list of valid indices for STM32MP1 is available in: + include/dt-bindings/reset-controller/stm32mp1-resets.h + + This file implements defines like: + #define LTDC_R 3072 + +properties: + "#clock-cells": + const: 1 + + "#reset-cells": + const: 1 + + compatible: + items: + - const: st,stm32mp1-rcc + - const: syscon + + reg: + maxItems: 1 + +required: + - "#clock-cells" + - "#reset-cells" + - compatible + - reg + +additionalProperties: false + +examples: + - | + rcc: rcc@50000000 { + compatible = "st,stm32mp1-rcc", "syscon"; + reg = <0x50000000 0x1000>; + #clock-cells = <1>; + #reset-cells = <1>; + }; +... diff --git a/Documentation/devicetree/bindings/clock/sun8i-de2.txt b/Documentation/devicetree/bindings/clock/sun8i-de2.txt deleted file mode 100644 index 41a52c2acffd..000000000000 --- a/Documentation/devicetree/bindings/clock/sun8i-de2.txt +++ /dev/null @@ -1,34 +0,0 @@ -Allwinner Display Engine 2.0/3.0 Clock Control Binding ------------------------------------------------------- - -Required properties : -- compatible: must contain one of the following compatibles: - - "allwinner,sun8i-a83t-de2-clk" - - "allwinner,sun8i-h3-de2-clk" - - "allwinner,sun8i-v3s-de2-clk" - - "allwinner,sun50i-a64-de2-clk" - - "allwinner,sun50i-h5-de2-clk" - - "allwinner,sun50i-h6-de3-clk" - -- reg: Must contain the registers base address and length -- clocks: phandle to the clocks feeding the display engine subsystem. - Three are needed: - - "mod": the display engine module clock (on A83T it's the DE PLL) - - "bus": the bus clock for the whole display engine subsystem -- clock-names: Must contain the clock names described just above -- resets: phandle to the reset control for the display engine subsystem. -- #clock-cells : must contain 1 -- #reset-cells : must contain 1 - -Example: -de2_clocks: clock@1000000 { - compatible = "allwinner,sun8i-h3-de2-clk"; - reg = <0x01000000 0x100000>; - clocks = <&ccu CLK_BUS_DE>, - <&ccu CLK_DE>; - clock-names = "bus", - "mod"; - resets = <&ccu RST_BUS_DE>; - #clock-cells = <1>; - #reset-cells = <1>; -}; diff --git a/Documentation/devicetree/bindings/clock/sun9i-de.txt b/Documentation/devicetree/bindings/clock/sun9i-de.txt deleted file mode 100644 index fb18f327b97a..000000000000 --- a/Documentation/devicetree/bindings/clock/sun9i-de.txt +++ /dev/null @@ -1,28 +0,0 @@ -Allwinner A80 Display Engine Clock Control Binding --------------------------------------------------- - -Required properties : -- compatible: must contain one of the following compatibles: - - "allwinner,sun9i-a80-de-clks" - -- reg: Must contain the registers base address and length -- clocks: phandle to the clocks feeding the display engine subsystem. - Three are needed: - - "mod": the display engine module clock - - "dram": the DRAM bus clock for the system - - "bus": the bus clock for the whole display engine subsystem -- clock-names: Must contain the clock names described just above -- resets: phandle to the reset control for the display engine subsystem. -- #clock-cells : must contain 1 -- #reset-cells : must contain 1 - -Example: -de_clocks: clock@3000000 { - compatible = "allwinner,sun9i-a80-de-clks"; - reg = <0x03000000 0x30>; - clocks = <&ccu CLK_DE>, <&ccu CLK_SDRAM>, <&ccu CLK_BUS_DE>; - clock-names = "mod", "dram", "bus"; - resets = <&ccu RST_BUS_DE>; - #clock-cells = <1>; - #reset-cells = <1>; -}; diff --git a/Documentation/devicetree/bindings/clock/sun9i-usb.txt b/Documentation/devicetree/bindings/clock/sun9i-usb.txt deleted file mode 100644 index 3564bd4f2a20..000000000000 --- a/Documentation/devicetree/bindings/clock/sun9i-usb.txt +++ /dev/null @@ -1,24 +0,0 @@ -Allwinner A80 USB Clock Control Binding ---------------------------------------- - -Required properties : -- compatible: must contain one of the following compatibles: - - "allwinner,sun9i-a80-usb-clocks" - -- reg: Must contain the registers base address and length -- clocks: phandle to the clocks feeding the USB subsystem. Two are needed: - - "bus": the bus clock for the whole USB subsystem - - "hosc": the high frequency oscillator (usually at 24MHz) -- clock-names: Must contain the clock names described just above -- #clock-cells : must contain 1 -- #reset-cells : must contain 1 - -Example: -usb_clocks: clock@a08000 { - compatible = "allwinner,sun9i-a80-usb-clks"; - reg = <0x00a08000 0x8>; - clocks = <&ccu CLK_BUS_USB>, <&osc24M>; - clock-names = "bus", "hosc"; - #clock-cells = <1>; - #reset-cells = <1>; -}; diff --git a/Documentation/devicetree/bindings/clock/sunxi.txt b/Documentation/devicetree/bindings/clock/sunxi.txt deleted file mode 100644 index 1a042e20b115..000000000000 --- a/Documentation/devicetree/bindings/clock/sunxi.txt +++ /dev/null @@ -1,225 +0,0 @@ -Device Tree Clock bindings for arch-sunxi - -This binding uses the common clock binding[1]. - -[1] Documentation/devicetree/bindings/clock/clock-bindings.txt - -Required properties: -- compatible : shall be one of the following: - "allwinner,sun4i-a10-osc-clk" - for a gatable oscillator - "allwinner,sun4i-a10-pll1-clk" - for the main PLL clock and PLL4 - "allwinner,sun6i-a31-pll1-clk" - for the main PLL clock on A31 - "allwinner,sun8i-a23-pll1-clk" - for the main PLL clock on A23 - "allwinner,sun4i-a10-pll3-clk" - for the video PLL clock on A10 - "allwinner,sun9i-a80-pll4-clk" - for the peripheral PLLs on A80 - "allwinner,sun4i-a10-pll5-clk" - for the PLL5 clock - "allwinner,sun4i-a10-pll6-clk" - for the PLL6 clock - "allwinner,sun6i-a31-pll6-clk" - for the PLL6 clock on A31 - "allwinner,sun9i-a80-gt-clk" - for the GT bus clock on A80 - "allwinner,sun4i-a10-cpu-clk" - for the CPU multiplexer clock - "allwinner,sun4i-a10-axi-clk" - for the AXI clock - "allwinner,sun8i-a23-axi-clk" - for the AXI clock on A23 - "allwinner,sun4i-a10-gates-clk" - for generic gates on all compatible SoCs - "allwinner,sun4i-a10-axi-gates-clk" - for the AXI gates - "allwinner,sun4i-a10-ahb-clk" - for the AHB clock - "allwinner,sun5i-a13-ahb-clk" - for the AHB clock on A13 - "allwinner,sun9i-a80-ahb-clk" - for the AHB bus clocks on A80 - "allwinner,sun4i-a10-ahb-gates-clk" - for the AHB gates on A10 - "allwinner,sun5i-a13-ahb-gates-clk" - for the AHB gates on A13 - "allwinner,sun5i-a10s-ahb-gates-clk" - for the AHB gates on A10s - "allwinner,sun7i-a20-ahb-gates-clk" - for the AHB gates on A20 - "allwinner,sun6i-a31-ar100-clk" - for the AR100 on A31 - "allwinner,sun9i-a80-cpus-clk" - for the CPUS on A80 - "allwinner,sun6i-a31-ahb1-clk" - for the AHB1 clock on A31 - "allwinner,sun8i-h3-ahb2-clk" - for the AHB2 clock on H3 - "allwinner,sun6i-a31-ahb1-gates-clk" - for the AHB1 gates on A31 - "allwinner,sun8i-a23-ahb1-gates-clk" - for the AHB1 gates on A23 - "allwinner,sun9i-a80-ahb0-gates-clk" - for the AHB0 gates on A80 - "allwinner,sun9i-a80-ahb1-gates-clk" - for the AHB1 gates on A80 - "allwinner,sun9i-a80-ahb2-gates-clk" - for the AHB2 gates on A80 - "allwinner,sun4i-a10-apb0-clk" - for the APB0 clock - "allwinner,sun6i-a31-apb0-clk" - for the APB0 clock on A31 - "allwinner,sun8i-a23-apb0-clk" - for the APB0 clock on A23 - "allwinner,sun9i-a80-apb0-clk" - for the APB0 bus clock on A80 - "allwinner,sun8i-a83t-apb0-gates-clk" - for the APB0 gates on A83T - "allwinner,sun4i-a10-apb0-gates-clk" - for the APB0 gates on A10 - "allwinner,sun5i-a13-apb0-gates-clk" - for the APB0 gates on A13 - "allwinner,sun5i-a10s-apb0-gates-clk" - for the APB0 gates on A10s - "allwinner,sun6i-a31-apb0-gates-clk" - for the APB0 gates on A31 - "allwinner,sun7i-a20-apb0-gates-clk" - for the APB0 gates on A20 - "allwinner,sun8i-a23-apb0-gates-clk" - for the APB0 gates on A23 - "allwinner,sun8i-h3-apb0-gates-clk" - for the APB0 gates on H3 - "allwinner,sun9i-a80-apb0-gates-clk" - for the APB0 gates on A80 - "allwinner,sun4i-a10-apb1-clk" - for the APB1 clock - "allwinner,sun9i-a80-apb1-clk" - for the APB1 bus clock on A80 - "allwinner,sun4i-a10-apb1-gates-clk" - for the APB1 gates on A10 - "allwinner,sun5i-a13-apb1-gates-clk" - for the APB1 gates on A13 - "allwinner,sun5i-a10s-apb1-gates-clk" - for the APB1 gates on A10s - "allwinner,sun6i-a31-apb1-gates-clk" - for the APB1 gates on A31 - "allwinner,sun7i-a20-apb1-gates-clk" - for the APB1 gates on A20 - "allwinner,sun8i-a23-apb1-gates-clk" - for the APB1 gates on A23 - "allwinner,sun9i-a80-apb1-gates-clk" - for the APB1 gates on A80 - "allwinner,sun6i-a31-apb2-gates-clk" - for the APB2 gates on A31 - "allwinner,sun8i-a23-apb2-gates-clk" - for the APB2 gates on A23 - "allwinner,sun8i-a83t-bus-gates-clk" - for the bus gates on A83T - "allwinner,sun8i-h3-bus-gates-clk" - for the bus gates on H3 - "allwinner,sun9i-a80-apbs-gates-clk" - for the APBS gates on A80 - "allwinner,sun4i-a10-display-clk" - for the display clocks on the A10 - "allwinner,sun4i-a10-dram-gates-clk" - for the DRAM gates on A10 - "allwinner,sun5i-a13-dram-gates-clk" - for the DRAM gates on A13 - "allwinner,sun5i-a13-mbus-clk" - for the MBUS clock on A13 - "allwinner,sun4i-a10-mmc-clk" - for the MMC clock - "allwinner,sun9i-a80-mmc-clk" - for mmc module clocks on A80 - "allwinner,sun9i-a80-mmc-config-clk" - for mmc gates + resets on A80 - "allwinner,sun4i-a10-mod0-clk" - for the module 0 family of clocks - "allwinner,sun9i-a80-mod0-clk" - for module 0 (storage) clocks on A80 - "allwinner,sun8i-a23-mbus-clk" - for the MBUS clock on A23 - "allwinner,sun7i-a20-out-clk" - for the external output clocks - "allwinner,sun7i-a20-gmac-clk" - for the GMAC clock module on A20/A31 - "allwinner,sun4i-a10-tcon-ch0-clk" - for the TCON channel 0 clock on the A10 - "allwinner,sun4i-a10-tcon-ch1-clk" - for the TCON channel 1 clock on the A10 - "allwinner,sun4i-a10-usb-clk" - for usb gates + resets on A10 / A20 - "allwinner,sun5i-a13-usb-clk" - for usb gates + resets on A13 - "allwinner,sun6i-a31-usb-clk" - for usb gates + resets on A31 - "allwinner,sun8i-a23-usb-clk" - for usb gates + resets on A23 - "allwinner,sun8i-h3-usb-clk" - for usb gates + resets on H3 - "allwinner,sun9i-a80-usb-mod-clk" - for usb gates + resets on A80 - "allwinner,sun9i-a80-usb-phy-clk" - for usb phy gates + resets on A80 - "allwinner,sun4i-a10-ve-clk" - for the Video Engine clock - "allwinner,sun6i-a31-display-clk" - for the display clocks - -Required properties for all clocks: -- reg : shall be the control register address for the clock. -- clocks : shall be the input parent clock(s) phandle for the clock. For - multiplexed clocks, the list order must match the hardware - programming order. -- #clock-cells : from common clock binding; shall be set to 0 except for - the following compatibles where it shall be set to 1: - "allwinner,*-gates-clk", "allwinner,sun4i-pll5-clk", - "allwinner,sun4i-pll6-clk", "allwinner,sun6i-a31-pll6-clk", - "allwinner,*-usb-clk", "allwinner,*-mmc-clk", - "allwinner,*-mmc-config-clk" -- clock-output-names : shall be the corresponding names of the outputs. - If the clock module only has one output, the name shall be the - module name. - -And "allwinner,*-usb-clk" clocks also require: -- reset-cells : shall be set to 1 - -The "allwinner,sun4i-a10-ve-clk" clock also requires: -- reset-cells : shall be set to 0 - -The "allwinner,sun9i-a80-mmc-config-clk" clock also requires: -- #reset-cells : shall be set to 1 -- resets : shall be the reset control phandle for the mmc block. - -For "allwinner,sun7i-a20-gmac-clk", the parent clocks shall be fixed rate -dummy clocks at 25 MHz and 125 MHz, respectively. See example. - -Clock consumers should specify the desired clocks they use with a -"clocks" phandle cell. Consumers that are using a gated clock should -provide an additional ID in their clock property. This ID is the -offset of the bit controlling this particular gate in the register. -For the other clocks with "#clock-cells" = 1, the additional ID shall -refer to the index of the output. - -For "allwinner,sun6i-a31-pll6-clk", there are 2 outputs. The first output -is the normal PLL6 output, or "pll6". The second output is rate doubled -PLL6, or "pll6x2". - -The "allwinner,*-mmc-clk" clocks have three different outputs: the -main clock, with the ID 0, and the output and sample clocks, with the -IDs 1 and 2, respectively. - -The "allwinner,sun9i-a80-mmc-config-clk" clock has one clock/reset output -per mmc controller. The number of outputs is determined by the size of -the address block, which is related to the overall mmc block. - -For example: - -osc24M: clk@1c20050 { - #clock-cells = <0>; - compatible = "allwinner,sun4i-a10-osc-clk"; - reg = <0x01c20050 0x4>; - clocks = <&osc24M_fixed>; - clock-output-names = "osc24M"; -}; - -pll1: clk@1c20000 { - #clock-cells = <0>; - compatible = "allwinner,sun4i-a10-pll1-clk"; - reg = <0x01c20000 0x4>; - clocks = <&osc24M>; - clock-output-names = "pll1"; -}; - -pll5: clk@1c20020 { - #clock-cells = <1>; - compatible = "allwinner,sun4i-pll5-clk"; - reg = <0x01c20020 0x4>; - clocks = <&osc24M>; - clock-output-names = "pll5_ddr", "pll5_other"; -}; - -pll6: clk@1c20028 { - #clock-cells = <1>; - compatible = "allwinner,sun6i-a31-pll6-clk"; - reg = <0x01c20028 0x4>; - clocks = <&osc24M>; - clock-output-names = "pll6", "pll6x2"; -}; - -cpu: cpu@1c20054 { - #clock-cells = <0>; - compatible = "allwinner,sun4i-a10-cpu-clk"; - reg = <0x01c20054 0x4>; - clocks = <&osc32k>, <&osc24M>, <&pll1>; - clock-output-names = "cpu"; -}; - -mmc0_clk: clk@1c20088 { - #clock-cells = <1>; - compatible = "allwinner,sun4i-a10-mmc-clk"; - reg = <0x01c20088 0x4>; - clocks = <&osc24M>, <&pll6 1>, <&pll5 1>; - clock-output-names = "mmc0", "mmc0_output", "mmc0_sample"; -}; - -mii_phy_tx_clk: clk@2 { - #clock-cells = <0>; - compatible = "fixed-clock"; - clock-frequency = <25000000>; - clock-output-names = "mii_phy_tx"; -}; - -gmac_int_tx_clk: clk@3 { - #clock-cells = <0>; - compatible = "fixed-clock"; - clock-frequency = <125000000>; - clock-output-names = "gmac_int_tx"; -}; - -gmac_clk: clk@1c20164 { - #clock-cells = <0>; - compatible = "allwinner,sun7i-a20-gmac-clk"; - reg = <0x01c20164 0x4>; - /* - * The first clock must be fixed at 25MHz; - * the second clock must be fixed at 125MHz - */ - clocks = <&mii_phy_tx_clk>, <&gmac_int_tx_clk>; - clock-output-names = "gmac"; -}; - -mmc_config_clk: clk@1c13000 { - compatible = "allwinner,sun9i-a80-mmc-config-clk"; - reg = <0x01c13000 0x10>; - clocks = <&ahb0_gates 8>; - clock-names = "ahb"; - resets = <&ahb0_resets 8>; - reset-names = "ahb"; - #clock-cells = <1>; - #reset-cells = <1>; - clock-output-names = "mmc0_config", "mmc1_config", - "mmc2_config", "mmc3_config"; -}; diff --git a/Documentation/devicetree/bindings/clock/ti-clkctrl.txt b/Documentation/devicetree/bindings/clock/ti-clkctrl.txt index 48ee6991f2cc..18af6b9409e3 100644 --- a/Documentation/devicetree/bindings/clock/ti-clkctrl.txt +++ b/Documentation/devicetree/bindings/clock/ti-clkctrl.txt @@ -16,18 +16,23 @@ For more information, please see the Linux clock framework binding at Documentation/devicetree/bindings/clock/clock-bindings.txt. Required properties : -- compatible : shall be "ti,clkctrl" +- compatible : shall be "ti,clkctrl" or a clock domain specific name: + "ti,clkctrl-l4-cfg" + "ti,clkctrl-l4-per" + "ti,clkctrl-l4-secure" + "ti,clkctrl-l4-wkup" - #clock-cells : shall contain 2 with the first entry being the instance offset from the clock domain base and the second being the clock index +- reg : clock registers Example: Clock controller node on omap 4430: &cm2 { l4per: cm@1400 { cm_l4per@0 { - cm_l4per_clkctrl: clk@20 { - compatible = "ti,clkctrl"; + cm_l4per_clkctrl: clock@20 { + compatible = "ti,clkctrl-l4-per", "ti,clkctrl"; reg = <0x20 0x1b0>; #clock-cells = <2>; }; diff --git a/Documentation/devicetree/bindings/clock/ti/dra7-atl.txt b/Documentation/devicetree/bindings/clock/ti/dra7-atl.txt index 10f7047755f3..21c002d28b9b 100644 --- a/Documentation/devicetree/bindings/clock/ti/dra7-atl.txt +++ b/Documentation/devicetree/bindings/clock/ti/dra7-atl.txt @@ -43,7 +43,7 @@ Configuration of ATL instances: - aws : Audio word select signal selection }; -For valid word select signals, see the dt-bindings/clk/ti-dra7-atl.h include +For valid word select signals, see the dt-bindings/clock/ti-dra7-atl.h include file. Examples: @@ -83,7 +83,7 @@ atl: atl@4843c000 { clock-names = "fck"; }; -#include <dt-bindings/clk/ti-dra7-atl.h> +#include <dt-bindings/clock/ti-dra7-atl.h> &atl { diff --git a/Documentation/devicetree/bindings/clock/xlnx,versal-clk.yaml b/Documentation/devicetree/bindings/clock/xlnx,versal-clk.yaml new file mode 100644 index 000000000000..229af98b1d30 --- /dev/null +++ b/Documentation/devicetree/bindings/clock/xlnx,versal-clk.yaml @@ -0,0 +1,64 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/clock/xlnx,versal-clk.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Xilinx Versal clock controller + +maintainers: + - Michal Simek <michal.simek@xilinx.com> + - Jolly Shah <jolly.shah@xilinx.com> + - Rajan Vaja <rajan.vaja@xilinx.com> + +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. + +select: false + +properties: + compatible: + const: xlnx,versal-clk + + "#clock-cells": + const: 1 + + clocks: + description: List of clock specifiers which are external input + clocks to the given clock controller. + items: + - description: reference clock + - description: alternate reference clock + - description: alternate reference clock for programmable logic + + clock-names: + items: + - const: ref + - const: alt_ref + - const: pl_alt_ref + +required: + - compatible + - "#clock-cells" + - clocks + - clock-names + +additionalProperties: false + +examples: + - | + firmware { + zynqmp_firmware: zynqmp-firmware { + compatible = "xlnx,zynqmp-firmware"; + method = "smc"; + versal_clk: clock-controller { + #clock-cells = <1>; + compatible = "xlnx,versal-clk"; + clocks = <&ref>, <&alt_ref>, <&pl_alt_ref>; + clock-names = "ref", "alt_ref", "pl_alt_ref"; + }; + }; + }; +... diff --git a/Documentation/devicetree/bindings/connector/usb-connector.txt b/Documentation/devicetree/bindings/connector/usb-connector.txt index d357987181ee..88578ac1a8a7 100644 --- a/Documentation/devicetree/bindings/connector/usb-connector.txt +++ b/Documentation/devicetree/bindings/connector/usb-connector.txt @@ -1,8 +1,8 @@ USB Connector ============= -USB connector node represents physical USB connector. It should be -a child of USB interface controller. +A USB connector node represents a physical USB connector. It should be +a child of a USB interface controller. Required properties: - compatible: describes type of the connector, must be one of: diff --git a/Documentation/devicetree/bindings/display/allwinner,sun4i-a10-display-backend.yaml b/Documentation/devicetree/bindings/display/allwinner,sun4i-a10-display-backend.yaml new file mode 100644 index 000000000000..86057d541065 --- /dev/null +++ b/Documentation/devicetree/bindings/display/allwinner,sun4i-a10-display-backend.yaml @@ -0,0 +1,291 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/display/allwinner,sun4i-a10-display-backend.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Allwinner A10 Display Engine Backend Device Tree Bindings + +maintainers: + - Chen-Yu Tsai <wens@csie.org> + - Maxime Ripard <mripard@kernel.org> + +description: | + The display engine backend exposes layers and sprites to the system. + +properties: + compatible: + enum: + - allwinner,sun4i-a10-display-backend + - allwinner,sun5i-a13-display-backend + - allwinner,sun6i-a31-display-backend + - allwinner,sun7i-a20-display-backend + - allwinner,sun8i-a23-display-backend + - allwinner,sun8i-a33-display-backend + - allwinner,sun9i-a80-display-backend + + reg: + minItems: 1 + maxItems: 2 + items: + - description: Display Backend registers + - description: SAT registers + + reg-names: + minItems: 1 + maxItems: 2 + items: + - const: be + - const: sat + + interrupts: + maxItems: 1 + + clocks: + minItems: 3 + maxItems: 4 + items: + - description: The backend interface clock + - description: The backend module clock + - description: The backend DRAM clock + - description: The SAT clock + + clock-names: + minItems: 3 + maxItems: 4 + items: + - const: ahb + - const: mod + - const: ram + - const: sat + + resets: + minItems: 1 + maxItems: 2 + items: + - description: The Backend reset line + - description: The SAT reset line + + reset-names: + minItems: 1 + maxItems: 2 + items: + - const: be + - const: sat + + # FIXME: This should be made required eventually once every SoC will + # have the MBUS declared. + interconnects: + maxItems: 1 + + # FIXME: This should be made required eventually once every SoC will + # have the MBUS declared. + interconnect-names: + const: dma-mem + + ports: + type: object + description: | + A ports node with endpoint definitions as defined in + Documentation/devicetree/bindings/media/video-interfaces.txt. + + properties: + "#address-cells": + const: 1 + + "#size-cells": + const: 0 + + port@0: + type: object + description: | + Input endpoints of the controller. + + port@1: + type: object + description: | + Output endpoints of the controller. + + required: + - "#address-cells" + - "#size-cells" + - port@0 + - port@1 + + additionalProperties: false + +required: + - compatible + - reg + - interrupts + - clocks + - clock-names + - resets + - ports + +additionalProperties: false + +if: + properties: + compatible: + contains: + const: allwinner,sun8i-a33-display-backend + +then: + properties: + reg: + minItems: 2 + + reg-names: + minItems: 2 + + clocks: + minItems: 4 + + clock-names: + minItems: 4 + + resets: + minItems: 2 + + reset-names: + minItems: 2 + + required: + - reg-names + - reset-names + +else: + properties: + reg: + maxItems: 1 + + reg-names: + maxItems: 1 + + clocks: + maxItems: 3 + + clock-names: + maxItems: 3 + + resets: + maxItems: 1 + + reset-names: + maxItems: 1 + +examples: + - | + /* + * This comes from the clock/sun4i-a10-ccu.h and + * reset/sun4i-a10-ccu.h headers, but we can't include them since + * it would trigger a bunch of warnings for redefinitions of + * symbols with the other example. + */ + + #define CLK_AHB_DE_BE0 42 + #define CLK_DRAM_DE_BE0 140 + #define CLK_DE_BE0 144 + #define RST_DE_BE0 5 + + display-backend@1e60000 { + compatible = "allwinner,sun4i-a10-display-backend"; + reg = <0x01e60000 0x10000>; + interrupts = <47>; + clocks = <&ccu CLK_AHB_DE_BE0>, <&ccu CLK_DE_BE0>, + <&ccu CLK_DRAM_DE_BE0>; + clock-names = "ahb", "mod", + "ram"; + resets = <&ccu RST_DE_BE0>; + + ports { + #address-cells = <1>; + #size-cells = <0>; + + port@0 { + #address-cells = <1>; + #size-cells = <0>; + reg = <0>; + + endpoint@0 { + reg = <0>; + remote-endpoint = <&fe0_out_be0>; + }; + + endpoint@1 { + reg = <1>; + remote-endpoint = <&fe1_out_be0>; + }; + }; + + port@1 { + #address-cells = <1>; + #size-cells = <0>; + reg = <1>; + + endpoint@0 { + reg = <0>; + remote-endpoint = <&tcon0_in_be0>; + }; + + endpoint@1 { + reg = <1>; + remote-endpoint = <&tcon1_in_be0>; + }; + }; + }; + }; + + - | + #include <dt-bindings/interrupt-controller/arm-gic.h> + + /* + * This comes from the clock/sun8i-a23-a33-ccu.h and + * reset/sun8i-a23-a33-ccu.h headers, but we can't include them + * since it would trigger a bunch of warnings for redefinitions of + * symbols with the other example. + */ + + #define CLK_BUS_DE_BE 40 + #define CLK_BUS_SAT 46 + #define CLK_DRAM_DE_BE 84 + #define CLK_DE_BE 85 + #define RST_BUS_DE_BE 21 + #define RST_BUS_SAT 27 + + display-backend@1e60000 { + compatible = "allwinner,sun8i-a33-display-backend"; + reg = <0x01e60000 0x10000>, <0x01e80000 0x1000>; + reg-names = "be", "sat"; + interrupts = <GIC_SPI 95 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&ccu CLK_BUS_DE_BE>, <&ccu CLK_DE_BE>, + <&ccu CLK_DRAM_DE_BE>, <&ccu CLK_BUS_SAT>; + clock-names = "ahb", "mod", + "ram", "sat"; + resets = <&ccu RST_BUS_DE_BE>, <&ccu RST_BUS_SAT>; + reset-names = "be", "sat"; + + ports { + #address-cells = <1>; + #size-cells = <0>; + + port@0 { + reg = <0>; + + endpoint { + remote-endpoint = <&fe0_out_be0>; + }; + }; + + port@1 { + reg = <1>; + + endpoint { + remote-endpoint = <&drc0_in_be0>; + }; + }; + }; + }; + +... diff --git a/Documentation/devicetree/bindings/display/allwinner,sun4i-a10-display-engine.yaml b/Documentation/devicetree/bindings/display/allwinner,sun4i-a10-display-engine.yaml new file mode 100644 index 000000000000..944ff2f1cf93 --- /dev/null +++ b/Documentation/devicetree/bindings/display/allwinner,sun4i-a10-display-engine.yaml @@ -0,0 +1,114 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/display/allwinner,sun4i-a10-display-engine.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Allwinner A10 Display Engine Pipeline Device Tree Bindings + +maintainers: + - Chen-Yu Tsai <wens@csie.org> + - Maxime Ripard <mripard@kernel.org> + +description: | + The display engine pipeline (and its entry point, since it can be + either directly the backend or the frontend) is represented as an + extra node. + + The Allwinner A10 Display pipeline is composed of several components + that are going to be documented below: + + For all connections between components up to the TCONs in the + display pipeline, when there are multiple components of the same + type at the same depth, the local endpoint ID must be the same as + the remote component's index. For example, if the remote endpoint is + Frontend 1, then the local endpoint ID must be 1. + + Frontend 0 [0] ------- [0] Backend 0 [0] ------- [0] TCON 0 + [1] -- -- [1] [1] -- -- [1] + \ / \ / + X X + / \ / \ + [0] -- -- [0] [0] -- -- [0] + Frontend 1 [1] ------- [1] Backend 1 [1] ------- [1] TCON 1 + + For a two pipeline system such as the one depicted above, the lines + represent the connections between the components, while the numbers + within the square brackets corresponds to the ID of the local endpoint. + + The same rule also applies to DE 2.0 mixer-TCON connections: + + Mixer 0 [0] ----------- [0] TCON 0 + [1] ---- ---- [1] + \ / + X + / \ + [0] ---- ---- [0] + Mixer 1 [1] ----------- [1] TCON 1 + +properties: + compatible: + enum: + - allwinner,sun4i-a10-display-engine + - allwinner,sun5i-a10s-display-engine + - allwinner,sun5i-a13-display-engine + - allwinner,sun6i-a31-display-engine + - allwinner,sun6i-a31s-display-engine + - allwinner,sun7i-a20-display-engine + - allwinner,sun8i-a23-display-engine + - allwinner,sun8i-a33-display-engine + - allwinner,sun8i-a83t-display-engine + - allwinner,sun8i-h3-display-engine + - allwinner,sun8i-r40-display-engine + - allwinner,sun8i-v3s-display-engine + - allwinner,sun9i-a80-display-engine + - allwinner,sun50i-a64-display-engine + - allwinner,sun50i-h6-display-engine + + allwinner,pipelines: + allOf: + - $ref: /schemas/types.yaml#/definitions/phandle-array + - minItems: 1 + maxItems: 2 + description: | + Available display engine frontends (DE 1.0) or mixers (DE + 2.0/3.0) available. + +required: + - compatible + - allwinner,pipelines + +additionalProperties: false + +if: + properties: + compatible: + contains: + enum: + - allwinner,sun4i-a10-display-engine + - allwinner,sun6i-a31-display-engine + - allwinner,sun6i-a31s-display-engine + - allwinner,sun7i-a20-display-engine + - allwinner,sun8i-a83t-display-engine + - allwinner,sun8i-r40-display-engine + - allwinner,sun9i-a80-display-engine + - allwinner,sun50i-a64-display-engine + +then: + properties: + allwinner,pipelines: + minItems: 2 + +else: + properties: + allwinner,pipelines: + maxItems: 1 + +examples: + - | + de: display-engine { + compatible = "allwinner,sun4i-a10-display-engine"; + allwinner,pipelines = <&fe0>, <&fe1>; + }; + +... diff --git a/Documentation/devicetree/bindings/display/allwinner,sun4i-a10-display-frontend.yaml b/Documentation/devicetree/bindings/display/allwinner,sun4i-a10-display-frontend.yaml new file mode 100644 index 000000000000..3eb1c2bbf4e7 --- /dev/null +++ b/Documentation/devicetree/bindings/display/allwinner,sun4i-a10-display-frontend.yaml @@ -0,0 +1,138 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/display/allwinner,sun4i-a10-display-frontend.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Allwinner A10 Display Engine Frontend Device Tree Bindings + +maintainers: + - Chen-Yu Tsai <wens@csie.org> + - Maxime Ripard <mripard@kernel.org> + +description: | + The display engine frontend does formats conversion, scaling, + deinterlacing and color space conversion. + +properties: + compatible: + enum: + - allwinner,sun4i-a10-display-frontend + - allwinner,sun5i-a13-display-frontend + - allwinner,sun6i-a31-display-frontend + - allwinner,sun7i-a20-display-frontend + - allwinner,sun8i-a23-display-frontend + - allwinner,sun8i-a33-display-frontend + - allwinner,sun9i-a80-display-frontend + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + clocks: + items: + - description: The frontend interface clock + - description: The frontend module clock + - description: The frontend DRAM clock + + clock-names: + items: + - const: ahb + - const: mod + - const: ram + + # FIXME: This should be made required eventually once every SoC will + # have the MBUS declared. + interconnects: + maxItems: 1 + + # FIXME: This should be made required eventually once every SoC will + # have the MBUS declared. + interconnect-names: + const: dma-mem + + resets: + maxItems: 1 + + ports: + type: object + description: | + A ports node with endpoint definitions as defined in + Documentation/devicetree/bindings/media/video-interfaces.txt. + + properties: + "#address-cells": + const: 1 + + "#size-cells": + const: 0 + + port@0: + type: object + description: | + Input endpoints of the controller. + + port@1: + type: object + description: | + Output endpoints of the controller. + + required: + - "#address-cells" + - "#size-cells" + - port@1 + + additionalProperties: false + +required: + - compatible + - reg + - interrupts + - clocks + - clock-names + - resets + - ports + +additionalProperties: false + +examples: + - | + #include <dt-bindings/clock/sun4i-a10-ccu.h> + #include <dt-bindings/reset/sun4i-a10-ccu.h> + + fe0: display-frontend@1e00000 { + compatible = "allwinner,sun4i-a10-display-frontend"; + reg = <0x01e00000 0x20000>; + interrupts = <47>; + clocks = <&ccu CLK_AHB_DE_FE0>, <&ccu CLK_DE_FE0>, + <&ccu CLK_DRAM_DE_FE0>; + clock-names = "ahb", "mod", + "ram"; + resets = <&ccu RST_DE_FE0>; + + ports { + #address-cells = <1>; + #size-cells = <0>; + + fe0_out: port@1 { + #address-cells = <1>; + #size-cells = <0>; + reg = <1>; + + fe0_out_be0: endpoint@0 { + reg = <0>; + remote-endpoint = <&be0_in_fe0>; + }; + + fe0_out_be1: endpoint@1 { + reg = <1>; + remote-endpoint = <&be1_in_fe0>; + }; + }; + }; + }; + + +... diff --git a/Documentation/devicetree/bindings/display/allwinner,sun4i-a10-hdmi.yaml b/Documentation/devicetree/bindings/display/allwinner,sun4i-a10-hdmi.yaml new file mode 100644 index 000000000000..5d4915aed1e2 --- /dev/null +++ b/Documentation/devicetree/bindings/display/allwinner,sun4i-a10-hdmi.yaml @@ -0,0 +1,183 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/display/allwinner,sun4i-a10-hdmi.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Allwinner A10 HDMI Controller Device Tree Bindings + +description: | + The HDMI Encoder supports the HDMI video and audio outputs, and does + CEC. It is one end of the pipeline. + +maintainers: + - Chen-Yu Tsai <wens@csie.org> + - Maxime Ripard <mripard@kernel.org> + +properties: + compatible: + oneOf: + - const: allwinner,sun4i-a10-hdmi + - const: allwinner,sun5i-a10s-hdmi + - const: allwinner,sun6i-a31-hdmi + - items: + - const: allwinner,sun7i-a20-hdmi + - const: allwinner,sun5i-a10s-hdmi + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + clocks: + oneOf: + - items: + - description: The HDMI interface clock + - description: The HDMI module clock + - description: The first video PLL + - description: The second video PLL + + - items: + - description: The HDMI interface clock + - description: The HDMI module clock + - description: The HDMI DDC clock + - description: The first video PLL + - description: The second video PLL + + clock-names: + oneOf: + - items: + - const: ahb + - const: mod + - const: pll-0 + - const: pll-1 + + - items: + - const: ahb + - const: mod + - const: ddc + - const: pll-0 + - const: pll-1 + + resets: + maxItems: 1 + + dmas: + items: + - description: DDC Transmission DMA Channel + - description: DDC Reception DMA Channel + - description: Audio Transmission DMA Channel + + dma-names: + items: + - const: ddc-tx + - const: ddc-rx + - const: audio-tx + + ports: + type: object + description: | + A ports node with endpoint definitions as defined in + Documentation/devicetree/bindings/media/video-interfaces.txt. + + properties: + "#address-cells": + const: 1 + + "#size-cells": + const: 0 + + port@0: + type: object + description: | + Input endpoints of the controller. + + port@1: + type: object + description: | + Output endpoints of the controller. Usually an HDMI + connector. + + required: + - "#address-cells" + - "#size-cells" + - port@0 + - port@1 + + additionalProperties: false + +required: + - compatible + - reg + - interrupts + - clocks + - clock-names + - dmas + - dma-names + +if: + properties: + compatible: + contains: + const: allwinner,sun6i-a31-hdmi + +then: + properties: + clocks: + minItems: 5 + + clock-names: + minItems: 5 + + required: + - resets + +additionalProperties: false + +examples: + - | + #include <dt-bindings/clock/sun4i-a10-ccu.h> + #include <dt-bindings/dma/sun4i-a10.h> + #include <dt-bindings/reset/sun4i-a10-ccu.h> + + hdmi: hdmi@1c16000 { + compatible = "allwinner,sun4i-a10-hdmi"; + reg = <0x01c16000 0x1000>; + interrupts = <58>; + clocks = <&ccu CLK_AHB_HDMI0>, <&ccu CLK_HDMI>, + <&ccu CLK_PLL_VIDEO0_2X>, + <&ccu CLK_PLL_VIDEO1_2X>; + clock-names = "ahb", "mod", "pll-0", "pll-1"; + dmas = <&dma SUN4I_DMA_NORMAL 16>, + <&dma SUN4I_DMA_NORMAL 16>, + <&dma SUN4I_DMA_DEDICATED 24>; + dma-names = "ddc-tx", "ddc-rx", "audio-tx"; + + ports { + #address-cells = <1>; + #size-cells = <0>; + + hdmi_in: port@0 { + #address-cells = <1>; + #size-cells = <0>; + reg = <0>; + + hdmi_in_tcon0: endpoint@0 { + reg = <0>; + remote-endpoint = <&tcon0_out_hdmi>; + }; + + hdmi_in_tcon1: endpoint@1 { + reg = <1>; + remote-endpoint = <&tcon1_out_hdmi>; + }; + }; + + hdmi_out: port@1 { + reg = <1>; + }; + }; + }; + +... diff --git a/Documentation/devicetree/bindings/display/allwinner,sun4i-a10-tcon.yaml b/Documentation/devicetree/bindings/display/allwinner,sun4i-a10-tcon.yaml new file mode 100644 index 000000000000..5ff9cf26ca38 --- /dev/null +++ b/Documentation/devicetree/bindings/display/allwinner,sun4i-a10-tcon.yaml @@ -0,0 +1,680 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/display/allwinner,sun4i-a10-tcon.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Allwinner A10 Timings Controller (TCON) Device Tree Bindings + +maintainers: + - Chen-Yu Tsai <wens@csie.org> + - Maxime Ripard <mripard@kernel.org> + +description: | + The TCON acts as a timing controller for RGB, LVDS and TV + interfaces. + +properties: + "#clock-cells": + const: 0 + + compatible: + oneOf: + - const: allwinner,sun4i-a10-tcon + - const: allwinner,sun5i-a13-tcon + - const: allwinner,sun6i-a31-tcon + - const: allwinner,sun6i-a31s-tcon + - const: allwinner,sun7i-a20-tcon + - const: allwinner,sun8i-a23-tcon + - const: allwinner,sun8i-a33-tcon + - const: allwinner,sun8i-a83t-tcon-lcd + - const: allwinner,sun8i-a83t-tcon-tv + - const: allwinner,sun8i-r40-tcon-tv + - const: allwinner,sun8i-v3s-tcon + - const: allwinner,sun9i-a80-tcon-lcd + - const: allwinner,sun9i-a80-tcon-tv + + - items: + - enum: + - allwinner,sun50i-a64-tcon-lcd + - const: allwinner,sun8i-a83t-tcon-lcd + + - items: + - enum: + - allwinner,sun8i-h3-tcon-tv + - allwinner,sun50i-a64-tcon-tv + - const: allwinner,sun8i-a83t-tcon-tv + + - items: + - enum: + - allwinner,sun50i-h6-tcon-tv + - const: allwinner,sun8i-r40-tcon-tv + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + clocks: + minItems: 1 + maxItems: 4 + + clock-names: + minItems: 1 + maxItems: 4 + + clock-output-names: + allOf: + - $ref: /schemas/types.yaml#/definitions/string-array + - maxItems: 1 + description: + Name of the LCD pixel clock created. + + dmas: + maxItems: 1 + + resets: + anyOf: + - items: + - description: TCON Reset Line + + - items: + - description: TCON Reset Line + - description: TCON LVDS Reset Line + + - items: + - description: TCON Reset Line + - description: TCON eDP Reset Line + + - items: + - description: TCON Reset Line + - description: TCON eDP Reset Line + - description: TCON LVDS Reset Line + + reset-names: + oneOf: + - const: lcd + + - items: + - const: lcd + - const: lvds + + - items: + - const: lcd + - const: edp + + - items: + - const: lcd + - const: edp + - const: lvds + + ports: + type: object + description: | + A ports node with endpoint definitions as defined in + Documentation/devicetree/bindings/media/video-interfaces.txt. + + properties: + "#address-cells": + const: 1 + + "#size-cells": + const: 0 + + port@0: + type: object + description: | + Input endpoints of the controller. + + port@1: + type: object + description: | + Output endpoints of the controller. + + patternProperties: + "^endpoint(@[0-9])$": + type: object + + properties: + allwinner,tcon-channel: + $ref: /schemas/types.yaml#/definitions/uint32 + description: | + TCON can have 1 or 2 channels, usually with the + first channel being used for the panels interfaces + (RGB, LVDS, etc.), and the second being used for the + outputs that require another controller (TV Encoder, + HDMI, etc.). + + If that property is present, specifies the TCON + channel the endpoint is associated to. If that + property is not present, the endpoint number will be + used as the channel number. + + unevaluatedProperties: true + + required: + - "#address-cells" + - "#size-cells" + - port@0 + - port@1 + + additionalProperties: false + +required: + - compatible + - reg + - interrupts + - clocks + - clock-names + - resets + - ports + +additionalProperties: false + +allOf: + - if: + properties: + compatible: + contains: + enum: + - allwinner,sun4i-a10-tcon + - allwinner,sun5i-a13-tcon + - allwinner,sun7i-a20-tcon + + then: + properties: + clocks: + minItems: 3 + + clock-names: + items: + - const: ahb + - const: tcon-ch0 + - const: tcon-ch1 + + - if: + properties: + compatible: + contains: + enum: + - allwinner,sun6i-a31-tcon + - allwinner,sun6i-a31s-tcon + + then: + properties: + clocks: + minItems: 4 + + clock-names: + items: + - const: ahb + - const: tcon-ch0 + - const: tcon-ch1 + - const: lvds-alt + + - if: + properties: + compatible: + contains: + enum: + - allwinner,sun8i-a23-tcon + - allwinner,sun8i-a33-tcon + + then: + properties: + clocks: + minItems: 3 + + clock-names: + items: + - const: ahb + - const: tcon-ch0 + - const: lvds-alt + + - if: + properties: + compatible: + contains: + enum: + - allwinner,sun8i-a83t-tcon-lcd + - allwinner,sun8i-v3s-tcon + - allwinner,sun9i-a80-tcon-lcd + + then: + properties: + clocks: + minItems: 2 + + clock-names: + items: + - const: ahb + - const: tcon-ch0 + + - if: + properties: + compatible: + contains: + enum: + - allwinner,sun8i-a83t-tcon-tv + - allwinner,sun8i-r40-tcon-tv + - allwinner,sun9i-a80-tcon-tv + + then: + properties: + clocks: + minItems: 2 + + clock-names: + items: + - const: ahb + - const: tcon-ch1 + + - if: + properties: + compatible: + contains: + enum: + - allwinner,sun5i-a13-tcon + - allwinner,sun6i-a31-tcon + - allwinner,sun6i-a31s-tcon + - allwinner,sun7i-a20-tcon + - allwinner,sun8i-a23-tcon + - allwinner,sun8i-a33-tcon + - allwinner,sun8i-v3s-tcon + - allwinner,sun9i-a80-tcon-lcd + - allwinner,sun4i-a10-tcon + - allwinner,sun8i-a83t-tcon-lcd + + then: + required: + - "#clock-cells" + - clock-output-names + + - if: + properties: + compatible: + contains: + enum: + - allwinner,sun6i-a31-tcon + - allwinner,sun6i-a31s-tcon + - allwinner,sun8i-a23-tcon + - allwinner,sun8i-a33-tcon + - allwinner,sun8i-a83t-tcon-lcd + + then: + properties: + resets: + minItems: 2 + + reset-names: + items: + - const: lcd + - const: lvds + + - if: + properties: + compatible: + contains: + enum: + - allwinner,sun9i-a80-tcon-lcd + + then: + properties: + resets: + minItems: 3 + + reset-names: + items: + - const: lcd + - const: edp + - const: lvds + + - if: + properties: + compatible: + contains: + enum: + - allwinner,sun9i-a80-tcon-tv + + then: + properties: + resets: + minItems: 2 + + reset-names: + items: + - const: lcd + - const: edp + + - if: + properties: + compatible: + contains: + enum: + - allwinner,sun4i-a10-tcon + - allwinner,sun5i-a13-tcon + - allwinner,sun6i-a31-tcon + - allwinner,sun6i-a31s-tcon + - allwinner,sun7i-a20-tcon + - allwinner,sun8i-a23-tcon + - allwinner,sun8i-a33-tcon + + then: + required: + - dmas + +examples: + - | + #include <dt-bindings/dma/sun4i-a10.h> + + /* + * This comes from the clock/sun4i-a10-ccu.h and + * reset/sun4i-a10-ccu.h headers, but we can't include them since + * it would trigger a bunch of warnings for redefinitions of + * symbols with the other example. + */ + + #define CLK_AHB_LCD0 56 + #define CLK_TCON0_CH0 149 + #define CLK_TCON0_CH1 155 + #define RST_TCON0 11 + + lcd-controller@1c0c000 { + compatible = "allwinner,sun4i-a10-tcon"; + reg = <0x01c0c000 0x1000>; + interrupts = <44>; + resets = <&ccu RST_TCON0>; + reset-names = "lcd"; + clocks = <&ccu CLK_AHB_LCD0>, + <&ccu CLK_TCON0_CH0>, + <&ccu CLK_TCON0_CH1>; + clock-names = "ahb", + "tcon-ch0", + "tcon-ch1"; + clock-output-names = "tcon0-pixel-clock"; + #clock-cells = <0>; + dmas = <&dma SUN4I_DMA_DEDICATED 14>; + + ports { + #address-cells = <1>; + #size-cells = <0>; + + port@0 { + #address-cells = <1>; + #size-cells = <0>; + reg = <0>; + + endpoint@0 { + reg = <0>; + remote-endpoint = <&be0_out_tcon0>; + }; + + endpoint@1 { + reg = <1>; + remote-endpoint = <&be1_out_tcon0>; + }; + }; + + port@1 { + #address-cells = <1>; + #size-cells = <0>; + reg = <1>; + + endpoint@1 { + reg = <1>; + remote-endpoint = <&hdmi_in_tcon0>; + allwinner,tcon-channel = <1>; + }; + }; + }; + }; + + #undef CLK_AHB_LCD0 + #undef CLK_TCON0_CH0 + #undef CLK_TCON0_CH1 + #undef RST_TCON0 + + - | + #include <dt-bindings/interrupt-controller/arm-gic.h> + + /* + * This comes from the clock/sun6i-a31-ccu.h and + * reset/sun6i-a31-ccu.h headers, but we can't include them since + * it would trigger a bunch of warnings for redefinitions of + * symbols with the other example. + */ + + #define CLK_PLL_MIPI 15 + #define CLK_AHB1_LCD0 47 + #define CLK_LCD0_CH0 127 + #define CLK_LCD0_CH1 129 + #define RST_AHB1_LCD0 27 + #define RST_AHB1_LVDS 41 + + lcd-controller@1c0c000 { + compatible = "allwinner,sun6i-a31-tcon"; + reg = <0x01c0c000 0x1000>; + interrupts = <GIC_SPI 86 IRQ_TYPE_LEVEL_HIGH>; + dmas = <&dma 11>; + resets = <&ccu RST_AHB1_LCD0>, <&ccu RST_AHB1_LVDS>; + reset-names = "lcd", "lvds"; + clocks = <&ccu CLK_AHB1_LCD0>, + <&ccu CLK_LCD0_CH0>, + <&ccu CLK_LCD0_CH1>, + <&ccu CLK_PLL_MIPI>; + clock-names = "ahb", + "tcon-ch0", + "tcon-ch1", + "lvds-alt"; + clock-output-names = "tcon0-pixel-clock"; + #clock-cells = <0>; + + ports { + #address-cells = <1>; + #size-cells = <0>; + + port@0 { + #address-cells = <1>; + #size-cells = <0>; + reg = <0>; + + endpoint@0 { + reg = <0>; + remote-endpoint = <&drc0_out_tcon0>; + }; + + endpoint@1 { + reg = <1>; + remote-endpoint = <&drc1_out_tcon0>; + }; + }; + + port@1 { + #address-cells = <1>; + #size-cells = <0>; + reg = <1>; + + endpoint@1 { + reg = <1>; + remote-endpoint = <&hdmi_in_tcon0>; + allwinner,tcon-channel = <1>; + }; + }; + }; + }; + + #undef CLK_PLL_MIPI + #undef CLK_AHB1_LCD0 + #undef CLK_LCD0_CH0 + #undef CLK_LCD0_CH1 + #undef RST_AHB1_LCD0 + #undef RST_AHB1_LVDS + + - | + #include <dt-bindings/interrupt-controller/arm-gic.h> + + /* + * This comes from the clock/sun9i-a80-ccu.h and + * reset/sun9i-a80-ccu.h headers, but we can't include them since + * it would trigger a bunch of warnings for redefinitions of + * symbols with the other example. + */ + + #define CLK_BUS_LCD0 102 + #define CLK_LCD0 58 + #define RST_BUS_LCD0 22 + #define RST_BUS_EDP 24 + #define RST_BUS_LVDS 25 + + lcd-controller@3c00000 { + compatible = "allwinner,sun9i-a80-tcon-lcd"; + reg = <0x03c00000 0x10000>; + interrupts = <GIC_SPI 86 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&ccu CLK_BUS_LCD0>, <&ccu CLK_LCD0>; + clock-names = "ahb", "tcon-ch0"; + resets = <&ccu RST_BUS_LCD0>, <&ccu RST_BUS_EDP>, <&ccu RST_BUS_LVDS>; + reset-names = "lcd", "edp", "lvds"; + clock-output-names = "tcon0-pixel-clock"; + #clock-cells = <0>; + + ports { + #address-cells = <1>; + #size-cells = <0>; + + port@0 { + reg = <0>; + + endpoint { + remote-endpoint = <&drc0_out_tcon0>; + }; + }; + + port@1 { + reg = <1>; + }; + }; + }; + + #undef CLK_BUS_TCON0 + #undef CLK_TCON0 + #undef RST_BUS_TCON0 + #undef RST_BUS_EDP + #undef RST_BUS_LVDS + + - | + #include <dt-bindings/interrupt-controller/arm-gic.h> + + /* + * This comes from the clock/sun8i-a83t-ccu.h and + * reset/sun8i-a83t-ccu.h headers, but we can't include them since + * it would trigger a bunch of warnings for redefinitions of + * symbols with the other example. + */ + + #define CLK_BUS_TCON0 36 + #define CLK_TCON0 85 + #define RST_BUS_TCON0 22 + #define RST_BUS_LVDS 31 + + lcd-controller@1c0c000 { + compatible = "allwinner,sun8i-a83t-tcon-lcd"; + reg = <0x01c0c000 0x1000>; + interrupts = <GIC_SPI 86 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&ccu CLK_BUS_TCON0>, <&ccu CLK_TCON0>; + clock-names = "ahb", "tcon-ch0"; + clock-output-names = "tcon-pixel-clock"; + #clock-cells = <0>; + resets = <&ccu RST_BUS_TCON0>, <&ccu RST_BUS_LVDS>; + reset-names = "lcd", "lvds"; + + ports { + #address-cells = <1>; + #size-cells = <0>; + + port@0 { + #address-cells = <1>; + #size-cells = <0>; + reg = <0>; + + endpoint@0 { + reg = <0>; + remote-endpoint = <&mixer0_out_tcon0>; + }; + + endpoint@1 { + reg = <1>; + remote-endpoint = <&mixer1_out_tcon0>; + }; + }; + + port@1 { + reg = <1>; + }; + }; + }; + + #undef CLK_BUS_TCON0 + #undef CLK_TCON0 + #undef RST_BUS_TCON0 + #undef RST_BUS_LVDS + + - | + #include <dt-bindings/interrupt-controller/arm-gic.h> + + /* + * This comes from the clock/sun8i-r40-ccu.h and + * reset/sun8i-r40-ccu.h headers, but we can't include them since + * it would trigger a bunch of warnings for redefinitions of + * symbols with the other example. + */ + + #define CLK_BUS_TCON_TV0 73 + #define RST_BUS_TCON_TV0 49 + + tcon_tv0: lcd-controller@1c73000 { + compatible = "allwinner,sun8i-r40-tcon-tv"; + reg = <0x01c73000 0x1000>; + interrupts = <GIC_SPI 51 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&ccu CLK_BUS_TCON_TV0>, <&tcon_top 0>; + clock-names = "ahb", "tcon-ch1"; + resets = <&ccu RST_BUS_TCON_TV0>; + reset-names = "lcd"; + + ports { + #address-cells = <1>; + #size-cells = <0>; + + port@0 { + #address-cells = <1>; + #size-cells = <0>; + reg = <0>; + + endpoint@0 { + reg = <0>; + remote-endpoint = <&tcon_top_mixer0_out_tcon_tv0>; + }; + + endpoint@1 { + reg = <1>; + remote-endpoint = <&tcon_top_mixer1_out_tcon_tv0>; + }; + }; + + tcon_tv0_out: port@1 { + #address-cells = <1>; + #size-cells = <0>; + reg = <1>; + + endpoint@1 { + reg = <1>; + remote-endpoint = <&tcon_top_hdmi_in_tcon_tv0>; + }; + }; + }; + }; + + #undef CLK_BUS_TCON_TV0 + #undef RST_BUS_TCON_TV0 + +... diff --git a/Documentation/devicetree/bindings/display/allwinner,sun4i-a10-tv-encoder.yaml b/Documentation/devicetree/bindings/display/allwinner,sun4i-a10-tv-encoder.yaml new file mode 100644 index 000000000000..5d5d39665119 --- /dev/null +++ b/Documentation/devicetree/bindings/display/allwinner,sun4i-a10-tv-encoder.yaml @@ -0,0 +1,62 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/display/allwinner,sun4i-a10-tv-encoder.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Allwinner A10 TV Encoder Device Tree Bindings + +maintainers: + - Chen-Yu Tsai <wens@csie.org> + - Maxime Ripard <mripard@kernel.org> + +properties: + compatible: + const: allwinner,sun4i-a10-tv-encoder + + reg: + maxItems: 1 + + clocks: + maxItems: 1 + + resets: + maxItems: 1 + + port: + type: object + description: + A port node with endpoint definitions as defined in + Documentation/devicetree/bindings/media/video-interfaces.txt. The + first port should be the input endpoint, usually coming from the + associated TCON. + +required: + - compatible + - reg + - clocks + - resets + - port + +additionalProperties: false + +examples: + - | + tve0: tv-encoder@1c0a000 { + compatible = "allwinner,sun4i-a10-tv-encoder"; + reg = <0x01c0a000 0x1000>; + clocks = <&ahb_gates 34>; + resets = <&tcon_ch0_clk 0>; + + port { + #address-cells = <1>; + #size-cells = <0>; + + tve0_in_tcon0: endpoint@0 { + reg = <0>; + remote-endpoint = <&tcon0_out_tve0>; + }; + }; + }; + +... diff --git a/Documentation/devicetree/bindings/display/allwinner,sun6i-a31-drc.yaml b/Documentation/devicetree/bindings/display/allwinner,sun6i-a31-drc.yaml new file mode 100644 index 000000000000..0c1ce55940e1 --- /dev/null +++ b/Documentation/devicetree/bindings/display/allwinner,sun6i-a31-drc.yaml @@ -0,0 +1,138 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/display/allwinner,sun6i-a31-drc.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Allwinner A31 Dynamic Range Controller Device Tree Bindings + +maintainers: + - Chen-Yu Tsai <wens@csie.org> + - Maxime Ripard <mripard@kernel.org> + +description: | + The DRC (Dynamic Range Controller) allows to dynamically adjust + pixel brightness/contrast based on histogram measurements for LCD + content adaptive backlight control. + +properties: + compatible: + enum: + - allwinner,sun6i-a31-drc + - allwinner,sun6i-a31s-drc + - allwinner,sun8i-a23-drc + - allwinner,sun8i-a33-drc + - allwinner,sun9i-a80-drc + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + clocks: + items: + - description: The DRC interface clock + - description: The DRC module clock + - description: The DRC DRAM clock + + clock-names: + items: + - const: ahb + - const: mod + - const: ram + + resets: + maxItems: 1 + + ports: + type: object + description: | + A ports node with endpoint definitions as defined in + Documentation/devicetree/bindings/media/video-interfaces.txt. + + properties: + "#address-cells": + const: 1 + + "#size-cells": + const: 0 + + port@0: + type: object + description: | + Input endpoints of the controller. + + port@1: + type: object + description: | + Output endpoints of the controller. + + required: + - "#address-cells" + - "#size-cells" + - port@0 + - port@1 + + additionalProperties: false + +required: + - compatible + - reg + - interrupts + - clocks + - clock-names + - resets + - ports + +additionalProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/arm-gic.h> + + #include <dt-bindings/clock/sun6i-a31-ccu.h> + #include <dt-bindings/reset/sun6i-a31-ccu.h> + + drc0: drc@1e70000 { + compatible = "allwinner,sun6i-a31-drc"; + reg = <0x01e70000 0x10000>; + interrupts = <GIC_SPI 91 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&ccu CLK_AHB1_DRC0>, <&ccu CLK_IEP_DRC0>, + <&ccu CLK_DRAM_DRC0>; + clock-names = "ahb", "mod", + "ram"; + resets = <&ccu RST_AHB1_DRC0>; + + ports { + #address-cells = <1>; + #size-cells = <0>; + + drc0_in: port@0 { + reg = <0>; + + drc0_in_be0: endpoint { + remote-endpoint = <&be0_out_drc0>; + }; + }; + + drc0_out: port@1 { + #address-cells = <1>; + #size-cells = <0>; + reg = <1>; + + drc0_out_tcon0: endpoint@0 { + reg = <0>; + remote-endpoint = <&tcon0_in_drc0>; + }; + + drc0_out_tcon1: endpoint@1 { + reg = <1>; + remote-endpoint = <&tcon1_in_drc0>; + }; + }; + }; + }; + + +... diff --git a/Documentation/devicetree/bindings/display/allwinner,sun6i-a31-mipi-dsi.yaml b/Documentation/devicetree/bindings/display/allwinner,sun6i-a31-mipi-dsi.yaml index 0f7074977c04..9e90c2b00960 100644 --- a/Documentation/devicetree/bindings/display/allwinner,sun6i-a31-mipi-dsi.yaml +++ b/Documentation/devicetree/bindings/display/allwinner,sun6i-a31-mipi-dsi.yaml @@ -15,7 +15,9 @@ properties: "#size-cells": true compatible: - const: allwinner,sun6i-a31-mipi-dsi + enum: + - allwinner,sun6i-a31-mipi-dsi + - allwinner,sun50i-a64-mipi-dsi reg: maxItems: 1 @@ -24,6 +26,8 @@ properties: maxItems: 1 clocks: + minItems: 1 + maxItems: 2 items: - description: Bus Clock - description: Module Clock @@ -63,13 +67,38 @@ required: - reg - interrupts - clocks - - clock-names - phys - phy-names - resets - vcc-dsi-supply - port +allOf: + - if: + properties: + compatible: + contains: + const: allwinner,sun6i-a31-mipi-dsi + + then: + properties: + clocks: + minItems: 2 + + required: + - clock-names + + - if: + properties: + compatible: + contains: + const: allwinner,sun50i-a64-mipi-dsi + + then: + properties: + clocks: + minItems: 1 + additionalProperties: false examples: diff --git a/Documentation/devicetree/bindings/display/allwinner,sun8i-a83t-de2-mixer.yaml b/Documentation/devicetree/bindings/display/allwinner,sun8i-a83t-de2-mixer.yaml new file mode 100644 index 000000000000..1dee641e3ea1 --- /dev/null +++ b/Documentation/devicetree/bindings/display/allwinner,sun8i-a83t-de2-mixer.yaml @@ -0,0 +1,118 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/display/allwinner,sun8i-a83t-de2-mixer.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Allwinner Display Engine 2.0 Mixer Device Tree Bindings + +maintainers: + - Chen-Yu Tsai <wens@csie.org> + - Maxime Ripard <mripard@kernel.org> + +properties: + compatible: + enum: + - allwinner,sun8i-a83t-de2-mixer-0 + - allwinner,sun8i-a83t-de2-mixer-1 + - allwinner,sun8i-h3-de2-mixer-0 + - allwinner,sun8i-r40-de2-mixer-0 + - allwinner,sun8i-r40-de2-mixer-1 + - allwinner,sun8i-v3s-de2-mixer + - allwinner,sun50i-a64-de2-mixer-0 + - allwinner,sun50i-a64-de2-mixer-1 + - allwinner,sun50i-h6-de3-mixer-0 + + reg: + maxItems: 1 + + clocks: + items: + - description: The mixer interface clock + - description: The mixer module clock + + clock-names: + items: + - const: bus + - const: mod + + resets: + maxItems: 1 + + ports: + type: object + description: | + A ports node with endpoint definitions as defined in + Documentation/devicetree/bindings/media/video-interfaces.txt. + + properties: + "#address-cells": + const: 1 + + "#size-cells": + const: 0 + + port@0: + type: object + description: | + Input endpoints of the controller. + + port@1: + type: object + description: | + Output endpoints of the controller. + + required: + - "#address-cells" + - "#size-cells" + - port@1 + + additionalProperties: false + +required: + - compatible + - reg + - clocks + - clock-names + - resets + - ports + +additionalProperties: false + +examples: + - | + #include <dt-bindings/clock/sun8i-de2.h> + #include <dt-bindings/reset/sun8i-de2.h> + + mixer0: mixer@1100000 { + compatible = "allwinner,sun8i-a83t-de2-mixer-0"; + reg = <0x01100000 0x100000>; + clocks = <&display_clocks CLK_BUS_MIXER0>, + <&display_clocks CLK_MIXER0>; + clock-names = "bus", + "mod"; + resets = <&display_clocks RST_MIXER0>; + + ports { + #address-cells = <1>; + #size-cells = <0>; + + mixer0_out: port@1 { + #address-cells = <1>; + #size-cells = <0>; + reg = <1>; + + mixer0_out_tcon0: endpoint@0 { + reg = <0>; + remote-endpoint = <&tcon0_in_mixer0>; + }; + + mixer0_out_tcon1: endpoint@1 { + reg = <1>; + remote-endpoint = <&tcon1_in_mixer0>; + }; + }; + }; + }; + +... diff --git a/Documentation/devicetree/bindings/display/allwinner,sun8i-a83t-dw-hdmi.yaml b/Documentation/devicetree/bindings/display/allwinner,sun8i-a83t-dw-hdmi.yaml new file mode 100644 index 000000000000..4d6795690ac3 --- /dev/null +++ b/Documentation/devicetree/bindings/display/allwinner,sun8i-a83t-dw-hdmi.yaml @@ -0,0 +1,273 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/display/allwinner,sun8i-a83t-dw-hdmi.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Allwinner A83t DWC HDMI TX Encoder Device Tree Bindings + +description: | + The HDMI transmitter is a Synopsys DesignWare HDMI 1.4 TX controller + IP with Allwinner\'s own PHY IP. It supports audio and video outputs + and CEC. + + These DT bindings follow the Synopsys DWC HDMI TX bindings defined + in Documentation/devicetree/bindings/display/bridge/dw_hdmi.txt with + the following device-specific properties. + +maintainers: + - Chen-Yu Tsai <wens@csie.org> + - Maxime Ripard <mripard@kernel.org> + +properties: + "#phy-cells": + const: 0 + + compatible: + oneOf: + - const: allwinner,sun8i-a83t-dw-hdmi + - const: allwinner,sun50i-h6-dw-hdmi + + - items: + - enum: + - allwinner,sun8i-h3-dw-hdmi + - allwinner,sun8i-r40-dw-hdmi + - allwinner,sun50i-a64-dw-hdmi + - const: allwinner,sun8i-a83t-dw-hdmi + + reg: + maxItems: 1 + + reg-io-width: + const: 1 + + interrupts: + maxItems: 1 + + clocks: + minItems: 3 + maxItems: 6 + items: + - description: Bus Clock + - description: Register Clock + - description: TMDS Clock + - description: HDMI CEC Clock + - description: HDCP Clock + - description: HDCP Bus Clock + + clock-names: + minItems: 3 + maxItems: 6 + items: + - const: iahb + - const: isfr + - const: tmds + - const: cec + - const: hdcp + - const: hdcp-bus + + resets: + minItems: 1 + maxItems: 2 + items: + - description: HDMI Controller Reset + - description: HDCP Reset + + reset-names: + minItems: 1 + maxItems: 2 + items: + - const: ctrl + - const: hdcp + + phys: + maxItems: 1 + description: + Phandle to the DWC HDMI PHY. + + phy-names: + const: phy + + hvcc-supply: + description: + The VCC power supply of the controller + + ports: + type: object + description: | + A ports node with endpoint definitions as defined in + Documentation/devicetree/bindings/media/video-interfaces.txt. + + properties: + "#address-cells": + const: 1 + + "#size-cells": + const: 0 + + port@0: + type: object + description: | + Input endpoints of the controller. Usually the associated + TCON. + + port@1: + type: object + description: | + Output endpoints of the controller. Usually an HDMI + connector. + + required: + - "#address-cells" + - "#size-cells" + - port@0 + - port@1 + + additionalProperties: false + +required: + - compatible + - reg + - reg-io-width + - interrupts + - clocks + - clock-names + - resets + - reset-names + - phys + - phy-names + - ports + +if: + properties: + compatible: + contains: + enum: + - allwinner,sun50i-h6-dw-hdmi + +then: + properties: + clocks: + minItems: 6 + + clock-names: + minItems: 6 + + resets: + minItems: 2 + + reset-names: + minItems: 2 + + +additionalProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/arm-gic.h> + + /* + * This comes from the clock/sun8i-a83t-ccu.h and + * reset/sun8i-a83t-ccu.h headers, but we can't include them since + * it would trigger a bunch of warnings for redefinitions of + * symbols with the other example. + */ + #define CLK_BUS_HDMI 39 + #define CLK_HDMI 93 + #define CLK_HDMI_SLOW 94 + #define RST_BUS_HDMI1 26 + + hdmi@1ee0000 { + compatible = "allwinner,sun8i-a83t-dw-hdmi"; + reg = <0x01ee0000 0x10000>; + reg-io-width = <1>; + interrupts = <GIC_SPI 88 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&ccu CLK_BUS_HDMI>, <&ccu CLK_HDMI_SLOW>, + <&ccu CLK_HDMI>; + clock-names = "iahb", "isfr", "tmds"; + resets = <&ccu RST_BUS_HDMI1>; + reset-names = "ctrl"; + phys = <&hdmi_phy>; + phy-names = "phy"; + pinctrl-names = "default"; + pinctrl-0 = <&hdmi_pins>; + status = "disabled"; + + ports { + #address-cells = <1>; + #size-cells = <0>; + + port@0 { + reg = <0>; + + endpoint { + remote-endpoint = <&tcon1_out_hdmi>; + }; + }; + + port@1 { + reg = <1>; + }; + }; + }; + + /* Cleanup after ourselves */ + #undef CLK_BUS_HDMI + #undef CLK_HDMI + #undef CLK_HDMI_SLOW + + - | + #include <dt-bindings/interrupt-controller/arm-gic.h> + + /* + * This comes from the clock/sun50i-h6-ccu.h and + * reset/sun50i-h6-ccu.h headers, but we can't include them since + * it would trigger a bunch of warnings for redefinitions of + * symbols with the other example. + */ + #define CLK_BUS_HDMI 126 + #define CLK_BUS_HDCP 137 + #define CLK_HDMI 123 + #define CLK_HDMI_SLOW 124 + #define CLK_HDMI_CEC 125 + #define CLK_HDCP 136 + #define RST_BUS_HDMI_SUB 57 + #define RST_BUS_HDCP 62 + + hdmi@6000000 { + compatible = "allwinner,sun50i-h6-dw-hdmi"; + reg = <0x06000000 0x10000>; + reg-io-width = <1>; + interrupts = <GIC_SPI 64 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&ccu CLK_BUS_HDMI>, <&ccu CLK_HDMI_SLOW>, + <&ccu CLK_HDMI>, <&ccu CLK_HDMI_CEC>, + <&ccu CLK_HDCP>, <&ccu CLK_BUS_HDCP>; + clock-names = "iahb", "isfr", "tmds", "cec", "hdcp", + "hdcp-bus"; + resets = <&ccu RST_BUS_HDMI_SUB>, <&ccu RST_BUS_HDCP>; + reset-names = "ctrl", "hdcp"; + phys = <&hdmi_phy>; + phy-names = "phy"; + pinctrl-names = "default"; + pinctrl-0 = <&hdmi_pins>; + status = "disabled"; + + ports { + #address-cells = <1>; + #size-cells = <0>; + + port@0 { + reg = <0>; + + endpoint { + remote-endpoint = <&tcon_top_hdmi_out_hdmi>; + }; + }; + + port@1 { + reg = <1>; + }; + }; + }; + +... diff --git a/Documentation/devicetree/bindings/display/allwinner,sun8i-a83t-hdmi-phy.yaml b/Documentation/devicetree/bindings/display/allwinner,sun8i-a83t-hdmi-phy.yaml new file mode 100644 index 000000000000..501cec16168c --- /dev/null +++ b/Documentation/devicetree/bindings/display/allwinner,sun8i-a83t-hdmi-phy.yaml @@ -0,0 +1,117 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/display/allwinner,sun8i-a83t-hdmi-phy.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Allwinner A83t HDMI PHY Device Tree Bindings + +maintainers: + - Chen-Yu Tsai <wens@csie.org> + - Maxime Ripard <mripard@kernel.org> + +properties: + "#phy-cells": + const: 0 + + compatible: + enum: + - allwinner,sun8i-a83t-hdmi-phy + - allwinner,sun8i-h3-hdmi-phy + - allwinner,sun8i-r40-hdmi-phy + - allwinner,sun50i-a64-hdmi-phy + - allwinner,sun50i-h6-hdmi-phy + + reg: + maxItems: 1 + + clocks: + minItems: 2 + maxItems: 4 + items: + - description: Bus Clock + - description: Module Clock + - description: Parent of the PHY clock + - description: Second possible parent of the PHY clock + + clock-names: + minItems: 2 + maxItems: 4 + items: + - const: bus + - const: mod + - const: pll-0 + - const: pll-1 + + resets: + maxItems: 1 + + reset-names: + const: phy + +required: + - compatible + - reg + - clocks + - clock-names + - resets + - reset-names + +if: + properties: + compatible: + contains: + enum: + - allwinner,sun8i-r40-hdmi-phy + +then: + properties: + clocks: + minItems: 4 + + clock-names: + minItems: 4 + +else: + if: + properties: + compatible: + contains: + enum: + - allwinner,sun8i-h3-hdmi-phy + - allwinner,sun50i-a64-hdmi-phy + + then: + properties: + clocks: + minItems: 3 + + clock-names: + minItems: 3 + + else: + properties: + clocks: + maxItems: 2 + + clock-names: + maxItems: 2 + +additionalProperties: false + +examples: + - | + #include <dt-bindings/clock/sun8i-a83t-ccu.h> + #include <dt-bindings/reset/sun8i-a83t-ccu.h> + + hdmi_phy: hdmi-phy@1ef0000 { + compatible = "allwinner,sun8i-a83t-hdmi-phy"; + reg = <0x01ef0000 0x10000>; + clocks = <&ccu CLK_BUS_HDMI>, <&ccu CLK_HDMI_SLOW>; + clock-names = "bus", "mod"; + resets = <&ccu RST_BUS_HDMI0>; + reset-names = "phy"; + #phy-cells = <0>; + }; + +... diff --git a/Documentation/devicetree/bindings/display/allwinner,sun8i-r40-tcon-top.yaml b/Documentation/devicetree/bindings/display/allwinner,sun8i-r40-tcon-top.yaml new file mode 100644 index 000000000000..b98ca609824b --- /dev/null +++ b/Documentation/devicetree/bindings/display/allwinner,sun8i-r40-tcon-top.yaml @@ -0,0 +1,382 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/display/allwinner,sun8i-r40-tcon-top.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Allwinner R40 TCON TOP Device Tree Bindings + +maintainers: + - Chen-Yu Tsai <wens@csie.org> + - Maxime Ripard <mripard@kernel.org> + +description: | + TCON TOPs main purpose is to configure whole display pipeline. It + determines relationships between mixers and TCONs, selects source + TCON for HDMI, muxes LCD and TV encoder GPIO output, selects TV + encoder clock source and contains additional TV TCON and DSI gates. + + It allows display pipeline to be configured in very different ways: + + / LCD0/LVDS0 + / [0] TCON-LCD0 + | \ MIPI DSI + mixer0 | + \ / [1] TCON-LCD1 - LCD1/LVDS1 + TCON-TOP + / \ [2] TCON-TV0 [0] - TVE0/RGB + mixer1 | \ + | TCON-TOP - HDMI + | / + \ [3] TCON-TV1 [1] - TVE1/RGB + + Note that both TCON TOP references same physical unit. Both mixers + can be connected to any TCON. Not all TCON TOP variants support all + features. + +properties: + "#clock-cells": + const: 1 + + compatible: + enum: + - allwinner,sun8i-r40-tcon-top + - allwinner,sun50i-h6-tcon-top + + reg: + maxItems: 1 + + clocks: + minItems: 2 + maxItems: 6 + items: + - description: The TCON TOP interface clock + - description: The TCON TOP TV0 clock + - description: The TCON TOP TVE0 clock + - description: The TCON TOP TV1 clock + - description: The TCON TOP TVE1 clock + - description: The TCON TOP MIPI DSI clock + + clock-names: + minItems: 2 + maxItems: 6 + items: + - const: bus + - const: tcon-tv0 + - const: tve0 + - const: tcon-tv1 + - const: tve1 + - const: dsi + + clock-output-names: + minItems: 1 + maxItems: 3 + description: > + The first item is the name of the clock created for the TV0 + channel, the second item is the name of the TCON TV1 channel + clock and the third one is the name of the DSI channel clock. + + resets: + maxItems: 1 + + ports: + type: object + description: | + A ports node with endpoint definitions as defined in + Documentation/devicetree/bindings/media/video-interfaces.txt. + All ports should have only one endpoint connected to + remote endpoint. + + properties: + "#address-cells": + const: 1 + + "#size-cells": + const: 0 + + port@0: + type: object + description: | + Input endpoint for Mixer 0 mux. + + port@1: + type: object + description: | + Output endpoint for Mixer 0 mux + + properties: + "#address-cells": + const: 1 + + "#size-cells": + const: 0 + + reg: true + + patternProperties: + "^endpoint@[0-9]$": + type: object + + properties: + reg: + description: | + ID of the target TCON + + required: + - reg + + required: + - "#address-cells" + - "#size-cells" + + additionalProperties: false + + port@2: + type: object + description: | + Input endpoint for Mixer 1 mux. + + port@3: + type: object + description: | + Output endpoint for Mixer 1 mux + + properties: + "#address-cells": + const: 1 + + "#size-cells": + const: 0 + + reg: true + + patternProperties: + "^endpoint@[0-9]$": + type: object + + properties: + reg: + description: | + ID of the target TCON + + required: + - reg + + required: + - "#address-cells" + - "#size-cells" + + additionalProperties: false + + port@4: + type: object + description: | + Input endpoint for HDMI mux. + + properties: + "#address-cells": + const: 1 + + "#size-cells": + const: 0 + + reg: true + + patternProperties: + "^endpoint@[0-9]$": + type: object + + properties: + reg: + description: | + ID of the target TCON + + required: + - reg + + required: + - "#address-cells" + - "#size-cells" + + additionalProperties: false + + port@5: + type: object + description: | + Output endpoint for HDMI mux + + required: + - "#address-cells" + - "#size-cells" + - port@0 + - port@1 + - port@4 + - port@5 + + additionalProperties: false + +required: + - "#clock-cells" + - compatible + - reg + - clocks + - clock-names + - clock-output-names + - resets + - ports + +additionalProperties: false + +if: + properties: + compatible: + contains: + const: allwinner,sun50i-h6-tcon-top + +then: + properties: + clocks: + maxItems: 2 + + clock-output-names: + maxItems: 1 + +else: + properties: + clocks: + minItems: 6 + + clock-output-names: + minItems: 3 + + ports: + required: + - port@2 + - port@3 + +examples: + - | + #include <dt-bindings/interrupt-controller/arm-gic.h> + + #include <dt-bindings/clock/sun8i-r40-ccu.h> + #include <dt-bindings/reset/sun8i-r40-ccu.h> + + tcon_top: tcon-top@1c70000 { + compatible = "allwinner,sun8i-r40-tcon-top"; + reg = <0x01c70000 0x1000>; + clocks = <&ccu CLK_BUS_TCON_TOP>, + <&ccu CLK_TCON_TV0>, + <&ccu CLK_TVE0>, + <&ccu CLK_TCON_TV1>, + <&ccu CLK_TVE1>, + <&ccu CLK_DSI_DPHY>; + clock-names = "bus", + "tcon-tv0", + "tve0", + "tcon-tv1", + "tve1", + "dsi"; + clock-output-names = "tcon-top-tv0", + "tcon-top-tv1", + "tcon-top-dsi"; + resets = <&ccu RST_BUS_TCON_TOP>; + #clock-cells = <1>; + + ports { + #address-cells = <1>; + #size-cells = <0>; + + tcon_top_mixer0_in: port@0 { + reg = <0>; + + tcon_top_mixer0_in_mixer0: endpoint { + remote-endpoint = <&mixer0_out_tcon_top>; + }; + }; + + tcon_top_mixer0_out: port@1 { + #address-cells = <1>; + #size-cells = <0>; + reg = <1>; + + tcon_top_mixer0_out_tcon_lcd0: endpoint@0 { + reg = <0>; + }; + + tcon_top_mixer0_out_tcon_lcd1: endpoint@1 { + reg = <1>; + }; + + tcon_top_mixer0_out_tcon_tv0: endpoint@2 { + reg = <2>; + remote-endpoint = <&tcon_tv0_in_tcon_top_mixer0>; + }; + + tcon_top_mixer0_out_tcon_tv1: endpoint@3 { + reg = <3>; + remote-endpoint = <&tcon_tv1_in_tcon_top_mixer0>; + }; + }; + + tcon_top_mixer1_in: port@2 { + #address-cells = <1>; + #size-cells = <0>; + reg = <2>; + + tcon_top_mixer1_in_mixer1: endpoint@1 { + reg = <1>; + remote-endpoint = <&mixer1_out_tcon_top>; + }; + }; + + tcon_top_mixer1_out: port@3 { + #address-cells = <1>; + #size-cells = <0>; + reg = <3>; + + tcon_top_mixer1_out_tcon_lcd0: endpoint@0 { + reg = <0>; + }; + + tcon_top_mixer1_out_tcon_lcd1: endpoint@1 { + reg = <1>; + }; + + tcon_top_mixer1_out_tcon_tv0: endpoint@2 { + reg = <2>; + remote-endpoint = <&tcon_tv0_in_tcon_top_mixer1>; + }; + + tcon_top_mixer1_out_tcon_tv1: endpoint@3 { + reg = <3>; + remote-endpoint = <&tcon_tv1_in_tcon_top_mixer1>; + }; + }; + + tcon_top_hdmi_in: port@4 { + #address-cells = <1>; + #size-cells = <0>; + reg = <4>; + + tcon_top_hdmi_in_tcon_tv0: endpoint@0 { + reg = <0>; + remote-endpoint = <&tcon_tv0_out_tcon_top>; + }; + + tcon_top_hdmi_in_tcon_tv1: endpoint@1 { + reg = <1>; + remote-endpoint = <&tcon_tv1_out_tcon_top>; + }; + }; + + tcon_top_hdmi_out: port@5 { + reg = <5>; + + tcon_top_hdmi_out_hdmi: endpoint { + remote-endpoint = <&hdmi_in_tcon_top>; + }; + }; + }; + }; + +... diff --git a/Documentation/devicetree/bindings/display/allwinner,sun9i-a80-deu.yaml b/Documentation/devicetree/bindings/display/allwinner,sun9i-a80-deu.yaml new file mode 100644 index 000000000000..96de41d32b3e --- /dev/null +++ b/Documentation/devicetree/bindings/display/allwinner,sun9i-a80-deu.yaml @@ -0,0 +1,133 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/display/allwinner,sun9i-a80-deu.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Allwinner A80 Detail Enhancement Unit Device Tree Bindings + +maintainers: + - Chen-Yu Tsai <wens@csie.org> + - Maxime Ripard <mripard@kernel.org> + +description: | + The DEU (Detail Enhancement Unit), found in the Allwinner A80 SoC, + can sharpen the display content in both luma and chroma channels. + +properties: + compatible: + const: allwinner,sun9i-a80-deu + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + clocks: + items: + - description: The DEU interface clock + - description: The DEU module clock + - description: The DEU DRAM clock + + clock-names: + items: + - const: ahb + - const: mod + - const: ram + + resets: + maxItems: 1 + + ports: + type: object + description: | + A ports node with endpoint definitions as defined in + Documentation/devicetree/bindings/media/video-interfaces.txt. + + properties: + "#address-cells": + const: 1 + + "#size-cells": + const: 0 + + port@0: + type: object + description: | + Input endpoints of the controller. + + port@1: + type: object + description: | + Output endpoints of the controller. + + required: + - "#address-cells" + - "#size-cells" + - port@0 + - port@1 + + additionalProperties: false + +required: + - compatible + - reg + - interrupts + - clocks + - clock-names + - resets + - ports + +additionalProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/arm-gic.h> + + #include <dt-bindings/clock/sun9i-a80-de.h> + #include <dt-bindings/reset/sun9i-a80-de.h> + + deu0: deu@3300000 { + compatible = "allwinner,sun9i-a80-deu"; + reg = <0x03300000 0x40000>; + interrupts = <GIC_SPI 92 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&de_clocks CLK_BUS_DEU0>, + <&de_clocks CLK_IEP_DEU0>, + <&de_clocks CLK_DRAM_DEU0>; + clock-names = "ahb", + "mod", + "ram"; + resets = <&de_clocks RST_DEU0>; + + ports { + #address-cells = <1>; + #size-cells = <0>; + + deu0_in: port@0 { + reg = <0>; + + deu0_in_fe0: endpoint { + remote-endpoint = <&fe0_out_deu0>; + }; + }; + + deu0_out: port@1 { + #address-cells = <1>; + #size-cells = <0>; + reg = <1>; + + deu0_out_be0: endpoint@0 { + reg = <0>; + remote-endpoint = <&be0_in_deu0>; + }; + + deu0_out_be1: endpoint@1 { + reg = <1>; + remote-endpoint = <&be1_in_deu0>; + }; + }; + }; + }; + +... diff --git a/Documentation/devicetree/bindings/display/bridge/lvds-codec.yaml b/Documentation/devicetree/bindings/display/bridge/lvds-codec.yaml new file mode 100644 index 000000000000..8f373029f5d2 --- /dev/null +++ b/Documentation/devicetree/bindings/display/bridge/lvds-codec.yaml @@ -0,0 +1,131 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/display/bridge/lvds-codec.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Transparent LVDS encoders and decoders + +maintainers: + - Laurent Pinchart <laurent.pinchart+renesas@ideasonboard.com> + +description: | + This binding supports transparent LVDS encoders and decoders that don't + require any configuration. + + LVDS is a physical layer specification defined in ANSI/TIA/EIA-644-A. Multiple + incompatible data link layers have been used over time to transmit image data + to LVDS panels. This binding targets devices compatible with the following + specifications only. + + [JEIDA] "Digital Interface Standards for Monitor", JEIDA-59-1999, February + 1999 (Version 1.0), Japan Electronic Industry Development Association (JEIDA) + [LDI] "Open LVDS Display Interface", May 1999 (Version 0.95), National + Semiconductor + [VESA] "VESA Notebook Panel Standard", October 2007 (Version 1.0), Video + Electronics Standards Association (VESA) + + Those devices have been marketed under the FPD-Link and FlatLink brand names + among others. + +properties: + compatible: + oneOf: + - items: + - enum: + - ti,ds90c185 # For the TI DS90C185 FPD-Link Serializer + - ti,ds90c187 # For the TI DS90C187 FPD-Link Serializer + - ti,sn75lvds83 # For the TI SN75LVDS83 FlatLink transmitter + - const: lvds-encoder # Generic LVDS encoder compatible fallback + - items: + - enum: + - ti,ds90cf384a # For the DS90CF384A FPD-Link LVDS Receiver + - const: lvds-decoder # Generic LVDS decoders compatible fallback + - enum: + - thine,thc63lvdm83d # For the THC63LVDM83D LVDS serializer + + ports: + type: object + description: | + This device has two video ports. Their connections are modeled using the + OF graph bindings specified in Documentation/devicetree/bindings/graph.txt + properties: + port@0: + type: object + description: | + For LVDS encoders, port 0 is the parallel input + For LVDS decoders, port 0 is the LVDS input + + port@1: + type: object + description: | + For LVDS encoders, port 1 is the LVDS output + For LVDS decoders, port 1 is the parallel output + + required: + - port@0 + - port@1 + + powerdown-gpios: + description: + The GPIO used to control the power down line of this device. + maxItems: 1 + +required: + - compatible + - ports + +examples: + - | + lvds-encoder { + compatible = "ti,ds90c185", "lvds-encoder"; + + ports { + #address-cells = <1>; + #size-cells = <0>; + + port@0 { + reg = <0>; + + lvds_enc_in: endpoint { + remote-endpoint = <&display_out_rgb>; + }; + }; + + port@1 { + reg = <1>; + + lvds_enc_out: endpoint { + remote-endpoint = <&lvds_panel_in>; + }; + }; + }; + }; + + - | + lvds-decoder { + compatible = "ti,ds90cf384a", "lvds-decoder"; + + ports { + #address-cells = <1>; + #size-cells = <0>; + + port@0 { + reg = <0>; + + lvds_dec_in: endpoint { + remote-endpoint = <&display_out_lvds>; + }; + }; + + port@1 { + reg = <1>; + + lvds_dec_out: endpoint { + remote-endpoint = <&rgb_panel_in>; + }; + }; + }; + }; + +... diff --git a/Documentation/devicetree/bindings/display/bridge/lvds-transmitter.txt b/Documentation/devicetree/bindings/display/bridge/lvds-transmitter.txt deleted file mode 100644 index 60091db5dfa5..000000000000 --- a/Documentation/devicetree/bindings/display/bridge/lvds-transmitter.txt +++ /dev/null @@ -1,66 +0,0 @@ -Parallel to LVDS Encoder ------------------------- - -This binding supports the parallel to LVDS encoders that don't require any -configuration. - -LVDS is a physical layer specification defined in ANSI/TIA/EIA-644-A. Multiple -incompatible data link layers have been used over time to transmit image data -to LVDS panels. This binding targets devices compatible with the following -specifications only. - -[JEIDA] "Digital Interface Standards for Monitor", JEIDA-59-1999, February -1999 (Version 1.0), Japan Electronic Industry Development Association (JEIDA) -[LDI] "Open LVDS Display Interface", May 1999 (Version 0.95), National -Semiconductor -[VESA] "VESA Notebook Panel Standard", October 2007 (Version 1.0), Video -Electronics Standards Association (VESA) - -Those devices have been marketed under the FPD-Link and FlatLink brand names -among others. - - -Required properties: - -- compatible: Must be "lvds-encoder" - - Any encoder compatible with this generic binding, but with additional - properties not listed here, must list a device specific compatible first - followed by this generic compatible. - -Required nodes: - -This device has two video ports. Their connections are modeled using the OF -graph bindings specified in Documentation/devicetree/bindings/graph.txt. - -- Video port 0 for parallel input -- Video port 1 for LVDS output - - -Example -------- - -lvds-encoder { - compatible = "lvds-encoder"; - - ports { - #address-cells = <1>; - #size-cells = <0>; - - port@0 { - reg = <0>; - - lvds_enc_in: endpoint { - remote-endpoint = <&display_out_rgb>; - }; - }; - - port@1 { - reg = <1>; - - lvds_enc_out: endpoint { - remote-endpoint = <&lvds_panel_in>; - }; - }; - }; -}; diff --git a/Documentation/devicetree/bindings/display/bridge/thine,thc63lvdm83d.txt b/Documentation/devicetree/bindings/display/bridge/thine,thc63lvdm83d.txt deleted file mode 100644 index fee3c88e1a17..000000000000 --- a/Documentation/devicetree/bindings/display/bridge/thine,thc63lvdm83d.txt +++ /dev/null @@ -1,50 +0,0 @@ -THine Electronics THC63LVDM83D LVDS serializer ----------------------------------------------- - -The THC63LVDM83D is an LVDS serializer designed to support pixel data -transmission between a host and a flat panel. - -Required properties: - -- compatible: Should be "thine,thc63lvdm83d" - -Optional properties: - -- powerdown-gpios: Power down control GPIO (the /PWDN pin, active low). - -Required nodes: - -The THC63LVDM83D has two video ports. Their connections are modeled using the -OFgraph bindings specified in Documentation/devicetree/bindings/graph.txt. - -- Video port 0 for CMOS/TTL input -- Video port 1 for LVDS output - - -Example -------- - - lvds_enc: encoder@0 { - compatible = "thine,thc63lvdm83d"; - - ports { - #address-cells = <1>; - #size-cells = <0>; - - port@0 { - reg = <0>; - - lvds_enc_in: endpoint@0 { - remote-endpoint = <&rgb_out>; - }; - }; - - port@1 { - reg = <1>; - - lvds_enc_out: endpoint@0 { - remote-endpoint = <&panel_in>; - }; - }; - }; - }; diff --git a/Documentation/devicetree/bindings/display/bridge/ti,ds90c185.txt b/Documentation/devicetree/bindings/display/bridge/ti,ds90c185.txt deleted file mode 100644 index e575f996959a..000000000000 --- a/Documentation/devicetree/bindings/display/bridge/ti,ds90c185.txt +++ /dev/null @@ -1,55 +0,0 @@ -Texas Instruments FPD-Link (LVDS) Serializer --------------------------------------------- - -The DS90C185 and DS90C187 are low-power serializers for portable -battery-powered applications that reduces the size of the RGB -interface between the host GPU and the display. - -Required properties: - -- compatible: Should be - "ti,ds90c185", "lvds-encoder" for the TI DS90C185 FPD-Link Serializer - "ti,ds90c187", "lvds-encoder" for the TI DS90C187 FPD-Link Serializer - -Optional properties: - -- powerdown-gpios: Power down control GPIO (the PDB pin, active-low) - -Required nodes: - -The devices have two video ports. Their connections are modeled using the OF -graph bindings specified in Documentation/devicetree/bindings/graph.txt. - -- Video port 0 for parallel input -- Video port 1 for LVDS output - - -Example -------- - -lvds-encoder { - compatible = "ti,ds90c185", "lvds-encoder"; - - powerdown-gpios = <&gpio 17 GPIO_ACTIVE_LOW>; - - ports { - #address-cells = <1>; - #size-cells = <0>; - - port@0 { - reg = <0>; - - lvds_enc_in: endpoint { - remote-endpoint = <&lcdc_out_rgb>; - }; - }; - - port@1 { - reg = <1>; - - lvds_enc_out: endpoint { - remote-endpoint = <&lvds_panel_in>; - }; - }; - }; -}; diff --git a/Documentation/devicetree/bindings/display/dsi-controller.yaml b/Documentation/devicetree/bindings/display/dsi-controller.yaml new file mode 100644 index 000000000000..fd986c36c737 --- /dev/null +++ b/Documentation/devicetree/bindings/display/dsi-controller.yaml @@ -0,0 +1,91 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/display/dsi-controller.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Common Properties for DSI Display Panels + +maintainers: + - Linus Walleij <linus.walleij@linaro.org> + +description: | + This document defines device tree properties common to DSI, Display + Serial Interface controllers and attached panels. It doesn't constitute + a device tree binding specification by itself but is meant to be referenced + by device tree bindings. + + When referenced from panel device tree bindings the properties defined in + this document are defined as follows. The panel device tree bindings are + responsible for defining whether each property is required or optional. + + Notice: this binding concerns DSI panels connected directly to a master + without any intermediate port graph to the panel. Each DSI master + can control one to four virtual channels to one panel. Each virtual + channel should have a node "panel" for their virtual channel with their + reg-property set to the virtual channel number, usually there is just + one virtual channel, number 0. + +properties: + $nodename: + pattern: "^dsi-controller(@.*)?$" + + "#address-cells": + const: 1 + + "#size-cells": + const: 0 + +patternProperties: + "^panel@[0-3]$": + description: Panels connected to the DSI link + type: object + + properties: + reg: + minimum: 0 + maximum: 3 + description: + The virtual channel number of a DSI peripheral. Must be in the range + from 0 to 3, as DSI uses a 2-bit addressing scheme. Some DSI + peripherals respond to more than a single virtual channel. In that + case the reg property can take multiple entries, one for each virtual + channel that the peripheral responds to. + + clock-master: + type: boolean + description: + Should be enabled if the host is being used in conjunction with + another DSI host to drive the same peripheral. Hardware supporting + such a configuration generally requires the data on both the busses + to be driven by the same clock. Only the DSI host instance + controlling this clock should contain this property. + + enforce-video-mode: + type: boolean + description: + The best option is usually to run a panel in command mode, as this + gives better control over the panel hardware. However for different + reasons like broken hardware, missing features or testing, it may be + useful to be able to force a command mode-capable panel into video + mode. + + required: + - reg + +examples: + - | + #include <dt-bindings/gpio/gpio.h> + dsi-controller@a0351000 { + reg = <0xa0351000 0x1000>; + #address-cells = <1>; + #size-cells = <0>; + panel@0 { + compatible = "sony,acx424akp"; + reg = <0>; + vddi-supply = <&ab8500_ldo_aux1_reg>; + reset-gpios = <&gpio2 1 GPIO_ACTIVE_LOW>; + }; + }; + +... diff --git a/Documentation/devicetree/bindings/display/ingenic,lcd.txt b/Documentation/devicetree/bindings/display/ingenic,lcd.txt index 7b536c8c6dde..01e3261defb6 100644 --- a/Documentation/devicetree/bindings/display/ingenic,lcd.txt +++ b/Documentation/devicetree/bindings/display/ingenic,lcd.txt @@ -4,6 +4,7 @@ Required properties: - compatible: one of: * ingenic,jz4740-lcd * ingenic,jz4725b-lcd + * ingenic,jz4770-lcd - reg: LCD registers location and length - clocks: LCD pixclock and device clock specifiers. The device clock is only required on the JZ4740. diff --git a/Documentation/devicetree/bindings/display/msm/dpu.txt b/Documentation/devicetree/bindings/display/msm/dpu.txt index a61dd40f3792..551ae26f60da 100644 --- a/Documentation/devicetree/bindings/display/msm/dpu.txt +++ b/Documentation/devicetree/bindings/display/msm/dpu.txt @@ -8,7 +8,7 @@ The DPU display controller is found in SDM845 SoC. MDSS: Required properties: -- compatible: "qcom,sdm845-mdss" +- compatible: "qcom,sdm845-mdss", "qcom,sc7180-mdss" - reg: physical base address and length of contoller's registers. - reg-names: register region names. The following region is required: * "mdss" @@ -41,7 +41,7 @@ Optional properties: MDP: Required properties: -- compatible: "qcom,sdm845-dpu" +- compatible: "qcom,sdm845-dpu", "qcom,sc7180-dpu" - reg: physical base address and length of controller's registers. - reg-names : register region names. The following region is required: * "mdp" diff --git a/Documentation/devicetree/bindings/display/msm/gpu.txt b/Documentation/devicetree/bindings/display/msm/gpu.txt index 2b8fd26c43b0..7edc298a15f2 100644 --- a/Documentation/devicetree/bindings/display/msm/gpu.txt +++ b/Documentation/devicetree/bindings/display/msm/gpu.txt @@ -23,13 +23,18 @@ Required properties: - iommus: optional phandle to an adreno iommu instance - operating-points-v2: optional phandle to the OPP operating points - interconnects: optional phandle to an interconnect provider. See - ../interconnect/interconnect.txt for details. + ../interconnect/interconnect.txt for details. Some A3xx and all A4xx platforms + will have two paths; all others will have one path. +- interconnect-names: The names of the interconnect paths that correspond to the + interconnects property. Values must be gfx-mem and ocmem. - qcom,gmu: For GMU attached devices a phandle to the GMU device that will control the power for the GPU. Applicable targets: - qcom,adreno-630.2 - zap-shader: For a5xx and a6xx devices this node contains a memory-region that points to reserved memory to store the zap shader that can be used to help bring the GPU out of secure mode. +- firmware-name: optional property of the 'zap-shader' node, listing the + relative path of the device specific zap firmware. Example 3xx/4xx/a5xx: @@ -76,11 +81,13 @@ Example a6xx (with GMU): operating-points-v2 = <&gpu_opp_table>; interconnects = <&rsc_hlos MASTER_GFX3D &rsc_hlos SLAVE_EBI1>; + interconnect-names = "gfx-mem"; qcom,gmu = <&gmu>; zap-shader { memory-region = <&zap_shader_region>; + firmware-name = "qcom/LENOVO/81JL/qcdxkmsuc850.mbn" }; }; }; diff --git a/Documentation/devicetree/bindings/display/mxsfb.txt b/Documentation/devicetree/bindings/display/mxsfb.txt index 472e1ea6c591..c985871c46b3 100644 --- a/Documentation/devicetree/bindings/display/mxsfb.txt +++ b/Documentation/devicetree/bindings/display/mxsfb.txt @@ -6,6 +6,7 @@ Required properties: - compatible: Should be "fsl,imx23-lcdif" for i.MX23. Should be "fsl,imx28-lcdif" for i.MX28. Should be "fsl,imx6sx-lcdif" for i.MX6SX. + Should be "fsl,imx8mq-lcdif" for i.MX8MQ. - reg: Address and length of the register set for LCDIF - interrupts: Should contain LCDIF interrupt - clocks: A list of phandle + clock-specifier pairs, one for each diff --git a/Documentation/devicetree/bindings/display/panel/ampire,am-480272h3tmqw-t01h.yaml b/Documentation/devicetree/bindings/display/panel/ampire,am-480272h3tmqw-t01h.yaml deleted file mode 100644 index c6e33e7f36d0..000000000000 --- a/Documentation/devicetree/bindings/display/panel/ampire,am-480272h3tmqw-t01h.yaml +++ /dev/null @@ -1,42 +0,0 @@ -# SPDX-License-Identifier: GPL-2.0 -%YAML 1.2 ---- -$id: http://devicetree.org/schemas/display/panel/ampire,am-480272h3tmqw-t01h.yaml# -$schema: http://devicetree.org/meta-schemas/core.yaml# - -title: Ampire AM-480272H3TMQW-T01H 4.3" WQVGA TFT LCD panel - -maintainers: - - Yannick Fertre <yannick.fertre@st.com> - - Thierry Reding <treding@nvidia.com> - -allOf: - - $ref: panel-common.yaml# - -properties: - compatible: - const: ampire,am-480272h3tmqw-t01h - - power-supply: true - enable-gpios: true - backlight: true - port: true - -required: - - compatible - -additionalProperties: false - -examples: - - | - panel_rgb: panel { - compatible = "ampire,am-480272h3tmqw-t01h"; - enable-gpios = <&gpioa 8 1>; - port { - panel_in_rgb: endpoint { - remote-endpoint = <&controller_out_rgb>; - }; - }; - }; - -... diff --git a/Documentation/devicetree/bindings/display/panel/ampire,am800480r3tmqwa1h.txt b/Documentation/devicetree/bindings/display/panel/ampire,am800480r3tmqwa1h.txt deleted file mode 100644 index 83e2cae1cc1b..000000000000 --- a/Documentation/devicetree/bindings/display/panel/ampire,am800480r3tmqwa1h.txt +++ /dev/null @@ -1,7 +0,0 @@ -Ampire AM-800480R3TMQW-A1H 7.0" WVGA TFT LCD panel - -Required properties: -- compatible: should be "ampire,am800480r3tmqwa1h" - -This binding is compatible with the simple-panel binding, which is specified -in simple-panel.txt in this directory. diff --git a/Documentation/devicetree/bindings/display/panel/giantplus,gpm940b0.txt b/Documentation/devicetree/bindings/display/panel/giantplus,gpm940b0.txt deleted file mode 100644 index 3dab52f92c26..000000000000 --- a/Documentation/devicetree/bindings/display/panel/giantplus,gpm940b0.txt +++ /dev/null @@ -1,12 +0,0 @@ -GiantPlus 3.0" (320x240 pixels) 24-bit TFT LCD panel - -Required properties: -- compatible: should be "giantplus,gpm940b0" -- power-supply: as specified in the base binding - -Optional properties: -- backlight: as specified in the base binding -- enable-gpios: as specified in the base binding - -This binding is compatible with the simple-panel binding, which is specified -in simple-panel.txt in this directory. diff --git a/Documentation/devicetree/bindings/display/panel/leadtek,ltk500hd1829.yaml b/Documentation/devicetree/bindings/display/panel/leadtek,ltk500hd1829.yaml new file mode 100644 index 000000000000..4ebcea7d0c63 --- /dev/null +++ b/Documentation/devicetree/bindings/display/panel/leadtek,ltk500hd1829.yaml @@ -0,0 +1,49 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/display/panel/leadtek,ltk500hd1829.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Leadtek LTK500HD1829 5.0in 720x1280 DSI panel + +maintainers: + - Heiko Stuebner <heiko.stuebner@theobroma-systems.com> + +allOf: + - $ref: panel-common.yaml# + +properties: + compatible: + const: leadtek,ltk500hd1829 + reg: true + backlight: true + reset-gpios: true + iovcc-supply: + description: regulator that supplies the iovcc voltage + vcc-supply: + description: regulator that supplies the vcc voltage + +required: + - compatible + - reg + - backlight + - iovcc-supply + - vcc-supply + +additionalProperties: false + +examples: + - | + dsi@ff450000 { + #address-cells = <1>; + #size-cells = <0>; + panel@0 { + compatible = "leadtek,ltk500hd1829"; + reg = <0>; + backlight = <&backlight>; + iovcc-supply = <&vcc_1v8>; + vcc-supply = <&vcc_2v8>; + }; + }; + +... diff --git a/Documentation/devicetree/bindings/display/panel/logicpd,type28.yaml b/Documentation/devicetree/bindings/display/panel/logicpd,type28.yaml new file mode 100644 index 000000000000..2834287b8d88 --- /dev/null +++ b/Documentation/devicetree/bindings/display/panel/logicpd,type28.yaml @@ -0,0 +1,42 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/display/panel/logicpd,type28.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Logic PD Type 28 4.3" WQVGA TFT LCD panel + +maintainers: + - Adam Ford <aford173@gmail.com> + +allOf: + - $ref: panel-common.yaml# + +properties: + compatible: + const: logicpd,type28 + + power-supply: true + enable-gpios: true + backlight: true + port: true + +required: + - compatible + +additionalProperties: false + +examples: + - | + lcd0: display { + compatible = "logicpd,type28"; + enable-gpios = <&gpio5 27 0>; + backlight = <&backlight>; + port { + lcd_in: endpoint { + remote-endpoint = <&dpi_out>; + }; + }; + }; + +... diff --git a/Documentation/devicetree/bindings/display/panel/panel-simple.yaml b/Documentation/devicetree/bindings/display/panel/panel-simple.yaml new file mode 100644 index 000000000000..8fe60ee2531c --- /dev/null +++ b/Documentation/devicetree/bindings/display/panel/panel-simple.yaml @@ -0,0 +1,69 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/display/panel/panel-simple.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Simple panels with one power supply + +maintainers: + - Thierry Reding <thierry.reding@gmail.com> + - Sam Ravnborg <sam@ravnborg.org> + +description: | + This binding file is a collection of the simple (dumb) panels that + requires only a single power-supply. + There are optionally a backlight and an enable GPIO. + The panel may use an OF graph binding for the association to the display, + or it may be a direct child node of the display. + + If the panel is more advanced a dedicated binding file is required. + +allOf: + - $ref: panel-common.yaml# + +properties: + + compatible: + enum: + # compatible must be listed in alphabetical order, ordered by compatible. + # The description in the comment is mandatory for each compatible. + + # Ampire AM-480272H3TMQW-T01H 4.3" WQVGA TFT LCD panel + - ampire,am-480272h3tmqw-t01h + # Ampire AM-800480R3TMQW-A1H 7.0" WVGA TFT LCD panel + - ampire,am800480r3tmqwa1h + # AUO B116XAK01 eDP TFT LCD panel + - auo,b116xa01 + # BOE NV140FHM-N49 14.0" FHD a-Si FT panel + - boe,nv140fhmn49 + # GiantPlus GPM940B0 3.0" QVGA TFT LCD panel + - giantplus,gpm940b0 + # Satoz SAT050AT40H12R2 5.0" WVGA TFT LCD panel + - satoz,sat050at40h12r2 + # Sharp LS020B1DD01D 2.0" HQVGA TFT LCD panel + - sharp,ls020b1dd01d + + backlight: true + enable-gpios: true + port: true + power-supply: true + +additionalProperties: false + +required: + - compatible + - power-supply + +examples: + - | + panel_rgb: panel-rgb { + compatible = "ampire,am-480272h3tmqw-t01h"; + power-supply = <&vcc_lcd_reg>; + + port { + panel_in_rgb: endpoint { + remote-endpoint = <<dc_out_rgb>; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/display/panel/sharp,ls020b1dd01d.txt b/Documentation/devicetree/bindings/display/panel/sharp,ls020b1dd01d.txt deleted file mode 100644 index e45edbc565a3..000000000000 --- a/Documentation/devicetree/bindings/display/panel/sharp,ls020b1dd01d.txt +++ /dev/null @@ -1,12 +0,0 @@ -Sharp 2.0" (240x160 pixels) 16-bit TFT LCD panel - -Required properties: -- compatible: should be "sharp,ls020b1dd01d" -- power-supply: as specified in the base binding - -Optional properties: -- backlight: as specified in the base binding -- enable-gpios: as specified in the base binding - -This binding is compatible with the simple-panel binding, which is specified -in simple-panel.txt in this directory. diff --git a/Documentation/devicetree/bindings/display/panel/sony,acx424akp.yaml b/Documentation/devicetree/bindings/display/panel/sony,acx424akp.yaml new file mode 100644 index 000000000000..185dcc8fd1f9 --- /dev/null +++ b/Documentation/devicetree/bindings/display/panel/sony,acx424akp.yaml @@ -0,0 +1,49 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/display/panel/sony,acx424akp.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Sony ACX424AKP 4" 480x864 AMOLED panel + +maintainers: + - Linus Walleij <linus.walleij@linaro.org> + +allOf: + - $ref: panel-common.yaml# + +properties: + compatible: + const: sony,acx424akp + reg: true + reset-gpios: true + vddi-supply: + description: regulator that supplies the vddi voltage + enforce-video-mode: true + +required: + - compatible + - reg + - reset-gpios + +additionalProperties: false + +examples: + - | + #include <dt-bindings/gpio/gpio.h> + + dsi-controller@a0351000 { + compatible = "ste,mcde-dsi"; + reg = <0xa0351000 0x1000>; + #address-cells = <1>; + #size-cells = <0>; + + panel@0 { + compatible = "sony,acx424akp"; + reg = <0>; + vddi-supply = <&foo>; + reset-gpios = <&foo_gpio 0 GPIO_ACTIVE_LOW>; + }; + }; + +... diff --git a/Documentation/devicetree/bindings/display/panel/xinpeng,xpp055c272.yaml b/Documentation/devicetree/bindings/display/panel/xinpeng,xpp055c272.yaml new file mode 100644 index 000000000000..186e5e1c8fa3 --- /dev/null +++ b/Documentation/devicetree/bindings/display/panel/xinpeng,xpp055c272.yaml @@ -0,0 +1,49 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/display/panel/xinpeng,xpp055c272.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Xinpeng XPP055C272 5.5in 720x1280 DSI panel + +maintainers: + - Heiko Stuebner <heiko.stuebner@theobroma-systems.com> + +allOf: + - $ref: panel-common.yaml# + +properties: + compatible: + const: xinpeng,xpp055c272 + reg: true + backlight: true + reset-gpios: true + iovcc-supply: + description: regulator that supplies the iovcc voltage + vci-supply: + description: regulator that supplies the vci voltage + +required: + - compatible + - reg + - backlight + - iovcc-supply + - vci-supply + +additionalProperties: false + +examples: + - | + dsi@ff450000 { + #address-cells = <1>; + #size-cells = <0>; + panel@0 { + compatible = "xinpeng,xpp055c272"; + reg = <0>; + backlight = <&backlight>; + iovcc-supply = <&vcc_1v8>; + vci-supply = <&vcc3v3_lcd>; + }; + }; + +... diff --git a/Documentation/devicetree/bindings/display/renesas,cmm.yaml b/Documentation/devicetree/bindings/display/renesas,cmm.yaml new file mode 100644 index 000000000000..a57037b9e9ba --- /dev/null +++ b/Documentation/devicetree/bindings/display/renesas,cmm.yaml @@ -0,0 +1,67 @@ +# SPDX-License-Identifier: GPL-2.0-only +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/display/renesas,cmm.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Renesas R-Car Color Management Module (CMM) + +maintainers: + - Laurent Pinchart <laurent.pinchart@ideasonboard.com> + - Kieran Bingham <kieran.bingham+renesas@ideasonboard.com> + - Jacopo Mondi <jacopo+renesas@jmondi.org> + +description: |+ + Renesas R-Car color management module connected to R-Car DU video channels. + It provides image enhancement functions such as 1-D look-up tables (LUT), + 3-D look-up tables (CLU), 1D-histogram generation (HGO), and color + space conversion (CSC). + +properties: + compatible: + oneOf: + - items: + - enum: + - renesas,r8a7795-cmm + - renesas,r8a7796-cmm + - renesas,r8a77965-cmm + - renesas,r8a77990-cmm + - renesas,r8a77995-cmm + - const: renesas,rcar-gen3-cmm + - items: + - const: renesas,rcar-gen2-cmm + + reg: + maxItems: 1 + + clocks: + maxItems: 1 + + resets: + maxItems: 1 + + power-domains: + maxItems: 1 + +required: + - compatible + - reg + - clocks + - resets + - power-domains + +additionalProperties: false + +examples: + - | + #include <dt-bindings/clock/r8a7796-cpg-mssr.h> + #include <dt-bindings/power/r8a7796-sysc.h> + + cmm0: cmm@fea40000 { + compatible = "renesas,r8a7796-cmm", + "renesas,rcar-gen3-cmm"; + reg = <0 0xfea40000 0 0x1000>; + power-domains = <&sysc R8A7796_PD_ALWAYS_ON>; + clocks = <&cpg CPG_MOD 711>; + resets = <&cpg 711>; + }; diff --git a/Documentation/devicetree/bindings/display/renesas,du.txt b/Documentation/devicetree/bindings/display/renesas,du.txt index 17cb2771364b..eb4ae41fe41f 100644 --- a/Documentation/devicetree/bindings/display/renesas,du.txt +++ b/Documentation/devicetree/bindings/display/renesas,du.txt @@ -41,10 +41,14 @@ Required Properties: supplied they must be named "dclkin.x" with "x" being the input clock numerical index. - - vsps: A list of phandle and channel index tuples to the VSPs that handle - the memory interfaces for the DU channels. The phandle identifies the VSP - instance that serves the DU channel, and the channel index identifies the - LIF instance in that VSP. + - renesas,cmms: A list of phandles to the CMM instances present in the SoC, + one for each available DU channel. The property shall not be specified for + SoCs that do not provide any CMM (such as V3M and V3H). + + - renesas,vsps: A list of phandle and channel index tuples to the VSPs that + handle the memory interfaces for the DU channels. The phandle identifies the + VSP instance that serves the DU channel, and the channel index identifies + the LIF instance in that VSP. Required nodes: @@ -92,7 +96,8 @@ Example: R8A7795 (R-Car H3) ES2.0 DU <&cpg CPG_MOD 722>, <&cpg CPG_MOD 721>; clock-names = "du.0", "du.1", "du.2", "du.3"; - vsps = <&vspd0 0>, <&vspd1 0>, <&vspd2 0>, <&vspd0 1>; + renesas,cmms = <&cmm0>, <&cmm1>, <&cmm2>, <&cmm3>; + renesas,vsps = <&vspd0 0>, <&vspd1 0>, <&vspd2 0>, <&vspd0 1>; ports { #address-cells = <1>; diff --git a/Documentation/devicetree/bindings/display/rockchip/dw_mipi_dsi_rockchip.txt b/Documentation/devicetree/bindings/display/rockchip/dw_mipi_dsi_rockchip.txt index ce4c1fc9116c..151be3bba06f 100644 --- a/Documentation/devicetree/bindings/display/rockchip/dw_mipi_dsi_rockchip.txt +++ b/Documentation/devicetree/bindings/display/rockchip/dw_mipi_dsi_rockchip.txt @@ -4,13 +4,16 @@ Rockchip specific extensions to the Synopsys Designware MIPI DSI Required properties: - #address-cells: Should be <1>. - #size-cells: Should be <0>. -- compatible: "rockchip,rk3288-mipi-dsi", "snps,dw-mipi-dsi". - "rockchip,rk3399-mipi-dsi", "snps,dw-mipi-dsi". +- compatible: one of + "rockchip,px30-mipi-dsi", "snps,dw-mipi-dsi" + "rockchip,rk3288-mipi-dsi", "snps,dw-mipi-dsi" + "rockchip,rk3399-mipi-dsi", "snps,dw-mipi-dsi" - reg: Represent the physical address range of the controller. - interrupts: Represent the controller's interrupt to the CPU(s). - clocks, clock-names: Phandles to the controller's pll reference - clock(ref) and APB clock(pclk). For RK3399, a phy config clock - (phy_cfg) and a grf clock(grf) are required. As described in [1]. + clock(ref) when using an internal dphy and APB clock(pclk). + For RK3399, a phy config clock (phy_cfg) and a grf clock(grf) + are required. As described in [1]. - rockchip,grf: this soc should set GRF regs to mux vopl/vopb. - ports: contain a port node with endpoint definitions as defined in [2]. For vopb,set the reg = <0> and set the reg = <1> for vopl. @@ -18,6 +21,8 @@ Required properties: - video port 1 for either a panel or subsequent encoder Optional properties: +- phys: from general PHY binding: the phandle for the PHY device. +- phy-names: Should be "dphy" if phys references an external phy. - power-domains: a phandle to mipi dsi power domain node. - resets: list of phandle + reset specifier pairs, as described in [3]. - reset-names: string reset name, must be "apb". diff --git a/Documentation/devicetree/bindings/display/rockchip/rockchip-lvds.txt b/Documentation/devicetree/bindings/display/rockchip/rockchip-lvds.txt index 7849ff039229..aaf8c44cf90f 100644 --- a/Documentation/devicetree/bindings/display/rockchip/rockchip-lvds.txt +++ b/Documentation/devicetree/bindings/display/rockchip/rockchip-lvds.txt @@ -4,6 +4,7 @@ Rockchip RK3288 LVDS interface Required properties: - compatible: matching the soc type, one of - "rockchip,rk3288-lvds"; + - "rockchip,px30-lvds"; - reg: physical base address of the controller and length of memory mapped region. @@ -18,6 +19,9 @@ Required properties: - rockchip,grf: phandle to the general register files syscon - rockchip,output: "rgb", "lvds" or "duallvds", This describes the output interface +- phys: LVDS/DSI DPHY (px30 only) +- phy-names: name of the PHY, must be "dphy" (px30 only) + Optional properties: - pinctrl-names: must contain a "lcdc" entry. - pinctrl-0: pin control group to be used for this controller. diff --git a/Documentation/devicetree/bindings/display/sunxi/sun4i-drm.txt b/Documentation/devicetree/bindings/display/sunxi/sun4i-drm.txt deleted file mode 100644 index 31ab72cba3d4..000000000000 --- a/Documentation/devicetree/bindings/display/sunxi/sun4i-drm.txt +++ /dev/null @@ -1,637 +0,0 @@ -Allwinner A10 Display Pipeline -============================== - -The Allwinner A10 Display pipeline is composed of several components -that are going to be documented below: - -For all connections between components up to the TCONs in the display -pipeline, when there are multiple components of the same type at the -same depth, the local endpoint ID must be the same as the remote -component's index. For example, if the remote endpoint is Frontend 1, -then the local endpoint ID must be 1. - - Frontend 0 [0] ------- [0] Backend 0 [0] ------- [0] TCON 0 - [1] -- -- [1] [1] -- -- [1] - \ / \ / - X X - / \ / \ - [0] -- -- [0] [0] -- -- [0] - Frontend 1 [1] ------- [1] Backend 1 [1] ------- [1] TCON 1 - -For a two pipeline system such as the one depicted above, the lines -represent the connections between the components, while the numbers -within the square brackets corresponds to the ID of the local endpoint. - -The same rule also applies to DE 2.0 mixer-TCON connections: - - Mixer 0 [0] ----------- [0] TCON 0 - [1] ---- ---- [1] - \ / - X - / \ - [0] ---- ---- [0] - Mixer 1 [1] ----------- [1] TCON 1 - -HDMI Encoder ------------- - -The HDMI Encoder supports the HDMI video and audio outputs, and does -CEC. It is one end of the pipeline. - -Required properties: - - compatible: value must be one of: - * allwinner,sun4i-a10-hdmi - * allwinner,sun5i-a10s-hdmi - * allwinner,sun6i-a31-hdmi - - reg: base address and size of memory-mapped region - - interrupts: interrupt associated to this IP - - clocks: phandles to the clocks feeding the HDMI encoder - * ahb: the HDMI interface clock - * mod: the HDMI module clock - * ddc: the HDMI ddc clock (A31 only) - * pll-0: the first video PLL - * pll-1: the second video PLL - - clock-names: the clock names mentioned above - - resets: phandle to the reset control for the HDMI encoder (A31 only) - - dmas: phandles to the DMA channels used by the HDMI encoder - * ddc-tx: The channel for DDC transmission - * ddc-rx: The channel for DDC reception - * audio-tx: The channel used for audio transmission - - dma-names: the channel names mentioned above - - - ports: A ports node with endpoint definitions as defined in - Documentation/devicetree/bindings/media/video-interfaces.txt. The - first port should be the input endpoint. The second should be the - output, usually to an HDMI connector. - -DWC HDMI TX Encoder -------------------- - -The HDMI transmitter is a Synopsys DesignWare HDMI 1.4 TX controller IP -with Allwinner's own PHY IP. It supports audio and video outputs and CEC. - -These DT bindings follow the Synopsys DWC HDMI TX bindings defined in -Documentation/devicetree/bindings/display/bridge/dw_hdmi.txt with the -following device-specific properties. - -Required properties: - - - compatible: value must be one of: - * "allwinner,sun8i-a83t-dw-hdmi" - * "allwinner,sun50i-a64-dw-hdmi", "allwinner,sun8i-a83t-dw-hdmi" - * "allwinner,sun50i-h6-dw-hdmi" - - reg: base address and size of memory-mapped region - - reg-io-width: See dw_hdmi.txt. Shall be 1. - - interrupts: HDMI interrupt number - - clocks: phandles to the clocks feeding the HDMI encoder - * iahb: the HDMI bus clock - * isfr: the HDMI register clock - * tmds: TMDS clock - * cec: HDMI CEC clock (H6 only) - * hdcp: HDCP clock (H6 only) - * hdcp-bus: HDCP bus clock (H6 only) - - clock-names: the clock names mentioned above - - resets: - * ctrl: HDMI controller reset - * hdcp: HDCP reset (H6 only) - - reset-names: reset names mentioned above - - phys: phandle to the DWC HDMI PHY - - phy-names: must be "phy" - - - ports: A ports node with endpoint definitions as defined in - Documentation/devicetree/bindings/media/video-interfaces.txt. The - first port should be the input endpoint. The second should be the - output, usually to an HDMI connector. - -Optional properties: - - hvcc-supply: the VCC power supply of the controller - -DWC HDMI PHY ------------- - -Required properties: - - compatible: value must be one of: - * allwinner,sun8i-a83t-hdmi-phy - * allwinner,sun8i-h3-hdmi-phy - * allwinner,sun8i-r40-hdmi-phy - * allwinner,sun50i-a64-hdmi-phy - * allwinner,sun50i-h6-hdmi-phy - - reg: base address and size of memory-mapped region - - clocks: phandles to the clocks feeding the HDMI PHY - * bus: the HDMI PHY interface clock - * mod: the HDMI PHY module clock - - clock-names: the clock names mentioned above - - resets: phandle to the reset controller driving the PHY - - reset-names: must be "phy" - -H3, A64 and R40 HDMI PHY require additional clocks: - - pll-0: parent of phy clock - - pll-1: second possible phy clock parent (A64/R40 only) - -TV Encoder ----------- - -The TV Encoder supports the composite and VGA output. It is one end of -the pipeline. - -Required properties: - - compatible: value should be "allwinner,sun4i-a10-tv-encoder". - - reg: base address and size of memory-mapped region - - clocks: the clocks driving the TV encoder - - resets: phandle to the reset controller driving the encoder - -- ports: A ports node with endpoint definitions as defined in - Documentation/devicetree/bindings/media/video-interfaces.txt. The - first port should be the input endpoint. - -TCON ----- - -The TCON acts as a timing controller for RGB, LVDS and TV interfaces. - -Required properties: - - compatible: value must be either: - * allwinner,sun4i-a10-tcon - * allwinner,sun5i-a13-tcon - * allwinner,sun6i-a31-tcon - * allwinner,sun6i-a31s-tcon - * allwinner,sun7i-a20-tcon - * allwinner,sun8i-a23-tcon - * allwinner,sun8i-a33-tcon - * allwinner,sun8i-a83t-tcon-lcd - * allwinner,sun8i-a83t-tcon-tv - * allwinner,sun8i-r40-tcon-tv - * allwinner,sun8i-v3s-tcon - * allwinner,sun9i-a80-tcon-lcd - * allwinner,sun9i-a80-tcon-tv - * "allwinner,sun50i-a64-tcon-lcd", "allwinner,sun8i-a83t-tcon-lcd" - * "allwinner,sun50i-a64-tcon-tv", "allwinner,sun8i-a83t-tcon-tv" - * allwinner,sun50i-h6-tcon-tv, allwinner,sun8i-r40-tcon-tv - - reg: base address and size of memory-mapped region - - interrupts: interrupt associated to this IP - - clocks: phandles to the clocks feeding the TCON. - - 'ahb': the interface clocks - - 'tcon-ch0': The clock driving the TCON channel 0, if supported - - resets: phandles to the reset controllers driving the encoder - - "lcd": the reset line for the TCON - - "edp": the reset line for the eDP block (A80 only) - - - clock-names: the clock names mentioned above - - reset-names: the reset names mentioned above - - clock-output-names: Name of the pixel clock created, if TCON supports - channel 0. - -- ports: A ports node with endpoint definitions as defined in - Documentation/devicetree/bindings/media/video-interfaces.txt. The - first port should be the input endpoint, the second one the output - - The output may have multiple endpoints. TCON can have 1 or 2 channels, - usually with the first channel being used for the panels interfaces - (RGB, LVDS, etc.), and the second being used for the outputs that - require another controller (TV Encoder, HDMI, etc.). The endpoints - will take an extra property, allwinner,tcon-channel, to specify the - channel the endpoint is associated to. If that property is not - present, the endpoint number will be used as the channel number. - -For TCONs with channel 0, there is one more clock required: - - 'tcon-ch0': The clock driving the TCON channel 0 -For TCONs with channel 1, there is one more clock required: - - 'tcon-ch1': The clock driving the TCON channel 1 - -When TCON support LVDS (all TCONs except TV TCONs on A83T, R40 and those found -in A13, H3, H5 and V3s SoCs), you need one more reset line: - - 'lvds': The reset line driving the LVDS logic - -And on the A23, A31, A31s and A33, you need one more clock line: - - 'lvds-alt': An alternative clock source, separate from the TCON channel 0 - clock, that can be used to drive the LVDS clock - -TCON TOP --------- - -TCON TOPs main purpose is to configure whole display pipeline. It determines -relationships between mixers and TCONs, selects source TCON for HDMI, muxes -LCD and TV encoder GPIO output, selects TV encoder clock source and contains -additional TV TCON and DSI gates. - -It allows display pipeline to be configured in very different ways: - - / LCD0/LVDS0 - / [0] TCON-LCD0 - | \ MIPI DSI - mixer0 | - \ / [1] TCON-LCD1 - LCD1/LVDS1 - TCON-TOP - / \ [2] TCON-TV0 [0] - TVE0/RGB - mixer1 | \ - | TCON-TOP - HDMI - | / - \ [3] TCON-TV1 [1] - TVE1/RGB - -Note that both TCON TOP references same physical unit. Both mixers can be -connected to any TCON. Not all TCON TOP variants support all features. - -Required properties: - - compatible: value must be one of: - * allwinner,sun8i-r40-tcon-top - * allwinner,sun50i-h6-tcon-top - - reg: base address and size of the memory-mapped region. - - clocks: phandle to the clocks feeding the TCON TOP - * bus: TCON TOP interface clock - * tcon-tv0: TCON TV0 clock - * tve0: TVE0 clock (R40 only) - * tcon-tv1: TCON TV1 clock (R40 only) - * tve1: TVE0 clock (R40 only) - * dsi: MIPI DSI clock (R40 only) - - clock-names: clock name mentioned above - - resets: phandle to the reset line driving the TCON TOP - - #clock-cells : must contain 1 - - clock-output-names: Names of clocks created for TCON TV0 channel clock, - TCON TV1 channel clock (R40 only) and DSI channel clock (R40 only), in - that order. - -- ports: A ports node with endpoint definitions as defined in - Documentation/devicetree/bindings/media/video-interfaces.txt. 6 ports should - be defined: - * port 0 is input for mixer0 mux - * port 1 is output for mixer0 mux - * port 2 is input for mixer1 mux - * port 3 is output for mixer1 mux - * port 4 is input for HDMI mux - * port 5 is output for HDMI mux - All output endpoints for mixer muxes and input endpoints for HDMI mux should - have reg property with the id of the target TCON, as shown in above graph - (0-3 for mixer muxes and 0-1 for HDMI mux). All ports should have only one - endpoint connected to remote endpoint. - -DRC ---- - -The DRC (Dynamic Range Controller), found in the latest Allwinner SoCs -(A31, A23, A33, A80), allows to dynamically adjust pixel -brightness/contrast based on histogram measurements for LCD content -adaptive backlight control. - - -Required properties: - - compatible: value must be one of: - * allwinner,sun6i-a31-drc - * allwinner,sun6i-a31s-drc - * allwinner,sun8i-a23-drc - * allwinner,sun8i-a33-drc - * allwinner,sun9i-a80-drc - - reg: base address and size of the memory-mapped region. - - interrupts: interrupt associated to this IP - - clocks: phandles to the clocks feeding the DRC - * ahb: the DRC interface clock - * mod: the DRC module clock - * ram: the DRC DRAM clock - - clock-names: the clock names mentioned above - - resets: phandles to the reset line driving the DRC - -- ports: A ports node with endpoint definitions as defined in - Documentation/devicetree/bindings/media/video-interfaces.txt. The - first port should be the input endpoints, the second one the outputs - -Display Engine Backend ----------------------- - -The display engine backend exposes layers and sprites to the -system. - -Required properties: - - compatible: value must be one of: - * allwinner,sun4i-a10-display-backend - * allwinner,sun5i-a13-display-backend - * allwinner,sun6i-a31-display-backend - * allwinner,sun7i-a20-display-backend - * allwinner,sun8i-a23-display-backend - * allwinner,sun8i-a33-display-backend - * allwinner,sun9i-a80-display-backend - - reg: base address and size of the memory-mapped region. - - interrupts: interrupt associated to this IP - - clocks: phandles to the clocks feeding the frontend and backend - * ahb: the backend interface clock - * mod: the backend module clock - * ram: the backend DRAM clock - - clock-names: the clock names mentioned above - - resets: phandles to the reset controllers driving the backend - -- ports: A ports node with endpoint definitions as defined in - Documentation/devicetree/bindings/media/video-interfaces.txt. The - first port should be the input endpoints, the second one the output - -On the A33, some additional properties are required: - - reg needs to have an additional region corresponding to the SAT - - reg-names need to be set, with "be" and "sat" - - clocks and clock-names need to have a phandle to the SAT bus - clocks, whose name will be "sat" - - resets and reset-names need to have a phandle to the SAT bus - resets, whose name will be "sat" - -DEU ---- - -The DEU (Detail Enhancement Unit), found in the Allwinner A80 SoC, -can sharpen the display content in both luma and chroma channels. - -Required properties: - - compatible: value must be one of: - * allwinner,sun9i-a80-deu - - reg: base address and size of the memory-mapped region. - - interrupts: interrupt associated to this IP - - clocks: phandles to the clocks feeding the DEU - * ahb: the DEU interface clock - * mod: the DEU module clock - * ram: the DEU DRAM clock - - clock-names: the clock names mentioned above - - resets: phandles to the reset line driving the DEU - -- ports: A ports node with endpoint definitions as defined in - Documentation/devicetree/bindings/media/video-interfaces.txt. The - first port should be the input endpoints, the second one the outputs - -Display Engine Frontend ------------------------ - -The display engine frontend does formats conversion, scaling, -deinterlacing and color space conversion. - -Required properties: - - compatible: value must be one of: - * allwinner,sun4i-a10-display-frontend - * allwinner,sun5i-a13-display-frontend - * allwinner,sun6i-a31-display-frontend - * allwinner,sun7i-a20-display-frontend - * allwinner,sun8i-a23-display-frontend - * allwinner,sun8i-a33-display-frontend - * allwinner,sun9i-a80-display-frontend - - reg: base address and size of the memory-mapped region. - - interrupts: interrupt associated to this IP - - clocks: phandles to the clocks feeding the frontend and backend - * ahb: the backend interface clock - * mod: the backend module clock - * ram: the backend DRAM clock - - clock-names: the clock names mentioned above - - resets: phandles to the reset controllers driving the backend - -- ports: A ports node with endpoint definitions as defined in - Documentation/devicetree/bindings/media/video-interfaces.txt. The - first port should be the input endpoints, the second one the outputs - -Display Engine 2.0 Mixer ------------------------- - -The DE2 mixer have many functionalities, currently only layer blending is -supported. - -Required properties: - - compatible: value must be one of: - * allwinner,sun8i-a83t-de2-mixer-0 - * allwinner,sun8i-a83t-de2-mixer-1 - * allwinner,sun8i-h3-de2-mixer-0 - * allwinner,sun8i-r40-de2-mixer-0 - * allwinner,sun8i-r40-de2-mixer-1 - * allwinner,sun8i-v3s-de2-mixer - * allwinner,sun50i-a64-de2-mixer-0 - * allwinner,sun50i-a64-de2-mixer-1 - * allwinner,sun50i-h6-de3-mixer-0 - - reg: base address and size of the memory-mapped region. - - clocks: phandles to the clocks feeding the mixer - * bus: the mixer interface clock - * mod: the mixer module clock - - clock-names: the clock names mentioned above - - resets: phandles to the reset controllers driving the mixer - -- ports: A ports node with endpoint definitions as defined in - Documentation/devicetree/bindings/media/video-interfaces.txt. The - first port should be the input endpoints, the second one the output - - -Display Engine Pipeline ------------------------ - -The display engine pipeline (and its entry point, since it can be -either directly the backend or the frontend) is represented as an -extra node. - -Required properties: - - compatible: value must be one of: - * allwinner,sun4i-a10-display-engine - * allwinner,sun5i-a10s-display-engine - * allwinner,sun5i-a13-display-engine - * allwinner,sun6i-a31-display-engine - * allwinner,sun6i-a31s-display-engine - * allwinner,sun7i-a20-display-engine - * allwinner,sun8i-a23-display-engine - * allwinner,sun8i-a33-display-engine - * allwinner,sun8i-a83t-display-engine - * allwinner,sun8i-h3-display-engine - * allwinner,sun8i-r40-display-engine - * allwinner,sun8i-v3s-display-engine - * allwinner,sun9i-a80-display-engine - * allwinner,sun50i-a64-display-engine - * allwinner,sun50i-h6-display-engine - - - allwinner,pipelines: list of phandle to the display engine - frontends (DE 1.0) or mixers (DE 2.0/3.0) available. - -Example: - -panel: panel { - compatible = "olimex,lcd-olinuxino-43-ts"; - #address-cells = <1>; - #size-cells = <0>; - - port { - #address-cells = <1>; - #size-cells = <0>; - - panel_input: endpoint { - remote-endpoint = <&tcon0_out_panel>; - }; - }; -}; - -connector { - compatible = "hdmi-connector"; - type = "a"; - - port { - hdmi_con_in: endpoint { - remote-endpoint = <&hdmi_out_con>; - }; - }; -}; - -hdmi: hdmi@1c16000 { - compatible = "allwinner,sun5i-a10s-hdmi"; - reg = <0x01c16000 0x1000>; - interrupts = <58>; - clocks = <&ccu CLK_AHB_HDMI>, <&ccu CLK_HDMI>, - <&ccu CLK_PLL_VIDEO0_2X>, - <&ccu CLK_PLL_VIDEO1_2X>; - clock-names = "ahb", "mod", "pll-0", "pll-1"; - dmas = <&dma SUN4I_DMA_NORMAL 16>, - <&dma SUN4I_DMA_NORMAL 16>, - <&dma SUN4I_DMA_DEDICATED 24>; - dma-names = "ddc-tx", "ddc-rx", "audio-tx"; - - ports { - #address-cells = <1>; - #size-cells = <0>; - - port@0 { - #address-cells = <1>; - #size-cells = <0>; - reg = <0>; - - hdmi_in_tcon0: endpoint { - remote-endpoint = <&tcon0_out_hdmi>; - }; - }; - - port@1 { - #address-cells = <1>; - #size-cells = <0>; - reg = <1>; - - hdmi_out_con: endpoint { - remote-endpoint = <&hdmi_con_in>; - }; - }; - }; -}; - -tve0: tv-encoder@1c0a000 { - compatible = "allwinner,sun4i-a10-tv-encoder"; - reg = <0x01c0a000 0x1000>; - clocks = <&ahb_gates 34>; - resets = <&tcon_ch0_clk 0>; - - port { - #address-cells = <1>; - #size-cells = <0>; - - tve0_in_tcon0: endpoint@0 { - reg = <0>; - remote-endpoint = <&tcon0_out_tve0>; - }; - }; -}; - -tcon0: lcd-controller@1c0c000 { - compatible = "allwinner,sun5i-a13-tcon"; - reg = <0x01c0c000 0x1000>; - interrupts = <44>; - resets = <&tcon_ch0_clk 1>; - reset-names = "lcd"; - clocks = <&ahb_gates 36>, - <&tcon_ch0_clk>, - <&tcon_ch1_clk>; - clock-names = "ahb", - "tcon-ch0", - "tcon-ch1"; - clock-output-names = "tcon-pixel-clock"; - - ports { - #address-cells = <1>; - #size-cells = <0>; - - tcon0_in: port@0 { - #address-cells = <1>; - #size-cells = <0>; - reg = <0>; - - tcon0_in_be0: endpoint@0 { - reg = <0>; - remote-endpoint = <&be0_out_tcon0>; - }; - }; - - tcon0_out: port@1 { - #address-cells = <1>; - #size-cells = <0>; - reg = <1>; - - tcon0_out_panel: endpoint@0 { - reg = <0>; - remote-endpoint = <&panel_input>; - }; - - tcon0_out_tve0: endpoint@1 { - reg = <1>; - remote-endpoint = <&tve0_in_tcon0>; - }; - }; - }; -}; - -fe0: display-frontend@1e00000 { - compatible = "allwinner,sun5i-a13-display-frontend"; - reg = <0x01e00000 0x20000>; - interrupts = <47>; - clocks = <&ahb_gates 46>, <&de_fe_clk>, - <&dram_gates 25>; - clock-names = "ahb", "mod", - "ram"; - resets = <&de_fe_clk>; - - ports { - #address-cells = <1>; - #size-cells = <0>; - - fe0_out: port@1 { - #address-cells = <1>; - #size-cells = <0>; - reg = <1>; - - fe0_out_be0: endpoint { - remote-endpoint = <&be0_in_fe0>; - }; - }; - }; -}; - -be0: display-backend@1e60000 { - compatible = "allwinner,sun5i-a13-display-backend"; - reg = <0x01e60000 0x10000>; - interrupts = <47>; - clocks = <&ahb_gates 44>, <&de_be_clk>, - <&dram_gates 26>; - clock-names = "ahb", "mod", - "ram"; - resets = <&de_be_clk>; - - ports { - #address-cells = <1>; - #size-cells = <0>; - - be0_in: port@0 { - #address-cells = <1>; - #size-cells = <0>; - reg = <0>; - - be0_in_fe0: endpoint@0 { - reg = <0>; - remote-endpoint = <&fe0_out_be0>; - }; - }; - - be0_out: port@1 { - #address-cells = <1>; - #size-cells = <0>; - reg = <1>; - - be0_out_tcon0: endpoint@0 { - reg = <0>; - remote-endpoint = <&tcon0_in_be0>; - }; - }; - }; -}; - -display-engine { - compatible = "allwinner,sun5i-a13-display-engine"; - allwinner,pipelines = <&fe0>; -}; diff --git a/Documentation/devicetree/bindings/display/tilcdc/tfp410.txt b/Documentation/devicetree/bindings/display/tilcdc/tfp410.txt deleted file mode 100644 index a58ae7756fc6..000000000000 --- a/Documentation/devicetree/bindings/display/tilcdc/tfp410.txt +++ /dev/null @@ -1,21 +0,0 @@ -Device-Tree bindings for tilcdc DRM TFP410 output driver - -Required properties: - - compatible: value should be "ti,tilcdc,tfp410". - - i2c: the phandle for the i2c device to use for DDC - -Recommended properties: - - pinctrl-names, pinctrl-0: the pincontrol settings to configure - muxing properly for pins that connect to TFP410 device - - powerdn-gpio: the powerdown GPIO, pulled low to power down the - TFP410 device (for DPMS_OFF) - -Example: - - dvicape { - compatible = "ti,tilcdc,tfp410"; - i2c = <&i2c2>; - pinctrl-names = "default"; - pinctrl-0 = <&bone_dvi_cape_dvi_00A1_pins>; - powerdn-gpio = <&gpio2 31 0>; - }; diff --git a/Documentation/devicetree/bindings/dma/atmel-xdma.txt b/Documentation/devicetree/bindings/dma/atmel-xdma.txt index 0eb2b3207e08..4dc398e1a371 100644 --- a/Documentation/devicetree/bindings/dma/atmel-xdma.txt +++ b/Documentation/devicetree/bindings/dma/atmel-xdma.txt @@ -2,9 +2,7 @@ * XDMA Controller Required properties: -- compatible: Should be "atmel,<chip>-dma". - <chip> compatible description: - - sama5d4: first SoC adding the XDMAC +- compatible: Should be "atmel,sama5d4-dma" or "microchip,sam9x60-dma". - reg: Should contain DMA registers location and length. - interrupts: Should contain DMA interrupt. - #dma-cells: Must be <1>, used to represent the number of integer cells in diff --git a/Documentation/devicetree/bindings/dma/fsl-edma.txt b/Documentation/devicetree/bindings/dma/fsl-edma.txt index 29dd3ccb1235..e77b08ebcd06 100644 --- a/Documentation/devicetree/bindings/dma/fsl-edma.txt +++ b/Documentation/devicetree/bindings/dma/fsl-edma.txt @@ -10,6 +10,7 @@ Required properties: - compatible : - "fsl,vf610-edma" for eDMA used similar to that on Vybrid vf610 SoC - "fsl,imx7ulp-edma" for eDMA2 used similar to that on i.mx7ulp + - "fsl,fsl,ls1028a-edma" for eDMA used similar to that on Vybrid vf610 SoC - reg : Specifies base physical address(s) and size of the eDMA registers. The 1st region is eDMA control register's address and size. The 2nd and the 3rd regions are programmable channel multiplexing diff --git a/Documentation/devicetree/bindings/dma/fsl-imx-sdma.txt b/Documentation/devicetree/bindings/dma/fsl-imx-sdma.txt index 9d8bbac27d8b..c9e97409e853 100644 --- a/Documentation/devicetree/bindings/dma/fsl-imx-sdma.txt +++ b/Documentation/devicetree/bindings/dma/fsl-imx-sdma.txt @@ -10,6 +10,9 @@ Required properties: "fsl,imx6q-sdma" "fsl,imx7d-sdma" "fsl,imx8mq-sdma" + "fsl,imx8mm-sdma" + "fsl,imx8mn-sdma" + "fsl,imx8mp-sdma" The -to variants should be preferred since they allow to determine the correct ROM script addresses needed for the driver to work without additional firmware. diff --git a/Documentation/devicetree/bindings/dma/jz4780-dma.txt b/Documentation/devicetree/bindings/dma/jz4780-dma.txt index ec89782d9498..3459e77be294 100644 --- a/Documentation/devicetree/bindings/dma/jz4780-dma.txt +++ b/Documentation/devicetree/bindings/dma/jz4780-dma.txt @@ -1,4 +1,4 @@ -* Ingenic JZ4780 DMA Controller +* Ingenic XBurst DMA Controller Required properties: @@ -8,10 +8,12 @@ Required properties: * ingenic,jz4770-dma * ingenic,jz4780-dma * ingenic,x1000-dma + * ingenic,x1830-dma - reg: Should contain the DMA channel registers location and length, followed by the DMA controller registers location and length. - interrupts: Should contain the interrupt specifier of the DMA controller. -- clocks: Should contain a clock specifier for the JZ4780/X1000 PDMA clock. +- clocks: Should contain a clock specifier for the JZ4780/X1000/X1830 PDMA + clock. - #dma-cells: Must be <2>. Number of integer cells in the dmas property of DMA clients (see below). diff --git a/Documentation/devicetree/bindings/dma/renesas,rcar-dmac.txt b/Documentation/devicetree/bindings/dma/renesas,rcar-dmac.txt index 5551e929fd99..b7f81c63be8b 100644 --- a/Documentation/devicetree/bindings/dma/renesas,rcar-dmac.txt +++ b/Documentation/devicetree/bindings/dma/renesas,rcar-dmac.txt @@ -30,6 +30,7 @@ Required Properties: - "renesas,dmac-r8a7794" (R-Car E2) - "renesas,dmac-r8a7795" (R-Car H3) - "renesas,dmac-r8a7796" (R-Car M3-W) + - "renesas,dmac-r8a77961" (R-Car M3-W+) - "renesas,dmac-r8a77965" (R-Car M3-N) - "renesas,dmac-r8a77970" (R-Car V3M) - "renesas,dmac-r8a77980" (R-Car V3H) diff --git a/Documentation/devicetree/bindings/dma/st,stm32-dma.yaml b/Documentation/devicetree/bindings/dma/st,stm32-dma.yaml new file mode 100644 index 000000000000..0c0ac11ad55f --- /dev/null +++ b/Documentation/devicetree/bindings/dma/st,stm32-dma.yaml @@ -0,0 +1,102 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/dma/st,stm32-dma.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: STMicroelectronics STM32 DMA Controller bindings + +description: | + The STM32 DMA is a general-purpose direct memory access controller capable of + supporting 8 independent DMA channels. Each channel can have up to 8 requests. + DMA clients connected to the STM32 DMA controller must use the format + described in the dma.txt file, using a four-cell specifier for each + channel: a phandle to the DMA controller plus the following four integer cells: + 1. The channel id + 2. The request line number + 3. A 32bit mask specifying the DMA channel configuration which are device + dependent: + -bit 9: Peripheral Increment Address + 0x0: no address increment between transfers + 0x1: increment address between transfers + -bit 10: Memory Increment Address + 0x0: no address increment between transfers + 0x1: increment address between transfers + -bit 15: Peripheral Increment Offset Size + 0x0: offset size is linked to the peripheral bus width + 0x1: offset size is fixed to 4 (32-bit alignment) + -bit 16-17: Priority level + 0x0: low + 0x1: medium + 0x2: high + 0x3: very high + 4. A 32bit bitfield value specifying DMA features which are device dependent: + -bit 0-1: DMA FIFO threshold selection + 0x0: 1/4 full FIFO + 0x1: 1/2 full FIFO + 0x2: 3/4 full FIFO + 0x3: full FIFO + +maintainers: + - Amelie Delaunay <amelie.delaunay@st.com> + +allOf: + - $ref: "dma-controller.yaml#" + +properties: + "#dma-cells": + const: 4 + + compatible: + const: st,stm32-dma + + reg: + maxItems: 1 + + clocks: + maxItems: 1 + + interrupts: + maxItems: 8 + description: Should contain all of the per-channel DMA + interrupts in ascending order with respect to the + DMA channel index. + + resets: + maxItems: 1 + + st,mem2mem: + $ref: /schemas/types.yaml#/definitions/flag + description: if defined, it indicates that the controller + supports memory-to-memory transfer + +required: + - compatible + - reg + - clocks + - interrupts + +examples: + - | + #include <dt-bindings/interrupt-controller/arm-gic.h> + #include <dt-bindings/clock/stm32mp1-clks.h> + #include <dt-bindings/reset/stm32mp1-resets.h> + dma-controller@40026400 { + compatible = "st,stm32-dma"; + reg = <0x40026400 0x400>; + interrupts = <56>, + <57>, + <58>, + <59>, + <60>, + <68>, + <69>, + <70>; + clocks = <&clk_hclk>; + #dma-cells = <4>; + st,mem2mem; + resets = <&rcc 150>; + dma-requests = <8>; + }; + +... diff --git a/Documentation/devicetree/bindings/dma/st,stm32-dmamux.yaml b/Documentation/devicetree/bindings/dma/st,stm32-dmamux.yaml new file mode 100644 index 000000000000..915bc4af9568 --- /dev/null +++ b/Documentation/devicetree/bindings/dma/st,stm32-dmamux.yaml @@ -0,0 +1,52 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/dma/st,stm32-dmamux.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: STMicroelectronics STM32 DMA MUX (DMA request router) bindings + +maintainers: + - Amelie Delaunay <amelie.delaunay@st.com> + +allOf: + - $ref: "dma-router.yaml#" + +properties: + "#dma-cells": + const: 3 + + compatible: + const: st,stm32h7-dmamux + + reg: + maxItems: 1 + + clocks: + maxItems: 1 + + resets: + maxItems: 1 + +required: + - compatible + - reg + - dma-masters + +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/st,stm32-mdma.yaml new file mode 100644 index 000000000000..c66543d0c267 --- /dev/null +++ b/Documentation/devicetree/bindings/dma/st,stm32-mdma.yaml @@ -0,0 +1,105 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/dma/st,stm32-mdma.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: STMicroelectronics STM32 MDMA Controller bindings + +description: | + The STM32 MDMA is a general-purpose direct memory access controller capable of + supporting 64 independent DMA channels with 256 HW requests. + DMA clients connected to the STM32 MDMA controller must use the format + described in the dma.txt file, using a five-cell specifier for each channel: + a phandle to the MDMA controller plus the following five integer cells: + 1. The request line number + 2. The priority level + 0x0: Low + 0x1: Medium + 0x2: High + 0x3: Very high + 3. A 32bit mask specifying the DMA channel configuration + -bit 0-1: Source increment mode + 0x0: Source address pointer is fixed + 0x2: Source address pointer is incremented after each data transfer + 0x3: Source address pointer is decremented after each data transfer + -bit 2-3: Destination increment mode + 0x0: Destination address pointer is fixed + 0x2: Destination address pointer is incremented after each data transfer + 0x3: Destination address pointer is decremented after each data transfer + -bit 8-9: Source increment offset size + 0x0: byte (8bit) + 0x1: half-word (16bit) + 0x2: word (32bit) + 0x3: double-word (64bit) + -bit 10-11: Destination increment offset size + 0x0: byte (8bit) + 0x1: half-word (16bit) + 0x2: word (32bit) + 0x3: double-word (64bit) + -bit 25-18: The number of bytes to be transferred in a single transfer + (min = 1 byte, max = 128 bytes) + -bit 29:28: Trigger Mode + 0x00: Each MDMA request triggers a buffer transfer (max 128 bytes) + 0x1: Each MDMA request triggers a block transfer (max 64K bytes) + 0x2: Each MDMA request triggers a repeated block transfer + 0x3: Each MDMA request triggers a linked list transfer + 4. A 32bit value specifying the register to be used to acknowledge the request + if no HW ack signal is used by the MDMA client + 5. A 32bit mask specifying the value to be written to acknowledge the request + if no HW ack signal is used by the MDMA client + +maintainers: + - Amelie Delaunay <amelie.delaunay@st.com> + +allOf: + - $ref: "dma-controller.yaml#" + +properties: + "#dma-cells": + const: 5 + + compatible: + const: st,stm32h7-mdma + + reg: + maxItems: 1 + + clocks: + maxItems: 1 + + interrupts: + maxItems: 1 + + resets: + maxItems: 1 + + st,ahb-addr-masks: + $ref: /schemas/types.yaml#/definitions/uint32-array + description: Array of u32 mask to list memory devices addressed via AHB bus. + +required: + - compatible + - reg + - clocks + - interrupts + +examples: + - | + #include <dt-bindings/interrupt-controller/arm-gic.h> + #include <dt-bindings/clock/stm32mp1-clks.h> + #include <dt-bindings/reset/stm32mp1-resets.h> + dma-controller@52000000 { + compatible = "st,stm32h7-mdma"; + reg = <0x52000000 0x1000>; + interrupts = <122>; + clocks = <&timer_clk>; + resets = <&rcc 992>; + #dma-cells = <5>; + dma-channels = <16>; + dma-requests = <32>; + st,ahb-addr-masks = <0x20000000>, <0x00000000>; + }; + +... + diff --git a/Documentation/devicetree/bindings/dma/stm32-dma.txt b/Documentation/devicetree/bindings/dma/stm32-dma.txt deleted file mode 100644 index c5f519097204..000000000000 --- a/Documentation/devicetree/bindings/dma/stm32-dma.txt +++ /dev/null @@ -1,83 +0,0 @@ -* STMicroelectronics STM32 DMA controller - -The STM32 DMA is a general-purpose direct memory access controller capable of -supporting 8 independent DMA channels. Each channel can have up to 8 requests. - -Required properties: -- compatible: Should be "st,stm32-dma" -- reg: Should contain DMA registers location and length. This should include - all of the per-channel registers. -- interrupts: Should contain all of the per-channel DMA interrupts in - ascending order with respect to the DMA channel index. -- clocks: Should contain the input clock of the DMA instance. -- #dma-cells : Must be <4>. See DMA client paragraph for more details. - -Optional properties: -- dma-requests : Number of DMA requests supported. -- resets: Reference to a reset controller asserting the DMA controller -- st,mem2mem: boolean; if defined, it indicates that the controller supports - memory-to-memory transfer - -Example: - - dma2: dma-controller@40026400 { - compatible = "st,stm32-dma"; - reg = <0x40026400 0x400>; - interrupts = <56>, - <57>, - <58>, - <59>, - <60>, - <68>, - <69>, - <70>; - clocks = <&clk_hclk>; - #dma-cells = <4>; - st,mem2mem; - resets = <&rcc 150>; - dma-requests = <8>; - }; - -* DMA client - -DMA clients connected to the STM32 DMA controller must use the format -described in the dma.txt file, using a four-cell specifier for each -channel: a phandle to the DMA controller plus the following four integer cells: - -1. The channel id -2. The request line number -3. A 32bit mask specifying the DMA channel configuration which are device - dependent: - -bit 9: Peripheral Increment Address - 0x0: no address increment between transfers - 0x1: increment address between transfers - -bit 10: Memory Increment Address - 0x0: no address increment between transfers - 0x1: increment address between transfers - -bit 15: Peripheral Increment Offset Size - 0x0: offset size is linked to the peripheral bus width - 0x1: offset size is fixed to 4 (32-bit alignment) - -bit 16-17: Priority level - 0x0: low - 0x1: medium - 0x2: high - 0x3: very high -4. A 32bit bitfield value specifying DMA features which are device dependent: - -bit 0-1: DMA FIFO threshold selection - 0x0: 1/4 full FIFO - 0x1: 1/2 full FIFO - 0x2: 3/4 full FIFO - 0x3: full FIFO - - -Example: - - usart1: serial@40011000 { - compatible = "st,stm32-uart"; - reg = <0x40011000 0x400>; - interrupts = <37>; - clocks = <&clk_pclk2>; - dmas = <&dma2 2 4 0x10400 0x3>, - <&dma2 7 5 0x10200 0x3>; - dma-names = "rx", "tx"; - }; diff --git a/Documentation/devicetree/bindings/dma/stm32-dmamux.txt b/Documentation/devicetree/bindings/dma/stm32-dmamux.txt deleted file mode 100644 index 1b893b235507..000000000000 --- a/Documentation/devicetree/bindings/dma/stm32-dmamux.txt +++ /dev/null @@ -1,84 +0,0 @@ -STM32 DMA MUX (DMA request router) - -Required properties: -- compatible: "st,stm32h7-dmamux" -- reg: Memory map for accessing module -- #dma-cells: Should be set to <3>. - First parameter is request line number. - Second is DMA channel configuration - Third is Fifo threshold - For more details about the three cells, please see - stm32-dma.txt documentation binding file -- dma-masters: Phandle pointing to the DMA controllers. - Several controllers are allowed. Only "st,stm32-dma" DMA - compatible are supported. - -Optional properties: -- dma-channels : Number of DMA requests supported. -- dma-requests : Number of DMAMUX requests supported. -- resets: Reference to a reset controller asserting the DMA controller -- clocks: Input clock of the DMAMUX instance. - -Example: - -/* DMA controller 1 */ -dma1: dma-controller@40020000 { - compatible = "st,stm32-dma"; - reg = <0x40020000 0x400>; - interrupts = <11>, - <12>, - <13>, - <14>, - <15>, - <16>, - <17>, - <47>; - clocks = <&timer_clk>; - #dma-cells = <4>; - st,mem2mem; - resets = <&rcc 150>; - dma-channels = <8>; - dma-requests = <8>; -}; - -/* DMA controller 1 */ -dma2: dma@40020400 { - compatible = "st,stm32-dma"; - reg = <0x40020400 0x400>; - interrupts = <56>, - <57>, - <58>, - <59>, - <60>, - <68>, - <69>, - <70>; - clocks = <&timer_clk>; - #dma-cells = <4>; - st,mem2mem; - resets = <&rcc 150>; - dma-channels = <8>; - dma-requests = <8>; -}; - -/* DMA mux */ -dmamux1: 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>; -}; - -/* DMA client */ -usart1: serial@40011000 { - compatible = "st,stm32-usart", "st,stm32-uart"; - reg = <0x40011000 0x400>; - interrupts = <37>; - clocks = <&timer_clk>; - dmas = <&dmamux1 41 0x414 0>, - <&dmamux1 42 0x414 0>; - dma-names = "rx", "tx"; -}; diff --git a/Documentation/devicetree/bindings/dma/stm32-mdma.txt b/Documentation/devicetree/bindings/dma/stm32-mdma.txt deleted file mode 100644 index d18772d6bc65..000000000000 --- a/Documentation/devicetree/bindings/dma/stm32-mdma.txt +++ /dev/null @@ -1,94 +0,0 @@ -* STMicroelectronics STM32 MDMA controller - -The STM32 MDMA is a general-purpose direct memory access controller capable of -supporting 64 independent DMA channels with 256 HW requests. - -Required properties: -- compatible: Should be "st,stm32h7-mdma" -- reg: Should contain MDMA registers location and length. This should include - all of the per-channel registers. -- interrupts: Should contain the MDMA interrupt. -- clocks: Should contain the input clock of the DMA instance. -- resets: Reference to a reset controller asserting the DMA controller. -- #dma-cells : Must be <5>. See DMA client paragraph for more details. - -Optional properties: -- dma-channels: Number of DMA channels supported by the controller. -- dma-requests: Number of DMA request signals supported by the controller. -- st,ahb-addr-masks: Array of u32 mask to list memory devices addressed via - AHB bus. - -Example: - - mdma1: dma@52000000 { - compatible = "st,stm32h7-mdma"; - reg = <0x52000000 0x1000>; - interrupts = <122>; - clocks = <&timer_clk>; - resets = <&rcc 992>; - #dma-cells = <5>; - dma-channels = <16>; - dma-requests = <32>; - st,ahb-addr-masks = <0x20000000>, <0x00000000>; - }; - -* DMA client - -DMA clients connected to the STM32 MDMA controller must use the format -described in the dma.txt file, using a five-cell specifier for each channel: -a phandle to the MDMA controller plus the following five integer cells: - -1. The request line number -2. The priority level - 0x00: Low - 0x01: Medium - 0x10: High - 0x11: Very high -3. A 32bit mask specifying the DMA channel configuration - -bit 0-1: Source increment mode - 0x00: Source address pointer is fixed - 0x10: Source address pointer is incremented after each data transfer - 0x11: Source address pointer is decremented after each data transfer - -bit 2-3: Destination increment mode - 0x00: Destination address pointer is fixed - 0x10: Destination address pointer is incremented after each data - transfer - 0x11: Destination address pointer is decremented after each data - transfer - -bit 8-9: Source increment offset size - 0x00: byte (8bit) - 0x01: half-word (16bit) - 0x10: word (32bit) - 0x11: double-word (64bit) - -bit 10-11: Destination increment offset size - 0x00: byte (8bit) - 0x01: half-word (16bit) - 0x10: word (32bit) - 0x11: double-word (64bit) --bit 25-18: The number of bytes to be transferred in a single transfer - (min = 1 byte, max = 128 bytes) --bit 29:28: Trigger Mode - 0x00: Each MDMA request triggers a buffer transfer (max 128 bytes) - 0x01: Each MDMA request triggers a block transfer (max 64K bytes) - 0x10: Each MDMA request triggers a repeated block transfer - 0x11: Each MDMA request triggers a linked list transfer -4. A 32bit value specifying the register to be used to acknowledge the request - if no HW ack signal is used by the MDMA client -5. A 32bit mask specifying the value to be written to acknowledge the request - if no HW ack signal is used by the MDMA client - -Example: - - i2c4: i2c@5c002000 { - compatible = "st,stm32f7-i2c"; - reg = <0x5c002000 0x400>; - interrupts = <95>, - <96>; - clocks = <&timer_clk>; - #address-cells = <1>; - #size-cells = <0>; - dmas = <&mdma1 36 0x0 0x40008 0x0 0x0>, - <&mdma1 37 0x0 0x40002 0x0 0x0>; - dma-names = "rx", "tx"; - status = "disabled"; - }; diff --git a/Documentation/devicetree/bindings/dma/ti/k3-udma.yaml b/Documentation/devicetree/bindings/dma/ti/k3-udma.yaml new file mode 100644 index 000000000000..8b5c346f23f6 --- /dev/null +++ b/Documentation/devicetree/bindings/dma/ti/k3-udma.yaml @@ -0,0 +1,184 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$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 + +maintainers: + - Peter Ujfalusi <peter.ujfalusi@ti.com> + +description: | + The UDMA-P is intended to perform similar (but significantly upgraded) + functions as the packet-oriented DMA used on previous SoC devices. The UDMA-P + module supports the transmission and reception of various packet types. + The UDMA-P architecture facilitates the segmentation and reassembly of SoC DMA + data structure compliant packets to/from smaller data blocks that are natively + compatible with the specific requirements of each connected peripheral. + Multiple Tx and Rx channels are provided within the DMA which allow multiple + segmentation or reassembly operations to be ongoing. The DMA controller + maintains state information for each of the channels which allows packet + segmentation and reassembly operations to be time division multiplexed between + channels in order to share the underlying DMA hardware. An external DMA + scheduler is used to control the ordering and rate at which this multiplexing + occurs for Transmit operations. The ordering and rate of Receive operations + is indirectly controlled by the order in which blocks are pushed into the DMA + on the Rx PSI-L interface. + + The UDMA-P also supports acting as both a UTC and UDMA-C for its internal + channels. Channels in the UDMA-P can be configured to be either Packet-Based + or Third-Party channels on a channel by channel basis. + + All transfers within NAVSS is done between PSI-L source and destination + threads. + The peripherals serviced by UDMA can be PSI-L native (sa2ul, cpsw, etc) or + legacy, non PSI-L native peripherals. In the later case a special, small PDMA + is tasked to act as a bridge between the PSI-L fabric and the legacy + peripheral. + + PDMAs can be configured via UDMAP peer registers to match with the + configuration of the legacy peripheral. + +allOf: + - $ref: "../dma-controller.yaml#" + +properties: + "#dma-cells": + const: 1 + description: | + The cell is the PSI-L thread ID of the remote (to UDMAP) end. + Valid ranges for thread ID depends on the data movement direction: + for source thread IDs (rx): 0 - 0x7fff + for destination thread IDs (tx): 0x8000 - 0xffff + + Please refer to the device documentation for the PSI-L thread map and also + the PSI-L peripheral chapter for the correct thread ID. + + compatible: + enum: + - ti,am654-navss-main-udmap + - ti,am654-navss-mcu-udmap + - ti,j721e-navss-main-udmap + - ti,j721e-navss-mcu-udmap + + reg: + maxItems: 3 + + reg-names: + items: + - const: gcfg + - const: rchanrt + - const: tchanrt + + msi-parent: true + + ti,sci: + description: phandle to TI-SCI compatible System controller node + allOf: + - $ref: /schemas/types.yaml#/definitions/phandle + + ti,sci-dev-id: + description: TI-SCI device id of UDMAP + allOf: + - $ref: /schemas/types.yaml#/definitions/uint32 + + ti,ringacc: + description: phandle to the ring accelerator node + allOf: + - $ref: /schemas/types.yaml#/definitions/phandle + + ti,sci-rm-range-tchan: + description: | + Array of UDMA tchan resource subtypes for resource allocation for this + host + allOf: + - $ref: /schemas/types.yaml#/definitions/uint32-array + minItems: 1 + # Should be enough + maxItems: 255 + + ti,sci-rm-range-rchan: + description: | + Array of UDMA rchan resource subtypes for resource allocation for this + host + allOf: + - $ref: /schemas/types.yaml#/definitions/uint32-array + minItems: 1 + # Should be enough + maxItems: 255 + + ti,sci-rm-range-rflow: + description: | + Array of UDMA rflow resource subtypes for resource allocation for this + host + allOf: + - $ref: /schemas/types.yaml#/definitions/uint32-array + minItems: 1 + # Should be enough + maxItems: 255 + +required: + - compatible + - "#dma-cells" + - reg + - reg-names + - msi-parent + - ti,sci + - ti,sci-dev-id + - ti,ringacc + - ti,sci-rm-range-tchan + - ti,sci-rm-range-rchan + - ti,sci-rm-range-rflow + +examples: + - |+ + cbass_main { + #address-cells = <2>; + #size-cells = <2>; + + cbass_main_navss: navss@30800000 { + compatible = "simple-mfd"; + #address-cells = <2>; + #size-cells = <2>; + dma-coherent; + dma-ranges; + ranges; + + ti,sci-dev-id = <118>; + + main_udmap: dma-controller@31150000 { + compatible = "ti,am654-navss-main-udmap"; + reg = <0x0 0x31150000 0x0 0x100>, + <0x0 0x34000000 0x0 0x100000>, + <0x0 0x35000000 0x0 0x100000>; + reg-names = "gcfg", "rchanrt", "tchanrt"; + #dma-cells = <1>; + + ti,ringacc = <&ringacc>; + + msi-parent = <&inta_main_udmass>; + + ti,sci = <&dmsc>; + ti,sci-dev-id = <188>; + + ti,sci-rm-range-tchan = <0x1>, /* TX_HCHAN */ + <0x2>; /* TX_CHAN */ + ti,sci-rm-range-rchan = <0x4>, /* RX_HCHAN */ + <0x5>; /* RX_CHAN */ + ti,sci-rm-range-rflow = <0x6>; /* GP RFLOW */ + }; + }; + + mcasp0: mcasp@02B00000 { + dmas = <&main_udmap 0xc400>, <&main_udmap 0x4400>; + dma-names = "tx", "rx"; + }; + + crypto: crypto@4E00000 { + compatible = "ti,sa2ul-crypto"; + + dmas = <&main_udmap 0xc000>, <&main_udmap 0x4000>, <&main_udmap 0x4001>; + dma-names = "tx", "rx1", "rx2"; + }; + }; diff --git a/Documentation/devicetree/bindings/eeprom/at24.yaml b/Documentation/devicetree/bindings/eeprom/at24.yaml index e8778560d966..0f6d8db18d6c 100644 --- a/Documentation/devicetree/bindings/eeprom/at24.yaml +++ b/Documentation/devicetree/bindings/eeprom/at24.yaml @@ -145,10 +145,7 @@ properties: over reads to the next slave address. Please consult the manual of your device. - wp-gpios: - description: - GPIO to which the write-protect pin of the chip is connected. - maxItems: 1 + wp-gpios: true address-width: allOf: @@ -167,6 +164,10 @@ properties: minimum: 1 maximum: 8 + vcc-supply: + description: + phandle of the regulator that provides the supply voltage. + required: - compatible - reg diff --git a/Documentation/devicetree/bindings/eeprom/at25.txt b/Documentation/devicetree/bindings/eeprom/at25.txt index 42577dd113dd..fcacd97abd0a 100644 --- a/Documentation/devicetree/bindings/eeprom/at25.txt +++ b/Documentation/devicetree/bindings/eeprom/at25.txt @@ -20,6 +20,7 @@ Optional properties: - spi-cpha : SPI shifted clock phase, as per spi-bus bindings. - spi-cpol : SPI inverse clock polarity, as per spi-bus bindings. - read-only : this parameter-less property disables writes to the eeprom +- wp-gpios : GPIO to which the write-protect pin of the chip is connected Obsolete legacy properties can be used in place of "size", "pagesize", "address-width", and "read-only": @@ -36,6 +37,7 @@ Example: spi-max-frequency = <5000000>; spi-cpha; spi-cpol; + wp-gpios = <&gpio1 3 0>; pagesize = <64>; size = <32768>; diff --git a/Documentation/devicetree/bindings/gpio/qcom,wcd934x-gpio.yaml b/Documentation/devicetree/bindings/gpio/qcom,wcd934x-gpio.yaml new file mode 100644 index 000000000000..32a566ec3558 --- /dev/null +++ b/Documentation/devicetree/bindings/gpio/qcom,wcd934x-gpio.yaml @@ -0,0 +1,47 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/gpio/qcom,wcd934x-gpio.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: WCD9340/WCD9341 GPIO controller + +maintainers: + - Srinivas Kandagatla <srinivas.kandagatla@linaro.org> + +description: | + Qualcomm Technologies Inc WCD9340/WCD9341 Audio Codec has integrated + gpio controller to control 5 gpios on the chip. + +properties: + compatible: + enum: + - qcom,wcd9340-gpio + - qcom,wcd9341-gpio + + reg: + maxItems: 1 + + gpio-controller: true + + '#gpio-cells': + const: 2 + +required: + - compatible + - reg + - gpio-controller + - "#gpio-cells" + +additionalProperties: false + +examples: + - | + wcdgpio: gpio@42 { + compatible = "qcom,wcd9340-gpio"; + reg = <0x042 0x2>; + gpio-controller; + #gpio-cells = <2>; + }; + +... diff --git a/Documentation/devicetree/bindings/gpio/renesas,gpio-rcar.txt b/Documentation/devicetree/bindings/gpio/renesas,gpio-rcar.txt index 41e5fed0f842..10dce84b1545 100644 --- a/Documentation/devicetree/bindings/gpio/renesas,gpio-rcar.txt +++ b/Documentation/devicetree/bindings/gpio/renesas,gpio-rcar.txt @@ -18,7 +18,8 @@ Required Properties: - "renesas,gpio-r8a7793": for R8A7793 (R-Car M2-N) compatible GPIO controller. - "renesas,gpio-r8a7794": for R8A7794 (R-Car E2) compatible GPIO controller. - "renesas,gpio-r8a7795": for R8A7795 (R-Car H3) compatible GPIO controller. - - "renesas,gpio-r8a7796": for R8A7796 (R-Car M3-W) compatible GPIO controller. + - "renesas,gpio-r8a7796": for R8A77960 (R-Car M3-W) compatible GPIO controller. + - "renesas,gpio-r8a77961": for R8A77961 (R-Car M3-W+) compatible GPIO controller. - "renesas,gpio-r8a77965": for R8A77965 (R-Car M3-N) compatible GPIO controller. - "renesas,gpio-r8a77970": for R8A77970 (R-Car V3M) compatible GPIO controller. - "renesas,gpio-r8a77980": for R8A77980 (R-Car V3H) compatible GPIO controller. diff --git a/Documentation/devicetree/bindings/gpio/sifive,gpio.yaml b/Documentation/devicetree/bindings/gpio/sifive,gpio.yaml new file mode 100644 index 000000000000..418e8381e07c --- /dev/null +++ b/Documentation/devicetree/bindings/gpio/sifive,gpio.yaml @@ -0,0 +1,68 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/gpio/sifive,gpio.yaml# +$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: + compatible: + items: + - const: sifive,fu540-c000-gpio + - const: sifive,gpio0 + + reg: + maxItems: 1 + + interrupts: + description: + interrupt mapping one per GPIO. Maximum 16 GPIOs. + minItems: 1 + maxItems: 16 + + interrupt-controller: true + + "#interrupt-cells": + const: 2 + + clocks: + maxItems: 1 + + "#gpio-cells": + const: 2 + + gpio-controller: true + +required: + - compatible + - reg + - interrupts + - interrupt-controller + - "#interrupt-cells" + - clocks + - "#gpio-cells" + - gpio-controller + +additionalProperties: false + +examples: + - | + #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>; + reg = <0x0 0x10060000 0x0 0x1000>; + clocks = <&tlclk PRCI_CLK_TLCLK>; + gpio-controller; + #gpio-cells = <2>; + interrupt-controller; + #interrupt-cells = <2>; + }; + +... diff --git a/Documentation/devicetree/bindings/gpio/xylon,logicvc-gpio.yaml b/Documentation/devicetree/bindings/gpio/xylon,logicvc-gpio.yaml new file mode 100644 index 000000000000..d102888c1be7 --- /dev/null +++ b/Documentation/devicetree/bindings/gpio/xylon,logicvc-gpio.yaml @@ -0,0 +1,69 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +# Copyright 2019 Bootlin +%YAML 1.2 +--- +$id: "http://devicetree.org/schemas/gpio/xylon,logicvc-gpio.yaml#" +$schema: "http://devicetree.org/meta-schemas/core.yaml#" + +title: Xylon LogiCVC GPIO controller + +maintainers: + - Paul Kocialkowski <paul.kocialkowski@bootlin.com> + +description: | + The LogiCVC GPIO describes the GPIO block included in the LogiCVC display + controller. These are meant to be used for controlling display-related + signals. + + The controller exposes GPIOs from the display and power control registers, + which are mapped by the driver as follows: + - GPIO[4:0] (display control) mapped to index 0-4 + - EN_BLIGHT (power control) mapped to index 5 + - EN_VDD (power control) mapped to index 6 + - EN_VEE (power control) mapped to index 7 + - V_EN (power control) mapped to index 8 + +properties: + $nodename: + pattern: "^gpio@[0-9a-f]+$" + + compatible: + enum: + - xylon,logicvc-3.02.a-gpio + + reg: + maxItems: 1 + + "#gpio-cells": + const: 2 + + gpio-controller: true + + gpio-line-names: + minItems: 1 + maxItems: 9 + +required: + - compatible + - reg + - "#gpio-cells" + - gpio-controller + +examples: + - | + logicvc: logicvc@43c00000 { + compatible = "xylon,logicvc-3.02.a", "syscon", "simple-mfd"; + reg = <0x43c00000 0x6000>; + + #address-cells = <1>; + #size-cells = <1>; + + logicvc_gpio: gpio@40 { + compatible = "xylon,logicvc-3.02.a-gpio"; + reg = <0x40 0x40>; + gpio-controller; + #gpio-cells = <2>; + gpio-line-names = "GPIO0", "GPIO1", "GPIO2", "GPIO3", "GPIO4", + "EN_BLIGHT", "EN_VDD", "EN_VEE", "V_EN"; + }; + }; diff --git a/Documentation/devicetree/bindings/gpu/arm,mali-bifrost.yaml b/Documentation/devicetree/bindings/gpu/arm,mali-bifrost.yaml index 0c426e371e71..4ea6a8789699 100644 --- a/Documentation/devicetree/bindings/gpu/arm,mali-bifrost.yaml +++ b/Documentation/devicetree/bindings/gpu/arm,mali-bifrost.yaml @@ -18,6 +18,7 @@ properties: - enum: - amlogic,meson-g12a-mali - realtek,rtd1619-mali + - rockchip,px30-mali - const: arm,mali-bifrost # Mali Bifrost GPU model/revision is fully discoverable reg: diff --git a/Documentation/devicetree/bindings/hwmon/adi,adm1177.yaml b/Documentation/devicetree/bindings/hwmon/adi,adm1177.yaml new file mode 100644 index 000000000000..2a9822075b36 --- /dev/null +++ b/Documentation/devicetree/bindings/hwmon/adi,adm1177.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/adi,adm1177.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +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 + https://www.analog.com/media/en/technical-documentation/data-sheets/ADM1177.pdf + +properties: + compatible: + enum: + - adi,adm1177 + + reg: + maxItems: 1 + + avcc-supply: + description: + Phandle to the Avcc power supply + + shunt-resistor-micro-ohms: + description: + The value of curent sense resistor in microohms. If not provided, + the current reading and overcurrent alert is disabled. + + adi,shutdown-threshold-microamp: + description: + Specifies the current level at which an over current alert occurs. + If not provided, the overcurrent alert is configured to max ADC range + based on shunt-resistor-micro-ohms. + + adi,vrange-high-enable: + description: + Specifies which internal voltage divider to be used. A 1 selects + a 7:2 voltage divider while a 0 selects a 14:1 voltage divider. + type: boolean + +required: + - compatible + - reg + +examples: + - | + #include <dt-bindings/gpio/gpio.h> + #include <dt-bindings/interrupt-controller/irq.h> + i2c0 { + #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; + }; + }; +... diff --git a/Documentation/devicetree/bindings/hwmon/adi,ltc2947.yaml b/Documentation/devicetree/bindings/hwmon/adi,ltc2947.yaml index ae04903f34bf..6a742a51e2f9 100644 --- a/Documentation/devicetree/bindings/hwmon/adi,ltc2947.yaml +++ b/Documentation/devicetree/bindings/hwmon/adi,ltc2947.yaml @@ -1,7 +1,7 @@ # SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) %YAML 1.2 --- -$id: http://devicetree.org/schemas/bindings/hwmon/adi,ltc2947.yaml# +$id: http://devicetree.org/schemas/hwmon/adi,ltc2947.yaml# $schema: http://devicetree.org/meta-schemas/core.yaml# title: Analog Devices LTC2947 high precision power and energy monitor diff --git a/Documentation/devicetree/bindings/hwmon/pmbus/ti,ucd90320.yaml b/Documentation/devicetree/bindings/hwmon/pmbus/ti,ucd90320.yaml new file mode 100644 index 000000000000..5d42e1304202 --- /dev/null +++ b/Documentation/devicetree/bindings/hwmon/pmbus/ti,ucd90320.yaml @@ -0,0 +1,45 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- + +$id: http://devicetree.org/schemas/hwmon/pmbus/ti,ucd90320.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: UCD90320 power sequencer + +maintainers: + - Jim Wright <wrightj@linux.vnet.ibm.com> + +description: | + The UCD90320 is a 32-rail PMBus/I2C addressable power-supply sequencer and + monitor. The 24 integrated ADC channels (AMONx) monitor the power supply + voltage, current, and temperature. Of the 84 GPIO pins, 8 can be used as + digital monitors (DMONx), 32 to enable the power supply (ENx), 24 for + margining (MARx), 16 for logical GPO, and 32 GPIs for cascading, and system + function. + + http://focus.ti.com/lit/ds/symlink/ucd90320.pdf + +properties: + compatible: + enum: + - ti,ucd90320 + + reg: + maxItems: 1 + +required: + - compatible + - reg + +examples: + - | + i2c { + #address-cells = <1>; + #size-cells = <0>; + + ucd90320@11 { + compatible = "ti,ucd90320"; + reg = <0x11>; + }; + }; diff --git a/Documentation/devicetree/bindings/i2c/i2c-at91.txt b/Documentation/devicetree/bindings/i2c/i2c-at91.txt index 8347b1e7c080..d4bad86107b8 100644 --- a/Documentation/devicetree/bindings/i2c/i2c-at91.txt +++ b/Documentation/devicetree/bindings/i2c/i2c-at91.txt @@ -1,10 +1,16 @@ I2C for Atmel platforms Required properties : -- compatible : Must be "atmel,at91rm9200-i2c", "atmel,at91sam9261-i2c", - "atmel,at91sam9260-i2c", "atmel,at91sam9g20-i2c", "atmel,at91sam9g10-i2c", - "atmel,at91sam9x5-i2c", "atmel,sama5d4-i2c", "atmel,sama5d2-i2c" or - "microchip,sam9x60-i2c" +- 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. diff --git a/Documentation/devicetree/bindings/i2c/i2c-imx-lpi2c.txt b/Documentation/devicetree/bindings/i2c/i2c-imx-lpi2c.txt index b245363d6d60..f0c072ff9eca 100644 --- a/Documentation/devicetree/bindings/i2c/i2c-imx-lpi2c.txt +++ b/Documentation/devicetree/bindings/i2c/i2c-imx-lpi2c.txt @@ -4,6 +4,7 @@ Required properties: - compatible : - "fsl,imx7ulp-lpi2c" for LPI2C compatible with the one integrated on i.MX7ULP soc - "fsl,imx8qxp-lpi2c" for LPI2C compatible with the one integrated on i.MX8QXP soc + - "fsl,imx8qm-lpi2c" for LPI2C compatible with the one integrated on i.MX8QM soc - reg : address and length of the lpi2c master registers - interrupts : lpi2c interrupt - clocks : lpi2c clock specifier diff --git a/Documentation/devicetree/bindings/i2c/i2c-jz4780.txt b/Documentation/devicetree/bindings/i2c/i2c-jz4780.txt index 3738cfbf863f..d229eff5ca1b 100644 --- a/Documentation/devicetree/bindings/i2c/i2c-jz4780.txt +++ b/Documentation/devicetree/bindings/i2c/i2c-jz4780.txt @@ -1,7 +1,9 @@ * Ingenic JZ4780 I2C Bus controller Required properties: -- compatible: should be "ingenic,jz4780-i2c" +- compatible: should be one of the following: + - "ingenic,jz4780-i2c" for the JZ4780 + - "ingenic,x1000-i2c" for the X1000 - reg: Should contain the address & size of the I2C controller registers. - interrupts: Should specify the interrupt provided by parent. - clocks: Should contain a single clock specifier for the JZ4780 I2C clock. diff --git a/Documentation/devicetree/bindings/i2c/i2c-mux-pca954x.txt b/Documentation/devicetree/bindings/i2c/i2c-mux-pca954x.txt index 30ac6a60f041..7abda506b828 100644 --- a/Documentation/devicetree/bindings/i2c/i2c-mux-pca954x.txt +++ b/Documentation/devicetree/bindings/i2c/i2c-mux-pca954x.txt @@ -25,6 +25,8 @@ Required Properties: Optional Properties: - reset-gpios: Reference to the GPIO connected to the reset input. + - idle-state: if present, overrides i2c-mux-idle-disconnect, + Please refer to Documentation/devicetree/bindings/mux/mux-controller.txt - i2c-mux-idle-disconnect: Boolean; if defined, forces mux to disconnect all children in idle state. This is necessary for example, if there are several multiplexers on the bus and the devices behind them use same I2C addresses. diff --git a/Documentation/devicetree/bindings/i2c/renesas,i2c.txt b/Documentation/devicetree/bindings/i2c/renesas,i2c.txt index 0660a3eb2547..c359965d0724 100644 --- a/Documentation/devicetree/bindings/i2c/renesas,i2c.txt +++ b/Documentation/devicetree/bindings/i2c/renesas,i2c.txt @@ -17,7 +17,8 @@ Required properties: "renesas,i2c-r8a7793" if the device is a part of a R8A7793 SoC. "renesas,i2c-r8a7794" if the device is a part of a R8A7794 SoC. "renesas,i2c-r8a7795" if the device is a part of a R8A7795 SoC. - "renesas,i2c-r8a7796" if the device is a part of a R8A7796 SoC. + "renesas,i2c-r8a7796" if the device is a part of a R8A77960 SoC. + "renesas,i2c-r8a77961" if the device is a part of a R8A77961 SoC. "renesas,i2c-r8a77965" if the device is a part of a R8A77965 SoC. "renesas,i2c-r8a77970" if the device is a part of a R8A77970 SoC. "renesas,i2c-r8a77980" if the device is a part of a R8A77980 SoC. diff --git a/Documentation/devicetree/bindings/i2c/renesas,iic.txt b/Documentation/devicetree/bindings/i2c/renesas,iic.txt index 64d11ffb07c4..ffe085c9947e 100644 --- a/Documentation/devicetree/bindings/i2c/renesas,iic.txt +++ b/Documentation/devicetree/bindings/i2c/renesas,iic.txt @@ -17,6 +17,7 @@ Required properties: - "renesas,iic-r8a7794" (R-Car E2) - "renesas,iic-r8a7795" (R-Car H3) - "renesas,iic-r8a7796" (R-Car M3-W) + - "renesas,iic-r8a77961" (R-Car M3-W+) - "renesas,iic-r8a77965" (R-Car M3-N) - "renesas,iic-r8a77990" (R-Car E3) - "renesas,iic-sh73a0" (SH-Mobile AG5) diff --git a/Documentation/devicetree/bindings/iio/accel/adi,adis16240.yaml b/Documentation/devicetree/bindings/iio/accel/adi,adis16240.yaml new file mode 100644 index 000000000000..4147f02b5e3c --- /dev/null +++ b/Documentation/devicetree/bindings/iio/accel/adi,adis16240.yaml @@ -0,0 +1,49 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/iio/accel/adi,adis16240.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: ADIS16240 Programmable Impact Sensor and Recorder driver + +maintainers: + - Alexandru Ardelean <alexandru.ardelean@analog.com> + +description: | + ADIS16240 Programmable Impact Sensor and Recorder driver that supports + SPI interface. + https://www.analog.com/en/products/adis16240.html + +properties: + compatible: + enum: + - adi,adis16240 + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + +required: + - compatible + - reg + - interrupts + +examples: + - | + #include <dt-bindings/gpio/gpio.h> + #include <dt-bindings/interrupt-controller/irq.h> + spi0 { + #address-cells = <1>; + #size-cells = <0>; + + /* Example for a SPI device node */ + accelerometer@0 { + compatible = "adi,adis16240"; + reg = <0>; + spi-max-frequency = <2500000>; + interrupt-parent = <&gpio0>; + interrupts = <0 IRQ_TYPE_LEVEL_HIGH>; + }; + }; diff --git a/Documentation/devicetree/bindings/iio/accel/bma180.txt b/Documentation/devicetree/bindings/iio/accel/bma180.txt index 3b25b4c4d446..f53237270b32 100644 --- a/Documentation/devicetree/bindings/iio/accel/bma180.txt +++ b/Documentation/devicetree/bindings/iio/accel/bma180.txt @@ -1,11 +1,14 @@ -* Bosch BMA180 / BMA250 triaxial acceleration sensor +* Bosch BMA180 / BMA25x triaxial acceleration sensor http://omapworld.com/BMA180_111_1002839.pdf http://ae-bst.resource.bosch.com/media/products/dokumente/bma250/bst-bma250-ds002-05.pdf Required properties: - - compatible : should be "bosch,bma180" or "bosch,bma250" + - compatible : should be one of: + "bosch,bma180" + "bosch,bma250" + "bosch,bma254" - reg : the I2C address of the sensor Optional properties: diff --git a/Documentation/devicetree/bindings/iio/accel/bosch,bma400.yaml b/Documentation/devicetree/bindings/iio/accel/bosch,bma400.yaml new file mode 100644 index 000000000000..c1c6d6f223cf --- /dev/null +++ b/Documentation/devicetree/bindings/iio/accel/bosch,bma400.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/accel/bosch,bma400.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Bosch BMA400 triaxial acceleration sensor + +maintainers: + - Dan Robertson <dan@dlrobertson.com> + +description: | + Acceleration and temperature iio sensors with an i2c interface + + Specifications about the sensor can be found at: + https://ae-bst.resource.bosch.com/media/_tech/media/datasheets/BST-BMA400-DS000.pdf + +properties: + compatible: + enum: + - bosch,bma400 + + reg: + maxItems: 1 + + vdd-supply: + description: phandle to the regulator that provides power to the accelerometer + + vddio-supply: + description: phandle to the regulator that provides power to the sensor's IO + + interrupts: + maxItems: 1 + +required: + - compatible + - reg + +examples: + - | + #include <dt-bindings/gpio/gpio.h> + #include <dt-bindings/interrupt-controller/irq.h> + i2c { + #address-cells = <1>; + #size-cells = <0>; + accelerometer@14 { + compatible = "bosch,bma400"; + reg = <0x14>; + vdd-supply = <&vdd>; + vddio-supply = <&vddio>; + interrupt-parent = <&gpio0>; + interrupts = <0 IRQ_TYPE_LEVEL_HIGH>; + }; + }; diff --git a/Documentation/devicetree/bindings/iio/accel/kionix,kxcjk1013.txt b/Documentation/devicetree/bindings/iio/accel/kionix,kxcjk1013.txt index eb76a02e2a82..ce950e162d5d 100644 --- a/Documentation/devicetree/bindings/iio/accel/kionix,kxcjk1013.txt +++ b/Documentation/devicetree/bindings/iio/accel/kionix,kxcjk1013.txt @@ -9,9 +9,16 @@ Required properties: "kionix,kxtf9" - reg: i2c slave address +Optional properties: + + - mount-matrix: an optional 3x3 mounting rotation matrix + Example: kxtf9@f { compatible = "kionix,kxtf9"; reg = <0x0F>; + mount-matrix = "0", "1", "0", + "1", "0", "0", + "0", "0", "1"; }; diff --git a/Documentation/devicetree/bindings/iio/adc/adi,ad7091r5.yaml b/Documentation/devicetree/bindings/iio/adc/adi,ad7091r5.yaml new file mode 100644 index 000000000000..31ffa275f5fa --- /dev/null +++ b/Documentation/devicetree/bindings/iio/adc/adi,ad7091r5.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/adc/adi,ad7091r5.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Analog Devices AD7091R5 4-Channel 12-Bit ADC + +maintainers: + - Beniamin Bia <beniamin.bia@analog.com> + +description: | + Analog Devices AD7091R5 4-Channel 12-Bit ADC + https://www.analog.com/media/en/technical-documentation/data-sheets/ad7091r-5.pdf + +properties: + compatible: + enum: + - adi,ad7091r5 + + reg: + maxItems: 1 + + vref-supply: + description: + Phandle to the vref power supply + + interrupts: + 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@2f { + compatible = "adi,ad7091r5"; + reg = <0x2f>; + + interrupts = <25 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 e932d5aed02f..f0934b295edc 100644 --- a/Documentation/devicetree/bindings/iio/adc/adi,ad7124.yaml +++ b/Documentation/devicetree/bindings/iio/adc/adi,ad7124.yaml @@ -2,7 +2,7 @@ # Copyright 2019 Analog Devices Inc. %YAML 1.2 --- -$id: http://devicetree.org/schemas/bindings/iio/adc/adi,ad7124.yaml# +$id: http://devicetree.org/schemas/iio/adc/adi,ad7124.yaml# $schema: http://devicetree.org/meta-schemas/core.yaml# title: Analog Devices AD7124 ADC device driver diff --git a/Documentation/devicetree/bindings/iio/adc/adi,ad7192.yaml b/Documentation/devicetree/bindings/iio/adc/adi,ad7192.yaml index 567a33a83dce..84d25bd39488 100644 --- a/Documentation/devicetree/bindings/iio/adc/adi,ad7192.yaml +++ b/Documentation/devicetree/bindings/iio/adc/adi,ad7192.yaml @@ -2,7 +2,7 @@ # Copyright 2019 Analog Devices Inc. %YAML 1.2 --- -$id: http://devicetree.org/schemas/bindings/iio/adc/adi,ad7192.yaml# +$id: http://devicetree.org/schemas/iio/adc/adi,ad7192.yaml# $schema: http://devicetree.org/meta-schemas/core.yaml# title: Analog Devices AD7192 ADC device driver diff --git a/Documentation/devicetree/bindings/iio/adc/adi,ad7606.yaml b/Documentation/devicetree/bindings/iio/adc/adi,ad7606.yaml index 6eb33207a167..5117ad68a584 100644 --- a/Documentation/devicetree/bindings/iio/adc/adi,ad7606.yaml +++ b/Documentation/devicetree/bindings/iio/adc/adi,ad7606.yaml @@ -82,7 +82,7 @@ properties: 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. - maxItems: 1 + maxItems: 3 adi,sw-mode: description: @@ -125,9 +125,9 @@ examples: 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>; + 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; }; diff --git a/Documentation/devicetree/bindings/iio/adc/at91-sama5d2_adc.txt b/Documentation/devicetree/bindings/iio/adc/at91-sama5d2_adc.txt index 4a3c1d496e1a..07c59f301b31 100644 --- a/Documentation/devicetree/bindings/iio/adc/at91-sama5d2_adc.txt +++ b/Documentation/devicetree/bindings/iio/adc/at91-sama5d2_adc.txt @@ -1,7 +1,7 @@ * AT91 SAMA5D2 Analog to Digital Converter (ADC) Required properties: - - compatible: Should be "atmel,sama5d2-adc". + - compatible: Should be "atmel,sama5d2-adc" or "microchip,sam9x60-adc". - reg: Should contain ADC registers location and length. - interrupts: Should contain the IRQ line for the ADC. - clocks: phandle to device clock. diff --git a/Documentation/devicetree/bindings/iio/adc/lltc,ltc2496.yaml b/Documentation/devicetree/bindings/iio/adc/lltc,ltc2496.yaml new file mode 100644 index 000000000000..59009997dca0 --- /dev/null +++ b/Documentation/devicetree/bindings/iio/adc/lltc,ltc2496.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/lltc,ltc2496.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +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: + enum: + - lltc,ltc2496 + + vref-supply: + description: phandle to an external regulator providing the reference voltage + allOf: + - $ref: /schemas/types.yaml#/definitions/phandle + + reg: + description: spi chipselect number according to the usual spi bindings + + spi-max-frequency: + description: maximal spi bus frequency supported + +required: + - compatible + - vref-supply + - reg + +examples: + - | + spi { + #address-cells = <1>; + #size-cells = <0>; + + adc@0 { + compatible = "lltc,ltc2496"; + reg = <0>; + vref-supply = <<c2496_reg>; + spi-max-frequency = <2000000>; + }; + }; diff --git a/Documentation/devicetree/bindings/iio/adc/microchip,mcp3911.yaml b/Documentation/devicetree/bindings/iio/adc/microchip,mcp3911.yaml index 881059b80d61..0ce290473fb0 100644 --- a/Documentation/devicetree/bindings/iio/adc/microchip,mcp3911.yaml +++ b/Documentation/devicetree/bindings/iio/adc/microchip,mcp3911.yaml @@ -2,7 +2,7 @@ # Copyright 2019 Marcus Folkesson <marcus.folkesson@gmail.com> %YAML 1.2 --- -$id: "http://devicetree.org/schemas/bindings/iio/adc/microchip,mcp3911.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) diff --git a/Documentation/devicetree/bindings/iio/adc/sigma-delta-modulator.txt b/Documentation/devicetree/bindings/iio/adc/sigma-delta-modulator.txt deleted file mode 100644 index 59b92cd32552..000000000000 --- a/Documentation/devicetree/bindings/iio/adc/sigma-delta-modulator.txt +++ /dev/null @@ -1,13 +0,0 @@ -Device-Tree bindings for sigma delta modulator - -Required properties: -- compatible: should be "ads1201", "sd-modulator". "sd-modulator" can be use - as a generic SD modulator if modulator not specified in compatible list. -- #io-channel-cells = <0>: See the IIO bindings section "IIO consumers". - -Example node: - - ads1202: adc { - compatible = "sd-modulator"; - #io-channel-cells = <0>; - }; diff --git a/Documentation/devicetree/bindings/iio/adc/sigma-delta-modulator.yaml b/Documentation/devicetree/bindings/iio/adc/sigma-delta-modulator.yaml new file mode 100644 index 000000000000..a390343d0c2a --- /dev/null +++ b/Documentation/devicetree/bindings/iio/adc/sigma-delta-modulator.yaml @@ -0,0 +1,37 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$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 + +maintainers: + - Arnaud Pouliquen <arnaud.pouliquen@st.com> + +properties: + compatible: + description: | + "sd-modulator" can be used as a generic SD modulator, + if the modulator is not specified in the compatible list. + enum: + - sd-modulator + - ads1201 + + '#io-channel-cells': + const: 0 + +required: + - compatible + - '#io-channel-cells' + +additionalProperties: false + +examples: + - | + ads1202: adc { + compatible = "sd-modulator"; + #io-channel-cells = <0>; + }; + +... diff --git a/Documentation/devicetree/bindings/iio/adc/st,stm32-dfsdm-adc.txt b/Documentation/devicetree/bindings/iio/adc/st,stm32-dfsdm-adc.txt deleted file mode 100644 index 75ba25d062e1..000000000000 --- a/Documentation/devicetree/bindings/iio/adc/st,stm32-dfsdm-adc.txt +++ /dev/null @@ -1,135 +0,0 @@ -STMicroelectronics STM32 DFSDM ADC device driver - - -STM32 DFSDM ADC is a sigma delta analog-to-digital converter dedicated to -interface external sigma delta modulators to STM32 micro controllers. -It is mainly targeted for: -- Sigma delta modulators (motor control, metering...) -- PDM microphones (audio digital microphone) - -It features up to 8 serial digital interfaces (SPI or Manchester) and -up to 4 filters on stm32h7 or 6 filters on stm32mp1. - -Each child node match with a filter instance. - -Contents of a STM32 DFSDM root node: ------------------------------------- -Required properties: -- compatible: Should be one of: - "st,stm32h7-dfsdm" - "st,stm32mp1-dfsdm" -- reg: Offset and length of the DFSDM block register set. -- clocks: IP and serial interfaces clocking. Should be set according - to rcc clock ID and "clock-names". -- clock-names: Input clock name "dfsdm" must be defined, - "audio" is optional. If defined CLKOUT is based on the audio - clock, else "dfsdm" is used. -- #interrupt-cells = <1>; -- #address-cells = <1>; -- #size-cells = <0>; - -Optional properties: -- spi-max-frequency: Requested only for SPI master mode. - SPI clock OUT frequency (Hz). This clock must be set according - to "clock" property. Frequency must be a multiple of the rcc - clock frequency. If not, SPI CLKOUT frequency will not be - accurate. -- pinctrl-names: Set to "default". -- pinctrl-0: List of phandles pointing to pin configuration - nodes to set pins in mode of operation for dfsdm - on external pin. - -Contents of a STM32 DFSDM child nodes: --------------------------------------- - -Required properties: -- compatible: Must be: - "st,stm32-dfsdm-adc" for sigma delta ADCs - "st,stm32-dfsdm-dmic" for audio digital microphone. -- reg: Specifies the DFSDM filter instance used. - Valid values are from 0 to 3 on stm32h7, 0 to 5 on stm32mp1. -- interrupts: IRQ lines connected to each DFSDM filter instance. -- st,adc-channels: List of single-ended channels muxed for this ADC. - valid values: - "st,stm32h7-dfsdm" compatibility: 0 to 7. -- st,adc-channel-names: List of single-ended channel names. -- st,filter-order: SinC filter order from 0 to 5. - 0: FastSinC - [1-5]: order 1 to 5. - For audio purpose it is recommended to use order 3 to 5. -- #io-channel-cells = <1>: See the IIO bindings section "IIO consumers". - -Required properties for "st,stm32-dfsdm-adc" compatibility: -- io-channels: From common IIO binding. Used to pipe external sigma delta - modulator or internal ADC output to DFSDM channel. - This is not required for "st,stm32-dfsdm-pdm" compatibility as - PDM microphone is binded in Audio DT node. - -Required properties for "st,stm32-dfsdm-pdm" compatibility: -- #sound-dai-cells: Must be set to 0. -- dma: DMA controller phandle and DMA request line associated to the - filter instance (specified by the field "reg") -- dma-names: Must be "rx" - -Optional properties: -- st,adc-channel-types: 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 -- st,adc-channel-clk-src: 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). - -- st,adc-alt-channel: Must be defined if two sigma delta modulator 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. - -- st,filter0-sync: Set to 1 to synchronize with DFSDM filter instance 0. - Used for multi microphones synchronization. - -Example of a sigma delta adc connected on DFSDM SPI port 0 -and a pdm microphone connected on DFSDM SPI port 1: - - ads1202: simple_sd_adc@0 { - compatible = "ads1202"; - #io-channel-cells = <1>; - }; - - dfsdm: dfsdm@40017000 { - compatible = "st,stm32h7-dfsdm"; - reg = <0x40017000 0x400>; - clocks = <&rcc DFSDM1_CK>; - clock-names = "dfsdm"; - #interrupt-cells = <1>; - #address-cells = <1>; - #size-cells = <0>; - - dfsdm_adc0: filter@0 { - compatible = "st,stm32-dfsdm-adc"; - #io-channel-cells = <1>; - reg = <0>; - interrupts = <110>; - st,adc-channels = <0>; - st,adc-channel-names = "sd_adc0"; - st,adc-channel-types = "SPI_F"; - st,adc-channel-clk-src = "CLKOUT"; - io-channels = <&ads1202 0>; - st,filter-order = <3>; - }; - dfsdm_pdm1: filter@1 { - compatible = "st,stm32-dfsdm-dmic"; - reg = <1>; - interrupts = <111>; - dmas = <&dmamux1 102 0x400 0x00>; - dma-names = "rx"; - st,adc-channels = <1>; - st,adc-channel-names = "dmic1"; - st,adc-channel-types = "SPI_R"; - st,adc-channel-clk-src = "CLKOUT"; - st,filter-order = <5>; - }; - } diff --git a/Documentation/devicetree/bindings/iio/adc/st,stm32-dfsdm-adc.yaml b/Documentation/devicetree/bindings/iio/adc/st,stm32-dfsdm-adc.yaml new file mode 100644 index 000000000000..acf36eef728b --- /dev/null +++ b/Documentation/devicetree/bindings/iio/adc/st,stm32-dfsdm-adc.yaml @@ -0,0 +1,332 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/iio/adc/st,stm32-dfsdm-adc.yaml# +$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> + +description: | + STM32 DFSDM ADC is a sigma delta analog-to-digital converter dedicated to + interface external sigma delta modulators to STM32 micro controllers. + It is mainly targeted for: + - Sigma delta modulators (motor control, metering...) + - PDM microphones (audio digital microphone) + + It features up to 8 serial digital interfaces (SPI or Manchester) and + up to 4 filters on stm32h7 or 6 filters on stm32mp1. + + Each child node matches with a filter instance. + +properties: + compatible: + enum: + - st,stm32h7-dfsdm + - st,stm32mp1-dfsdm + + reg: + maxItems: 1 + + clocks: + items: + - description: + Internal clock used for DFSDM digital processing and control blocks. + dfsdm clock can also feed CLKOUT, when CLKOUT is used. + - description: audio clock can be used as an alternate to feed CLKOUT. + minItems: 1 + maxItems: 2 + + clock-names: + items: + - const: dfsdm + - const: audio + minItems: 1 + maxItems: 2 + + "#address-cells": + const: 1 + + "#size-cells": + const: 0 + + spi-max-frequency: + description: + SPI clock OUT frequency (Hz). Requested only for SPI master mode. + This clock must be set according to the "clock" property. + Frequency must be a multiple of the rcc clock frequency. + If not, SPI CLKOUT frequency will not be accurate. + maximum: 20000000 + +required: + - compatible + - reg + - clocks + - clock-names + - "#address-cells" + - "#size-cells" + +patternProperties: + "^filter@[0-9]+$": + type: object + description: child node + + properties: + compatible: + enum: + - st,stm32-dfsdm-adc + - st,stm32-dfsdm-dmic + + reg: + description: Specifies the DFSDM filter instance used. + maxItems: 1 + + interrupts: + maxItems: 1 + + st,adc-channels: + description: | + List of single-ended channels muxed for this ADC. + On stm32h7 and stm32mp1: + - For st,stm32-dfsdm-adc: up to 8 channels numbered from 0 to 7. + - For st,stm32-dfsdm-dmic: 1 channel numbered from 0 to 7. + allOf: + - $ref: /schemas/types.yaml#/definitions/uint32-array + - items: + minimum: 0 + maximum: 7 + + st,adc-channel-names: + description: List of single-ended channel names. + allOf: + - $ref: /schemas/types.yaml#/definitions/string-array + + st,filter-order: + description: | + SinC filter order from 0 to 5. + - 0: FastSinC + - [1-5]: order 1 to 5. + For audio purpose it is recommended to use order 3 to 5. + allOf: + - $ref: /schemas/types.yaml#/definitions/uint32 + - items: + minimum: 0 + maximum: 5 + + "#io-channel-cells": + const: 1 + + st,adc-channel-types: + 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 + items: + enum: [ SPI_R, SPI_F, MANCH_R, MANCH_F ] + allOf: + - $ref: /schemas/types.yaml#/definitions/non-unique-string-array + + 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). + items: + enum: [ CLKIN, CLKOUT, CLKOUT_F, CLKOUT_R ] + allOf: + - $ref: /schemas/types.yaml#/definitions/non-unique-string-array + + 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 + + st,filter0-sync: + description: + Set to 1 to synchronize with DFSDM filter instance 0. + Used for multi microphones synchronization. + type: boolean + + dmas: + maxItems: 1 + + dma-names: + items: + - const: rx + + required: + - compatible + - reg + - interrupts + - st,adc-channels + - st,adc-channel-names + - st,filter-order + - "#io-channel-cells" + + allOf: + - if: + properties: + compatible: + contains: + const: st,stm32-dfsdm-adc + + - then: + properties: + st,adc-channels: + minItems: 1 + maxItems: 8 + + st,adc-channel-names: + minItems: 1 + maxItems: 8 + + st,adc-channel-types: + minItems: 1 + maxItems: 8 + + st,adc-channel-clk-src: + minItems: 1 + maxItems: 8 + + io-channels: + description: + From common IIO binding. Used to pipe external sigma delta + modulator or internal ADC output to DFSDM channel. + This is not required for "st,stm32-dfsdm-pdm" compatibility as + PDM microphone is binded in Audio DT node. + + required: + - io-channels + + - if: + properties: + compatible: + contains: + const: st,stm32-dfsdm-dmic + + - then: + properties: + st,adc-channels: + maxItems: 1 + + st,adc-channel-names: + maxItems: 1 + + st,adc-channel-types: + maxItems: 1 + + st,adc-channel-clk-src: + maxItems: 1 + + required: + - dmas + - dma-names + + patternProperties: + "^dfsdm-dai+$": + type: object + description: child node + + properties: + "#sound-dai-cells": + const: 0 + + io-channels: + description: + From common IIO binding. Used to pipe external sigma delta + modulator or internal ADC output to DFSDM channel. + + required: + - "#sound-dai-cells" + - io-channels + +allOf: + - if: + properties: + compatible: + contains: + const: st,stm32h7-dfsdm + + - then: + patternProperties: + "^filter@[0-9]+$": + properties: + reg: + items: + minimum: 0 + maximum: 3 + + - if: + properties: + compatible: + contains: + const: st,stm32mp1-dfsdm + + - then: + patternProperties: + "^filter@[0-9]+$": + properties: + reg: + items: + minimum: 0 + maximum: 5 + +examples: + - | + #include <dt-bindings/interrupt-controller/arm-gic.h> + #include <dt-bindings/clock/stm32mp1-clks.h> + dfsdm: dfsdm@4400d000 { + compatible = "st,stm32mp1-dfsdm"; + reg = <0x4400d000 0x800>; + clocks = <&rcc DFSDM_K>, <&rcc ADFSDM_K>; + clock-names = "dfsdm", "audio"; + #address-cells = <1>; + #size-cells = <0>; + + dfsdm0: filter@0 { + compatible = "st,stm32-dfsdm-dmic"; + reg = <0>; + interrupts = <GIC_SPI 110 IRQ_TYPE_LEVEL_HIGH>; + 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"; + st,filter-order = <5>; + + asoc_pdm0: dfsdm-dai { + compatible = "st,stm32h7-dfsdm-dai"; + #sound-dai-cells = <0>; + io-channels = <&dfsdm0 0>; + }; + }; + + dfsdm_pdm1: 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>; + }; + }; + +... diff --git a/Documentation/devicetree/bindings/iio/dac/lltc,ltc1660.yaml b/Documentation/devicetree/bindings/iio/dac/lltc,ltc1660.yaml index 13d005b68931..a285eaba7125 100644 --- a/Documentation/devicetree/bindings/iio/dac/lltc,ltc1660.yaml +++ b/Documentation/devicetree/bindings/iio/dac/lltc,ltc1660.yaml @@ -2,7 +2,7 @@ # Copyright 2019 Marcus Folkesson <marcus.folkesson@gmail.com> %YAML 1.2 --- -$id: "http://devicetree.org/schemas/bindings/iio/dac/lltc,ltc1660.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 diff --git a/Documentation/devicetree/bindings/iio/imu/adi,adis16480.txt b/Documentation/devicetree/bindings/iio/imu/adi,adis16480.txt index ed7783f45233..cd903a1d880d 100644 --- a/Documentation/devicetree/bindings/iio/imu/adi,adis16480.txt +++ b/Documentation/devicetree/bindings/iio/imu/adi,adis16480.txt @@ -8,6 +8,7 @@ Required properties for the ADIS16480: * "adi,adis16480" * "adi,adis16485" * "adi,adis16488" + * "adi,adis16490" * "adi,adis16495-1" * "adi,adis16495-2" * "adi,adis16495-3" diff --git a/Documentation/devicetree/bindings/iio/pressure/asc,dlhl60d.yaml b/Documentation/devicetree/bindings/iio/pressure/asc,dlhl60d.yaml new file mode 100644 index 000000000000..9f5ca9c42025 --- /dev/null +++ b/Documentation/devicetree/bindings/iio/pressure/asc,dlhl60d.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/pressure/asc,dlhl60d.yaml# +$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> + +description: | + Bindings for the All Sensors DLH series pressure sensors. + + Specifications about the sensors can be found at: + http://www.allsensors.com/cad/DS-0355_Rev_B.PDF + +properties: + compatible: + enum: + - asc,dlhl60d + - asc,dlhl60g + + reg: + description: I2C device address + maxItems: 1 + + interrupts: + description: interrupt mapping for EOC(data ready) pin + maxItems: 1 + +required: + - compatible + - reg + +examples: + - | + #include <dt-bindings/interrupt-controller/irq.h> + + i2c0 { + #address-cells = <1>; + #size-cells = <0>; + + pressure@29 { + compatible = "asc,dlhl60d"; + reg = <0x29>; + interrupt-parent = <&gpio0>; + interrupts = <10 IRQ_TYPE_EDGE_RISING>; + }; + }; +... diff --git a/Documentation/devicetree/bindings/iio/proximity/parallax-ping.yaml b/Documentation/devicetree/bindings/iio/proximity/parallax-ping.yaml new file mode 100644 index 000000000000..a079c9921af6 --- /dev/null +++ b/Documentation/devicetree/bindings/iio/proximity/parallax-ping.yaml @@ -0,0 +1,51 @@ +# SPDX-License-Identifier: (GPL-2.0-or-later OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/iio/proximity/parallax-ping.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Parallax PING))) and LaserPING range finder + +maintainers: + - Andreas Klinger <ak@it-klinger.de> + +description: | + Bit-banging driver using one GPIO: + - ping-gpios is raised by the driver to start measurement + - direction of ping-gpio is then switched into input with an interrupt + for receiving distance value as PWM signal + + Specifications about the devices can be found at: + http://parallax.com/sites/default/files/downloads/28041-LaserPING-2m-Rangefinder-Guide.pdf + http://parallax.com/sites/default/files/downloads/28015-PING-Documentation-v1.6.pdf + +properties: + compatible: + enum: + - parallax,ping + - parallax,laserping + + ping-gpios: + description: + Definition of the GPIO for the triggering and echo (output and input) + This GPIO is set for about 5 us by the driver to tell the device it + should initiate the measurement cycle. Afterwards the GPIO is switched + to input direction with an interrupt. The device sets it and the + length of the input signal corresponds to the measured distance. + It needs to be an GPIO which is able to deliver an interrupt because + the time between two interrupts is measured in the driver. + See Documentation/devicetree/bindings/gpio/gpio.txt for information + on how to specify a consumer gpio. + maxItems: 1 + +required: + - compatible + - ping-gpios + +examples: + - | + #include <dt-bindings/gpio/gpio.h> + proximity { + compatible = "parallax,laserping"; + ping-gpios = <&gpio0 26 GPIO_ACTIVE_HIGH>; + }; diff --git a/Documentation/devicetree/bindings/iio/temperature/maxim_thermocouple.txt b/Documentation/devicetree/bindings/iio/temperature/maxim_thermocouple.txt index 28bc5c4d965b..bb85cd0e039c 100644 --- a/Documentation/devicetree/bindings/iio/temperature/maxim_thermocouple.txt +++ b/Documentation/devicetree/bindings/iio/temperature/maxim_thermocouple.txt @@ -5,7 +5,10 @@ Maxim thermocouple support Required properties: - - compatible: must be "maxim,max31855" or "maxim,max6675" + - compatible: must be "maxim,max6675" or one of the following: + "maxim,max31855k", "maxim,max31855j", "maxim,max31855n", + "maxim,max31855s", "maxim,max31855t", "maxim,max31855e", + "maxim,max31855r"; the generic "max,max31855" is deprecated. - reg: SPI chip select number for the device - spi-max-frequency: must be 4300000 - spi-cpha: must be defined for max6675 to enable SPI mode 1 @@ -15,7 +18,7 @@ Required properties: Example: max31855@0 { - compatible = "maxim,max31855"; + compatible = "maxim,max31855k"; reg = <0>; spi-max-frequency = <4300000>; }; diff --git a/Documentation/devicetree/bindings/input/gpio-vibrator.yaml b/Documentation/devicetree/bindings/input/gpio-vibrator.yaml index 903475f52dbd..b98bf9363c8f 100644 --- a/Documentation/devicetree/bindings/input/gpio-vibrator.yaml +++ b/Documentation/devicetree/bindings/input/gpio-vibrator.yaml @@ -1,7 +1,7 @@ # SPDX-License-Identifier: GPL-2.0 %YAML 1.2 --- -$id: http://devicetree.org/schemas/bindings/input/gpio-vibrator.yaml# +$id: http://devicetree.org/schemas/input/gpio-vibrator.yaml# $schema: http://devicetree.org/meta-schemas/core.yaml# title: GPIO vibrator diff --git a/Documentation/devicetree/bindings/input/ilitek,ili2xxx.txt b/Documentation/devicetree/bindings/input/ilitek,ili2xxx.txt index dc194b2c151a..cdcaa3f52d25 100644 --- a/Documentation/devicetree/bindings/input/ilitek,ili2xxx.txt +++ b/Documentation/devicetree/bindings/input/ilitek,ili2xxx.txt @@ -1,9 +1,10 @@ -Ilitek ILI210x/ILI2117/ILI251x touchscreen controller +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 diff --git a/Documentation/devicetree/bindings/input/touchscreen/edt-ft5x06.txt b/Documentation/devicetree/bindings/input/touchscreen/edt-ft5x06.txt index 0f6950073d6f..0e57315e9cbd 100644 --- a/Documentation/devicetree/bindings/input/touchscreen/edt-ft5x06.txt +++ b/Documentation/devicetree/bindings/input/touchscreen/edt-ft5x06.txt @@ -36,6 +36,8 @@ Optional properties: - pinctrl-0: a phandle pointing to the pin settings for the control gpios + - wakeup-source: If present the device will act as wakeup-source + - threshold: allows setting the "click"-threshold in the range from 0 to 80. diff --git a/Documentation/devicetree/bindings/input/touchscreen/goodix.txt b/Documentation/devicetree/bindings/input/touchscreen/goodix.txt deleted file mode 100644 index fc03ea4cf5ab..000000000000 --- a/Documentation/devicetree/bindings/input/touchscreen/goodix.txt +++ /dev/null @@ -1,50 +0,0 @@ -Device tree bindings for Goodix GT9xx series touchscreen controller - -Required properties: - - - compatible : Should be "goodix,gt1151" - or "goodix,gt5663" - or "goodix,gt5688" - or "goodix,gt911" - or "goodix,gt9110" - or "goodix,gt912" - or "goodix,gt927" - or "goodix,gt9271" - or "goodix,gt928" - or "goodix,gt967" - - reg : I2C address of the chip. Should be 0x5d or 0x14 - - interrupts : Interrupt to which the chip is connected - -Optional properties: - - - irq-gpios : GPIO pin used for IRQ. The driver uses the - interrupt gpio pin as output to reset the device. - - reset-gpios : GPIO pin used for reset - - AVDD28-supply : Analog power supply regulator on AVDD28 pin - - VDDIO-supply : GPIO power supply regulator on VDDIO pin - - touchscreen-inverted-x - - touchscreen-inverted-y - - touchscreen-size-x - - touchscreen-size-y - - touchscreen-swapped-x-y - -The touchscreen-* properties are documented in touchscreen.txt in this -directory. - -Example: - - i2c@00000000 { - /* ... */ - - gt928@5d { - compatible = "goodix,gt928"; - reg = <0x5d>; - interrupt-parent = <&gpio>; - interrupts = <0 0>; - - irq-gpios = <&gpio1 0 0>; - reset-gpios = <&gpio1 1 0>; - }; - - /* ... */ - }; diff --git a/Documentation/devicetree/bindings/input/touchscreen/goodix.yaml b/Documentation/devicetree/bindings/input/touchscreen/goodix.yaml new file mode 100644 index 000000000000..d7c3262b2494 --- /dev/null +++ b/Documentation/devicetree/bindings/input/touchscreen/goodix.yaml @@ -0,0 +1,78 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/input/touchscreen/goodix.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Goodix GT9xx series touchscreen controller Bindings + +maintainers: + - Dmitry Torokhov <dmitry.torokhov@gmail.com> + +allOf: + - $ref: touchscreen.yaml# + +properties: + compatible: + enum: + - goodix,gt1151 + - goodix,gt5663 + - goodix,gt5688 + - goodix,gt911 + - goodix,gt9110 + - goodix,gt912 + - goodix,gt927 + - goodix,gt9271 + - goodix,gt928 + - goodix,gt967 + + reg: + enum: [ 0x5d, 0x14 ] + + interrupts: + maxItems: 1 + + irq-gpios: + description: GPIO pin used for IRQ. + The driver uses the interrupt gpio pin as + output to reset the device. + maxItems: 1 + + reset-gpios: + maxItems: 1 + + AVDD28-supply: + description: Analog power supply regulator on AVDD28 pin + + VDDIO-supply: + description: GPIO power supply regulator on VDDIO pin + + 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: +- | + i2c@00000000 { + #address-cells = <1>; + #size-cells = <0>; + gt928@5d { + compatible = "goodix,gt928"; + reg = <0x5d>; + interrupt-parent = <&gpio>; + interrupts = <0 0>; + irq-gpios = <&gpio1 0 0>; + reset-gpios = <&gpio1 1 0>; + }; + }; + +... diff --git a/Documentation/devicetree/bindings/input/touchscreen/touchscreen.txt b/Documentation/devicetree/bindings/input/touchscreen/touchscreen.txt index 8641a2d70851..e1adb902d503 100644 --- a/Documentation/devicetree/bindings/input/touchscreen/touchscreen.txt +++ b/Documentation/devicetree/bindings/input/touchscreen/touchscreen.txt @@ -1,39 +1 @@ -General Touchscreen Properties: - -Optional properties for Touchscreens: - - touchscreen-min-x : minimum x coordinate reported (0 if not set) - - touchscreen-min-y : minimum y coordinate reported (0 if not set) - - touchscreen-size-x : horizontal resolution of touchscreen - (maximum x coordinate reported + 1) - - touchscreen-size-y : vertical resolution of touchscreen - (maximum y coordinate reported + 1) - - touchscreen-max-pressure : maximum reported pressure (arbitrary range - dependent on the controller) - - touchscreen-min-pressure : minimum pressure on the touchscreen to be - achieved in order for the touchscreen - driver to report a touch event. - - 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-fuzz-pressure : pressure noise value of the absolute input - device (arbitrary range dependent on the - controller) - - touchscreen-average-samples : Number of data samples which are averaged - for each read (valid values dependent on the - controller) - - 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 - - touchscreen-x-mm : horizontal length in mm of the touchscreen - - touchscreen-y-mm : vertical length in mm of the touchscreen - -Deprecated properties for Touchscreens: - - x-size : deprecated name for touchscreen-size-x - - y-size : deprecated name for touchscreen-size-y - - moving-threshold : deprecated name for a combination of - touchscreen-fuzz-x and touchscreen-fuzz-y - - contact-threshold : deprecated name for touchscreen-fuzz-pressure - - x-invert : deprecated name for touchscreen-inverted-x - - y-invert : deprecated name for touchscreen-inverted-y +See touchscreen.yaml diff --git a/Documentation/devicetree/bindings/input/touchscreen/touchscreen.yaml b/Documentation/devicetree/bindings/input/touchscreen/touchscreen.yaml new file mode 100644 index 000000000000..d7dac16a3960 --- /dev/null +++ b/Documentation/devicetree/bindings/input/touchscreen/touchscreen.yaml @@ -0,0 +1,83 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/input/touchscreen/touchscreen.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Common touchscreen Bindings + +maintainers: + - Dmitry Torokhov <dmitry.torokhov@gmail.com> + +properties: + touchscreen-min-x: + description: minimum x coordinate reported + $ref: /schemas/types.yaml#/definitions/uint32 + default: 0 + + touchscreen-min-y: + description: minimum y coordinate reported + $ref: /schemas/types.yaml#/definitions/uint32 + default: 0 + + touchscreen-size-x: + description: horizontal resolution of touchscreen (maximum x coordinate reported + 1) + $ref: /schemas/types.yaml#/definitions/uint32 + + touchscreen-size-y: + description: vertical resolution of touchscreen (maximum y coordinate reported + 1) + $ref: /schemas/types.yaml#/definitions/uint32 + + touchscreen-max-pressure: + description: maximum reported pressure (arbitrary range dependent on the controller) + $ref: /schemas/types.yaml#/definitions/uint32 + + touchscreen-min-pressure: + description: minimum pressure on the touchscreen to be achieved in order for the + touchscreen driver to report a touch event. + $ref: /schemas/types.yaml#/definitions/uint32 + + touchscreen-fuzz-x: + description: horizontal noise value of the absolute input device (in pixels) + $ref: /schemas/types.yaml#/definitions/uint32 + + touchscreen-fuzz-y: + description: vertical noise value of the absolute input device (in pixels) + $ref: /schemas/types.yaml#/definitions/uint32 + + touchscreen-fuzz-pressure: + description: pressure noise value of the absolute input device (arbitrary range + dependent on the controller) + $ref: /schemas/types.yaml#/definitions/uint32 + + touchscreen-average-samples: + description: Number of data samples which are averaged for each read (valid values + dependent on the controller) + $ref: /schemas/types.yaml#/definitions/uint32 + + touchscreen-inverted-x: + description: X axis is inverted + type: boolean + + touchscreen-inverted-y: + description: Y axis is inverted + type: boolean + + touchscreen-swapped-x-y: + description: X and Y axis are swapped + Swapping is done after inverting the axis + type: boolean + + touchscreen-x-mm: + description: horizontal length in mm of the touchscreen + $ref: /schemas/types.yaml#/definitions/uint32 + + touchscreen-y-mm: + description: vertical length in mm of the touchscreen + $ref: /schemas/types.yaml#/definitions/uint32 + +dependencies: + touchscreen-size-x: [ touchscreen-size-y ] + touchscreen-size-y: [ touchscreen-size-x ] + touchscreen-x-mm: [ touchscreen-y-mm ] + touchscreen-y-mm: [ touchscreen-x-mm ] diff --git a/Documentation/devicetree/bindings/interconnect/qcom,msm8916.yaml b/Documentation/devicetree/bindings/interconnect/qcom,msm8916.yaml new file mode 100644 index 000000000000..4107e60cab12 --- /dev/null +++ b/Documentation/devicetree/bindings/interconnect/qcom,msm8916.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,msm8916.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Qualcomm MSM8916 Network-On-Chip interconnect + +maintainers: + - Georgi Djakov <georgi.djakov@linaro.org> + +description: | + The Qualcomm MSM8916 interconnect providers support adjusting the + bandwidth requirements between the various NoC fabrics. + +properties: + compatible: + enum: + - qcom,msm8916-bimc + - qcom,msm8916-pcnoc + - qcom,msm8916-snoc + + reg: + maxItems: 1 + + '#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 + +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>; + }; + + 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>; + }; diff --git a/Documentation/devicetree/bindings/interrupt-controller/amlogic,meson-gpio-intc.txt b/Documentation/devicetree/bindings/interrupt-controller/amlogic,meson-gpio-intc.txt index 684bb1cd75ec..23b18b92c558 100644 --- a/Documentation/devicetree/bindings/interrupt-controller/amlogic,meson-gpio-intc.txt +++ b/Documentation/devicetree/bindings/interrupt-controller/amlogic,meson-gpio-intc.txt @@ -17,6 +17,7 @@ Required properties: "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 diff --git a/Documentation/devicetree/bindings/interrupt-controller/aspeed,ast2xxx-scu-ic.txt b/Documentation/devicetree/bindings/interrupt-controller/aspeed,ast2xxx-scu-ic.txt new file mode 100644 index 000000000000..251ed44171db --- /dev/null +++ b/Documentation/devicetree/bindings/interrupt-controller/aspeed,ast2xxx-scu-ic.txt @@ -0,0 +1,23 @@ +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/fsl,intmux.yaml b/Documentation/devicetree/bindings/interrupt-controller/fsl,intmux.yaml new file mode 100644 index 000000000000..43c6effbb5bd --- /dev/null +++ b/Documentation/devicetree/bindings/interrupt-controller/fsl,intmux.yaml @@ -0,0 +1,68 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/interrupt-controller/fsl,intmux.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Freescale INTMUX interrupt multiplexer + +maintainers: + - Joakim Zhang <qiangqing.zhang@nxp.com> + +properties: + compatible: + const: fsl,imx-intmux + + reg: + maxItems: 1 + + interrupts: + minItems: 1 + maxItems: 8 + description: | + Should contain the parent interrupt lines (up to 8) used to multiplex + the input interrupts. + + interrupt-controller: true + + '#interrupt-cells': + const: 2 + description: | + The 1st cell is hw interrupt number, the 2nd cell is channel index. + + clocks: + description: ipg clock. + + clock-names: + const: ipg + +required: + - compatible + - reg + - interrupts + - interrupt-controller + - '#interrupt-cells' + - clocks + - clock-names + +additionalProperties: false + +examples: + - | + interrupt-controller@37400000 { + compatible = "fsl,imx-intmux"; + reg = <0x37400000 0x1000>; + interrupts = <0 16 4>, + <0 17 4>, + <0 18 4>, + <0 19 4>, + <0 20 4>, + <0 21 4>, + <0 22 4>, + <0 23 4>; + interrupt-controller; + interrupt-parent = <&gic>; + #interrupt-cells = <2>; + clocks = <&clk>; + clock-names = "ipg"; + }; diff --git a/Documentation/devicetree/bindings/iommu/iommu.txt b/Documentation/devicetree/bindings/iommu/iommu.txt index 5a8b4624defc..3c36334e4f94 100644 --- a/Documentation/devicetree/bindings/iommu/iommu.txt +++ b/Documentation/devicetree/bindings/iommu/iommu.txt @@ -86,6 +86,12 @@ have a means to turn off translation. But it is invalid in such cases to disable the IOMMU's device tree node in the first place because it would prevent any driver from properly setting up the translations. +Optional properties: +-------------------- +- pasid-num-bits: Some masters support multiple address spaces for DMA, by + tagging DMA transactions with an address space identifier. By default, + this is 0, which means that the device only has one address space. + Notes: ====== diff --git a/Documentation/devicetree/bindings/leds/common.txt b/Documentation/devicetree/bindings/leds/common.txt index 9fa6f9795d50..26d770ef3601 100644 --- a/Documentation/devicetree/bindings/leds/common.txt +++ b/Documentation/devicetree/bindings/leds/common.txt @@ -1,173 +1 @@ -* Common leds properties. - -LED and flash LED devices provide the same basic functionality as current -regulators, but extended with LED and flash LED specific features like -blinking patterns, flash timeout, flash faults and external flash strobe mode. - -Many LED devices expose more than one current output that can be connected -to one or more discrete LED component. Since the arrangement of connections -can influence the way of the LED device initialization, the LED components -have to be tightly coupled with the LED device binding. They are represented -by child nodes of the parent LED device binding. - - -Optional properties for child nodes: -- led-sources : List of device current outputs the LED is connected to. The - outputs are identified by the numbers that must be defined - in the LED device binding documentation. - -- function: LED functon. Use one of the LED_FUNCTION_* prefixed definitions - from the header include/dt-bindings/leds/common.h. - If there is no matching LED_FUNCTION available, add a new one. - -- color : Color of the LED. Use one of the LED_COLOR_ID_* prefixed definitions - from the header include/dt-bindings/leds/common.h. - If there is no matching LED_COLOR_ID available, add a new one. - -- function-enumerator: Integer to be used when more than one instance - of the same function is needed, differing only with - an ordinal number. - -- label : The label for this LED. If omitted, the label is taken from the node - name (excluding the unit address). It has to uniquely identify - a device, i.e. no other LED class device can be assigned the same - label. This property is deprecated - use 'function' and 'color' - properties instead. function-enumerator has no effect when this - property is present. - -- default-state : The initial state of the LED. Valid values are "on", "off", - and "keep". If the LED is already on or off and the default-state property is - set the to 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. The default is - off if this property is not present. - -- linux,default-trigger : This parameter, if present, is a - string defining the trigger assigned to the LED. Current triggers are: - "backlight" - LED will act as a back-light, controlled by the framebuffer - system - "default-on" - LED will turn on (but for leds-gpio see "default-state" - property in Documentation/devicetree/bindings/leds/leds-gpio.txt) - "heartbeat" - LED "double" flashes at a load average based rate - "disk-activity" - LED indicates disk activity - "ide-disk" - LED indicates IDE disk activity (deprecated), - in new implementations use "disk-activity" - "timer" - LED flashes at a fixed, configurable rate - "pattern" - LED alters the brightness for the specified duration with one - software timer (requires "led-pattern" property) - -- led-pattern : Array of integers with default pattern for certain triggers. - Each trigger may parse this property differently: - - one-shot : two numbers specifying delay on and delay off (in ms), - - timer : two numbers specifying delay on and delay off (in ms), - - pattern : the pattern is given by a series of tuples, of - brightness and duration (in ms). The exact format is - described in: - Documentation/devicetree/bindings/leds/leds-trigger-pattern.txt - - -- led-max-microamp : Maximum LED supply current in microamperes. This property - can be made mandatory for the board configurations - introducing a risk of hardware damage in case an excessive - current is set. - For flash LED controllers with configurable current this - property is mandatory for the LEDs in the non-flash modes - (e.g. torch or indicator). - -- panic-indicator : This property specifies that the LED should be used, - if at all possible, as a panic indicator. - -- trigger-sources : List of devices which should be used as a source triggering - this LED activity. Some LEDs can be related to a specific - device and should somehow indicate its state. E.g. USB 2.0 - LED may react to device(s) in a USB 2.0 port(s). - Another common example is switch or router with multiple - Ethernet ports 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). - 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 arguments. A - length of arguments should be specified by the - #trigger-source-cells property in the source node. - -Required properties for flash LED child nodes: -- flash-max-microamp : Maximum flash LED supply current in microamperes. -- flash-max-timeout-us : Maximum timeout in microseconds after which the flash - LED is turned off. - -For controllers that have no configurable current the flash-max-microamp -property can be omitted. -For controllers that have no configurable timeout the flash-max-timeout-us -property can be omitted. - -* Trigger source providers - -Each trigger source should be represented by a device tree node. It may be e.g. -a USB port or an Ethernet device. - -Required properties for trigger source: -- #trigger-source-cells : Number of cells in a source trigger. Typically 0 for - nodes of simple trigger sources (e.g. a specific USB - port). - -* Examples - -#include <dt-bindings/leds/common.h> - -led-controller@0 { - compatible = "gpio-leds"; - - led0 { - function = LED_FUNCTION_STATUS; - linux,default-trigger = "heartbeat"; - gpios = <&gpio0 0 GPIO_ACTIVE_HIGH>; - }; - - led1 { - function = LED_FUNCTION_USB; - gpios = <&gpio0 1 GPIO_ACTIVE_HIGH>; - trigger-sources = <&ohci_port1>, <&ehci_port1>; - }; -}; - -led-controller@0 { - compatible = "maxim,max77693-led"; - - led { - function = LED_FUNCTION_FLASH; - color = <LED_COLOR_ID_WHITE>; - led-sources = <0>, <1>; - led-max-microamp = <50000>; - flash-max-microamp = <320000>; - flash-max-timeout-us = <500000>; - }; -}; - -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; - function-enumerator = <1>; - }; - - led@2 { - reg = <2>; - function = LED_FUNCTION_INDICATOR; - function-enumerator = <2>; - }; - - led@3 { - reg = <3>; - function = LED_FUNCTION_INDICATOR; - function-enumerator = <3>; - }; -}; +This file has moved to ./common.yaml. diff --git a/Documentation/devicetree/bindings/leds/common.yaml b/Documentation/devicetree/bindings/leds/common.yaml new file mode 100644 index 000000000000..d97d099b87e5 --- /dev/null +++ b/Documentation/devicetree/bindings/leds/common.yaml @@ -0,0 +1,228 @@ +# SPDX-License-Identifier: GPL-2.0-only +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/leds/common.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Common leds properties + +maintainers: + - Jacek Anaszewski <jacek.anaszewski@gmail.com> + - Pavel Machek <pavel@ucw.cz> + +description: + LED and flash LED devices provide the same basic functionality as current + regulators, but extended with LED and flash LED specific features like + blinking patterns, flash timeout, flash faults and external flash strobe mode. + + Many LED devices expose more than one current output that can be connected + to one or more discrete LED component. Since the arrangement of connections + can influence the way of the LED device initialization, the LED components + have to be tightly coupled with the LED device binding. They are represented + by child nodes of the parent LED device binding. + +properties: + led-sources: + description: + List of device current outputs the LED is connected to. The outputs are + identified by the numbers that must be defined in the LED device binding + documentation. + $ref: /schemas/types.yaml#definitions/uint32-array + + function: + description: + LED function. Use one of the LED_FUNCTION_* prefixed definitions + from the header include/dt-bindings/leds/common.h. If there is no + matching LED_FUNCTION available, add a new one. + $ref: /schemas/types.yaml#definitions/string + + color: + description: + Color of the LED. Use one of the LED_COLOR_ID_* prefixed definitions from + the header include/dt-bindings/leds/common.h. If there is no matching + LED_COLOR_ID available, add a new one. + allOf: + - $ref: /schemas/types.yaml#definitions/uint32 + minimum: 0 + maximum: 8 + + function-enumerator: + description: + Integer to be used when more than one instance of the same function is + needed, differing only with an ordinal number. + $ref: /schemas/types.yaml#definitions/uint32 + + label: + description: + The label for this LED. If omitted, the label is taken from the node name + (excluding the unit address). It has to uniquely identify a device, i.e. + no other LED class device can be assigned the same label. This property is + deprecated - use 'function' and 'color' properties instead. + function-enumerator has no effect when this property is present. + + 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 + 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. + allOf: + - $ref: /schemas/types.yaml#definitions/string + enum: + - on + - off + - keep + default: off + + linux,default-trigger: + description: + This parameter, if present, is a string defining the trigger assigned to + the LED. + allOf: + - $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.txt) + - 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 + + led-pattern: + description: | + Array of integers with default pattern for certain triggers. + + Each trigger may parse this property differently: + - one-shot : two numbers specifying delay on and delay off (in ms), + - timer : two numbers specifying delay on and delay off (in ms), + - pattern : the pattern is given by a series of tuples, of + brightness and duration (in ms). The exact format is + described in: + Documentation/devicetree/bindings/leds/leds-trigger-pattern.txt + allOf: + - $ref: /schemas/types.yaml#definitions/uint32-matrix + items: + minItems: 2 + maxItems: 2 + + led-max-microamp: + description: + Maximum LED supply current in microamperes. This property can be made + mandatory for the board configurations introducing a risk of hardware + damage in case an excessive current is set. + For flash LED controllers with configurable current this property is + mandatory for the LEDs in the non-flash modes (e.g. torch or indicator). + + panic-indicator: + description: + This property specifies that the LED should be used, if at all possible, + as a panic indicator. + type: boolean + + trigger-sources: + description: | + List of devices which should be used as a source triggering this LED + activity. Some LEDs can be related to a specific device and should somehow + indicate its state. E.g. USB 2.0 LED may react to device(s) in a USB 2.0 + port(s). + Another common example is switch or router with multiple Ethernet ports + 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). + 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 + arguments. A length of arguments should be specified by the + #trigger-source-cells property in the source node. + $ref: /schemas/types.yaml#definitions/phandle-array + + # Required properties for flash LED child nodes: + flash-max-microamp: + description: + Maximum flash LED supply current in microamperes. Required for flash LED + nodes with configurable current. + + flash-max-timeout-us: + description: + Maximum timeout in microseconds after which the flash LED is turned off. + Required for flash LED nodes with configurable timeout. + +examples: + - | + #include <dt-bindings/gpio/gpio.h> + #include <dt-bindings/leds/common.h> + + led-controller { + compatible = "gpio-leds"; + + led0 { + function = LED_FUNCTION_STATUS; + linux,default-trigger = "heartbeat"; + gpios = <&gpio0 0 GPIO_ACTIVE_HIGH>; + }; + + led1 { + function = LED_FUNCTION_USB; + gpios = <&gpio0 1 GPIO_ACTIVE_HIGH>; + trigger-sources = <&ohci_port1>, <&ehci_port1>; + }; + }; + + led-controller@0 { + compatible = "maxim,max77693-led"; + reg = <0 0x100>; + + led { + function = LED_FUNCTION_FLASH; + color = <LED_COLOR_ID_WHITE>; + led-sources = <0>, <1>; + led-max-microamp = <50000>; + flash-max-microamp = <320000>; + flash-max-timeout-us = <500000>; + }; + }; + + 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; + function-enumerator = <1>; + }; + + led@2 { + reg = <2>; + function = LED_FUNCTION_INDICATOR; + function-enumerator = <2>; + }; + + led@3 { + reg = <3>; + function = LED_FUNCTION_INDICATOR; + function-enumerator = <3>; + }; + }; + }; + +... diff --git a/Documentation/devicetree/bindings/leds/irled/spi-ir-led.txt b/Documentation/devicetree/bindings/leds/irled/spi-ir-led.txt index 21882c8d4b0c..83ff1b4d70a6 100644 --- a/Documentation/devicetree/bindings/leds/irled/spi-ir-led.txt +++ b/Documentation/devicetree/bindings/leds/irled/spi-ir-led.txt @@ -8,7 +8,7 @@ Required properties: - compatible: should be "ir-spi-led". Optional properties: - - duty-cycle: 8 bit balue that represents the percentage of one period + - 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. diff --git a/Documentation/devicetree/bindings/leds/leds-gpio.txt b/Documentation/devicetree/bindings/leds/leds-gpio.txt deleted file mode 100644 index d21281b63d38..000000000000 --- a/Documentation/devicetree/bindings/leds/leds-gpio.txt +++ /dev/null @@ -1,75 +0,0 @@ -LEDs connected to GPIO lines - -Required properties: -- compatible : should be "gpio-leds". - -Each LED is represented as a sub-node of the gpio-leds device. Each -node's name represents the name of the corresponding LED. - -LED sub-node properties: -- gpios : Should specify the LED's GPIO, see "gpios property" in - Documentation/devicetree/bindings/gpio/gpio.txt. Active low LEDs should be - indicated using flags in the GPIO specifier. -- function : (optional) - see Documentation/devicetree/bindings/leds/common.txt -- color : (optional) - see Documentation/devicetree/bindings/leds/common.txt -- label : (optional) - see Documentation/devicetree/bindings/leds/common.txt (deprecated) -- 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 -- retain-state-suspended: (optional) The suspend state can be retained.Such - as charge-led gpio. -- retain-state-shutdown: (optional) Retain the state of the LED on shutdown. - Useful in BMC systems, for example when the BMC is rebooted while the host - remains up. -- panic-indicator : (optional) - see Documentation/devicetree/bindings/leds/common.txt - -Examples: - -#include <dt-bindings/gpio/gpio.h> -#include <dt-bindings/leds/common.h> - -leds { - compatible = "gpio-leds"; - led0 { - gpios = <&mcu_pio 0 GPIO_ACTIVE_LOW>; - linux,default-trigger = "disk-activity"; - function = LED_FUNCTION_DISK; - }; - - led1 { - gpios = <&mcu_pio 1 GPIO_ACTIVE_HIGH>; - /* Keep LED on if BIOS detected hardware fault */ - default-state = "keep"; - function = LED_FUNCTION_FAULT; - }; -}; - -run-control { - compatible = "gpio-leds"; - led0 { - gpios = <&mpc8572 6 GPIO_ACTIVE_HIGH>; - color = <LED_COLOR_ID_RED>; - default-state = "off"; - }; - led1 { - gpios = <&mpc8572 7 GPIO_ACTIVE_HIGH>; - color = <LED_COLOR_ID_GREEN>; - default-state = "on"; - }; -}; - -leds { - compatible = "gpio-leds"; - - led0 { - gpios = <&gpio1 2 GPIO_ACTIVE_HIGH>; - linux,default-trigger = "max8903-charger-charging"; - retain-state-suspended; - function = LED_FUNCTION_CHARGE; - }; -}; diff --git a/Documentation/devicetree/bindings/leds/leds-gpio.yaml b/Documentation/devicetree/bindings/leds/leds-gpio.yaml new file mode 100644 index 000000000000..0e75b185dd19 --- /dev/null +++ b/Documentation/devicetree/bindings/leds/leds-gpio.yaml @@ -0,0 +1,86 @@ +# SPDX-License-Identifier: GPL-2.0-only +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/leds/leds-gpio.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: LEDs connected to GPIO lines + +maintainers: + - Jacek Anaszewski <jacek.anaszewski@gmail.com> + - Pavel Machek <pavel@ucw.cz> + +description: + Each LED is represented as a sub-node of the gpio-leds device. Each + node's name represents the name of the corresponding LED. + +properties: + compatible: + const: gpio-leds + +patternProperties: + # The first form is preferred, but fall back to just 'led' anywhere in the + # node name to at least catch some child nodes. + "(^led-[0-9a-f]$|led)": + type: object + + allOf: + - $ref: common.yaml# + + properties: + gpios: + maxItems: 1 + + retain-state-suspended: + description: + The suspend state can be retained.Such as charge-led gpio. + type: boolean + + retain-state-shutdown: + description: + Retain the state of the LED on shutdown. Useful in BMC systems, for + example when the BMC is rebooted while the host remains up. + type: boolean + + required: + - gpios + +additionalProperties: false + +examples: + - | + + #include <dt-bindings/gpio/gpio.h> + #include <dt-bindings/leds/common.h> + + leds { + compatible = "gpio-leds"; + led-0 { + gpios = <&mcu_pio 0 GPIO_ACTIVE_LOW>; + linux,default-trigger = "disk-activity"; + function = LED_FUNCTION_DISK; + }; + + led-1 { + gpios = <&mcu_pio 1 GPIO_ACTIVE_HIGH>; + /* Keep LED on if BIOS detected hardware fault */ + default-state = "keep"; + function = LED_FUNCTION_FAULT; + }; + }; + + run-control { + compatible = "gpio-leds"; + led-0 { + gpios = <&mpc8572 6 GPIO_ACTIVE_HIGH>; + color = <LED_COLOR_ID_RED>; + default-state = "off"; + }; + led-1 { + gpios = <&mpc8572 7 GPIO_ACTIVE_HIGH>; + color = <LED_COLOR_ID_GREEN>; + default-state = "on"; + }; + }; + +... diff --git a/Documentation/devicetree/bindings/leds/leds-lm3692x.txt b/Documentation/devicetree/bindings/leds/leds-lm3692x.txt index 4c2d923f8758..501468aa4d38 100644 --- a/Documentation/devicetree/bindings/leds/leds-lm3692x.txt +++ b/Documentation/devicetree/bindings/leds/leds-lm3692x.txt @@ -18,6 +18,10 @@ Required properties: 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 @@ -31,6 +35,8 @@ Optional child properties: - 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: @@ -44,12 +50,14 @@ led-controller@36 { 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/leds/rohm,bd71828-leds.yaml b/Documentation/devicetree/bindings/leds/rohm,bd71828-leds.yaml new file mode 100644 index 000000000000..b50f4bcc98f1 --- /dev/null +++ b/Documentation/devicetree/bindings/leds/rohm,bd71828-leds.yaml @@ -0,0 +1,52 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/leds/rohm,bd71828-leds.yaml# +$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> + +description: | + This module is part of the ROHM BD71828 MFD device. For more details + see Documentation/devicetree/bindings/mfd/rohm,bd71828-pmic.yaml. + + The LED controller is represented as a sub-node of the PMIC node on the device + tree. + + 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. + properties: + #allOf: + #- $ref: "common.yaml#" + rohm,led-compatible: + description: LED identification string + allOf: + - $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/trigger-source.yaml b/Documentation/devicetree/bindings/leds/trigger-source.yaml new file mode 100644 index 000000000000..0618003e40bd --- /dev/null +++ b/Documentation/devicetree/bindings/leds/trigger-source.yaml @@ -0,0 +1,24 @@ +# SPDX-License-Identifier: GPL-2.0-only +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/leds/trigger-source.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Trigger source providers + +maintainers: + - Jacek Anaszewski <jacek.anaszewski@gmail.com> + - Pavel Machek <pavel@ucw.cz> + +description: + Each trigger source provider should be represented by a device tree node. It + may be e.g. a USB port or an Ethernet device. + +properties: + '#trigger-source-cells': + description: + Number of cells in a source trigger. Typically 0 for nodes of simple + trigger sources (e.g. a specific USB port). + enum: [ 0, 1 ] + +... diff --git a/Documentation/devicetree/bindings/mailbox/qcom,apcs-kpss-global.txt b/Documentation/devicetree/bindings/mailbox/qcom,apcs-kpss-global.txt index 0278482af65c..beec612dbe6a 100644 --- a/Documentation/devicetree/bindings/mailbox/qcom,apcs-kpss-global.txt +++ b/Documentation/devicetree/bindings/mailbox/qcom,apcs-kpss-global.txt @@ -21,10 +21,11 @@ platforms. Usage: required Value type: <prop-encoded-array> Definition: must specify the base address and size of the global block + - clocks: - Usage: required if #clocks-cells property is present - Value type: <phandle> - Definition: phandle to the input PLL, which feeds the APCS mux/divider + Usage: required if #clock-names property is present + Value type: <phandle array> + Definition: phandles to the two parent clocks of the clock driver. - #mbox-cells: Usage: required @@ -36,6 +37,12 @@ platforms. Value type: <u32> Definition: as described in clock.txt, must be 0 +- clock-names: + Usage: required if the platform data based clock driver needs to + retrieve the parent clock names from device tree. + This will requires two mandatory clocks to be defined. + Value type: <string-array> + Definition: must be "pll" and "aux" = EXAMPLE The following example describes the APCS HMSS found in MSM8996 and part of the @@ -68,3 +75,14 @@ Below is another example of the APCS binding on MSM8916 platforms: clocks = <&a53pll>; #clock-cells = <0>; }; + +Below is another example of the APCS binding on QCS404 platforms: + + apcs_glb: mailbox@b011000 { + compatible = "qcom,qcs404-apcs-apps-global", "syscon"; + reg = <0x0b011000 0x1000>; + #mbox-cells = <1>; + clocks = <&apcs_hfpll>, <&gcc GCC_GPLL0_AO_OUT_MAIN>; + clock-names = "pll", "aux"; + #clock-cells = <0>; + }; diff --git a/Documentation/devicetree/bindings/media/allwinner,sun4i-a10-csi.yaml b/Documentation/devicetree/bindings/media/allwinner,sun4i-a10-csi.yaml index 0f6374ceaa69..8453ee340b9f 100644 --- a/Documentation/devicetree/bindings/media/allwinner,sun4i-a10-csi.yaml +++ b/Documentation/devicetree/bindings/media/allwinner,sun4i-a10-csi.yaml @@ -16,7 +16,15 @@ description: |- properties: compatible: - const: allwinner,sun7i-a20-csi0 + oneOf: + - const: allwinner,sun4i-a10-csi1 + - const: allwinner,sun7i-a20-csi0 + - items: + - const: allwinner,sun7i-a20-csi1 + - const: allwinner,sun4i-a10-csi1 + - items: + - const: allwinner,sun8i-r40-csi0 + - const: allwinner,sun7i-a20-csi0 reg: maxItems: 1 @@ -25,20 +33,40 @@ properties: maxItems: 1 clocks: - items: - - description: The CSI interface clock - - description: The CSI ISP clock - - description: The CSI DRAM clock + oneOf: + - items: + - description: The CSI interface clock + - description: The CSI DRAM clock + + - items: + - description: The CSI interface clock + - description: The CSI ISP clock + - description: The CSI DRAM clock clock-names: - items: - - const: bus - - const: isp - - const: ram + oneOf: + - items: + - const: bus + - const: ram + + - items: + - const: bus + - const: isp + - const: ram resets: maxItems: 1 + # FIXME: This should be made required eventually once every SoC will + # have the MBUS declared. + interconnects: + maxItems: 1 + + # FIXME: This should be made required eventually once every SoC will + # have the MBUS declared. + interconnect-names: + const: dma-mem + # See ./video-interfaces.txt for details port: type: object diff --git a/Documentation/devicetree/bindings/media/allwinner,sun4i-a10-video-engine.yaml b/Documentation/devicetree/bindings/media/allwinner,sun4i-a10-video-engine.yaml new file mode 100644 index 000000000000..526593c8c614 --- /dev/null +++ b/Documentation/devicetree/bindings/media/allwinner,sun4i-a10-video-engine.yaml @@ -0,0 +1,83 @@ +# SPDX-License-Identifier: GPL-2.0-only +%YAML 1.2 +--- +$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 + +maintainers: + - Chen-Yu Tsai <wens@csie.org> + - Maxime Ripard <mripard@kernel.org> + +properties: + compatible: + enum: + - allwinner,sun4i-a10-video-engine + - allwinner,sun5i-a13-video-engine + - allwinner,sun7i-a20-video-engine + - allwinner,sun8i-a33-video-engine + - allwinner,sun8i-h3-video-engine + - allwinner,sun50i-a64-video-engine + - allwinner,sun50i-h5-video-engine + - allwinner,sun50i-h6-video-engine + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + clocks: + items: + - description: Bus Clock + - description: Module Clock + - description: RAM Clock + + clock-names: + items: + - const: ahb + - const: mod + - const: ram + + resets: + maxItems: 1 + + allwinner,sram: + $ref: /schemas/types.yaml#/definitions/phandle-array + description: Phandle to the device SRAM + + memory-region: + description: + CMA pool to use for buffers allocation instead of the default + CMA pool. + +required: + - compatible + - reg + - interrupts + - clocks + - clock-names + - resets + - allwinner,sram + +additionalProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/arm-gic.h> + #include <dt-bindings/clock/sun7i-a20-ccu.h> + #include <dt-bindings/reset/sun4i-a10-ccu.h> + + video-codec@1c0e000 { + compatible = "allwinner,sun7i-a20-video-engine"; + reg = <0x01c0e000 0x1000>; + interrupts = <GIC_SPI 53 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&ccu CLK_AHB_VE>, <&ccu CLK_VE>, + <&ccu CLK_DRAM_VE>; + clock-names = "ahb", "mod", "ram"; + resets = <&ccu RST_VE>; + allwinner,sram = <&ve_sram 1>; + }; + +... diff --git a/Documentation/devicetree/bindings/media/allwinner,sun6i-a31-csi.yaml b/Documentation/devicetree/bindings/media/allwinner,sun6i-a31-csi.yaml new file mode 100644 index 000000000000..1fd9b5532a21 --- /dev/null +++ b/Documentation/devicetree/bindings/media/allwinner,sun6i-a31-csi.yaml @@ -0,0 +1,115 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$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 + +maintainers: + - Chen-Yu Tsai <wens@csie.org> + - Maxime Ripard <mripard@kernel.org> + +properties: + compatible: + enum: + - allwinner,sun6i-a31-csi + - allwinner,sun8i-a83t-csi + - allwinner,sun8i-h3-csi + - allwinner,sun8i-v3s-csi + - allwinner,sun50i-a64-csi + + 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 + + # See ./video-interfaces.txt for details + port: + type: object + + properties: + endpoint: + type: object + + properties: + remote-endpoint: true + + bus-width: + enum: [ 8, 10, 12, 16 ] + + pclk-sample: true + hsync-active: true + vsync-active: true + + required: + - bus-width + - remote-endpoint + + required: + - endpoint + + additionalProperties: false + +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> + + csi1: csi@1cb4000 { + compatible = "allwinner,sun8i-v3s-csi"; + reg = <0x01cb4000 0x1000>; + interrupts = <GIC_SPI 84 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&ccu CLK_BUS_CSI>, + <&ccu CLK_CSI1_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 */ + }; + }; + }; + +... diff --git a/Documentation/devicetree/bindings/media/amlogic,gx-vdec.yaml b/Documentation/devicetree/bindings/media/amlogic,gx-vdec.yaml new file mode 100644 index 000000000000..335717e15970 --- /dev/null +++ b/Documentation/devicetree/bindings/media/amlogic,gx-vdec.yaml @@ -0,0 +1,141 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +# 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#" + +title: Amlogic Video Decoder + +maintainers: + - Neil Armstrong <narmstrong@baylibre.com> + - Maxime Jourdan <mjourdan@baylibre.com> + +description: | + The video decoding IP lies within the DOS memory region, + except for the hardware bitstream parser that makes use of an undocumented + region. + + It makes use of the following blocks: + - ESPARSER is a bitstream parser that outputs to a VIFIFO. Further VDEC blocks + then feed from this VIFIFO. + - VDEC_1 can decode MPEG-1, MPEG-2, MPEG-4 part 2, MJPEG, H.263, H.264, VC-1. + - VDEC_HEVC can decode HEVC and VP9. + + Both VDEC_1 and VDEC_HEVC share the "vdec" IRQ and as such cannot run + concurrently. + +properties: + compatible: + oneOf: + - items: + - enum: + - amlogic,gxbb-vdec # GXBB (S905) + - amlogic,gxl-vdec # GXL (S905X, S905D) + - amlogic,gxm-vdec # GXM (S912) + - const: amlogic,gx-vdec + - enum: + - amlogic,g12a-vdec # G12A (S905X2, S905D2) + - amlogic,sm1-vdec # SM1 (S905X3, S905D3) + + interrupts: + minItems: 2 + + interrupt-names: + items: + - const: vdec + - const: esparser + + reg: + minItems: 2 + + reg-names: + items: + - const: dos + - const: esparser + + resets: + maxItems: 1 + + reset-names: + items: + - const: esparser + + clocks: + minItems: 4 + maxItems: 5 + + clock-names: + minItems: 4 + maxItems: 5 + items: + - const: dos_parser + - const: dos + - const: vdec_1 + - const: vdec_hevc + - const: vdec_hevcf + + amlogic,ao-sysctrl: + description: should point to the AOBUS sysctrl node + allOf: + - $ref: /schemas/types.yaml#/definitions/phandle + + amlogic,canvas: + description: should point to a canvas provider node + allOf: + - $ref: /schemas/types.yaml#/definitions/phandle + +allOf: + - if: + properties: + compatible: + contains: + enum: + - amlogic,gx-vdec + + then: + properties: + clock-names: + maxItems: 4 + + - if: + properties: + compatible: + contains: + enum: + - amlogic,g12a-vdec + - amlogic,sm1-vdec + + then: + properties: + clock-names: + minItems: 5 + +required: + - compatible + - reg + - reg-names + - interrupts + - interrupt-names + - clocks + - clock-names + - resets + - reset-names + - amlogic,ao-sysctrl + - amlogic,canvas + +examples: + - | + vdec: video-decoder@c8820000 { + compatible = "amlogic,gxl-vdec", "amlogic,gx-vdec"; + reg = <0xc8820000 0x10000>, <0xc110a580 0xe4>; + reg-names = "dos", "esparser"; + interrupts = <44>, <32>; + interrupt-names = "vdec", "esparser"; + clocks = <&clk_dos_parser> ,<&clk_dos>, <&clk_vdec_1>, <&clk_vdec_hevc>; + clock-names = "dos_parser", "dos", "vdec_1", "vdec_hevc"; + resets = <&reset_parser>; + reset-names = "esparser"; + amlogic,ao-sysctrl = <&sysctrl_AO>; + amlogic,canvas = <&canvas>; + }; diff --git a/Documentation/devicetree/bindings/media/amlogic,vdec.txt b/Documentation/devicetree/bindings/media/amlogic,vdec.txt deleted file mode 100644 index 9b6aace86ca7..000000000000 --- a/Documentation/devicetree/bindings/media/amlogic,vdec.txt +++ /dev/null @@ -1,72 +0,0 @@ -Amlogic Video Decoder -================================ - -The video decoding IP lies within the DOS memory region, -except for the hardware bitstream parser that makes use of an undocumented -region. - -It makes use of the following blocks: - -- ESPARSER is a bitstream parser that outputs to a VIFIFO. Further VDEC blocks -then feed from this VIFIFO. -- VDEC_1 can decode MPEG-1, MPEG-2, MPEG-4 part 2, MJPEG, H.263, H.264, VC-1. -- VDEC_HEVC can decode HEVC and VP9. - -Both VDEC_1 and VDEC_HEVC share the "vdec" IRQ and as such cannot run -concurrently. - -Device Tree Bindings: ---------------------- - -VDEC: Video Decoder --------------------------- - -Required properties: -- compatible: value should be different for each SoC family as : - - GXBB (S905) : "amlogic,gxbb-vdec" - - GXL (S905X, S905D) : "amlogic,gxl-vdec" - - GXM (S912) : "amlogic,gxm-vdec" - followed by the common "amlogic,gx-vdec" -- reg: base address and size of he following memory-mapped regions : - - dos - - esparser -- reg-names: should contain the names of the previous memory regions -- interrupts: should contain the following IRQs: - - vdec - - esparser -- interrupt-names: should contain the names of the previous interrupts -- amlogic,ao-sysctrl: should point to the AOBUS sysctrl node -- amlogic,canvas: should point to a canvas provider node -- clocks: should contain the following clocks : - - dos_parser - - dos - - vdec_1 - - vdec_hevc -- clock-names: should contain the names of the previous clocks -- resets: should contain the parser reset -- reset-names: should be "esparser" - -Example: - -vdec: video-codec@c8820000 { - compatible = "amlogic,gxbb-vdec", "amlogic,gx-vdec"; - reg = <0x0 0xc8820000 0x0 0x10000>, - <0x0 0xc110a580 0x0 0xe4>; - reg-names = "dos", "esparser"; - - interrupts = <GIC_SPI 44 IRQ_TYPE_EDGE_RISING>, - <GIC_SPI 32 IRQ_TYPE_EDGE_RISING>; - interrupt-names = "vdec", "esparser"; - - amlogic,ao-sysctrl = <&sysctrl_AO>; - amlogic,canvas = <&canvas>; - - clocks = <&clkc CLKID_DOS_PARSER>, - <&clkc CLKID_DOS>, - <&clkc CLKID_VDEC_1>, - <&clkc CLKID_VDEC_HEVC>; - clock-names = "dos_parser", "dos", "vdec_1", "vdec_hevc"; - - resets = <&reset RESET_PARSER>; - reset-names = "esparser"; -}; diff --git a/Documentation/devicetree/bindings/media/atmel-isi.txt b/Documentation/devicetree/bindings/media/atmel-isi.txt index 332513a151cc..8924c7545b63 100644 --- a/Documentation/devicetree/bindings/media/atmel-isi.txt +++ b/Documentation/devicetree/bindings/media/atmel-isi.txt @@ -2,7 +2,7 @@ Atmel Image Sensor Interface (ISI) ---------------------------------- Required properties for ISI: -- compatible: must be "atmel,at91sam9g45-isi". +- compatible: must be "atmel,at91sam9g45-isi" or "microchip,sam9x60-isi". - reg: physical base address and length of the registers set for the device. - interrupts: should contain IRQ line for the ISI. - clocks: list of clock specifiers, corresponding to entries in the clock-names diff --git a/Documentation/devicetree/bindings/media/cedrus.txt b/Documentation/devicetree/bindings/media/cedrus.txt deleted file mode 100644 index 20c82fb0c343..000000000000 --- a/Documentation/devicetree/bindings/media/cedrus.txt +++ /dev/null @@ -1,57 +0,0 @@ -Device-tree bindings for the VPU found in Allwinner SoCs, referred to as the -Video Engine (VE) in Allwinner literature. - -The VPU can only access the first 256 MiB of DRAM, that are DMA-mapped starting -from the DRAM base. This requires specific memory allocation and handling. - -Required properties: -- compatible : must be one of the following compatibles: - - "allwinner,sun4i-a10-video-engine" - - "allwinner,sun5i-a13-video-engine" - - "allwinner,sun7i-a20-video-engine" - - "allwinner,sun8i-a33-video-engine" - - "allwinner,sun8i-h3-video-engine" - - "allwinner,sun50i-a64-video-engine" - - "allwinner,sun50i-h5-video-engine" - - "allwinner,sun50i-h6-video-engine" -- reg : register base and length of VE; -- clocks : list of clock specifiers, corresponding to entries in - the clock-names property; -- clock-names : should contain "ahb", "mod" and "ram" entries; -- resets : phandle for reset; -- interrupts : VE interrupt number; -- allwinner,sram : SRAM region to use with the VE. - -Optional properties: -- memory-region : CMA pool to use for buffers allocation instead of the - default CMA pool. - -Example: - -reserved-memory { - #address-cells = <1>; - #size-cells = <1>; - ranges; - - /* Address must be kept in the lower 256 MiBs of DRAM for VE. */ - cma_pool: default-pool { - compatible = "shared-dma-pool"; - size = <0x6000000>; - alloc-ranges = <0x4a000000 0x6000000>; - reusable; - linux,cma-default; - }; -}; - -video-codec@1c0e000 { - compatible = "allwinner,sun7i-a20-video-engine"; - reg = <0x01c0e000 0x1000>; - - clocks = <&ccu CLK_AHB_VE>, <&ccu CLK_VE>, - <&ccu CLK_DRAM_VE>; - clock-names = "ahb", "mod", "ram"; - - resets = <&ccu RST_VE>; - interrupts = <GIC_SPI 53 IRQ_TYPE_LEVEL_HIGH>; - allwinner,sram = <&ve_sram 1>; -}; diff --git a/Documentation/devicetree/bindings/media/exynos-jpeg-codec.txt b/Documentation/devicetree/bindings/media/exynos-jpeg-codec.txt index 38941db23dd2..ce9a22689e53 100644 --- a/Documentation/devicetree/bindings/media/exynos-jpeg-codec.txt +++ b/Documentation/devicetree/bindings/media/exynos-jpeg-codec.txt @@ -1,4 +1,4 @@ -Samsung S5P/EXYNOS SoC series JPEG codec +Samsung S5P/Exynos SoC series JPEG codec Required properties: diff --git a/Documentation/devicetree/bindings/media/exynos5-gsc.txt b/Documentation/devicetree/bindings/media/exynos5-gsc.txt index bc963a6d305a..1872688fa408 100644 --- a/Documentation/devicetree/bindings/media/exynos5-gsc.txt +++ b/Documentation/devicetree/bindings/media/exynos5-gsc.txt @@ -1,6 +1,6 @@ * Samsung Exynos5 G-Scaler device -G-Scaler is used for scaling and color space conversion on EXYNOS5 SoCs. +G-Scaler is used for scaling and color space conversion on Exynos5 SoCs. Required properties: - compatible: should be one of diff --git a/Documentation/devicetree/bindings/media/fsl-pxp.txt b/Documentation/devicetree/bindings/media/fsl-pxp.txt index 2477e7f87381..f8090e06530d 100644 --- a/Documentation/devicetree/bindings/media/fsl-pxp.txt +++ b/Documentation/devicetree/bindings/media/fsl-pxp.txt @@ -8,7 +8,7 @@ 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, imx6ul, imx6sx, imx6ull, or imx7d. + 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" diff --git a/Documentation/devicetree/bindings/media/hix5hd2-ir.txt b/Documentation/devicetree/bindings/media/hix5hd2-ir.txt index 13ebc0fac9ea..ca4cf774662e 100644 --- a/Documentation/devicetree/bindings/media/hix5hd2-ir.txt +++ b/Documentation/devicetree/bindings/media/hix5hd2-ir.txt @@ -1,7 +1,8 @@ Device-Tree bindings for hix5hd2 ir IP Required properties: - - compatible: Should contain "hisilicon,hix5hd2-ir". + - compatible: Should contain "hisilicon,hix5hd2-ir", or: + - "hisilicon,hi3796cv300-ir" for Hi3796CV300 IR device. - reg: Base physical address of the controller and length of memory mapped region. - interrupts: interrupt-specifier for the sole interrupt generated by diff --git a/Documentation/devicetree/bindings/media/rc.yaml b/Documentation/devicetree/bindings/media/rc.yaml index d11380794ff4..a64ee038d235 100644 --- a/Documentation/devicetree/bindings/media/rc.yaml +++ b/Documentation/devicetree/bindings/media/rc.yaml @@ -123,6 +123,7 @@ properties: - rc-su3000 - rc-tango - rc-tanix-tx3mini + - rc-tanix-tx5max - rc-tbs-nec - rc-technisat-ts35 - rc-technisat-usb2 diff --git a/Documentation/devicetree/bindings/media/renesas,ceu.txt b/Documentation/devicetree/bindings/media/renesas,ceu.txt deleted file mode 100644 index 3e2a2652eb19..000000000000 --- a/Documentation/devicetree/bindings/media/renesas,ceu.txt +++ /dev/null @@ -1,86 +0,0 @@ -Renesas Capture Engine Unit (CEU) ----------------------------------------------- - -The Capture Engine Unit is the image capture interface found in the Renesas -SH Mobile, R-Mobile and RZ SoCs. - -The interface supports a single parallel input with data bus width of 8 or 16 -bits. - -Required properties: -- compatible: Shall be one of the following values: - "renesas,r7s72100-ceu" for CEU units found in RZ/A1H and RZ/A1M SoCs - "renesas,r8a7740-ceu" for CEU units found in R-Mobile A1 R8A7740 SoCs -- reg: Registers address base and size. -- interrupts: The interrupt specifier. - -The CEU supports a single parallel input and should contain a single 'port' -subnode with a single 'endpoint'. Connection to input devices are modeled -according to the video interfaces OF bindings specified in: -[1] Documentation/devicetree/bindings/media/video-interfaces.txt - -Optional endpoint properties applicable to parallel input bus described in -the above mentioned "video-interfaces.txt" file are supported. - -- hsync-active: See [1] for description. If property is not present, - default is active high. -- vsync-active: See [1] for description. If property is not present, - default is active high. -- bus-width: See [1] for description. Accepted values are '8' and '16'. - If property is not present, default is '8'. -- field-even-active: See [1] for description. If property is not present, - an even field is identified by a logic 0 (active-low signal). - -Example: - -The example describes the connection between the Capture Engine Unit and an -OV7670 image sensor connected to i2c1 interface. - -ceu: ceu@e8210000 { - reg = <0xe8210000 0x209c>; - compatible = "renesas,r7s72100-ceu"; - interrupts = <GIC_SPI 332 IRQ_TYPE_LEVEL_HIGH>; - - pinctrl-names = "default"; - pinctrl-0 = <&vio_pins>; - - status = "okay"; - - port { - ceu_in: endpoint { - remote-endpoint = <&ov7670_out>; - - hsync-active = <1>; - vsync-active = <0>; - }; - }; -}; - -i2c1: i2c@fcfee400 { - pinctrl-names = "default"; - pinctrl-0 = <&i2c1_pins>; - - status = "okay"; - - clock-frequency = <100000>; - - ov7670: camera@21 { - compatible = "ovti,ov7670"; - reg = <0x21>; - - pinctrl-names = "default"; - pinctrl-0 = <&vio_pins>; - - reset-gpios = <&port3 11 GPIO_ACTIVE_LOW>; - powerdown-gpios = <&port3 12 GPIO_ACTIVE_HIGH>; - - port { - ov7670_out: endpoint { - remote-endpoint = <&ceu_in>; - - hsync-active = <1>; - vsync-active = <0>; - }; - }; - }; -}; diff --git a/Documentation/devicetree/bindings/media/renesas,ceu.yaml b/Documentation/devicetree/bindings/media/renesas,ceu.yaml new file mode 100644 index 000000000000..8e9251a0f9ef --- /dev/null +++ b/Documentation/devicetree/bindings/media/renesas,ceu.yaml @@ -0,0 +1,78 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/media/renesas,ceu.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Renesas Capture Engine Unit (CEU) Bindings + +maintainers: + - Jacopo Mondi <jacopo+renesas@jmondi.org> + - linux-renesas-soc@vger.kernel.org + +description: |+ + The Capture Engine Unit is the image capture interface found in the Renesas SH + Mobile, R-Mobile and RZ SoCs. The interface supports a single parallel input + with data bus width of 8 or 16 bits. + +properties: + compatible: + enum: + - renesas,r7s72100-ceu + - renesas,r8a7740-ceu + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + port: + type: object + additionalProperties: false + + properties: + endpoint: + type: object + additionalProperties: false + + # Properties described in + # Documentation/devicetree/bindings/media/video-interfaces.txt + properties: + remote-endpoint: true + hsync-active: true + vsync-active: true + field-even-active: false + bus-width: + enum: [8, 16] + default: 8 + + required: + - remote-endpoint + + required: + - endpoint + +required: + - compatible + - reg + - interrupts + - port + +examples: + - | + #include <dt-bindings/interrupt-controller/arm-gic.h> + + ceu: ceu@e8210000 { + reg = <0xe8210000 0x209c>; + compatible = "renesas,r7s72100-ceu"; + interrupts = <GIC_SPI 332 IRQ_TYPE_LEVEL_HIGH>; + + port { + ceu_in: endpoint { + remote-endpoint = <&ov7670_out>; + hsync-active = <1>; + vsync-active = <0>; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/media/renesas,csi2.txt b/Documentation/devicetree/bindings/media/renesas,csi2.txt deleted file mode 100644 index 2da6f60b2b56..000000000000 --- a/Documentation/devicetree/bindings/media/renesas,csi2.txt +++ /dev/null @@ -1,107 +0,0 @@ -Renesas R-Car MIPI CSI-2 ------------------------- - -The R-Car CSI-2 receiver device provides MIPI CSI-2 capabilities for the -Renesas R-Car and RZ/G2 family of devices. It is used in conjunction with the -R-Car VIN module, which provides the video capture capabilities. - -Mandatory properties --------------------- - - compatible: Must be one or more of the following - - "renesas,r8a774a1-csi2" for the R8A774A1 device. - - "renesas,r8a774b1-csi2" for the R8A774B1 device. - - "renesas,r8a774c0-csi2" for the R8A774C0 device. - - "renesas,r8a7795-csi2" for the R8A7795 device. - - "renesas,r8a7796-csi2" for the R8A7796 device. - - "renesas,r8a77965-csi2" for the R8A77965 device. - - "renesas,r8a77970-csi2" for the R8A77970 device. - - "renesas,r8a77980-csi2" for the R8A77980 device. - - "renesas,r8a77990-csi2" for the R8A77990 device. - - - reg: the register base and size for the device registers - - interrupts: the interrupt for the device - - clocks: A phandle + clock specifier for the module clock - - resets: A phandle + reset specifier for the module reset - -The device node shall contain two 'port' child nodes according to the -bindings defined in Documentation/devicetree/bindings/media/ -video-interfaces.txt. port@0 shall connect to the CSI-2 source. port@1 -shall connect to all the R-Car VIN modules that have a hardware -connection to the CSI-2 receiver. - -- port@0- Video source (mandatory) - - endpoint@0 - sub-node describing the endpoint that is the video source - -- port@1 - VIN instances (optional) - - One endpoint sub-node for every R-Car VIN instance which is connected - to the R-Car CSI-2 receiver. - -Example: - - csi20: csi2@fea80000 { - compatible = "renesas,r8a7796-csi2"; - reg = <0 0xfea80000 0 0x10000>; - interrupts = <0 184 IRQ_TYPE_LEVEL_HIGH>; - clocks = <&cpg CPG_MOD 714>; - power-domains = <&sysc R8A7796_PD_ALWAYS_ON>; - resets = <&cpg 714>; - - ports { - #address-cells = <1>; - #size-cells = <0>; - - port@0 { - #address-cells = <1>; - #size-cells = <0>; - - reg = <0>; - - csi20_in: endpoint@0 { - reg = <0>; - clock-lanes = <0>; - data-lanes = <1>; - remote-endpoint = <&adv7482_txb>; - }; - }; - - port@1 { - #address-cells = <1>; - #size-cells = <0>; - - reg = <1>; - - csi20vin0: endpoint@0 { - reg = <0>; - remote-endpoint = <&vin0csi20>; - }; - csi20vin1: endpoint@1 { - reg = <1>; - remote-endpoint = <&vin1csi20>; - }; - csi20vin2: endpoint@2 { - reg = <2>; - remote-endpoint = <&vin2csi20>; - }; - csi20vin3: endpoint@3 { - reg = <3>; - remote-endpoint = <&vin3csi20>; - }; - csi20vin4: endpoint@4 { - reg = <4>; - remote-endpoint = <&vin4csi20>; - }; - csi20vin5: endpoint@5 { - reg = <5>; - remote-endpoint = <&vin5csi20>; - }; - csi20vin6: endpoint@6 { - reg = <6>; - remote-endpoint = <&vin6csi20>; - }; - csi20vin7: endpoint@7 { - reg = <7>; - remote-endpoint = <&vin7csi20>; - }; - }; - }; - }; diff --git a/Documentation/devicetree/bindings/media/renesas,csi2.yaml b/Documentation/devicetree/bindings/media/renesas,csi2.yaml new file mode 100644 index 000000000000..408442a0c389 --- /dev/null +++ b/Documentation/devicetree/bindings/media/renesas,csi2.yaml @@ -0,0 +1,198 @@ +# SPDX-License-Identifier: GPL-2.0-only +# Copyright (C) 2020 Renesas Electronics Corp. +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/media/renesas,csi2.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Renesas R-Car MIPI CSI-2 receiver + +maintainers: + - Niklas Söderlund <niklas.soderlund@ragnatech.se> + +description: + The R-Car CSI-2 receiver device provides MIPI CSI-2 capabilities for the + Renesas R-Car and RZ/G2 family of devices. It is used in conjunction with the + R-Car VIN module, which provides the video capture capabilities. + +properties: + compatible: + items: + - enum: + - renesas,r8a774a1-csi2 # RZ/G2M + - renesas,r8a774b1-csi2 # RZ/G2N + - renesas,r8a774c0-csi2 # RZ/G2E + - renesas,r8a7795-csi2 # R-Car H3 + - renesas,r8a7796-csi2 # R-Car M3-W + - renesas,r8a77965-csi2 # R-Car M3-N + - renesas,r8a77970-csi2 # R-Car V3M + - renesas,r8a77980-csi2 # R-Car V3H + - renesas,r8a77990-csi2 # R-Car E3 + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + clocks: + maxItems: 1 + + power-domains: + maxItems: 1 + + resets: + maxItems: 1 + + ports: + type: object + description: + A node containing input and output port nodes with endpoint definitions + as documented in + Documentation/devicetree/bindings/media/video-interfaces.txt + + properties: + port@0: + type: object + description: + Input port node, single endpoint describing the CSI-2 transmitter. + + properties: + reg: + const: 0 + + endpoint: + type: object + + properties: + clock-lanes: + maxItems: 1 + + data-lanes: + maxItems: 1 + + remote-endpoint: true + + required: + - clock-lanes + - data-lanes + - remote-endpoint + + additionalProperties: false + + additionalProperties: false + + port@1: + type: object + description: + Output port node, multiple endpoints describing all the R-Car VIN + modules connected the CSI-2 receiver. + + properties: + '#address-cells': + const: 1 + + '#size-cells': + const: 0 + + reg: + const: 1 + + patternProperties: + "^endpoint@[0-9a-f]$": + type: object + + properties: + reg: + maxItems: 1 + + remote-endpoint: true + + required: + - reg + - remote-endpoint + + additionalProperties: false + + additionalProperties: false + +required: + - compatible + - reg + - interrupts + - clocks + - power-domains + - resets + - ports + +additionalProperties: false + +examples: + - | + #include <dt-bindings/clock/r8a7796-cpg-mssr.h> + #include <dt-bindings/interrupt-controller/arm-gic.h> + #include <dt-bindings/power/r8a7796-sysc.h> + + csi20: csi2@fea80000 { + compatible = "renesas,r8a7796-csi2"; + reg = <0 0xfea80000 0 0x10000>; + interrupts = <0 184 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&cpg CPG_MOD 714>; + power-domains = <&sysc R8A7796_PD_ALWAYS_ON>; + resets = <&cpg 714>; + + ports { + #address-cells = <1>; + #size-cells = <0>; + + port@0 { + reg = <0>; + + csi20_in: endpoint { + clock-lanes = <0>; + data-lanes = <1>; + remote-endpoint = <&adv7482_txb>; + }; + }; + + port@1 { + #address-cells = <1>; + #size-cells = <0>; + + reg = <1>; + + csi20vin0: endpoint@0 { + reg = <0>; + remote-endpoint = <&vin0csi20>; + }; + csi20vin1: endpoint@1 { + reg = <1>; + remote-endpoint = <&vin1csi20>; + }; + csi20vin2: endpoint@2 { + reg = <2>; + remote-endpoint = <&vin2csi20>; + }; + csi20vin3: endpoint@3 { + reg = <3>; + remote-endpoint = <&vin3csi20>; + }; + csi20vin4: endpoint@4 { + reg = <4>; + remote-endpoint = <&vin4csi20>; + }; + csi20vin5: endpoint@5 { + reg = <5>; + remote-endpoint = <&vin5csi20>; + }; + csi20vin6: endpoint@6 { + reg = <6>; + remote-endpoint = <&vin6csi20>; + }; + csi20vin7: endpoint@7 { + reg = <7>; + remote-endpoint = <&vin7csi20>; + }; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/media/renesas,vin.txt b/Documentation/devicetree/bindings/media/renesas,vin.txt index e30b0d4eefdd..5eefd62ac5c5 100644 --- a/Documentation/devicetree/bindings/media/renesas,vin.txt +++ b/Documentation/devicetree/bindings/media/renesas,vin.txt @@ -13,6 +13,7 @@ on Gen3 and RZ/G2 platforms to a CSI-2 receiver. - "renesas,vin-r8a7743" for the R8A7743 device - "renesas,vin-r8a7744" for the R8A7744 device - "renesas,vin-r8a7745" for the R8A7745 device + - "renesas,vin-r8a77470" for the R8A77470 device - "renesas,vin-r8a774a1" for the R8A774A1 device - "renesas,vin-r8a774b1" for the R8A774B1 device - "renesas,vin-r8a774c0" for the R8A774C0 device @@ -41,9 +42,6 @@ on Gen3 and RZ/G2 platforms to a CSI-2 receiver. - interrupts: the interrupt for the device - clocks: Reference to the parent clock -Additionally, an alias named vinX will need to be created to specify -which video input device this is. - The per-board settings for Gen2 and RZ/G1 platforms: - port - sub-node describing a single endpoint connected to the VIN diff --git a/Documentation/devicetree/bindings/media/samsung-fimc.txt b/Documentation/devicetree/bindings/media/samsung-fimc.txt index 48c599dacbdf..f91b9dc80eb3 100644 --- a/Documentation/devicetree/bindings/media/samsung-fimc.txt +++ b/Documentation/devicetree/bindings/media/samsung-fimc.txt @@ -1,4 +1,4 @@ -Samsung S5P/EXYNOS SoC Camera Subsystem (FIMC) +Samsung S5P/Exynos SoC Camera Subsystem (FIMC) ---------------------------------------------- The S5P/Exynos SoC Camera subsystem comprises of multiple sub-devices diff --git a/Documentation/devicetree/bindings/media/samsung-mipi-csis.txt b/Documentation/devicetree/bindings/media/samsung-mipi-csis.txt index be45f0b1a449..a4149c9434ea 100644 --- a/Documentation/devicetree/bindings/media/samsung-mipi-csis.txt +++ b/Documentation/devicetree/bindings/media/samsung-mipi-csis.txt @@ -1,4 +1,4 @@ -Samsung S5P/EXYNOS SoC series MIPI CSI-2 receiver (MIPI CSIS) +Samsung S5P/Exynos SoC series MIPI CSI-2 receiver (MIPI CSIS) ------------------------------------------------------------- Required properties: diff --git a/Documentation/devicetree/bindings/media/sun6i-csi.txt b/Documentation/devicetree/bindings/media/sun6i-csi.txt deleted file mode 100644 index a2e3e56f0257..000000000000 --- a/Documentation/devicetree/bindings/media/sun6i-csi.txt +++ /dev/null @@ -1,61 +0,0 @@ -Allwinner V3s Camera Sensor Interface -------------------------------------- - -Allwinner V3s SoC features a CSI module(CSI1) with parallel interface. - -Required properties: - - compatible: value must be one of: - * "allwinner,sun6i-a31-csi" - * "allwinner,sun8i-a83t-csi" - * "allwinner,sun8i-h3-csi" - * "allwinner,sun8i-v3s-csi" - * "allwinner,sun50i-a64-csi" - - reg: base address and size of the memory-mapped region. - - interrupts: interrupt associated to this IP - - clocks: phandles to the clocks feeding the CSI - * bus: the CSI interface clock - * mod: the CSI module clock - * ram: the CSI DRAM clock - - clock-names: the clock names mentioned above - - resets: phandles to the reset line driving the CSI - -The CSI 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. - -Endpoint node properties for CSI ---------------------------------- -See the video-interfaces.txt for a detailed description of these properties. -- remote-endpoint : (required) a phandle to the bus receiver's endpoint - node -- bus-width: : (required) must be 8, 10, 12 or 16 -- pclk-sample : (optional) (default: sample on falling edge) -- hsync-active : (required; parallel-only) -- vsync-active : (required; parallel-only) - -Example: - -csi1: csi@1cb4000 { - compatible = "allwinner,sun8i-v3s-csi"; - reg = <0x01cb4000 0x1000>; - interrupts = <GIC_SPI 84 IRQ_TYPE_LEVEL_HIGH>; - clocks = <&ccu CLK_BUS_CSI>, - <&ccu CLK_CSI1_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 */ - }; - }; -}; diff --git a/Documentation/devicetree/bindings/media/ti,cal.yaml b/Documentation/devicetree/bindings/media/ti,cal.yaml new file mode 100644 index 000000000000..1ea784179536 --- /dev/null +++ b/Documentation/devicetree/bindings/media/ti,cal.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/ti,cal.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Texas Instruments DRA72x CAMERA ADAPTATION LAYER (CAL) Device Tree Bindings + +maintainers: + - Benoit Parrot <bparrot@ti.com> + +description: |- + The Camera Adaptation Layer (CAL) is a key component for image capture + applications. The capture module provides the system interface and the + processing capability to connect CSI2 image-sensor modules to the + DRA72x device. + + CAL supports 2 camera port nodes on MIPI bus. Each CSI2 camera port nodes + should contain a 'port' child node with child 'endpoint' node. Please + refer to the bindings defined in + Documentation/devicetree/bindings/media/video-interfaces.txt. + +properties: + compatible: + enum: + # for DRA72 controllers + - ti,dra72-cal + # for DRA72 controllers pre ES2.0 + - ti,dra72-pre-es2-cal + # for DRA76 controllers + - ti,dra76-cal + # for AM654 controllers + - ti,am654-cal + + reg: + minItems: 2 + items: + - description: The CAL main register region + - description: The RX Core0 (DPHY0) register region + - description: The RX Core1 (DPHY1) register region + + reg-names: + minItems: 2 + items: + - const: cal_top + - const: cal_rx_core0 + - const: cal_rx_core1 + + interrupts: + maxItems: 1 + + ti,camerrx-control: + $ref: "/schemas/types.yaml#/definitions/phandle-array" + description: + phandle to the device control module and offset to the + control_camerarx_core register + + clocks: + maxItems: 1 + + clock-names: + const: fck + + power-domains: + description: + List of phandle and PM domain specifier as documented in + Documentation/devicetree/bindings/power/power_domain.txt + maxItems: 1 + + # See ./video-interfaces.txt for details + ports: + type: object + additionalProperties: false + + properties: + "#address-cells": + const: 1 + + "#size-cells": + const: 0 + + port@0: + type: object + additionalProperties: false + + properties: + reg: + const: 0 + description: CSI2 Port #0 + + patternProperties: + endpoint: + type: object + additionalProperties: false + + properties: + clock-lanes: + maxItems: 1 + + data-lanes: + minItems: 1 + maxItems: 4 + + remote-endpoint: true + + required: + - reg + + port@1: + type: object + additionalProperties: false + + properties: + reg: + const: 1 + description: CSI2 Port #1 + + patternProperties: + endpoint: + type: object + additionalProperties: false + + properties: + clock-lanes: + maxItems: 1 + + data-lanes: + minItems: 1 + maxItems: 4 + + remote-endpoint: true + + required: + - reg + + required: + - "#address-cells" + - "#size-cells" + - port@0 + +required: + - compatible + - reg + - reg-names + - interrupts + - ti,camerrx-control + +additionalProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/arm-gic.h> + + cal: cal@4845b000 { + compatible = "ti,dra72-cal"; + reg = <0x4845B000 0x400>, + <0x4845B800 0x40>, + <0x4845B900 0x40>; + reg-names = "cal_top", + "cal_rx_core0", + "cal_rx_core1"; + interrupts = <GIC_SPI 119 IRQ_TYPE_LEVEL_HIGH>; + ti,camerrx-control = <&scm_conf 0xE94>; + + ports { + #address-cells = <1>; + #size-cells = <0>; + + csi2_0: port@0 { + reg = <0>; + csi2_phy0: endpoint { + remote-endpoint = <&csi2_cam0>; + clock-lanes = <0>; + data-lanes = <1 2>; + }; + }; + }; + }; + + i2c5: i2c@4807c000 { + clock-frequency = <400000>; + #address-cells = <1>; + #size-cells = <0>; + + camera-sensor@3c { + compatible = "ovti,ov5640"; + reg = <0x3c>; + + clocks = <&clk_ov5640_fixed>; + clock-names = "xclk"; + + port { + csi2_cam0: endpoint { + remote-endpoint = <&csi2_phy0>; + clock-lanes = <0>; + data-lanes = <1 2>; + }; + }; + }; + }; + +... diff --git a/Documentation/devicetree/bindings/media/ti-cal.txt b/Documentation/devicetree/bindings/media/ti-cal.txt deleted file mode 100644 index ae9b52f37576..000000000000 --- a/Documentation/devicetree/bindings/media/ti-cal.txt +++ /dev/null @@ -1,72 +0,0 @@ -Texas Instruments DRA72x CAMERA ADAPTATION LAYER (CAL) ------------------------------------------------------- - -The Camera Adaptation Layer (CAL) is a key component for image capture -applications. The capture module provides the system interface and the -processing capability to connect CSI2 image-sensor modules to the -DRA72x device. - -Required properties: -- compatible: must be "ti,dra72-cal" -- reg: CAL Top level, Receiver Core #0, Receiver Core #1 and Camera RX - control address space -- reg-names: cal_top, cal_rx_core0, cal_rx_core1, and camerrx_control - registers -- interrupts: should contain IRQ line for the CAL; - -CAL supports 2 camera port nodes on MIPI bus. Each CSI2 camera port nodes -should contain a 'port' child node with child 'endpoint' node. Please -refer to the bindings defined in -Documentation/devicetree/bindings/media/video-interfaces.txt. - -Example: - cal: cal@4845b000 { - compatible = "ti,dra72-cal"; - ti,hwmods = "cal"; - reg = <0x4845B000 0x400>, - <0x4845B800 0x40>, - <0x4845B900 0x40>, - <0x4A002e94 0x4>; - reg-names = "cal_top", - "cal_rx_core0", - "cal_rx_core1", - "camerrx_control"; - interrupts = <GIC_SPI 119 IRQ_TYPE_LEVEL_HIGH>; - #address-cells = <1>; - #size-cells = <0>; - - ports { - #address-cells = <1>; - #size-cells = <0>; - - csi2_0: port@0 { - reg = <0>; - endpoint { - slave-mode; - remote-endpoint = <&ar0330_1>; - }; - }; - csi2_1: port@1 { - reg = <1>; - }; - }; - }; - - i2c5: i2c@4807c000 { - ar0330@10 { - compatible = "ti,ar0330"; - reg = <0x10>; - - port { - #address-cells = <1>; - #size-cells = <0>; - - ar0330_1: endpoint { - reg = <0>; - clock-lanes = <1>; - data-lanes = <0 2 3 4>; - remote-endpoint = <&csi2_0>; - }; - }; - }; - }; diff --git a/Documentation/devicetree/bindings/memory-controllers/fsl/imx8m-ddrc.yaml b/Documentation/devicetree/bindings/memory-controllers/fsl/imx8m-ddrc.yaml new file mode 100644 index 000000000000..c9e6c22cb5be --- /dev/null +++ b/Documentation/devicetree/bindings/memory-controllers/fsl/imx8m-ddrc.yaml @@ -0,0 +1,72 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/memory-controllers/fsl/imx8m-ddrc.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: i.MX8M DDR Controller + +maintainers: + - Leonard Crestez <leonard.crestez@nxp.com> + +description: + The DDRC block is integrated in i.MX8M for interfacing with DDR based + memories. + + It supports switching between different frequencies at runtime but during + this process RAM itself becomes briefly inaccessible so actual frequency + switching is implemented by TF-A code which runs from a SRAM area. + + The Linux driver for the DDRC doesn't even map registers (they're included + for the sake of "describing hardware"), it mostly just exposes firmware + capabilities through standard Linux mechanism like devfreq and OPP tables. + +properties: + compatible: + items: + - enum: + - fsl,imx8mn-ddrc + - fsl,imx8mm-ddrc + - fsl,imx8mq-ddrc + - const: fsl,imx8m-ddrc + + reg: + maxItems: 1 + description: + Base address and size of DDRC CTL area. + This is not currently mapped by the imx8m-ddrc driver. + + clocks: + maxItems: 4 + + clock-names: + items: + - const: core + - const: pll + - const: alt + - const: apb + + operating-points-v2: true + opp-table: true + +required: + - reg + - compatible + - clocks + - clock-names + +additionalProperties: false + +examples: + - | + #include <dt-bindings/clock/imx8mm-clock.h> + ddrc: memory-controller@3d400000 { + compatible = "fsl,imx8mm-ddrc", "fsl,imx8m-ddrc"; + reg = <0x3d400000 0x400000>; + clock-names = "core", "pll", "alt", "apb"; + clocks = <&clk IMX8MM_CLK_DRAM_CORE>, + <&clk IMX8MM_DRAM_PLL>, + <&clk IMX8MM_CLK_DRAM_ALT>, + <&clk IMX8MM_CLK_DRAM_APB>; + operating-points-v2 = <&ddrc_opp_table>; + }; diff --git a/Documentation/devicetree/bindings/memory-controllers/nvidia,tegra124-emc.txt b/Documentation/devicetree/bindings/memory-controllers/nvidia,tegra124-emc.txt deleted file mode 100644 index ba0bc3f12419..000000000000 --- a/Documentation/devicetree/bindings/memory-controllers/nvidia,tegra124-emc.txt +++ /dev/null @@ -1,374 +0,0 @@ -NVIDIA Tegra124 SoC EMC (external memory controller) -==================================================== - -Required properties : -- compatible : Should be "nvidia,tegra124-emc". -- reg : physical base address and length of the controller's registers. -- nvidia,memory-controller : phandle of the MC driver. - -The node should contain a "emc-timings" subnode for each supported RAM type -(see field RAM_CODE in register PMC_STRAPPING_OPT_A), with its unit address -being its RAM_CODE. - -Required properties for "emc-timings" nodes : -- nvidia,ram-code : Should contain the value of RAM_CODE this timing set is -used for. - -Each "emc-timings" node should contain a "timing" subnode for every supported -EMC clock rate. The "timing" subnodes should have the clock rate in Hz as -their unit address. - -Required properties for "timing" nodes : -- clock-frequency : Should contain the memory clock rate in Hz. -- The following properties contain EMC timing characterization values -(specified in the board documentation) : - - nvidia,emc-auto-cal-config : EMC_AUTO_CAL_CONFIG - - nvidia,emc-auto-cal-config2 : EMC_AUTO_CAL_CONFIG2 - - nvidia,emc-auto-cal-config3 : EMC_AUTO_CAL_CONFIG3 - - nvidia,emc-auto-cal-interval : EMC_AUTO_CAL_INTERVAL - - nvidia,emc-bgbias-ctl0 : EMC_BGBIAS_CTL0 - - nvidia,emc-cfg : EMC_CFG - - nvidia,emc-cfg-2 : EMC_CFG_2 - - nvidia,emc-ctt-term-ctrl : EMC_CTT_TERM_CTRL - - nvidia,emc-mode-1 : Mode Register 1 - - nvidia,emc-mode-2 : Mode Register 2 - - nvidia,emc-mode-4 : Mode Register 4 - - nvidia,emc-mode-reset : Mode Register 0 - - nvidia,emc-mrs-wait-cnt : EMC_MRS_WAIT_CNT - - nvidia,emc-sel-dpd-ctrl : EMC_SEL_DPD_CTRL - - nvidia,emc-xm2dqspadctrl2 : EMC_XM2DQSPADCTRL2 - - nvidia,emc-zcal-cnt-long : EMC_ZCAL_WAIT_CNT after clock change - - nvidia,emc-zcal-interval : EMC_ZCAL_INTERVAL -- nvidia,emc-configuration : EMC timing characterization data. These are the -registers (see section "15.6.2 EMC Registers" in the TRM) whose values need to -be specified, according to the board documentation: - - EMC_RC - EMC_RFC - EMC_RFC_SLR - EMC_RAS - EMC_RP - EMC_R2W - EMC_W2R - EMC_R2P - EMC_W2P - EMC_RD_RCD - EMC_WR_RCD - EMC_RRD - EMC_REXT - EMC_WEXT - EMC_WDV - EMC_WDV_MASK - EMC_QUSE - EMC_QUSE_WIDTH - EMC_IBDLY - EMC_EINPUT - EMC_EINPUT_DURATION - EMC_PUTERM_EXTRA - EMC_PUTERM_WIDTH - EMC_PUTERM_ADJ - EMC_CDB_CNTL_1 - EMC_CDB_CNTL_2 - EMC_CDB_CNTL_3 - EMC_QRST - EMC_QSAFE - EMC_RDV - EMC_RDV_MASK - EMC_REFRESH - EMC_BURST_REFRESH_NUM - EMC_PRE_REFRESH_REQ_CNT - EMC_PDEX2WR - EMC_PDEX2RD - EMC_PCHG2PDEN - EMC_ACT2PDEN - EMC_AR2PDEN - EMC_RW2PDEN - EMC_TXSR - EMC_TXSRDLL - EMC_TCKE - EMC_TCKESR - EMC_TPD - EMC_TFAW - EMC_TRPAB - EMC_TCLKSTABLE - EMC_TCLKSTOP - EMC_TREFBW - EMC_FBIO_CFG6 - EMC_ODT_WRITE - EMC_ODT_READ - EMC_FBIO_CFG5 - EMC_CFG_DIG_DLL - EMC_CFG_DIG_DLL_PERIOD - EMC_DLL_XFORM_DQS0 - EMC_DLL_XFORM_DQS1 - EMC_DLL_XFORM_DQS2 - EMC_DLL_XFORM_DQS3 - EMC_DLL_XFORM_DQS4 - EMC_DLL_XFORM_DQS5 - EMC_DLL_XFORM_DQS6 - EMC_DLL_XFORM_DQS7 - EMC_DLL_XFORM_DQS8 - EMC_DLL_XFORM_DQS9 - EMC_DLL_XFORM_DQS10 - EMC_DLL_XFORM_DQS11 - EMC_DLL_XFORM_DQS12 - EMC_DLL_XFORM_DQS13 - EMC_DLL_XFORM_DQS14 - EMC_DLL_XFORM_DQS15 - EMC_DLL_XFORM_QUSE0 - EMC_DLL_XFORM_QUSE1 - EMC_DLL_XFORM_QUSE2 - EMC_DLL_XFORM_QUSE3 - EMC_DLL_XFORM_QUSE4 - EMC_DLL_XFORM_QUSE5 - EMC_DLL_XFORM_QUSE6 - EMC_DLL_XFORM_QUSE7 - EMC_DLL_XFORM_ADDR0 - EMC_DLL_XFORM_ADDR1 - EMC_DLL_XFORM_ADDR2 - EMC_DLL_XFORM_ADDR3 - EMC_DLL_XFORM_ADDR4 - EMC_DLL_XFORM_ADDR5 - EMC_DLL_XFORM_QUSE8 - EMC_DLL_XFORM_QUSE9 - EMC_DLL_XFORM_QUSE10 - EMC_DLL_XFORM_QUSE11 - EMC_DLL_XFORM_QUSE12 - EMC_DLL_XFORM_QUSE13 - EMC_DLL_XFORM_QUSE14 - EMC_DLL_XFORM_QUSE15 - EMC_DLI_TRIM_TXDQS0 - EMC_DLI_TRIM_TXDQS1 - EMC_DLI_TRIM_TXDQS2 - EMC_DLI_TRIM_TXDQS3 - EMC_DLI_TRIM_TXDQS4 - EMC_DLI_TRIM_TXDQS5 - EMC_DLI_TRIM_TXDQS6 - EMC_DLI_TRIM_TXDQS7 - EMC_DLI_TRIM_TXDQS8 - EMC_DLI_TRIM_TXDQS9 - EMC_DLI_TRIM_TXDQS10 - EMC_DLI_TRIM_TXDQS11 - EMC_DLI_TRIM_TXDQS12 - EMC_DLI_TRIM_TXDQS13 - EMC_DLI_TRIM_TXDQS14 - EMC_DLI_TRIM_TXDQS15 - EMC_DLL_XFORM_DQ0 - EMC_DLL_XFORM_DQ1 - EMC_DLL_XFORM_DQ2 - EMC_DLL_XFORM_DQ3 - EMC_DLL_XFORM_DQ4 - EMC_DLL_XFORM_DQ5 - EMC_DLL_XFORM_DQ6 - EMC_DLL_XFORM_DQ7 - EMC_XM2CMDPADCTRL - EMC_XM2CMDPADCTRL4 - EMC_XM2CMDPADCTRL5 - EMC_XM2DQPADCTRL2 - EMC_XM2DQPADCTRL3 - EMC_XM2CLKPADCTRL - EMC_XM2CLKPADCTRL2 - EMC_XM2COMPPADCTRL - EMC_XM2VTTGENPADCTRL - EMC_XM2VTTGENPADCTRL2 - EMC_XM2VTTGENPADCTRL3 - EMC_XM2DQSPADCTRL3 - EMC_XM2DQSPADCTRL4 - EMC_XM2DQSPADCTRL5 - EMC_XM2DQSPADCTRL6 - EMC_DSR_VTTGEN_DRV - EMC_TXDSRVTTGEN - EMC_FBIO_SPARE - EMC_ZCAL_WAIT_CNT - EMC_MRS_WAIT_CNT2 - EMC_CTT - EMC_CTT_DURATION - EMC_CFG_PIPE - EMC_DYN_SELF_REF_CONTROL - EMC_QPOP - -Example SoC include file: - -/ { - emc@7001b000 { - compatible = "nvidia,tegra124-emc"; - reg = <0x0 0x7001b000 0x0 0x1000>; - - nvidia,memory-controller = <&mc>; - }; -}; - -Example board file: - -/ { - emc@7001b000 { - emc-timings-3 { - nvidia,ram-code = <3>; - - timing-12750000 { - clock-frequency = <12750000>; - - nvidia,emc-zcal-cnt-long = <0x00000042>; - nvidia,emc-auto-cal-interval = <0x001fffff>; - nvidia,emc-ctt-term-ctrl = <0x00000802>; - nvidia,emc-cfg = <0x73240000>; - nvidia,emc-cfg-2 = <0x000008c5>; - nvidia,emc-sel-dpd-ctrl = <0x00040128>; - nvidia,emc-bgbias-ctl0 = <0x00000008>; - nvidia,emc-auto-cal-config = <0xa1430000>; - nvidia,emc-auto-cal-config2 = <0x00000000>; - nvidia,emc-auto-cal-config3 = <0x00000000>; - nvidia,emc-mode-reset = <0x80001221>; - nvidia,emc-mode-1 = <0x80100003>; - nvidia,emc-mode-2 = <0x80200008>; - nvidia,emc-mode-4 = <0x00000000>; - - nvidia,emc-configuration = < - 0x00000000 /* EMC_RC */ - 0x00000003 /* EMC_RFC */ - 0x00000000 /* EMC_RFC_SLR */ - 0x00000000 /* EMC_RAS */ - 0x00000000 /* EMC_RP */ - 0x00000004 /* EMC_R2W */ - 0x0000000a /* EMC_W2R */ - 0x00000003 /* EMC_R2P */ - 0x0000000b /* EMC_W2P */ - 0x00000000 /* EMC_RD_RCD */ - 0x00000000 /* EMC_WR_RCD */ - 0x00000003 /* EMC_RRD */ - 0x00000003 /* EMC_REXT */ - 0x00000000 /* EMC_WEXT */ - 0x00000006 /* EMC_WDV */ - 0x00000006 /* EMC_WDV_MASK */ - 0x00000006 /* EMC_QUSE */ - 0x00000002 /* EMC_QUSE_WIDTH */ - 0x00000000 /* EMC_IBDLY */ - 0x00000005 /* EMC_EINPUT */ - 0x00000005 /* EMC_EINPUT_DURATION */ - 0x00010000 /* EMC_PUTERM_EXTRA */ - 0x00000003 /* EMC_PUTERM_WIDTH */ - 0x00000000 /* EMC_PUTERM_ADJ */ - 0x00000000 /* EMC_CDB_CNTL_1 */ - 0x00000000 /* EMC_CDB_CNTL_2 */ - 0x00000000 /* EMC_CDB_CNTL_3 */ - 0x00000004 /* EMC_QRST */ - 0x0000000c /* EMC_QSAFE */ - 0x0000000d /* EMC_RDV */ - 0x0000000f /* EMC_RDV_MASK */ - 0x00000060 /* EMC_REFRESH */ - 0x00000000 /* EMC_BURST_REFRESH_NUM */ - 0x00000018 /* EMC_PRE_REFRESH_REQ_CNT */ - 0x00000002 /* EMC_PDEX2WR */ - 0x00000002 /* EMC_PDEX2RD */ - 0x00000001 /* EMC_PCHG2PDEN */ - 0x00000000 /* EMC_ACT2PDEN */ - 0x00000007 /* EMC_AR2PDEN */ - 0x0000000f /* EMC_RW2PDEN */ - 0x00000005 /* EMC_TXSR */ - 0x00000005 /* EMC_TXSRDLL */ - 0x00000004 /* EMC_TCKE */ - 0x00000005 /* EMC_TCKESR */ - 0x00000004 /* EMC_TPD */ - 0x00000000 /* EMC_TFAW */ - 0x00000000 /* EMC_TRPAB */ - 0x00000005 /* EMC_TCLKSTABLE */ - 0x00000005 /* EMC_TCLKSTOP */ - 0x00000064 /* EMC_TREFBW */ - 0x00000000 /* EMC_FBIO_CFG6 */ - 0x00000000 /* EMC_ODT_WRITE */ - 0x00000000 /* EMC_ODT_READ */ - 0x106aa298 /* EMC_FBIO_CFG5 */ - 0x002c00a0 /* EMC_CFG_DIG_DLL */ - 0x00008000 /* EMC_CFG_DIG_DLL_PERIOD */ - 0x00064000 /* EMC_DLL_XFORM_DQS0 */ - 0x00064000 /* EMC_DLL_XFORM_DQS1 */ - 0x00064000 /* EMC_DLL_XFORM_DQS2 */ - 0x00064000 /* EMC_DLL_XFORM_DQS3 */ - 0x00064000 /* EMC_DLL_XFORM_DQS4 */ - 0x00064000 /* EMC_DLL_XFORM_DQS5 */ - 0x00064000 /* EMC_DLL_XFORM_DQS6 */ - 0x00064000 /* EMC_DLL_XFORM_DQS7 */ - 0x00064000 /* EMC_DLL_XFORM_DQS8 */ - 0x00064000 /* EMC_DLL_XFORM_DQS9 */ - 0x00064000 /* EMC_DLL_XFORM_DQS10 */ - 0x00064000 /* EMC_DLL_XFORM_DQS11 */ - 0x00064000 /* EMC_DLL_XFORM_DQS12 */ - 0x00064000 /* EMC_DLL_XFORM_DQS13 */ - 0x00064000 /* EMC_DLL_XFORM_DQS14 */ - 0x00064000 /* EMC_DLL_XFORM_DQS15 */ - 0x00000000 /* EMC_DLL_XFORM_QUSE0 */ - 0x00000000 /* EMC_DLL_XFORM_QUSE1 */ - 0x00000000 /* EMC_DLL_XFORM_QUSE2 */ - 0x00000000 /* EMC_DLL_XFORM_QUSE3 */ - 0x00000000 /* EMC_DLL_XFORM_QUSE4 */ - 0x00000000 /* EMC_DLL_XFORM_QUSE5 */ - 0x00000000 /* EMC_DLL_XFORM_QUSE6 */ - 0x00000000 /* EMC_DLL_XFORM_QUSE7 */ - 0x00000000 /* EMC_DLL_XFORM_ADDR0 */ - 0x00000000 /* EMC_DLL_XFORM_ADDR1 */ - 0x00000000 /* EMC_DLL_XFORM_ADDR2 */ - 0x00000000 /* EMC_DLL_XFORM_ADDR3 */ - 0x00000000 /* EMC_DLL_XFORM_ADDR4 */ - 0x00000000 /* EMC_DLL_XFORM_ADDR5 */ - 0x00000000 /* EMC_DLL_XFORM_QUSE8 */ - 0x00000000 /* EMC_DLL_XFORM_QUSE9 */ - 0x00000000 /* EMC_DLL_XFORM_QUSE10 */ - 0x00000000 /* EMC_DLL_XFORM_QUSE11 */ - 0x00000000 /* EMC_DLL_XFORM_QUSE12 */ - 0x00000000 /* EMC_DLL_XFORM_QUSE13 */ - 0x00000000 /* EMC_DLL_XFORM_QUSE14 */ - 0x00000000 /* EMC_DLL_XFORM_QUSE15 */ - 0x00000000 /* EMC_DLI_TRIM_TXDQS0 */ - 0x00000000 /* EMC_DLI_TRIM_TXDQS1 */ - 0x00000000 /* EMC_DLI_TRIM_TXDQS2 */ - 0x00000000 /* EMC_DLI_TRIM_TXDQS3 */ - 0x00000000 /* EMC_DLI_TRIM_TXDQS4 */ - 0x00000000 /* EMC_DLI_TRIM_TXDQS5 */ - 0x00000000 /* EMC_DLI_TRIM_TXDQS6 */ - 0x00000000 /* EMC_DLI_TRIM_TXDQS7 */ - 0x00000000 /* EMC_DLI_TRIM_TXDQS8 */ - 0x00000000 /* EMC_DLI_TRIM_TXDQS9 */ - 0x00000000 /* EMC_DLI_TRIM_TXDQS10 */ - 0x00000000 /* EMC_DLI_TRIM_TXDQS11 */ - 0x00000000 /* EMC_DLI_TRIM_TXDQS12 */ - 0x00000000 /* EMC_DLI_TRIM_TXDQS13 */ - 0x00000000 /* EMC_DLI_TRIM_TXDQS14 */ - 0x00000000 /* EMC_DLI_TRIM_TXDQS15 */ - 0x000fc000 /* EMC_DLL_XFORM_DQ0 */ - 0x000fc000 /* EMC_DLL_XFORM_DQ1 */ - 0x000fc000 /* EMC_DLL_XFORM_DQ2 */ - 0x000fc000 /* EMC_DLL_XFORM_DQ3 */ - 0x0000fc00 /* EMC_DLL_XFORM_DQ4 */ - 0x0000fc00 /* EMC_DLL_XFORM_DQ5 */ - 0x0000fc00 /* EMC_DLL_XFORM_DQ6 */ - 0x0000fc00 /* EMC_DLL_XFORM_DQ7 */ - 0x10000280 /* EMC_XM2CMDPADCTRL */ - 0x00000000 /* EMC_XM2CMDPADCTRL4 */ - 0x00111111 /* EMC_XM2CMDPADCTRL5 */ - 0x00000000 /* EMC_XM2DQPADCTRL2 */ - 0x00000000 /* EMC_XM2DQPADCTRL3 */ - 0x77ffc081 /* EMC_XM2CLKPADCTRL */ - 0x00000e0e /* EMC_XM2CLKPADCTRL2 */ - 0x81f1f108 /* EMC_XM2COMPPADCTRL */ - 0x07070004 /* EMC_XM2VTTGENPADCTRL */ - 0x0000003f /* EMC_XM2VTTGENPADCTRL2 */ - 0x016eeeee /* EMC_XM2VTTGENPADCTRL3 */ - 0x51451400 /* EMC_XM2DQSPADCTRL3 */ - 0x00514514 /* EMC_XM2DQSPADCTRL4 */ - 0x00514514 /* EMC_XM2DQSPADCTRL5 */ - 0x51451400 /* EMC_XM2DQSPADCTRL6 */ - 0x0000003f /* EMC_DSR_VTTGEN_DRV */ - 0x00000007 /* EMC_TXDSRVTTGEN */ - 0x00000000 /* EMC_FBIO_SPARE */ - 0x00000042 /* EMC_ZCAL_WAIT_CNT */ - 0x000e000e /* EMC_MRS_WAIT_CNT2 */ - 0x00000000 /* EMC_CTT */ - 0x00000003 /* EMC_CTT_DURATION */ - 0x0000f2f3 /* EMC_CFG_PIPE */ - 0x800001c5 /* EMC_DYN_SELF_REF_CONTROL */ - 0x0000000a /* EMC_QPOP */ - >; - }; - }; - }; -}; diff --git a/Documentation/devicetree/bindings/memory-controllers/nvidia,tegra124-emc.yaml b/Documentation/devicetree/bindings/memory-controllers/nvidia,tegra124-emc.yaml new file mode 100644 index 000000000000..3e0a8a92d652 --- /dev/null +++ b/Documentation/devicetree/bindings/memory-controllers/nvidia,tegra124-emc.yaml @@ -0,0 +1,532 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/memory-controllers/nvidia,tegra124-emc.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: NVIDIA Tegra124 SoC External Memory Controller + +maintainers: + - Thierry Reding <thierry.reding@gmail.com> + - Jon Hunter <jonathanh@nvidia.com> + +description: | + The EMC interfaces with the off-chip SDRAM to service the request stream + sent from the memory controller. + +properties: + compatible: + const: nvidia,tegra124-emc + + reg: + maxItems: 1 + + clocks: + items: + - description: external memory clock + + clock-names: + items: + - const: emc + + nvidia,memory-controller: + $ref: /schemas/types.yaml#/definitions/phandle + description: + phandle of the memory controller node + +patternProperties: + "^emc-timings-[0-9]+$": + type: object + properties: + nvidia,ram-code: + $ref: /schemas/types.yaml#/definitions/uint32 + description: + value of the RAM_CODE field in the PMC_STRAPPING_OPT_A register that + this timing set is used for + + patternProperties: + "^timing-[0-9]+$": + type: object + properties: + clock-frequency: + description: + external memory clock rate in Hz + minimum: 1000000 + maximum: 1000000000 + + nvidia,emc-auto-cal-config: + $ref: /schemas/types.yaml#/definitions/uint32 + description: + value of the EMC_AUTO_CAL_CONFIG register for this set of + timings + + nvidia,emc-auto-cal-config2: + $ref: /schemas/types.yaml#/definitions/uint32 + description: + value of the EMC_AUTO_CAL_CONFIG2 register for this set of + timings + + nvidia,emc-auto-cal-config3: + $ref: /schemas/types.yaml#/definitions/uint32 + description: + value of the EMC_AUTO_CAL_CONFIG3 register for this set of + timings + + nvidia,emc-auto-cal-interval: + allOf: + - $ref: /schemas/types.yaml#/definitions/uint32 + description: + pad calibration interval in microseconds + minimum: 0 + maximum: 2097151 + + nvidia,emc-bgbias-ctl0: + $ref: /schemas/types.yaml#/definitions/uint32 + description: + value of the EMC_BGBIAS_CTL0 register for this set of timings + + nvidia,emc-cfg: + $ref: /schemas/types.yaml#/definitions/uint32 + description: + value of the EMC_CFG register for this set of timings + + nvidia,emc-cfg-2: + $ref: /schemas/types.yaml#/definitions/uint32 + description: + value of the EMC_CFG_2 register for this set of timings + + nvidia,emc-ctt-term-ctrl: + $ref: /schemas/types.yaml#/definitions/uint32 + description: + value of the EMC_CTT_TERM_CTRL register for this set of timings + + nvidia,emc-mode-1: + $ref: /schemas/types.yaml#/definitions/uint32 + description: + value of the EMC_MRW register for this set of timings + + nvidia,emc-mode-2: + $ref: /schemas/types.yaml#/definitions/uint32 + description: + value of the EMC_MRW2 register for this set of timings + + nvidia,emc-mode-4: + $ref: /schemas/types.yaml#/definitions/uint32 + description: + value of the EMC_MRW4 register for this set of timings + + nvidia,emc-mode-reset: + $ref: /schemas/types.yaml#/definitions/uint32 + description: + reset value of the EMC_MRS register for this set of timings + + nvidia,emc-mrs-wait-cnt: + $ref: /schemas/types.yaml#/definitions/uint32 + description: + value of the EMR_MRS_WAIT_CNT register for this set of timings + + nvidia,emc-sel-dpd-ctrl: + $ref: /schemas/types.yaml#/definitions/uint32 + description: + value of the EMC_SEL_DPD_CTRL register for this set of timings + + nvidia,emc-xm2dqspadctrl2: + $ref: /schemas/types.yaml#/definitions/uint32 + description: + value of the EMC_XM2DQSPADCTRL2 register for this set of timings + + nvidia,emc-zcal-cnt-long: + allOf: + - $ref: /schemas/types.yaml#/definitions/uint32 + description: + number of EMC clocks to wait before issuing any commands after + clock change + minimum: 0 + maximum: 1023 + + nvidia,emc-zcal-interval: + $ref: /schemas/types.yaml#/definitions/uint32 + description: + value of the EMC_ZCAL_INTERVAL register for this set of timings + + nvidia,emc-configuration: + allOf: + - $ref: /schemas/types.yaml#/definitions/uint32-array + description: + EMC timing characterization data. These are the registers (see + section "15.6.2 EMC Registers" in the TRM) whose values need to + be specified, according to the board documentation. + items: + - description: EMC_RC + - description: EMC_RFC + - description: EMC_RFC_SLR + - description: EMC_RAS + - description: EMC_RP + - description: EMC_R2W + - description: EMC_W2R + - description: EMC_R2P + - description: EMC_W2P + - description: EMC_RD_RCD + - description: EMC_WR_RCD + - description: EMC_RRD + - description: EMC_REXT + - description: EMC_WEXT + - description: EMC_WDV + - description: EMC_WDV_MASK + - description: EMC_QUSE + - description: EMC_QUSE_WIDTH + - description: EMC_IBDLY + - description: EMC_EINPUT + - description: EMC_EINPUT_DURATION + - description: EMC_PUTERM_EXTRA + - description: EMC_PUTERM_WIDTH + - description: EMC_PUTERM_ADJ + - description: EMC_CDB_CNTL_1 + - description: EMC_CDB_CNTL_2 + - description: EMC_CDB_CNTL_3 + - description: EMC_QRST + - description: EMC_QSAFE + - description: EMC_RDV + - description: EMC_RDV_MASK + - description: EMC_REFRESH + - description: EMC_BURST_REFRESH_NUM + - description: EMC_PRE_REFRESH_REQ_CNT + - description: EMC_PDEX2WR + - description: EMC_PDEX2RD + - description: EMC_PCHG2PDEN + - description: EMC_ACT2PDEN + - description: EMC_AR2PDEN + - description: EMC_RW2PDEN + - description: EMC_TXSR + - description: EMC_TXSRDLL + - description: EMC_TCKE + - description: EMC_TCKESR + - description: EMC_TPD + - description: EMC_TFAW + - description: EMC_TRPAB + - description: EMC_TCLKSTABLE + - description: EMC_TCLKSTOP + - description: EMC_TREFBW + - description: EMC_FBIO_CFG6 + - description: EMC_ODT_WRITE + - description: EMC_ODT_READ + - description: EMC_FBIO_CFG5 + - description: EMC_CFG_DIG_DLL + - description: EMC_CFG_DIG_DLL_PERIOD + - description: EMC_DLL_XFORM_DQS0 + - description: EMC_DLL_XFORM_DQS1 + - description: EMC_DLL_XFORM_DQS2 + - description: EMC_DLL_XFORM_DQS3 + - description: EMC_DLL_XFORM_DQS4 + - description: EMC_DLL_XFORM_DQS5 + - description: EMC_DLL_XFORM_DQS6 + - description: EMC_DLL_XFORM_DQS7 + - description: EMC_DLL_XFORM_DQS8 + - description: EMC_DLL_XFORM_DQS9 + - description: EMC_DLL_XFORM_DQS10 + - description: EMC_DLL_XFORM_DQS11 + - description: EMC_DLL_XFORM_DQS12 + - description: EMC_DLL_XFORM_DQS13 + - description: EMC_DLL_XFORM_DQS14 + - description: EMC_DLL_XFORM_DQS15 + - description: EMC_DLL_XFORM_QUSE0 + - description: EMC_DLL_XFORM_QUSE1 + - description: EMC_DLL_XFORM_QUSE2 + - description: EMC_DLL_XFORM_QUSE3 + - description: EMC_DLL_XFORM_QUSE4 + - description: EMC_DLL_XFORM_QUSE5 + - description: EMC_DLL_XFORM_QUSE6 + - description: EMC_DLL_XFORM_QUSE7 + - description: EMC_DLL_XFORM_ADDR0 + - description: EMC_DLL_XFORM_ADDR1 + - description: EMC_DLL_XFORM_ADDR2 + - description: EMC_DLL_XFORM_ADDR3 + - description: EMC_DLL_XFORM_ADDR4 + - description: EMC_DLL_XFORM_ADDR5 + - description: EMC_DLL_XFORM_QUSE8 + - description: EMC_DLL_XFORM_QUSE9 + - description: EMC_DLL_XFORM_QUSE10 + - description: EMC_DLL_XFORM_QUSE11 + - description: EMC_DLL_XFORM_QUSE12 + - description: EMC_DLL_XFORM_QUSE13 + - description: EMC_DLL_XFORM_QUSE14 + - description: EMC_DLL_XFORM_QUSE15 + - description: EMC_DLI_TRIM_TXDQS0 + - description: EMC_DLI_TRIM_TXDQS1 + - description: EMC_DLI_TRIM_TXDQS2 + - description: EMC_DLI_TRIM_TXDQS3 + - description: EMC_DLI_TRIM_TXDQS4 + - description: EMC_DLI_TRIM_TXDQS5 + - description: EMC_DLI_TRIM_TXDQS6 + - description: EMC_DLI_TRIM_TXDQS7 + - description: EMC_DLI_TRIM_TXDQS8 + - description: EMC_DLI_TRIM_TXDQS9 + - description: EMC_DLI_TRIM_TXDQS10 + - description: EMC_DLI_TRIM_TXDQS11 + - description: EMC_DLI_TRIM_TXDQS12 + - description: EMC_DLI_TRIM_TXDQS13 + - description: EMC_DLI_TRIM_TXDQS14 + - description: EMC_DLI_TRIM_TXDQS15 + - description: EMC_DLL_XFORM_DQ0 + - description: EMC_DLL_XFORM_DQ1 + - description: EMC_DLL_XFORM_DQ2 + - description: EMC_DLL_XFORM_DQ3 + - description: EMC_DLL_XFORM_DQ4 + - description: EMC_DLL_XFORM_DQ5 + - description: EMC_DLL_XFORM_DQ6 + - description: EMC_DLL_XFORM_DQ7 + - description: EMC_XM2CMDPADCTRL + - description: EMC_XM2CMDPADCTRL4 + - description: EMC_XM2CMDPADCTRL5 + - description: EMC_XM2DQPADCTRL2 + - description: EMC_XM2DQPADCTRL3 + - description: EMC_XM2CLKPADCTRL + - description: EMC_XM2CLKPADCTRL2 + - description: EMC_XM2COMPPADCTRL + - description: EMC_XM2VTTGENPADCTRL + - description: EMC_XM2VTTGENPADCTRL2 + - description: EMC_XM2VTTGENPADCTRL3 + - description: EMC_XM2DQSPADCTRL3 + - description: EMC_XM2DQSPADCTRL4 + - description: EMC_XM2DQSPADCTRL5 + - description: EMC_XM2DQSPADCTRL6 + - description: EMC_DSR_VTTGEN_DRV + - description: EMC_TXDSRVTTGEN + - description: EMC_FBIO_SPARE + - description: EMC_ZCAL_WAIT_CNT + - description: EMC_MRS_WAIT_CNT2 + - description: EMC_CTT + - description: EMC_CTT_DURATION + - description: EMC_CFG_PIPE + - description: EMC_DYN_SELF_REF_CONTROL + - description: EMC_QPOP + + required: + - clock-frequency + - nvidia,emc-auto-cal-config + - nvidia,emc-auto-cal-config2 + - nvidia,emc-auto-cal-config3 + - nvidia,emc-auto-cal-interval + - nvidia,emc-bgbias-ctl0 + - nvidia,emc-cfg + - nvidia,emc-cfg-2 + - nvidia,emc-ctt-term-ctrl + - nvidia,emc-mode-1 + - nvidia,emc-mode-2 + - nvidia,emc-mode-4 + - nvidia,emc-mode-reset + - nvidia,emc-mrs-wait-cnt + - nvidia,emc-sel-dpd-ctrl + - nvidia,emc-xm2dqspadctrl2 + - nvidia,emc-zcal-cnt-long + - nvidia,emc-zcal-interval + - nvidia,emc-configuration + + additionalProperties: false + +required: + - compatible + - reg + - clocks + - clock-names + - nvidia,memory-controller + +additionalProperties: false + +examples: + - | + #include <dt-bindings/clock/tegra124-car.h> + #include <dt-bindings/interrupt-controller/arm-gic.h> + + mc: memory-controller@70019000 { + compatible = "nvidia,tegra124-mc"; + reg = <0x0 0x70019000 0x0 0x1000>; + clocks = <&tegra_car TEGRA124_CLK_MC>; + clock-names = "mc"; + + interrupts = <GIC_SPI 77 IRQ_TYPE_LEVEL_HIGH>; + + #iommu-cells = <1>; + #reset-cells = <1>; + }; + + external-memory-controller@7001b000 { + compatible = "nvidia,tegra124-emc"; + reg = <0x0 0x7001b000 0x0 0x1000>; + clocks = <&car TEGRA124_CLK_EMC>; + clock-names = "emc"; + + nvidia,memory-controller = <&mc>; + + emc-timings-0 { + nvidia,ram-code = <3>; + + timing-0 { + clock-frequency = <12750000>; + + nvidia,emc-auto-cal-config = <0xa1430000>; + nvidia,emc-auto-cal-config2 = <0x00000000>; + nvidia,emc-auto-cal-config3 = <0x00000000>; + nvidia,emc-auto-cal-interval = <0x001fffff>; + nvidia,emc-bgbias-ctl0 = <0x00000008>; + nvidia,emc-cfg = <0x73240000>; + nvidia,emc-cfg-2 = <0x000008c5>; + nvidia,emc-ctt-term-ctrl = <0x00000802>; + nvidia,emc-mode-1 = <0x80100003>; + nvidia,emc-mode-2 = <0x80200008>; + nvidia,emc-mode-4 = <0x00000000>; + nvidia,emc-mode-reset = <0x80001221>; + nvidia,emc-mrs-wait-cnt = <0x000e000e>; + nvidia,emc-sel-dpd-ctrl = <0x00040128>; + nvidia,emc-xm2dqspadctrl2 = <0x0130b118>; + nvidia,emc-zcal-cnt-long = <0x00000042>; + nvidia,emc-zcal-interval = <0x00000000>; + + nvidia,emc-configuration = < + 0x00000000 /* EMC_RC */ + 0x00000003 /* EMC_RFC */ + 0x00000000 /* EMC_RFC_SLR */ + 0x00000000 /* EMC_RAS */ + 0x00000000 /* EMC_RP */ + 0x00000004 /* EMC_R2W */ + 0x0000000a /* EMC_W2R */ + 0x00000003 /* EMC_R2P */ + 0x0000000b /* EMC_W2P */ + 0x00000000 /* EMC_RD_RCD */ + 0x00000000 /* EMC_WR_RCD */ + 0x00000003 /* EMC_RRD */ + 0x00000003 /* EMC_REXT */ + 0x00000000 /* EMC_WEXT */ + 0x00000006 /* EMC_WDV */ + 0x00000006 /* EMC_WDV_MASK */ + 0x00000006 /* EMC_QUSE */ + 0x00000002 /* EMC_QUSE_WIDTH */ + 0x00000000 /* EMC_IBDLY */ + 0x00000005 /* EMC_EINPUT */ + 0x00000005 /* EMC_EINPUT_DURATION */ + 0x00010000 /* EMC_PUTERM_EXTRA */ + 0x00000003 /* EMC_PUTERM_WIDTH */ + 0x00000000 /* EMC_PUTERM_ADJ */ + 0x00000000 /* EMC_CDB_CNTL_1 */ + 0x00000000 /* EMC_CDB_CNTL_2 */ + 0x00000000 /* EMC_CDB_CNTL_3 */ + 0x00000004 /* EMC_QRST */ + 0x0000000c /* EMC_QSAFE */ + 0x0000000d /* EMC_RDV */ + 0x0000000f /* EMC_RDV_MASK */ + 0x00000060 /* EMC_REFRESH */ + 0x00000000 /* EMC_BURST_REFRESH_NUM */ + 0x00000018 /* EMC_PRE_REFRESH_REQ_CNT */ + 0x00000002 /* EMC_PDEX2WR */ + 0x00000002 /* EMC_PDEX2RD */ + 0x00000001 /* EMC_PCHG2PDEN */ + 0x00000000 /* EMC_ACT2PDEN */ + 0x00000007 /* EMC_AR2PDEN */ + 0x0000000f /* EMC_RW2PDEN */ + 0x00000005 /* EMC_TXSR */ + 0x00000005 /* EMC_TXSRDLL */ + 0x00000004 /* EMC_TCKE */ + 0x00000005 /* EMC_TCKESR */ + 0x00000004 /* EMC_TPD */ + 0x00000000 /* EMC_TFAW */ + 0x00000000 /* EMC_TRPAB */ + 0x00000005 /* EMC_TCLKSTABLE */ + 0x00000005 /* EMC_TCLKSTOP */ + 0x00000064 /* EMC_TREFBW */ + 0x00000000 /* EMC_FBIO_CFG6 */ + 0x00000000 /* EMC_ODT_WRITE */ + 0x00000000 /* EMC_ODT_READ */ + 0x106aa298 /* EMC_FBIO_CFG5 */ + 0x002c00a0 /* EMC_CFG_DIG_DLL */ + 0x00008000 /* EMC_CFG_DIG_DLL_PERIOD */ + 0x00064000 /* EMC_DLL_XFORM_DQS0 */ + 0x00064000 /* EMC_DLL_XFORM_DQS1 */ + 0x00064000 /* EMC_DLL_XFORM_DQS2 */ + 0x00064000 /* EMC_DLL_XFORM_DQS3 */ + 0x00064000 /* EMC_DLL_XFORM_DQS4 */ + 0x00064000 /* EMC_DLL_XFORM_DQS5 */ + 0x00064000 /* EMC_DLL_XFORM_DQS6 */ + 0x00064000 /* EMC_DLL_XFORM_DQS7 */ + 0x00064000 /* EMC_DLL_XFORM_DQS8 */ + 0x00064000 /* EMC_DLL_XFORM_DQS9 */ + 0x00064000 /* EMC_DLL_XFORM_DQS10 */ + 0x00064000 /* EMC_DLL_XFORM_DQS11 */ + 0x00064000 /* EMC_DLL_XFORM_DQS12 */ + 0x00064000 /* EMC_DLL_XFORM_DQS13 */ + 0x00064000 /* EMC_DLL_XFORM_DQS14 */ + 0x00064000 /* EMC_DLL_XFORM_DQS15 */ + 0x00000000 /* EMC_DLL_XFORM_QUSE0 */ + 0x00000000 /* EMC_DLL_XFORM_QUSE1 */ + 0x00000000 /* EMC_DLL_XFORM_QUSE2 */ + 0x00000000 /* EMC_DLL_XFORM_QUSE3 */ + 0x00000000 /* EMC_DLL_XFORM_QUSE4 */ + 0x00000000 /* EMC_DLL_XFORM_QUSE5 */ + 0x00000000 /* EMC_DLL_XFORM_QUSE6 */ + 0x00000000 /* EMC_DLL_XFORM_QUSE7 */ + 0x00000000 /* EMC_DLL_XFORM_ADDR0 */ + 0x00000000 /* EMC_DLL_XFORM_ADDR1 */ + 0x00000000 /* EMC_DLL_XFORM_ADDR2 */ + 0x00000000 /* EMC_DLL_XFORM_ADDR3 */ + 0x00000000 /* EMC_DLL_XFORM_ADDR4 */ + 0x00000000 /* EMC_DLL_XFORM_ADDR5 */ + 0x00000000 /* EMC_DLL_XFORM_QUSE8 */ + 0x00000000 /* EMC_DLL_XFORM_QUSE9 */ + 0x00000000 /* EMC_DLL_XFORM_QUSE10 */ + 0x00000000 /* EMC_DLL_XFORM_QUSE11 */ + 0x00000000 /* EMC_DLL_XFORM_QUSE12 */ + 0x00000000 /* EMC_DLL_XFORM_QUSE13 */ + 0x00000000 /* EMC_DLL_XFORM_QUSE14 */ + 0x00000000 /* EMC_DLL_XFORM_QUSE15 */ + 0x00000000 /* EMC_DLI_TRIM_TXDQS0 */ + 0x00000000 /* EMC_DLI_TRIM_TXDQS1 */ + 0x00000000 /* EMC_DLI_TRIM_TXDQS2 */ + 0x00000000 /* EMC_DLI_TRIM_TXDQS3 */ + 0x00000000 /* EMC_DLI_TRIM_TXDQS4 */ + 0x00000000 /* EMC_DLI_TRIM_TXDQS5 */ + 0x00000000 /* EMC_DLI_TRIM_TXDQS6 */ + 0x00000000 /* EMC_DLI_TRIM_TXDQS7 */ + 0x00000000 /* EMC_DLI_TRIM_TXDQS8 */ + 0x00000000 /* EMC_DLI_TRIM_TXDQS9 */ + 0x00000000 /* EMC_DLI_TRIM_TXDQS10 */ + 0x00000000 /* EMC_DLI_TRIM_TXDQS11 */ + 0x00000000 /* EMC_DLI_TRIM_TXDQS12 */ + 0x00000000 /* EMC_DLI_TRIM_TXDQS13 */ + 0x00000000 /* EMC_DLI_TRIM_TXDQS14 */ + 0x00000000 /* EMC_DLI_TRIM_TXDQS15 */ + 0x000fc000 /* EMC_DLL_XFORM_DQ0 */ + 0x000fc000 /* EMC_DLL_XFORM_DQ1 */ + 0x000fc000 /* EMC_DLL_XFORM_DQ2 */ + 0x000fc000 /* EMC_DLL_XFORM_DQ3 */ + 0x0000fc00 /* EMC_DLL_XFORM_DQ4 */ + 0x0000fc00 /* EMC_DLL_XFORM_DQ5 */ + 0x0000fc00 /* EMC_DLL_XFORM_DQ6 */ + 0x0000fc00 /* EMC_DLL_XFORM_DQ7 */ + 0x10000280 /* EMC_XM2CMDPADCTRL */ + 0x00000000 /* EMC_XM2CMDPADCTRL4 */ + 0x00111111 /* EMC_XM2CMDPADCTRL5 */ + 0x00000000 /* EMC_XM2DQPADCTRL2 */ + 0x00000000 /* EMC_XM2DQPADCTRL3 */ + 0x77ffc081 /* EMC_XM2CLKPADCTRL */ + 0x00000e0e /* EMC_XM2CLKPADCTRL2 */ + 0x81f1f108 /* EMC_XM2COMPPADCTRL */ + 0x07070004 /* EMC_XM2VTTGENPADCTRL */ + 0x0000003f /* EMC_XM2VTTGENPADCTRL2 */ + 0x016eeeee /* EMC_XM2VTTGENPADCTRL3 */ + 0x51451400 /* EMC_XM2DQSPADCTRL3 */ + 0x00514514 /* EMC_XM2DQSPADCTRL4 */ + 0x00514514 /* EMC_XM2DQSPADCTRL5 */ + 0x51451400 /* EMC_XM2DQSPADCTRL6 */ + 0x0000003f /* EMC_DSR_VTTGEN_DRV */ + 0x00000007 /* EMC_TXDSRVTTGEN */ + 0x00000000 /* EMC_FBIO_SPARE */ + 0x00000042 /* EMC_ZCAL_WAIT_CNT */ + 0x000e000e /* EMC_MRS_WAIT_CNT2 */ + 0x00000000 /* EMC_CTT */ + 0x00000003 /* EMC_CTT_DURATION */ + 0x0000f2f3 /* EMC_CFG_PIPE */ + 0x800001c5 /* EMC_DYN_SELF_REF_CONTROL */ + 0x0000000a /* EMC_QPOP */ + >; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/memory-controllers/nvidia,tegra186-mc.yaml b/Documentation/devicetree/bindings/memory-controllers/nvidia,tegra186-mc.yaml new file mode 100644 index 000000000000..12516bd89cf9 --- /dev/null +++ b/Documentation/devicetree/bindings/memory-controllers/nvidia,tegra186-mc.yaml @@ -0,0 +1,130 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/memory-controllers/nvidia,tegra186-mc.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: NVIDIA Tegra186 (and later) SoC Memory Controller + +maintainers: + - Jon Hunter <jonathanh@nvidia.com> + - Thierry Reding <thierry.reding@gmail.com> + +description: | + The NVIDIA Tegra186 SoC features a 128 bit memory controller that is split + into four 32 bit channels to support LPDDR4 with x16 subpartitions. The MC + handles memory requests for 40-bit virtual addresses from internal clients + and arbitrates among them to allocate memory bandwidth. + + Up to 15 GiB of physical memory can be supported. Security features such as + encryption of traffic to and from DRAM via general security apertures are + available for video and other secure applications, as well as DRAM ECC for + automotive safety applications (single bit error correction and double bit + error detection). + +properties: + $nodename: + pattern: "^memory-controller@[0-9a-f]+$" + + compatible: + items: + - enum: + - nvidia,tegra186-mc + - nvidia,tegra194-mc + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + "#address-cells": + const: 2 + + "#size-cells": + const: 2 + + ranges: true + + dma-ranges: true + +patternProperties: + "^external-memory-controller@[0-9a-f]+$": + description: + The bulk of the work involved in controlling the external memory + controller on NVIDIA Tegra186 and later is performed on the BPMP. This + coprocessor exposes the EMC clock that is used to set the frequency at + which the external memory is clocked and a remote procedure call that + can be used to obtain the set of available frequencies. + type: object + properties: + compatible: + items: + - enum: + - nvidia,tegra186-emc + - nvidia,tegra194-emc + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + clocks: + items: + - description: external memory clock + + clock-names: + items: + - const: emc + + nvidia,bpmp: + $ref: /schemas/types.yaml#/definitions/phandle + description: + phandle of the node representing the BPMP + +required: + - compatible + - reg + - interrupts + - "#address-cells" + - "#size-cells" + +additionalProperties: false + +examples: + - | + #include <dt-bindings/clock/tegra186-clock.h> + #include <dt-bindings/interrupt-controller/arm-gic.h> + + memory-controller@2c00000 { + compatible = "nvidia,tegra186-mc"; + reg = <0x0 0x02c00000 0x0 0xb0000>; + interrupts = <GIC_SPI 223 IRQ_TYPE_LEVEL_HIGH>; + + #address-cells = <2>; + #size-cells = <2>; + + ranges = <0x0 0x02c00000 0x02c00000 0x0 0xb0000>; + + /* + * Memory clients have access to all 40 bits that the memory + * controller can address. + */ + dma-ranges = <0x0 0x0 0x0 0x0 0x100 0x0>; + + external-memory-controller@2c60000 { + compatible = "nvidia,tegra186-emc"; + reg = <0x0 0x02c60000 0x0 0x50000>; + interrupts = <GIC_SPI 224 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&bpmp TEGRA186_CLK_EMC>; + clock-names = "emc"; + + nvidia,bpmp = <&bpmp>; + }; + }; + + bpmp: bpmp { + compatible = "nvidia,tegra186-bpmp"; + #clock-cells = <1>; + }; diff --git a/Documentation/devicetree/bindings/mfd/ab8500.txt b/Documentation/devicetree/bindings/mfd/ab8500.txt index b6bc30d7777e..5c6eabeed341 100644 --- a/Documentation/devicetree/bindings/mfd/ab8500.txt +++ b/Documentation/devicetree/bindings/mfd/ab8500.txt @@ -1,7 +1,7 @@ * AB8500 Multi-Functional Device (MFD) Required parent device properties: -- compatible : contains "stericsson,ab8500"; +- compatible : contains "stericsson,ab8500" or "stericsson,ab8505"; - interrupts : contains the IRQ line for the AB8500 - interrupt-controller : describes the AB8500 as an Interrupt Controller (has its own domain) - #interrupt-cells : should be 2, for 2-cell format @@ -49,11 +49,13 @@ ab8500-charger : : vddadc : Charger interface : CH_WD_EXP : : Charger watchdog detected ab8500-gpadc : HW_CONV_END : vddadc : Analogue to Digital Converter SW_CONV_END : : -ab8500-gpio : : : GPIO Controller +ab8500-gpio : : : GPIO Controller (AB8500) +ab8505-gpio : : : GPIO Controller (AB8505) ab8500-ponkey : ONKEY_DBF : : Power-on Key ONKEY_DBR : : ab8500-pwm : : : Pulse Width Modulator -ab8500-regulator : : : Regulators +ab8500-regulator : : : Regulators (AB8500) +ab8505-regulator : : : Regulators (AB8505) ab8500-rtc : 60S : : Real Time Clock : ALARM : : ab8500-sysctrl : : : System Control diff --git a/Documentation/devicetree/bindings/mfd/allwinner,sun6i-a31-prcm.yaml b/Documentation/devicetree/bindings/mfd/allwinner,sun6i-a31-prcm.yaml new file mode 100644 index 000000000000..d131759ccaf3 --- /dev/null +++ b/Documentation/devicetree/bindings/mfd/allwinner,sun6i-a31-prcm.yaml @@ -0,0 +1,219 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/mfd/allwinner,sun6i-a31-prcm.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Allwinner A31 PRCM Device Tree Bindings + +maintainers: + - Chen-Yu Tsai <wens@csie.org> + - Maxime Ripard <mripard@kernel.org> + +deprecated: true + +properties: + compatible: + const: allwinner,sun6i-a31-prcm + + reg: + maxItems: 1 + +patternProperties: + "^.*_(clk|rst)$": + type: object + + properties: + compatible: + enum: + - allwinner,sun4i-a10-mod0-clk + - allwinner,sun6i-a31-apb0-clk + - allwinner,sun6i-a31-apb0-gates-clk + - allwinner,sun6i-a31-ar100-clk + - allwinner,sun6i-a31-clock-reset + - fixed-factor-clock + + allOf: + - if: + properties: + compatible: + contains: + const: allwinner,sun6i-a31-apb0-clk + + then: + properties: + "#clock-cells": + const: 0 + + # Already checked in the main schema + compatible: true + + clocks: + maxItems: 1 + + clock-output-names: + maxItems: 1 + + phandle: true + + required: + - "#clock-cells" + - compatible + - clocks + - clock-output-names + + additionalProperties: false + + - if: + properties: + compatible: + contains: + const: allwinner,sun6i-a31-apb0-gates-clk + + then: + properties: + "#clock-cells": + const: 1 + description: > + This additional argument passed to that clock is the + offset of the bit controlling this particular gate in + the register. + + # Already checked in the main schema + compatible: true + + clocks: + maxItems: 1 + + clock-output-names: + minItems: 1 + maxItems: 32 + + phandle: true + + required: + - "#clock-cells" + - compatible + - clocks + - clock-output-names + + additionalProperties: false + + - if: + properties: + compatible: + contains: + const: allwinner,sun6i-a31-ar100-clk + + then: + properties: + "#clock-cells": + const: 0 + + # Already checked in the main schema + compatible: true + + clocks: + maxItems: 4 + description: > + The parent order must match the hardware programming + order. + + clock-output-names: + maxItems: 1 + + phandle: true + + required: + - "#clock-cells" + - compatible + - clocks + - clock-output-names + + additionalProperties: false + + - if: + properties: + compatible: + contains: + const: allwinner,sun6i-a31-clock-reset + + then: + properties: + "#reset-cells": + const: 1 + + # Already checked in the main schema + compatible: true + + phandle: true + + required: + - "#reset-cells" + - compatible + + additionalProperties: false + +required: + - compatible + - reg + +additionalProperties: false + +examples: + - | + #include <dt-bindings/clock/sun6i-a31-ccu.h> + + prcm@1f01400 { + compatible = "allwinner,sun6i-a31-prcm"; + reg = <0x01f01400 0x200>; + + ar100: ar100_clk { + compatible = "allwinner,sun6i-a31-ar100-clk"; + #clock-cells = <0>; + clocks = <&rtc 0>, <&osc24M>, + <&ccu CLK_PLL_PERIPH>, + <&ccu CLK_PLL_PERIPH>; + clock-output-names = "ar100"; + }; + + ahb0: ahb0_clk { + compatible = "fixed-factor-clock"; + #clock-cells = <0>; + clock-div = <1>; + clock-mult = <1>; + clocks = <&ar100>; + clock-output-names = "ahb0"; + }; + + apb0: apb0_clk { + compatible = "allwinner,sun6i-a31-apb0-clk"; + #clock-cells = <0>; + clocks = <&ahb0>; + clock-output-names = "apb0"; + }; + + apb0_gates: apb0_gates_clk { + compatible = "allwinner,sun6i-a31-apb0-gates-clk"; + #clock-cells = <1>; + clocks = <&apb0>; + clock-output-names = "apb0_pio", "apb0_ir", + "apb0_timer", "apb0_p2wi", + "apb0_uart", "apb0_1wire", + "apb0_i2c"; + }; + + ir_clk: ir_clk { + #clock-cells = <0>; + compatible = "allwinner,sun4i-a10-mod0-clk"; + clocks = <&rtc 0>, <&osc24M>; + clock-output-names = "ir"; + }; + + apb0_rst: apb0_rst { + compatible = "allwinner,sun6i-a31-clock-reset"; + #reset-cells = <1>; + }; + }; + +... diff --git a/Documentation/devicetree/bindings/mfd/allwinner,sun8i-a23-prcm.yaml b/Documentation/devicetree/bindings/mfd/allwinner,sun8i-a23-prcm.yaml new file mode 100644 index 000000000000..aa5e683b236c --- /dev/null +++ b/Documentation/devicetree/bindings/mfd/allwinner,sun8i-a23-prcm.yaml @@ -0,0 +1,200 @@ +# SPDX-License-Identifier: GPL-2.0+ +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/mfd/allwinner,sun8i-a23-prcm.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Allwinner A23 PRCM Device Tree Bindings + +maintainers: + - Chen-Yu Tsai <wens@csie.org> + - Maxime Ripard <mripard@kernel.org> + +deprecated: true + +properties: + compatible: + const: allwinner,sun8i-a23-prcm + + reg: + maxItems: 1 + +patternProperties: + "^.*(clk|rst|codec).*$": + type: object + + properties: + compatible: + enum: + - fixed-factor-clock + - allwinner,sun8i-a23-apb0-clk + - allwinner,sun8i-a23-apb0-gates-clk + - allwinner,sun6i-a31-clock-reset + - allwinner,sun8i-a23-codec-analog + + required: + - compatible + + allOf: + - if: + properties: + compatible: + contains: + const: allwinner,sun8i-a23-apb0-clk + + then: + properties: + "#clock-cells": + const: 0 + + # Already checked in the main schema + compatible: true + + clocks: + maxItems: 1 + + clock-output-names: + maxItems: 1 + + phandle: true + + required: + - "#clock-cells" + - compatible + - clocks + - clock-output-names + + additionalProperties: false + + - if: + properties: + compatible: + contains: + const: allwinner,sun8i-a23-apb0-gates-clk + + then: + properties: + "#clock-cells": + const: 1 + description: > + This additional argument passed to that clock is the + offset of the bit controlling this particular gate in + the register. + + # Already checked in the main schema + compatible: true + + clocks: + maxItems: 1 + + clock-output-names: + minItems: 1 + maxItems: 32 + + phandle: true + + required: + - "#clock-cells" + - compatible + - clocks + - clock-output-names + + additionalProperties: false + + - if: + properties: + compatible: + contains: + const: allwinner,sun6i-a31-clock-reset + + then: + properties: + "#reset-cells": + const: 1 + + # Already checked in the main schema + compatible: true + + phandle: true + + required: + - "#reset-cells" + - compatible + + additionalProperties: false + + - if: + properties: + compatible: + contains: + const: allwinner,sun8i-a23-codec-analog + + then: + properties: + # Already checked in the main schema + compatible: true + + phandle: true + + required: + - compatible + + additionalProperties: false + +required: + - compatible + - reg + +additionalProperties: false + +examples: + - | + prcm@1f01400 { + compatible = "allwinner,sun8i-a23-prcm"; + reg = <0x01f01400 0x200>; + + ar100: ar100_clk { + compatible = "fixed-factor-clock"; + #clock-cells = <0>; + clock-div = <1>; + clock-mult = <1>; + clocks = <&osc24M>; + clock-output-names = "ar100"; + }; + + ahb0: ahb0_clk { + compatible = "fixed-factor-clock"; + #clock-cells = <0>; + clock-div = <1>; + clock-mult = <1>; + clocks = <&ar100>; + clock-output-names = "ahb0"; + }; + + apb0: apb0_clk { + compatible = "allwinner,sun8i-a23-apb0-clk"; + #clock-cells = <0>; + clocks = <&ahb0>; + clock-output-names = "apb0"; + }; + + apb0_gates: apb0_gates_clk { + compatible = "allwinner,sun8i-a23-apb0-gates-clk"; + #clock-cells = <1>; + clocks = <&apb0>; + clock-output-names = "apb0_pio", "apb0_timer", + "apb0_rsb", "apb0_uart", + "apb0_i2c"; + }; + + apb0_rst: apb0_rst { + compatible = "allwinner,sun6i-a31-clock-reset"; + #reset-cells = <1>; + }; + + codec_analog: codec-analog { + compatible = "allwinner,sun8i-a23-codec-analog"; + }; + }; + +... diff --git a/Documentation/devicetree/bindings/mfd/atmel-gpbr.txt b/Documentation/devicetree/bindings/mfd/atmel-gpbr.txt index a28569540683..e8c525569f10 100644 --- a/Documentation/devicetree/bindings/mfd/atmel-gpbr.txt +++ b/Documentation/devicetree/bindings/mfd/atmel-gpbr.txt @@ -3,7 +3,9 @@ The GPBR are a set of battery-backed registers. Required properties: -- compatible: "atmel,at91sam9260-gpbr", "syscon" +- compatible: Should be one of the following: + "atmel,at91sam9260-gpbr", "syscon" + "microchip,sam9x60-gpbr", "syscon" - reg: contains offset/length value of the GPBR memory region. diff --git a/Documentation/devicetree/bindings/mfd/atmel-matrix.txt b/Documentation/devicetree/bindings/mfd/atmel-matrix.txt index e3ef50ca02a5..89d05c64fb01 100644 --- a/Documentation/devicetree/bindings/mfd/atmel-matrix.txt +++ b/Documentation/devicetree/bindings/mfd/atmel-matrix.txt @@ -13,6 +13,7 @@ Required properties: "atmel,at91sam9n12-matrix", "syscon" "atmel,at91sam9x5-matrix", "syscon" "atmel,sama5d3-matrix", "syscon" + "microchip,sam9x60-matrix", "syscon" - reg: Contains offset/length value of the Bus Matrix memory region. diff --git a/Documentation/devicetree/bindings/mfd/atmel-smc.txt b/Documentation/devicetree/bindings/mfd/atmel-smc.txt index 1103ce2030fb..5696d9fcb5dc 100644 --- a/Documentation/devicetree/bindings/mfd/atmel-smc.txt +++ b/Documentation/devicetree/bindings/mfd/atmel-smc.txt @@ -9,6 +9,7 @@ Required properties: "atmel,at91sam9260-smc", "syscon" "atmel,sama5d3-smc", "syscon" "atmel,sama5d2-smc", "syscon" + "microchip,sam9x60-smc", "syscon" - reg: Contains offset/length value of the SMC memory region. diff --git a/Documentation/devicetree/bindings/mfd/atmel-usart.txt b/Documentation/devicetree/bindings/mfd/atmel-usart.txt index 699fd3c9ace8..a09133066aff 100644 --- a/Documentation/devicetree/bindings/mfd/atmel-usart.txt +++ b/Documentation/devicetree/bindings/mfd/atmel-usart.txt @@ -1,10 +1,13 @@ * Atmel Universal Synchronous Asynchronous Receiver/Transmitter (USART) Required properties for USART: -- compatible: Should be "atmel,<chip>-usart" or "atmel,<chip>-dbgu" - The compatible <chip> indicated will be the first SoC to support an - additional mode or an USART new feature. - For the dbgu UART, use "atmel,<chip>-dbgu", "atmel,<chip>-usart" +- compatible: Should be one of the following: + - "atmel,at91rm9200-usart" + - "atmel,at91sam9260-usart" + - "microchip,sam9x60-usart" + - "atmel,at91rm9200-dbgu", "atmel,at91rm9200-usart" + - "atmel,at91sam9260-dbgu", "atmel,at91sam9260-usart" + - "microchip,sam9x60-dbgu", "microchip,sam9x60-usart" - reg: Should contain registers location and length - interrupts: Should contain interrupt - clock-names: tuple listing input clock names. diff --git a/Documentation/devicetree/bindings/mfd/da9062.txt b/Documentation/devicetree/bindings/mfd/da9062.txt index bc4b59de6a55..857af982c88f 100644 --- a/Documentation/devicetree/bindings/mfd/da9062.txt +++ b/Documentation/devicetree/bindings/mfd/da9062.txt @@ -13,6 +13,7 @@ da9062-rtc : : Real-Time Clock da9062-onkey : : On Key da9062-watchdog : : Watchdog Timer da9062-thermal : : Thermal +da9062-gpio : : GPIOs The DA9061 PMIC consists of: @@ -38,6 +39,15 @@ Required properties: See Documentation/devicetree/bindings/interrupt-controller/interrupts.txt for further information on IRQ bindings. +Optional properties: + +- gpio-controller : Marks the device 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. + +See Documentation/devicetree/bindings/gpio/gpio.txt for further information on +GPIO bindings. + Sub-nodes: - regulators : This node defines the settings for the LDOs and BUCKs. diff --git a/Documentation/devicetree/bindings/mfd/max14577.txt b/Documentation/devicetree/bindings/mfd/max14577.txt index fc6f0f4e8beb..92070b346756 100644 --- a/Documentation/devicetree/bindings/mfd/max14577.txt +++ b/Documentation/devicetree/bindings/mfd/max14577.txt @@ -5,6 +5,8 @@ Battery Charger and SFOUT LDO output for powering USB devices. It is interfaced to host controller using I2C. MAX77836 additionally contains PMIC (with two LDO regulators) and Fuel Gauge. +For the description of Fuel Gauge low SOC alert interrupt see: +../power/supply/max17040_battery.txt Required properties: diff --git a/Documentation/devicetree/bindings/mfd/rohm,bd71828-pmic.yaml b/Documentation/devicetree/bindings/mfd/rohm,bd71828-pmic.yaml new file mode 100644 index 000000000000..4fbb9e734284 --- /dev/null +++ b/Documentation/devicetree/bindings/mfd/rohm,bd71828-pmic.yaml @@ -0,0 +1,193 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/mfd/rohm,bd71828-pmic.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: ROHM BD71828 Power Management Integrated Circuit bindings + +maintainers: + - Matti Vaittinen <matti.vaittinen@fi.rohmeurope.com> + +description: | + BD71828GW is a single-chip power management IC for battery-powered portable + devices. The IC integrates 7 buck converters, 7 LDOs, and a 1500 mA + single-cell linear charger. Also included is a Coulomb counter, a real-time + clock (RTC), and a 32.768 kHz clock gate. + +properties: + compatible: + const: rohm,bd71828 + + reg: + description: + I2C slave address. + maxItems: 1 + + interrupts: + maxItems: 1 + + gpio-controller: true + + "#gpio-cells": + const: 2 + description: | + The first cell is the pin number and the second cell is used to specify + flags. See ../gpio/gpio.txt for more information. + + clocks: + maxItems: 1 + + "#clock-cells": + const: 0 + + rohm,charger-sense-resistor-ohms: + minimum: 10000000 + maximum: 50000000 + description: | + BD71827 and BD71828 have SAR ADC for measuring charging currents. + External sense resistor (RSENSE in data sheet) should be used. If some + other but 30MOhm resistor is used the resistance value should be given + here in Ohms. + + regulators: + $ref: ../regulator/rohm,bd71828-regulator.yaml + description: + List of child nodes that specify the regulators. + + leds: + $ref: ../leds/rohm,bd71828-leds.yaml + + gpio-reserved-ranges: + description: | + Usage of BD71828 GPIO pins can be changed via OTP. This property can be + used to mark the pins which should not be configured for GPIO. Please see + the ../gpio/gpio.txt for more information. + +required: + - compatible + - reg + - interrupts + - clocks + - "#clock-cells" + - regulators + - gpio-controller + - "#gpio-cells" + +examples: + - | + #include <dt-bindings/interrupt-controller/irq.h> + #include <dt-bindings/leds/common.h> + i2c { + #address-cells = <1>; + #size-cells = <0>; + pmic: pmic@4b { + compatible = "rohm,bd71828"; + reg = <0x4b>; + + interrupt-parent = <&gpio1>; + interrupts = <29 IRQ_TYPE_LEVEL_LOW>; + + clocks = <&osc 0>; + #clock-cells = <0>; + clock-output-names = "bd71828-32k-out"; + + gpio-controller; + #gpio-cells = <2>; + gpio-reserved-ranges = <0 1>, <2 1>; + + rohm,charger-sense-resistor-ohms = <10000000>; + + regulators { + buck1: BUCK1 { + regulator-name = "buck1"; + regulator-min-microvolt = <500000>; + regulator-max-microvolt = <2000000>; + regulator-ramp-delay = <2500>; + }; + buck2: BUCK2 { + regulator-name = "buck2"; + regulator-min-microvolt = <500000>; + regulator-max-microvolt = <2000000>; + regulator-ramp-delay = <2500>; + }; + buck3: BUCK3 { + regulator-name = "buck3"; + regulator-min-microvolt = <1200000>; + regulator-max-microvolt = <2000000>; + }; + buck4: BUCK4 { + regulator-name = "buck4"; + regulator-min-microvolt = <1000000>; + regulator-max-microvolt = <1800000>; + }; + buck5: BUCK5 { + regulator-name = "buck5"; + regulator-min-microvolt = <2500000>; + regulator-max-microvolt = <3300000>; + }; + buck6: BUCK6 { + regulator-name = "buck6"; + regulator-min-microvolt = <500000>; + regulator-max-microvolt = <2000000>; + regulator-ramp-delay = <2500>; + }; + buck7: BUCK7 { + regulator-name = "buck7"; + regulator-min-microvolt = <500000>; + regulator-max-microvolt = <2000000>; + regulator-ramp-delay = <2500>; + }; + ldo1: LDO1 { + regulator-name = "ldo1"; + regulator-min-microvolt = <800000>; + regulator-max-microvolt = <3300000>; + }; + ldo2: LDO2 { + regulator-name = "ldo2"; + regulator-min-microvolt = <800000>; + regulator-max-microvolt = <3300000>; + }; + ldo3: LDO3 { + regulator-name = "ldo3"; + regulator-min-microvolt = <800000>; + regulator-max-microvolt = <3300000>; + }; + ldo4: LDO4 { + regulator-name = "ldo4"; + regulator-min-microvolt = <800000>; + regulator-max-microvolt = <3300000>; + }; + ldo5: LDO5 { + regulator-name = "ldo5"; + regulator-min-microvolt = <800000>; + regulator-max-microvolt = <3300000>; + }; + ldo6: LDO6 { + regulator-name = "ldo6"; + regulator-min-microvolt = <1800000>; + regulator-max-microvolt = <1800000>; + }; + ldo7_reg: LDO7 { + regulator-name = "ldo7"; + regulator-min-microvolt = <800000>; + regulator-max-microvolt = <3300000>; + }; + }; + + leds { + compatible = "rohm,bd71828-leds"; + + led-1 { + rohm,led-compatible = "bd71828-grnled"; + function = LED_FUNCTION_INDICATOR; + color = <LED_COLOR_ID_GREEN>; + }; + led-2 { + rohm,led-compatible = "bd71828-ambled"; + function = LED_FUNCTION_CHARGING; + color = <LED_COLOR_ID_AMBER>; + }; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/mfd/sun6i-prcm.txt b/Documentation/devicetree/bindings/mfd/sun6i-prcm.txt deleted file mode 100644 index daa091c2e67b..000000000000 --- a/Documentation/devicetree/bindings/mfd/sun6i-prcm.txt +++ /dev/null @@ -1,59 +0,0 @@ -* Allwinner PRCM (Power/Reset/Clock Management) Multi-Functional Device - -PRCM is an MFD device exposing several Power Management related devices -(like clks and reset controllers). - -Required properties: - - compatible: "allwinner,sun6i-a31-prcm" or "allwinner,sun8i-a23-prcm" - - reg: The PRCM registers range - -The prcm node may contain several subdevices definitions: - - see Documentation/devicetree/bindings/clock/sunxi.txt for clock devices - - see Documentation/devicetree/bindings/reset/allwinner,sunxi-clock-reset.txt for reset - controller devices - - -Example: - - prcm: prcm@1f01400 { - compatible = "allwinner,sun6i-a31-prcm"; - reg = <0x01f01400 0x200>; - - /* Put subdevices here */ - ar100: ar100_clk { - compatible = "allwinner,sun6i-a31-ar100-clk"; - #clock-cells = <0>; - clocks = <&osc32k>, <&osc24M>, <&pll6>, <&pll6>; - }; - - ahb0: ahb0_clk { - compatible = "fixed-factor-clock"; - #clock-cells = <0>; - clock-div = <1>; - clock-mult = <1>; - clocks = <&ar100_div>; - clock-output-names = "ahb0"; - }; - - apb0: apb0_clk { - compatible = "allwinner,sun6i-a31-apb0-clk"; - #clock-cells = <0>; - clocks = <&ahb0>; - clock-output-names = "apb0"; - }; - - apb0_gates: apb0_gates_clk { - compatible = "allwinner,sun6i-a31-apb0-gates-clk"; - #clock-cells = <1>; - clocks = <&apb0>; - clock-output-names = "apb0_pio", "apb0_ir", - "apb0_timer01", "apb0_p2wi", - "apb0_uart", "apb0_1wire", - "apb0_i2c"; - }; - - apb0_rst: apb0_rst { - compatible = "allwinner,sun6i-a31-clock-reset"; - #reset-cells = <1>; - }; - }; diff --git a/Documentation/devicetree/bindings/mfd/tps6105x.txt b/Documentation/devicetree/bindings/mfd/tps6105x.txt index 93602c7a19c8..dc448a9d5b4d 100644 --- a/Documentation/devicetree/bindings/mfd/tps6105x.txt +++ b/Documentation/devicetree/bindings/mfd/tps6105x.txt @@ -7,11 +7,56 @@ Required properties: - compatible: "ti,tps61050" or "ti,tps61052" - reg: Specifies the I2C slave address -Example: +Optional sub-node: + +This subnode selects the chip's operational mode. +There can be at most one single available subnode. + +- regulator: presence of this sub-node puts the chip in regulator mode. + see ../regulator/regulator.yaml + +- led: presence of this sub-node puts the chip in led mode. + Optional properties: + - function : see ../leds/common.txt + - color : see ../leds/common.txt + - label : see ../leds/common.txt + (deprecated) + +Example (GPIO operation only): + +i2c0 { + tps61052@33 { + compatible = "ti,tps61052"; + reg = <0x33>; + }; +}; + +Example (GPIO + regulator operation): i2c0 { tps61052@33 { compatible = "ti,tps61052"; reg = <0x33>; + + regulator { + regulator-min-microvolt = <5000000>; + regulator-max-microvolt = <5000000>; + regulator-always-on; + }; + }; +}; + +Example (GPIO + led operation): + +#include <dt-bindings/leds/common.h> + +i2c0 { + tps61052@33 { + compatible = "ti,tps61052"; + reg = <0x33>; + + led { + color = <LED_COLOR_ID_WHITE>; + }; }; }; diff --git a/Documentation/devicetree/bindings/mfd/xylon,logicvc.yaml b/Documentation/devicetree/bindings/mfd/xylon,logicvc.yaml new file mode 100644 index 000000000000..abc9937506e0 --- /dev/null +++ b/Documentation/devicetree/bindings/mfd/xylon,logicvc.yaml @@ -0,0 +1,50 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +# Copyright 2019 Bootlin +%YAML 1.2 +--- +$id: "http://devicetree.org/schemas/mfd/xylon,logicvc.yaml#" +$schema: "http://devicetree.org/meta-schemas/core.yaml#" + +title: Xylon LogiCVC multi-function device + +maintainers: + - Paul Kocialkowski <paul.kocialkowski@bootlin.com> + +description: | + The LogiCVC is a display controller that also contains a GPIO controller. + As a result, a multi-function device is exposed as parent of the display + and GPIO blocks. + +properties: + compatible: + items: + - enum: + - xylon,logicvc-3.02.a + - const: syscon + - const: simple-mfd + + reg: + maxItems: 1 + +select: + properties: + compatible: + contains: + enum: + - xylon,logicvc-3.02.a + + required: + - compatible + +required: + - compatible + - reg + +examples: + - | + logicvc: logicvc@43c00000 { + compatible = "xylon,logicvc-3.02.a", "syscon", "simple-mfd"; + reg = <0x43c00000 0x6000>; + #address-cells = <1>; + #size-cells = <1>; + }; diff --git a/Documentation/devicetree/bindings/mips/ingenic/devices.yaml b/Documentation/devicetree/bindings/mips/ingenic/devices.yaml new file mode 100644 index 000000000000..78dcf6ef3883 --- /dev/null +++ b/Documentation/devicetree/bindings/mips/ingenic/devices.yaml @@ -0,0 +1,35 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/mips/ingenic/devices.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Ingenic XBurst based Platforms Device Tree Bindings + +maintainers: + - 周ç°æ° (Zhou Yanjie) <zhouyanjie@wanyeetech.com> +description: | + Devices with a Ingenic XBurst CPU shall have the following properties. + +properties: + $nodename: + const: '/' + compatible: + oneOf: + + - description: Qi Hardware Ben NanoNote + items: + - const: qi,lb60 + + - description: Game Consoles Worldwide GCW Zero + items: + - const: gcw,zero + + - description: MIPS Creator CI20 + items: + - const: img,ci20 + + - description: YSH & ATIL General Board CU Neo + items: + - const: yna,cu1000-neo +... diff --git a/Documentation/devicetree/bindings/misc/aspeed-p2a-ctrl.txt b/Documentation/devicetree/bindings/misc/aspeed-p2a-ctrl.txt index 0e1fa5bc6a30..f2e2e28b317c 100644 --- a/Documentation/devicetree/bindings/misc/aspeed-p2a-ctrl.txt +++ b/Documentation/devicetree/bindings/misc/aspeed-p2a-ctrl.txt @@ -18,6 +18,7 @@ Required properties: Optional properties: =================== +- reg: A hint for the memory regions associated with the P2A controller - memory-region: A phandle to a reserved_memory region to be used for the PCI to AHB mapping diff --git a/Documentation/devicetree/bindings/mmc/brcm,sdhci-brcmstb.txt b/Documentation/devicetree/bindings/mmc/brcm,sdhci-brcmstb.txt index 733b64a4d8eb..ae2074184528 100644 --- a/Documentation/devicetree/bindings/mmc/brcm,sdhci-brcmstb.txt +++ b/Documentation/devicetree/bindings/mmc/brcm,sdhci-brcmstb.txt @@ -11,28 +11,43 @@ Required properties: - compatible: should be one of the following - "brcm,bcm7425-sdhci" - "brcm,bcm7445-sdhci" + - "brcm,bcm7216-sdhci" Refer to clocks/clock-bindings.txt for generic clock consumer properties. Example: - sdhci@f03e0100 { - compatible = "brcm,bcm7425-sdhci"; - reg = <0xf03e0000 0x100>; - interrupts = <0x0 0x26 0x0>; - sdhci,auto-cmd12; - clocks = <&sw_sdio>; + sdhci@84b0000 { sd-uhs-sdr50; sd-uhs-ddr50; + sd-uhs-sdr104; + sdhci,auto-cmd12; + compatible = "brcm,bcm7216-sdhci", + "brcm,bcm7445-sdhci", + "brcm,sdhci-brcmstb"; + reg = <0x84b0000 0x260 0x84b0300 0x200>; + reg-names = "host", "cfg"; + interrupts = <0x0 0x26 0x4>; + interrupt-names = "sdio0_0"; + clocks = <&scmi_clk 245>; + clock-names = "sw_sdio"; }; - sdhci@f03e0300 { + sdhci@84b1000 { + mmc-ddr-1_8v; + mmc-hs200-1_8v; + mmc-hs400-1_8v; + mmc-hs400-enhanced-strobe; + supports-cqe; non-removable; bus-width = <0x8>; - compatible = "brcm,bcm7425-sdhci"; - reg = <0xf03e0200 0x100>; - interrupts = <0x0 0x27 0x0>; - sdhci,auto-cmd12; - clocks = <sw_sdio>; - mmc-hs200-1_8v; + compatible = "brcm,bcm7216-sdhci", + "brcm,bcm7445-sdhci", + "brcm,sdhci-brcmstb"; + reg = <0x84b1000 0x260 0x84b1300 0x200>; + reg-names = "host", "cfg"; + interrupts = <0x0 0x27 0x4>; + interrupt-names = "sdio1_0"; + clocks = <&scmi_clk 245>; + clock-names = "sw_sdio"; }; diff --git a/Documentation/devicetree/bindings/mmc/fsl-imx-esdhc.txt b/Documentation/devicetree/bindings/mmc/fsl-imx-esdhc.txt index 2fb466ca2a9d..0f97d711444e 100644 --- a/Documentation/devicetree/bindings/mmc/fsl-imx-esdhc.txt +++ b/Documentation/devicetree/bindings/mmc/fsl-imx-esdhc.txt @@ -21,6 +21,8 @@ Required properties: "fsl,imx8mq-usdhc" "fsl,imx8mm-usdhc" "fsl,imx8mn-usdhc" + "fsl,imx8mp-usdhc" + "fsl,imx8qm-usdhc" "fsl,imx8qxp-usdhc" Optional properties: diff --git a/Documentation/devicetree/bindings/mmc/mmc-controller.yaml b/Documentation/devicetree/bindings/mmc/mmc-controller.yaml index b130450c3b34..3c0df4016a12 100644 --- a/Documentation/devicetree/bindings/mmc/mmc-controller.yaml +++ b/Documentation/devicetree/bindings/mmc/mmc-controller.yaml @@ -96,11 +96,10 @@ properties: description: When set, no physical write-protect line is present. This property should only be specified when the controller has a - dedicated write-protect detection logic. If a GPIO is always - used for the write-protect detection. If a GPIO is always used + dedicated write-protect detection logic. If a GPIO is always used for the write-protect detection logic, it is sufficient to not specify the wp-gpios property in the absence of a write-protect - line. + line. Not used in combination with eMMC or SDIO. wp-gpios: description: diff --git a/Documentation/devicetree/bindings/mmc/renesas,sdhi.txt b/Documentation/devicetree/bindings/mmc/renesas,sdhi.txt index bc08fc43a9be..e6cc47844207 100644 --- a/Documentation/devicetree/bindings/mmc/renesas,sdhi.txt +++ b/Documentation/devicetree/bindings/mmc/renesas,sdhi.txt @@ -23,7 +23,8 @@ Required properties: "renesas,sdhi-r8a7793" - SDHI IP on R8A7793 SoC "renesas,sdhi-r8a7794" - SDHI IP on R8A7794 SoC "renesas,sdhi-r8a7795" - SDHI IP on R8A7795 SoC - "renesas,sdhi-r8a7796" - SDHI IP on R8A7796 SoC + "renesas,sdhi-r8a7796" - SDHI IP on R8A77960 SoC + "renesas,sdhi-r8a77961" - SDHI IP on R8A77961 SoC "renesas,sdhi-r8a77965" - SDHI IP on R8A77965 SoC "renesas,sdhi-r8a77970" - SDHI IP on R8A77970 SoC "renesas,sdhi-r8a77980" - SDHI IP on R8A77980 SoC diff --git a/Documentation/devicetree/bindings/mmc/rockchip-dw-mshc.txt b/Documentation/devicetree/bindings/mmc/rockchip-dw-mshc.txt deleted file mode 100644 index 6f629b12bd69..000000000000 --- a/Documentation/devicetree/bindings/mmc/rockchip-dw-mshc.txt +++ /dev/null @@ -1,49 +0,0 @@ -* Rockchip specific extensions to the Synopsys Designware Mobile - Storage Host Controller - -The Synopsys designware mobile storage host controller is used to interface -a SoC with storage medium such as eMMC or SD/MMC cards. This file documents -differences between the core Synopsys dw mshc controller properties described -by synopsys-dw-mshc.txt and the properties used by the Rockchip specific -extensions to the Synopsys Designware Mobile Storage Host Controller. - -Required Properties: - -* compatible: should be - - "rockchip,rk2928-dw-mshc": for Rockchip RK2928 and following, - before RK3288 - - "rockchip,rk3288-dw-mshc": for Rockchip RK3288 - - "rockchip,rv1108-dw-mshc", "rockchip,rk3288-dw-mshc": for Rockchip RV1108 - - "rockchip,px30-dw-mshc", "rockchip,rk3288-dw-mshc": for Rockchip PX30 - - "rockchip,rk3036-dw-mshc", "rockchip,rk3288-dw-mshc": for Rockchip RK3036 - - "rockchip,rk3228-dw-mshc", "rockchip,rk3288-dw-mshc": for Rockchip RK322x - - "rockchip,rk3328-dw-mshc", "rockchip,rk3288-dw-mshc": for Rockchip RK3328 - - "rockchip,rk3368-dw-mshc", "rockchip,rk3288-dw-mshc": for Rockchip RK3368 - - "rockchip,rk3399-dw-mshc", "rockchip,rk3288-dw-mshc": for Rockchip RK3399 - -Optional Properties: -* clocks: from common clock binding: if ciu-drive and ciu-sample are - specified in clock-names, should contain handles to these clocks. - -* clock-names: Apart from the clock-names described in synopsys-dw-mshc.txt - two more clocks "ciu-drive" and "ciu-sample" are supported. They are used - to control the clock phases, "ciu-sample" is required for tuning high- - speed modes. - -* rockchip,default-sample-phase: The default phase to set ciu-sample at - probing, low speeds or in case where all phases work at tuning time. - If not specified 0 deg will be used. - -* rockchip,desired-num-phases: The desired number of times that the host - execute tuning when needed. If not specified, the host will do tuning - for 360 times, namely tuning for each degree. - -Example: - - rkdwmmc0@12200000 { - compatible = "rockchip,rk3288-dw-mshc"; - reg = <0x12200000 0x1000>; - interrupts = <0 75 0>; - #address-cells = <1>; - #size-cells = <0>; - }; diff --git a/Documentation/devicetree/bindings/mmc/rockchip-dw-mshc.yaml b/Documentation/devicetree/bindings/mmc/rockchip-dw-mshc.yaml new file mode 100644 index 000000000000..89c3edd6a728 --- /dev/null +++ b/Documentation/devicetree/bindings/mmc/rockchip-dw-mshc.yaml @@ -0,0 +1,125 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/mmc/rockchip-dw-mshc.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Rockchip designware mobile storage host controller device tree bindings + +description: + Rockchip uses the Synopsys designware mobile storage host controller + to interface a SoC with storage medium such as eMMC or SD/MMC cards. + This file documents the combined properties for the core Synopsys dw mshc + controller that are not already included in the synopsys-dw-mshc-common.yaml + file and the Rockchip specific extensions. + +allOf: + - $ref: "synopsys-dw-mshc-common.yaml#" + +maintainers: + - Heiko Stuebner <heiko@sntech.de> + +# Everything else is described in the common file +properties: + compatible: + oneOf: + # for Rockchip RK2928 and before RK3288 + - const: rockchip,rk2928-dw-mshc + # for Rockchip RK3288 + - const: rockchip,rk3288-dw-mshc + - items: + - enum: + # for Rockchip PX30 + - rockchip,px30-dw-mshc + # for Rockchip RK3036 + - rockchip,rk3036-dw-mshc + # for Rockchip RK322x + - rockchip,rk3228-dw-mshc + # for Rockchip RK3308 + - rockchip,rk3308-dw-mshc + # for Rockchip RK3328 + - rockchip,rk3328-dw-mshc + # for Rockchip RK3368 + - rockchip,rk3368-dw-mshc + # for Rockchip RK3399 + - rockchip,rk3399-dw-mshc + # for Rockchip RV1108 + - rockchip,rv1108-dw-mshc + - const: rockchip,rk3288-dw-mshc + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + clocks: + minItems: 2 + maxItems: 4 + description: + Handle to "biu" and "ciu" clocks for the bus interface unit clock and + the card interface unit clock. If "ciu-drive" and "ciu-sample" are + specified in clock-names, it should also contain + handles to these clocks. + + clock-names: + minItems: 2 + items: + - const: biu + - const: ciu + - const: ciu-drive + - const: ciu-sample + description: + Apart from the clock-names "biu" and "ciu" two more clocks + "ciu-drive" and "ciu-sample" are supported. They are used + to control the clock phases, "ciu-sample" is required for tuning + high speed modes. + + rockchip,default-sample-phase: + allOf: + - $ref: /schemas/types.yaml#/definitions/uint32 + minimum: 0 + maximum: 360 + default: 0 + description: + The default phase to set "ciu-sample" at probing, + low speeds or in case where all phases work at tuning time. + If not specified 0 deg will be used. + + rockchip,desired-num-phases: + allOf: + - $ref: /schemas/types.yaml#/definitions/uint32 + minimum: 0 + maximum: 360 + default: 360 + description: + The desired number of times that the host execute tuning when needed. + If not specified, the host will do tuning for 360 times, + namely tuning for each degree. + +required: + - compatible + - reg + - interrupts + - clocks + - clock-names + +examples: + - | + #include <dt-bindings/clock/rk3288-cru.h> + #include <dt-bindings/interrupt-controller/arm-gic.h> + #include <dt-bindings/interrupt-controller/irq.h> + sdmmc: mmc@ff0c0000 { + compatible = "rockchip,rk3288-dw-mshc"; + reg = <0x0 0xff0c0000 0x0 0x4000>; + interrupts = <GIC_SPI 32 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&cru HCLK_SDMMC>, <&cru SCLK_SDMMC>, + <&cru SCLK_SDMMC_DRV>, <&cru SCLK_SDMMC_SAMPLE>; + clock-names = "biu", "ciu", "ciu-drive", "ciu-sample"; + resets = <&cru SRST_MMC0>; + reset-names = "reset"; + fifo-depth = <0x100>; + max-frequency = <150000000>; + }; + +... diff --git a/Documentation/devicetree/bindings/mmc/sdhci-atmel.txt b/Documentation/devicetree/bindings/mmc/sdhci-atmel.txt index 503c6dbac1b2..69edfd4d3922 100644 --- a/Documentation/devicetree/bindings/mmc/sdhci-atmel.txt +++ b/Documentation/devicetree/bindings/mmc/sdhci-atmel.txt @@ -5,11 +5,16 @@ Documentation/devicetree/bindings/mmc/mmc.txt and the properties used by the sdhci-of-at91 driver. Required properties: -- compatible: Must be "atmel,sama5d2-sdhci". +- compatible: Must be "atmel,sama5d2-sdhci" or "microchip,sam9x60-sdhci". - clocks: Phandlers to the clocks. -- clock-names: Must be "hclock", "multclk", "baseclk"; +- clock-names: Must be "hclock", "multclk", "baseclk" for + "atmel,sama5d2-sdhci". + Must be "hclock", "multclk" for "microchip,sam9x60-sdhci". Optional properties: +- assigned-clocks: The same with "multclk". +- assigned-clock-rates The rate of "multclk" in order to not rely on the + gck configuration set by previous components. - microchip,sdcal-inverted: when present, polarity on the SDCAL SoC pin is inverted. The default polarity for this signal is described in the datasheet. For instance on SAMA5D2, the pin is usually tied to the GND with a resistor @@ -17,10 +22,12 @@ Optional properties: Example: -sdmmc0: sdio-host@a0000000 { +mmc0: sdio-host@a0000000 { compatible = "atmel,sama5d2-sdhci"; reg = <0xa0000000 0x300>; interrupts = <31 IRQ_TYPE_LEVEL_HIGH 0>; clocks = <&sdmmc0_hclk>, <&sdmmc0_gclk>, <&main>; clock-names = "hclock", "multclk", "baseclk"; + assigned-clocks = <&sdmmc0_gclk>; + assigned-clock-rates = <480000000>; }; diff --git a/Documentation/devicetree/bindings/mmc/sdhci-msm.txt b/Documentation/devicetree/bindings/mmc/sdhci-msm.txt index da4edb146a98..7ee639b1af03 100644 --- a/Documentation/devicetree/bindings/mmc/sdhci-msm.txt +++ b/Documentation/devicetree/bindings/mmc/sdhci-msm.txt @@ -19,6 +19,7 @@ Required properties: "qcom,msm8996-sdhci", "qcom,sdhci-msm-v4" "qcom,sdm845-sdhci", "qcom,sdhci-msm-v5" "qcom,qcs404-sdhci", "qcom,sdhci-msm-v5" + "qcom,sc7180-sdhci", "qcom,sdhci-msm-v5"; NOTE that some old device tree files may be floating around that only have the string "qcom,sdhci-msm-v4" without the SoC compatible string but doing that should be considered a deprecated practice. diff --git a/Documentation/devicetree/bindings/mmc/sdhci-omap.txt b/Documentation/devicetree/bindings/mmc/sdhci-omap.txt index 72c4dec7e1db..aeb615ef672a 100644 --- a/Documentation/devicetree/bindings/mmc/sdhci-omap.txt +++ b/Documentation/devicetree/bindings/mmc/sdhci-omap.txt @@ -7,6 +7,8 @@ For UHS devices which require tuning, the device tree should have a "cpu_thermal Required properties: - compatible: Should be "ti,dra7-sdhci" for DRA7 and DRA72 controllers Should be "ti,k2g-sdhci" for K2G + Should be "ti,am335-sdhci" for am335x controllers + Should be "ti,am437-sdhci" for am437x controllers - ti,hwmods: Must be "mmc<n>", <n> is controller instance starting 1 (Not required for K2G). - pinctrl-names: Should be subset of "default", "hs", "sdr12", "sdr25", "sdr50", @@ -15,6 +17,13 @@ Required properties: "hs200_1_8v", - pinctrl-<n> : Pinctrl states as described in bindings/pinctrl/pinctrl-bindings.txt +Optional properties: +- dmas: List of DMA specifiers with the controller specific format as described + in the generic DMA client binding. A tx and rx specifier is required. +- dma-names: List of DMA request names. These strings correspond 1:1 with the + DMA specifiers listed in dmas. The string naming is to be "tx" + and "rx" for TX and RX DMA requests, respectively. + Example: mmc1: mmc@4809c000 { compatible = "ti,dra7-sdhci"; @@ -22,4 +31,6 @@ Example: ti,hwmods = "mmc1"; bus-width = <4>; vmmc-supply = <&vmmc>; /* phandle to regulator node */ + dmas = <&sdma 61 &sdma 62>; + dma-names = "tx", "rx"; }; diff --git a/Documentation/devicetree/bindings/mmc/synopsys-dw-mshc-common.yaml b/Documentation/devicetree/bindings/mmc/synopsys-dw-mshc-common.yaml new file mode 100644 index 000000000000..890d47a87ac5 --- /dev/null +++ b/Documentation/devicetree/bindings/mmc/synopsys-dw-mshc-common.yaml @@ -0,0 +1,68 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/mmc/synopsys-dw-mshc-common.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Synopsys Designware Mobile Storage Host Controller Common Properties + +allOf: + - $ref: "mmc-controller.yaml#" + +maintainers: + - Ulf Hansson <ulf.hansson@linaro.org> + +# Everything else is described in the common file +properties: + resets: + maxItems: 1 + + reset-names: + const: reset + + clock-frequency: + description: + Should be the frequency (in Hz) of the ciu clock. If this + is specified and the ciu clock is specified then we'll try to set the ciu + clock to this at probe time. + + fifo-depth: + allOf: + - $ref: /schemas/types.yaml#/definitions/uint32 + description: + The maximum size of the tx/rx fifo's. If this property is not + specified, the default value of the fifo size is determined from the + controller registers. + + card-detect-delay: + allOf: + - $ref: /schemas/types.yaml#/definitions/uint32 + - default: 0 + description: + Delay in milli-seconds before detecting card after card + insert event. The default value is 0. + + data-addr: + allOf: + - $ref: /schemas/types.yaml#/definitions/uint32 + description: + Override fifo address with value provided by DT. The default FIFO reg + offset is assumed as 0x100 (version < 0x240A) and 0x200(version >= 0x240A) + by driver. If the controller does not follow this rule, please use + this property to set fifo address in device tree. + + fifo-watermark-aligned: + allOf: + - $ref: /schemas/types.yaml#/definitions/flag + description: + Data done irq is expected if data length is less than + watermark in PIO mode. But fifo watermark is requested to be aligned + with data length in some SoC so that TX/RX irq can be generated with + data done irq. Add this watermark quirk to mark this requirement and + force fifo watermark setting accordingly. + + dmas: + maxItems: 1 + + dma-names: + const: rx-tx diff --git a/Documentation/devicetree/bindings/mmc/synopsys-dw-mshc.txt b/Documentation/devicetree/bindings/mmc/synopsys-dw-mshc.txt deleted file mode 100644 index 7e5e427a22ce..000000000000 --- a/Documentation/devicetree/bindings/mmc/synopsys-dw-mshc.txt +++ /dev/null @@ -1,141 +0,0 @@ -* Synopsys Designware Mobile Storage Host Controller - -The Synopsys designware mobile storage host controller is used to interface -a SoC with storage medium such as eMMC or SD/MMC cards. This file documents -differences between the core mmc properties described by mmc.txt and the -properties used by the Synopsys Designware Mobile Storage Host Controller. - -Required Properties: - -* compatible: should be - - snps,dw-mshc: for controllers compliant with synopsys dw-mshc. -* #address-cells: should be 1. -* #size-cells: should be 0. - -# Slots (DEPRECATED): The slot specific information are contained within - child-nodes with each child-node representing a supported slot. There should - be atleast one child node representing a card slot. The name of the child node - representing the slot is recommended to be slot@n where n is the unique number - of the slot connected to the controller. The following are optional properties - which can be included in the slot child node. - - * reg: specifies the physical slot number. The valid values of this - property is 0 to (num-slots -1), where num-slots is the value - specified by the num-slots property. - - * bus-width: as documented in mmc core bindings. - - * wp-gpios: specifies the write protect gpio line. The format of the - gpio specifier depends on the gpio controller. If a GPIO is not used - for write-protect, this property is optional. - - * disable-wp: If the wp-gpios property isn't present then (by default) - we'd assume that the write protect is hooked up directly to the - controller's special purpose write protect line (accessible via - the WRTPRT register). However, it's possible that we simply don't - want write protect. In that case specify 'disable-wp'. - NOTE: This property is not required for slots known to always - connect to eMMC or SDIO cards. - -Optional properties: - -* resets: phandle + reset specifier pair, intended to represent hardware - reset signal present internally in some host controller IC designs. - See Documentation/devicetree/bindings/reset/reset.txt for details. - -* reset-names: request name for using "resets" property. Must be "reset". - (It will be used together with "resets" property.) - -* clocks: from common clock binding: handle to biu and ciu clocks for the - bus interface unit clock and the card interface unit clock. - -* clock-names: from common clock binding: Shall be "biu" and "ciu". - If the biu clock is missing we'll simply skip enabling it. If the - ciu clock is missing we'll just assume that the clock is running at - clock-frequency. It is an error to omit both the ciu clock and the - clock-frequency. - -* clock-frequency: should be the frequency (in Hz) of the ciu clock. If this - is specified and the ciu clock is specified then we'll try to set the ciu - clock to this at probe time. - -* fifo-depth: The maximum size of the tx/rx fifo's. If this property is not - specified, the default value of the fifo size is determined from the - controller registers. - -* card-detect-delay: Delay in milli-seconds before detecting card after card - insert event. The default value is 0. - -* data-addr: Override fifo address with value provided by DT. The default FIFO reg - offset is assumed as 0x100 (version < 0x240A) and 0x200(version >= 0x240A) by - driver. If the controller does not follow this rule, please use this property - to set fifo address in device tree. - -* fifo-watermark-aligned: Data done irq is expected if data length is less than - watermark in PIO mode. But fifo watermark is requested to be aligned with data - length in some SoC so that TX/RX irq can be generated with data done irq. Add this - watermark quirk to mark this requirement and force fifo watermark setting - accordingly. - -* vmmc-supply: The phandle to the regulator to use for vmmc. If this is - specified we'll defer probe until we can find this regulator. - -* dmas: List of DMA specifiers with the controller specific format as described - in the generic DMA client binding. Refer to dma.txt for details. - -* dma-names: request names for generic DMA client binding. Must be "rx-tx". - Refer to dma.txt for details. - -Aliases: - -- All the MSHC controller nodes should be represented in the aliases node using - the following format 'mshc{n}' where n is a unique number for the alias. - -Example: - -The MSHC controller node can be split into two portions, SoC specific and -board specific portions as listed below. - - dwmmc0@12200000 { - compatible = "snps,dw-mshc"; - clocks = <&clock 351>, <&clock 132>; - clock-names = "biu", "ciu"; - reg = <0x12200000 0x1000>; - interrupts = <0 75 0>; - #address-cells = <1>; - #size-cells = <0>; - data-addr = <0x200>; - fifo-watermark-aligned; - resets = <&rst 20>; - reset-names = "reset"; - }; - -[board specific internal DMA resources] - - dwmmc0@12200000 { - clock-frequency = <400000000>; - clock-freq-min-max = <400000 200000000>; - broken-cd; - fifo-depth = <0x80>; - card-detect-delay = <200>; - vmmc-supply = <&buck8>; - bus-width = <8>; - cap-mmc-highspeed; - cap-sd-highspeed; - }; - -[board specific generic DMA request binding] - - dwmmc0@12200000 { - clock-frequency = <400000000>; - clock-freq-min-max = <400000 200000000>; - broken-cd; - fifo-depth = <0x80>; - card-detect-delay = <200>; - vmmc-supply = <&buck8>; - bus-width = <8>; - cap-mmc-highspeed; - cap-sd-highspeed; - dmas = <&pdma 12>; - dma-names = "rx-tx"; - }; diff --git a/Documentation/devicetree/bindings/mmc/synopsys-dw-mshc.yaml b/Documentation/devicetree/bindings/mmc/synopsys-dw-mshc.yaml new file mode 100644 index 000000000000..05f9f36dcb75 --- /dev/null +++ b/Documentation/devicetree/bindings/mmc/synopsys-dw-mshc.yaml @@ -0,0 +1,70 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/mmc/synopsys-dw-mshc.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Synopsys Designware Mobile Storage Host Controller Binding + +allOf: + - $ref: "synopsys-dw-mshc-common.yaml#" + +maintainers: + - Ulf Hansson <ulf.hansson@linaro.org> + +# Everything else is described in the common file +properties: + compatible: + const: snps,dw-mshc + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + clocks: + minItems: 2 + maxItems: 2 + description: + Handle to "biu" and "ciu" clocks for the + bus interface unit clock and the card interface unit clock. + + clock-names: + items: + - const: biu + - const: ciu + +required: + - compatible + - reg + - interrupts + - clocks + - clock-names + +examples: + - | + mmc@12200000 { + compatible = "snps,dw-mshc"; + reg = <0x12200000 0x1000>; + interrupts = <0 75 0>; + clocks = <&clock 351>, <&clock 132>; + clock-names = "biu", "ciu"; + dmas = <&pdma 12>; + dma-names = "rx-tx"; + resets = <&rst 20>; + reset-names = "reset"; + vmmc-supply = <&buck8>; + #address-cells = <1>; + #size-cells = <0>; + broken-cd; + bus-width = <8>; + cap-mmc-highspeed; + cap-sd-highspeed; + card-detect-delay = <200>; + clock-freq-min-max = <400000 200000000>; + clock-frequency = <400000000>; + data-addr = <0x200>; + fifo-depth = <0x80>; + fifo-watermark-aligned; + }; diff --git a/Documentation/devicetree/bindings/mmc/ti-omap-hsmmc.txt b/Documentation/devicetree/bindings/mmc/ti-omap-hsmmc.txt index 19f5508a7569..4a9145ef15d6 100644 --- a/Documentation/devicetree/bindings/mmc/ti-omap-hsmmc.txt +++ b/Documentation/devicetree/bindings/mmc/ti-omap-hsmmc.txt @@ -124,7 +124,7 @@ not every application needs SDIO irq, e.g. MMC cards. pinctrl-1 = <&mmc1_idle>; pinctrl-2 = <&mmc1_sleep>; ... - interrupts-extended = <&intc 64 &gpio2 28 GPIO_ACTIVE_LOW>; + interrupts-extended = <&intc 64 &gpio2 28 IRQ_TYPE_LEVEL_LOW>; }; mmc1_idle : pinmux_cirq_pin { diff --git a/Documentation/devicetree/bindings/mtd/atmel-nand.txt b/Documentation/devicetree/bindings/mtd/atmel-nand.txt index 68b51dc58816..3aa297c97ab6 100644 --- a/Documentation/devicetree/bindings/mtd/atmel-nand.txt +++ b/Documentation/devicetree/bindings/mtd/atmel-nand.txt @@ -57,6 +57,7 @@ Required properties: "atmel,at91sam9g45-pmecc" "atmel,sama5d4-pmecc" "atmel,sama5d2-pmecc" + "microchip,sam9x60-pmecc" - reg: should contain 2 register ranges. The first one is pointing to the PMECC block, and the second one to the PMECC_ERRLOC block. diff --git a/Documentation/devicetree/bindings/mtd/denali-nand.txt b/Documentation/devicetree/bindings/mtd/denali-nand.txt index b32aed1db46d..98916a84bbf6 100644 --- a/Documentation/devicetree/bindings/mtd/denali-nand.txt +++ b/Documentation/devicetree/bindings/mtd/denali-nand.txt @@ -14,6 +14,11 @@ Required properties: interface clock, and the ECC circuit clock. - clock-names: should contain "nand", "nand_x", "ecc" +Optional properties: + - resets: may contain phandles to the controller core reset, the register + reset + - reset-names: may contain "nand", "reg" + Sub-nodes: Sub-nodes represent available NAND chips. @@ -46,6 +51,8 @@ nand: nand@ff900000 { reg-names = "nand_data", "denali_reg"; clocks = <&nand_clk>, <&nand_x_clk>, <&nand_ecc_clk>; clock-names = "nand", "nand_x", "ecc"; + resets = <&nand_rst>, <&nand_reg_rst>; + reset-names = "nand", "reg"; interrupts = <0 144 4>; nand@0 { diff --git a/Documentation/devicetree/bindings/net/broadcom-bluetooth.txt b/Documentation/devicetree/bindings/net/broadcom-bluetooth.txt index f16b99571af1..dd258674633c 100644 --- a/Documentation/devicetree/bindings/net/broadcom-bluetooth.txt +++ b/Documentation/devicetree/bindings/net/broadcom-bluetooth.txt @@ -11,6 +11,7 @@ Required properties: - compatible: should contain one of the following: * "brcm,bcm20702a1" + * "brcm,bcm4329-bt" * "brcm,bcm4330-bt" * "brcm,bcm43438-bt" * "brcm,bcm4345c5" @@ -22,7 +23,9 @@ Optional properties: - max-speed: see Documentation/devicetree/bindings/serial/slave-device.txt - shutdown-gpios: GPIO specifier, used to enable the BT module - device-wakeup-gpios: GPIO specifier, used to wakeup the controller - - host-wakeup-gpios: GPIO specifier, used to wakeup the host processor + - host-wakeup-gpios: GPIO specifier, used to wakeup the host processor. + deprecated, replaced by interrupts and + "host-wakeup" interrupt-names - clocks: 1 or 2 clocks as defined in clock-names below, in that order - clock-names: names for clock inputs, matching the clocks given - "extclk": deprecated, replaced by "txco" @@ -30,7 +33,14 @@ Optional properties: - "lpo": external low power 32.768 kHz clock - vbat-supply: phandle to regulator supply for VBAT - vddio-supply: phandle to regulator supply for VDDIO - + - brcm,bt-pcm-int-params: configure PCM parameters via a 5-byte array + - sco-routing: 0 = PCM, 1 = Transport, 2 = Codec, 3 = I2S + - pcm-interface-rate: 128KBps, 256KBps, 512KBps, 1024KBps, 2048KBps + - pcm-frame-type: short, long + - pcm-sync-mode: slave, master + - pcm-clock-mode: slave, master + - interrupts: must be one, used to wakeup the host processor + - interrupt-names: must be "host-wakeup" Example: @@ -41,5 +51,6 @@ Example: bluetooth { compatible = "brcm,bcm43438-bt"; max-speed = <921600>; + brcm,bt-pcm-int-params = [01 02 00 01 01]; }; }; diff --git a/Documentation/devicetree/bindings/net/can/atmel-can.txt b/Documentation/devicetree/bindings/net/can/atmel-can.txt index 14e52a0d86ec..218a3b3eb27e 100644 --- a/Documentation/devicetree/bindings/net/can/atmel-can.txt +++ b/Documentation/devicetree/bindings/net/can/atmel-can.txt @@ -1,7 +1,8 @@ * AT91 CAN * Required properties: - - compatible: Should be "atmel,at91sam9263-can" or "atmel,at91sam9x5-can" + - compatible: Should be "atmel,at91sam9263-can", "atmel,at91sam9x5-can" or + "microchip,sam9x60-can" - reg: Should contain CAN controller registers location and length - interrupts: Should contain IRQ line for the CAN controller diff --git a/Documentation/devicetree/bindings/net/can/rcar_can.txt b/Documentation/devicetree/bindings/net/can/rcar_can.txt index 19e4a7d91511..85c6551b602a 100644 --- a/Documentation/devicetree/bindings/net/can/rcar_can.txt +++ b/Documentation/devicetree/bindings/net/can/rcar_can.txt @@ -7,6 +7,7 @@ Required properties: "renesas,can-r8a7745" if CAN controller is a part of R8A7745 SoC. "renesas,can-r8a77470" if CAN controller is a part of R8A77470 SoC. "renesas,can-r8a774a1" if CAN controller is a part of R8A774A1 SoC. + "renesas,can-r8a774b1" if CAN controller is a part of R8A774B1 SoC. "renesas,can-r8a774c0" if CAN controller is a part of R8A774C0 SoC. "renesas,can-r8a7778" if CAN controller is a part of R8A7778 SoC. "renesas,can-r8a7779" if CAN controller is a part of R8A7779 SoC. @@ -36,8 +37,8 @@ Required properties: - pinctrl-0: pin control group to be used for this controller. - pinctrl-names: must be "default". -Required properties for R8A774A1, R8A774C0, R8A7795, R8A7796, R8A77965, -R8A77990, and R8A77995: +Required properties for R8A774A1, R8A774B1, R8A774C0, R8A7795, R8A7796, +R8A77965, R8A77990, and R8A77995: For the denoted SoCs, "clkp2" can be CANFD clock. This is a div6 clock and can be used by both CAN and CAN FD controller at the same time. It needs to be scaled to maximum frequency if any of these controllers use it. This is done diff --git a/Documentation/devicetree/bindings/net/can/rcar_canfd.txt b/Documentation/devicetree/bindings/net/can/rcar_canfd.txt index a901cd9be29e..13a4e34c0c73 100644 --- a/Documentation/devicetree/bindings/net/can/rcar_canfd.txt +++ b/Documentation/devicetree/bindings/net/can/rcar_canfd.txt @@ -5,6 +5,7 @@ Required properties: - compatible: Must contain one or more of the following: - "renesas,rcar-gen3-canfd" for R-Car Gen3 and RZ/G2 compatible controllers. - "renesas,r8a774a1-canfd" for R8A774A1 (RZ/G2M) compatible controller. + - "renesas,r8a774b1-canfd" for R8A774B1 (RZ/G2N) compatible controller. - "renesas,r8a774c0-canfd" for R8A774C0 (RZ/G2E) compatible controller. - "renesas,r8a7795-canfd" for R8A7795 (R-Car H3) compatible controller. - "renesas,r8a7796-canfd" for R8A7796 (R-Car M3-W) compatible controller. @@ -31,8 +32,8 @@ The name of the child nodes are "channel0" and "channel1" respectively. Each child node supports the "status" property only, which is used to enable/disable the respective channel. -Required properties for R8A774A1, R8A774C0, R8A7795, R8A7796, R8A77965, -R8A77990, and R8A77995: +Required properties for R8A774A1, R8A774B1, R8A774C0, R8A7795, R8A7796, +R8A77965, R8A77990, and R8A77995: In the denoted SoCs, canfd clock is a div6 clock and can be used by both CAN and CAN FD controller at the same time. It needs to be scaled to maximum frequency if any of these controllers use it. This is done using the below diff --git a/Documentation/devicetree/bindings/net/dsa/ar9331.txt b/Documentation/devicetree/bindings/net/dsa/ar9331.txt new file mode 100644 index 000000000000..320607cbbb17 --- /dev/null +++ b/Documentation/devicetree/bindings/net/dsa/ar9331.txt @@ -0,0 +1,148 @@ +Atheros AR9331 built-in switch +============================= + +It is a switch built-in to Atheros AR9331 WiSoC and addressable over internal +MDIO bus. All PHYs are built-in as well. + +Required properties: + + - compatible: should be: "qca,ar9331-switch" + - reg: Address on the MII bus for the switch. + - resets : Must contain an entry for each entry in reset-names. + - reset-names : Must include the following entries: "switch" + - interrupt-parent: Phandle to the parent interrupt controller + - interrupts: IRQ line for the switch + - interrupt-controller: Indicates the switch is itself an interrupt + controller. This is used for the PHY interrupts. + - #interrupt-cells: must be 1 + - mdio: Container of PHY and devices on the switches MDIO bus. + +See Documentation/devicetree/bindings/net/dsa/dsa.txt for a list of additional +required and optional properties. +Examples: + +eth0: ethernet@19000000 { + compatible = "qca,ar9330-eth"; + reg = <0x19000000 0x200>; + interrupts = <4>; + + resets = <&rst 9>, <&rst 22>; + reset-names = "mac", "mdio"; + clocks = <&pll ATH79_CLK_AHB>, <&pll ATH79_CLK_AHB>; + clock-names = "eth", "mdio"; + + phy-mode = "mii"; + phy-handle = <&phy_port4>; +}; + +eth1: ethernet@1a000000 { + compatible = "qca,ar9330-eth"; + reg = <0x1a000000 0x200>; + interrupts = <5>; + resets = <&rst 13>, <&rst 23>; + reset-names = "mac", "mdio"; + clocks = <&pll ATH79_CLK_AHB>, <&pll ATH79_CLK_AHB>; + clock-names = "eth", "mdio"; + + phy-mode = "gmii"; + + fixed-link { + speed = <1000>; + full-duplex; + }; + + mdio { + #address-cells = <1>; + #size-cells = <0>; + + switch10: switch@10 { + #address-cells = <1>; + #size-cells = <0>; + + compatible = "qca,ar9331-switch"; + reg = <0x10>; + resets = <&rst 8>; + reset-names = "switch"; + + interrupt-parent = <&miscintc>; + interrupts = <12>; + + interrupt-controller; + #interrupt-cells = <1>; + + ports { + #address-cells = <1>; + #size-cells = <0>; + + switch_port0: port@0 { + reg = <0x0>; + label = "cpu"; + ethernet = <ð1>; + + phy-mode = "gmii"; + + fixed-link { + speed = <1000>; + full-duplex; + }; + }; + + switch_port1: port@1 { + reg = <0x1>; + phy-handle = <&phy_port0>; + phy-mode = "internal"; + }; + + switch_port2: port@2 { + reg = <0x2>; + phy-handle = <&phy_port1>; + phy-mode = "internal"; + }; + + switch_port3: port@3 { + reg = <0x3>; + phy-handle = <&phy_port2>; + phy-mode = "internal"; + }; + + switch_port4: port@4 { + reg = <0x4>; + phy-handle = <&phy_port3>; + phy-mode = "internal"; + }; + }; + + mdio { + #address-cells = <1>; + #size-cells = <0>; + + interrupt-parent = <&switch10>; + + phy_port0: phy@0 { + reg = <0x0>; + interrupts = <0>; + }; + + phy_port1: phy@1 { + reg = <0x1>; + interrupts = <0>; + }; + + phy_port2: phy@2 { + reg = <0x2>; + interrupts = <0>; + }; + + phy_port3: phy@3 { + reg = <0x3>; + interrupts = <0>; + }; + + phy_port4: phy@4 { + reg = <0x4>; + interrupts = <0>; + }; + }; + }; + }; +}; diff --git a/Documentation/devicetree/bindings/net/fsl-fman.txt b/Documentation/devicetree/bindings/net/fsl-fman.txt index 299c0dcd67db..250f8d8cdce4 100644 --- a/Documentation/devicetree/bindings/net/fsl-fman.txt +++ b/Documentation/devicetree/bindings/net/fsl-fman.txt @@ -403,6 +403,19 @@ PROPERTIES The settings and programming routines for internal/external MDIO are different. Must be included for internal MDIO. +- fsl,erratum-a011043 + Usage: optional + Value type: <boolean> + Definition: Indicates the presence of the A011043 erratum + describing that the MDIO_CFG[MDIO_RD_ER] bit may be falsely + set when reading internal PCS registers. MDIO reads to + internal PCS registers may result in having the + MDIO_CFG[MDIO_RD_ER] bit set, even when there is no error and + read data (MDIO_DATA[MDIO_DATA]) is correct. + Software may get false read error when reading internal + PCS registers through MDIO. As a workaround, all internal + MDIO accesses should ignore the MDIO_CFG[MDIO_RD_ER] bit. + For internal PHY device on internal mdio bus, a PHY node should be created. See the definition of the PHY node in booting-without-of.txt for an example of how to define a PHY (Internal PHY has no interrupt line). diff --git a/Documentation/devicetree/bindings/net/mdio.yaml b/Documentation/devicetree/bindings/net/mdio.yaml index 5d08d2ffd4eb..50c3397a82bc 100644 --- a/Documentation/devicetree/bindings/net/mdio.yaml +++ b/Documentation/devicetree/bindings/net/mdio.yaml @@ -56,7 +56,6 @@ patternProperties: examples: - | davinci_mdio: mdio@5c030000 { - compatible = "ti,davinci_mdio"; reg = <0x5c030000 0x1000>; #address-cells = <1>; #size-cells = <0>; diff --git a/Documentation/devicetree/bindings/net/mediatek-dwmac.txt b/Documentation/devicetree/bindings/net/mediatek-dwmac.txt index 8a08621a5b54..afbcaebf062e 100644 --- a/Documentation/devicetree/bindings/net/mediatek-dwmac.txt +++ b/Documentation/devicetree/bindings/net/mediatek-dwmac.txt @@ -14,7 +14,7 @@ Required properties: Should be "macirq" for the main MAC IRQ - clocks: Must contain a phandle for each entry in clock-names. - clock-names: The name of the clock listed in the clocks property. These are - "axi", "apb", "mac_main", "ptp_ref" for MT2712 SoC + "axi", "apb", "mac_main", "ptp_ref", "rmii_internal" for MT2712 SoC. - mac-address: See ethernet.txt in the same directory - phy-mode: See ethernet.txt in the same directory - mediatek,pericfg: A phandle to the syscon node that control ethernet @@ -23,8 +23,10 @@ Required properties: Optional properties: - mediatek,tx-delay-ps: TX clock delay macro value. Default is 0. It should be defined for RGMII/MII interface. + It should be defined for RMII interface when the reference clock is from MT2712 SoC. - mediatek,rx-delay-ps: RX clock delay macro value. Default is 0. - It should be defined for RGMII/MII/RMII interface. + It should be defined for RGMII/MII interface. + It should be defined for RMII interface. Both delay properties need to be a multiple of 170 for RGMII interface, or will round down. Range 0~31*170. Both delay properties need to be a multiple of 550 for MII/RMII interface, @@ -34,13 +36,20 @@ or will round down. Range 0~31*550. reference clock, which is from external PHYs, is connected to RXC pin on MT2712 SoC. Otherwise, is connected to TXC pin. +- mediatek,rmii-clk-from-mac: boolean property, if present indicates that + MT2712 SoC provides the RMII reference clock, which outputs to TXC pin only. - mediatek,txc-inverse: boolean property, if present indicates that 1. tx clock will be inversed in MII/RGMII case, 2. tx clock inside MAC will be inversed relative to reference clock which is from external PHYs in RMII case, and it rarely happen. + 3. the reference clock, which outputs to TXC pin will be inversed in RMII case + when the reference clock is from MT2712 SoC. - mediatek,rxc-inverse: boolean property, if present indicates that 1. rx clock will be inversed in MII/RGMII case. - 2. reference clock will be inversed when arrived at MAC in RMII case. + 2. reference clock will be inversed when arrived at MAC in RMII case, when + the reference clock is from external PHYs. + 3. the inside clock, which be sent to MAC, will be inversed in RMII case when + the reference clock is from MT2712 SoC. - assigned-clocks: mac_main and ptp_ref clocks - assigned-clock-parents: parent clocks of the assigned clocks @@ -50,29 +59,33 @@ Example: reg = <0 0x1101c000 0 0x1300>; interrupts = <GIC_SPI 237 IRQ_TYPE_LEVEL_LOW>; interrupt-names = "macirq"; - phy-mode ="rgmii"; + phy-mode ="rgmii-rxid"; mac-address = [00 55 7b b5 7d f7]; clock-names = "axi", "apb", "mac_main", "ptp_ref", - "ptp_top"; + "rmii_internal"; clocks = <&pericfg CLK_PERI_GMAC>, <&pericfg CLK_PERI_GMAC_PCLK>, <&topckgen CLK_TOP_ETHER_125M_SEL>, - <&topckgen CLK_TOP_ETHER_50M_SEL>; + <&topckgen CLK_TOP_ETHER_50M_SEL>, + <&topckgen CLK_TOP_ETHER_50M_RMII_SEL>; assigned-clocks = <&topckgen CLK_TOP_ETHER_125M_SEL>, - <&topckgen CLK_TOP_ETHER_50M_SEL>; + <&topckgen CLK_TOP_ETHER_50M_SEL>, + <&topckgen CLK_TOP_ETHER_50M_RMII_SEL>; assigned-clock-parents = <&topckgen CLK_TOP_ETHERPLL_125M>, - <&topckgen CLK_TOP_APLL1_D3>; + <&topckgen CLK_TOP_APLL1_D3>, + <&topckgen CLK_TOP_ETHERPLL_50M>; + power-domains = <&scpsys MT2712_POWER_DOMAIN_AUDIO>; mediatek,pericfg = <&pericfg>; mediatek,tx-delay-ps = <1530>; mediatek,rx-delay-ps = <1530>; mediatek,rmii-rxc; mediatek,txc-inverse; mediatek,rxc-inverse; - snps,txpbl = <32>; - snps,rxpbl = <32>; + snps,txpbl = <1>; + snps,rxpbl = <1>; snps,reset-gpio = <&pio 87 GPIO_ACTIVE_LOW>; snps,reset-active-low; }; diff --git a/Documentation/devicetree/bindings/net/qualcomm-bluetooth.txt b/Documentation/devicetree/bindings/net/qualcomm-bluetooth.txt index 68b67d9db63a..999aceadb985 100644 --- a/Documentation/devicetree/bindings/net/qualcomm-bluetooth.txt +++ b/Documentation/devicetree/bindings/net/qualcomm-bluetooth.txt @@ -11,6 +11,7 @@ Required properties: - compatible: should contain one of the following: * "qcom,qca6174-bt" * "qcom,wcn3990-bt" + * "qcom,wcn3991-bt" * "qcom,wcn3998-bt" Optional properties for compatible string qcom,qca6174-bt: diff --git a/Documentation/devicetree/bindings/net/renesas,ravb.txt b/Documentation/devicetree/bindings/net/renesas,ravb.txt index 5df4aa7f6811..87dad2dd8ca0 100644 --- a/Documentation/devicetree/bindings/net/renesas,ravb.txt +++ b/Documentation/devicetree/bindings/net/renesas,ravb.txt @@ -21,7 +21,8 @@ Required properties: - "renesas,etheravb-r8a774b1" for the R8A774B1 SoC. - "renesas,etheravb-r8a774c0" for the R8A774C0 SoC. - "renesas,etheravb-r8a7795" for the R8A7795 SoC. - - "renesas,etheravb-r8a7796" for the R8A7796 SoC. + - "renesas,etheravb-r8a7796" for the R8A77960 SoC. + - "renesas,etheravb-r8a77961" for the R8A77961 SoC. - "renesas,etheravb-r8a77965" for the R8A77965 SoC. - "renesas,etheravb-r8a77970" for the R8A77970 SoC. - "renesas,etheravb-r8a77980" for the R8A77980 SoC. @@ -37,8 +38,8 @@ Required properties: - reg: Offset and length of (1) the register block and (2) the stream buffer. The region for the register block is mandatory. The region for the stream buffer is optional, as it is only present on - R-Car Gen2 and RZ/G1 SoCs, and on R-Car H3 (R8A7795), M3-W (R8A7796), - and M3-N (R8A77965). + R-Car Gen2 and RZ/G1 SoCs, and on R-Car H3 (R8A7795), M3-W (R8A77960), + M3-W+ (R8A77961), and M3-N (R8A77965). - interrupts: A list of interrupt-specifiers, one for each entry in interrupt-names. If interrupt-names is not present, an interrupt specifier diff --git a/Documentation/devicetree/bindings/net/ti,dp83867.txt b/Documentation/devicetree/bindings/net/ti,dp83867.txt index 388ff48f53ae..44e2a4fab29e 100644 --- a/Documentation/devicetree/bindings/net/ti,dp83867.txt +++ b/Documentation/devicetree/bindings/net/ti,dp83867.txt @@ -8,8 +8,6 @@ Required properties: - ti,tx-internal-delay - RGMII Transmit Clock Delay - see dt-bindings/net/ti-dp83867.h for applicable values. Required only if interface type is PHY_INTERFACE_MODE_RGMII_ID or PHY_INTERFACE_MODE_RGMII_TXID - - ti,fifo-depth - Transmitt FIFO depth- see dt-bindings/net/ti-dp83867.h - for applicable values Note: If the interface type is PHY_INTERFACE_MODE_RGMII the TX/RX clock delays will be left at their default values, as set by the PHY's pin strapping. @@ -42,6 +40,14 @@ Optional property: Some MACs work with differential SGMII clock. See data manual for details. + - ti,fifo-depth - Transmitt FIFO depth- see dt-bindings/net/ti-dp83867.h + for applicable values (deprecated) + + -tx-fifo-depth - As defined in the ethernet-controller.yaml. Values for + the depth can be found in dt-bindings/net/ti-dp83867.h + -rx-fifo-depth - As defined in the ethernet-controller.yaml. Values for + the depth can be found in dt-bindings/net/ti-dp83867.h + Note: ti,min-output-impedance and ti,max-output-impedance are mutually exclusive. When both properties are present ti,max-output-impedance takes precedence. @@ -55,7 +61,7 @@ Example: reg = <0>; ti,rx-internal-delay = <DP83867_RGMIIDCTL_2_25_NS>; ti,tx-internal-delay = <DP83867_RGMIIDCTL_2_75_NS>; - ti,fifo-depth = <DP83867_PHYCR_FIFO_DEPTH_4_B_NIB>; + tx-fifo-depth = <DP83867_PHYCR_FIFO_DEPTH_4_B_NIB>; }; Datasheet can be found: diff --git a/Documentation/devicetree/bindings/net/wireless/qcom,ath10k.txt b/Documentation/devicetree/bindings/net/wireless/qcom,ath10k.txt index 017128394a3e..616c87746d6f 100644 --- a/Documentation/devicetree/bindings/net/wireless/qcom,ath10k.txt +++ b/Documentation/devicetree/bindings/net/wireless/qcom,ath10k.txt @@ -50,7 +50,7 @@ Optional properties: entry in clock-names. - clock-names: Should contain the clock names "wifi_wcss_cmd", "wifi_wcss_ref", "wifi_wcss_rtc" for "qcom,ipq4019-wifi" compatible target and - "cxo_ref_clk_pin" for "qcom,wcn3990-wifi" + "cxo_ref_clk_pin" and optionally "qdss" for "qcom,wcn3990-wifi" compatible target. - qcom,msi_addr: MSI interrupt address. - qcom,msi_base: Base value to add before writing MSI data into @@ -88,6 +88,9 @@ Optional properties: of the host capability QMI request - qcom,xo-cal-data: xo cal offset to be configured in xo trim register. +- qcom,msa-fixed-perm: Boolean context flag to disable SCM call for statically + mapped msa region. + Example (to supply PCI based wifi block details): In this example, the node is defined as child node of the PCI controller. @@ -185,4 +188,5 @@ wifi@18000000 { vdd-3.3-ch0-supply = <&vreg_l25a_3p3>; memory-region = <&wifi_msa_mem>; iommus = <&apps_smmu 0x0040 0x1>; + qcom,msa-fixed-perm; }; diff --git a/Documentation/devicetree/bindings/net/wireless/qcom,ath11k.yaml b/Documentation/devicetree/bindings/net/wireless/qcom,ath11k.yaml new file mode 100644 index 000000000000..a1717db36dba --- /dev/null +++ b/Documentation/devicetree/bindings/net/wireless/qcom,ath11k.yaml @@ -0,0 +1,273 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +# Copyright (c) 2018-2019 The Linux Foundation. All rights reserved. + +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/net/wireless/qcom,ath11k.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Qualcomm Technologies ath11k wireless devices Generic Binding + +maintainers: + - Kalle Valo <kvalo@codeaurora.org> + +description: | + These are dt entries for Qualcomm Technologies, Inc. IEEE 802.11ax + devices, for example like AHB based IPQ8074. + +properties: + compatible: + const: qcom,ipq8074-wifi + + reg: + maxItems: 1 + + interrupts: + items: + - description: misc-pulse1 interrupt events + - description: misc-latch interrupt events + - description: sw exception interrupt events + - description: watchdog interrupt events + - description: interrupt event for ring CE0 + - description: interrupt event for ring CE1 + - description: interrupt event for ring CE2 + - description: interrupt event for ring CE3 + - description: interrupt event for ring CE4 + - description: interrupt event for ring CE5 + - description: interrupt event for ring CE6 + - description: interrupt event for ring CE7 + - description: interrupt event for ring CE8 + - description: interrupt event for ring CE9 + - description: interrupt event for ring CE10 + - description: interrupt event for ring CE11 + - description: interrupt event for ring host2wbm-desc-feed + - description: interrupt event for ring host2reo-re-injection + - description: interrupt event for ring host2reo-command + - description: interrupt event for ring host2rxdma-monitor-ring3 + - description: interrupt event for ring host2rxdma-monitor-ring2 + - description: interrupt event for ring host2rxdma-monitor-ring1 + - description: interrupt event for ring reo2ost-exception + - description: interrupt event for ring wbm2host-rx-release + - description: interrupt event for ring reo2host-status + - description: interrupt event for ring reo2host-destination-ring4 + - description: interrupt event for ring reo2host-destination-ring3 + - description: interrupt event for ring reo2host-destination-ring2 + - description: interrupt event for ring reo2host-destination-ring1 + - description: interrupt event for ring rxdma2host-monitor-destination-mac3 + - description: interrupt event for ring rxdma2host-monitor-destination-mac2 + - description: interrupt event for ring rxdma2host-monitor-destination-mac1 + - description: interrupt event for ring ppdu-end-interrupts-mac3 + - description: interrupt event for ring ppdu-end-interrupts-mac2 + - description: interrupt event for ring ppdu-end-interrupts-mac1 + - description: interrupt event for ring rxdma2host-monitor-status-ring-mac3 + - description: interrupt event for ring rxdma2host-monitor-status-ring-mac2 + - description: interrupt event for ring rxdma2host-monitor-status-ring-mac1 + - description: interrupt event for ring host2rxdma-host-buf-ring-mac3 + - description: interrupt event for ring host2rxdma-host-buf-ring-mac2 + - description: interrupt event for ring host2rxdma-host-buf-ring-mac1 + - description: interrupt event for ring rxdma2host-destination-ring-mac3 + - description: interrupt event for ring rxdma2host-destination-ring-mac2 + - description: interrupt event for ring rxdma2host-destination-ring-mac1 + - description: interrupt event for ring host2tcl-input-ring4 + - description: interrupt event for ring host2tcl-input-ring3 + - description: interrupt event for ring host2tcl-input-ring2 + - description: interrupt event for ring host2tcl-input-ring1 + - description: interrupt event for ring wbm2host-tx-completions-ring3 + - description: interrupt event for ring wbm2host-tx-completions-ring2 + - description: interrupt event for ring wbm2host-tx-completions-ring1 + - description: interrupt event for ring tcl2host-status-ring + + + interrupt-names: + items: + - const: misc-pulse1 + - const: misc-latch + - const: sw-exception + - const: watchdog + - const: ce0 + - const: ce1 + - const: ce2 + - const: ce3 + - const: ce4 + - const: ce5 + - const: ce6 + - const: ce7 + - const: ce8 + - const: ce9 + - const: ce10 + - const: ce11 + - const: host2wbm-desc-feed + - const: host2reo-re-injection + - const: host2reo-command + - const: host2rxdma-monitor-ring3 + - const: host2rxdma-monitor-ring2 + - const: host2rxdma-monitor-ring1 + - const: reo2ost-exception + - const: wbm2host-rx-release + - const: reo2host-status + - const: reo2host-destination-ring4 + - const: reo2host-destination-ring3 + - const: reo2host-destination-ring2 + - const: reo2host-destination-ring1 + - const: rxdma2host-monitor-destination-mac3 + - const: rxdma2host-monitor-destination-mac2 + - const: rxdma2host-monitor-destination-mac1 + - const: ppdu-end-interrupts-mac3 + - const: ppdu-end-interrupts-mac2 + - const: ppdu-end-interrupts-mac1 + - const: rxdma2host-monitor-status-ring-mac3 + - const: rxdma2host-monitor-status-ring-mac2 + - const: rxdma2host-monitor-status-ring-mac1 + - const: host2rxdma-host-buf-ring-mac3 + - const: host2rxdma-host-buf-ring-mac2 + - const: host2rxdma-host-buf-ring-mac1 + - const: rxdma2host-destination-ring-mac3 + - const: rxdma2host-destination-ring-mac2 + - const: rxdma2host-destination-ring-mac1 + - const: host2tcl-input-ring4 + - const: host2tcl-input-ring3 + - const: host2tcl-input-ring2 + - const: host2tcl-input-ring1 + - const: wbm2host-tx-completions-ring3 + - const: wbm2host-tx-completions-ring2 + - const: wbm2host-tx-completions-ring1 + - const: tcl2host-status-ring + + qcom,rproc: + $ref: /schemas/types.yaml#definitions/phandle + description: + DT entry of q6v5-wcss remoteproc driver. + Phandle to a node that can contain the following properties + * compatible + * reg + * reg-names + +required: + - compatible + - reg + - interrupts + - interrupt-names + - qcom,rproc + +additionalProperties: false + +examples: + - | + + q6v5_wcss: q6v5_wcss@CD00000 { + compatible = "qcom,ipq8074-wcss-pil"; + reg = <0xCD00000 0x4040>, + <0x4AB000 0x20>; + reg-names = "qdsp6", + "rmb"; + }; + + wifi0: wifi@c000000 { + compatible = "qcom,ipq8074-wifi"; + reg = <0xc000000 0x2000000>; + interrupts = <0 320 1>, + <0 319 1>, + <0 318 1>, + <0 317 1>, + <0 316 1>, + <0 315 1>, + <0 314 1>, + <0 311 1>, + <0 310 1>, + <0 411 1>, + <0 410 1>, + <0 40 1>, + <0 39 1>, + <0 302 1>, + <0 301 1>, + <0 37 1>, + <0 36 1>, + <0 296 1>, + <0 295 1>, + <0 294 1>, + <0 293 1>, + <0 292 1>, + <0 291 1>, + <0 290 1>, + <0 289 1>, + <0 288 1>, + <0 239 1>, + <0 236 1>, + <0 235 1>, + <0 234 1>, + <0 233 1>, + <0 232 1>, + <0 231 1>, + <0 230 1>, + <0 229 1>, + <0 228 1>, + <0 224 1>, + <0 223 1>, + <0 203 1>, + <0 183 1>, + <0 180 1>, + <0 179 1>, + <0 178 1>, + <0 177 1>, + <0 176 1>, + <0 163 1>, + <0 162 1>, + <0 160 1>, + <0 159 1>, + <0 158 1>, + <0 157 1>, + <0 156 1>; + interrupt-names = "misc-pulse1", + "misc-latch", + "sw-exception", + "watchdog", + "ce0", + "ce1", + "ce2", + "ce3", + "ce4", + "ce5", + "ce6", + "ce7", + "ce8", + "ce9", + "ce10", + "ce11", + "host2wbm-desc-feed", + "host2reo-re-injection", + "host2reo-command", + "host2rxdma-monitor-ring3", + "host2rxdma-monitor-ring2", + "host2rxdma-monitor-ring1", + "reo2ost-exception", + "wbm2host-rx-release", + "reo2host-status", + "reo2host-destination-ring4", + "reo2host-destination-ring3", + "reo2host-destination-ring2", + "reo2host-destination-ring1", + "rxdma2host-monitor-destination-mac3", + "rxdma2host-monitor-destination-mac2", + "rxdma2host-monitor-destination-mac1", + "ppdu-end-interrupts-mac3", + "ppdu-end-interrupts-mac2", + "ppdu-end-interrupts-mac1", + "rxdma2host-monitor-status-ring-mac3", + "rxdma2host-monitor-status-ring-mac2", + "rxdma2host-monitor-status-ring-mac1", + "host2rxdma-host-buf-ring-mac3", + "host2rxdma-host-buf-ring-mac2", + "host2rxdma-host-buf-ring-mac1", + "rxdma2host-destination-ring-mac3", + "rxdma2host-destination-ring-mac2", + "rxdma2host-destination-ring-mac1", + "host2tcl-input-ring4", + "host2tcl-input-ring3", + "host2tcl-input-ring2", + "host2tcl-input-ring1", + "wbm2host-tx-completions-ring3", + "wbm2host-tx-completions-ring2", + "wbm2host-tx-completions-ring1", + "tcl2host-status-ring"; + qcom,rproc = <&q6v5_wcss>; + }; diff --git a/Documentation/devicetree/bindings/nvmem/imx-ocotp.txt b/Documentation/devicetree/bindings/nvmem/imx-ocotp.txt index 904dadf3d07b..6e346d5cddcf 100644 --- a/Documentation/devicetree/bindings/nvmem/imx-ocotp.txt +++ b/Documentation/devicetree/bindings/nvmem/imx-ocotp.txt @@ -2,7 +2,7 @@ Freescale i.MX6 On-Chip OTP Controller (OCOTP) device tree bindings This binding represents the on-chip eFuse OTP controller found on i.MX6Q/D, i.MX6DL/S, i.MX6SL, i.MX6SX, i.MX6UL, i.MX6ULL/ULZ, i.MX6SLL, -i.MX7D/S, i.MX7ULP, i.MX8MQ, i.MX8MM and i.MX8MN SoCs. +i.MX7D/S, i.MX7ULP, i.MX8MQ, i.MX8MM, i.MX8MN and i.MX8MP SoCs. Required properties: - compatible: should be one of @@ -17,6 +17,7 @@ Required properties: "fsl,imx8mq-ocotp" (i.MX8MQ), "fsl,imx8mm-ocotp" (i.MX8MM), "fsl,imx8mn-ocotp" (i.MX8MN), + "fsl,imx8mp-ocotp" (i.MX8MP), followed by "syscon". - #address-cells : Should be 1 - #size-cells : Should be 1 diff --git a/Documentation/devicetree/bindings/nvmem/nvmem.yaml b/Documentation/devicetree/bindings/nvmem/nvmem.yaml index 1c75a059206c..b43c6c65294e 100644 --- a/Documentation/devicetree/bindings/nvmem/nvmem.yaml +++ b/Documentation/devicetree/bindings/nvmem/nvmem.yaml @@ -34,6 +34,14 @@ properties: description: Mark the provider as read only. + wp-gpios: + description: + GPIO to which the write-protect pin of the chip is connected. + The write-protect GPIO is asserted, when it's driven high + (logical '1') to block the write operation. It's deasserted, + when it's driven low (logical '0') to allow writing. + maxItems: 1 + patternProperties: "^.*@[0-9a-f]+$": type: object @@ -63,9 +71,12 @@ patternProperties: examples: - | + #include <dt-bindings/gpio/gpio.h> + qfprom: eeprom@700000 { #address-cells = <1>; #size-cells = <1>; + wp-gpios = <&gpio1 3 GPIO_ACTIVE_HIGH>; /* ... */ diff --git a/Documentation/devicetree/bindings/nvmem/qcom,spmi-sdam.yaml b/Documentation/devicetree/bindings/nvmem/qcom,spmi-sdam.yaml new file mode 100644 index 000000000000..7bbd4e62044e --- /dev/null +++ b/Documentation/devicetree/bindings/nvmem/qcom,spmi-sdam.yaml @@ -0,0 +1,84 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/nvmem/qcom,spmi-sdam.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Qualcomm Technologies, Inc. SPMI SDAM DT bindings + +maintainers: + - Shyam Kumar Thella <sthella@codeaurora.org> + +description: | + The SDAM provides scratch register space for the PMIC clients. This + memory can be used by software to store information or communicate + to/from the PBUS. + +allOf: + - $ref: "nvmem.yaml#" + +properties: + compatible: + enum: + - qcom,spmi-sdam + + reg: + maxItems: 1 + + "#address-cells": + const: 1 + + "#size-cells": + const: 1 + + ranges: true + +required: + - compatible + - reg + - ranges + +patternProperties: + "^.*@[0-9a-f]+$": + type: object + + properties: + reg: + maxItems: 1 + description: + Offset and size in bytes within the storage device. + + bits: + $ref: /schemas/types.yaml#/definitions/uint32-array + maxItems: 1 + items: + items: + - minimum: 0 + maximum: 7 + description: + Offset in bit within the address range specified by reg. + - minimum: 1 + description: + Size in bit within the address range specified by reg. + + required: + - reg + + additionalProperties: false + +examples: + - | + sdam_1: nvram@b000 { + #address-cells = <1>; + #size-cells = <1>; + compatible = "qcom,spmi-sdam"; + reg = <0xb000 0x100>; + ranges = <0 0xb000 0x100>; + + /* Data cells */ + restart_reason: restart@50 { + reg = <0x50 0x1>; + bits = <6 2>; + }; + }; +... diff --git a/Documentation/devicetree/bindings/nvmem/st,stm32-romem.txt b/Documentation/devicetree/bindings/nvmem/st,stm32-romem.txt deleted file mode 100644 index 142a51d5a9be..000000000000 --- a/Documentation/devicetree/bindings/nvmem/st,stm32-romem.txt +++ /dev/null @@ -1,31 +0,0 @@ -STMicroelectronics STM32 Factory-programmed data device tree bindings - -This represents STM32 Factory-programmed read only non-volatile area: locked -flash, OTP, read-only HW regs... This contains various information such as: -analog calibration data for temperature sensor (e.g. TS_CAL1, TS_CAL2), -internal vref (VREFIN_CAL), unique device ID... - -Required properties: -- compatible: Should be one of: - "st,stm32f4-otp" - "st,stm32mp15-bsec" -- reg: Offset and length of factory-programmed area. -- #address-cells: Should be '<1>'. -- #size-cells: Should be '<1>'. - -Optional Data cells: -- Must be child nodes as described in nvmem.txt. - -Example on stm32f4: - romem: nvmem@1fff7800 { - compatible = "st,stm32f4-otp"; - reg = <0x1fff7800 0x400>; - #address-cells = <1>; - #size-cells = <1>; - - /* Data cells: ts_cal1 at 0x1fff7a2c */ - ts_cal1: calib@22c { - reg = <0x22c 0x2>; - }; - ... - }; diff --git a/Documentation/devicetree/bindings/nvmem/st,stm32-romem.yaml b/Documentation/devicetree/bindings/nvmem/st,stm32-romem.yaml new file mode 100644 index 000000000000..d84deb4774a4 --- /dev/null +++ b/Documentation/devicetree/bindings/nvmem/st,stm32-romem.yaml @@ -0,0 +1,46 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/nvmem/st,stm32-romem.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: STMicroelectronics STM32 Factory-programmed data bindings + +description: | + This represents STM32 Factory-programmed read only non-volatile area: locked + flash, OTP, read-only HW regs... This contains various information such as: + analog calibration data for temperature sensor (e.g. TS_CAL1, TS_CAL2), + internal vref (VREFIN_CAL), unique device ID... + +maintainers: + - Fabrice Gasnier <fabrice.gasnier@st.com> + +allOf: + - $ref: "nvmem.yaml#" + +properties: + compatible: + enum: + - st,stm32f4-otp + - st,stm32mp15-bsec + +required: + - "#address-cells" + - "#size-cells" + - compatible + - reg + +examples: + - | + efuse@1fff7800 { + compatible = "st,stm32f4-otp"; + reg = <0x1fff7800 0x400>; + #address-cells = <1>; + #size-cells = <1>; + + calib@22c { + reg = <0x22c 0x2>; + }; + }; + +... diff --git a/Documentation/devicetree/bindings/opp/allwinner,sun50i-h6-operating-points.yaml b/Documentation/devicetree/bindings/opp/allwinner,sun50i-h6-operating-points.yaml new file mode 100644 index 000000000000..aef87a33a7c9 --- /dev/null +++ b/Documentation/devicetree/bindings/opp/allwinner,sun50i-h6-operating-points.yaml @@ -0,0 +1,129 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/opp/allwinner,sun50i-h6-operating-points.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Allwinner H6 CPU OPP Device Tree Bindings + +maintainers: + - Chen-Yu Tsai <wens@csie.org> + - Maxime Ripard <mripard@kernel.org> + +description: | + For some SoCs, the CPU frequency subset and voltage value of each + OPP varies based on the silicon variant in use. Allwinner Process + Voltage Scaling Tables defines the voltage and frequency value based + on the speedbin blown in the efuse combination. The + sun50i-cpufreq-nvmem driver reads the efuse value from the SoC to + provide the OPP framework with required information. + +properties: + compatible: + const: allwinner,sun50i-h6-operating-points + + nvmem-cells: + description: | + A phandle pointing to a nvmem-cells node representing the efuse + registers that has information about the speedbin that is used + to select the right frequency/voltage value pair. Please refer + the for nvmem-cells bindings + Documentation/devicetree/bindings/nvmem/nvmem.txt and also + examples below. + +required: + - compatible + - nvmem-cells + +patternProperties: + "opp-[0-9]+": + type: object + + properties: + opp-hz: true + + patternProperties: + "opp-microvolt-.*": true + + required: + - opp-hz + - opp-microvolt-speed0 + - opp-microvolt-speed1 + - opp-microvolt-speed2 + + unevaluatedProperties: false + +unevaluatedProperties: false + +examples: + - | + cpu_opp_table: opp-table { + compatible = "allwinner,sun50i-h6-operating-points"; + nvmem-cells = <&speedbin_efuse>; + opp-shared; + + opp-480000000 { + clock-latency-ns = <244144>; /* 8 32k periods */ + opp-hz = /bits/ 64 <480000000>; + + opp-microvolt-speed0 = <880000>; + opp-microvolt-speed1 = <820000>; + opp-microvolt-speed2 = <800000>; + }; + + opp-720000000 { + clock-latency-ns = <244144>; /* 8 32k periods */ + opp-hz = /bits/ 64 <720000000>; + + opp-microvolt-speed0 = <880000>; + opp-microvolt-speed1 = <820000>; + opp-microvolt-speed2 = <800000>; + }; + + opp-816000000 { + clock-latency-ns = <244144>; /* 8 32k periods */ + opp-hz = /bits/ 64 <816000000>; + + opp-microvolt-speed0 = <880000>; + opp-microvolt-speed1 = <820000>; + opp-microvolt-speed2 = <800000>; + }; + + opp-888000000 { + clock-latency-ns = <244144>; /* 8 32k periods */ + opp-hz = /bits/ 64 <888000000>; + + opp-microvolt-speed0 = <940000>; + opp-microvolt-speed1 = <820000>; + opp-microvolt-speed2 = <800000>; + }; + + opp-1080000000 { + clock-latency-ns = <244144>; /* 8 32k periods */ + opp-hz = /bits/ 64 <1080000000>; + + opp-microvolt-speed0 = <1060000>; + opp-microvolt-speed1 = <880000>; + opp-microvolt-speed2 = <840000>; + }; + + opp-1320000000 { + clock-latency-ns = <244144>; /* 8 32k periods */ + opp-hz = /bits/ 64 <1320000000>; + + opp-microvolt-speed0 = <1160000>; + opp-microvolt-speed1 = <940000>; + opp-microvolt-speed2 = <900000>; + }; + + opp-1488000000 { + clock-latency-ns = <244144>; /* 8 32k periods */ + opp-hz = /bits/ 64 <1488000000>; + + opp-microvolt-speed0 = <1160000>; + opp-microvolt-speed1 = <1000000>; + opp-microvolt-speed2 = <960000>; + }; + }; + +... diff --git a/Documentation/devicetree/bindings/opp/sun50i-nvmem-cpufreq.txt b/Documentation/devicetree/bindings/opp/sun50i-nvmem-cpufreq.txt deleted file mode 100644 index 7deae57a587b..000000000000 --- a/Documentation/devicetree/bindings/opp/sun50i-nvmem-cpufreq.txt +++ /dev/null @@ -1,167 +0,0 @@ -Allwinner Technologies, Inc. NVMEM CPUFreq and OPP bindings -=================================== - -For some SoCs, the CPU frequency subset and voltage value of each OPP -varies based on the silicon variant in use. Allwinner Process Voltage -Scaling Tables defines the voltage and frequency value based on the -speedbin blown in the efuse combination. The sun50i-cpufreq-nvmem driver -reads the efuse value from the SoC to provide the OPP framework with -required information. - -Required properties: --------------------- -In 'cpus' nodes: -- operating-points-v2: Phandle to the operating-points-v2 table to use. - -In 'operating-points-v2' table: -- compatible: Should be - - 'allwinner,sun50i-h6-operating-points'. -- nvmem-cells: A phandle pointing to a nvmem-cells node representing the - efuse registers that has information about the speedbin - that is used to select the right frequency/voltage value - pair. Please refer the for nvmem-cells bindings - Documentation/devicetree/bindings/nvmem/nvmem.txt and - also examples below. - -In every OPP node: -- opp-microvolt-<name>: Voltage in micro Volts. - At runtime, the platform can pick a <name> and - matching opp-microvolt-<name> property. - [See: opp.txt] - HW: <name>: - sun50i-h6 speed0 speed1 speed2 - -Example 1: ---------- - - cpus { - #address-cells = <1>; - #size-cells = <0>; - - cpu0: cpu@0 { - compatible = "arm,cortex-a53"; - device_type = "cpu"; - reg = <0>; - enable-method = "psci"; - clocks = <&ccu CLK_CPUX>; - clock-latency-ns = <244144>; /* 8 32k periods */ - operating-points-v2 = <&cpu_opp_table>; - #cooling-cells = <2>; - }; - - cpu1: cpu@1 { - compatible = "arm,cortex-a53"; - device_type = "cpu"; - reg = <1>; - enable-method = "psci"; - clocks = <&ccu CLK_CPUX>; - clock-latency-ns = <244144>; /* 8 32k periods */ - operating-points-v2 = <&cpu_opp_table>; - #cooling-cells = <2>; - }; - - cpu2: cpu@2 { - compatible = "arm,cortex-a53"; - device_type = "cpu"; - reg = <2>; - enable-method = "psci"; - clocks = <&ccu CLK_CPUX>; - clock-latency-ns = <244144>; /* 8 32k periods */ - operating-points-v2 = <&cpu_opp_table>; - #cooling-cells = <2>; - }; - - cpu3: cpu@3 { - compatible = "arm,cortex-a53"; - device_type = "cpu"; - reg = <3>; - enable-method = "psci"; - clocks = <&ccu CLK_CPUX>; - clock-latency-ns = <244144>; /* 8 32k periods */ - operating-points-v2 = <&cpu_opp_table>; - #cooling-cells = <2>; - }; - }; - - cpu_opp_table: opp_table { - compatible = "allwinner,sun50i-h6-operating-points"; - nvmem-cells = <&speedbin_efuse>; - opp-shared; - - opp@480000000 { - clock-latency-ns = <244144>; /* 8 32k periods */ - opp-hz = /bits/ 64 <480000000>; - - opp-microvolt-speed0 = <880000>; - opp-microvolt-speed1 = <820000>; - opp-microvolt-speed2 = <800000>; - }; - - opp@720000000 { - clock-latency-ns = <244144>; /* 8 32k periods */ - opp-hz = /bits/ 64 <720000000>; - - opp-microvolt-speed0 = <880000>; - opp-microvolt-speed1 = <820000>; - opp-microvolt-speed2 = <800000>; - }; - - opp@816000000 { - clock-latency-ns = <244144>; /* 8 32k periods */ - opp-hz = /bits/ 64 <816000000>; - - opp-microvolt-speed0 = <880000>; - opp-microvolt-speed1 = <820000>; - opp-microvolt-speed2 = <800000>; - }; - - opp@888000000 { - clock-latency-ns = <244144>; /* 8 32k periods */ - opp-hz = /bits/ 64 <888000000>; - - opp-microvolt-speed0 = <940000>; - opp-microvolt-speed1 = <820000>; - opp-microvolt-speed2 = <800000>; - }; - - opp@1080000000 { - clock-latency-ns = <244144>; /* 8 32k periods */ - opp-hz = /bits/ 64 <1080000000>; - - opp-microvolt-speed0 = <1060000>; - opp-microvolt-speed1 = <880000>; - opp-microvolt-speed2 = <840000>; - }; - - opp@1320000000 { - clock-latency-ns = <244144>; /* 8 32k periods */ - opp-hz = /bits/ 64 <1320000000>; - - opp-microvolt-speed0 = <1160000>; - opp-microvolt-speed1 = <940000>; - opp-microvolt-speed2 = <900000>; - }; - - opp@1488000000 { - clock-latency-ns = <244144>; /* 8 32k periods */ - opp-hz = /bits/ 64 <1488000000>; - - opp-microvolt-speed0 = <1160000>; - opp-microvolt-speed1 = <1000000>; - opp-microvolt-speed2 = <960000>; - }; - }; -.... -soc { -.... - sid: sid@3006000 { - compatible = "allwinner,sun50i-h6-sid"; - reg = <0x03006000 0x400>; - #address-cells = <1>; - #size-cells = <1>; - .... - speedbin_efuse: speed@1c { - reg = <0x1c 4>; - }; - }; -}; diff --git a/Documentation/devicetree/bindings/pci/arm,juno-r1-pcie.txt b/Documentation/devicetree/bindings/pci/arm,juno-r1-pcie.txt deleted file mode 100644 index f7514c170a32..000000000000 --- a/Documentation/devicetree/bindings/pci/arm,juno-r1-pcie.txt +++ /dev/null @@ -1,10 +0,0 @@ -* ARM Juno R1 PCIe interface - -This PCIe host controller is based on PLDA XpressRICH3-AXI IP -and thus inherits all the common properties defined in plda,xpressrich3-axi.txt -as well as the base properties defined in host-generic-pci.txt. - -Required properties: - - compatible: "arm,juno-r1-pcie" - - dma-coherent: The host controller bridges the AXI transactions into PCIe bus - in a manner that makes the DMA operations to appear coherent to the CPUs. diff --git a/Documentation/devicetree/bindings/pci/brcm,stb-pcie.yaml b/Documentation/devicetree/bindings/pci/brcm,stb-pcie.yaml new file mode 100644 index 000000000000..77d3e81a437b --- /dev/null +++ b/Documentation/devicetree/bindings/pci/brcm,stb-pcie.yaml @@ -0,0 +1,97 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/pci/brcm,stb-pcie.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Brcmstb PCIe Host Controller Device Tree Bindings + +maintainers: + - Nicolas Saenz Julienne <nsaenzjulienne@suse.de> + +allOf: + - $ref: /schemas/pci/pci-bus.yaml# + +properties: + compatible: + const: brcm,bcm2711-pcie # The Raspberry Pi 4 + + reg: + maxItems: 1 + + interrupts: + minItems: 1 + maxItems: 2 + items: + - description: PCIe host controller + - description: builtin MSI controller + + interrupt-names: + minItems: 1 + maxItems: 2 + items: + - const: pcie + - const: msi + + ranges: + maxItems: 1 + + dma-ranges: + maxItems: 1 + + clocks: + maxItems: 1 + + clock-names: + items: + - const: sw_pcie + + msi-controller: + description: Identifies the node as an MSI controller. + + msi-parent: + description: MSI controller the device is capable of using. + + brcm,enable-ssc: + description: Indicates usage of spread-spectrum clocking. + type: boolean + +required: + - reg + - dma-ranges + - "#interrupt-cells" + - interrupts + - interrupt-names + - interrupt-map-mask + - interrupt-map + - msi-controller + +unevaluatedProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/irq.h> + #include <dt-bindings/interrupt-controller/arm-gic.h> + + scb { + #address-cells = <2>; + #size-cells = <1>; + pcie0: pcie@7d500000 { + compatible = "brcm,bcm2711-pcie"; + reg = <0x0 0x7d500000 0x9310>; + device_type = "pci"; + #address-cells = <3>; + #size-cells = <2>; + #interrupt-cells = <1>; + interrupts = <GIC_SPI 148 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 148 IRQ_TYPE_LEVEL_HIGH>; + interrupt-names = "pcie", "msi"; + interrupt-map-mask = <0x0 0x0 0x0 0x7>; + interrupt-map = <0 0 0 1 &gicv2 GIC_SPI 143 IRQ_TYPE_LEVEL_HIGH>; + msi-parent = <&pcie0>; + msi-controller; + ranges = <0x02000000 0x0 0xf8000000 0x6 0x00000000 0x0 0x04000000>; + dma-ranges = <0x02000000 0x0 0x00000000 0x0 0x00000000 0x0 0x80000000>; + brcm,enable-ssc; + }; + }; diff --git a/Documentation/devicetree/bindings/pci/designware-pcie-ecam.txt b/Documentation/devicetree/bindings/pci/designware-pcie-ecam.txt deleted file mode 100644 index 515b2f9542e5..000000000000 --- a/Documentation/devicetree/bindings/pci/designware-pcie-ecam.txt +++ /dev/null @@ -1,42 +0,0 @@ -* Synopsys DesignWare PCIe root complex in ECAM shift mode - -In some cases, firmware may already have configured the Synopsys DesignWare -PCIe controller in RC mode with static ATU window mappings that cover all -config, MMIO and I/O spaces in a [mostly] ECAM compatible fashion. -In this case, there is no need for the OS to perform any low level setup -of clocks, PHYs or device registers, nor is there any reason for the driver -to reconfigure ATU windows for config and/or IO space accesses at runtime. - -In cases where the IP was synthesized with a minimum ATU window size of -64 KB, it cannot be supported by the generic ECAM driver, because it -requires special config space accessors that filter accesses to device #1 -and beyond on the first bus. - -Required properties: -- compatible: "marvell,armada8k-pcie-ecam" or - "socionext,synquacer-pcie-ecam" or - "snps,dw-pcie-ecam" (must be preceded by a more specific match) - -Please refer to the binding document of "pci-host-ecam-generic" in the -file host-generic-pci.txt for a description of the remaining required -and optional properties. - -Example: - - pcie1: pcie@7f000000 { - compatible = "socionext,synquacer-pcie-ecam", "snps,dw-pcie-ecam"; - device_type = "pci"; - reg = <0x0 0x7f000000 0x0 0xf00000>; - bus-range = <0x0 0xe>; - #address-cells = <3>; - #size-cells = <2>; - ranges = <0x1000000 0x00 0x00010000 0x00 0x7ff00000 0x0 0x00010000>, - <0x2000000 0x00 0x70000000 0x00 0x70000000 0x0 0x0f000000>, - <0x3000000 0x3f 0x00000000 0x3f 0x00000000 0x1 0x00000000>; - - #interrupt-cells = <0x1>; - interrupt-map-mask = <0x0 0x0 0x0 0x0>; - interrupt-map = <0x0 0x0 0x0 0x0 &gic 0x0 0x0 0x0 182 0x4>; - msi-map = <0x0 &its 0x0 0x10000>; - dma-coherent; - }; diff --git a/Documentation/devicetree/bindings/pci/hisilicon-pcie.txt b/Documentation/devicetree/bindings/pci/hisilicon-pcie.txt index 0dcb87d6554f..d6796ef54ea1 100644 --- a/Documentation/devicetree/bindings/pci/hisilicon-pcie.txt +++ b/Documentation/devicetree/bindings/pci/hisilicon-pcie.txt @@ -41,45 +41,3 @@ Hip05 Example (note that Hip06 is the same except compatible): 0x0 0 0 3 &mbigen_pcie 3 12 0x0 0 0 4 &mbigen_pcie 4 13>; }; - -HiSilicon Hip06/Hip07 PCIe host bridge DT (almost-ECAM) description. - -Some BIOSes place the host controller in a mode where it is ECAM -compliant for all devices other than the root complex. In such cases, -the host controller should be described as below. - -The properties and their meanings are identical to those described in -host-generic-pci.txt except as listed below. - -Properties of the host controller node that differ from -host-generic-pci.txt: - -- compatible : Must be "hisilicon,hip06-pcie-ecam", or - "hisilicon,hip07-pcie-ecam" - -- reg : Two entries: First the ECAM configuration space for any - other bus underneath the root bus. Second, the base - and size of the HiSilicon host bridge registers include - the RC's own config space. - -Example: - pcie0: pcie@a0090000 { - compatible = "hisilicon,hip06-pcie-ecam"; - reg = <0 0xb0000000 0 0x2000000>, /* ECAM configuration space */ - <0 0xa0090000 0 0x10000>; /* host bridge registers */ - bus-range = <0 31>; - msi-map = <0x0000 &its_dsa 0x0000 0x2000>; - msi-map-mask = <0xffff>; - #address-cells = <3>; - #size-cells = <2>; - device_type = "pci"; - dma-coherent; - ranges = <0x02000000 0 0xb2000000 0x0 0xb2000000 0 0x5ff0000 - 0x01000000 0 0 0 0xb7ff0000 0 0x10000>; - #interrupt-cells = <1>; - interrupt-map-mask = <0xf800 0 0 7>; - interrupt-map = <0x0 0 0 1 &mbigen_pcie0 650 4 - 0x0 0 0 2 &mbigen_pcie0 650 4 - 0x0 0 0 3 &mbigen_pcie0 650 4 - 0x0 0 0 4 &mbigen_pcie0 650 4>; - }; diff --git a/Documentation/devicetree/bindings/pci/host-generic-pci.txt b/Documentation/devicetree/bindings/pci/host-generic-pci.txt deleted file mode 100644 index 614b594f4e72..000000000000 --- a/Documentation/devicetree/bindings/pci/host-generic-pci.txt +++ /dev/null @@ -1,101 +0,0 @@ -* Generic PCI host controller - -Firmware-initialised PCI host controllers and PCI emulations, such as the -virtio-pci implementations found in kvmtool and other para-virtualised -systems, do not require driver support for complexities such as regulator -and clock management. In fact, the controller may not even require the -configuration of a control interface by the operating system, instead -presenting a set of fixed windows describing a subset of IO, Memory and -Configuration Spaces. - -Such a controller can be described purely in terms of the standardized device -tree bindings communicated in pci.txt: - - -Properties of the host controller node: - -- compatible : Must be "pci-host-cam-generic" or "pci-host-ecam-generic" - depending on the layout of configuration space (CAM vs - ECAM respectively). - -- device_type : Must be "pci". - -- ranges : As described in IEEE Std 1275-1994, but must provide - at least a definition of non-prefetchable memory. One - or both of prefetchable Memory and IO Space may also - be provided. - -- bus-range : Optional property (also described in IEEE Std 1275-1994) - to indicate the range of bus numbers for this controller. - If absent, defaults to <0 255> (i.e. all buses). - -- #address-cells : Must be 3. - -- #size-cells : Must be 2. - -- reg : The Configuration Space base address and size, as accessed - from the parent bus. The base address corresponds to - the first bus in the "bus-range" property. If no - "bus-range" is specified, this will be bus 0 (the default). - -Properties of the /chosen node: - -- linux,pci-probe-only - : Optional property which takes a single-cell argument. - If '0', then Linux will assign devices in its usual manner, - otherwise it will not try to assign devices and instead use - them as they are configured already. - -Configuration Space is assumed to be memory-mapped (as opposed to being -accessed via an ioport) and laid out with a direct correspondence to the -geography of a PCI bus address by concatenating the various components to -form an offset. - -For CAM, this 24-bit offset is: - - cfg_offset(bus, device, function, register) = - bus << 16 | device << 11 | function << 8 | register - -While ECAM extends this by 4 bits to accommodate 4k of function space: - - cfg_offset(bus, device, function, register) = - bus << 20 | device << 15 | function << 12 | register - -Interrupt mapping is exactly as described in `Open Firmware Recommended -Practice: Interrupt Mapping' and requires the following properties: - -- #interrupt-cells : Must be 1 - -- interrupt-map : <see aforementioned specification> - -- interrupt-map-mask : <see aforementioned specification> - - -Example: - -pci { - compatible = "pci-host-cam-generic" - device_type = "pci"; - #address-cells = <3>; - #size-cells = <2>; - bus-range = <0x0 0x1>; - - // CPU_PHYSICAL(2) SIZE(2) - reg = <0x0 0x40000000 0x0 0x1000000>; - - // BUS_ADDRESS(3) CPU_PHYSICAL(2) SIZE(2) - ranges = <0x01000000 0x0 0x01000000 0x0 0x01000000 0x0 0x00010000>, - <0x02000000 0x0 0x41000000 0x0 0x41000000 0x0 0x3f000000>; - - - #interrupt-cells = <0x1>; - - // PCI_DEVICE(3) INT#(1) CONTROLLER(PHANDLE) CONTROLLER_DATA(3) - interrupt-map = < 0x0 0x0 0x0 0x1 &gic 0x0 0x4 0x1 - 0x800 0x0 0x0 0x1 &gic 0x0 0x5 0x1 - 0x1000 0x0 0x0 0x1 &gic 0x0 0x6 0x1 - 0x1800 0x0 0x0 0x1 &gic 0x0 0x7 0x1>; - - // PCI_DEVICE(3) INT#(1) - interrupt-map-mask = <0xf800 0x0 0x0 0x7>; -} diff --git a/Documentation/devicetree/bindings/pci/host-generic-pci.yaml b/Documentation/devicetree/bindings/pci/host-generic-pci.yaml new file mode 100644 index 000000000000..47353d0cd394 --- /dev/null +++ b/Documentation/devicetree/bindings/pci/host-generic-pci.yaml @@ -0,0 +1,172 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/pci/host-generic-pci.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Generic PCI host controller + +maintainers: + - Will Deacon <will@kernel.org> + +description: | + Firmware-initialised PCI host controllers and PCI emulations, such as the + virtio-pci implementations found in kvmtool and other para-virtualised + systems, do not require driver support for complexities such as regulator + and clock management. In fact, the controller may not even require the + configuration of a control interface by the operating system, instead + presenting a set of fixed windows describing a subset of IO, Memory and + Configuration Spaces. + + Configuration Space is assumed to be memory-mapped (as opposed to being + accessed via an ioport) and laid out with a direct correspondence to the + geography of a PCI bus address by concatenating the various components to + form an offset. + + For CAM, this 24-bit offset is: + + cfg_offset(bus, device, function, register) = + bus << 16 | device << 11 | function << 8 | register + + While ECAM extends this by 4 bits to accommodate 4k of function space: + + cfg_offset(bus, device, function, register) = + bus << 20 | device << 15 | function << 12 | register + +properties: + compatible: + description: Depends on the layout of configuration space (CAM vs ECAM + respectively). May also have more specific compatibles. + oneOf: + - description: + PCIe host controller in Arm Juno based on PLDA XpressRICH3-AXI IP + items: + - const: arm,juno-r1-pcie + - const: plda,xpressrich3-axi + - const: pci-host-ecam-generic + - description: | + ThunderX PCI host controller for pass-1.x silicon + + Firmware-initialized PCI host controller to on-chip devices found on + some Cavium ThunderX processors. These devices have ECAM-based config + access, but the BARs are all at fixed addresses. We handle the fixed + addresses by synthesizing Enhanced Allocation (EA) capabilities for + these devices. + const: cavium,pci-host-thunder-ecam + - description: + Cavium ThunderX PEM firmware-initialized PCIe host controller + const: cavium,pci-host-thunder-pem + - description: + HiSilicon Hip06/Hip07 PCIe host bridge in almost-ECAM mode. Some + firmware places the host controller in a mode where it is ECAM + compliant for all devices other than the root complex. + enum: + - hisilicon,hip06-pcie-ecam + - hisilicon,hip07-pcie-ecam + - description: | + In some cases, firmware may already have configured the Synopsys + DesignWare PCIe controller in RC mode with static ATU window mappings + that cover all config, MMIO and I/O spaces in a [mostly] ECAM + compatible fashion. In this case, there is no need for the OS to + perform any low level setup of clocks, PHYs or device registers, nor + is there any reason for the driver to reconfigure ATU windows for + config and/or IO space accesses at runtime. + + In cases where the IP was synthesized with a minimum ATU window size + of 64 KB, it cannot be supported by the generic ECAM driver, because + it requires special config space accessors that filter accesses to + device #1 and beyond on the first bus. + items: + - enum: + - marvell,armada8k-pcie-ecam + - socionext,synquacer-pcie-ecam + - const: snps,dw-pcie-ecam + - description: + CAM or ECAM compliant PCI host controllers without any quirks + enum: + - pci-host-cam-generic + - pci-host-ecam-generic + + reg: + description: + The Configuration Space base address and size, as accessed from the parent + bus. The base address corresponds to the first bus in the "bus-range" + property. If no "bus-range" is specified, this will be bus 0 (the + default). Some host controllers have a 2nd non-compliant address range, + so 2 entries are allowed. + minItems: 1 + maxItems: 2 + + ranges: + description: + As described in IEEE Std 1275-1994, but must provide at least a + definition of non-prefetchable memory. One or both of prefetchable Memory + and IO Space may also be provided. + minItems: 1 + maxItems: 3 + + dma-coherent: true + +required: + - compatible + - reg + - ranges + +allOf: + - $ref: /schemas/pci/pci-bus.yaml# + - if: + properties: + compatible: + contains: + const: arm,juno-r1-pcie + then: + required: + - dma-coherent + + - if: + properties: + compatible: + not: + contains: + enum: + - cavium,pci-host-thunder-pem + - hisilicon,hip06-pcie-ecam + - hisilicon,hip07-pcie-ecam + then: + properties: + reg: + maxItems: 1 + +examples: + - | + + bus { + #address-cells = <2>; + #size-cells = <2>; + pcie@40000000 { + compatible = "pci-host-cam-generic"; + device_type = "pci"; + #address-cells = <3>; + #size-cells = <2>; + bus-range = <0x0 0x1>; + + // CPU_PHYSICAL(2) SIZE(2) + reg = <0x0 0x40000000 0x0 0x1000000>; + + // BUS_ADDRESS(3) CPU_PHYSICAL(2) SIZE(2) + ranges = <0x01000000 0x0 0x01000000 0x0 0x01000000 0x0 0x00010000>, + <0x02000000 0x0 0x41000000 0x0 0x41000000 0x0 0x3f000000>; + + #interrupt-cells = <0x1>; + + // PCI_DEVICE(3) INT#(1) CONTROLLER(PHANDLE) CONTROLLER_DATA(3) + interrupt-map = < 0x0 0x0 0x0 0x1 &gic 0x0 0x4 0x1>, + < 0x800 0x0 0x0 0x1 &gic 0x0 0x5 0x1>, + <0x1000 0x0 0x0 0x1 &gic 0x0 0x6 0x1>, + <0x1800 0x0 0x0 0x1 &gic 0x0 0x7 0x1>; + + // PCI_DEVICE(3) INT#(1) + interrupt-map-mask = <0xf800 0x0 0x0 0x7>; + }; + }; +... diff --git a/Documentation/devicetree/bindings/pci/intel-gw-pcie.yaml b/Documentation/devicetree/bindings/pci/intel-gw-pcie.yaml new file mode 100644 index 000000000000..48a98dae00de --- /dev/null +++ b/Documentation/devicetree/bindings/pci/intel-gw-pcie.yaml @@ -0,0 +1,136 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/pci/intel-gw-pcie.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: PCIe RC controller on Intel Gateway SoCs + +maintainers: + - Dilip Kota <eswara.kota@linux.intel.com> + +properties: + compatible: + items: + - const: intel,lgm-pcie + - const: snps,dw-pcie + + device_type: + const: pci + + "#address-cells": + const: 3 + + "#size-cells": + const: 2 + + reg: + items: + - description: Controller control and status registers. + - description: PCIe configuration registers. + - description: Controller application registers. + + reg-names: + items: + - const: dbi + - const: config + - const: app + + ranges: + maxItems: 1 + + resets: + maxItems: 1 + + clocks: + maxItems: 1 + + phys: + maxItems: 1 + + phy-names: + const: pcie + + reset-gpios: + maxItems: 1 + + linux,pci-domain: true + + num-lanes: + maximum: 2 + description: Number of lanes to use for this port. + + '#interrupt-cells': + const: 1 + + interrupt-map-mask: + description: Standard PCI IRQ mapping properties. + + interrupt-map: + description: Standard PCI IRQ mapping properties. + + max-link-speed: + description: Specify PCI Gen for link capability. + allOf: + - $ref: /schemas/types.yaml#/definitions/uint32 + - enum: [ 1, 2, 3, 4 ] + - default: 1 + + bus-range: + description: Range of bus numbers associated with this controller. + + reset-assert-ms: + description: | + Delay after asserting reset to the PCIe device. + maximum: 500 + default: 100 + +required: + - compatible + - device_type + - "#address-cells" + - "#size-cells" + - reg + - reg-names + - ranges + - resets + - clocks + - phys + - phy-names + - reset-gpios + - '#interrupt-cells' + - interrupt-map + - interrupt-map-mask + +additionalProperties: false + +examples: + - | + #include <dt-bindings/gpio/gpio.h> + pcie10: pcie@d0e00000 { + compatible = "intel,lgm-pcie", "snps,dw-pcie"; + device_type = "pci"; + #address-cells = <3>; + #size-cells = <2>; + reg = <0xd0e00000 0x1000>, + <0xd2000000 0x800000>, + <0xd0a41000 0x1000>; + reg-names = "dbi", "config", "app"; + linux,pci-domain = <0>; + max-link-speed = <4>; + bus-range = <0x00 0x08>; + #interrupt-cells = <1>; + interrupt-map-mask = <0 0 0 0x7>; + interrupt-map = <0 0 0 1 &ioapic1 27 1>, + <0 0 0 2 &ioapic1 28 1>, + <0 0 0 3 &ioapic1 29 1>, + <0 0 0 4 &ioapic1 30 1>; + ranges = <0x02000000 0 0xd4000000 0xd4000000 0 0x04000000>; + resets = <&rcu0 0x50 0>; + clocks = <&cgu0 120>; + phys = <&cb0phy0>; + phy-names = "pcie"; + reset-assert-ms = <500>; + reset-gpios = <&gpio0 3 GPIO_ACTIVE_LOW>; + num-lanes = <2>; + }; diff --git a/Documentation/devicetree/bindings/pci/pci-thunder-ecam.txt b/Documentation/devicetree/bindings/pci/pci-thunder-ecam.txt deleted file mode 100644 index f478874b79ce..000000000000 --- a/Documentation/devicetree/bindings/pci/pci-thunder-ecam.txt +++ /dev/null @@ -1,30 +0,0 @@ -* ThunderX PCI host controller for pass-1.x silicon - -Firmware-initialized PCI host controller to on-chip devices found on -some Cavium ThunderX processors. These devices have ECAM-based config -access, but the BARs are all at fixed addresses. We handle the fixed -addresses by synthesizing Enhanced Allocation (EA) capabilities for -these devices. - -The properties and their meanings are identical to those described in -host-generic-pci.txt except as listed below. - -Properties of the host controller node that differ from -host-generic-pci.txt: - -- compatible : Must be "cavium,pci-host-thunder-ecam" - -Example: - - pcie@84b000000000 { - compatible = "cavium,pci-host-thunder-ecam"; - device_type = "pci"; - msi-parent = <&its>; - msi-map = <0 &its 0x30000 0x10000>; - bus-range = <0 31>; - #size-cells = <2>; - #address-cells = <3>; - #stream-id-cells = <1>; - reg = <0x84b0 0x00000000 0 0x02000000>; /* Configuration space */ - ranges = <0x03000000 0x8180 0x00000000 0x8180 0x00000000 0x80 0x00000000>; /* mem ranges */ - }; diff --git a/Documentation/devicetree/bindings/pci/pci-thunder-pem.txt b/Documentation/devicetree/bindings/pci/pci-thunder-pem.txt deleted file mode 100644 index f131faea3b7c..000000000000 --- a/Documentation/devicetree/bindings/pci/pci-thunder-pem.txt +++ /dev/null @@ -1,43 +0,0 @@ -* ThunderX PEM PCIe host controller - -Firmware-initialized PCI host controller found on some Cavium -ThunderX processors. - -The properties and their meanings are identical to those described in -host-generic-pci.txt except as listed below. - -Properties of the host controller node that differ from -host-generic-pci.txt: - -- compatible : Must be "cavium,pci-host-thunder-pem" - -- reg : Two entries: First the configuration space for down - stream devices base address and size, as accessed - from the parent bus. Second, the register bank of - the PEM device PCIe bridge. - -Example: - - pci@87e0,c2000000 { - compatible = "cavium,pci-host-thunder-pem"; - device_type = "pci"; - msi-parent = <&its>; - msi-map = <0 &its 0x10000 0x10000>; - bus-range = <0x8f 0xc7>; - #size-cells = <2>; - #address-cells = <3>; - - reg = <0x8880 0x8f000000 0x0 0x39000000>, /* Configuration space */ - <0x87e0 0xc2000000 0x0 0x00010000>; /* PEM space */ - ranges = <0x01000000 0x00 0x00020000 0x88b0 0x00020000 0x00 0x00010000>, /* I/O */ - <0x03000000 0x00 0x10000000 0x8890 0x10000000 0x0f 0xf0000000>, /* mem64 */ - <0x43000000 0x10 0x00000000 0x88a0 0x00000000 0x10 0x00000000>, /* mem64-pref */ - <0x03000000 0x87e0 0xc2f00000 0x87e0 0xc2000000 0x00 0x00100000>; /* mem64 PEM BAR4 */ - - #interrupt-cells = <1>; - interrupt-map-mask = <0 0 0 7>; - interrupt-map = <0 0 0 1 &gic0 0 0 0 24 4>, /* INTA */ - <0 0 0 2 &gic0 0 0 0 25 4>, /* INTB */ - <0 0 0 3 &gic0 0 0 0 26 4>, /* INTC */ - <0 0 0 4 &gic0 0 0 0 27 4>; /* INTD */ - }; diff --git a/Documentation/devicetree/bindings/pci/plda,xpressrich3-axi.txt b/Documentation/devicetree/bindings/pci/plda,xpressrich3-axi.txt deleted file mode 100644 index f3f75bfb42bc..000000000000 --- a/Documentation/devicetree/bindings/pci/plda,xpressrich3-axi.txt +++ /dev/null @@ -1,12 +0,0 @@ -* PLDA XpressRICH3-AXI host controller - -The PLDA XpressRICH3-AXI host controller can be configured in a manner that -makes it compliant with the SBSA[1] standard published by ARM Ltd. For those -scenarios, the host-generic-pci.txt bindings apply with the following additions -to the compatible property: - -Required properties: - - compatible: should contain "plda,xpressrich3-axi" to identify the IP used. - - -[1] http://infocenter.arm.com/help/topic/com.arm.doc.den0029a/ diff --git a/Documentation/devicetree/bindings/pci/qcom,pcie.txt b/Documentation/devicetree/bindings/pci/qcom,pcie.txt index ada80b01bf0c..981b4de12807 100644 --- a/Documentation/devicetree/bindings/pci/qcom,pcie.txt +++ b/Documentation/devicetree/bindings/pci/qcom,pcie.txt @@ -11,6 +11,7 @@ - "qcom,pcie-ipq4019" for ipq4019 - "qcom,pcie-ipq8074" for ipq8074 - "qcom,pcie-qcs404" for qcs404 + - "qcom,pcie-sdm845" for sdm845 - reg: Usage: required @@ -126,6 +127,18 @@ - "master_bus" AXI Master clock - "slave_bus" AXI Slave clock +-clock-names: + Usage: required for sdm845 + Value type: <stringlist> + Definition: Should contain the following entries + - "aux" Auxiliary clock + - "cfg" Configuration clock + - "bus_master" Master AXI clock + - "bus_slave" Slave AXI clock + - "slave_q2a" Slave Q2A clock + - "tbu" PCIe TBU clock + - "pipe" PIPE clock + - resets: Usage: required Value type: <prop-encoded-array> @@ -188,6 +201,12 @@ - "pwr" PWR reset - "ahb" AHB reset +- reset-names: + Usage: required for sdm845 + Value type: <stringlist> + Definition: Should contain the following entries + - "pci" PCIe core reset + - power-domains: Usage: required for apq8084 and msm8996/apq8096 Value type: <prop-encoded-array> diff --git a/Documentation/devicetree/bindings/pci/versatile.txt b/Documentation/devicetree/bindings/pci/versatile.txt deleted file mode 100644 index 0a702b13d2ac..000000000000 --- a/Documentation/devicetree/bindings/pci/versatile.txt +++ /dev/null @@ -1,59 +0,0 @@ -* ARM Versatile Platform Baseboard PCI interface - -PCI host controller found on the ARM Versatile PB board's FPGA. - -Required properties: -- compatible: should contain "arm,versatile-pci" to identify the Versatile PCI - controller. -- reg: base addresses and lengths of the PCI controller. There must be 3 - entries: - - Versatile-specific registers - - Self Config space - - Config space -- #address-cells: set to <3> -- #size-cells: set to <2> -- device_type: set to "pci" -- bus-range: set to <0 0xff> -- ranges: ranges for the PCI memory and I/O regions -- #interrupt-cells: set to <1> -- interrupt-map-mask and interrupt-map: standard PCI properties to define - the mapping of the PCI interface to interrupt numbers. - -Example: - -pci-controller@10001000 { - compatible = "arm,versatile-pci"; - device_type = "pci"; - reg = <0x10001000 0x1000 - 0x41000000 0x10000 - 0x42000000 0x100000>; - bus-range = <0 0xff>; - #address-cells = <3>; - #size-cells = <2>; - #interrupt-cells = <1>; - - ranges = <0x01000000 0 0x00000000 0x43000000 0 0x00010000 /* downstream I/O */ - 0x02000000 0 0x50000000 0x50000000 0 0x10000000 /* non-prefetchable memory */ - 0x42000000 0 0x60000000 0x60000000 0 0x10000000>; /* prefetchable memory */ - - interrupt-map-mask = <0x1800 0 0 7>; - interrupt-map = <0x1800 0 0 1 &sic 28 - 0x1800 0 0 2 &sic 29 - 0x1800 0 0 3 &sic 30 - 0x1800 0 0 4 &sic 27 - - 0x1000 0 0 1 &sic 27 - 0x1000 0 0 2 &sic 28 - 0x1000 0 0 3 &sic 29 - 0x1000 0 0 4 &sic 30 - - 0x0800 0 0 1 &sic 30 - 0x0800 0 0 2 &sic 27 - 0x0800 0 0 3 &sic 28 - 0x0800 0 0 4 &sic 29 - - 0x0000 0 0 1 &sic 29 - 0x0000 0 0 2 &sic 30 - 0x0000 0 0 3 &sic 27 - 0x0000 0 0 4 &sic 28>; -}; diff --git a/Documentation/devicetree/bindings/pci/versatile.yaml b/Documentation/devicetree/bindings/pci/versatile.yaml new file mode 100644 index 000000000000..07a48c27db1f --- /dev/null +++ b/Documentation/devicetree/bindings/pci/versatile.yaml @@ -0,0 +1,92 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/pci/versatile.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: ARM Versatile Platform Baseboard PCI interface + +maintainers: + - Rob Herring <robh@kernel.org> + +description: |+ + PCI host controller found on the ARM Versatile PB board's FPGA. + +allOf: + - $ref: /schemas/pci/pci-bus.yaml# + +properties: + compatible: + const: arm,versatile-pci + + reg: + items: + - description: Versatile-specific registers + - description: Self Config space + - description: Config space + + ranges: + maxItems: 3 + + "#interrupt-cells": true + + interrupt-map: + maxItems: 16 + + interrupt-map-mask: + items: + - const: 0x1800 + - const: 0 + - const: 0 + - const: 7 + +required: + - compatible + - reg + - ranges + - "#interrupt-cells" + - interrupt-map + - interrupt-map-mask + +examples: + - | + pci@10001000 { + compatible = "arm,versatile-pci"; + device_type = "pci"; + reg = <0x10001000 0x1000>, + <0x41000000 0x10000>, + <0x42000000 0x100000>; + bus-range = <0 0xff>; + #address-cells = <3>; + #size-cells = <2>; + #interrupt-cells = <1>; + + ranges = + <0x01000000 0 0x00000000 0x43000000 0 0x00010000>, /* downstream I/O */ + <0x02000000 0 0x50000000 0x50000000 0 0x10000000>, /* non-prefetchable memory */ + <0x42000000 0 0x60000000 0x60000000 0 0x10000000>; /* prefetchable memory */ + + interrupt-map-mask = <0x1800 0 0 7>; + interrupt-map = <0x1800 0 0 1 &sic 28>, + <0x1800 0 0 2 &sic 29>, + <0x1800 0 0 3 &sic 30>, + <0x1800 0 0 4 &sic 27>, + + <0x1000 0 0 1 &sic 27>, + <0x1000 0 0 2 &sic 28>, + <0x1000 0 0 3 &sic 29>, + <0x1000 0 0 4 &sic 30>, + + <0x0800 0 0 1 &sic 30>, + <0x0800 0 0 2 &sic 27>, + <0x0800 0 0 3 &sic 28>, + <0x0800 0 0 4 &sic 29>, + + <0x0000 0 0 1 &sic 29>, + <0x0000 0 0 2 &sic 30>, + <0x0000 0 0 3 &sic 27>, + <0x0000 0 0 4 &sic 28>; + }; + + +... diff --git a/Documentation/devicetree/bindings/phy/allwinner,sun4i-a10-usb-phy.yaml b/Documentation/devicetree/bindings/phy/allwinner,sun4i-a10-usb-phy.yaml new file mode 100644 index 000000000000..020ef9e4c411 --- /dev/null +++ b/Documentation/devicetree/bindings/phy/allwinner,sun4i-a10-usb-phy.yaml @@ -0,0 +1,105 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/phy/allwinner,sun4i-a10-usb-phy.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Allwinner A10 USB PHY Device Tree Bindings + +maintainers: + - Chen-Yu Tsai <wens@csie.org> + - Maxime Ripard <mripard@kernel.org> + +properties: + "#phy-cells": + const: 1 + + compatible: + enum: + - allwinner,sun4i-a10-usb-phy + - allwinner,sun7i-a20-usb-phy + + reg: + items: + - description: PHY Control registers + - description: PHY PMU1 registers + - description: PHY PMU2 registers + + reg-names: + items: + - const: phy_ctrl + - const: pmu1 + - const: pmu2 + + clocks: + maxItems: 1 + description: USB PHY bus clock + + clock-names: + const: usb_phy + + resets: + items: + - description: USB OTG reset + - description: USB Host 1 Controller reset + - description: USB Host 2 Controller reset + + reset-names: + items: + - const: usb0_reset + - const: usb1_reset + - const: usb2_reset + + usb0_id_det-gpios: + description: GPIO to the USB OTG ID pin + + usb0_vbus_det-gpios: + description: GPIO to the USB OTG VBUS detect pin + + usb0_vbus_power-supply: + description: Power supply to detect the USB OTG VBUS + + usb0_vbus-supply: + description: Regulator controlling USB OTG VBUS + + usb1_vbus-supply: + description: Regulator controlling USB1 Host controller + + usb2_vbus-supply: + description: Regulator controlling USB2 Host controller + +required: + - "#phy-cells" + - compatible + - clocks + - clock-names + - reg + - reg-names + - resets + - reset-names + +additionalProperties: false + +examples: + - | + #include <dt-bindings/gpio/gpio.h> + #include <dt-bindings/clock/sun4i-a10-ccu.h> + #include <dt-bindings/reset/sun4i-a10-ccu.h> + + usbphy: phy@01c13400 { + #phy-cells = <1>; + compatible = "allwinner,sun4i-a10-usb-phy"; + reg = <0x01c13400 0x10>, <0x01c14800 0x4>, <0x01c1c800 0x4>; + reg-names = "phy_ctrl", "pmu1", "pmu2"; + clocks = <&ccu CLK_USB_PHY>; + clock-names = "usb_phy"; + resets = <&ccu RST_USB_PHY0>, + <&ccu RST_USB_PHY1>, + <&ccu RST_USB_PHY2>; + reset-names = "usb0_reset", "usb1_reset", "usb2_reset"; + usb0_id_det-gpios = <&pio 7 19 GPIO_ACTIVE_HIGH>; + usb0_vbus_det-gpios = <&pio 7 22 GPIO_ACTIVE_HIGH>; + usb0_vbus-supply = <®_usb0_vbus>; + usb1_vbus-supply = <®_usb1_vbus>; + usb2_vbus-supply = <®_usb2_vbus>; + }; diff --git a/Documentation/devicetree/bindings/phy/allwinner,sun50i-a64-usb-phy.yaml b/Documentation/devicetree/bindings/phy/allwinner,sun50i-a64-usb-phy.yaml new file mode 100644 index 000000000000..fd6e126fcf18 --- /dev/null +++ b/Documentation/devicetree/bindings/phy/allwinner,sun50i-a64-usb-phy.yaml @@ -0,0 +1,106 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/phy/allwinner,sun50i-a64-usb-phy.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Allwinner A64 USB PHY Device Tree Bindings + +maintainers: + - Chen-Yu Tsai <wens@csie.org> + - Maxime Ripard <mripard@kernel.org> + +properties: + "#phy-cells": + const: 1 + + compatible: + const: allwinner,sun50i-a64-usb-phy + + reg: + items: + - description: PHY Control registers + - description: PHY PMU0 registers + - description: PHY PMU1 registers + + reg-names: + items: + - const: phy_ctrl + - const: pmu0 + - const: pmu1 + + clocks: + items: + - description: USB OTG PHY bus clock + - description: USB Host 0 PHY bus clock + + clock-names: + items: + - const: usb0_phy + - const: usb1_phy + + resets: + items: + - description: USB OTG reset + - description: USB Host 1 Controller reset + + reset-names: + items: + - const: usb0_reset + - const: usb1_reset + + usb0_id_det-gpios: + description: GPIO to the USB OTG ID pin + + usb0_vbus_det-gpios: + description: GPIO to the USB OTG VBUS detect pin + + usb0_vbus_power-supply: + description: Power supply to detect the USB OTG VBUS + + usb0_vbus-supply: + description: Regulator controlling USB OTG VBUS + + usb1_vbus-supply: + description: Regulator controlling USB1 Host controller + +required: + - "#phy-cells" + - compatible + - clocks + - clock-names + - reg + - reg-names + - resets + - reset-names + +additionalProperties: false + +examples: + - | + #include <dt-bindings/gpio/gpio.h> + #include <dt-bindings/clock/sun50i-a64-ccu.h> + #include <dt-bindings/reset/sun50i-a64-ccu.h> + + phy@1c19400 { + #phy-cells = <1>; + compatible = "allwinner,sun50i-a64-usb-phy"; + reg = <0x01c19400 0x14>, + <0x01c1a800 0x4>, + <0x01c1b800 0x4>; + reg-names = "phy_ctrl", + "pmu0", + "pmu1"; + clocks = <&ccu CLK_USB_PHY0>, + <&ccu CLK_USB_PHY1>; + clock-names = "usb0_phy", + "usb1_phy"; + resets = <&ccu RST_USB_PHY0>, + <&ccu RST_USB_PHY1>; + reset-names = "usb0_reset", + "usb1_reset"; + usb0_id_det-gpios = <&pio 7 9 GPIO_ACTIVE_HIGH>; /* PH9 */ + usb0_vbus_power-supply = <&usb_power_supply>; + usb0_vbus-supply = <®_drivevbus>; + usb1_vbus-supply = <®_usb1_vbus>; + }; diff --git a/Documentation/devicetree/bindings/phy/allwinner,sun50i-h6-usb-phy.yaml b/Documentation/devicetree/bindings/phy/allwinner,sun50i-h6-usb-phy.yaml new file mode 100644 index 000000000000..7670411002c9 --- /dev/null +++ b/Documentation/devicetree/bindings/phy/allwinner,sun50i-h6-usb-phy.yaml @@ -0,0 +1,105 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/phy/allwinner,sun50i-h6-usb-phy.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Allwinner H6 USB PHY Device Tree Bindings + +maintainers: + - Chen-Yu Tsai <wens@csie.org> + - Maxime Ripard <mripard@kernel.org> + +properties: + "#phy-cells": + const: 1 + + compatible: + const: allwinner,sun50i-h6-usb-phy + + reg: + items: + - description: PHY Control registers + - description: PHY PMU0 registers + - description: PHY PMU3 registers + + reg-names: + items: + - const: phy_ctrl + - const: pmu0 + - const: pmu3 + + clocks: + items: + - description: USB OTG PHY bus clock + - description: USB Host PHY bus clock + + clock-names: + items: + - const: usb0_phy + - const: usb3_phy + + resets: + items: + - description: USB OTG reset + - description: USB Host Controller reset + + reset-names: + items: + - const: usb0_reset + - const: usb3_reset + + usb0_id_det-gpios: + description: GPIO to the USB OTG ID pin + + usb0_vbus_det-gpios: + description: GPIO to the USB OTG VBUS detect pin + + usb0_vbus_power-supply: + description: Power supply to detect the USB OTG VBUS + + usb0_vbus-supply: + description: Regulator controlling USB OTG VBUS + + usb3_vbus-supply: + description: Regulator controlling USB3 Host controller + +required: + - "#phy-cells" + - compatible + - clocks + - clock-names + - reg + - reg-names + - resets + - reset-names + +additionalProperties: false + +examples: + - | + #include <dt-bindings/gpio/gpio.h> + #include <dt-bindings/clock/sun50i-h6-ccu.h> + #include <dt-bindings/reset/sun50i-h6-ccu.h> + + phy@5100400 { + #phy-cells = <1>; + compatible = "allwinner,sun50i-h6-usb-phy"; + reg = <0x05100400 0x24>, + <0x05101800 0x4>, + <0x05311800 0x4>; + reg-names = "phy_ctrl", + "pmu0", + "pmu3"; + clocks = <&ccu CLK_USB_PHY0>, + <&ccu CLK_USB_PHY3>; + clock-names = "usb0_phy", + "usb3_phy"; + resets = <&ccu RST_USB_PHY0>, + <&ccu RST_USB_PHY3>; + reset-names = "usb0_reset", + "usb3_reset"; + usb0_id_det-gpios = <&pio 2 6 GPIO_ACTIVE_HIGH>; /* PC6 */ + usb0_vbus-supply = <®_vcc5v>; + usb3_vbus-supply = <®_vcc5v>; + }; diff --git a/Documentation/devicetree/bindings/phy/allwinner,sun5i-a13-usb-phy.yaml b/Documentation/devicetree/bindings/phy/allwinner,sun5i-a13-usb-phy.yaml new file mode 100644 index 000000000000..9b319381d1ad --- /dev/null +++ b/Documentation/devicetree/bindings/phy/allwinner,sun5i-a13-usb-phy.yaml @@ -0,0 +1,93 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/phy/allwinner,sun5i-a13-usb-phy.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Allwinner A13 USB PHY Device Tree Bindings + +maintainers: + - Chen-Yu Tsai <wens@csie.org> + - Maxime Ripard <mripard@kernel.org> + +properties: + "#phy-cells": + const: 1 + + compatible: + const: allwinner,sun5i-a13-usb-phy + + reg: + items: + - description: PHY Control registers + - description: PHY PMU1 registers + + reg-names: + items: + - const: phy_ctrl + - const: pmu1 + + clocks: + maxItems: 1 + description: USB OTG PHY bus clock + + clock-names: + const: usb_phy + + resets: + items: + - description: USB OTG reset + - description: USB Host 1 Controller reset + + reset-names: + items: + - const: usb0_reset + - const: usb1_reset + + usb0_id_det-gpios: + description: GPIO to the USB OTG ID pin + + usb0_vbus_det-gpios: + description: GPIO to the USB OTG VBUS detect pin + + usb0_vbus_power-supply: + description: Power supply to detect the USB OTG VBUS + + usb0_vbus-supply: + description: Regulator controlling USB OTG VBUS + + usb1_vbus-supply: + description: Regulator controlling USB1 Host controller + +required: + - "#phy-cells" + - compatible + - clocks + - clock-names + - reg + - reg-names + - resets + - reset-names + +additionalProperties: false + +examples: + - | + #include <dt-bindings/gpio/gpio.h> + #include <dt-bindings/clock/sun5i-ccu.h> + #include <dt-bindings/reset/sun5i-ccu.h> + + phy@1c13400 { + #phy-cells = <1>; + compatible = "allwinner,sun5i-a13-usb-phy"; + reg = <0x01c13400 0x10>, <0x01c14800 0x4>; + reg-names = "phy_ctrl", "pmu1"; + clocks = <&ccu CLK_USB_PHY0>; + clock-names = "usb_phy"; + resets = <&ccu RST_USB_PHY0>, <&ccu RST_USB_PHY1>; + reset-names = "usb0_reset", "usb1_reset"; + usb0_id_det-gpios = <&pio 6 2 (GPIO_ACTIVE_HIGH | GPIO_PULL_UP)>; /* PG2 */ + usb0_vbus_det-gpios = <&pio 6 1 (GPIO_ACTIVE_HIGH | GPIO_PULL_DOWN)>; /* PG1 */ + usb0_vbus-supply = <®_usb0_vbus>; + usb1_vbus-supply = <®_usb1_vbus>; + }; diff --git a/Documentation/devicetree/bindings/phy/allwinner,sun6i-a31-mipi-dphy.yaml b/Documentation/devicetree/bindings/phy/allwinner,sun6i-a31-mipi-dphy.yaml index 230d74f22136..d0b541a461f3 100644 --- a/Documentation/devicetree/bindings/phy/allwinner,sun6i-a31-mipi-dphy.yaml +++ b/Documentation/devicetree/bindings/phy/allwinner,sun6i-a31-mipi-dphy.yaml @@ -15,7 +15,11 @@ properties: const: 0 compatible: - const: allwinner,sun6i-a31-mipi-dphy + oneOf: + - const: allwinner,sun6i-a31-mipi-dphy + - items: + - const: allwinner,sun50i-a64-mipi-dphy + - const: allwinner,sun6i-a31-mipi-dphy reg: maxItems: 1 diff --git a/Documentation/devicetree/bindings/phy/allwinner,sun6i-a31-usb-phy.yaml b/Documentation/devicetree/bindings/phy/allwinner,sun6i-a31-usb-phy.yaml new file mode 100644 index 000000000000..b0ed01bbf3db --- /dev/null +++ b/Documentation/devicetree/bindings/phy/allwinner,sun6i-a31-usb-phy.yaml @@ -0,0 +1,119 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/phy/allwinner,sun6i-a31-usb-phy.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Allwinner A31 USB PHY Device Tree Bindings + +maintainers: + - Chen-Yu Tsai <wens@csie.org> + - Maxime Ripard <mripard@kernel.org> + +properties: + "#phy-cells": + const: 1 + + compatible: + const: allwinner,sun6i-a31-usb-phy + + reg: + items: + - description: PHY Control registers + - description: PHY PMU1 registers + - description: PHY PMU2 registers + + reg-names: + items: + - const: phy_ctrl + - const: pmu1 + - const: pmu2 + + clocks: + items: + - description: USB OTG PHY bus clock + - description: USB Host 0 PHY bus clock + - description: USB Host 1 PHY bus clock + + clock-names: + items: + - const: usb0_phy + - const: usb1_phy + - const: usb2_phy + + resets: + items: + - description: USB OTG reset + - description: USB Host 1 Controller reset + - description: USB Host 2 Controller reset + + reset-names: + items: + - const: usb0_reset + - const: usb1_reset + - const: usb2_reset + + usb0_id_det-gpios: + description: GPIO to the USB OTG ID pin + + usb0_vbus_det-gpios: + description: GPIO to the USB OTG VBUS detect pin + + usb0_vbus_power-supply: + description: Power supply to detect the USB OTG VBUS + + usb0_vbus-supply: + description: Regulator controlling USB OTG VBUS + + usb1_vbus-supply: + description: Regulator controlling USB1 Host controller + + usb2_vbus-supply: + description: Regulator controlling USB2 Host controller + +required: + - "#phy-cells" + - compatible + - clocks + - clock-names + - reg + - reg-names + - resets + - reset-names + +additionalProperties: false + +examples: + - | + #include <dt-bindings/gpio/gpio.h> + #include <dt-bindings/clock/sun6i-a31-ccu.h> + #include <dt-bindings/reset/sun6i-a31-ccu.h> + + phy@1c19400 { + #phy-cells = <1>; + compatible = "allwinner,sun6i-a31-usb-phy"; + reg = <0x01c19400 0x10>, + <0x01c1a800 0x4>, + <0x01c1b800 0x4>; + reg-names = "phy_ctrl", + "pmu1", + "pmu2"; + clocks = <&ccu CLK_USB_PHY0>, + <&ccu CLK_USB_PHY1>, + <&ccu CLK_USB_PHY2>; + clock-names = "usb0_phy", + "usb1_phy", + "usb2_phy"; + resets = <&ccu RST_USB_PHY0>, + <&ccu RST_USB_PHY1>, + <&ccu RST_USB_PHY2>; + reset-names = "usb0_reset", + "usb1_reset", + "usb2_reset"; + usb0_id_det-gpios = <&pio 0 15 GPIO_ACTIVE_HIGH>; /* PA15 */ + usb0_vbus_det-gpios = <&pio 0 16 GPIO_ACTIVE_HIGH>; /* PA16 */ + usb0_vbus_power-supply = <&usb_power_supply>; + usb0_vbus-supply = <®_drivevbus>; + usb1_vbus-supply = <®_usb1_vbus>; + usb2_vbus-supply = <®_usb2_vbus>; + }; diff --git a/Documentation/devicetree/bindings/phy/allwinner,sun8i-a23-usb-phy.yaml b/Documentation/devicetree/bindings/phy/allwinner,sun8i-a23-usb-phy.yaml new file mode 100644 index 000000000000..b0674406f8aa --- /dev/null +++ b/Documentation/devicetree/bindings/phy/allwinner,sun8i-a23-usb-phy.yaml @@ -0,0 +1,102 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/phy/allwinner,sun8i-a23-usb-phy.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Allwinner A23 USB PHY Device Tree Bindings + +maintainers: + - Chen-Yu Tsai <wens@csie.org> + - Maxime Ripard <mripard@kernel.org> + +properties: + "#phy-cells": + const: 1 + + compatible: + enum: + - allwinner,sun8i-a23-usb-phy + - allwinner,sun8i-a33-usb-phy + + reg: + items: + - description: PHY Control registers + - description: PHY PMU1 registers + + reg-names: + items: + - const: phy_ctrl + - const: pmu1 + + clocks: + items: + - description: USB OTG PHY bus clock + - description: USB Host 0 PHY bus clock + + clock-names: + items: + - const: usb0_phy + - const: usb1_phy + + resets: + items: + - description: USB OTG reset + - description: USB Host 1 Controller reset + + reset-names: + items: + - const: usb0_reset + - const: usb1_reset + + usb0_id_det-gpios: + description: GPIO to the USB OTG ID pin + + usb0_vbus_det-gpios: + description: GPIO to the USB OTG VBUS detect pin + + usb0_vbus_power-supply: + description: Power supply to detect the USB OTG VBUS + + usb0_vbus-supply: + description: Regulator controlling USB OTG VBUS + + usb1_vbus-supply: + description: Regulator controlling USB1 Host controller + +required: + - "#phy-cells" + - compatible + - clocks + - clock-names + - reg + - reg-names + - resets + - reset-names + +additionalProperties: false + +examples: + - | + #include <dt-bindings/gpio/gpio.h> + #include <dt-bindings/clock/sun8i-a23-a33-ccu.h> + #include <dt-bindings/reset/sun8i-a23-a33-ccu.h> + + phy@1c19400 { + #phy-cells = <1>; + compatible = "allwinner,sun8i-a23-usb-phy"; + reg = <0x01c19400 0x10>, <0x01c1a800 0x4>; + reg-names = "phy_ctrl", "pmu1"; + clocks = <&ccu CLK_USB_PHY0>, + <&ccu CLK_USB_PHY1>; + clock-names = "usb0_phy", + "usb1_phy"; + resets = <&ccu RST_USB_PHY0>, + <&ccu RST_USB_PHY1>; + reset-names = "usb0_reset", + "usb1_reset"; + usb0_id_det-gpios = <&pio 1 3 GPIO_ACTIVE_HIGH>; /* PB3 */ + usb0_vbus_power-supply = <&usb_power_supply>; + usb0_vbus-supply = <®_drivevbus>; + usb1_vbus-supply = <®_usb1_vbus>; + }; diff --git a/Documentation/devicetree/bindings/phy/allwinner,sun8i-a83t-usb-phy.yaml b/Documentation/devicetree/bindings/phy/allwinner,sun8i-a83t-usb-phy.yaml new file mode 100644 index 000000000000..48dc9c834a9b --- /dev/null +++ b/Documentation/devicetree/bindings/phy/allwinner,sun8i-a83t-usb-phy.yaml @@ -0,0 +1,122 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/phy/allwinner,sun8i-a83t-usb-phy.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Allwinner A83t USB PHY Device Tree Bindings + +maintainers: + - Chen-Yu Tsai <wens@csie.org> + - Maxime Ripard <mripard@kernel.org> + +properties: + "#phy-cells": + const: 1 + + compatible: + const: allwinner,sun8i-a83t-usb-phy + + reg: + items: + - description: PHY Control registers + - description: PHY PMU1 registers + - description: PHY PMU2 registers + + reg-names: + items: + - const: phy_ctrl + - const: pmu1 + - const: pmu2 + + clocks: + items: + - description: USB OTG PHY bus clock + - description: USB Host 0 PHY bus clock + - description: USB Host 1 PHY bus clock + - description: USB HSIC 12MHz clock + + clock-names: + items: + - const: usb0_phy + - const: usb1_phy + - const: usb2_phy + - const: usb2_hsic_12M + + resets: + items: + - description: USB OTG reset + - description: USB Host 1 Controller reset + - description: USB Host 2 Controller reset + + reset-names: + items: + - const: usb0_reset + - const: usb1_reset + - const: usb2_reset + + usb0_id_det-gpios: + description: GPIO to the USB OTG ID pin + + usb0_vbus_det-gpios: + description: GPIO to the USB OTG VBUS detect pin + + usb0_vbus_power-supply: + description: Power supply to detect the USB OTG VBUS + + usb0_vbus-supply: + description: Regulator controlling USB OTG VBUS + + usb1_vbus-supply: + description: Regulator controlling USB1 Host controller + + usb2_vbus-supply: + description: Regulator controlling USB2 Host controller + +required: + - "#phy-cells" + - compatible + - clocks + - clock-names + - reg + - reg-names + - resets + - reset-names + +additionalProperties: false + +examples: + - | + #include <dt-bindings/gpio/gpio.h> + #include <dt-bindings/clock/sun8i-a83t-ccu.h> + #include <dt-bindings/reset/sun8i-a83t-ccu.h> + + phy@1c19400 { + #phy-cells = <1>; + compatible = "allwinner,sun8i-a83t-usb-phy"; + reg = <0x01c19400 0x10>, + <0x01c1a800 0x14>, + <0x01c1b800 0x14>; + reg-names = "phy_ctrl", + "pmu1", + "pmu2"; + clocks = <&ccu CLK_USB_PHY0>, + <&ccu CLK_USB_PHY1>, + <&ccu CLK_USB_HSIC>, + <&ccu CLK_USB_HSIC_12M>; + clock-names = "usb0_phy", + "usb1_phy", + "usb2_phy", + "usb2_hsic_12M"; + resets = <&ccu RST_USB_PHY0>, + <&ccu RST_USB_PHY1>, + <&ccu RST_USB_HSIC>; + reset-names = "usb0_reset", + "usb1_reset", + "usb2_reset"; + usb0_id_det-gpios = <&pio 7 11 GPIO_ACTIVE_HIGH>; /* PH11 */ + usb0_vbus_power-supply = <&usb_power_supply>; + usb0_vbus-supply = <®_drivevbus>; + usb1_vbus-supply = <®_usb1_vbus>; + usb2_vbus-supply = <®_usb2_vbus>; + }; diff --git a/Documentation/devicetree/bindings/phy/allwinner,sun8i-h3-usb-phy.yaml b/Documentation/devicetree/bindings/phy/allwinner,sun8i-h3-usb-phy.yaml new file mode 100644 index 000000000000..60c344585276 --- /dev/null +++ b/Documentation/devicetree/bindings/phy/allwinner,sun8i-h3-usb-phy.yaml @@ -0,0 +1,137 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/phy/allwinner,sun8i-h3-usb-phy.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Allwinner H3 USB PHY Device Tree Bindings + +maintainers: + - Chen-Yu Tsai <wens@csie.org> + - Maxime Ripard <mripard@kernel.org> + +properties: + "#phy-cells": + const: 1 + + compatible: + const: allwinner,sun8i-h3-usb-phy + + reg: + items: + - description: PHY Control registers + - description: PHY PMU0 registers + - description: PHY PMU1 registers + - description: PHY PMU2 registers + - description: PHY PMU3 registers + + reg-names: + items: + - const: phy_ctrl + - const: pmu0 + - const: pmu1 + - const: pmu2 + - const: pmu3 + + clocks: + items: + - description: USB OTG PHY bus clock + - description: USB Host 0 PHY bus clock + - description: USB Host 1 PHY bus clock + - description: USB Host 2 PHY bus clock + + clock-names: + items: + - const: usb0_phy + - const: usb1_phy + - const: usb2_phy + - const: usb3_phy + + resets: + items: + - description: USB OTG reset + - description: USB Host 1 Controller reset + - description: USB Host 2 Controller reset + - description: USB Host 3 Controller reset + + reset-names: + items: + - const: usb0_reset + - const: usb1_reset + - const: usb2_reset + - const: usb3_reset + + usb0_id_det-gpios: + description: GPIO to the USB OTG ID pin + + usb0_vbus_det-gpios: + description: GPIO to the USB OTG VBUS detect pin + + usb0_vbus_power-supply: + description: Power supply to detect the USB OTG VBUS + + usb0_vbus-supply: + description: Regulator controlling USB OTG VBUS + + usb1_vbus-supply: + description: Regulator controlling USB1 Host controller + + usb2_vbus-supply: + description: Regulator controlling USB2 Host controller + + usb3_vbus-supply: + description: Regulator controlling USB3 Host controller + +required: + - "#phy-cells" + - compatible + - clocks + - clock-names + - reg + - reg-names + - resets + - reset-names + +additionalProperties: false + +examples: + - | + #include <dt-bindings/gpio/gpio.h> + #include <dt-bindings/clock/sun8i-h3-ccu.h> + #include <dt-bindings/reset/sun8i-h3-ccu.h> + + phy@1c19400 { + #phy-cells = <1>; + compatible = "allwinner,sun8i-h3-usb-phy"; + reg = <0x01c19400 0x2c>, + <0x01c1a800 0x4>, + <0x01c1b800 0x4>, + <0x01c1c800 0x4>, + <0x01c1d800 0x4>; + reg-names = "phy_ctrl", + "pmu0", + "pmu1", + "pmu2", + "pmu3"; + clocks = <&ccu CLK_USB_PHY0>, + <&ccu CLK_USB_PHY1>, + <&ccu CLK_USB_PHY2>, + <&ccu CLK_USB_PHY3>; + clock-names = "usb0_phy", + "usb1_phy", + "usb2_phy", + "usb3_phy"; + resets = <&ccu RST_USB_PHY0>, + <&ccu RST_USB_PHY1>, + <&ccu RST_USB_PHY2>, + <&ccu RST_USB_PHY3>; + reset-names = "usb0_reset", + "usb1_reset", + "usb2_reset", + "usb3_reset"; + usb0_id_det-gpios = <&pio 6 12 GPIO_ACTIVE_HIGH>; /* PG12 */ + usb0_vbus-supply = <®_usb0_vbus>; + usb1_vbus-supply = <®_usb1_vbus>; + usb2_vbus-supply = <®_usb2_vbus>; + usb3_vbus-supply = <®_usb3_vbus>; + }; diff --git a/Documentation/devicetree/bindings/phy/allwinner,sun8i-r40-usb-phy.yaml b/Documentation/devicetree/bindings/phy/allwinner,sun8i-r40-usb-phy.yaml new file mode 100644 index 000000000000..a2bb36790fbd --- /dev/null +++ b/Documentation/devicetree/bindings/phy/allwinner,sun8i-r40-usb-phy.yaml @@ -0,0 +1,119 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/phy/allwinner,sun8i-r40-usb-phy.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Allwinner R40 USB PHY Device Tree Bindings + +maintainers: + - Chen-Yu Tsai <wens@csie.org> + - Maxime Ripard <mripard@kernel.org> + +properties: + "#phy-cells": + const: 1 + + compatible: + const: allwinner,sun8i-r40-usb-phy + + reg: + items: + - description: PHY Control registers + - description: PHY PMU0 registers + - description: PHY PMU1 registers + - description: PHY PMU2 registers + + reg-names: + items: + - const: phy_ctrl + - const: pmu0 + - const: pmu1 + - const: pmu2 + + clocks: + items: + - description: USB OTG PHY bus clock + - description: USB Host 0 PHY bus clock + - description: USB Host 1 PHY bus clock + + clock-names: + items: + - const: usb0_phy + - const: usb1_phy + - const: usb2_phy + + resets: + items: + - description: USB OTG reset + - description: USB Host 1 Controller reset + - description: USB Host 2 Controller reset + + reset-names: + items: + - const: usb0_reset + - const: usb1_reset + - const: usb2_reset + + usb0_id_det-gpios: + description: GPIO to the USB OTG ID pin + + usb0_vbus_det-gpios: + description: GPIO to the USB OTG VBUS detect pin + + usb0_vbus_power-supply: + description: Power supply to detect the USB OTG VBUS + + usb0_vbus-supply: + description: Regulator controlling USB OTG VBUS + + usb1_vbus-supply: + description: Regulator controlling USB1 Host controller + + usb2_vbus-supply: + description: Regulator controlling USB2 Host controller + +required: + - "#phy-cells" + - compatible + - clocks + - clock-names + - reg + - reg-names + - resets + - reset-names + +additionalProperties: false + +examples: + - | + #include <dt-bindings/gpio/gpio.h> + #include <dt-bindings/clock/sun8i-r40-ccu.h> + #include <dt-bindings/reset/sun8i-r40-ccu.h> + + phy@1c13400 { + #phy-cells = <1>; + compatible = "allwinner,sun8i-r40-usb-phy"; + reg = <0x01c13400 0x14>, + <0x01c14800 0x4>, + <0x01c19800 0x4>, + <0x01c1c800 0x4>; + reg-names = "phy_ctrl", + "pmu0", + "pmu1", + "pmu2"; + clocks = <&ccu CLK_USB_PHY0>, + <&ccu CLK_USB_PHY1>, + <&ccu CLK_USB_PHY2>; + clock-names = "usb0_phy", + "usb1_phy", + "usb2_phy"; + resets = <&ccu RST_USB_PHY0>, + <&ccu RST_USB_PHY1>, + <&ccu RST_USB_PHY2>; + reset-names = "usb0_reset", + "usb1_reset", + "usb2_reset"; + usb1_vbus-supply = <®_vcc5v0>; + usb2_vbus-supply = <®_vcc5v0>; + }; diff --git a/Documentation/devicetree/bindings/phy/allwinner,sun8i-v3s-usb-phy.yaml b/Documentation/devicetree/bindings/phy/allwinner,sun8i-v3s-usb-phy.yaml new file mode 100644 index 000000000000..eadfd0c9493c --- /dev/null +++ b/Documentation/devicetree/bindings/phy/allwinner,sun8i-v3s-usb-phy.yaml @@ -0,0 +1,86 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/phy/allwinner,sun8i-v3s-usb-phy.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Allwinner V3s USB PHY Device Tree Bindings + +maintainers: + - Chen-Yu Tsai <wens@csie.org> + - Maxime Ripard <mripard@kernel.org> + +properties: + "#phy-cells": + const: 1 + + compatible: + const: allwinner,sun8i-v3s-usb-phy + + reg: + items: + - description: PHY Control registers + - description: PHY PMU0 registers + + reg-names: + items: + - const: phy_ctrl + - const: pmu0 + + clocks: + maxItems: 1 + description: USB OTG PHY bus clock + + clock-names: + const: usb0_phy + + resets: + maxItems: 1 + description: USB OTG reset + + reset-names: + const: usb0_reset + + usb0_id_det-gpios: + description: GPIO to the USB OTG ID pin + + usb0_vbus_det-gpios: + description: GPIO to the USB OTG VBUS detect pin + + usb0_vbus_power-supply: + description: Power supply to detect the USB OTG VBUS + + usb0_vbus-supply: + description: Regulator controlling USB OTG VBUS + +required: + - "#phy-cells" + - compatible + - clocks + - clock-names + - reg + - reg-names + - resets + - reset-names + +additionalProperties: false + +examples: + - | + #include <dt-bindings/gpio/gpio.h> + #include <dt-bindings/clock/sun8i-v3s-ccu.h> + #include <dt-bindings/reset/sun8i-v3s-ccu.h> + + phy@1c19400 { + #phy-cells = <1>; + compatible = "allwinner,sun8i-v3s-usb-phy"; + reg = <0x01c19400 0x2c>, + <0x01c1a800 0x4>; + reg-names = "phy_ctrl", + "pmu0"; + clocks = <&ccu CLK_USB_PHY0>; + clock-names = "usb0_phy"; + resets = <&ccu RST_USB_PHY0>; + reset-names = "usb0_reset"; + usb0_id_det-gpios = <&pio 5 6 GPIO_ACTIVE_HIGH>; + }; diff --git a/Documentation/devicetree/bindings/phy/allwinner,sun9i-a80-usb-phy.yaml b/Documentation/devicetree/bindings/phy/allwinner,sun9i-a80-usb-phy.yaml new file mode 100644 index 000000000000..ded7d6f0a119 --- /dev/null +++ b/Documentation/devicetree/bindings/phy/allwinner,sun9i-a80-usb-phy.yaml @@ -0,0 +1,135 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/phy/allwinner,sun9i-a80-usb-phy.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Allwinner A80 USB PHY Device Tree Bindings + +maintainers: + - Chen-Yu Tsai <wens@csie.org> + - Maxime Ripard <mripard@kernel.org> + +properties: + "#phy-cells": + const: 0 + + compatible: + const: allwinner,sun9i-a80-usb-phy + + reg: + maxItems: 1 + + clocks: + anyOf: + - description: Main PHY Clock + + - items: + - description: Main PHY clock + - description: HSIC 12MHz clock + - description: HSIC 480MHz clock + + clock-names: + oneOf: + - const: phy + + - items: + - const: phy + - const: hsic_12M + - const: hsic_480M + + resets: + anyOf: + - description: Normal USB PHY reset + + - items: + - description: Normal USB PHY reset + - description: HSIC Reset + + reset-names: + oneOf: + - const: phy + + - items: + - const: phy + - const: hsic + + phy_type: + const: hsic + description: + When absent, the PHY type will be assumed to be normal USB. + + phy-supply: + description: + Regulator that powers VBUS + +required: + - "#phy-cells" + - compatible + - reg + - clocks + - clock-names + - resets + - reset-names + +additionalProperties: false + +if: + properties: + phy_type: + const: hsic + + required: + - phy_type + +then: + properties: + clocks: + maxItems: 3 + + clock-names: + maxItems: 3 + + resets: + maxItems: 2 + + reset-names: + maxItems: 2 + +examples: + - | + #include <dt-bindings/clock/sun9i-a80-usb.h> + #include <dt-bindings/reset/sun9i-a80-usb.h> + + usbphy1: phy@a00800 { + compatible = "allwinner,sun9i-a80-usb-phy"; + reg = <0x00a00800 0x4>; + clocks = <&usb_clocks CLK_USB0_PHY>; + clock-names = "phy"; + resets = <&usb_clocks RST_USB0_PHY>; + reset-names = "phy"; + phy-supply = <®_usb1_vbus>; + #phy-cells = <0>; + }; + + - | + #include <dt-bindings/clock/sun9i-a80-usb.h> + #include <dt-bindings/reset/sun9i-a80-usb.h> + + usbphy3: phy@a02800 { + compatible = "allwinner,sun9i-a80-usb-phy"; + reg = <0x00a02800 0x4>; + clocks = <&usb_clocks CLK_USB2_PHY>, + <&usb_clocks CLK_USB_HSIC>, + <&usb_clocks CLK_USB2_HSIC>; + clock-names = "phy", + "hsic_12M", + "hsic_480M"; + resets = <&usb_clocks RST_USB2_PHY>, + <&usb_clocks RST_USB2_HSIC>; + reset-names = "phy", + "hsic"; + phy_type = "hsic"; + phy-supply = <®_usb3_vbus>; + #phy-cells = <0>; + }; diff --git a/Documentation/devicetree/bindings/phy/brcm,brcmstb-usb-phy.txt b/Documentation/devicetree/bindings/phy/brcm,brcmstb-usb-phy.txt index 24a0d06acd1d..698aacbdcfc4 100644 --- a/Documentation/devicetree/bindings/phy/brcm,brcmstb-usb-phy.txt +++ b/Documentation/devicetree/bindings/phy/brcm,brcmstb-usb-phy.txt @@ -1,30 +1,49 @@ Broadcom STB USB PHY Required properties: - - compatible: brcm,brcmstb-usb-phy - - reg: two offset and length pairs. - The first pair specifies a manditory set of memory mapped - registers used for general control of the PHY. - The second pair specifies optional registers used by some of - the SoCs that support USB 3.x - - #phy-cells: Shall be 1 as it expects one argument for setting - the type of the PHY. Possible values are: - - PHY_TYPE_USB2 for USB1.1/2.0 PHY - - PHY_TYPE_USB3 for USB3.x PHY +- compatible: should be one of + "brcm,brcmstb-usb-phy" + "brcm,bcm7216-usb-phy" + "brcm,bcm7211-usb-phy" + +- reg and reg-names properties requirements are specific to the + compatible string. + "brcm,brcmstb-usb-phy": + - reg: 1 or 2 offset and length pairs. One for the base CTRL registers + and an optional pair for systems with USB 3.x support + - reg-names: not specified + "brcm,bcm7216-usb-phy": + - reg: 3 offset and length pairs for CTRL, XHCI_EC and XHCI_GBL + registers + - reg-names: "ctrl", "xhci_ec", "xhci_gbl" + "brcm,bcm7211-usb-phy": + - reg: 5 offset and length pairs for CTRL, XHCI_EC, XHCI_GBL, + USB_PHY and USB_MDIO registers and an optional pair + for the BDC registers + - reg-names: "ctrl", "xhci_ec", "xhci_gbl", "usb_phy", "usb_mdio", "bdc_ec" + +- #phy-cells: Shall be 1 as it expects one argument for setting + the type of the PHY. Possible values are: + - PHY_TYPE_USB2 for USB1.1/2.0 PHY + - PHY_TYPE_USB3 for USB3.x PHY Optional Properties: - clocks : clock phandles. - clock-names: String, clock name. +- interrupts: wakeup interrupt +- interrupt-names: "wakeup" - brcm,ipp: Boolean, Invert Port Power. Possible values are: 0 (Don't invert), 1 (Invert) - brcm,ioc: Boolean, Invert Over Current detection. Possible values are: 0 (Don't invert), 1 (Invert) -NOTE: one or both of the following two properties must be set -- brcm,has-xhci: Boolean indicating the phy has an XHCI phy. -- brcm,has-eohci: Boolean indicating the phy has an EHCI/OHCI phy. - dr_mode: String, PHY Device mode. Possible values are: "host", "peripheral ", "drd" or "typec-pd" If this property is not defined, the phy will default to "host" mode. +- brcm,syscon-piarbctl: phandle to syscon for handling config registers +NOTE: one or both of the following two properties must be set +- brcm,has-xhci: Boolean indicating the phy has an XHCI phy. +- brcm,has-eohci: Boolean indicating the phy has an EHCI/OHCI phy. + Example: @@ -41,3 +60,27 @@ usbphy_0: usb-phy@f0470200 { clocks = <&usb20>, <&usb30>; clock-names = "sw_usb", "sw_usb3"; }; + +usb-phy@29f0200 { + reg = <0x29f0200 0x200>, + <0x29c0880 0x30>, + <0x29cc100 0x534>, + <0x2808000 0x24>, + <0x2980080 0x8>; + reg-names = "ctrl", + "xhci_ec", + "xhci_gbl", + "usb_phy", + "usb_mdio"; + brcm,ioc = <0x0>; + brcm,ipp = <0x0>; + compatible = "brcm,bcm7211-usb-phy"; + interrupts = <0x30>; + interrupt-parent = <&vpu_intr1_nosec_intc>; + interrupt-names = "wake"; + #phy-cells = <0x1>; + brcm,has-xhci; + syscon-piarbctl = <&syscon_piarbctl>; + clocks = <&scmi_clk 256>; + clock-names = "sw_usb"; +}; diff --git a/Documentation/devicetree/bindings/phy/brcm-sata-phy.txt b/Documentation/devicetree/bindings/phy/brcm-sata-phy.txt index b640845fec67..c03ad2198410 100644 --- a/Documentation/devicetree/bindings/phy/brcm-sata-phy.txt +++ b/Documentation/devicetree/bindings/phy/brcm-sata-phy.txt @@ -2,6 +2,7 @@ Required properties: - compatible: should be one or more of + "brcm,bcm7216-sata-phy" "brcm,bcm7425-sata-phy" "brcm,bcm7445-sata-phy" "brcm,iproc-ns2-sata-phy" diff --git a/Documentation/devicetree/bindings/phy/intel,lgm-emmc-phy.yaml b/Documentation/devicetree/bindings/phy/intel,lgm-emmc-phy.yaml new file mode 100644 index 000000000000..0ccee64c6962 --- /dev/null +++ b/Documentation/devicetree/bindings/phy/intel,lgm-emmc-phy.yaml @@ -0,0 +1,58 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/phy/intel,lgm-emmc-phy.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Intel Lightning Mountain(LGM) eMMC PHY Device Tree Bindings + +maintainers: + - Ramuthevar Vadivel Murugan <vadivel.muruganx.ramuthevar@linux.intel.com> + +description: |+ + Bindings for eMMC PHY on Intel's Lightning Mountain SoC, syscon + node is used to reference the base address of eMMC phy registers. + + The eMMC PHY node should be the child of a syscon node with the + required property: + + - compatible: Should be one of the following: + "intel,lgm-syscon", "syscon" + - reg: + maxItems: 1 + +properties: + compatible: + const: intel,lgm-emmc-phy + + "#phy-cells": + const: 0 + + reg: + maxItems: 1 + + clocks: + maxItems: 1 + +required: + - "#phy-cells" + - compatible + - reg + - clocks + +examples: + - | + sysconf: chiptop@e0200000 { + compatible = "intel,lgm-syscon", "syscon"; + reg = <0xe0200000 0x100>; + #address-cells = <1>; + #size-cells = <1>; + + emmc_phy: emmc-phy@a8 { + compatible = "intel,lgm-emmc-phy"; + reg = <0x00a8 0x10>; + clocks = <&emmc>; + #phy-cells = <0>; + }; + }; +... diff --git a/Documentation/devicetree/bindings/phy/marvell,mmp3-hsic-phy.yaml b/Documentation/devicetree/bindings/phy/marvell,mmp3-hsic-phy.yaml new file mode 100644 index 000000000000..5ab436189f3b --- /dev/null +++ b/Documentation/devicetree/bindings/phy/marvell,mmp3-hsic-phy.yaml @@ -0,0 +1,42 @@ +# SPDX-License-Identifier: GPL-2.0-or-later +# Copyright 2019 Lubomir Rintel <lkundrak@v3.sk> +%YAML 1.2 +--- +$id: "http://devicetree.org/schemas/phy/marvell,mmp3-hsic-phy.yaml#" +$schema: "http://devicetree.org/meta-schemas/core.yaml#" + +title: Marvell MMP3 HSIC PHY + +maintainers: + - Lubomir Rintel <lkundrak@v3.sk> + +properties: + compatible: + const: marvell,mmp3-hsic-phy + + reg: + maxItems: 1 + description: base address of the device + + reset-gpios: + maxItems: 1 + description: GPIO connected to reset + + "#phy-cells": + const: 0 + +required: + - compatible + - reg + - reset-gpios + - "#phy-cells" + +examples: + - | + #include <dt-bindings/gpio/gpio.h> + hsic-phy@f0001800 { + compatible = "marvell,mmp3-hsic-phy"; + reg = <0xf0001800 0x40>; + reset-gpios = <&gpio 63 GPIO_ACTIVE_HIGH>; + #phy-cells = <0>; + }; diff --git a/Documentation/devicetree/bindings/phy/phy-cadence-sierra.txt b/Documentation/devicetree/bindings/phy/phy-cadence-sierra.txt index 6e1b47bfce43..03f5939d3d19 100644 --- a/Documentation/devicetree/bindings/phy/phy-cadence-sierra.txt +++ b/Documentation/devicetree/bindings/phy/phy-cadence-sierra.txt @@ -2,21 +2,24 @@ Cadence Sierra PHY ----------------------- Required properties: -- compatible: cdns,sierra-phy-t0 -- clocks: Must contain an entry in clock-names. - See ../clocks/clock-bindings.txt for details. -- clock-names: Must be "phy_clk" +- compatible: Must be "cdns,sierra-phy-t0" for Sierra in Cadence platform + Must be "ti,sierra-phy-t0" for Sierra in TI's J721E SoC. - resets: Must contain an entry for each in reset-names. See ../reset/reset.txt for details. - reset-names: Must include "sierra_reset" and "sierra_apb". "sierra_reset" must control the reset line to the PHY. "sierra_apb" must control the reset line to the APB PHY - interface. + interface ("sierra_apb" is optional). - reg: register range for the PHY. - #address-cells: Must be 1 - #size-cells: Must be 0 Optional properties: +- clocks: Must contain an entry in clock-names. + See ../clocks/clock-bindings.txt for details. +- clock-names: Must contain "cmn_refclk_dig_div" and + "cmn_refclk1_dig_div" for configuring the frequency of + the clock to the lanes. "phy_clk" is deprecated. - cdns,autoconf: A boolean property whose presence indicates that the PHY registers will be configured by hardware. If not present, all sub-node optional properties must be diff --git a/Documentation/devicetree/bindings/phy/rockchip,px30-dsi-dphy.yaml b/Documentation/devicetree/bindings/phy/rockchip,px30-dsi-dphy.yaml index bb0da87bcd84..72aca81e8959 100644 --- a/Documentation/devicetree/bindings/phy/rockchip,px30-dsi-dphy.yaml +++ b/Documentation/devicetree/bindings/phy/rockchip,px30-dsi-dphy.yaml @@ -13,9 +13,6 @@ properties: "#phy-cells": const: 0 - "#clock-cells": - const: 0 - compatible: enum: - rockchip,px30-dsi-dphy @@ -49,7 +46,6 @@ properties: required: - "#phy-cells" - - "#clock-cells" - compatible - reg - clocks @@ -62,11 +58,10 @@ additionalProperties: false examples: - | dsi_dphy: phy@ff2e0000 { - compatible = "rockchip,px30-video-phy"; + compatible = "rockchip,px30-dsi-dphy"; reg = <0x0 0xff2e0000 0x0 0x10000>; clocks = <&pmucru 13>, <&cru 12>; clock-names = "ref", "pclk"; - #clock-cells = <0>; resets = <&cru 12>; reset-names = "apb"; #phy-cells = <0>; diff --git a/Documentation/devicetree/bindings/phy/samsung-phy.txt b/Documentation/devicetree/bindings/phy/samsung-phy.txt index 1c40ccd40ce4..7510830a79bd 100644 --- a/Documentation/devicetree/bindings/phy/samsung-phy.txt +++ b/Documentation/devicetree/bindings/phy/samsung-phy.txt @@ -1,4 +1,4 @@ -Samsung S5P/EXYNOS SoC series MIPI CSIS/DSIM DPHY +Samsung S5P/Exynos SoC series MIPI CSIS/DSIM DPHY ------------------------------------------------- Required properties: @@ -27,7 +27,7 @@ the PHY specifier identifies the PHY and its meaning is as follows: supports additional fifth PHY: 4 - MIPI CSIS 2. -Samsung EXYNOS SoC series Display Port PHY +Samsung Exynos SoC series Display Port PHY ------------------------------------------------- Required properties: @@ -38,7 +38,7 @@ Required properties: control pmu registers for power isolation. - #phy-cells : from the generic PHY bindings, must be 0; -Samsung S5P/EXYNOS SoC series USB PHY +Samsung S5P/Exynos SoC series USB PHY ------------------------------------------------- Required properties: diff --git a/Documentation/devicetree/bindings/phy/sun4i-usb-phy.txt b/Documentation/devicetree/bindings/phy/sun4i-usb-phy.txt deleted file mode 100644 index f2e120af17f0..000000000000 --- a/Documentation/devicetree/bindings/phy/sun4i-usb-phy.txt +++ /dev/null @@ -1,68 +0,0 @@ -Allwinner sun4i USB PHY ------------------------ - -Required properties: -- compatible : should be one of - * allwinner,sun4i-a10-usb-phy - * allwinner,sun5i-a13-usb-phy - * allwinner,sun6i-a31-usb-phy - * allwinner,sun7i-a20-usb-phy - * allwinner,sun8i-a23-usb-phy - * allwinner,sun8i-a33-usb-phy - * allwinner,sun8i-a83t-usb-phy - * allwinner,sun8i-h3-usb-phy - * allwinner,sun8i-r40-usb-phy - * allwinner,sun8i-v3s-usb-phy - * allwinner,sun50i-a64-usb-phy - * allwinner,sun50i-h6-usb-phy -- reg : a list of offset + length pairs -- reg-names : - * "phy_ctrl" - * "pmu0" for H3, V3s, A64 or H6 - * "pmu1" - * "pmu2" for sun4i, sun6i, sun7i, sun8i-a83t or sun8i-h3 - * "pmu3" for sun8i-h3 or sun50i-h6 -- #phy-cells : from the generic phy bindings, must be 1 -- clocks : phandle + clock specifier for the phy clocks -- clock-names : - * "usb_phy" for sun4i, sun5i or sun7i - * "usb0_phy", "usb1_phy" and "usb2_phy" for sun6i - * "usb0_phy", "usb1_phy" for sun8i - * "usb0_phy", "usb1_phy", "usb2_phy" and "usb2_hsic_12M" for sun8i-a83t - * "usb0_phy", "usb1_phy", "usb2_phy" and "usb3_phy" for sun8i-h3 - * "usb0_phy" and "usb3_phy" for sun50i-h6 -- resets : a list of phandle + reset specifier pairs -- reset-names : - * "usb0_reset" - * "usb1_reset" - * "usb2_reset" for sun4i, sun6i, sun7i, sun8i-a83t or sun8i-h3 - * "usb3_reset" for sun8i-h3 and sun50i-h6 - -Optional properties: -- usb0_id_det-gpios : gpio phandle for reading the otg id pin value -- usb0_vbus_det-gpios : gpio phandle for detecting the presence of usb0 vbus -- usb0_vbus_power-supply: power-supply phandle for usb0 vbus presence detect -- usb0_vbus-supply : regulator phandle for controller usb0 vbus -- usb1_vbus-supply : regulator phandle for controller usb1 vbus -- usb2_vbus-supply : regulator phandle for controller usb2 vbus -- usb3_vbus-supply : regulator phandle for controller usb3 vbus - -Example: - usbphy: phy@01c13400 { - #phy-cells = <1>; - compatible = "allwinner,sun4i-a10-usb-phy"; - /* phy base regs, phy1 pmu reg, phy2 pmu reg */ - reg = <0x01c13400 0x10 0x01c14800 0x4 0x01c1c800 0x4>; - reg-names = "phy_ctrl", "pmu1", "pmu2"; - clocks = <&usb_clk 8>; - clock-names = "usb_phy"; - resets = <&usb_clk 0>, <&usb_clk 1>, <&usb_clk 2>; - reset-names = "usb0_reset", "usb1_reset", "usb2_reset"; - pinctrl-names = "default"; - pinctrl-0 = <&usb0_id_detect_pin>, <&usb0_vbus_detect_pin>; - usb0_id_det-gpios = <&pio 7 19 GPIO_ACTIVE_HIGH>; /* PH19 */ - usb0_vbus_det-gpios = <&pio 7 22 GPIO_ACTIVE_HIGH>; /* PH22 */ - usb0_vbus-supply = <®_usb0_vbus>; - usb1_vbus-supply = <®_usb1_vbus>; - usb2_vbus-supply = <®_usb2_vbus>; - }; diff --git a/Documentation/devicetree/bindings/phy/sun9i-usb-phy.txt b/Documentation/devicetree/bindings/phy/sun9i-usb-phy.txt deleted file mode 100644 index 64f7109aea1f..000000000000 --- a/Documentation/devicetree/bindings/phy/sun9i-usb-phy.txt +++ /dev/null @@ -1,37 +0,0 @@ -Allwinner sun9i USB PHY ------------------------ - -Required properties: -- compatible : should be one of - * allwinner,sun9i-a80-usb-phy -- reg : a list of offset + length pairs -- #phy-cells : from the generic phy bindings, must be 0 -- phy_type : "hsic" for HSIC usage; - other values or absence of this property indicates normal USB -- clocks : phandle + clock specifier for the phy clocks -- clock-names : depending on the "phy_type" property, - * "phy" for normal USB - * "hsic_480M", "hsic_12M" for HSIC -- resets : a list of phandle + reset specifier pairs -- reset-names : depending on the "phy_type" property, - * "phy" for normal USB - * "hsic" for HSIC - -Optional Properties: -- phy-supply : from the generic phy bindings, a phandle to a regulator that - provides power to VBUS. - -It is recommended to list all clocks and resets available. -The driver will only use those matching the phy_type. - -Example: - usbphy1: phy@a01800 { - compatible = "allwinner,sun9i-a80-usb-phy"; - reg = <0x00a01800 0x4>; - clocks = <&usb_phy_clk 2>, <&usb_phy_clk 10>, - <&usb_phy_clk 3>; - clock-names = "hsic_480M", "hsic_12M", "phy"; - resets = <&usb_phy_clk 18>, <&usb_phy_clk 19>; - reset-names = "hsic", "phy"; - #phy-cells = <0>; - }; diff --git a/Documentation/devicetree/bindings/phy/ti,phy-j721e-wiz.yaml b/Documentation/devicetree/bindings/phy/ti,phy-j721e-wiz.yaml new file mode 100644 index 000000000000..452cee1aed32 --- /dev/null +++ b/Documentation/devicetree/bindings/phy/ti,phy-j721e-wiz.yaml @@ -0,0 +1,221 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +# Copyright (C) 2019 Texas Instruments Incorporated - http://www.ti.com/ +%YAML 1.2 +--- +$id: "http://devicetree.org/schemas/phy/ti,phy-j721e-wiz.yaml#" +$schema: "http://devicetree.org/meta-schemas/core.yaml#" + +title: TI J721E WIZ (SERDES Wrapper) + +maintainers: + - Kishon Vijay Abraham I <kishon@ti.com> + +properties: + compatible: + enum: + - ti,j721e-wiz-16g + - ti,j721e-wiz-10g + + power-domains: + maxItems: 1 + + clocks: + maxItems: 3 + description: clock-specifier to represent input to the WIZ + + clock-names: + items: + - const: fck + - const: core_ref_clk + - const: ext_ref_clk + + num-lanes: + minimum: 1 + maximum: 4 + + "#address-cells": + const: 1 + + "#size-cells": + const: 1 + + "#reset-cells": + const: 1 + + ranges: true + + assigned-clocks: + maxItems: 2 + + assigned-clock-parents: + maxItems: 2 + + typec-dir-gpios: + maxItems: 1 + description: + GPIO to signal Type-C cable orientation for lane swap. + If GPIO is active, lane 0 and lane 1 of SERDES will be swapped to + achieve the funtionality of an external type-C plug flip mux. + + typec-dir-debounce-ms: + minimum: 100 + maximum: 1000 + default: 100 + description: + Number of milliseconds to wait before sampling typec-dir-gpio. + If not specified, the default debounce of 100ms will be used. + Type-C spec states minimum CC pin debounce of 100 ms and maximum + of 200 ms. However, some solutions might need more than 200 ms. + +patternProperties: + "^pll[0|1]-refclk$": + type: object + description: | + WIZ node should have subnodes for each of the PLLs present in + the SERDES. + properties: + clocks: + maxItems: 2 + description: Phandle to clock nodes representing the two inputs to PLL. + + "#clock-cells": + const: 0 + + assigned-clocks: + maxItems: 1 + + assigned-clock-parents: + maxItems: 1 + + required: + - clocks + - "#clock-cells" + - assigned-clocks + - assigned-clock-parents + + "^cmn-refclk1?-dig-div$": + type: object + description: + WIZ node should have subnodes for each of the PMA common refclock + provided by the SERDES. + properties: + clocks: + maxItems: 1 + description: Phandle to the clock node representing the input to the + divider clock. + + "#clock-cells": + const: 0 + + required: + - clocks + - "#clock-cells" + + "^refclk-dig$": + type: object + description: | + WIZ node should have subnode for refclk_dig to select the reference + clock source for the reference clock used in the PHY and PMA digital + logic. + properties: + clocks: + maxItems: 4 + description: Phandle to four clock nodes representing the inputs to + refclk_dig + + "#clock-cells": + const: 0 + + assigned-clocks: + maxItems: 1 + + assigned-clock-parents: + maxItems: 1 + + required: + - clocks + - "#clock-cells" + - assigned-clocks + - assigned-clock-parents + + "^serdes@[0-9a-f]+$": + type: object + description: | + WIZ node should have '1' subnode for the SERDES. It could be either + Sierra SERDES or Torrent SERDES. Sierra SERDES should follow the + bindings specified in + Documentation/devicetree/bindings/phy/phy-cadence-sierra.txt + Torrent SERDES should follow the bindings specified in + Documentation/devicetree/bindings/phy/phy-cadence-dp.txt + +required: + - compatible + - power-domains + - clocks + - clock-names + - num-lanes + - "#address-cells" + - "#size-cells" + - "#reset-cells" + - ranges + +examples: + - | + #include <dt-bindings/soc/ti,sci_pm_domain.h> + + wiz@5000000 { + compatible = "ti,j721e-wiz-16g"; + #address-cells = <1>; + #size-cells = <1>; + power-domains = <&k3_pds 292 TI_SCI_PD_EXCLUSIVE>; + clocks = <&k3_clks 292 5>, <&k3_clks 292 11>, <&dummy_cmn_refclk>; + clock-names = "fck", "core_ref_clk", "ext_ref_clk"; + assigned-clocks = <&k3_clks 292 11>, <&k3_clks 292 0>; + assigned-clock-parents = <&k3_clks 292 15>, <&k3_clks 292 4>; + num-lanes = <2>; + #reset-cells = <1>; + ranges = <0x5000000 0x5000000 0x10000>; + + pll0-refclk { + clocks = <&k3_clks 293 13>, <&dummy_cmn_refclk>; + #clock-cells = <0>; + assigned-clocks = <&wiz1_pll0_refclk>; + assigned-clock-parents = <&k3_clks 293 13>; + }; + + pll1-refclk { + clocks = <&k3_clks 293 0>, <&dummy_cmn_refclk1>; + #clock-cells = <0>; + assigned-clocks = <&wiz1_pll1_refclk>; + assigned-clock-parents = <&k3_clks 293 0>; + }; + + cmn-refclk-dig-div { + clocks = <&wiz1_refclk_dig>; + #clock-cells = <0>; + }; + + cmn-refclk1-dig-div { + clocks = <&wiz1_pll1_refclk>; + #clock-cells = <0>; + }; + + refclk-dig { + clocks = <&k3_clks 292 11>, <&k3_clks 292 0>, <&dummy_cmn_refclk>, <&dummy_cmn_refclk1>; + #clock-cells = <0>; + assigned-clocks = <&wiz0_refclk_dig>; + assigned-clock-parents = <&k3_clks 292 11>; + }; + + serdes@5000000 { + compatible = "cdns,ti,sierra-phy-t0"; + reg-names = "serdes"; + reg = <0x5000000 0x10000>; + #address-cells = <1>; + #size-cells = <0>; + resets = <&serdes_wiz0 0>; + reset-names = "sierra_reset"; + clocks = <&wiz0_cmn_refclk_dig_div>, <&wiz0_cmn_refclk1_dig_div>; + clock-names = "cmn_refclk_dig_div", "cmn_refclk1_dig_div"; + }; + }; diff --git a/Documentation/devicetree/bindings/pinctrl/aspeed,ast2400-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/aspeed,ast2400-pinctrl.yaml index 39ad8657d018..bb690e20c368 100644 --- a/Documentation/devicetree/bindings/pinctrl/aspeed,ast2400-pinctrl.yaml +++ b/Documentation/devicetree/bindings/pinctrl/aspeed,ast2400-pinctrl.yaml @@ -22,6 +22,9 @@ description: |+ properties: compatible: const: aspeed,ast2400-pinctrl + reg: + description: | + A hint for the memory regions associated with the pin-controller patternProperties: '^.*$': diff --git a/Documentation/devicetree/bindings/pinctrl/aspeed,ast2500-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/aspeed,ast2500-pinctrl.yaml index 3c6405be07ed..f7f5d57f2c9a 100644 --- a/Documentation/devicetree/bindings/pinctrl/aspeed,ast2500-pinctrl.yaml +++ b/Documentation/devicetree/bindings/pinctrl/aspeed,ast2500-pinctrl.yaml @@ -23,6 +23,9 @@ description: |+ properties: compatible: const: aspeed,ast2500-pinctrl + reg: + description: | + A hint for the memory regions associated with the pin-controller aspeed,external-nodes: minItems: 2 maxItems: 2 diff --git a/Documentation/devicetree/bindings/pinctrl/aspeed,ast2600-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/aspeed,ast2600-pinctrl.yaml index 064b7dfc4252..3749fa233e87 100644 --- a/Documentation/devicetree/bindings/pinctrl/aspeed,ast2600-pinctrl.yaml +++ b/Documentation/devicetree/bindings/pinctrl/aspeed,ast2600-pinctrl.yaml @@ -54,8 +54,9 @@ patternProperties: TACH10, TACH11, TACH12, TACH13, TACH14, TACH15, TACH2, TACH3, TACH4, TACH5, TACH6, TACH7, TACH8, TACH9, THRU0, THRU1, THRU2, THRU3, TXD1, TXD2, TXD3, TXD4, UART10, UART11, UART12, UART13, - UART6, UART7, UART8, UART9, VB, VGAHS, VGAVS, WDTRST1, WDTRST2, - WDTRST3, WDTRST4, ] + UART6, UART7, UART8, UART9, USBAD, USBADP, USB2AH, USB2AHP, + USB2BD, USB2BH, VB, VGAHS, VGAVS, WDTRST1, WDTRST2, WDTRST3, + WDTRST4, ] groups: allOf: - $ref: "/schemas/types.yaml#/definitions/string" @@ -85,8 +86,8 @@ patternProperties: TACH10, TACH11, TACH12, TACH13, TACH14, TACH15, TACH2, TACH3, TACH4, TACH5, TACH6, TACH7, TACH8, TACH9, THRU0, THRU1, THRU2, THRU3, TXD1, TXD2, TXD3, TXD4, UART10, UART11, UART12G0, - UART12G1, UART13G0, UART13G1, UART6, UART7, UART8, UART9, VB, - VGAHS, VGAVS, WDTRST1, WDTRST2, WDTRST3, WDTRST4, ] + UART12G1, UART13G0, UART13G1, UART6, UART7, UART8, UART9, USBA, + USBB, VB, VGAHS, VGAVS, WDTRST1, WDTRST2, WDTRST3, WDTRST4, ] required: - compatible diff --git a/Documentation/devicetree/bindings/pinctrl/fsl,imx8mp-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/fsl,imx8mp-pinctrl.yaml new file mode 100644 index 000000000000..2e31e120395e --- /dev/null +++ b/Documentation/devicetree/bindings/pinctrl/fsl,imx8mp-pinctrl.yaml @@ -0,0 +1,69 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/pinctrl/fsl,imx8mp-pinctrl.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Freescale IMX8MP IOMUX Controller + +maintainers: + - Anson Huang <Anson.Huang@nxp.com> + +description: + Please refer to fsl,imx-pinctrl.txt and pinctrl-bindings.txt in this directory + for common binding part and usage. + +properties: + compatible: + const: fsl,imx8mp-iomuxc + + reg: + maxItems: 1 + +# Client device subnode's properties +patternProperties: + 'grp$': + type: object + description: + Pinctrl node's client devices use subnodes for desired pin configuration. + Client device subnodes use below standard properties. + + properties: + fsl,pins: + allOf: + - $ref: /schemas/types.yaml#/definitions/uint32-array + 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/imx8mp-pinfunc.h>. The last + integer CONFIG is the pad setting value like pull-up on this pin. Please + refer to i.MX8M Plus Reference Manual for detailed CONFIG settings. + + required: + - fsl,pins + + additionalProperties: false + +required: + - compatible + - reg + +additionalProperties: false + +examples: + # Pinmux controller node + - | + iomuxc: pinctrl@30330000 { + compatible = "fsl,imx8mp-iomuxc"; + reg = <0x30330000 0x10000>; + + pinctrl_uart2: uart2grp { + fsl,pins = < + 0x228 0x488 0x5F0 0x0 0x6 0x49 + 0x228 0x488 0x000 0x0 0x0 0x49 + >; + }; + }; + +... diff --git a/Documentation/devicetree/bindings/pinctrl/ingenic,pinctrl.txt b/Documentation/devicetree/bindings/pinctrl/ingenic,pinctrl.txt index 0014d9899797..d9b2100c98e8 100644 --- a/Documentation/devicetree/bindings/pinctrl/ingenic,pinctrl.txt +++ b/Documentation/devicetree/bindings/pinctrl/ingenic,pinctrl.txt @@ -10,9 +10,9 @@ GPIO port configuration registers and it is typical to refer to pins using the naming scheme "PxN" where x is a character identifying the GPIO port with which the pin is associated and N is an integer from 0 to 31 identifying the pin within that GPIO port. For example PA0 is the first pin in GPIO port A, and -PB31 is the last pin in GPIO port B. The jz4740 and the x1000 contains 4 GPIO -ports, PA to PD, for a total of 128 pins. The jz4760, the jz4770 and the jz4780 -contains 6 GPIO ports, PA to PF, for a total of 192 pins. +PB31 is the last pin in GPIO port B. The jz4740, the x1000 and the x1830 +contains 4 GPIO ports, PA to PD, for a total of 128 pins. The jz4760, the +jz4770 and the jz4780 contains 6 GPIO ports, PA to PF, for a total of 192 pins. Required properties: @@ -28,6 +28,7 @@ Required properties: - "ingenic,x1000-pinctrl" - "ingenic,x1000e-pinctrl" - "ingenic,x1500-pinctrl" + - "ingenic,x1830-pinctrl" - reg: Address range of the pinctrl registers. @@ -40,6 +41,7 @@ Required properties for sub-nodes (GPIO chips): - "ingenic,jz4770-gpio" - "ingenic,jz4780-gpio" - "ingenic,x1000-gpio" + - "ingenic,x1830-gpio" - reg: The GPIO bank number. - interrupt-controller: Marks the device node as an interrupt controller. - interrupts: Interrupt specifier for the controllers interrupt. diff --git a/Documentation/devicetree/bindings/pinctrl/intel,lgm-io.yaml b/Documentation/devicetree/bindings/pinctrl/intel,lgm-io.yaml new file mode 100644 index 000000000000..cd2b436350ef --- /dev/null +++ b/Documentation/devicetree/bindings/pinctrl/intel,lgm-io.yaml @@ -0,0 +1,75 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/pinctrl/intel,lgm-io.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Intel Lightning Mountain SoC pinmux & GPIO controller binding + +maintainers: + - Rahul Tanwar <rahul.tanwar@linux.intel.com> + +description: | + Pinmux & GPIO controller controls pin multiplexing & configuration including + GPIO function selection & GPIO attributes configuration. + +properties: + compatible: + const: intel,lgm-io + + reg: + maxItems: 1 + +# Client device subnode's properties +patternProperties: + '-pins$': + type: object + allOf: + - $ref: pincfg-node.yaml# + - $ref: pinmux-node.yaml# + description: + Pinctrl node's client devices use subnodes for desired pin configuration. + Client device subnodes use below standard properties. + + properties: + function: true + groups: true + pins: true + pinmux: true + bias-pull-up: true + bias-pull-down: true + drive-strength: true + slew-rate: true + drive-open-drain: true + output-enable: true + + required: + - function + - groups + + additionalProperties: false + +required: + - compatible + - reg + +additionalProperties: false + +examples: + # Pinmux controller node + - | + pinctrl: pinctrl@e2880000 { + compatible = "intel,lgm-io"; + reg = <0xe2880000 0x100000>; + + uart0-pins { + pins = <64>, /* UART_RX0 */ + <65>; /* UART_TX0 */ + function = "CONSOLE_UART0"; + pinmux = <1>, + <1>; + groups = "CONSOLE_UART0"; + }; + }; + +... diff --git a/Documentation/devicetree/bindings/pinctrl/intel,lgm-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/intel,lgm-pinctrl.yaml deleted file mode 100644 index 240d429f773b..000000000000 --- a/Documentation/devicetree/bindings/pinctrl/intel,lgm-pinctrl.yaml +++ /dev/null @@ -1,116 +0,0 @@ -# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) -%YAML 1.2 ---- -$id: http://devicetree.org/schemas/bindings/pinctrl/intel,lgm-pinctrl.yaml# -$schema: http://devicetree.org/meta-schemas/core.yaml# - -title: Intel Lightning Mountain SoC pinmux & GPIO controller binding - -maintainers: - - Rahul Tanwar <rahul.tanwar@linux.intel.com> - -description: | - Pinmux & GPIO controller controls pin multiplexing & configuration including - GPIO function selection & GPIO attributes configuration. - - Please refer to [1] for details of the common pinctrl bindings used by the - client devices. - - [1] Documentation/devicetree/bindings/pinctrl/pinctrl-bindings.txt - -properties: - compatible: - const: intel,lgm-io - - reg: - maxItems: 1 - -# Client device subnode's properties -patternProperties: - '-pins$': - type: object - description: - Pinctrl node's client devices use subnodes for desired pin configuration. - Client device subnodes use below standard properties. - - properties: - function: - $ref: /schemas/types.yaml#/definitions/string - description: - A string containing the name of the function to mux to the group. - - groups: - $ref: /schemas/types.yaml#/definitions/string-array - description: - An array of strings identifying the list of groups. - - pins: - $ref: /schemas/types.yaml#/definitions/uint32-array - description: - List of pins to select with this function. - - pinmux: - description: The applicable mux group. - allOf: - - $ref: "/schemas/types.yaml#/definitions/uint32-array" - - bias-pull-up: - type: boolean - - bias-pull-down: - type: boolean - - drive-strength: - description: | - Selects the drive strength for the specified pins in mA. - 0: 2 mA - 1: 4 mA - 2: 8 mA - 3: 12 mA - allOf: - - $ref: /schemas/types.yaml#/definitions/uint32 - - enum: [0, 1, 2, 3] - - slew-rate: - type: boolean - description: | - Sets slew rate for specified pins. - 0: slow slew - 1: fast slew - - drive-open-drain: - type: boolean - - output-enable: - type: boolean - - required: - - function - - groups - - additionalProperties: false - -required: - - compatible - - reg - -additionalProperties: false - -examples: - # Pinmux controller node - - | - pinctrl: pinctrl@e2880000 { - compatible = "intel,lgm-pinctrl"; - reg = <0xe2880000 0x100000>; - - uart0-pins { - pins = <64>, /* UART_RX0 */ - <65>; /* UART_TX0 */ - function = "CONSOLE_UART0"; - pinmux = <1>, - <1>; - groups = "CONSOLE_UART0"; - }; - }; - -... diff --git a/Documentation/devicetree/bindings/pinctrl/pinmux-node.yaml b/Documentation/devicetree/bindings/pinctrl/pinmux-node.yaml index 777623a57fd5..732d9075560b 100644 --- a/Documentation/devicetree/bindings/pinctrl/pinmux-node.yaml +++ b/Documentation/devicetree/bindings/pinctrl/pinmux-node.yaml @@ -114,7 +114,7 @@ properties: specific binding for the hardware defines whether the entries are integers or strings, and their meaning. - group: + groups: $ref: /schemas/types.yaml#/definitions/string-array description: the group to apply the properties to, if the driver supports diff --git a/Documentation/devicetree/bindings/pinctrl/qcom,sc7180-pinctrl.txt b/Documentation/devicetree/bindings/pinctrl/qcom,sc7180-pinctrl.txt index b5767ee82ee6..6ffeac9801df 100644 --- a/Documentation/devicetree/bindings/pinctrl/qcom,sc7180-pinctrl.txt +++ b/Documentation/devicetree/bindings/pinctrl/qcom,sc7180-pinctrl.txt @@ -125,8 +125,9 @@ to specify in a pin configuration subnode: mi2s_1, mi2s_2, mss_lte, m_voc, pa_indicator, phase_flag, PLL_BIST, pll_bypassnl, pll_reset, prng_rosc, qdss, qdss_cti, qlink_enable, qlink_request, qspi_clk, qspi_cs, - qspi_data, qup00, qup01, qup02, qup03, qup04, qup05, - qup10, qup11, qup12, qup13, qup14, qup15, sdc1_tb, + qspi_data, qup00, qup01, qup02_i2c, qup02_uart, qup03, + qup04_i2c, qup04_uart, qup05, qup10, qup11_i2c, qup11_uart, + qup12, qup13_i2c, qup13_uart, qup14, qup15, sdc1_tb, sdc2_tb, sd_write, sp_cmu, tgu_ch0, tgu_ch1, tgu_ch2, tgu_ch3, tsense_pwm1, tsense_pwm2, uim1, uim2, uim_batt, usb_phy, vfr_1, _V_GPIO, _V_PPS_IN, _V_PPS_OUT, diff --git a/Documentation/devicetree/bindings/power/avs/qcom,cpr.txt b/Documentation/devicetree/bindings/power/avs/qcom,cpr.txt new file mode 100644 index 000000000000..ab0d5ebbad4e --- /dev/null +++ b/Documentation/devicetree/bindings/power/avs/qcom,cpr.txt @@ -0,0 +1,130 @@ +QCOM CPR (Core Power Reduction) + +CPR (Core Power Reduction) is a technology to reduce core power on a CPU +or other device. Each OPP of a device corresponds to a "corner" that has +a range of valid voltages for a particular frequency. While the device is +running at a particular frequency, CPR monitors dynamic factors such as +temperature, etc. and suggests adjustments to the voltage to save power +and meet silicon characteristic requirements. + +- compatible: + Usage: required + Value type: <string> + Definition: should be "qcom,qcs404-cpr", "qcom,cpr" for qcs404 + +- reg: + Usage: required + Value type: <prop-encoded-array> + Definition: base address and size of the rbcpr register region + +- interrupts: + Usage: required + Value type: <prop-encoded-array> + Definition: should specify the CPR interrupt + +- clocks: + Usage: required + Value type: <prop-encoded-array> + Definition: phandle to the reference clock + +- clock-names: + Usage: required + Value type: <stringlist> + Definition: must be "ref" + +- vdd-apc-supply: + Usage: required + Value type: <phandle> + Definition: phandle to the vdd-apc-supply regulator + +- #power-domain-cells: + Usage: required + Value type: <u32> + Definition: should be 0 + +- operating-points-v2: + Usage: required + Value type: <phandle> + Definition: A phandle to the OPP table containing the + performance states supported by the CPR + power domain + +- acc-syscon: + Usage: optional + Value type: <phandle> + Definition: phandle to syscon for writing ACC settings + +- nvmem-cells: + Usage: required + Value type: <phandle> + Definition: phandle to nvmem cells containing the data + that makes up a fuse corner, for each fuse corner. + As well as the CPR fuse revision. + +- nvmem-cell-names: + Usage: required + Value type: <stringlist> + Definition: should be "cpr_quotient_offset1", "cpr_quotient_offset2", + "cpr_quotient_offset3", "cpr_init_voltage1", + "cpr_init_voltage2", "cpr_init_voltage3", "cpr_quotient1", + "cpr_quotient2", "cpr_quotient3", "cpr_ring_osc1", + "cpr_ring_osc2", "cpr_ring_osc3", "cpr_fuse_revision" + for qcs404. + +Example: + + cpr_opp_table: cpr-opp-table { + compatible = "operating-points-v2-qcom-level"; + + cpr_opp1: opp1 { + opp-level = <1>; + qcom,opp-fuse-level = <1>; + }; + cpr_opp2: opp2 { + opp-level = <2>; + qcom,opp-fuse-level = <2>; + }; + cpr_opp3: opp3 { + opp-level = <3>; + qcom,opp-fuse-level = <3>; + }; + }; + + power-controller@b018000 { + compatible = "qcom,qcs404-cpr", "qcom,cpr"; + reg = <0x0b018000 0x1000>; + interrupts = <0 15 IRQ_TYPE_EDGE_RISING>; + clocks = <&xo_board>; + clock-names = "ref"; + vdd-apc-supply = <&pms405_s3>; + #power-domain-cells = <0>; + operating-points-v2 = <&cpr_opp_table>; + acc-syscon = <&tcsr>; + + nvmem-cells = <&cpr_efuse_quot_offset1>, + <&cpr_efuse_quot_offset2>, + <&cpr_efuse_quot_offset3>, + <&cpr_efuse_init_voltage1>, + <&cpr_efuse_init_voltage2>, + <&cpr_efuse_init_voltage3>, + <&cpr_efuse_quot1>, + <&cpr_efuse_quot2>, + <&cpr_efuse_quot3>, + <&cpr_efuse_ring1>, + <&cpr_efuse_ring2>, + <&cpr_efuse_ring3>, + <&cpr_efuse_revision>; + nvmem-cell-names = "cpr_quotient_offset1", + "cpr_quotient_offset2", + "cpr_quotient_offset3", + "cpr_init_voltage1", + "cpr_init_voltage2", + "cpr_init_voltage3", + "cpr_quotient1", + "cpr_quotient2", + "cpr_quotient3", + "cpr_ring_osc1", + "cpr_ring_osc2", + "cpr_ring_osc3", + "cpr_fuse_revision"; + }; diff --git a/Documentation/devicetree/bindings/power/qcom,rpmpd.txt b/Documentation/devicetree/bindings/power/qcom,rpmpd.txt deleted file mode 100644 index bc75bf49cdae..000000000000 --- a/Documentation/devicetree/bindings/power/qcom,rpmpd.txt +++ /dev/null @@ -1,148 +0,0 @@ -Qualcomm RPM/RPMh Power domains - -For RPM/RPMh Power domains, we communicate a performance state to RPM/RPMh -which then translates it into a corresponding voltage on a rail - -Required Properties: - - compatible: Should be one of the following - * qcom,msm8976-rpmpd: RPM Power domain for the msm8976 family of SoC - * qcom,msm8996-rpmpd: RPM Power domain for the msm8996 family of SoC - * qcom,msm8998-rpmpd: RPM Power domain for the msm8998 family of SoC - * qcom,qcs404-rpmpd: RPM Power domain for the qcs404 family of SoC - * qcom,sdm845-rpmhpd: RPMh Power domain for the sdm845 family of SoC - - #power-domain-cells: number of cells in Power domain specifier - must be 1. - - operating-points-v2: Phandle to the OPP table for the Power domain. - Refer to Documentation/devicetree/bindings/power/power_domain.txt - and Documentation/devicetree/bindings/opp/opp.txt for more details - -Refer to <dt-bindings/power/qcom-rpmpd.h> for the level values for -various OPPs for different platforms as well as Power domain indexes - -Example: rpmh power domain controller and OPP table - -#include <dt-bindings/power/qcom-rpmhpd.h> - -opp-level values specified in the OPP tables for RPMh power domains -should use the RPMH_REGULATOR_LEVEL_* constants from -<dt-bindings/power/qcom-rpmhpd.h> - - rpmhpd: power-controller { - compatible = "qcom,sdm845-rpmhpd"; - #power-domain-cells = <1>; - operating-points-v2 = <&rpmhpd_opp_table>; - - rpmhpd_opp_table: opp-table { - compatible = "operating-points-v2"; - - rpmhpd_opp_ret: opp1 { - opp-level = <RPMH_REGULATOR_LEVEL_RETENTION>; - }; - - rpmhpd_opp_min_svs: opp2 { - opp-level = <RPMH_REGULATOR_LEVEL_MIN_SVS>; - }; - - rpmhpd_opp_low_svs: opp3 { - opp-level = <RPMH_REGULATOR_LEVEL_LOW_SVS>; - }; - - rpmhpd_opp_svs: opp4 { - opp-level = <RPMH_REGULATOR_LEVEL_SVS>; - }; - - rpmhpd_opp_svs_l1: opp5 { - opp-level = <RPMH_REGULATOR_LEVEL_SVS_L1>; - }; - - rpmhpd_opp_nom: opp6 { - opp-level = <RPMH_REGULATOR_LEVEL_NOM>; - }; - - rpmhpd_opp_nom_l1: opp7 { - opp-level = <RPMH_REGULATOR_LEVEL_NOM_L1>; - }; - - rpmhpd_opp_nom_l2: opp8 { - opp-level = <RPMH_REGULATOR_LEVEL_NOM_L2>; - }; - - rpmhpd_opp_turbo: opp9 { - opp-level = <RPMH_REGULATOR_LEVEL_TURBO>; - }; - - rpmhpd_opp_turbo_l1: opp10 { - opp-level = <RPMH_REGULATOR_LEVEL_TURBO_L1>; - }; - }; - }; - -Example: rpm power domain controller and OPP table - - rpmpd: power-controller { - compatible = "qcom,msm8996-rpmpd"; - #power-domain-cells = <1>; - operating-points-v2 = <&rpmpd_opp_table>; - - rpmpd_opp_table: opp-table { - compatible = "operating-points-v2"; - - rpmpd_opp_low: opp1 { - opp-level = <1>; - }; - - rpmpd_opp_ret: opp2 { - opp-level = <2>; - }; - - rpmpd_opp_svs: opp3 { - opp-level = <3>; - }; - - rpmpd_opp_normal: opp4 { - opp-level = <4>; - }; - - rpmpd_opp_high: opp5 { - opp-level = <5>; - }; - - rpmpd_opp_turbo: opp6 { - opp-level = <6>; - }; - }; - }; - -Example: Client/Consumer device using OPP table - - leaky-device0@12350000 { - compatible = "foo,i-leak-current"; - reg = <0x12350000 0x1000>; - power-domains = <&rpmhpd SDM845_MX>; - operating-points-v2 = <&leaky_opp_table>; - }; - - - leaky_opp_table: opp-table { - compatible = "operating-points-v2"; - - opp1 { - opp-hz = /bits/ 64 <144000>; - required-opps = <&rpmhpd_opp_low>; - }; - - opp2 { - opp-hz = /bits/ 64 <400000>; - required-opps = <&rpmhpd_opp_ret>; - }; - - opp3 { - opp-hz = /bits/ 64 <20000000>; - required-opps = <&rpmpd_opp_svs>; - }; - - opp4 { - opp-hz = /bits/ 64 <25000000>; - required-opps = <&rpmpd_opp_normal>; - }; - }; diff --git a/Documentation/devicetree/bindings/power/qcom,rpmpd.yaml b/Documentation/devicetree/bindings/power/qcom,rpmpd.yaml new file mode 100644 index 000000000000..ba605310abeb --- /dev/null +++ b/Documentation/devicetree/bindings/power/qcom,rpmpd.yaml @@ -0,0 +1,170 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/power/qcom,rpmpd.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Qualcomm RPM/RPMh Power domains + +maintainers: + - Rajendra Nayak <rnayak@codeaurora.org> + +description: + For RPM/RPMh Power domains, we communicate a performance state to RPM/RPMh + which then translates it into a corresponding voltage on a rail. + +properties: + compatible: + enum: + - qcom,msm8976-rpmpd + - qcom,msm8996-rpmpd + - qcom,msm8998-rpmpd + - qcom,qcs404-rpmpd + - qcom,sc7180-rpmhpd + - qcom,sdm845-rpmhpd + - qcom,sm8150-rpmhpd + + '#power-domain-cells': + const: 1 + + operating-points-v2: true + + opp-table: + type: object + +required: + - compatible + - '#power-domain-cells' + - operating-points-v2 + +additionalProperties: false + +examples: + - | + + // Example 1 (rpmh power domain controller and OPP table): + + #include <dt-bindings/power/qcom-rpmpd.h> + + rpmhpd: power-controller { + compatible = "qcom,sdm845-rpmhpd"; + #power-domain-cells = <1>; + operating-points-v2 = <&rpmhpd_opp_table>; + + rpmhpd_opp_table: opp-table { + compatible = "operating-points-v2"; + + rpmhpd_opp_ret: opp1 { + opp-level = <RPMH_REGULATOR_LEVEL_RETENTION>; + }; + + rpmhpd_opp_min_svs: opp2 { + opp-level = <RPMH_REGULATOR_LEVEL_MIN_SVS>; + }; + + rpmhpd_opp_low_svs: opp3 { + opp-level = <RPMH_REGULATOR_LEVEL_LOW_SVS>; + }; + + rpmhpd_opp_svs: opp4 { + opp-level = <RPMH_REGULATOR_LEVEL_SVS>; + }; + + rpmhpd_opp_svs_l1: opp5 { + opp-level = <RPMH_REGULATOR_LEVEL_SVS_L1>; + }; + + rpmhpd_opp_nom: opp6 { + opp-level = <RPMH_REGULATOR_LEVEL_NOM>; + }; + + rpmhpd_opp_nom_l1: opp7 { + opp-level = <RPMH_REGULATOR_LEVEL_NOM_L1>; + }; + + rpmhpd_opp_nom_l2: opp8 { + opp-level = <RPMH_REGULATOR_LEVEL_NOM_L2>; + }; + + rpmhpd_opp_turbo: opp9 { + opp-level = <RPMH_REGULATOR_LEVEL_TURBO>; + }; + + rpmhpd_opp_turbo_l1: opp10 { + opp-level = <RPMH_REGULATOR_LEVEL_TURBO_L1>; + }; + }; + }; + + - | + + // Example 2 (rpm power domain controller and OPP table): + + rpmpd: power-controller { + compatible = "qcom,msm8996-rpmpd"; + #power-domain-cells = <1>; + operating-points-v2 = <&rpmpd_opp_table>; + + rpmpd_opp_table: opp-table { + compatible = "operating-points-v2"; + + rpmpd_opp_low: opp1 { + opp-level = <1>; + }; + + rpmpd_opp_ret: opp2 { + opp-level = <2>; + }; + + rpmpd_opp_svs: opp3 { + opp-level = <3>; + }; + + rpmpd_opp_normal: opp4 { + opp-level = <4>; + }; + + rpmpd_opp_high: opp5 { + opp-level = <5>; + }; + + rpmpd_opp_turbo: opp6 { + opp-level = <6>; + }; + }; + }; + + - | + + // Example 3 (Client/Consumer device using OPP table): + + leaky-device0@12350000 { + compatible = "foo,i-leak-current"; + reg = <0x12350000 0x1000>; + power-domains = <&rpmhpd 0>; + operating-points-v2 = <&leaky_opp_table>; + }; + + leaky_opp_table: opp-table { + compatible = "operating-points-v2"; + opp1 { + opp-hz = /bits/ 64 <144000>; + required-opps = <&rpmhpd_opp_low>; + }; + + opp2 { + opp-hz = /bits/ 64 <400000>; + required-opps = <&rpmhpd_opp_ret>; + }; + + opp3 { + opp-hz = /bits/ 64 <20000000>; + required-opps = <&rpmpd_opp_svs>; + }; + + opp4 { + opp-hz = /bits/ 64 <25000000>; + required-opps = <&rpmpd_opp_normal>; + }; + }; +... diff --git a/Documentation/devicetree/bindings/power/reset/xlnx,zynqmp-power.txt b/Documentation/devicetree/bindings/power/reset/xlnx,zynqmp-power.txt index d366f1eb623a..bb529ecf8a57 100644 --- a/Documentation/devicetree/bindings/power/reset/xlnx,zynqmp-power.txt +++ b/Documentation/devicetree/bindings/power/reset/xlnx,zynqmp-power.txt @@ -8,9 +8,41 @@ Required properties: - compatible: Must contain: "xlnx,zynqmp-power" - interrupts: Interrupt specifier -------- -Example -------- +Optional properties: + - mbox-names : Name given to channels seen in the 'mboxes' property. + "tx" - Mailbox corresponding to transmit path + "rx" - Mailbox corresponding to receive path + - mboxes : Standard property to specify a Mailbox. Each value of + the mboxes property should contain a phandle to the + mailbox controller device node and an args specifier + that will be the phandle to the intended sub-mailbox + child node to be used for communication. See + Documentation/devicetree/bindings/mailbox/mailbox.txt + for more details about the generic mailbox controller + and client driver bindings. Also see + Documentation/devicetree/bindings/mailbox/ \ + xlnx,zynqmp-ipi-mailbox.txt for typical controller that + is used to communicate with this System controllers. + +-------- +Examples +-------- + +Example with interrupt method: + +firmware { + zynqmp_firmware: zynqmp-firmware { + compatible = "xlnx,zynqmp-firmware"; + method = "smc"; + + zynqmp_power: zynqmp-power { + compatible = "xlnx,zynqmp-power"; + interrupts = <0 35 4>; + }; + }; +}; + +Example with IPI mailbox method: firmware { zynqmp_firmware: zynqmp-firmware { @@ -19,7 +51,11 @@ firmware { zynqmp_power: zynqmp-power { compatible = "xlnx,zynqmp-power"; + interrupt-parent = <&gic>; interrupts = <0 35 4>; + mboxes = <&ipi_mailbox_pmu0 0>, + <&ipi_mailbox_pmu0 1>; + mbox-names = "tx", "rx"; }; }; }; diff --git a/Documentation/devicetree/bindings/power/supply/battery.txt b/Documentation/devicetree/bindings/power/supply/battery.txt index 5c913d4cf36c..3049cf88bdcf 100644 --- a/Documentation/devicetree/bindings/power/supply/battery.txt +++ b/Documentation/devicetree/bindings/power/supply/battery.txt @@ -35,6 +35,10 @@ Optional Properties: for each of the battery capacity lookup table. The first temperature value specifies the OCV table 0, and the second temperature value specifies the OCV table 1, and so on. + - resistance-temp-table: An array providing the temperature in degree Celsius + and corresponding battery internal resistance percent, which is used to look + up the resistance percent according to current temperature to get a accurate + batterty internal resistance in different temperatures. Battery properties are named, where possible, for the corresponding elements in enum power_supply_property, defined in @@ -61,6 +65,7 @@ Example: ocv-capacity-table-0 = <4185000 100>, <4113000 95>, <4066000 90>, ...; ocv-capacity-table-1 = <4200000 100>, <4185000 95>, <4113000 90>, ...; ocv-capacity-table-2 = <4250000 100>, <4200000 95>, <4185000 90>, ...; + resistance-temp-table = <20 100>, <10 90>, <0 80>, <(-10) 60>; }; charger: charger@11 { diff --git a/Documentation/devicetree/bindings/power/supply/bq25890.txt b/Documentation/devicetree/bindings/power/supply/bq25890.txt index dc0568933359..dc9c8f76e06c 100644 --- a/Documentation/devicetree/bindings/power/supply/bq25890.txt +++ b/Documentation/devicetree/bindings/power/supply/bq25890.txt @@ -1,11 +1,14 @@ Binding for TI bq25890 Li-Ion Charger -This driver will support the bq25896 and the bq25890. There are other ICs -in the same family but those have not been tested. +This driver will support the bq25892, the bq25896 and the bq25890. There are +other ICs in the same family but those have not been tested. Required properties: - compatible: Should contain one of the following: * "ti,bq25890" + * "ti,bq25892" + * "ti,bq25895" + * "ti,bq25896" - reg: integer, i2c address of the device. - ti,battery-regulation-voltage: integer, maximum charging voltage (in uV); - ti,charge-current: integer, maximum charging current (in uA); diff --git a/Documentation/devicetree/bindings/power/supply/max17040_battery.txt b/Documentation/devicetree/bindings/power/supply/max17040_battery.txt new file mode 100644 index 000000000000..4e0186b8380f --- /dev/null +++ b/Documentation/devicetree/bindings/power/supply/max17040_battery.txt @@ -0,0 +1,33 @@ +max17040_battery +~~~~~~~~~~~~~~~~ + +Required properties : + - compatible : "maxim,max17040" or "maxim,max77836-battery" + - reg: i2c slave address + +Optional properties : +- maxim,alert-low-soc-level : The alert threshold that sets the state of + charge level (%) where an interrupt is + generated. Can be configured from 1 up to 32 + (%). If skipped the power up default value of + 4 (%) will be used. +- interrupts : Interrupt line see Documentation/devicetree/ + bindings/interrupt-controller/interrupts.txt +- wakeup-source : This device has wakeup capabilities. Use this + property to use alert low SOC level interrupt + as wake up source. + +Optional properties support interrupt functionality for alert low state of +charge level, present in some ICs in the same family, and should be used with +compatible "maxim,max77836-battery". + +Example: + + battery-fuel-gauge@36 { + compatible = "maxim,max77836-battery"; + reg = <0x36>; + maxim,alert-low-soc-level = <10>; + interrupt-parent = <&gpio7>; + interrupts = <2 IRQ_TYPE_EDGE_FALLING>; + wakeup-source; + }; diff --git a/Documentation/devicetree/bindings/power/supply/max17042_battery.txt b/Documentation/devicetree/bindings/power/supply/max17042_battery.txt index 3f3894aaeebc..f34c5daae9af 100644 --- a/Documentation/devicetree/bindings/power/supply/max17042_battery.txt +++ b/Documentation/devicetree/bindings/power/supply/max17042_battery.txt @@ -2,7 +2,11 @@ max17042_battery ~~~~~~~~~~~~~~~~ Required properties : - - compatible : "maxim,max17042" + - compatible : one of the following + * "maxim,max17042" + * "maxim,max17047" + * "maxim,max17050" + * "maxim,max17055" Optional properties : - maxim,rsns-microohm : Resistance of rsns resistor in micro Ohms diff --git a/Documentation/devicetree/bindings/power/supply/sc27xx-fg.txt b/Documentation/devicetree/bindings/power/supply/sc27xx-fg.txt index 0a5705b8b592..b6359b590383 100644 --- a/Documentation/devicetree/bindings/power/supply/sc27xx-fg.txt +++ b/Documentation/devicetree/bindings/power/supply/sc27xx-fg.txt @@ -13,6 +13,8 @@ Required properties: - io-channel-names: Should be "bat-temp" or "charge-vol". - nvmem-cells: A phandle to the calibration cells provided by eFuse device. - nvmem-cell-names: Should be "fgu_calib". +- sprd,calib-resistance-micro-ohms: Specify the real resistance of coulomb counter + chip in micro Ohms. - monitored-battery: Phandle of battery characteristics devicetree node. See Documentation/devicetree/bindings/power/supply/battery.txt @@ -52,5 +54,6 @@ Example: nvmem-cells = <&fgu_calib>; nvmem-cell-names = "fgu_calib"; monitored-battery = <&bat>; + sprd,calib-resistance-micro-ohms = <21500>; }; }; diff --git a/Documentation/devicetree/bindings/ptp/ptp-ines.txt b/Documentation/devicetree/bindings/ptp/ptp-ines.txt new file mode 100644 index 000000000000..4c242bd1ce9c --- /dev/null +++ b/Documentation/devicetree/bindings/ptp/ptp-ines.txt @@ -0,0 +1,35 @@ +ZHAW InES PTP time stamping IP core + +The IP core needs two different kinds of nodes. The control node +lives somewhere in the memory map and specifies the address of the +control registers. There can be up to three port handles placed as +attributes of PHY nodes. These associate a particular MII bus with a +port index within the IP core. + +Required properties of the control node: + +- compatible: "ines,ptp-ctrl" +- reg: physical address and size of the register bank + +Required format of the port handle within the PHY node: + +- timestamper: provides control node reference and + the port channel within the IP core + +Example: + + tstamper: timestamper@60000000 { + compatible = "ines,ptp-ctrl"; + reg = <0x60000000 0x80>; + }; + + ethernet@80000000 { + ... + mdio { + ... + ethernet-phy@3 { + ... + timestamper = <&tstamper 0>; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/ptp/timestamper.txt b/Documentation/devicetree/bindings/ptp/timestamper.txt new file mode 100644 index 000000000000..fc550ce4d4ea --- /dev/null +++ b/Documentation/devicetree/bindings/ptp/timestamper.txt @@ -0,0 +1,42 @@ +Time stamps from MII bus snooping devices + +This binding supports non-PHY devices that snoop the MII bus and +provide time stamps. In contrast to PHY time stamping drivers (which +can simply attach their interface directly to the PHY instance), stand +alone MII time stamping drivers use this binding to specify the +connection between the snooping device and a given network interface. + +Non-PHY MII time stamping drivers typically talk to the control +interface over another bus like I2C, SPI, UART, or via a memory mapped +peripheral. This controller device is associated with one or more +time stamping channels, each of which snoops on a MII bus. + +The "timestamper" property lives in a phy node and links a time +stamping channel from the controller device to that phy's MII bus. + +Example: + + tstamper: timestamper@10000000 { + compatible = "ines,ptp-ctrl"; + reg = <0x10000000 0x80>; + }; + + ethernet@20000000 { + mdio { + ethernet-phy@1 { + timestamper = <&tstamper 0>; + }; + }; + }; + + ethernet@30000000 { + mdio { + ethernet-phy@2 { + timestamper = <&tstamper 1>; + }; + }; + }; + +In this example, time stamps from the MII bus attached to phy@1 will +appear on time stamp channel 0 (zero), and those from phy@2 appear on +channel 1. diff --git a/Documentation/devicetree/bindings/pwm/allwinner,sun4i-a10-pwm.yaml b/Documentation/devicetree/bindings/pwm/allwinner,sun4i-a10-pwm.yaml index 4a21fe77ee1d..7dcab2bf8128 100644 --- a/Documentation/devicetree/bindings/pwm/allwinner,sun4i-a10-pwm.yaml +++ b/Documentation/devicetree/bindings/pwm/allwinner,sun4i-a10-pwm.yaml @@ -30,13 +30,51 @@ properties: - items: - const: allwinner,sun50i-h5-pwm - const: allwinner,sun5i-a13-pwm + - const: allwinner,sun50i-h6-pwm reg: maxItems: 1 clocks: + minItems: 1 + maxItems: 2 + items: + - description: Module Clock + - description: Bus Clock + + # Even though it only applies to subschemas under the conditionals, + # not listing them here will trigger a warning because of the + # additionalsProperties set to false. + clock-names: true + + resets: maxItems: 1 +if: + properties: + compatible: + contains: + const: allwinner,sun50i-h6-pwm + +then: + properties: + clocks: + maxItems: 2 + + clock-names: + items: + - const: mod + - const: bus + + required: + - clock-names + - resets + +else: + properties: + clocks: + maxItems: 1 + required: - "#pwm-cells" - compatible @@ -54,4 +92,17 @@ examples: #pwm-cells = <3>; }; + - | + #include <dt-bindings/clock/sun50i-h6-ccu.h> + #include <dt-bindings/reset/sun50i-h6-ccu.h> + + pwm@300a000 { + compatible = "allwinner,sun50i-h6-pwm"; + reg = <0x0300a000 0x400>; + clocks = <&osc24M>, <&ccu CLK_BUS_PWM>; + clock-names = "mod", "bus"; + resets = <&ccu RST_BUS_PWM>; + #pwm-cells = <3>; + }; + ... diff --git a/Documentation/devicetree/bindings/pwm/mxs-pwm.txt b/Documentation/devicetree/bindings/pwm/mxs-pwm.txt index 1b06f86a7091..a1b8a482f873 100644 --- a/Documentation/devicetree/bindings/pwm/mxs-pwm.txt +++ b/Documentation/devicetree/bindings/pwm/mxs-pwm.txt @@ -3,7 +3,7 @@ Freescale MXS PWM controller Required properties: - compatible: should be "fsl,imx23-pwm" - reg: physical base address and length of the controller's registers -- #pwm-cells: should be 2. See pwm.yaml in this directory for a description of +- #pwm-cells: should be 3. See pwm.yaml in this directory for a description of the cells format. - fsl,pwm-number: the number of PWM devices @@ -12,6 +12,6 @@ Example: pwm: pwm@80064000 { compatible = "fsl,imx28-pwm", "fsl,imx23-pwm"; reg = <0x80064000 0x2000>; - #pwm-cells = <2>; + #pwm-cells = <3>; fsl,pwm-number = <8>; }; diff --git a/Documentation/devicetree/bindings/regulator/mp8859.txt b/Documentation/devicetree/bindings/regulator/mp8859.txt new file mode 100644 index 000000000000..74ad69730989 --- /dev/null +++ b/Documentation/devicetree/bindings/regulator/mp8859.txt @@ -0,0 +1,22 @@ +Monolithic Power Systems MP8859 voltage regulator + +Required properties: +- compatible: "mps,mp8859"; +- reg: I2C slave address. + +Optional subnode for regulator: "mp8859_dcdc", using common regulator +bindings given in <Documentation/devicetree/bindings/regulator/regulator.txt>. + +Example: + + mp8859: regulator@66 { + compatible = "mps,mp8859"; + reg = <0x66>; + dc_12v: mp8859_dcdc { + regulator-name = "dc_12v"; + regulator-min-microvolt = <12000000>; + regulator-max-microvolt = <12000000>; + regulator-boot-on; + regulator-always-on; + }; + }; diff --git a/Documentation/devicetree/bindings/regulator/mps,mpq7920.yaml b/Documentation/devicetree/bindings/regulator/mps,mpq7920.yaml new file mode 100644 index 000000000000..a682af0dc67e --- /dev/null +++ b/Documentation/devicetree/bindings/regulator/mps,mpq7920.yaml @@ -0,0 +1,121 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/regulator/mps,mpq7920.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Monolithic Power System MPQ7920 PMIC + +maintainers: + - Saravanan Sekar <sravanhome@gmail.com> + +properties: + $nodename: + pattern: "pmic@[0-9a-f]{1,2}" + compatible: + enum: + - mps,mpq7920 + + reg: + maxItems: 1 + + regulators: + type: object + allOf: + - $ref: regulator.yaml# + description: | + list of regulators provided by this controller, must be named + after their hardware counterparts BUCK[1-4], one LDORTC, and LDO[2-5] + + properties: + mps,switch-freq: + allOf: + - $ref: "/schemas/types.yaml#/definitions/uint8" + enum: [ 0, 1, 2, 3 ] + default: 2 + description: | + switching frequency must be one of following corresponding value + 1.1MHz, 1.65MHz, 2.2MHz, 2.75MHz + + patternProperties: + "^ldo[1-4]$": + type: object + allOf: + - $ref: regulator.yaml# + + "^ldortc$": + type: object + allOf: + - $ref: regulator.yaml# + + "^buck[1-4]$": + type: object + allOf: + - $ref: regulator.yaml# + + properties: + mps,buck-softstart: + allOf: + - $ref: "/schemas/types.yaml#/definitions/uint8" + enum: [ 0, 1, 2, 3 ] + description: | + defines the soft start time of this buck, must be one of the following + corresponding values 150us, 300us, 610us, 920us + + mps,buck-phase-delay: + allOf: + - $ref: "/schemas/types.yaml#/definitions/uint8" + enum: [ 0, 1, 2, 3 ] + description: | + defines the phase delay of this buck, must be one of the following + corresponding values 0deg, 90deg, 180deg, 270deg + + mps,buck-ovp-disable: + type: boolean + description: | + disables over voltage protection of this buck + + additionalProperties: false + additionalProperties: false + +required: + - compatible + - reg + - regulators + +additionalProperties: false + +examples: + - | + i2c { + #address-cells = <1>; + #size-cells = <0>; + + pmic@69 { + compatible = "mps,mpq7920"; + reg = <0x69>; + + regulators { + mps,switch-freq = /bits/ 8 <1>; + + buck1 { + regulator-name = "buck1"; + regulator-min-microvolt = <400000>; + regulator-max-microvolt = <3587500>; + regulator-min-microamp = <460000>; + regulator-max-microamp = <7600000>; + regulator-boot-on; + mps,buck-ovp-disable; + mps,buck-phase-delay = /bits/ 8 <2>; + mps,buck-softstart = /bits/ 8 <1>; + }; + + ldo2 { + regulator-name = "ldo2"; + regulator-min-microvolt = <650000>; + regulator-max-microvolt = <3587500>; + }; + }; + }; + }; +... diff --git a/Documentation/devicetree/bindings/regulator/rohm,bd71828-regulator.yaml b/Documentation/devicetree/bindings/regulator/rohm,bd71828-regulator.yaml new file mode 100644 index 000000000000..71ce032b8cf8 --- /dev/null +++ b/Documentation/devicetree/bindings/regulator/rohm,bd71828-regulator.yaml @@ -0,0 +1,107 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/regulator/rohm,bd71828-regulator.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: ROHM BD71828 Power Management Integrated Circuit regulators + +maintainers: + - Matti Vaittinen <matti.vaittinen@fi.rohmeurope.com> + +description: | + This module is part of the ROHM BD71828 MFD device. For more details + see Documentation/devicetree/bindings/mfd/rohm,bd71828-pmic.yaml. + + The regulator controller is represented as a sub-node of the PMIC node + on the device tree. + + Regulator nodes should be named to BUCK_<number> and LDO_<number>. + The valid names for BD71828 regulator nodes are + BUCK1, BUCK2, BUCK3, BUCK4, BUCK5, BUCK6, BUCK7 + LDO1, LDO2, LDO3, LDO4, LDO5, LDO6, LDO7 + +patternProperties: + "^LDO[1-7]$": + type: object + allOf: + - $ref: regulator.yaml# + description: + Properties for single LDO regulator. + + properties: + regulator-name: + pattern: "^ldo[1-7]$" + description: + should be "ldo1", ..., "ldo7" + + "^BUCK[1-7]$": + type: object + allOf: + - $ref: regulator.yaml# + description: + Properties for single BUCK regulator. + + properties: + regulator-name: + pattern: "^buck[1-7]$" + description: + should be "buck1", ..., "buck7" + + rohm,dvs-run-voltage: + allOf: + - $ref: "/schemas/types.yaml#/definitions/uint32" + - minimum: 0 + maximum: 3300000 + description: + PMIC default "RUN" state voltage in uV. See below table for + bucks which support this. 0 means disabled. + + rohm,dvs-idle-voltage: + allOf: + - $ref: "/schemas/types.yaml#/definitions/uint32" + - minimum: 0 + maximum: 3300000 + description: + PMIC default "IDLE" state voltage in uV. See below table for + bucks which support this. 0 means disabled. + + rohm,dvs-suspend-voltage: + allOf: + - $ref: "/schemas/types.yaml#/definitions/uint32" + - minimum: 0 + maximum: 3300000 + description: + PMIC default "SUSPEND" state voltage in uV. See below table for + bucks which support this. 0 means disabled. + + rohm,dvs-lpsr-voltage: + allOf: + - $ref: "/schemas/types.yaml#/definitions/uint32" + - minimum: 0 + maximum: 3300000 + description: + PMIC default "LPSR" state voltage in uV. See below table for + bucks which support this. 0 means disabled. + + # Supported default DVS states: + # buck | run | idle | suspend | lpsr + #-------------------------------------------------------------- + # 1, 2, 6, and 7 | supported | supported | supported (*) + #-------------------------------------------------------------- + # 3, 4, and 5 | supported (**) + #-------------------------------------------------------------- + # + #(*) LPSR and SUSPEND states use same voltage but both states have own + # enable / + # disable settings. Voltage 0 can be specified for a state to make + # regulator disabled on that state. + # + #(**) All states use same voltage but have own enable / disable + # settings. Voltage 0 can be specified for a state to make + # regulator disabled on that state. + + required: + - regulator-name + additionalProperties: false +additionalProperties: false diff --git a/Documentation/devicetree/bindings/regulator/st,stm32-booster.txt b/Documentation/devicetree/bindings/regulator/st,stm32-booster.txt deleted file mode 100644 index 479ad4c8758e..000000000000 --- a/Documentation/devicetree/bindings/regulator/st,stm32-booster.txt +++ /dev/null @@ -1,18 +0,0 @@ -STM32 BOOSTER - Booster for ADC analog input switches - -Some STM32 devices embed a 3.3V booster supplied by Vdda, that can be used -to supply ADC analog input switches. - -Required properties: -- compatible: Should be one of: - "st,stm32h7-booster" - "st,stm32mp1-booster" -- st,syscfg: Phandle to system configuration controller. -- vdda-supply: Phandle to the vdda input analog voltage. - -Example: - booster: regulator-booster { - compatible = "st,stm32mp1-booster"; - st,syscfg = <&syscfg>; - vdda-supply = <&vdda>; - }; diff --git a/Documentation/devicetree/bindings/regulator/st,stm32-booster.yaml b/Documentation/devicetree/bindings/regulator/st,stm32-booster.yaml new file mode 100644 index 000000000000..64f1183ce841 --- /dev/null +++ b/Documentation/devicetree/bindings/regulator/st,stm32-booster.yaml @@ -0,0 +1,46 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/regulator/st,stm32-booster.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: STMicroelectronics STM32 booster for ADC analog input switches bindings + +maintainers: + - Fabrice Gasnier <fabrice.gasnier@st.com> + +description: | + Some STM32 devices embed a 3.3V booster supplied by Vdda, that can be used + to supply ADC analog input switches. + +allOf: + - $ref: "regulator.yaml#" + +properties: + compatible: + enum: + - st,stm32h7-booster + - st,stm32mp1-booster + + st,syscfg: + allOf: + - $ref: "/schemas/types.yaml#/definitions/phandle-array" + description: phandle to system configuration controller. + + vdda-supply: + description: phandle to the vdda input analog voltage. + +required: + - compatible + - st,syscfg + - vdda-supply + +examples: + - | + regulator-booster { + compatible = "st,stm32mp1-booster"; + st,syscfg = <&syscfg>; + vdda-supply = <&vdda>; + }; + +... diff --git a/Documentation/devicetree/bindings/regulator/st,stm32-vrefbuf.txt b/Documentation/devicetree/bindings/regulator/st,stm32-vrefbuf.txt deleted file mode 100644 index 5ddb8500a929..000000000000 --- a/Documentation/devicetree/bindings/regulator/st,stm32-vrefbuf.txt +++ /dev/null @@ -1,20 +0,0 @@ -STM32 VREFBUF - Voltage reference buffer - -Some STM32 devices embed a voltage reference buffer which can be used as -voltage reference for ADCs, DACs and also as voltage reference for external -components through the dedicated VREF+ pin. - -Required properties: -- compatible: Must be "st,stm32-vrefbuf". -- reg: Offset and length of VREFBUF register set. -- clocks: Must contain an entry for peripheral clock. - -Example: - vrefbuf: regulator@58003c00 { - compatible = "st,stm32-vrefbuf"; - reg = <0x58003C00 0x8>; - clocks = <&rcc VREF_CK>; - regulator-min-microvolt = <1500000>; - regulator-max-microvolt = <2500000>; - vdda-supply = <&vdda>; - }; diff --git a/Documentation/devicetree/bindings/regulator/st,stm32-vrefbuf.yaml b/Documentation/devicetree/bindings/regulator/st,stm32-vrefbuf.yaml new file mode 100644 index 000000000000..33cdaeb25aee --- /dev/null +++ b/Documentation/devicetree/bindings/regulator/st,stm32-vrefbuf.yaml @@ -0,0 +1,52 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/regulator/st,stm32-vrefbuf.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: STMicroelectronics STM32 Voltage reference buffer bindings + +description: | + Some STM32 devices embed a voltage reference buffer which can be used as + voltage reference for ADCs, DACs and also as voltage reference for external + components through the dedicated VREF+ pin. + +maintainers: + - Fabrice Gasnier <fabrice.gasnier@st.com> + +allOf: + - $ref: "regulator.yaml#" + +properties: + compatible: + const: st,stm32-vrefbuf + + reg: + maxItems: 1 + + clocks: + maxItems: 1 + + vdda-supply: + description: phandle to the vdda input analog voltage. + +required: + - compatible + - reg + - clocks + - vdda-supply + +examples: + - | + #include <dt-bindings/clock/stm32mp1-clks.h> + vrefbuf@50025000 { + compatible = "st,stm32-vrefbuf"; + reg = <0x50025000 0x8>; + regulator-min-microvolt = <1500000>; + regulator-max-microvolt = <2500000>; + clocks = <&rcc VREF>; + vdda-supply = <&vdda>; + }; + +... + diff --git a/Documentation/devicetree/bindings/regulator/st,stm32mp1-pwr-reg.txt b/Documentation/devicetree/bindings/regulator/st,stm32mp1-pwr-reg.txt deleted file mode 100644 index e372dd3f0c8a..000000000000 --- a/Documentation/devicetree/bindings/regulator/st,stm32mp1-pwr-reg.txt +++ /dev/null @@ -1,43 +0,0 @@ -STM32MP1 PWR Regulators ------------------------ - -Available Regulators in STM32MP1 PWR block are: - - reg11 for regulator 1V1 - - reg18 for regulator 1V8 - - usb33 for the swtich USB3V3 - -Required properties: -- compatible: Must be "st,stm32mp1,pwr-reg" -- list of child nodes that specify the regulator reg11, reg18 or usb33 - initialization data for defined regulators. The definition for each of - these nodes is defined using the standard binding for regulators found at - Documentation/devicetree/bindings/regulator/regulator.txt. -- vdd-supply: phandle to the parent supply/regulator node for vdd input -- vdd_3v3_usbfs-supply: phandle to the parent supply/regulator node for usb33 - -Example: - -pwr_regulators: pwr@50001000 { - compatible = "st,stm32mp1,pwr-reg"; - reg = <0x50001000 0x10>; - vdd-supply = <&vdd>; - vdd_3v3_usbfs-supply = <&vdd_usb>; - - reg11: reg11 { - regulator-name = "reg11"; - regulator-min-microvolt = <1100000>; - regulator-max-microvolt = <1100000>; - }; - - reg18: reg18 { - regulator-name = "reg18"; - regulator-min-microvolt = <1800000>; - regulator-max-microvolt = <1800000>; - }; - - usb33: usb33 { - regulator-name = "usb33"; - regulator-min-microvolt = <3300000>; - regulator-max-microvolt = <3300000>; - }; -}; diff --git a/Documentation/devicetree/bindings/regulator/st,stm32mp1-pwr-reg.yaml b/Documentation/devicetree/bindings/regulator/st,stm32mp1-pwr-reg.yaml new file mode 100644 index 000000000000..8d8f38fe85dc --- /dev/null +++ b/Documentation/devicetree/bindings/regulator/st,stm32mp1-pwr-reg.yaml @@ -0,0 +1,64 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/regulator/st,stm32mp1-pwr-reg.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: STM32MP1 PWR voltage regulators + +maintainers: + - Pascal Paillet <p.paillet@st.com> + +properties: + compatible: + const: st,stm32mp1,pwr-reg + + reg: + maxItems: 1 + + vdd-supply: + description: Input supply phandle(s) for vdd input + + vdd_3v3_usbfs-supply: + description: Input supply phandle(s) for vdd_3v3_usbfs input + +patternProperties: + "^(reg11|reg18|usb33)$": + type: object + + allOf: + - $ref: "regulator.yaml#" + +required: + - compatible + - reg + +additionalProperties: false + +examples: + - | + pwr@50001000 { + compatible = "st,stm32mp1,pwr-reg"; + reg = <0x50001000 0x10>; + vdd-supply = <&vdd>; + vdd_3v3_usbfs-supply = <&vdd_usb>; + + reg11 { + regulator-name = "reg11"; + regulator-min-microvolt = <1100000>; + regulator-max-microvolt = <1100000>; + }; + + reg18 { + regulator-name = "reg18"; + regulator-min-microvolt = <1800000>; + regulator-max-microvolt = <1800000>; + }; + + usb33 { + regulator-name = "usb33"; + regulator-min-microvolt = <3300000>; + regulator-max-microvolt = <3300000>; + }; + }; +... diff --git a/Documentation/devicetree/bindings/remoteproc/mtk,scp.txt b/Documentation/devicetree/bindings/remoteproc/mtk,scp.txt new file mode 100644 index 000000000000..3ba668bab14b --- /dev/null +++ b/Documentation/devicetree/bindings/remoteproc/mtk,scp.txt @@ -0,0 +1,36 @@ +Mediatek SCP Bindings +---------------------------------------- + +This binding provides support for ARM Cortex M4 Co-processor found on some +Mediatek SoCs. + +Required properties: +- compatible Should be "mediatek,mt8183-scp" +- reg Should contain the address ranges for the two memory + regions, SRAM and CFG. +- reg-names Contains the corresponding names for the two memory + regions. These should be named "sram" & "cfg". +- clocks Clock for co-processor (See: ../clock/clock-bindings.txt) +- clock-names Contains the corresponding name for the clock. This + should be named "main". + +Subnodes +-------- + +Subnodes of the SCP represent rpmsg devices. The names of the devices are not +important. The properties of these nodes are defined by the individual bindings +for the rpmsg devices - but must contain the following property: + +- mtk,rpmsg-name Contains the name for the rpmsg device. Used to match + the subnode to rpmsg device announced by SCP. + +Example: + + scp: scp@10500000 { + compatible = "mediatek,mt8183-scp"; + reg = <0 0x10500000 0 0x80000>, + <0 0x105c0000 0 0x5000>; + reg-names = "sram", "cfg"; + clocks = <&infracfg CLK_INFRA_SCPSYS>; + clock-names = "main"; + }; diff --git a/Documentation/devicetree/bindings/remoteproc/qcom,adsp.txt b/Documentation/devicetree/bindings/remoteproc/qcom,adsp.txt index 292dfda9770d..9938918b2fea 100644 --- a/Documentation/devicetree/bindings/remoteproc/qcom,adsp.txt +++ b/Documentation/devicetree/bindings/remoteproc/qcom,adsp.txt @@ -10,11 +10,17 @@ on the Qualcomm ADSP Hexagon core. "qcom,msm8974-adsp-pil" "qcom,msm8996-adsp-pil" "qcom,msm8996-slpi-pil" + "qcom,msm8998-adsp-pas" + "qcom,msm8998-slpi-pas" "qcom,qcs404-adsp-pas" "qcom,qcs404-cdsp-pas" "qcom,qcs404-wcss-pas" "qcom,sdm845-adsp-pas" "qcom,sdm845-cdsp-pas" + "qcom,sm8150-adsp-pas" + "qcom,sm8150-cdsp-pas" + "qcom,sm8150-mpss-pas" + "qcom,sm8150-slpi-pas" - interrupts-extended: Usage: required @@ -29,12 +35,18 @@ on the Qualcomm ADSP Hexagon core. qcom,msm8974-adsp-pil: qcom,msm8996-adsp-pil: qcom,msm8996-slpi-pil: + qcom,msm8998-adsp-pas: + qcom,msm8998-slpi-pas: qcom,qcs404-adsp-pas: qcom,qcs404-cdsp-pas: qcom,sdm845-adsp-pas: qcom,sdm845-cdsp-pas: + qcom,sm8150-adsp-pas: + qcom,sm8150-cdsp-pas: + qcom,sm8150-slpi-pas: must be "wdog", "fatal", "ready", "handover", "stop-ack" qcom,qcs404-wcss-pas: + qcom,sm8150-mpss-pas: must be "wdog", "fatal", "ready", "handover", "stop-ack", "shutdown-ack" @@ -67,6 +79,38 @@ on the Qualcomm ADSP Hexagon core. Definition: reference to the px regulator to be held on behalf of the booting Hexagon core +- power-domains: + Usage: required + Value type: <phandle> + Definition: reference to power-domains that match the power-domain-names + +- power-domain-names: + Usage: required + Value type: <stringlist> + Definition: The power-domains needed depend on the compatible string: + qcom,msm8974-adsp-pil: + qcom,msm8996-adsp-pil: + qcom,msm8998-adsp-pas: + must be "cx" + qcom,msm8996-slpi-pil: + must be "ss_cx" + qcom,msm8998-slpi-pas: + must be "ssc_cx" + qcom,qcs404-adsp-pas: + must be "lpi_cx" + qcom,qcs404-cdsp-pas: + qcom,qcs404-wcss-pas: + must be "mx" + qcom,sdm845-adsp-pas: + qcom,sdm845-cdsp-pas: + qcom,sm8150-adsp-pas: + qcom,sm8150-cdsp-pas: + must be "cx", "load_state" + qcom,sm8150-mpss-pas: + must be "cx", "load_state", "mss" + qcom,sm8150-slpi-pas: + must be "lcx", "lmx", "load_state" + - memory-region: Usage: required Value type: <phandle> diff --git a/Documentation/devicetree/bindings/remoteproc/qcom,q6v5.txt b/Documentation/devicetree/bindings/remoteproc/qcom,q6v5.txt index c416746f93cf..88dfa3fc15f7 100644 --- a/Documentation/devicetree/bindings/remoteproc/qcom,q6v5.txt +++ b/Documentation/devicetree/bindings/remoteproc/qcom,q6v5.txt @@ -13,6 +13,7 @@ on the Qualcomm Hexagon core. "qcom,msm8974-mss-pil" "qcom,msm8996-mss-pil" "qcom,msm8998-mss-pil" + "qcom,sc7180-mss-pil" "qcom,sdm845-mss-pil" - reg: @@ -43,6 +44,7 @@ on the Qualcomm Hexagon core. must be "wdog", "fatal", "ready", "handover", "stop-ack" qcom,msm8996-mss-pil: qcom,msm8998-mss-pil: + qcom,sc7180-mss-pil: qcom,sdm845-mss-pil: must be "wdog", "fatal", "ready", "handover", "stop-ack", "shutdown-ack" @@ -75,6 +77,9 @@ on the Qualcomm Hexagon core. qcom,msm8998-mss-pil: must be "iface", "bus", "mem", "xo", "gpll0_mss", "snoc_axi", "mnoc_axi", "qdss" + qcom,sc7180-mss-pil: + must be "iface", "bus", "xo", "snoc_axi", "mnoc_axi", + "mss_crypto", "mss_nav", "nav" qcom,sdm845-mss-pil: must be "iface", "bus", "mem", "xo", "gpll0_mss", "snoc_axi", "mnoc_axi", "prng" @@ -86,7 +91,7 @@ on the Qualcomm Hexagon core. reference to the list of 3 reset-controllers for the wcss sub-system reference to the list of 2 reset-controllers for the modem - sub-system on SDM845 SoCs + sub-system on SC7180, SDM845 SoCs - reset-names: Usage: required @@ -95,7 +100,7 @@ on the Qualcomm Hexagon core. must be "wcss_aon_reset", "wcss_reset", "wcss_q6_reset" for the wcss sub-system must be "mss_restart", "pdc_reset" for the modem - sub-system on SDM845 SoCs + sub-system on SC7180, SDM845 SoCs For the compatible strings below the following supplies are required: "qcom,q6v5-pil" @@ -144,6 +149,7 @@ For the compatible string below the following supplies are required: qcom,msm8996-mss-pil: qcom,msm8998-mss-pil: must be "cx", "mx" + qcom,sc7180-mss-pil: qcom,sdm845-mss-pil: must be "cx", "mx", "mss", "load_state" @@ -165,6 +171,19 @@ For the compatible string below the following supplies are required: by the three offsets within syscon for q6, modem and nc halt registers. +For the compatible strings below the following phandle references are required: + "qcom,sc7180-mss-pil" +- qcom,halt-nav-regs: + Usage: required + Value type: <prop-encoded-array> + Definition: reference to a list of 2 phandles with one offset each for + the modem sub-system running on SC7180 SoC. The first + phandle reference is to the mss clock node followed by the + offset within register space for nav halt register. The + second phandle reference is to a syscon representing TCSR + followed by the offset within syscon for conn_box_spare0 + register. + = SUBNODES: The Hexagon node must contain two subnodes, named "mba" and "mpss" representing the memory regions used by the Hexagon firmware. Each sub-node must contain: diff --git a/Documentation/devicetree/bindings/reset/allwinner,sun6i-a31-clock-reset.yaml b/Documentation/devicetree/bindings/reset/allwinner,sun6i-a31-clock-reset.yaml new file mode 100644 index 000000000000..001c0d2a8c1f --- /dev/null +++ b/Documentation/devicetree/bindings/reset/allwinner,sun6i-a31-clock-reset.yaml @@ -0,0 +1,68 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/reset/allwinner,sun6i-a31-clock-reset.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Allwinner A31 Peripheral Reset Controller Device Tree Bindings + +maintainers: + - Chen-Yu Tsai <wens@csie.org> + - Maxime Ripard <mripard@kernel.org> + +deprecated: true + +select: + properties: + compatible: + contains: + enum: + - allwinner,sun6i-a31-ahb1-reset + - allwinner,sun6i-a31-clock-reset + + # The PRCM on the A31 and A23 will have the reg property missing, + # since it's set at the upper level node, and will be validated by + # PRCM's schema. Make sure we only validate standalone nodes. + required: + - compatible + - reg + +properties: + "#reset-cells": + const: 1 + description: > + This additional argument passed to that reset controller is the + offset of the bit controlling this particular reset line in the + register. + + compatible: + enum: + - allwinner,sun6i-a31-ahb1-reset + - allwinner,sun6i-a31-clock-reset + + reg: + maxItems: 1 + +required: + - "#reset-cells" + - compatible + - reg + +additionalProperties: false + +examples: + - | + ahb1_rst: reset@1c202c0 { + #reset-cells = <1>; + compatible = "allwinner,sun6i-a31-ahb1-reset"; + reg = <0x01c202c0 0xc>; + }; + + - | + apbs_rst: reset@80014b0 { + #reset-cells = <1>; + compatible = "allwinner,sun6i-a31-clock-reset"; + reg = <0x080014b0 0x4>; + }; + +... diff --git a/Documentation/devicetree/bindings/reset/allwinner,sunxi-clock-reset.txt b/Documentation/devicetree/bindings/reset/allwinner,sunxi-clock-reset.txt deleted file mode 100644 index 4ca66c96fe97..000000000000 --- a/Documentation/devicetree/bindings/reset/allwinner,sunxi-clock-reset.txt +++ /dev/null @@ -1,21 +0,0 @@ -Allwinner sunxi Peripheral Reset Controller -=========================================== - -Please also refer to reset.txt in this directory for common reset -controller binding usage. - -Required properties: -- compatible: Should be one of the following: - "allwinner,sun6i-a31-ahb1-reset" - "allwinner,sun6i-a31-clock-reset" -- reg: should be register base and length as documented in the - datasheet -- #reset-cells: 1, see below - -example: - -ahb1_rst: reset@1c202c0 { - #reset-cells = <1>; - compatible = "allwinner,sun6i-a31-ahb1-reset"; - reg = <0x01c202c0 0xc>; -}; diff --git a/Documentation/devicetree/bindings/reset/brcm,bcm7216-pcie-sata-rescal.yaml b/Documentation/devicetree/bindings/reset/brcm,bcm7216-pcie-sata-rescal.yaml new file mode 100644 index 000000000000..411bd76f1b64 --- /dev/null +++ b/Documentation/devicetree/bindings/reset/brcm,bcm7216-pcie-sata-rescal.yaml @@ -0,0 +1,37 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +# Copyright 2020 Broadcom +%YAML 1.2 +--- +$id: "http://devicetree.org/schemas/reset/brcm,bcm7216-pcie-sata-rescal.yaml#" +$schema: "http://devicetree.org/meta-schemas/core.yaml#" + +title: BCM7216 RESCAL reset controller + +description: This document describes the BCM7216 RESCAL reset controller which is responsible for controlling the reset of the SATA and PCIe0/1 instances on BCM7216. + +maintainers: + - Florian Fainelli <f.fainelli@gmail.com> + - Jim Quinlan <jim2101024@gmail.com> + +properties: + compatible: + const: brcm,bcm7216-pcie-sata-rescal + + reg: + maxItems: 1 + + "#reset-cells": + const: 0 + +required: + - compatible + - reg + - "#reset-cells" + +examples: + - | + reset-controller@8b2c800 { + compatible = "brcm,bcm7216-pcie-sata-rescal"; + reg = <0x8b2c800 0x10>; + #reset-cells = <0>; + }; diff --git a/Documentation/devicetree/bindings/reset/intel,rcu-gw.yaml b/Documentation/devicetree/bindings/reset/intel,rcu-gw.yaml new file mode 100644 index 000000000000..246dea8a2ec9 --- /dev/null +++ b/Documentation/devicetree/bindings/reset/intel,rcu-gw.yaml @@ -0,0 +1,63 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/reset/intel,rcu-gw.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: System Reset Controller on Intel Gateway SoCs + +maintainers: + - Dilip Kota <eswara.kota@linux.intel.com> + +properties: + compatible: + enum: + - intel,rcu-lgm + - intel,rcu-xrx200 + + reg: + description: Reset controller registers. + maxItems: 1 + + intel,global-reset: + description: Global reset register offset and bit offset. + allOf: + - $ref: /schemas/types.yaml#/definitions/uint32-array + - maxItems: 2 + + "#reset-cells": + minimum: 2 + maximum: 3 + description: | + First cell is reset request register offset. + Second cell is bit offset in reset request register. + Third cell is bit offset in reset status register. + For LGM SoC, reset cell count is 2 as bit offset in + reset request and reset status registers is same. Whereas + 3 for legacy SoCs as bit offset differs. + +required: + - compatible + - reg + - intel,global-reset + - "#reset-cells" + +additionalProperties: false + +examples: + - | + rcu0: reset-controller@e0000000 { + compatible = "intel,rcu-lgm"; + reg = <0xe0000000 0x20000>; + intel,global-reset = <0x10 30>; + #reset-cells = <2>; + }; + + pwm: pwm@e0d00000 { + status = "disabled"; + compatible = "intel,lgm-pwm"; + reg = <0xe0d00000 0x30>; + clocks = <&cgu0 1>; + #pwm-cells = <2>; + resets = <&rcu0 0x30 21>; + }; diff --git a/Documentation/devicetree/bindings/reset/nuvoton,npcm-reset.txt b/Documentation/devicetree/bindings/reset/nuvoton,npcm-reset.txt new file mode 100644 index 000000000000..6e802703af60 --- /dev/null +++ b/Documentation/devicetree/bindings/reset/nuvoton,npcm-reset.txt @@ -0,0 +1,32 @@ +Nuvoton NPCM Reset controller + +Required properties: +- compatible : "nuvoton,npcm750-reset" for NPCM7XX BMC +- reg : specifies physical base address and size of the register. +- #reset-cells: must be set to 2 + +Optional property: +- nuvoton,sw-reset-number - Contains the software reset number to restart the SoC. + NPCM7xx contain four software reset that represent numbers 1 to 4. + + If 'nuvoton,sw-reset-number' is not specfied software reset is disabled. + +Example: + rstc: rstc@f0801000 { + compatible = "nuvoton,npcm750-reset"; + reg = <0xf0801000 0x70>; + #reset-cells = <2>; + nuvoton,sw-reset-number = <2>; + }; + +Specifying reset lines connected to IP NPCM7XX modules +====================================================== +example: + + spi0: spi@..... { + ... + resets = <&rstc NPCM7XX_RESET_IPSRST2 NPCM7XX_RESET_PSPI1>; + ... + }; + +The index could be found in <dt-bindings/reset/nuvoton,npcm7xx-reset.h>. diff --git a/Documentation/devicetree/bindings/rng/brcm,iproc-rng200.txt b/Documentation/devicetree/bindings/rng/brcm,iproc-rng200.txt index c223e54452da..802523196ee5 100644 --- a/Documentation/devicetree/bindings/rng/brcm,iproc-rng200.txt +++ b/Documentation/devicetree/bindings/rng/brcm,iproc-rng200.txt @@ -2,6 +2,7 @@ HWRNG support for the iproc-rng200 driver Required properties: - compatible : Must be one of: + "brcm,bcm2711-rng200" "brcm,bcm7211-rng200" "brcm,bcm7278-rng200" "brcm,iproc-rng200" diff --git a/Documentation/devicetree/bindings/rtc/atmel,at91rm9200-rtc.txt b/Documentation/devicetree/bindings/rtc/atmel,at91rm9200-rtc.txt deleted file mode 100644 index 5d3791e789c6..000000000000 --- a/Documentation/devicetree/bindings/rtc/atmel,at91rm9200-rtc.txt +++ /dev/null @@ -1,17 +0,0 @@ -Atmel AT91RM9200 Real Time Clock - -Required properties: -- compatible: should be: "atmel,at91rm9200-rtc" or "atmel,at91sam9x5-rtc" -- reg: physical base address of the controller and length of memory mapped - region. -- interrupts: rtc alarm/event interrupt -- clocks: phandle to input clock. - -Example: - -rtc@fffffe00 { - compatible = "atmel,at91rm9200-rtc"; - reg = <0xfffffe00 0x100>; - interrupts = <1 4 7>; - clocks = <&clk32k>; -}; diff --git a/Documentation/devicetree/bindings/rtc/atmel,at91rm9200-rtc.yaml b/Documentation/devicetree/bindings/rtc/atmel,at91rm9200-rtc.yaml new file mode 100644 index 000000000000..02bbfe726c62 --- /dev/null +++ b/Documentation/devicetree/bindings/rtc/atmel,at91rm9200-rtc.yaml @@ -0,0 +1,49 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/rtc/atmel,at91rm9200-rtc.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Atmel AT91 RTC Device Tree Bindings + +allOf: + - $ref: "rtc.yaml#" + +maintainers: + - Alexandre Belloni <alexandre.belloni@bootlin.com> + +properties: + compatible: + enum: + - atmel,at91rm9200-rtc + - atmel,at91sam9x5-rtc + - atmel,sama5d4-rtc + - atmel,sama5d2-rtc + - microchip,sam9x60-rtc + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + clocks: + maxItems: 1 + +required: + - compatible + - reg + - interrupts + - clocks + +additionalProperties: false + +examples: + - | + rtc@fffffe00 { + compatible = "atmel,at91rm9200-rtc"; + reg = <0xfffffe00 0x100>; + interrupts = <1 4 7>; + clocks = <&clk32k>; + }; +... diff --git a/Documentation/devicetree/bindings/rtc/st,stm32-rtc.txt b/Documentation/devicetree/bindings/rtc/st,stm32-rtc.txt deleted file mode 100644 index 130ca5b98253..000000000000 --- a/Documentation/devicetree/bindings/rtc/st,stm32-rtc.txt +++ /dev/null @@ -1,61 +0,0 @@ -STM32 Real Time Clock - -Required properties: -- compatible: can be one of the following: - - "st,stm32-rtc" for devices compatible with stm32(f4/f7). - - "st,stm32h7-rtc" for devices compatible with stm32h7. - - "st,stm32mp1-rtc" for devices compatible with stm32mp1. -- reg: address range of rtc register set. -- clocks: can use up to two clocks, depending on part used: - - "rtc_ck": RTC clock source. - - "pclk": RTC APB interface clock. - It is not present on stm32(f4/f7). - It is required on stm32(h7/mp1). -- clock-names: must be "rtc_ck" and "pclk". - It is required on stm32(h7/mp1). -- interrupts: rtc alarm interrupt. On stm32mp1, a second interrupt is required - for rtc alarm wakeup interrupt. -- st,syscfg: phandle/offset/mask triplet. The phandle to pwrcfg used to - access control register at offset, and change the dbp (Disable Backup - Protection) bit represented by the mask, mandatory to disable/enable backup - domain (RTC registers) write protection. - It is required on stm32(f4/f7/h7). - -Optional properties (to override default rtc_ck parent clock on stm32(f4/f7/h7): -- assigned-clocks: reference to the rtc_ck clock entry. -- assigned-clock-parents: phandle of the new parent clock of rtc_ck. - -Example: - - rtc: rtc@40002800 { - compatible = "st,stm32-rtc"; - reg = <0x40002800 0x400>; - clocks = <&rcc 1 CLK_RTC>; - assigned-clocks = <&rcc 1 CLK_RTC>; - assigned-clock-parents = <&rcc 1 CLK_LSE>; - interrupt-parent = <&exti>; - interrupts = <17 1>; - st,syscfg = <&pwrcfg 0x00 0x100>; - }; - - rtc: rtc@58004000 { - compatible = "st,stm32h7-rtc"; - reg = <0x58004000 0x400>; - clocks = <&rcc RTCAPB_CK>, <&rcc RTC_CK>; - clock-names = "pclk", "rtc_ck"; - assigned-clocks = <&rcc RTC_CK>; - assigned-clock-parents = <&rcc LSE_CK>; - interrupt-parent = <&exti>; - interrupts = <17 1>; - interrupt-names = "alarm"; - st,syscfg = <&pwrcfg 0x00 0x100>; - }; - - rtc: rtc@5c004000 { - compatible = "st,stm32mp1-rtc"; - reg = <0x5c004000 0x400>; - clocks = <&rcc RTCAPB>, <&rcc RTC>; - clock-names = "pclk", "rtc_ck"; - interrupts-extended = <&intc GIC_SPI 3 IRQ_TYPE_NONE>, - <&exti 19 1>; - }; diff --git a/Documentation/devicetree/bindings/rtc/st,stm32-rtc.yaml b/Documentation/devicetree/bindings/rtc/st,stm32-rtc.yaml new file mode 100644 index 000000000000..0a54296d7218 --- /dev/null +++ b/Documentation/devicetree/bindings/rtc/st,stm32-rtc.yaml @@ -0,0 +1,139 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/rtc/st,stm32-rtc.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: STMicroelectronics STM32 Real Time Clock Bindings + +maintainers: + - Gabriel Fernandez <gabriel.fernandez@st.com> + +properties: + compatible: + enum: + - st,stm32-rtc + - st,stm32h7-rtc + - st,stm32mp1-rtc + + reg: + maxItems: 1 + + clocks: + minItems: 1 + maxItems: 2 + + clock-names: + items: + - const: pclk + - const: rtc_ck + + interrupts: + maxItems: 1 + + st,syscfg: + allOf: + - $ref: "/schemas/types.yaml#/definitions/phandle-array" + - items: + minItems: 3 + maxItems: 3 + description: | + Phandle/offset/mask triplet. The phandle to pwrcfg used to + access control register at offset, and change the dbp (Disable Backup + Protection) bit represented by the mask, mandatory to disable/enable backup + domain (RTC registers) write protection. + + assigned-clocks: + description: | + override default rtc_ck parent clock reference to the rtc_ck clock entry + maxItems: 1 + + assigned-clock-parents: + description: | + override default rtc_ck parent clock phandle of the new parent clock of rtc_ck + maxItems: 1 + +allOf: + - if: + properties: + compatible: + contains: + const: st,stm32-rtc + + then: + properties: + clocks: + minItems: 1 + maxItems: 1 + + clock-names: false + + required: + - st,syscfg + + - if: + properties: + compatible: + contains: + const: st,stm32h7-rtc + + then: + properties: + clocks: + minItems: 2 + maxItems: 2 + + required: + - clock-names + - st,syscfg + + - if: + properties: + compatible: + contains: + const: st,stm32mp1-rtc + + then: + properties: + clocks: + minItems: 2 + maxItems: 2 + + assigned-clocks: false + assigned-clock-parents: false + + required: + - clock-names + +required: + - compatible + - reg + - clocks + - interrupts + +examples: + - | + #include <dt-bindings/mfd/stm32f4-rcc.h> + #include <dt-bindings/clock/stm32fx-clock.h> + rtc@40002800 { + compatible = "st,stm32-rtc"; + reg = <0x40002800 0x400>; + clocks = <&rcc 1 CLK_RTC>; + assigned-clocks = <&rcc 1 CLK_RTC>; + assigned-clock-parents = <&rcc 1 CLK_LSE>; + interrupt-parent = <&exti>; + interrupts = <17 1>; + st,syscfg = <&pwrcfg 0x00 0x100>; + }; + + #include <dt-bindings/interrupt-controller/arm-gic.h> + #include <dt-bindings/clock/stm32mp1-clks.h> + rtc@5c004000 { + compatible = "st,stm32mp1-rtc"; + reg = <0x5c004000 0x400>; + clocks = <&rcc RTCAPB>, <&rcc RTC>; + clock-names = "pclk", "rtc_ck"; + interrupts = <GIC_SPI 3 IRQ_TYPE_LEVEL_HIGH>; + }; + +... diff --git a/Documentation/devicetree/bindings/serial/fsl-lpuart.txt b/Documentation/devicetree/bindings/serial/fsl-lpuart.txt index f5f5ab0fd14e..c904e2e68332 100644 --- a/Documentation/devicetree/bindings/serial/fsl-lpuart.txt +++ b/Documentation/devicetree/bindings/serial/fsl-lpuart.txt @@ -10,6 +10,8 @@ Required properties: on i.MX7ULP SoC with 32-bit little-endian register organization - "fsl,imx8qxp-lpuart" for lpuart compatible with the one integrated on i.MX8QXP SoC with 32-bit little-endian register organization + - "fsl,imx8qm-lpuart" for lpuart compatible with the one integrated + on i.MX8QM SoC with 32-bit little-endian register organization - reg : Address and length of the register set for the device - interrupts : Should contain uart interrupt - clocks : phandle + clock specifier pairs, one for each entry in clock-names diff --git a/Documentation/devicetree/bindings/serial/rs485.txt b/Documentation/devicetree/bindings/serial/rs485.txt index b92592dff6dd..a7fe93efc4a5 100644 --- a/Documentation/devicetree/bindings/serial/rs485.txt +++ b/Documentation/devicetree/bindings/serial/rs485.txt @@ -1,31 +1 @@ -* RS485 serial communications - -The RTS signal is capable of automatically controlling line direction for -the built-in half-duplex mode. -The properties described hereafter shall be given to a half-duplex capable -UART node. - -Optional properties: -- rs485-rts-delay: prop-encoded-array <a b> where: - * a is the delay between rts signal and beginning of data sent in milliseconds. - it corresponds to the delay before sending data. - * b is the delay between end of data sent and rts signal in milliseconds - it corresponds to the delay after sending data and actual release of the line. - If this property is not specified, <0 0> is assumed. -- rs485-rts-active-low: drive RTS low when sending (default is high). -- linux,rs485-enabled-at-boot-time: empty property telling to enable the rs485 - feature at boot time. It can be disabled later with proper ioctl. -- rs485-rx-during-tx: empty property that enables the receiving of data even - while sending data. - -RS485 example for Atmel USART: - usart0: serial@fff8c000 { - compatible = "atmel,at91sam9260-usart"; - reg = <0xfff8c000 0x4000>; - interrupts = <7>; - atmel,use-dma-rx; - atmel,use-dma-tx; - linux,rs485-enabled-at-boot-time; - rs485-rts-delay = <0 200>; // in milliseconds - }; - +See rs485.yaml diff --git a/Documentation/devicetree/bindings/serial/rs485.yaml b/Documentation/devicetree/bindings/serial/rs485.yaml new file mode 100644 index 000000000000..d4beaf11222d --- /dev/null +++ b/Documentation/devicetree/bindings/serial/rs485.yaml @@ -0,0 +1,45 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/serial/rs485.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: RS485 serial communications Bindings + +description: The RTS signal is capable of automatically controlling + line direction for the built-in half-duplex mode. + The properties described hereafter shall be given to a + half-duplex capable UART node. + +maintainers: + - Rob Herring <robh@kernel.org> + +properties: + rs485-rts-delay: + description: prop-encoded-array <a b> + allOf: + - $ref: /schemas/types.yaml#/definitions/uint32-array + - items: + items: + - description: + Delay between rts signal and beginning of data sent in milliseconds. + It corresponds to the delay before sending data. + default: 0 + maximum: 1000 + - description: + Delay between end of data sent and rts signal in milliseconds. + It corresponds to the delay after sending data and actual release of the line. + default: 0 + maximum: 1000 + + rs485-rts-active-low: + description: drive RTS low when sending (default is high). + $ref: /schemas/types.yaml#/definitions/flag + + linux,rs485-enabled-at-boot-time: + description: enables the rs485 feature at boot time. It can be disabled later with proper ioctl. + $ref: /schemas/types.yaml#/definitions/flag + + rs485-rx-during-tx: + description: enables the receiving of data even while sending data. + $ref: /schemas/types.yaml#/definitions/flag diff --git a/Documentation/devicetree/bindings/serial/st,stm32-uart.yaml b/Documentation/devicetree/bindings/serial/st,stm32-uart.yaml new file mode 100644 index 000000000000..238c44192d31 --- /dev/null +++ b/Documentation/devicetree/bindings/serial/st,stm32-uart.yaml @@ -0,0 +1,80 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/serial/st,stm32-uart.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +maintainers: + - Erwan Le Ray <erwan.leray@st.com> + +title: STMicroelectronics STM32 USART bindings + +allOf: + - $ref: rs485.yaml + +properties: + compatible: + enum: + - st,stm32-uart + - st,stm32f7-uart + - st,stm32h7-uart + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + clocks: + maxItems: 1 + + resets: + maxItems: 1 + + label: + description: label associated with this uart + + st,hw-flow-ctrl: + description: enable hardware flow control + $ref: /schemas/types.yaml#/definitions/flag + + dmas: + minItems: 1 + maxItems: 2 + + dma-names: + items: + enum: [ rx, tx ] + minItems: 1 + maxItems: 2 + + wakeup-source: true + + rs485-rts-delay: true + rs485-rts-active-low: true + linux,rs485-enabled-at-boot-time: true + rs485-rx-during-tx: true + +required: + - compatible + - reg + - interrupts + - clocks + +additionalProperties: false + +examples: + - | + #include <dt-bindings/clock/stm32mp1-clks.h> + usart1: serial@40011000 { + compatible = "st,stm32-uart"; + reg = <0x40011000 0x400>; + interrupts = <37>; + clocks = <&rcc 0 164>; + dmas = <&dma2 2 4 0x414 0x0>, + <&dma2 7 4 0x414 0x0>; + dma-names = "rx", "tx"; + rs485-rts-active-low; + }; + +... diff --git a/Documentation/devicetree/bindings/serial/st,stm32-usart.txt b/Documentation/devicetree/bindings/serial/st,stm32-usart.txt deleted file mode 100644 index 8620f7fcbd50..000000000000 --- a/Documentation/devicetree/bindings/serial/st,stm32-usart.txt +++ /dev/null @@ -1,57 +0,0 @@ -* STMicroelectronics STM32 USART - -Required properties: -- compatible: can be either: - - "st,stm32-uart", - - "st,stm32f7-uart", - - "st,stm32h7-uart". - depending is compatible with stm32(f4), stm32f7 or stm32h7. -- reg: The address and length of the peripheral registers space -- interrupts: - - The interrupt line for the USART instance, - - An optional wake-up interrupt. -- clocks: The input clock of the USART instance - -Optional properties: -- resets: Must contain the phandle to the reset controller. -- pinctrl: The reference on the pins configuration -- st,hw-flow-ctrl: bool flag to enable hardware flow control. -- rs485-rts-delay, rs485-rx-during-tx, rs485-rts-active-low, - linux,rs485-enabled-at-boot-time: see rs485.txt. -- dmas: phandle(s) to DMA controller node(s). Refer to stm32-dma.txt -- dma-names: "rx" and/or "tx" -- wakeup-source: bool flag to indicate this device has wakeup capabilities -- interrupt-names, if optional wake-up interrupt is used, should be: - - "event": the name for the interrupt line of the USART instance - - "wakeup" the name for the optional wake-up interrupt - - -Examples: -usart4: serial@40004c00 { - compatible = "st,stm32-uart"; - reg = <0x40004c00 0x400>; - interrupts = <52>; - clocks = <&clk_pclk1>; - pinctrl-names = "default"; - pinctrl-0 = <&pinctrl_usart4>; -}; - -usart2: serial@40004400 { - compatible = "st,stm32-uart"; - reg = <0x40004400 0x400>; - interrupts = <38>; - clocks = <&clk_pclk1>; - st,hw-flow-ctrl; - pinctrl-names = "default"; - pinctrl-0 = <&pinctrl_usart2 &pinctrl_usart2_rtscts>; -}; - -usart1: serial@40011000 { - compatible = "st,stm32-uart"; - reg = <0x40011000 0x400>; - interrupts = <37>; - clocks = <&rcc 0 164>; - dmas = <&dma2 2 4 0x414 0x0>, - <&dma2 7 4 0x414 0x0>; - dma-names = "rx", "tx"; -}; diff --git a/Documentation/devicetree/bindings/slimbus/bus.txt b/Documentation/devicetree/bindings/slimbus/bus.txt index 52fa6426388c..bbe871f82a8b 100644 --- a/Documentation/devicetree/bindings/slimbus/bus.txt +++ b/Documentation/devicetree/bindings/slimbus/bus.txt @@ -32,6 +32,10 @@ Required property for SLIMbus child node if it is present: Product Code, shall be in lower case hexadecimal with leading zeroes suppressed +Optional property for SLIMbus child node if it is present: +- slim-ifc-dev - Should be phandle to SLIMBus Interface device. + Required for devices which deal with streams. + SLIMbus example for Qualcomm's slimbus manager component: slim@28080000 { @@ -43,8 +47,14 @@ SLIMbus example for Qualcomm's slimbus manager component: #address-cells = <2>; #size-cell = <0>; + codec_ifd: ifd@0,0{ + compatible = "slim217,60"; + reg = <0 0>; + }; + codec: wcd9310@1,0{ compatible = "slim217,60"; reg = <1 0>; + slim-ifc-dev = <&codec_ifd>; }; }; diff --git a/Documentation/devicetree/bindings/soc/mediatek/scpsys.txt b/Documentation/devicetree/bindings/soc/mediatek/scpsys.txt index 8f469d85833b..2bc367793aec 100644 --- a/Documentation/devicetree/bindings/soc/mediatek/scpsys.txt +++ b/Documentation/devicetree/bindings/soc/mediatek/scpsys.txt @@ -11,6 +11,7 @@ The driver implements the Generic PM domain bindings described in power/power-domain.yaml. It provides the power domains defined in - include/dt-bindings/power/mt8173-power.h - include/dt-bindings/power/mt6797-power.h +- include/dt-bindings/power/mt6765-power.h - include/dt-bindings/power/mt2701-power.h - include/dt-bindings/power/mt2712-power.h - include/dt-bindings/power/mt7622-power.h @@ -19,6 +20,7 @@ Required properties: - compatible: Should be one of: - "mediatek,mt2701-scpsys" - "mediatek,mt2712-scpsys" + - "mediatek,mt6765-scpsys" - "mediatek,mt6797-scpsys" - "mediatek,mt7622-scpsys" - "mediatek,mt7623-scpsys", "mediatek,mt2701-scpsys": For MT7623 SoC @@ -33,6 +35,10 @@ Required properties: enabled before enabling certain power domains. Required clocks for MT2701 or MT7623: "mm", "mfg", "ethif" Required clocks for MT2712: "mm", "mfg", "venc", "jpgdec", "audio", "vdec" + Required clocks for MT6765: MUX: "mm", "mfg" + CG: "mm-0", "mm-1", "mm-2", "mm-3", "isp-0", + "isp-1", "cam-0", "cam-1", "cam-2", + "cam-3","cam-4" Required clocks for MT6797: "mm", "mfg", "vdec" Required clocks for MT7622 or MT7629: "hif_sel" Required clocks for MT7623A: "ethif" diff --git a/Documentation/devicetree/bindings/soc/ti/k3-ringacc.txt b/Documentation/devicetree/bindings/soc/ti/k3-ringacc.txt new file mode 100644 index 000000000000..59758ccce809 --- /dev/null +++ b/Documentation/devicetree/bindings/soc/ti/k3-ringacc.txt @@ -0,0 +1,59 @@ +* Texas Instruments K3 NavigatorSS Ring Accelerator + +The Ring Accelerator (RA) is a machine which converts read/write accesses +from/to a constant address into corresponding read/write accesses from/to a +circular data structure in memory. The RA eliminates the need for each DMA +controller which needs to access ring elements from having to know the current +state of the ring (base address, current offset). The DMA controller +performs a read or write access to a specific address range (which maps to the +source interface on the RA) and the RA replaces the address for the transaction +with a new address which corresponds to the head or tail element of the ring +(head for reads, tail for writes). + +The Ring Accelerator is a hardware module that is responsible for accelerating +management of the packet queues. The K3 SoCs can have more than one RA instances + +Required properties: +- compatible : Must be "ti,am654-navss-ringacc"; +- reg : Should contain register location and length of the following + named register regions. +- reg-names : should be + "rt" - The RA Ring Real-time Control/Status Registers + "fifos" - The RA Queues Registers + "proxy_gcfg" - The RA Proxy Global Config Registers + "proxy_target" - The RA Proxy Datapath Registers +- ti,num-rings : Number of rings supported by RA +- ti,sci-rm-range-gp-rings : TI-SCI RM subtype for GP ring range +- ti,sci : phandle on TI-SCI compatible System controller node +- ti,sci-dev-id : TI-SCI device id of the ring accelerator +- msi-parent : phandle for "ti,sci-inta" interrupt controller + +Optional properties: + -- ti,dma-ring-reset-quirk : enable ringacc / udma ring state interoperability + issue software w/a + +Example: + +ringacc: ringacc@3c000000 { + compatible = "ti,am654-navss-ringacc"; + reg = <0x0 0x3c000000 0x0 0x400000>, + <0x0 0x38000000 0x0 0x400000>, + <0x0 0x31120000 0x0 0x100>, + <0x0 0x33000000 0x0 0x40000>; + reg-names = "rt", "fifos", + "proxy_gcfg", "proxy_target"; + ti,num-rings = <818>; + ti,sci-rm-range-gp-rings = <0x2>; /* GP ring range */ + ti,dma-ring-reset-quirk; + ti,sci = <&dmsc>; + ti,sci-dev-id = <187>; + msi-parent = <&inta_main_udmass>; +}; + +client: + +dma_ipx: dma_ipx@<addr> { + ... + ti,ringacc = <&ringacc>; + ... +} diff --git a/Documentation/devicetree/bindings/sound/amlogic,axg-fifo.txt b/Documentation/devicetree/bindings/sound/amlogic,axg-fifo.txt index 3080979350a0..fa4545ed81ca 100644 --- a/Documentation/devicetree/bindings/sound/amlogic,axg-fifo.txt +++ b/Documentation/devicetree/bindings/sound/amlogic,axg-fifo.txt @@ -17,6 +17,9 @@ Required properties: * "arb" : memory ARB line (required) * "rst" : dedicated device reset line (optional) - #sound-dai-cells: must be 0. +- amlogic,fifo-depth: The size of the controller's fifo in bytes. This + is useful for determining certain configuration such + as the flush threshold of the fifo Example of FRDDR A on the A113 SoC: @@ -27,4 +30,5 @@ frddr_a: audio-controller@1c0 { interrupts = <GIC_SPI 88 IRQ_TYPE_EDGE_RISING>; clocks = <&clkc_audio AUD_CLKID_FRDDR_A>; resets = <&arb AXG_ARB_FRDDR_A>; + fifo-depth = <512>; }; diff --git a/Documentation/devicetree/bindings/sound/fsl,asrc.txt b/Documentation/devicetree/bindings/sound/fsl,asrc.txt index 1d4d9f938689..cb9a25165503 100644 --- a/Documentation/devicetree/bindings/sound/fsl,asrc.txt +++ b/Documentation/devicetree/bindings/sound/fsl,asrc.txt @@ -8,7 +8,12 @@ three substreams within totally 10 channels. Required properties: - - compatible : Contains "fsl,imx35-asrc" or "fsl,imx53-asrc". + - compatible : Compatible list, should contain one of the following + compatibles: + "fsl,imx35-asrc", + "fsl,imx53-asrc", + "fsl,imx8qm-asrc", + "fsl,imx8qxp-asrc", - reg : Offset and length of the register set for the device. @@ -35,6 +40,11 @@ Required properties: - fsl,asrc-width : Defines a mutual sample width used by DPCM Back Ends. + - fsl,asrc-clk-map : Defines clock map used in driver. which is required + by imx8qm/imx8qxp platform + <0> - select the map for asrc0 in imx8qm/imx8qxp + <1> - select the map for asrc1 in imx8qm/imx8qxp + Optional properties: - big-endian : If this property is absent, the little endian mode diff --git a/Documentation/devicetree/bindings/sound/gtm601.txt b/Documentation/devicetree/bindings/sound/gtm601.txt index 5efc8c068de0..efa32a486c4a 100644 --- a/Documentation/devicetree/bindings/sound/gtm601.txt +++ b/Documentation/devicetree/bindings/sound/gtm601.txt @@ -1,10 +1,16 @@ GTM601 UMTS modem audio interface CODEC -This device has no configuration interface. Sample rate is fixed - 8kHz. +This device has no configuration interface. The sample rate and channels are +based on the compatible string + "option,gtm601" = 8kHz mono + "broadmobi,bm818" = 48KHz stereo Required properties: - - compatible : "option,gtm601" + - compatible : one of + "option,gtm601" + "broadmobi,bm818" + Example: diff --git a/Documentation/devicetree/bindings/sound/ingenic,codec.yaml b/Documentation/devicetree/bindings/sound/ingenic,codec.yaml new file mode 100644 index 000000000000..eb4be86464bb --- /dev/null +++ b/Documentation/devicetree/bindings/sound/ingenic,codec.yaml @@ -0,0 +1,55 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/sound/ingenic,codec.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Ingenic JZ47xx internal codec DT bindings + +maintainers: + - Paul Cercueil <paul@crapouillou.net> + +properties: + $nodename: + pattern: '^audio-codec@.*' + + compatible: + oneOf: + - const: ingenic,jz4770-codec + - const: ingenic,jz4725b-codec + - const: ingenic,jz4740-codec + + reg: + maxItems: 1 + + clocks: + maxItems: 1 + + clock-names: + items: + - const: aic + + '#sound-dai-cells': + const: 0 + +additionalProperties: false + +required: + - compatible + - reg + - clocks + - clock-names + - '#sound-dai-cells' + +examples: + - | + #include <dt-bindings/clock/jz4740-cgu.h> + codec: audio-codec@10020080 { + compatible = "ingenic,jz4740-codec"; + reg = <0x10020080 0x8>; + #sound-dai-cells = <0>; + clocks = <&cgu JZ4740_CLK_AIC>; + clock-names = "aic"; + }; + +... diff --git a/Documentation/devicetree/bindings/sound/ingenic,jz4725b-codec.txt b/Documentation/devicetree/bindings/sound/ingenic,jz4725b-codec.txt deleted file mode 100644 index 05adc0d47b13..000000000000 --- a/Documentation/devicetree/bindings/sound/ingenic,jz4725b-codec.txt +++ /dev/null @@ -1,20 +0,0 @@ -Ingenic JZ4725B codec controller - -Required properties: -- compatible : "ingenic,jz4725b-codec" -- reg : codec registers location and length -- clocks : phandle to the AIC clock. -- clock-names: must be set to "aic". -- #sound-dai-cells: Must be set to 0. - -Example: - -codec: audio-codec@100200a4 { - compatible = "ingenic,jz4725b-codec"; - reg = <0x100200a4 0x8>; - - #sound-dai-cells = <0>; - - clocks = <&cgu JZ4725B_CLK_AIC>; - clock-names = "aic"; -}; diff --git a/Documentation/devicetree/bindings/sound/ingenic,jz4740-codec.txt b/Documentation/devicetree/bindings/sound/ingenic,jz4740-codec.txt deleted file mode 100644 index 1ffcade87e7b..000000000000 --- a/Documentation/devicetree/bindings/sound/ingenic,jz4740-codec.txt +++ /dev/null @@ -1,20 +0,0 @@ -Ingenic JZ4740 codec controller - -Required properties: -- compatible : "ingenic,jz4740-codec" -- reg : codec registers location and length -- clocks : phandle to the AIC clock. -- clock-names: must be set to "aic". -- #sound-dai-cells: Must be set to 0. - -Example: - -codec: audio-codec@10020080 { - compatible = "ingenic,jz4740-codec"; - reg = <0x10020080 0x8>; - - #sound-dai-cells = <0>; - - clocks = <&cgu JZ4740_CLK_AIC>; - clock-names = "aic"; -}; diff --git a/Documentation/devicetree/bindings/sound/qcom,sdm845.txt b/Documentation/devicetree/bindings/sound/qcom,sdm845.txt index 408c4837e6d5..ca8c89e88bfa 100644 --- a/Documentation/devicetree/bindings/sound/qcom,sdm845.txt +++ b/Documentation/devicetree/bindings/sound/qcom,sdm845.txt @@ -5,7 +5,10 @@ This binding describes the SDM845 sound card, which uses qdsp for audio. - compatible: Usage: required Value type: <stringlist> - Definition: must be "qcom,sdm845-sndcard" + Definition: must be one of this + "qcom,sdm845-sndcard" + "qcom,db845c-sndcard" + "lenovo,yoga-c630-sndcard" - audio-routing: Usage: Optional diff --git a/Documentation/devicetree/bindings/sound/qcom,wcd934x.yaml b/Documentation/devicetree/bindings/sound/qcom,wcd934x.yaml new file mode 100644 index 000000000000..38eaf0c028f9 --- /dev/null +++ b/Documentation/devicetree/bindings/sound/qcom,wcd934x.yaml @@ -0,0 +1,175 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/sound/qcom,wcd934x.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Bindings for Qualcomm WCD9340/WCD9341 Audio Codec + +maintainers: + - Srinivas Kandagatla <srinivas.kandagatla@linaro.org> + +description: | + Qualcomm WCD9340/WCD9341 Codec is a standalone Hi-Fi audio codec IC. + It has in-built Soundwire controller, pin controller, interrupt mux and + supports both I2S/I2C and SLIMbus audio interfaces. + +properties: + compatible: + const: slim217,250 + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + reset-gpios: + description: GPIO spec for reset line to use + maxItems: 1 + + slim-ifc-dev: true + + clocks: + maxItems: 1 + + clock-names: + const: extclk + + vdd-buck-supply: + description: A reference to the 1.8V buck supply + + vdd-buck-sido-supply: + description: A reference to the 1.8V SIDO buck supply + + vdd-rx-supply: + description: A reference to the 1.8V rx supply + + vdd-tx-supply: + description: A reference to the 1.8V tx supply + + vdd-vbat-supply: + description: A reference to the vbat supply + + vdd-io-supply: + description: A reference to the 1.8V I/O supply + + vdd-micbias-supply: + description: A reference to the micbias supply + + qcom,micbias1-microvolt: + description: micbias1 voltage + minimum: 1800000 + maximum: 2850000 + + qcom,micbias2-microvolt: + description: micbias2 voltage + minimum: 1800000 + maximum: 2850000 + + qcom,micbias3-microvolt: + description: micbias3 voltage + minimum: 1800000 + maximum: 2850000 + + qcom,micbias4-microvolt: + description: micbias4 voltage + minimum: 1800000 + maximum: 2850000 + + clock-output-names: + const: mclk + + clock-frequency: + description: Clock frequency of output clk in Hz + + interrupt-controller: true + + '#interrupt-cells': + const: 1 + + '#clock-cells': + const: 0 + + '#sound-dai-cells': + const: 1 + + "#address-cells": + const: 1 + + "#size-cells": + const: 1 + + gpio@42: + type: object + allOf: + - $ref: ../gpio/qcom,wcd934x-gpio.yaml# + +patternProperties: + "^.*@[0-9a-f]+$": + type: object + description: | + WCD934x subnode for each slave devices. Bindings of each subnodes + depends on the specific driver providing the functionality and + documented in their respective bindings. + + properties: + reg: + maxItems: 1 + + required: + - reg + +required: + - compatible + - reg + - reset-gpios + - slim-ifc-dev + - interrupts + - interrupt-controller + - clock-frequency + - clock-output-names + - qcom,micbias1-microvolt + - qcom,micbias2-microvolt + - qcom,micbias3-microvolt + - qcom,micbias4-microvolt + - "#interrupt-cells" + - "#clock-cells" + - "#sound-dai-cells" + - "#address-cells" + - "#size-cells" + +examples: + - | + codec@1,0{ + compatible = "slim217,250"; + reg = <1 0>; + reset-gpios = <&tlmm 64 0>; + slim-ifc-dev = <&wcd9340_ifd>; + #sound-dai-cells = <1>; + interrupt-parent = <&tlmm>; + interrupts = <54 4>; + interrupt-controller; + #interrupt-cells = <1>; + #clock-cells = <0>; + clock-frequency = <9600000>; + clock-output-names = "mclk"; + qcom,micbias1-microvolt = <1800000>; + qcom,micbias2-microvolt = <1800000>; + qcom,micbias3-microvolt = <1800000>; + qcom,micbias4-microvolt = <1800000>; + clock-names = "extclk"; + clocks = <&rpmhcc 2>; + + #address-cells = <1>; + #size-cells = <1>; + + gpio@42 { + compatible = "qcom,wcd9340-gpio"; + reg = <0x42 0x2>; + gpio-controller; + #gpio-cells = <2>; + }; + }; + +... diff --git a/Documentation/devicetree/bindings/sound/qcom,wsa881x.yaml b/Documentation/devicetree/bindings/sound/qcom,wsa881x.yaml new file mode 100644 index 000000000000..ea44d03e58ca --- /dev/null +++ b/Documentation/devicetree/bindings/sound/qcom,wsa881x.yaml @@ -0,0 +1,68 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/sound/qcom,wsa881x.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Bindings for Qualcomm WSA8810/WSA8815 Class-D Smart Speaker Amplifier + +maintainers: + - Srinivas Kandagatla <srinivas.kandagatla@linaro.org> + +description: | + WSA8810 is a class-D smart speaker amplifier and WSA8815 + is a high-output power class-D smart speaker amplifier. + Their primary operating mode uses a SoundWire digital audio + interface. This binding is for SoundWire interface. + +properties: + compatible: + const: sdw10217201000 + + reg: + maxItems: 1 + + powerdown-gpios: + description: GPIO spec for Powerdown/Shutdown line to use + maxItems: 1 + + '#thermal-sensor-cells': + const: 0 + + '#sound-dai-cells': + const: 0 + +required: + - compatible + - reg + - powerdown-gpios + - "#thermal-sensor-cells" + - "#sound-dai-cells" + +additionalProperties: false + +examples: + - | + soundwire@c2d0000 { + #address-cells = <2>; + #size-cells = <0>; + reg = <0x0c2d0000 0x2000>; + + speaker@0,1 { + compatible = "sdw10217201000"; + reg = <0 1>; + powerdown-gpios = <&wcdpinctrl 2 0>; + #thermal-sensor-cells = <0>; + #sound-dai-cells = <0>; + }; + + speaker@0,2 { + compatible = "sdw10217201000"; + reg = <0 2>; + powerdown-gpios = <&wcdpinctrl 2 0>; + #thermal-sensor-cells = <0>; + #sound-dai-cells = <0>; + }; + }; + +... diff --git a/Documentation/devicetree/bindings/sound/rt1015.txt b/Documentation/devicetree/bindings/sound/rt1015.txt new file mode 100644 index 000000000000..fcfd02d8d32f --- /dev/null +++ b/Documentation/devicetree/bindings/sound/rt1015.txt @@ -0,0 +1,17 @@ +RT1015 Mono Class D Audio Amplifier + +This device supports I2C only. + +Required properties: + +- compatible : "realtek,rt1015". + +- reg : The I2C address of the device. + + +Example: + +rt1015: codec@28 { + compatible = "realtek,rt1015"; + reg = <0x28>; +}; diff --git a/Documentation/devicetree/bindings/sound/rt5645.txt b/Documentation/devicetree/bindings/sound/rt5645.txt index a03f9a872a71..41a62fd2ae1f 100644 --- a/Documentation/devicetree/bindings/sound/rt5645.txt +++ b/Documentation/devicetree/bindings/sound/rt5645.txt @@ -10,6 +10,10 @@ Required properties: - interrupts : The CODEC's interrupt output. +- avdd-supply: Power supply for AVDD, providing 1.8V. + +- cpvdd-supply: Power supply for CPVDD, providing 3.5V. + Optional properties: - hp-detect-gpios: diff --git a/Documentation/devicetree/bindings/soundwire/qcom,sdw.txt b/Documentation/devicetree/bindings/soundwire/qcom,sdw.txt new file mode 100644 index 000000000000..436547f3b155 --- /dev/null +++ b/Documentation/devicetree/bindings/soundwire/qcom,sdw.txt @@ -0,0 +1,167 @@ +Qualcomm SoundWire Controller Bindings + + +This binding describes the Qualcomm SoundWire Controller along with its +board specific bus parameters. + +- compatible: + Usage: required + Value type: <stringlist> + Definition: must be "qcom,soundwire-v<MAJOR>.<MINOR>.<STEP>", + Example: + "qcom,soundwire-v1.3.0" + "qcom,soundwire-v1.5.0" + "qcom,soundwire-v1.6.0" +- reg: + Usage: required + Value type: <prop-encoded-array> + Definition: the base address and size of SoundWire controller + address space. + +- interrupts: + Usage: required + Value type: <prop-encoded-array> + Definition: should specify the SoundWire Controller IRQ + +- clock-names: + Usage: required + Value type: <stringlist> + Definition: should be "iface" for SoundWire Controller interface clock + +- clocks: + Usage: required + Value type: <prop-encoded-array> + Definition: should specify the SoundWire Controller interface clock + +- #sound-dai-cells: + Usage: required + Value type: <u32> + Definition: must be 1 for digital audio interfaces on the controller. + +- qcom,dout-ports: + Usage: required + Value type: <u32> + Definition: must be count of data out ports + +- qcom,din-ports: + Usage: required + Value type: <u32> + Definition: must be count of data in ports + +- qcom,ports-offset1: + Usage: required + Value type: <prop-encoded-array> + Definition: should specify payload transport window offset1 of each + data port. Out ports followed by In ports. + More info in MIPI Alliance SoundWire 1.0 Specifications. + +- qcom,ports-offset2: + Usage: required + Value type: <prop-encoded-array> + Definition: should specify payload transport window offset2 of each + data port. Out ports followed by In ports. + More info in MIPI Alliance SoundWire 1.0 Specifications. + +- qcom,ports-sinterval-low: + Usage: required + Value type: <prop-encoded-array> + Definition: should be sample interval low of each data port. + Out ports followed by In ports. Used for Sample Interval + calculation. + More info in MIPI Alliance SoundWire 1.0 Specifications. + +- qcom,ports-word-length: + Usage: optional + Value type: <prop-encoded-array> + Definition: should be size of payload channel sample. + More info in MIPI Alliance SoundWire 1.0 Specifications. + +- qcom,ports-block-pack-mode: + Usage: optional + Value type: <prop-encoded-array> + Definition: should be 0 or 1 to indicate the block packing mode. + 0 to indicate Blocks are per Channel + 1 to indicate Blocks are per Port. + Out ports followed by In ports. + More info in MIPI Alliance SoundWire 1.0 Specifications. + +- qcom,ports-block-group-count: + Usage: optional + Value type: <prop-encoded-array> + Definition: should be in range 1 to 4 to indicate how many sample + intervals are combined into a payload. + Out ports followed by In ports. + More info in MIPI Alliance SoundWire 1.0 Specifications. + +- qcom,ports-lane-control: + Usage: optional + Value type: <prop-encoded-array> + Definition: should be in range 0 to 7 to identify which data lane + the data port uses. + Out ports followed by In ports. + More info in MIPI Alliance SoundWire 1.0 Specifications. + +- qcom,ports-hstart: + Usage: optional + Value type: <prop-encoded-array> + Definition: should be number identifying lowerst numbered coloum in + SoundWire Frame, i.e. left edge of the Transport sub-frame + for each port. Values between 0 and 15 are valid. + Out ports followed by In ports. + More info in MIPI Alliance SoundWire 1.0 Specifications. + +- qcom,ports-hstop: + Usage: optional + Value type: <prop-encoded-array> + Definition: should be number identifying highest numbered coloum in + SoundWire Frame, i.e. the right edge of the Transport + sub-frame for each port. Values between 0 and 15 are valid. + Out ports followed by In ports. + More info in MIPI Alliance SoundWire 1.0 Specifications. + +- qcom,dports-type: + Usage: optional + Value type: <prop-encoded-array> + Definition: should be one of the following types + 0 for reduced port + 1 for simple ports + 2 for full port + Out ports followed by In ports. + More info in MIPI Alliance SoundWire 1.0 Specifications. + +Note: + More Information on detail of encoding of these fields can be +found in MIPI Alliance SoundWire 1.0 Specifications. + += SoundWire devices +Each subnode of the bus represents SoundWire device attached to it. +The properties of these nodes are defined by the individual bindings. + += EXAMPLE +The following example represents a SoundWire controller on DB845c board +which has controller integrated inside WCD934x codec on SDM845 SoC. + +soundwire: soundwire@c85 { + compatible = "qcom,soundwire-v1.3.0"; + reg = <0xc85 0x20>; + interrupts = <20 IRQ_TYPE_EDGE_RISING>; + clocks = <&wcc>; + clock-names = "iface"; + #sound-dai-cells = <1>; + qcom,dports-type = <0>; + qcom,dout-ports = <6>; + qcom,din-ports = <2>; + qcom,ports-sinterval-low = /bits/ 8 <0x07 0x1F 0x3F 0x7 0x1F 0x3F 0x0F 0x0F>; + qcom,ports-offset1 = /bits/ 8 <0x01 0x02 0x0C 0x6 0x12 0x0D 0x07 0x0A >; + qcom,ports-offset2 = /bits/ 8 <0x00 0x00 0x1F 0x00 0x00 0x1F 0x00 0x00>; + + /* Left Speaker */ + left{ + .... + }; + + /* Right Speaker */ + right{ + .... + }; +}; diff --git a/Documentation/devicetree/bindings/soundwire/soundwire-controller.yaml b/Documentation/devicetree/bindings/soundwire/soundwire-controller.yaml index 1b43993bccdb..330924b8618e 100644 --- a/Documentation/devicetree/bindings/soundwire/soundwire-controller.yaml +++ b/Documentation/devicetree/bindings/soundwire/soundwire-controller.yaml @@ -69,6 +69,7 @@ examples: reg = <0 1>; powerdown-gpios = <&wcdpinctrl 2 0>; #thermal-sensor-cells = <0>; + #sound-dai-cells = <0>; }; speaker@0,2 { @@ -76,6 +77,7 @@ examples: reg = <0 2>; powerdown-gpios = <&wcdpinctrl 2 0>; #thermal-sensor-cells = <0>; + #sound-dai-cells = <0>; }; }; diff --git a/Documentation/devicetree/bindings/spi/fsl-spi.txt b/Documentation/devicetree/bindings/spi/fsl-spi.txt index 411375eac54d..0654380eb751 100644 --- a/Documentation/devicetree/bindings/spi/fsl-spi.txt +++ b/Documentation/devicetree/bindings/spi/fsl-spi.txt @@ -15,13 +15,13 @@ Required properties: - clock-frequency : input clock frequency to non FSL_SOC cores Optional properties: -- gpios : specifies the gpio pins to be used for chipselects. +- cs-gpios : specifies the gpio pins to be used for chipselects. The gpios will be referred to as reg = <index> in the SPI child nodes. If unspecified, a single SPI device without a chip select can be used. - fsl,spisel_boot : for the MPC8306 and MPC8309, specifies that the SPISEL_BOOT signal is used as chip select for a slave device. Use reg = <number of gpios> in the corresponding child node, i.e. 0 if - the gpios property is not present. + the cs-gpios property is not present. Example: spi@4c0 { @@ -31,8 +31,8 @@ Example: interrupts = <82 0>; interrupt-parent = <700>; mode = "cpu"; - gpios = <&gpio 18 1 // device reg=<0> - &gpio 19 1>; // device reg=<1> + cs-gpios = <&gpio 18 1 // device reg=<0> + &gpio 19 1>; // device reg=<1> }; diff --git a/Documentation/devicetree/bindings/spi/nuvoton,npcm-pspi.txt b/Documentation/devicetree/bindings/spi/nuvoton,npcm-pspi.txt index 1fd9a4406a1d..b98203ca656d 100644 --- a/Documentation/devicetree/bindings/spi/nuvoton,npcm-pspi.txt +++ b/Documentation/devicetree/bindings/spi/nuvoton,npcm-pspi.txt @@ -12,6 +12,7 @@ Required properties: - clock-names: Should be "clk_apb5". - pinctrl-names : a pinctrl state named "default" must be defined. - pinctrl-0 : phandle referencing pin configuration of the device. + - resets : phandle to the reset control for this device. - cs-gpios: Specifies the gpio pins to be used for chipselects. See: Documentation/devicetree/bindings/spi/spi-bus.txt @@ -19,16 +20,6 @@ Optional properties: - clock-frequency : Input clock frequency to the PSPI block in Hz. Default is 25000000 Hz. -Aliases: -- All the SPI controller nodes should be represented in the aliases node using - the following format 'spi{n}' withe the correct numbered in "aliases" node. - -Example: - -aliases { - spi0 = &spi0; -}; - spi0: spi@f0200000 { compatible = "nuvoton,npcm750-pspi"; reg = <0xf0200000 0x1000>; @@ -39,5 +30,6 @@ spi0: spi@f0200000 { interrupts = <GIC_SPI 31 IRQ_TYPE_LEVEL_HIGH>; clocks = <&clk NPCM7XX_CLK_APB5>; clock-names = "clk_apb5"; + resets = <&rstc NPCM7XX_RESET_IPSRST2 NPCM7XX_RESET_PSPI1> cs-gpios = <&gpio6 11 GPIO_ACTIVE_LOW>; }; diff --git a/Documentation/devicetree/bindings/spi/spi-stm32.txt b/Documentation/devicetree/bindings/spi/spi-stm32.txt deleted file mode 100644 index d82755c63eaf..000000000000 --- a/Documentation/devicetree/bindings/spi/spi-stm32.txt +++ /dev/null @@ -1,62 +0,0 @@ -STMicroelectronics STM32 SPI Controller - -The STM32 SPI controller is used to communicate with external devices using -the Serial Peripheral Interface. It supports full-duplex, half-duplex and -simplex synchronous serial communication with external devices. It supports -from 4 to 32-bit data size. Although it can be configured as master or slave, -only master is supported by the driver. - -Required properties: -- compatible: Should be one of: - "st,stm32h7-spi" - "st,stm32f4-spi" -- reg: Offset and length of the device's register set. -- interrupts: Must contain the interrupt id. -- clocks: Must contain an entry for spiclk (which feeds the internal clock - generator). -- #address-cells: Number of cells required to define a chip select address. -- #size-cells: Should be zero. - -Optional properties: -- resets: Must contain the phandle to the reset controller. -- A pinctrl state named "default" may be defined to set pins in mode of - operation for SPI transfer. -- dmas: DMA specifiers for tx and rx dma. DMA fifo mode must be used. See the - STM32 DMA bindings, Documentation/devicetree/bindings/dma/stm32-dma.txt. -- dma-names: DMA request names should include "tx" and "rx" if present. -- cs-gpios: list of GPIO chip selects. See the SPI bus bindings, - Documentation/devicetree/bindings/spi/spi-bus.txt - - -Child nodes represent devices on the SPI bus - See ../spi/spi-bus.txt - -Optional properties: -- st,spi-midi-ns: Only for STM32H7, (Master Inter-Data Idleness) minimum time - delay in nanoseconds inserted between two consecutive data - frames. - - -Example: - spi2: spi@40003800 { - #address-cells = <1>; - #size-cells = <0>; - compatible = "st,stm32h7-spi"; - reg = <0x40003800 0x400>; - interrupts = <36>; - clocks = <&rcc SPI2_CK>; - resets = <&rcc 1166>; - dmas = <&dmamux1 0 39 0x400 0x01>, - <&dmamux1 1 40 0x400 0x01>; - dma-names = "rx", "tx"; - pinctrl-0 = <&spi2_pins_b>; - pinctrl-names = "default"; - cs-gpios = <&gpioa 11 0>; - - aardvark@0 { - compatible = "totalphase,aardvark"; - reg = <0>; - spi-max-frequency = <4000000>; - st,spi-midi-ns = <4000>; - }; - }; diff --git a/Documentation/devicetree/bindings/spi/spi_atmel.txt b/Documentation/devicetree/bindings/spi/spi_atmel.txt index f99c733d75c1..5bb4a8f1df7a 100644 --- a/Documentation/devicetree/bindings/spi/spi_atmel.txt +++ b/Documentation/devicetree/bindings/spi/spi_atmel.txt @@ -1,7 +1,7 @@ Atmel SPI device Required properties: -- compatible : should be "atmel,at91rm9200-spi". +- compatible : should be "atmel,at91rm9200-spi" or "microchip,sam9x60-spi". - reg: Address and length of the register set for the device - interrupts: Should contain spi interrupt - cs-gpios: chipselects (optional for SPI controller version >= 2 with the diff --git a/Documentation/devicetree/bindings/spi/st,stm32-spi.yaml b/Documentation/devicetree/bindings/spi/st,stm32-spi.yaml new file mode 100644 index 000000000000..f0d979664f07 --- /dev/null +++ b/Documentation/devicetree/bindings/spi/st,stm32-spi.yaml @@ -0,0 +1,105 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/spi/st,stm32-spi.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: STMicroelectronics STM32 SPI Controller bindings + +description: | + The STM32 SPI controller is used to communicate with external devices using + the Serial Peripheral Interface. It supports full-duplex, half-duplex and + simplex synchronous serial communication with external devices. It supports + from 4 to 32-bit data size. + +maintainers: + - Erwan Leray <erwan.leray@st.com> + - Fabrice Gasnier <fabrice.gasnier@st.com> + +allOf: + - $ref: "spi-controller.yaml#" + - if: + properties: + compatible: + contains: + const: st,stm32f4-spi + + then: + properties: + st,spi-midi-ns: false + +properties: + compatible: + enum: + - st,stm32f4-spi + - st,stm32h7-spi + + reg: + maxItems: 1 + + clocks: + maxItems: 1 + + interrupts: + maxItems: 1 + + resets: + maxItems: 1 + + dmas: + description: | + DMA specifiers for tx and rx dma. DMA fifo mode must be used. See + the STM32 DMA bindings Documentation/devicetree/bindings/dma/stm32-dma.txt. + items: + - description: rx DMA channel + - description: tx DMA channel + + dma-names: + items: + - const: rx + - const: tx + +patternProperties: + "^[a-zA-Z][a-zA-Z0-9,+\\-._]{0,63}@[0-9a-f]+$": + type: object + # SPI slave nodes must be children of the SPI master node and can + # contain the following properties. + properties: + st,spi-midi-ns: + description: | + Only for STM32H7, (Master Inter-Data Idleness) minimum time + delay in nanoseconds inserted between two consecutive data frames. + +required: + - compatible + - reg + - clocks + - interrupts + +examples: + - | + #include <dt-bindings/interrupt-controller/arm-gic.h> + #include <dt-bindings/clock/stm32mp1-clks.h> + #include <dt-bindings/reset/stm32mp1-resets.h> + spi@4000b000 { + #address-cells = <1>; + #size-cells = <0>; + compatible = "st,stm32h7-spi"; + reg = <0x4000b000 0x400>; + interrupts = <GIC_SPI 36 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&rcc SPI2_K>; + resets = <&rcc SPI2_R>; + dmas = <&dmamux1 0 39 0x400 0x05>, + <&dmamux1 1 40 0x400 0x05>; + dma-names = "rx", "tx"; + cs-gpios = <&gpioa 11 0>; + + aardvark@0 { + compatible = "totalphase,aardvark"; + reg = <0>; + spi-max-frequency = <4000000>; + st,spi-midi-ns = <4000>; + }; + }; + +... diff --git a/Documentation/devicetree/bindings/sram/allwinner,sun4i-a10-system-control.yaml b/Documentation/devicetree/bindings/sram/allwinner,sun4i-a10-system-control.yaml new file mode 100644 index 000000000000..80bac7a182d5 --- /dev/null +++ b/Documentation/devicetree/bindings/sram/allwinner,sun4i-a10-system-control.yaml @@ -0,0 +1,140 @@ +# SPDX-License-Identifier: GPL-2.0+ +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/sram/allwinner,sun4i-a10-system-control.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Allwinner A10 System Control Device Tree Bindings + +maintainers: + - Chen-Yu Tsai <wens@csie.org> + - Maxime Ripard <mripard@kernel.org> + +description: + The SRAM controller found on most Allwinner devices is represented + by a regular node for the SRAM controller itself, with sub-nodes + representing the SRAM handled by the SRAM controller. + +properties: + "#address-cells": + const: 1 + + "#size-cells": + const: 1 + + compatible: + oneOf: + - const: allwinner,sun4i-a10-sram-controller + deprecated: true + - const: allwinner,sun4i-a10-system-control + - const: allwinner,sun5i-a13-system-control + - items: + - const: allwinner,sun7i-a20-system-control + - const: allwinner,sun4i-a10-system-control + - const: allwinner,sun8i-a23-system-control + - const: allwinner,sun8i-h3-system-control + - const: allwinner,sun50i-a64-sram-controller + deprecated: true + - const: allwinner,sun50i-a64-system-control + - const: allwinner,sun50i-h5-system-control + - items: + - const: allwinner,sun50i-h6-system-control + - const: allwinner,sun50i-a64-system-control + - items: + - const: allwinner,suniv-f1c100s-system-control + - const: allwinner,sun4i-a10-system-control + + reg: + maxItems: 1 + + ranges: true + +patternProperties: + "^sram@[a-z0-9]+": + type: object + + properties: + compatible: + const: mmio-sram + + patternProperties: + "^sram-section?@[a-f0-9]+$": + type: object + + properties: + compatible: + oneOf: + - const: allwinner,sun4i-a10-sram-a3-a4 + - const: allwinner,sun4i-a10-sram-c1 + - const: allwinner,sun4i-a10-sram-d + - const: allwinner,sun50i-a64-sram-c + - items: + - const: allwinner,sun5i-a13-sram-a3-a4 + - const: allwinner,sun4i-a10-sram-a3-a4 + - items: + - const: allwinner,sun7i-a20-sram-a3-a4 + - const: allwinner,sun4i-a10-sram-a3-a4 + - items: + - const: allwinner,sun5i-a13-sram-c1 + - const: allwinner,sun4i-a10-sram-c1 + - items: + - const: allwinner,sun7i-a20-sram-c1 + - const: allwinner,sun4i-a10-sram-c1 + - items: + - const: allwinner,sun8i-a23-sram-c1 + - const: allwinner,sun4i-a10-sram-c1 + - items: + - const: allwinner,sun8i-h3-sram-c1 + - const: allwinner,sun4i-a10-sram-c1 + - items: + - const: allwinner,sun50i-a64-sram-c1 + - const: allwinner,sun4i-a10-sram-c1 + - items: + - const: allwinner,sun50i-h5-sram-c1 + - const: allwinner,sun4i-a10-sram-c1 + - items: + - const: allwinner,sun50i-h6-sram-c1 + - const: allwinner,sun4i-a10-sram-c1 + - items: + - const: allwinner,sun5i-a13-sram-d + - const: allwinner,sun4i-a10-sram-d + - items: + - const: allwinner,sun7i-a20-sram-d + - const: allwinner,sun4i-a10-sram-d + - items: + - const: allwinner,suniv-f1c100s-sram-d + - const: allwinner,sun4i-a10-sram-d + - items: + - const: allwinner,sun50i-h6-sram-c + - const: allwinner,sun50i-a64-sram-c + +required: + - "#address-cells" + - "#size-cells" + - compatible + - reg + +additionalProperties: false + +examples: + - | + system-control@1c00000 { + compatible = "allwinner,sun4i-a10-system-control"; + reg = <0x01c00000 0x30>; + #address-cells = <1>; + #size-cells = <1>; + ranges; + + sram_a: sram@00000000 { + compatible = "mmio-sram"; + reg = <0x00000000 0xc000>; + #address-cells = <1>; + #size-cells = <1>; + ranges = <0 0x00000000 0xc000>; + + emac_sram: sram-section@8000 { + compatible = "allwinner,sun4i-a10-sram-a3-a4"; + reg = <0x8000 0x4000>; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/sram/sram.yaml b/Documentation/devicetree/bindings/sram/sram.yaml index ee2287a1b14d..7b83cc6c9bfa 100644 --- a/Documentation/devicetree/bindings/sram/sram.yaml +++ b/Documentation/devicetree/bindings/sram/sram.yaml @@ -55,7 +55,7 @@ properties: type: boolean patternProperties: - "^([a-z]*-)?sram@[a-f0-9]+$": + "^([a-z]*-)?sram(-section)?@[a-f0-9]+$": type: object description: Each child of the sram node specifies a region of reserved memory. @@ -64,15 +64,20 @@ patternProperties: description: Should contain a vendor specific string in the form <vendor>,[<device>-]<usage> - enum: - - allwinner,sun9i-a80-smp-sram - - amlogic,meson8-smp-sram - - amlogic,meson8b-smp-sram - - renesas,smp-sram - - rockchip,rk3066-smp-sram - - samsung,exynos4210-sysram - - samsung,exynos4210-sysram-ns - - socionext,milbeaut-smp-sram + contains: + enum: + - allwinner,sun4i-a10-sram-a3-a4 + - allwinner,sun4i-a10-sram-c1 + - allwinner,sun4i-a10-sram-d + - allwinner,sun9i-a80-smp-sram + - allwinner,sun50i-a64-sram-c + - amlogic,meson8-smp-sram + - amlogic,meson8b-smp-sram + - renesas,smp-sram + - rockchip,rk3066-smp-sram + - samsung,exynos4210-sysram + - samsung,exynos4210-sysram-ns + - socionext,milbeaut-smp-sram reg: description: diff --git a/Documentation/devicetree/bindings/sram/sunxi-sram.txt b/Documentation/devicetree/bindings/sram/sunxi-sram.txt deleted file mode 100644 index 380246a805f2..000000000000 --- a/Documentation/devicetree/bindings/sram/sunxi-sram.txt +++ /dev/null @@ -1,113 +0,0 @@ -Allwinnner SoC SRAM controllers ------------------------------------------------------ - -The SRAM controller found on most Allwinner devices is represented by -a regular node for the SRAM controller itself, with sub-nodes -reprensenting the SRAM handled by the SRAM controller. - -Controller Node ---------------- - -Required properties: -- compatible : should be: - - "allwinner,sun4i-a10-sram-controller" (deprecated) - - "allwinner,sun4i-a10-system-control" - - "allwinner,sun5i-a13-system-control" - - "allwinner,sun7i-a20-system-control", "allwinner,sun4i-a10-system-control" - - "allwinner,sun8i-a23-system-control" - - "allwinner,sun8i-h3-system-control" - - "allwinner,sun50i-a64-sram-controller" (deprecated) - - "allwinner,sun50i-a64-system-control" - - "allwinner,sun50i-h5-system-control" - - "allwinner,sun50i-h6-system-control", "allwinner,sun50i-a64-system-control" - - "allwinner,suniv-f1c100s-system-control", "allwinner,sun4i-a10-system-control" -- reg : sram controller register offset + length - -SRAM nodes ----------- - -Each SRAM is described using the mmio-sram bindings documented in -Documentation/devicetree/bindings/sram/sram.txt - -Each SRAM will have SRAM sections that are going to be handled by the -SRAM controller as subnodes. These sections are represented following -once again the representation described in the mmio-sram binding. - -The valid sections compatible for A10 are: - - allwinner,sun4i-a10-sram-a3-a4 - - allwinner,sun4i-a10-sram-c1 - - allwinner,sun4i-a10-sram-d - -The valid sections compatible for A13 are: - - allwinner,sun5i-a13-sram-a3-a4, allwinner,sun4i-a10-sram-a3-a4 - - allwinner,sun5i-a13-sram-c1, allwinner,sun4i-a10-sram-c1 - - allwinner,sun5i-a13-sram-d, allwinner,sun4i-a10-sram-d - -The valid sections compatible for A20 are: - - allwinner,sun7i-a20-sram-a3-a4, allwinner,sun4i-a10-sram-a3-a4 - - allwinner,sun7i-a20-sram-c1, allwinner,sun4i-a10-sram-c1 - - allwinner,sun7i-a20-sram-d, allwinner,sun4i-a10-sram-d - -The valid sections compatible for A23/A33 are: - - allwinner,sun8i-a23-sram-c1, allwinner,sun4i-a10-sram-c1 - -The valid sections compatible for H3 are: - - allwinner,sun8i-h3-sram-c1, allwinner,sun4i-a10-sram-c1 - -The valid sections compatible for A64 are: - - allwinner,sun50i-a64-sram-c - - allwinner,sun50i-a64-sram-c1, allwinner,sun4i-a10-sram-c1 - -The valid sections compatible for H5 are: - - allwinner,sun50i-h5-sram-c1, allwinner,sun4i-a10-sram-c1 - -The valid sections compatible for H6 are: - - allwinner,sun50i-h6-sram-c, allwinner,sun50i-a64-sram-c - - allwinner,sun50i-h6-sram-c1, allwinner,sun4i-a10-sram-c1 - -The valid sections compatible for F1C100s are: - - allwinner,suniv-f1c100s-sram-d, allwinner,sun4i-a10-sram-d - -Devices using SRAM sections ---------------------------- - -Some devices need to request to the SRAM controller to map an SRAM for -their exclusive use. - -The relationship between such a device and an SRAM section is -expressed through the allwinner,sram property, that will take a -phandle and an argument. - -This valid values for this argument are: - - 0: CPU - - 1: Device - -Example -------- -system-control@1c00000 { - compatible = "allwinner,sun4i-a10-system-control"; - reg = <0x01c00000 0x30>; - #address-cells = <1>; - #size-cells = <1>; - ranges; - - sram_a: sram@00000000 { - compatible = "mmio-sram"; - reg = <0x00000000 0xc000>; - #address-cells = <1>; - #size-cells = <1>; - ranges = <0 0x00000000 0xc000>; - - emac_sram: sram-section@8000 { - compatible = "allwinner,sun4i-a10-sram-a3-a4"; - reg = <0x8000 0x4000>; - }; - }; -}; - -emac: ethernet@1c0b000 { - compatible = "allwinner,sun4i-a10-emac"; - ... - - allwinner,sram = <&emac_sram 1>; -}; diff --git a/Documentation/devicetree/bindings/thermal/allwinner,sun8i-a83t-ths.yaml b/Documentation/devicetree/bindings/thermal/allwinner,sun8i-a83t-ths.yaml new file mode 100644 index 000000000000..87369264feb9 --- /dev/null +++ b/Documentation/devicetree/bindings/thermal/allwinner,sun8i-a83t-ths.yaml @@ -0,0 +1,160 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/thermal/allwinner,sun8i-a83t-ths.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Allwinner SUN8I Thermal Controller Device Tree Bindings + +maintainers: + - Vasily Khoruzhick <anarsoul@gmail.com> + - Yangtao Li <tiny.windzz@gmail.com> + +properties: + compatible: + enum: + - allwinner,sun8i-a83t-ths + - allwinner,sun8i-h3-ths + - allwinner,sun8i-r40-ths + - allwinner,sun50i-a64-ths + - allwinner,sun50i-h5-ths + - allwinner,sun50i-h6-ths + + clocks: + minItems: 1 + maxItems: 2 + items: + - description: Bus Clock + - description: Module Clock + + clock-names: + minItems: 1 + maxItems: 2 + items: + - const: bus + - const: mod + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + resets: + maxItems: 1 + + nvmem-cells: + maxItems: 1 + description: Calibration data for thermal sensors + + nvmem-cell-names: + const: calibration + + # See ./thermal.txt for details + "#thermal-sensor-cells": + enum: + - 0 + - 1 + +allOf: + - if: + properties: + compatible: + contains: + const: allwinner,sun50i-h6-ths + + then: + properties: + clocks: + maxItems: 1 + + clock-names: + maxItems: 1 + + else: + properties: + clocks: + minItems: 2 + + clock-names: + minItems: 2 + + - if: + properties: + compatible: + contains: + const: allwinner,sun8i-h3-ths + + then: + properties: + "#thermal-sensor-cells": + const: 0 + + else: + properties: + "#thermal-sensor-cells": + const: 1 + + - if: + properties: + compatible: + contains: + enum: + - const: allwinner,sun8i-h3-ths + - const: allwinner,sun8i-r40-ths + - const: allwinner,sun50i-a64-ths + - const: allwinner,sun50i-h5-ths + - const: allwinner,sun50i-h6-ths + + then: + required: + - clocks + - clock-names + - resets + +required: + - compatible + - reg + - interrupts + - '#thermal-sensor-cells' + +additionalProperties: false + +examples: + - | + thermal-sensor@1f04000 { + compatible = "allwinner,sun8i-a83t-ths"; + reg = <0x01f04000 0x100>; + interrupts = <0 31 0>; + nvmem-cells = <&ths_calibration>; + nvmem-cell-names = "calibration"; + #thermal-sensor-cells = <1>; + }; + + - | + thermal-sensor@1c25000 { + compatible = "allwinner,sun8i-h3-ths"; + reg = <0x01c25000 0x400>; + clocks = <&ccu 0>, <&ccu 1>; + clock-names = "bus", "mod"; + resets = <&ccu 2>; + interrupts = <0 31 0>; + nvmem-cells = <&ths_calibration>; + nvmem-cell-names = "calibration"; + #thermal-sensor-cells = <0>; + }; + + - | + thermal-sensor@5070400 { + compatible = "allwinner,sun50i-h6-ths"; + reg = <0x05070400 0x100>; + clocks = <&ccu 0>; + clock-names = "bus"; + resets = <&ccu 2>; + interrupts = <0 15 0>; + nvmem-cells = <&ths_calibration>; + nvmem-cell-names = "calibration"; + #thermal-sensor-cells = <1>; + }; + +... diff --git a/Documentation/devicetree/bindings/thermal/brcm,avs-ro-thermal.yaml b/Documentation/devicetree/bindings/thermal/brcm,avs-ro-thermal.yaml new file mode 100644 index 000000000000..d9fdf4809a49 --- /dev/null +++ b/Documentation/devicetree/bindings/thermal/brcm,avs-ro-thermal.yaml @@ -0,0 +1,48 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/thermal/brcm,avs-ro-thermal.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Broadcom AVS ring oscillator thermal + +maintainers: + - Stefan Wahren <wahrenst@gmx.net> + +description: |+ + The thermal node should be the child of a syscon node with the + required property: + + - compatible: Should be one of the following: + "brcm,bcm2711-avs-monitor", "syscon", "simple-mfd" + + Refer to the the bindings described in + Documentation/devicetree/bindings/mfd/syscon.txt + +properties: + compatible: + const: brcm,bcm2711-thermal + + # See ./thermal.txt for details + "#thermal-sensor-cells": + const: 0 + +required: + - compatible + - '#thermal-sensor-cells' + +additionalProperties: false + +examples: + - | + avs-monitor@7d5d2000 { + compatible = "brcm,bcm2711-avs-monitor", + "syscon", "simple-mfd"; + reg = <0x7d5d2000 0xf00>; + + thermal: thermal { + compatible = "brcm,bcm2711-thermal"; + #thermal-sensor-cells = <0>; + }; + }; +... diff --git a/Documentation/devicetree/bindings/thermal/brcm,avs-tmon.txt b/Documentation/devicetree/bindings/thermal/brcm,avs-tmon.txt index 43a9ed545944..74a9ef09db8b 100644 --- a/Documentation/devicetree/bindings/thermal/brcm,avs-tmon.txt +++ b/Documentation/devicetree/bindings/thermal/brcm,avs-tmon.txt @@ -3,9 +3,13 @@ Thermal management core, provided by the AVS TMON hardware block. Required properties: -- compatible: must be "brcm,avs-tmon" and/or "brcm,avs-tmon-bcm7445" +- compatible: must be one of: + "brcm,avs-tmon-bcm7216" + "brcm,avs-tmon-bcm7445" + "brcm,avs-tmon" - reg: address range for the AVS TMON registers -- interrupts: temperature monitor interrupt, for high/low threshold triggers +- interrupts: temperature monitor interrupt, for high/low threshold triggers, + required except for "brcm,avs-tmon-bcm7216" - interrupt-names: should be "tmon" Example: diff --git a/Documentation/devicetree/bindings/timer/arm,arch_timer_mmio.yaml b/Documentation/devicetree/bindings/timer/arm,arch_timer_mmio.yaml index b3f0fe96ff0d..102f319833d9 100644 --- a/Documentation/devicetree/bindings/timer/arm,arch_timer_mmio.yaml +++ b/Documentation/devicetree/bindings/timer/arm,arch_timer_mmio.yaml @@ -99,22 +99,22 @@ examples: compatible = "arm,armv7-timer-mem"; #address-cells = <1>; #size-cells = <1>; - ranges; + ranges = <0 0xf0001000 0x1000>; reg = <0xf0000000 0x1000>; clock-frequency = <50000000>; - frame@f0001000 { + frame@0 { frame-number = <0>; interrupts = <0 13 0x8>, <0 14 0x8>; - reg = <0xf0001000 0x1000>, - <0xf0002000 0x1000>; + reg = <0x0000 0x1000>, + <0x1000 0x1000>; }; - frame@f0003000 { + frame@2000 { frame-number = <1>; interrupts = <0 15 0x8>; - reg = <0xf0003000 0x1000>; + reg = <0x2000 0x1000>; }; }; diff --git a/Documentation/devicetree/bindings/timer/renesas,cmt.txt b/Documentation/devicetree/bindings/timer/renesas,cmt.txt index a444cfc5852a..a747fabab7d3 100644 --- a/Documentation/devicetree/bindings/timer/renesas,cmt.txt +++ b/Documentation/devicetree/bindings/timer/renesas,cmt.txt @@ -29,6 +29,8 @@ Required Properties: - "renesas,r8a77470-cmt1" for the 48-bit CMT1 device included in r8a77470. - "renesas,r8a774a1-cmt0" for the 32-bit CMT0 device included in r8a774a1. - "renesas,r8a774a1-cmt1" for the 48-bit CMT devices included in r8a774a1. + - "renesas,r8a774b1-cmt0" for the 32-bit CMT0 device included in r8a774b1. + - "renesas,r8a774b1-cmt1" for the 48-bit CMT devices included in r8a774b1. - "renesas,r8a774c0-cmt0" for the 32-bit CMT0 device included in r8a774c0. - "renesas,r8a774c0-cmt1" for the 48-bit CMT devices included in r8a774c0. - "renesas,r8a7790-cmt0" for the 32-bit CMT0 device included in r8a7790. diff --git a/Documentation/devicetree/bindings/timer/renesas,tmu.txt b/Documentation/devicetree/bindings/timer/renesas,tmu.txt index 9dff7e5cae6a..29159f4e65ab 100644 --- a/Documentation/devicetree/bindings/timer/renesas,tmu.txt +++ b/Documentation/devicetree/bindings/timer/renesas,tmu.txt @@ -11,6 +11,7 @@ Required Properties: - compatible: must contain one or more of the following: - "renesas,tmu-r8a7740" for the r8a7740 TMU - "renesas,tmu-r8a774a1" for the r8a774A1 TMU + - "renesas,tmu-r8a774b1" for the r8a774B1 TMU - "renesas,tmu-r8a774c0" for the r8a774C0 TMU - "renesas,tmu-r8a7778" for the r8a7778 TMU - "renesas,tmu-r8a7779" for the r8a7779 TMU diff --git a/Documentation/devicetree/bindings/trivial-devices.yaml b/Documentation/devicetree/bindings/trivial-devices.yaml index 765fd1c170df..978de7d37c66 100644 --- a/Documentation/devicetree/bindings/trivial-devices.yaml +++ b/Documentation/devicetree/bindings/trivial-devices.yaml @@ -104,6 +104,10 @@ properties: - infineon,slb9645tt # Infineon TLV493D-A1B6 I2C 3D Magnetic Sensor - infineon,tlv493d-a1b6 + # Infineon Multi-phase Digital VR Controller xdpe12254 + - infineon,xdpe12254 + # Infineon Multi-phase Digital VR Controller xdpe12284 + - infineon,xdpe12284 # Inspur Power System power supply unit version 1 - inspur,ipsps1 # Intersil ISL29028 Ambient Light and Proximity Sensor @@ -132,6 +136,8 @@ properties: - maxim,max6621 # 9-Bit/12-Bit Temperature Sensors with I²C-Compatible Serial Interface - maxim,max6625 + # 3-Channel Remote Temperature Sensor + - maxim,max31730 # mCube 3-axis 8-bit digital accelerometer - mcube,mc3230 # MEMSIC 2-axis 8-bit digital accelerometer @@ -354,6 +360,10 @@ properties: - ti,tmp103 # Digital Temperature Sensor - ti,tmp275 + # TI Dual channel DCAP+ multiphase controller TPS53679 + - ti,tps53679 + # TI Dual channel DCAP+ multiphase controller TPS53688 + - ti,tps53688 # Winbond/Nuvoton H/W Monitor - winbond,w83793 # i2c trusted platform module (TPM) diff --git a/Documentation/devicetree/bindings/usb/amlogic,meson-g12a-usb-ctrl.yaml b/Documentation/devicetree/bindings/usb/amlogic,meson-g12a-usb-ctrl.yaml index 4efb77b653ab..267fce165994 100644 --- a/Documentation/devicetree/bindings/usb/amlogic,meson-g12a-usb-ctrl.yaml +++ b/Documentation/devicetree/bindings/usb/amlogic,meson-g12a-usb-ctrl.yaml @@ -107,7 +107,7 @@ examples: reg = <0xff400000 0x40000>; interrupts = <31>; clocks = <&clkc_usb1>; - clock-names = "ddr"; + clock-names = "otg"; phys = <&usb2_phy1>; dr_mode = "peripheral"; g-rx-fifo-size = <192>; diff --git a/Documentation/devicetree/bindings/usb/ci-hdrc-usb2.txt b/Documentation/devicetree/bindings/usb/ci-hdrc-usb2.txt index cfc9f40ab641..51376cbe5f3d 100644 --- a/Documentation/devicetree/bindings/usb/ci-hdrc-usb2.txt +++ b/Documentation/devicetree/bindings/usb/ci-hdrc-usb2.txt @@ -15,6 +15,10 @@ Required properties: "qcom,ci-hdrc" "chipidea,usb2" "xlnx,zynq-usb-2.20a" + "nvidia,tegra20-udc" + "nvidia,tegra30-udc" + "nvidia,tegra114-udc" + "nvidia,tegra124-udc" - reg: base address and length of the registers - interrupts: interrupt for the USB controller diff --git a/Documentation/devicetree/bindings/usb/dwc2.txt b/Documentation/devicetree/bindings/usb/dwc2.txt deleted file mode 100644 index aafff3a6904d..000000000000 --- a/Documentation/devicetree/bindings/usb/dwc2.txt +++ /dev/null @@ -1,64 +0,0 @@ -Platform DesignWare HS OTG USB 2.0 controller ------------------------------------------------------ - -Required properties: -- compatible : One of: - - brcm,bcm2835-usb: The DWC2 USB controller instance in the BCM2835 SoC. - - hisilicon,hi6220-usb: The DWC2 USB controller instance in the hi6220 SoC. - - rockchip,rk3066-usb: The DWC2 USB controller instance in the rk3066 Soc; - - "rockchip,px30-usb", "rockchip,rk3066-usb", "snps,dwc2": for px30 Soc; - - "rockchip,rk3188-usb", "rockchip,rk3066-usb", "snps,dwc2": for rk3188 Soc; - - "rockchip,rk3288-usb", "rockchip,rk3066-usb", "snps,dwc2": for rk3288 Soc; - - "lantiq,arx100-usb": The DWC2 USB controller instance in Lantiq ARX SoCs; - - "lantiq,xrx200-usb": The DWC2 USB controller instance in Lantiq XRX SoCs; - - "amlogic,meson8-usb": The DWC2 USB controller instance in Amlogic Meson8 SoCs; - - "amlogic,meson8b-usb": The DWC2 USB controller instance in Amlogic Meson8b SoCs; - - "amlogic,meson-gxbb-usb": The DWC2 USB controller instance in Amlogic S905 SoCs; - - "amlogic,meson-g12a-usb": The DWC2 USB controller instance in Amlogic G12A SoCs; - - "amcc,dwc-otg": The DWC2 USB controller instance in AMCC Canyonlands 460EX SoCs; - - snps,dwc2: A generic DWC2 USB controller with default parameters. - - "st,stm32f4x9-fsotg": The DWC2 USB FS/HS controller instance in STM32F4x9 SoCs - configured in FS mode; - - "st,stm32f4x9-hsotg": The DWC2 USB HS controller instance in STM32F4x9 SoCs - configured in HS mode; - - "st,stm32f7-hsotg": The DWC2 USB HS controller instance in STM32F7 SoCs - configured in HS mode; -- reg : Should contain 1 register range (address and length) -- interrupts : Should contain 1 interrupt -- clocks: clock provider specifier -- clock-names: shall be "otg" -Refer to clk/clock-bindings.txt for generic clock consumer properties - -Optional properties: -- phys: phy provider specifier -- phy-names: shall be "usb2-phy" -- vbus-supply: reference to the VBUS regulator. Depending on the current mode - this is enabled (in "host" mode") or disabled (in "peripheral" mode). The - regulator is updated if the controller is configured in "otg" mode and the - status changes between "host" and "peripheral". -Refer to phy/phy-bindings.txt for generic phy consumer properties -- dr_mode: shall be one of "host", "peripheral" and "otg" - Refer to usb/generic.txt -- g-rx-fifo-size: size of rx fifo size in gadget mode. -- g-np-tx-fifo-size: size of non-periodic tx fifo size in gadget mode. -- g-tx-fifo-size: size of periodic tx fifo per endpoint (except ep0) in gadget mode. -- snps,need-phy-for-wake: If present indicates that the phy needs to be left - on for remote wakeup during suspend. -- snps,reset-phy-on-wake: If present indicates that we need to reset the PHY when - we detect a wakeup. This is due to a hardware errata. - -Deprecated properties: -- g-use-dma: gadget DMA mode is automatically detected - -Example: - - usb@101c0000 { - compatible = "ralink,rt3050-usb, snps,dwc2"; - reg = <0x101c0000 40000>; - interrupts = <18>; - clocks = <&usb_otg_ahb_clk>; - clock-names = "otg"; - phys = <&usbphy>; - phy-names = "usb2-phy"; - snps,need-phy-for-wake; - }; diff --git a/Documentation/devicetree/bindings/usb/dwc2.yaml b/Documentation/devicetree/bindings/usb/dwc2.yaml new file mode 100644 index 000000000000..71cf7ba32237 --- /dev/null +++ b/Documentation/devicetree/bindings/usb/dwc2.yaml @@ -0,0 +1,151 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/usb/dwc2.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: DesignWare HS OTG USB 2.0 controller Bindings + +maintainers: + - Rob Herring <robh@kernel.org> + +properties: + compatible: + oneOf: + - const: brcm,bcm2835-usb + - const: hisilicon,hi6220-usb + - items: + - const: rockchip,rk3066-usb + - const: snps,dwc2 + - items: + - const: rockchip,px30-usb + - const: rockchip,rk3066-usb + - const: snps,dwc2 + - items: + - const: rockchip,rk3036-usb + - const: rockchip,rk3066-usb + - const: snps,dwc2 + - items: + - const: rockchip,rv1108-usb + - const: rockchip,rk3066-usb + - const: snps,dwc2 + - items: + - const: rockchip,rk3188-usb + - const: rockchip,rk3066-usb + - const: snps,dwc2 + - items: + - const: rockchip,rk3228-usb + - const: rockchip,rk3066-usb + - const: snps,dwc2 + - items: + - const: rockchip,rk3288-usb + - const: rockchip,rk3066-usb + - const: snps,dwc2 + - const: lantiq,arx100-usb + - const: lantiq,xrx200-usb + - items: + - const: amlogic,meson8-usb + - const: snps,dwc2 + - items: + - const: amlogic,meson8b-usb + - const: snps,dwc2 + - const: amlogic,meson-gxbb-usb + - items: + - const: amlogic,meson-g12a-usb + - const: snps,dwc2 + - const: amcc,dwc-otg + - const: snps,dwc2 + - const: st,stm32f4x9-fsotg + - const: st,stm32f4x9-hsotg + - const: st,stm32f7-hsotg + - const: samsung,s3c6400-hsotg + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + clocks: + maxItems: 1 + + clock-names: + items: + - const: otg + + resets: + items: + - description: common reset + - description: ecc reset + minItems: 1 + + reset-names: + items: + - const: dwc2 + - const: dwc2-ecc + minItems: 1 + + phys: + maxItems: 1 + + phy-names: + const: usb2-phy + + vbus-supply: + description: reference to the VBUS regulator. Depending on the current mode + this is enabled (in "host" mode") or disabled (in "peripheral" mode). The + regulator is updated if the controller is configured in "otg" mode and the + status changes between "host" and "peripheral". + + vusb_d-supply: + description: phandle to voltage regulator of digital section, + + vusb_a-supply: + description: phandle to voltage regulator of analog section. + + dr_mode: + enum: [host, peripheral, otg] + + g-rx-fifo-size: + $ref: /schemas/types.yaml#/definitions/uint32 + description: size of rx fifo size in gadget mode. + + g-np-tx-fifo-size: + $ref: /schemas/types.yaml#/definitions/uint32 + description: size of non-periodic tx fifo size in gadget mode. + + g-tx-fifo-size: + $ref: /schemas/types.yaml#/definitions/uint32-array + description: size of periodic tx fifo per endpoint (except ep0) in gadget mode. + + snps,need-phy-for-wake: + $ref: /schemas/types.yaml#/definitions/flag + description: If present indicates that the phy needs to be left on for remote wakeup during suspend. + + snps,reset-phy-on-wake: + $ref: /schemas/types.yaml#/definitions/flag + description: If present indicates that we need to reset the PHY when we detect a wakeup. + This is due to a hardware errata. + +required: + - compatible + - reg + - interrupts + - clocks + - clock-names + +additionalProperties: false + +examples: + - | + usb@101c0000 { + compatible = "rockchip,rk3066-usb", "snps,dwc2"; + reg = <0x10180000 0x40000>; + interrupts = <18>; + clocks = <&usb_otg_ahb_clk>; + clock-names = "otg"; + phys = <&usbphy>; + phy-names = "usb2-phy"; + }; + +... diff --git a/Documentation/devicetree/bindings/usb/generic.txt b/Documentation/devicetree/bindings/usb/generic.txt index cf5a1ad456e6..e6790d2a4da9 100644 --- a/Documentation/devicetree/bindings/usb/generic.txt +++ b/Documentation/devicetree/bindings/usb/generic.txt @@ -2,10 +2,11 @@ Generic USB Properties Optional properties: - maximum-speed: tells USB controllers we want to work up to a certain - speed. Valid arguments are "super-speed", "high-speed", - "full-speed" and "low-speed". In case this isn't passed - via DT, USB controllers should default to their maximum - HW capability. + speed. Valid arguments are "super-speed-plus", + "super-speed", "high-speed", "full-speed" and + "low-speed". In case this isn't passed via DT, USB + controllers should default to their maximum HW + capability. - dr_mode: tells Dual-Role USB controllers that we want to work on a particular mode. Valid arguments are "host", "peripheral" and "otg". In case this attribute isn't diff --git a/Documentation/devicetree/bindings/usb/mediatek,musb.txt b/Documentation/devicetree/bindings/usb/mediatek,musb.txt new file mode 100644 index 000000000000..2b8a87c90d9e --- /dev/null +++ b/Documentation/devicetree/bindings/usb/mediatek,musb.txt @@ -0,0 +1,57 @@ +MediaTek musb DRD/OTG controller +------------------------------------------- + +Required properties: + - compatible : should be one of: + "mediatek,mt2701-musb" + ... + followed by "mediatek,mtk-musb" + - reg : specifies physical base address and size of + the registers + - interrupts : interrupt used by musb controller + - interrupt-names : must be "mc" + - phys : PHY specifier for the OTG phy + - dr_mode : should be one of "host", "peripheral" or "otg", + refer to usb/generic.txt + - clocks : a list of phandle + clock-specifier pairs, one for + each entry in clock-names + - clock-names : must contain "main", "mcu", "univpll" + for clocks of controller + +Optional properties: + - power-domains : a phandle to USB power domain node to control USB's + MTCMOS + +Required child nodes: + usb connector node as defined in bindings/connector/usb-connector.txt +Optional properties: + - id-gpios : input GPIO for USB ID pin. + - vbus-gpios : input GPIO for USB VBUS pin. + - vbus-supply : reference to the VBUS regulator, needed when supports + dual-role mode + - usb-role-switch : use USB Role Switch to support dual-role switch, see + usb/generic.txt. + +Example: + +usb2: usb@11200000 { + compatible = "mediatek,mt2701-musb", + "mediatek,mtk-musb"; + reg = <0 0x11200000 0 0x1000>; + interrupts = <GIC_SPI 32 IRQ_TYPE_LEVEL_LOW>; + interrupt-names = "mc"; + phys = <&u2port2 PHY_TYPE_USB2>; + dr_mode = "otg"; + clocks = <&pericfg CLK_PERI_USB0>, + <&pericfg CLK_PERI_USB0_MCU>, + <&pericfg CLK_PERI_USB_SLV>; + clock-names = "main","mcu","univpll"; + power-domains = <&scpsys MT2701_POWER_DOMAIN_IFR_MSC>; + usb-role-switch; + connector{ + compatible = "gpio-usb-b-connector", "usb-b-connector"; + type = "micro"; + id-gpios = <&pio 44 GPIO_ACTIVE_HIGH>; + vbus-supply = <&usb_vbus>; + }; +}; diff --git a/Documentation/devicetree/bindings/vendor-prefixes.yaml b/Documentation/devicetree/bindings/vendor-prefixes.yaml index 6046f4555852..9e67944bec9c 100644 --- a/Documentation/devicetree/bindings/vendor-prefixes.yaml +++ b/Documentation/devicetree/bindings/vendor-prefixes.yaml @@ -109,6 +109,8 @@ patternProperties: description: Artesyn Embedded Technologies Inc. "^asahi-kasei,.*": description: Asahi Kasei Corp. + "^asc,.*": + description: All Sensors Corporation "^aspeed,.*": description: ASPEED Technology Inc. "^asus,.*": @@ -149,6 +151,8 @@ patternProperties: description: Bosch Sensortec GmbH "^boundary,.*": description: Boundary Devices Inc. + "^broadmobi,.*": + description: Shanghai Broadmobi Communication Technology Co.,Ltd. "^brcm,.*": description: Broadcom Corporation "^buffalo,.*": @@ -157,6 +161,8 @@ patternProperties: description: B&R Industrial Automation GmbH "^bticino,.*": description: Bticino International + "^calaosystems,.*": + description: CALAO Systems SAS "^calxeda,.*": description: Calxeda "^capella,.*": @@ -475,6 +481,8 @@ patternProperties: description: Shenzhen Jesurun Electronics Business Dept. "^jianda,.*": description: Jiandangjing Technology Co., Ltd. + "^kam,.*": + description: Kamstrup A/S "^karo,.*": description: Ka-Ro electronics GmbH "^keithkoep,.*": @@ -513,6 +521,8 @@ patternProperties: description: Lantiq Semiconductor "^lattice,.*": description: Lattice Semiconductor + "^leadtek,.*": + description: Shenzhen Leadtek Technology Co., Ltd. "^leez,.*": description: Leez "^lego,.*": @@ -545,6 +555,8 @@ patternProperties: description: Logic PD, Inc. "^longcheer,.*": description: Longcheer Technology (Shanghai) Co., Ltd. + "^loongson,.*": + description: Loongson Technology Corporation Limited "^lsi,.*": description: LSI Corp. (LSI Logic) "^lwn,.*": @@ -613,6 +625,8 @@ patternProperties: description: Moxa Inc. "^mpl,.*": description: MPL AG + "^mps,.*": + description: Monolithic Power Systems Inc. "^mqmaker,.*": description: mqmaker Inc. "^mscc,.*": @@ -717,6 +731,8 @@ patternProperties: description: Panasonic Corporation "^parade,.*": description: Parade Technologies Inc. + "^parallax,.*": + description: Parallax Inc. "^pda,.*": description: Precision Design Associates, Inc. "^pericom,.*": @@ -823,6 +839,8 @@ patternProperties: description: Sancloud Ltd "^sandisk,.*": description: Sandisk Corporation + "^satoz,.*": + description: Satoz International Co., Ltd "^sbs,.*": description: Smart Battery System "^schindler,.*": @@ -911,8 +929,12 @@ patternProperties: description: Startek "^ste,.*": description: ST-Ericsson + deprecated: true "^stericsson,.*": description: ST-Ericsson + "^st-ericsson,.*": + description: ST-Ericsson + deprecated: true "^summit,.*": description: Summit microelectronics "^sunchip,.*": @@ -1012,6 +1034,8 @@ patternProperties: description: Variscite Ltd. "^via,.*": description: VIA Technologies, Inc. + "^videostrong,.*": + description: Videostrong Technology Co., Ltd. "^virtio,.*": description: Virtual I/O Device Specification, developed by the OASIS consortium "^vishay,.*": @@ -1056,10 +1080,16 @@ patternProperties: description: Extreme Engineering Solutions (X-ES) "^xillybus,.*": description: Xillybus Ltd. + "^xinpeng,.*": + description: Shenzhen Xinpeng Technology Co., Ltd "^xlnx,.*": description: Xilinx "^xunlong,.*": description: Shenzhen Xunlong Software CO.,Limited + "^xylon,.*": + description: Xylon + "^yna,.*": + description: YSH & ATIL "^yones-toptech,.*": description: Yones Toptech Co., Ltd. "^ysoft,.*": diff --git a/Documentation/devicetree/bindings/watchdog/da9062-wdt.txt b/Documentation/devicetree/bindings/watchdog/da9062-wdt.txt index b935b526d2f3..950e4fba8dbc 100644 --- a/Documentation/devicetree/bindings/watchdog/da9062-wdt.txt +++ b/Documentation/devicetree/bindings/watchdog/da9062-wdt.txt @@ -6,6 +6,11 @@ Required properties: "dlg,da9061-watchdog", "dlg,da9062-watchdog" "dlg,da9062-watchdog" +Optional properties: +- dlg,use-sw-pm: Add this property to disable the watchdog during suspend. + Only use this option if you can't use the watchdog automatic suspend + function during a suspend (see register CONTROL_B). + Example: DA9062 pmic0: da9062@58 { diff --git a/Documentation/devicetree/bindings/watchdog/mtk-wdt.txt b/Documentation/devicetree/bindings/watchdog/mtk-wdt.txt index fd380eb28df5..4dd36bd3f1ad 100644 --- a/Documentation/devicetree/bindings/watchdog/mtk-wdt.txt +++ b/Documentation/devicetree/bindings/watchdog/mtk-wdt.txt @@ -4,22 +4,27 @@ Required properties: - compatible should contain: "mediatek,mt2701-wdt", "mediatek,mt6589-wdt": for MT2701 + "mediatek,mt2712-wdt", "mediatek,mt6589-wdt": for MT2712 "mediatek,mt6589-wdt": for MT6589 "mediatek,mt6797-wdt", "mediatek,mt6589-wdt": for MT6797 "mediatek,mt7622-wdt", "mediatek,mt6589-wdt": for MT7622 "mediatek,mt7623-wdt", "mediatek,mt6589-wdt": for MT7623 "mediatek,mt7629-wdt", "mediatek,mt6589-wdt": for MT7629 + "mediatek,mt8183-wdt", "mediatek,mt6589-wdt": for MT8183 "mediatek,mt8516-wdt", "mediatek,mt6589-wdt": for MT8516 - reg : Specifies base physical address and size of the registers. Optional properties: - timeout-sec: contains the watchdog timeout in seconds. +- #reset-cells: Should be 1. Example: -wdt: watchdog@10000000 { - compatible = "mediatek,mt6589-wdt"; - reg = <0x10000000 0x18>; +watchdog: watchdog@10007000 { + compatible = "mediatek,mt8183-wdt", + "mediatek,mt6589-wdt"; + reg = <0 0x10007000 0 0x100>; timeout-sec = <10>; + #reset-cells = <1>; }; diff --git a/Documentation/devicetree/bindings/watchdog/renesas,wdt.txt b/Documentation/devicetree/bindings/watchdog/renesas,wdt.txt index a5bf04dba410..79b3c62f183d 100644 --- a/Documentation/devicetree/bindings/watchdog/renesas,wdt.txt +++ b/Documentation/devicetree/bindings/watchdog/renesas,wdt.txt @@ -19,6 +19,7 @@ Required properties: - "renesas,r8a7794-wdt" (R-Car E2) - "renesas,r8a7795-wdt" (R-Car H3) - "renesas,r8a7796-wdt" (R-Car M3-W) + - "renesas,r8a77961-wdt" (R-Car M3-W+) - "renesas,r8a77965-wdt" (R-Car M3-N) - "renesas,r8a77970-wdt" (R-Car V3M) - "renesas,r8a77990-wdt" (R-Car E3) diff --git a/Documentation/devicetree/bindings/watchdog/st,stm32-iwdg.txt b/Documentation/devicetree/bindings/watchdog/st,stm32-iwdg.txt deleted file mode 100644 index d8f4430b0a13..000000000000 --- a/Documentation/devicetree/bindings/watchdog/st,stm32-iwdg.txt +++ /dev/null @@ -1,26 +0,0 @@ -STM32 Independent WatchDoG (IWDG) ---------------------------------- - -Required properties: -- compatible: Should be either: - - "st,stm32-iwdg" - - "st,stm32mp1-iwdg" -- reg: Physical base address and length of the registers set for the device -- clocks: Reference to the clock entry lsi. Additional pclk clock entry - is required only for st,stm32mp1-iwdg. -- clock-names: Name of the clocks used. - "lsi" for st,stm32-iwdg - "lsi", "pclk" for st,stm32mp1-iwdg - -Optional Properties: -- timeout-sec: Watchdog timeout value in seconds. - -Example: - -iwdg: watchdog@40003000 { - compatible = "st,stm32-iwdg"; - reg = <0x40003000 0x400>; - clocks = <&clk_lsi>; - clock-names = "lsi"; - timeout-sec = <32>; -}; diff --git a/Documentation/devicetree/bindings/watchdog/st,stm32-iwdg.yaml b/Documentation/devicetree/bindings/watchdog/st,stm32-iwdg.yaml new file mode 100644 index 000000000000..a27c504e2e4f --- /dev/null +++ b/Documentation/devicetree/bindings/watchdog/st,stm32-iwdg.yaml @@ -0,0 +1,57 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/watchdog/st,stm32-iwdg.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: STMicroelectronics STM32 Independent WatchDoG (IWDG) bindings + +maintainers: + - Yannick Fertre <yannick.fertre@st.com> + - Christophe Roullier <christophe.roullier@st.com> + +allOf: + - $ref: "watchdog.yaml#" + +properties: + compatible: + enum: + - st,stm32-iwdg + - st,stm32mp1-iwdg + + reg: + maxItems: 1 + + clocks: + items: + - description: Low speed clock + - description: Optional peripheral clock + minItems: 1 + maxItems: 2 + + clock-names: + items: + enum: + - lsi + - pclk + minItems: 1 + maxItems: 2 + +required: + - compatible + - reg + - clocks + - clock-names + +examples: + - | + #include <dt-bindings/clock/stm32mp1-clks.h> + watchdog@5a002000 { + compatible = "st,stm32mp1-iwdg"; + reg = <0x5a002000 0x400>; + clocks = <&rcc IWDG2>, <&rcc CK_LSI>; + clock-names = "pclk", "lsi"; + timeout-sec = <32>; + }; + +... diff --git a/Documentation/devicetree/writing-schema.rst b/Documentation/devicetree/writing-schema.rst index efcd5d21dc2b..7635ab230456 100644 --- a/Documentation/devicetree/writing-schema.rst +++ b/Documentation/devicetree/writing-schema.rst @@ -121,7 +121,13 @@ Several executables (dt-doc-validate, dt-mk-schema, dt-validate) will be installed. Ensure they are in your PATH (~/.local/bin by default). dtc must also be built with YAML output support enabled. This requires that -libyaml and its headers be installed on the host system. +libyaml and its headers be installed on the host system. For some distributions +that involves installing the development package, such as: + +Debian: + apt-get install libyaml-dev +Fedora: + dnf -y install libyaml-devel Running checks ~~~~~~~~~~~~~~ diff --git a/Documentation/doc-guide/contributing.rst b/Documentation/doc-guide/contributing.rst new file mode 100644 index 000000000000..67ee3691f91f --- /dev/null +++ b/Documentation/doc-guide/contributing.rst @@ -0,0 +1,295 @@ +.. SPDX-License-Identifier: GPL-2.0 + +How to help improve kernel documentation +======================================== + +Documentation is an important part of any software-development project. +Good documentation helps to bring new developers in and helps established +developers work more effectively. Without top-quality documentation, a lot +of time is wasted in reverse-engineering the code and making avoidable +mistakes. + +Unfortunately, the kernel's documentation currently falls far short of what +it needs to be to support a project of this size and importance. + +This guide is for contributors who would like to improve that situation. +Kernel documentation improvements can be made by developers at a variety of +skill levels; they are a relatively easy way to learn the kernel process in +general and find a place in the community. The bulk of what follows is the +documentation maintainer's list of tasks that most urgently need to be +done. + +The documentation TODO list +--------------------------- + +There is an endless list of tasks that need to be carried out to get our +documentation to where it should be. This list contains a number of +important items, but is far from exhaustive; if you see a different way to +improve the documentation, please do not hold back! + +Addressing warnings +~~~~~~~~~~~~~~~~~~~ + +The documentation build currently spews out an unbelievable number of +warnings. When you have that many, you might as well have none at all; +people ignore them, and they will never notice when their work adds new +ones. For this reason, eliminating warnings is one of the highest-priority +tasks on the documentation TODO list. The task itself is reasonably +straightforward, but it must be approached in the right way to be +successful. + +Warnings issued by a compiler for C code can often be dismissed as false +positives, leading to patches aimed at simply shutting the compiler up. +Warnings from the documentation build almost always point at a real +problem; making those warnings go away requires understanding the problem +and fixing it at its source. For this reason, patches fixing documentation +warnings should probably not say "fix a warning" in the changelog title; +they should indicate the real problem that has been fixed. + +Another important point is that documentation warnings are often created by +problems in kerneldoc comments in C code. While the documentation +maintainer appreciates being copied on fixes for these warnings, the +documentation tree is often not the right one to actually carry those +fixes; they should go to the maintainer of the subsystem in question. + +For example, in a documentation build I grabbed a pair of warnings nearly +at random:: + + ./drivers/devfreq/devfreq.c:1818: warning: bad line: + - Resource-managed devfreq_register_notifier() + ./drivers/devfreq/devfreq.c:1854: warning: bad line: + - Resource-managed devfreq_unregister_notifier() + +(The lines were split for readability). + +A quick look at the source file named above turned up a couple of kerneldoc +comments that look like this:: + + /** + * devm_devfreq_register_notifier() + - Resource-managed devfreq_register_notifier() + * @dev: The devfreq user device. (parent of devfreq) + * @devfreq: The devfreq object. + * @nb: The notifier block to be unregistered. + * @list: DEVFREQ_TRANSITION_NOTIFIER. + */ + +The problem is the missing "*", which confuses the build system's +simplistic idea of what C comment blocks look like. This problem had been +present since that comment was added in 2016 — a full four years. Fixing +it was a matter of adding the missing asterisks. A quick look at the +history for that file showed what the normal format for subject lines is, +and ``scripts/get_maintainer.pl`` told me who should receive it. The +resulting patch looked like this:: + + [PATCH] PM / devfreq: Fix two malformed kerneldoc comments + + Two kerneldoc comments in devfreq.c fail to adhere to the required format, + resulting in these doc-build warnings: + + ./drivers/devfreq/devfreq.c:1818: warning: bad line: + - Resource-managed devfreq_register_notifier() + ./drivers/devfreq/devfreq.c:1854: warning: bad line: + - Resource-managed devfreq_unregister_notifier() + + Add a couple of missing asterisks and make kerneldoc a little happier. + + Signed-off-by: Jonathan Corbet <corbet@lwn.net> + --- + drivers/devfreq/devfreq.c | 4 ++-- + 1 file changed, 2 insertions(+), 2 deletions(-) + + diff --git a/drivers/devfreq/devfreq.c b/drivers/devfreq/devfreq.c + index 57f6944d65a6..00c9b80b3d33 100644 + --- a/drivers/devfreq/devfreq.c + +++ b/drivers/devfreq/devfreq.c + @@ -1814,7 +1814,7 @@ static void devm_devfreq_notifier_release(struct device *dev, void *res) + + /** + * devm_devfreq_register_notifier() + - - Resource-managed devfreq_register_notifier() + + * - Resource-managed devfreq_register_notifier() + * @dev: The devfreq user device. (parent of devfreq) + * @devfreq: The devfreq object. + * @nb: The notifier block to be unregistered. + @@ -1850,7 +1850,7 @@ EXPORT_SYMBOL(devm_devfreq_register_notifier); + + /** + * devm_devfreq_unregister_notifier() + - - Resource-managed devfreq_unregister_notifier() + + * - Resource-managed devfreq_unregister_notifier() + * @dev: The devfreq user device. (parent of devfreq) + * @devfreq: The devfreq object. + * @nb: The notifier block to be unregistered. + -- + 2.24.1 + +The entire process only took a few minutes. Of course, I then found that +somebody else had fixed it in a separate tree, highlighting another lesson: +always check linux-next to see if a problem has been fixed before you dig +into it. + +Other fixes will take longer, especially those relating to structure +members or function parameters that lack documentation. In such cases, it +is necessary to work out what the role of those members or parameters is +and describe them correctly. Overall, this task gets a little tedious at +times, but it's highly important. If we can actually eliminate warnings +from the documentation build, then we can start expecting developers to +avoid adding new ones. + +Languishing kerneldoc comments +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Developers are encouraged to write kerneldoc comments for their code, but +many of those comments are never pulled into the docs build. That makes +this information harder to find and, for example, makes Sphinx unable to +generate links to that documentation. Adding ``kernel-doc`` directives to +the documentation to bring those comments in can help the community derive +the full value of the work that has gone into creating them. + +The ``scripts/find-unused-docs.sh`` tool can be used to find these +overlooked comments. + +Note that the most value comes from pulling in the documentation for +exported functions and data structures. Many subsystems also have +kerneldoc comments for internal use; those should not be pulled into the +documentation build unless they are placed in a document that is +specifically aimed at developers working within the relevant subsystem. + + +Typo fixes +~~~~~~~~~~ + +Fixing typographical or formatting errors in the documentation is a quick +way to figure out how to create and send patches, and it is a useful +service. I am always willing to accept such patches. That said, once you +have fixed a few, please consider moving on to more advanced tasks, leaving +some typos for the next beginner to address. + +Please note that some things are *not* typos and should not be "fixed": + + - Both American and British English spellings are allowed within the + kernel documentation. There is no need to fix one by replacing it with + the other. + + - The question of whether a period should be followed by one or two spaces + is not to be debated in the context of kernel documentation. Other + areas of rational disagreement, such as the "Oxford comma", are also + off-topic here. + +As with any patch to any project, please consider whether your change is +really making things better. + +Ancient documentation +~~~~~~~~~~~~~~~~~~~~~ + +Some kernel documentation is current, maintained, and useful. Some +documentation is ... not. Dusty, old, and inaccurate documentation can +mislead readers and casts doubt on our documentation as a whole. Anything +that can be done to address such problems is more than welcome. + +Whenever you are working with a document, please consider whether it is +current, whether it needs updating, or whether it should perhaps be removed +altogether. There are a number of warning signs that you can pay attention +to here: + + - References to 2.x kernels + - Pointers to SourceForge repositories + - Nothing but typo fixes in the history for several years + - Discussion of pre-Git workflows + +The best thing to do, of course, would be to bring the documentation +current, adding whatever information is needed. Such work often requires +the cooperation of developers familiar with the subsystem in question, of +course. Developers are often more than willing to cooperate with people +working to improve the documentation when asked nicely, and when their +answers are listened to and acted upon. + +Some documentation is beyond hope; we occasionally find documents that +refer to code that was removed from the kernel long ago, for example. +There is surprising resistance to removing obsolete documentation, but we +should do that anyway. Extra cruft in our documentation helps nobody. + +In cases where there is perhaps some useful information in a badly outdated +document, and you are unable to update it, the best thing to do may be to +add a warning at the beginning. The following text is recommended:: + + .. warning :: + This document is outdated and in need of attention. Please use + this information with caution, and please consider sending patches + to update it. + +That way, at least our long-suffering readers have been warned that the +document may lead them astray. + +Documentation coherency +~~~~~~~~~~~~~~~~~~~~~~~ + +The old-timers around here will remember the Linux books that showed up on +the shelves in the 1990s. They were simply collections of documentation +files scrounged from various locations on the net. The books have (mostly) +improved since then, but the kernel's documentation is still mostly built +on that model. It is thousands of files, almost each of which was written +in isolation from all of the others. We don't have a coherent body of +kernel documentation; we have thousands of individual documents. + +We have been trying to improve the situation through the creation of +a set of "books" that group documentation for specific readers. These +include: + + - :doc:`../admin-guide/index` + - :doc:`../core-api/index` + - :doc:`../driver-api/index` + - :doc:`../userspace-api/index` + +As well as this book on documentation itself. + +Moving documents into the appropriate books is an important task and needs +to continue. There are a couple of challenges associated with this work, +though. Moving documentation files creates short-term pain for the people +who work with those files; they are understandably unenthusiastic about +such changes. Usually the case can be made to move a document once; we +really don't want to keep shifting them around, though. + +Even when all documents are in the right place, though, we have only +managed to turn a big pile into a group of smaller piles. The work of +trying to knit all of those documents together into a single whole has not +yet begun. If you have bright ideas on how we could proceed on that front, +we would be more than happy to hear them. + +Stylesheet improvements +~~~~~~~~~~~~~~~~~~~~~~~ + +With the adoption of Sphinx we have much nicer-looking HTML output than we +once did. But it could still use a lot of improvement; Donald Knuth and +Edward Tufte would be unimpressed. That requires tweaking our stylesheets +to create more typographically sound, accessible, and readable output. + +Be warned: if you take on this task you are heading into classic bikeshed +territory. Expect a lot of opinions and discussion for even relatively +obvious changes. That is, alas, the nature of the world we live in. + +Non-LaTeX PDF build +~~~~~~~~~~~~~~~~~~~ + +This is a decidedly nontrivial task for somebody with a lot of time and +Python skills. The Sphinx toolchain is relatively small and well +contained; it is easy to add to a development system. But building PDF or +EPUB output requires installing LaTeX, which is anything but small or well +contained. That would be a nice thing to eliminate. + +The original hope had been to use the rst2pdf tool (https://rst2pdf.org/) +for PDF generation, but it turned out to not be up to the task. +Development work on rst2pdf seems to have picked up again in recent times, +though, which is a hopeful sign. If a suitably motivated developer were to +work with that project to make rst2pdf work with the kernel documentation +build, the world would be eternally grateful. + +Write more documentation +~~~~~~~~~~~~~~~~~~~~~~~~ + +Naturally, there are massive parts of the kernel that are severely +underdocumented. If you have the knowledge to document a specific kernel +subsystem and the desire to do so, please do not hesitate to do some +writing and contribute the result to the kernel. Untold numbers of kernel +developers and users will thank you. diff --git a/Documentation/doc-guide/index.rst b/Documentation/doc-guide/index.rst index 603f3ff55d5a..7c7d97784626 100644 --- a/Documentation/doc-guide/index.rst +++ b/Documentation/doc-guide/index.rst @@ -10,6 +10,8 @@ How to write kernel documentation sphinx kernel-doc parse-headers + contributing + maintainer-profile .. only:: subproject and html diff --git a/Documentation/doc-guide/maintainer-profile.rst b/Documentation/doc-guide/maintainer-profile.rst new file mode 100644 index 000000000000..5afc0ddba40a --- /dev/null +++ b/Documentation/doc-guide/maintainer-profile.rst @@ -0,0 +1,45 @@ +.. SPDX-License-Identifier: GPL-2.0 + +Documentation subsystem maintainer entry profile +================================================ + +The documentation "subsystem" is the central coordinating point for the +kernel's documentation and associated infrastructure. It covers the +hierarchy under Documentation/ (with the exception of +Documentation/device-tree), various utilities under scripts/ and, at least +some of the time, LICENSES/. + +It's worth noting, though, that the boundaries of this subsystem are rather +fuzzier than normal. Many other subsystem maintainers like to keep control +of portions of Documentation/, and many more freely apply changes there +when it is convenient. Beyond that, much of the kernel's documentation is +found in the source as kerneldoc comments; those are usually (but not +always) maintained by the relevant subsystem maintainer. + +The mailing list for documentation is linux-doc@vger.kernel.org. Patches +should be made against the docs-next tree whenever possible. + +Submit checklist addendum +------------------------- + +When making documentation changes, you should actually build the +documentation and ensure that no new errors or warnings have been +introduced. Generating HTML documents and looking at the result will help +to avoid unsightly misunderstandings about how things will be rendered. + +Key cycle dates +--------------- + +Patches can be sent anytime, but response will be slower than usual during +the merge window. The docs tree tends to close late before the merge +window opens, since the risk of regressions from documentation patches is +low. + +Review cadence +-------------- + +I am the sole maintainer for the documentation subsystem, and I am doing +the work on my own time, so the response to patches will occasionally be +slow. I try to always send out a notification when a patch is merged (or +when I decide that one cannot be). Do not hesitate to send a ping if you +have not heard back within a week of sending a patch. diff --git a/Documentation/driver-api/dmaengine/client.rst b/Documentation/driver-api/dmaengine/client.rst index 45953f171500..e5953e7e4bf4 100644 --- a/Documentation/driver-api/dmaengine/client.rst +++ b/Documentation/driver-api/dmaengine/client.rst @@ -151,6 +151,93 @@ The details of these operations are: Note that callbacks will always be invoked from the DMA engines tasklet, never from interrupt context. +Optional: per descriptor metadata +--------------------------------- + DMAengine provides two ways for metadata support. + + DESC_METADATA_CLIENT + + The metadata buffer is allocated/provided by the client driver and it is + attached to the descriptor. + + .. code-block:: c + + int dmaengine_desc_attach_metadata(struct dma_async_tx_descriptor *desc, + void *data, size_t len); + + DESC_METADATA_ENGINE + + The metadata buffer is allocated/managed by the DMA driver. The client + driver can ask for the pointer, maximum size and the currently used size of + the metadata and can directly update or read it. + + Becasue the DMA driver manages the memory area containing the metadata, + clients must make sure that they do not try to access or get the pointer + after their transfer completion callback has run for the descriptor. + If no completion callback has been defined for the transfer, then the + metadata must not be accessed after issue_pending. + In other words: if the aim is to read back metadata after the transfer is + completed, then the client must use completion callback. + + .. code-block:: c + + void *dmaengine_desc_get_metadata_ptr(struct dma_async_tx_descriptor *desc, + size_t *payload_len, size_t *max_len); + + int dmaengine_desc_set_metadata_len(struct dma_async_tx_descriptor *desc, + size_t payload_len); + + Client drivers can query if a given mode is supported with: + + .. code-block:: c + + bool dmaengine_is_metadata_mode_supported(struct dma_chan *chan, + enum dma_desc_metadata_mode mode); + + Depending on the used mode client drivers must follow different flow. + + DESC_METADATA_CLIENT + + - DMA_MEM_TO_DEV / DEV_MEM_TO_MEM: + 1. prepare the descriptor (dmaengine_prep_*) + construct the metadata in the client's buffer + 2. use dmaengine_desc_attach_metadata() to attach the buffer to the + descriptor + 3. submit the transfer + - DMA_DEV_TO_MEM: + 1. prepare the descriptor (dmaengine_prep_*) + 2. use dmaengine_desc_attach_metadata() to attach the buffer to the + descriptor + 3. submit the transfer + 4. when the transfer is completed, the metadata should be available in the + attached buffer + + DESC_METADATA_ENGINE + + - DMA_MEM_TO_DEV / DEV_MEM_TO_MEM: + 1. prepare the descriptor (dmaengine_prep_*) + 2. use dmaengine_desc_get_metadata_ptr() to get the pointer to the + engine's metadata area + 3. update the metadata at the pointer + 4. use dmaengine_desc_set_metadata_len() to tell the DMA engine the + amount of data the client has placed into the metadata buffer + 5. submit the transfer + - DMA_DEV_TO_MEM: + 1. prepare the descriptor (dmaengine_prep_*) + 2. submit the transfer + 3. on transfer completion, use dmaengine_desc_get_metadata_ptr() to get + the pointer to the engine's metadata area + 4. read out the metadata from the pointer + + .. note:: + + When DESC_METADATA_ENGINE mode is used the metadata area for the descriptor + is no longer valid after the transfer has been completed (valid up to the + point when the completion callback returns if used). + + Mixed use of DESC_METADATA_CLIENT / DESC_METADATA_ENGINE is not allowed, + client drivers must use either of the modes per descriptor. + 4. Submit the transaction Once the descriptor has been prepared and the callback information diff --git a/Documentation/driver-api/dmaengine/provider.rst b/Documentation/driver-api/dmaengine/provider.rst index dfc4486b5743..790a15089f1f 100644 --- a/Documentation/driver-api/dmaengine/provider.rst +++ b/Documentation/driver-api/dmaengine/provider.rst @@ -247,6 +247,54 @@ after each transfer. In case of a ring buffer, they may loop (DMA_CYCLIC). Addresses pointing to a device's register (e.g. a FIFO) are typically fixed. +Per descriptor metadata support +------------------------------- +Some data movement architecture (DMA controller and peripherals) uses metadata +associated with a transaction. The DMA controller role is to transfer the +payload and the metadata alongside. +The metadata itself is not used by the DMA engine itself, but it contains +parameters, keys, vectors, etc for peripheral or from the peripheral. + +The DMAengine framework provides a generic ways to facilitate the metadata for +descriptors. Depending on the architecture the DMA driver can implement either +or both of the methods and it is up to the client driver to choose which one +to use. + +- DESC_METADATA_CLIENT + + The metadata buffer is allocated/provided by the client driver and it is + attached (via the dmaengine_desc_attach_metadata() helper to the descriptor. + + From the DMA driver the following is expected for this mode: + - DMA_MEM_TO_DEV / DEV_MEM_TO_MEM + The data from the provided metadata buffer should be prepared for the DMA + controller to be sent alongside of the payload data. Either by copying to a + hardware descriptor, or highly coupled packet. + - DMA_DEV_TO_MEM + On transfer completion the DMA driver must copy the metadata to the client + provided metadata buffer before notifying the client about the completion. + After the transfer completion, DMA drivers must not touch the metadata + buffer provided by the client. + +- DESC_METADATA_ENGINE + + The metadata buffer is allocated/managed by the DMA driver. The client driver + can ask for the pointer, maximum size and the currently used size of the + metadata and can directly update or read it. dmaengine_desc_get_metadata_ptr() + and dmaengine_desc_set_metadata_len() is provided as helper functions. + + From the DMA driver the following is expected for this mode: + - get_metadata_ptr + Should return a pointer for the metadata buffer, the maximum size of the + metadata buffer and the currently used / valid (if any) bytes in the buffer. + - set_metadata_len + It is called by the clients after it have placed the metadata to the buffer + to let the DMA driver know the number of valid bytes provided. + + Note: since the client will ask for the metadata pointer in the completion + callback (in DMA_DEV_TO_MEM case) the DMA driver must ensure that the + descriptor is not freed up prior the callback is called. + Device operations ----------------- diff --git a/Documentation/driver-api/driver-model/devres.rst b/Documentation/driver-api/driver-model/devres.rst index 13046fcf0a5d..46c13780994c 100644 --- a/Documentation/driver-api/driver-model/devres.rst +++ b/Documentation/driver-api/driver-model/devres.rst @@ -267,6 +267,8 @@ DRM GPIO devm_gpiod_get() + devm_gpiod_get_array() + devm_gpiod_get_array_optional() devm_gpiod_get_index() devm_gpiod_get_index_optional() devm_gpiod_get_optional() @@ -313,7 +315,6 @@ IOMAP devm_ioport_map() devm_ioport_unmap() devm_ioremap() - devm_ioremap_nocache() devm_ioremap_uc() devm_ioremap_wc() devm_ioremap_resource() : checks resource, requests memory region, ioremaps diff --git a/Documentation/driver-api/gpio/driver.rst b/Documentation/driver-api/gpio/driver.rst index 2ff743105927..871922529332 100644 --- a/Documentation/driver-api/gpio/driver.rst +++ b/Documentation/driver-api/gpio/driver.rst @@ -507,11 +507,6 @@ available but we try to move away from this: cascaded irq has to be handled by a threaded interrupt handler. Apart from that it works exactly like the chained irqchip. -- DEPRECATED: gpiochip_set_chained_irqchip(): sets up a chained cascaded irq - handler for a gpio_chip from a parent IRQ and passes the struct gpio_chip* - as handler data. Notice that we pass is as the handler data, since the - irqchip data is likely used by the parent irqchip. - - gpiochip_set_nested_irqchip(): sets up a nested cascaded irq handler for a gpio_chip from a parent IRQ. As the parent IRQ has usually been explicitly requested by the driver, this does very little more than diff --git a/Documentation/driver-api/gpio/drivers-on-gpio.rst b/Documentation/driver-api/gpio/drivers-on-gpio.rst index f3a189320e11..820b403d50f6 100644 --- a/Documentation/driver-api/gpio/drivers-on-gpio.rst +++ b/Documentation/driver-api/gpio/drivers-on-gpio.rst @@ -95,7 +95,7 @@ to emulate MCTRL (modem control) signals CTS/RTS by using two GPIO lines. The MTD NOR flash has add-ons for extra GPIO lines too, though the address bus is usually connected directly to the flash. -Use those instead of talking directly to the GPIOs using sysfs; they integrate -with kernel frameworks better than your userspace code could. Needless to say, -just using the appropriate kernel drivers will simplify and speed up your -embedded hacking in particular by providing ready-made components. +Use those instead of talking directly to the GPIOs from userspace; they +integrate with kernel frameworks better than your userspace code could. +Needless to say, just using the appropriate kernel drivers will simplify and +speed up your embedded hacking in particular by providing ready-made components. diff --git a/Documentation/driver-api/gpio/index.rst b/Documentation/driver-api/gpio/index.rst index 5b61032aa4ea..1d48fe248f05 100644 --- a/Documentation/driver-api/gpio/index.rst +++ b/Documentation/driver-api/gpio/index.rst @@ -8,6 +8,7 @@ Contents: :maxdepth: 2 intro + using-gpio driver consumer board diff --git a/Documentation/driver-api/gpio/using-gpio.rst b/Documentation/driver-api/gpio/using-gpio.rst new file mode 100644 index 000000000000..dda069444032 --- /dev/null +++ b/Documentation/driver-api/gpio/using-gpio.rst @@ -0,0 +1,50 @@ +========================= +Using GPIO Lines in Linux +========================= + +The Linux kernel exists to abstract and present hardware to users. GPIO lines +as such are normally not user facing abstractions. The most obvious, natural +and preferred way to use GPIO lines is to let kernel hardware drivers deal +with them. + +For examples of already existing generic drivers that will also be good +examples for any other kernel drivers you want to author, refer to +:doc:`drivers-on-gpio` + +For any kind of mass produced system you want to support, such as servers, +laptops, phones, tablets, routers, and any consumer or office or business goods +using appropriate kernel drivers is paramount. Submit your code for inclusion +in the upstream Linux kernel when you feel it is mature enough and you will get +help to refine it, see :doc:`../../process/submitting-patches`. + +In Linux GPIO lines also have a userspace ABI. + +The userspace ABI is intended for one-off deployments. Examples are prototypes, +factory lines, maker community projects, workshop specimen, production tools, +industrial automation, PLC-type use cases, door controllers, in short a piece +of specialized equipment that is not produced by the numbers, requiring +operators to have a deep knowledge of the equipment and knows about the +software-hardware interface to be set up. They should not have a natural fit +to any existing kernel subsystem and not be a good fit for an operating system, +because of not being reusable or abstract enough, or involving a lot of non +computer hardware related policy. + +Applications that have a good reason to use the industrial I/O (IIO) subsystem +from userspace will likely be a good fit for using GPIO lines from userspace as +well. + +Do not under any circumstances abuse the GPIO userspace ABI to cut corners in +any product development projects. If you use it for prototyping, then do not +productify the prototype: rewrite it using proper kernel drivers. Do not under +any circumstances deploy any uniform products using GPIO from userspace. + +The userspace ABI is a character device for each GPIO hardware unit (GPIO chip). +These devices will appear on the system as ``/dev/gpiochip0`` thru +``/dev/gpiochipN``. Examples of how to directly use the userspace ABI can be +found in the kernel tree ``tools/gpio`` subdirectory. + +For structured and managed applications, we recommend that you make use of the +libgpiod_ library. This provides helper abstractions, command line utlities +and arbitration for multiple simultaneous consumers on the same GPIO chip. + +.. _libgpiod: https://git.kernel.org/pub/scm/libs/libgpiod/libgpiod.git/ diff --git a/Documentation/driver-api/interconnect.rst b/Documentation/driver-api/interconnect.rst index cdeb5825f314..5ed4f57a6bac 100644 --- a/Documentation/driver-api/interconnect.rst +++ b/Documentation/driver-api/interconnect.rst @@ -91,3 +91,25 @@ Interconnect consumers are the clients which use the interconnect APIs to get paths between endpoints and set their bandwidth/latency/QoS requirements for these interconnect paths. These interfaces are not currently documented. + +Interconnect debugfs interfaces +------------------------------- + +Like several other subsystems interconnect will create some files for debugging +and introspection. Files in debugfs are not considered ABI so application +software shouldn't rely on format details change between kernel versions. + +``/sys/kernel/debug/interconnect/interconnect_summary``: + +Show all interconnect nodes in the system with their aggregated bandwidth +request. Indented under each node show bandwidth requests from each device. + +``/sys/kernel/debug/interconnect/interconnect_graph``: + +Show the interconnect graph in the graphviz dot format. It shows all +interconnect nodes and links in the system and groups together nodes from the +same provider as subgraphs. The format is human-readable and can also be piped +through dot to generate diagrams in many graphical formats:: + + $ cat /sys/kernel/debug/interconnect/interconnect_graph | \ + dot -Tsvg > interconnect_graph.svg diff --git a/Documentation/driver-api/ipmb.rst b/Documentation/driver-api/ipmb.rst index 3ec3baed84c4..209c49e05116 100644 --- a/Documentation/driver-api/ipmb.rst +++ b/Documentation/driver-api/ipmb.rst @@ -71,9 +71,13 @@ b) Example for device tree:: ipmb@10 { compatible = "ipmb-dev"; reg = <0x10>; + i2c-protocol; }; }; +If xmit of data to be done using raw i2c block vs smbus +then "i2c-protocol" needs to be defined as above. + 2) Manually from Linux:: modprobe ipmb-dev-int diff --git a/Documentation/driver-api/thermal/cpu-idle-cooling.rst b/Documentation/driver-api/thermal/cpu-idle-cooling.rst new file mode 100644 index 000000000000..9f0016ee4cfb --- /dev/null +++ b/Documentation/driver-api/thermal/cpu-idle-cooling.rst @@ -0,0 +1,194 @@ + +Situation: +---------- + +Under certain circumstances a SoC can reach a critical temperature +limit and is unable to stabilize the temperature around a temperature +control. When the SoC has to stabilize the temperature, the kernel can +act on a cooling device to mitigate the dissipated power. When the +critical temperature is reached, a decision must be taken to reduce +the temperature, that, in turn impacts performance. + +Another situation is when the silicon temperature continues to +increase even after the dynamic leakage is reduced to its minimum by +clock gating the component. This runaway phenomenon can continue due +to the static leakage. The only solution is to power down the +component, thus dropping the dynamic and static leakage that will +allow the component to cool down. + +Last but not least, the system can ask for a specific power budget but +because of the OPP density, we can only choose an OPP with a power +budget lower than the requested one and under-utilize the CPU, thus +losing performance. In other words, one OPP under-utilizes the CPU +with a power less than the requested power budget and the next OPP +exceeds the power budget. An intermediate OPP could have been used if +it were present. + +Solutions: +---------- + +If we can remove the static and the dynamic leakage for a specific +duration in a controlled period, the SoC temperature will +decrease. Acting on the idle state duration or the idle cycle +injection period, we can mitigate the temperature by modulating the +power budget. + +The Operating Performance Point (OPP) density has a great influence on +the control precision of cpufreq, however different vendors have a +plethora of OPP density, and some have large power gap between OPPs, +that will result in loss of performance during thermal control and +loss of power in other scenarios. + +At a specific OPP, we can assume that injecting idle cycle on all CPUs +belong to the same cluster, with a duration greater than the cluster +idle state target residency, we lead to dropping the static and the +dynamic leakage for this period (modulo the energy needed to enter +this state). So the sustainable power with idle cycles has a linear +relation with the OPP’s sustainable power and can be computed with a +coefficient similar to: + + Power(IdleCycle) = Coef x Power(OPP) + +Idle Injection: +--------------- + +The base concept of the idle injection is to force the CPU to go to an +idle state for a specified time each control cycle, it provides +another way to control CPU power and heat in addition to +cpufreq. Ideally, if all CPUs belonging to the same cluster, inject +their idle cycles synchronously, the cluster can reach its power down +state with a minimum power consumption and reduce the static leakage +to almost zero. However, these idle cycles injection will add extra +latencies as the CPUs will have to wakeup from a deep sleep state. + +We use a fixed duration of idle injection that gives an acceptable +performance penalty and a fixed latency. Mitigation can be increased +or decreased by modulating the duty cycle of the idle injection. + +:: + + ^ + | + | + |------- ------- + |_______|_______________________|_______|___________ + + <------> + idle <----------------------> + running + + <-----------------------------> + duty cycle 25% + + +The implementation of the cooling device bases the number of states on +the duty cycle percentage. When no mitigation is happening the cooling +device state is zero, meaning the duty cycle is 0%. + +When the mitigation begins, depending on the governor's policy, a +starting state is selected. With a fixed idle duration and the duty +cycle (aka the cooling device state), the running duration can be +computed. + +The governor will change the cooling device state thus the duty cycle +and this variation will modulate the cooling effect. + +:: + + ^ + | + | + |------- ------- + |_______|_______________|_______|___________ + + <------> + idle <--------------> + running + + <-----------------------------> + duty cycle 33% + + + ^ + | + | + |------- ------- + |_______|_______|_______|___________ + + <------> + idle <------> + running + + <-------------> + duty cycle 50% + +The idle injection duration value must comply with the constraints: + +- It is less than or equal to the latency we tolerate when the + mitigation begins. It is platform dependent and will depend on the + user experience, reactivity vs performance trade off we want. This + value should be specified. + +- It is greater than the idle state’s target residency we want to go + for thermal mitigation, otherwise we end up consuming more energy. + +Power considerations +-------------------- + +When we reach the thermal trip point, we have to sustain a specified +power for a specific temperature but at this time we consume: + + Power = Capacitance x Voltage^2 x Frequency x Utilisation + +... which is more than the sustainable power (or there is something +wrong in the system setup). The ‘Capacitance’ and ‘Utilisation’ are a +fixed value, ‘Voltage’ and the ‘Frequency’ are fixed artificially +because we don’t want to change the OPP. We can group the +‘Capacitance’ and the ‘Utilisation’ into a single term which is the +‘Dynamic Power Coefficient (Cdyn)’ Simplifying the above, we have: + + Pdyn = Cdyn x Voltage^2 x Frequency + +The power allocator governor will ask us somehow to reduce our power +in order to target the sustainable power defined in the device +tree. So with the idle injection mechanism, we want an average power +(Ptarget) resulting in an amount of time running at full power on a +specific OPP and idle another amount of time. That could be put in a +equation: + + P(opp)target = ((Trunning x (P(opp)running) + (Tidle x P(opp)idle)) / + (Trunning + Tidle) + + ... + + Tidle = Trunning x ((P(opp)running / P(opp)target) - 1) + +At this point if we know the running period for the CPU, that gives us +the idle injection we need. Alternatively if we have the idle +injection duration, we can compute the running duration with: + + Trunning = Tidle / ((P(opp)running / P(opp)target) - 1) + +Practically, if the running power is less than the targeted power, we +end up with a negative time value, so obviously the equation usage is +bound to a power reduction, hence a higher OPP is needed to have the +running power greater than the targeted power. + +However, in this demonstration we ignore three aspects: + + * The static leakage is not defined here, we can introduce it in the + equation but assuming it will be zero most of the time as it is + difficult to get the values from the SoC vendors + + * The idle state wake up latency (or entry + exit latency) is not + taken into account, it must be added in the equation in order to + rigorously compute the idle injection + + * The injected idle duration must be greater than the idle state + target residency, otherwise we end up consuming more energy and + potentially invert the mitigation effect + +So the final equation is: + + Trunning = (Tidle - Twakeup ) x + (((P(opp)dyn + P(opp)static ) - P(opp)target) / P(opp)target ) diff --git a/Documentation/driver-api/thermal/exynos_thermal.rst b/Documentation/driver-api/thermal/exynos_thermal.rst index 5bd556566c70..764df4ab584d 100644 --- a/Documentation/driver-api/thermal/exynos_thermal.rst +++ b/Documentation/driver-api/thermal/exynos_thermal.rst @@ -4,7 +4,7 @@ Kernel driver exynos_tmu Supported chips: -* ARM SAMSUNG EXYNOS4, EXYNOS5 series of SoC +* ARM Samsung Exynos4, Exynos5 series of SoC Datasheet: Not publicly available @@ -14,7 +14,7 @@ Authors: Amit Daniel <amit.daniel@samsung.com> TMU controller Description: --------------------------- -This driver allows to read temperature inside SAMSUNG EXYNOS4/5 series of SoC. +This driver allows to read temperature inside Samsung Exynos4/5 series of SoC. The chip only exposes the measured 8-bit temperature code value through a register. @@ -43,7 +43,7 @@ The three equations are: Trimming info for 85 degree Celsius (stored at TRIMINFO register) Temperature code measured at 85 degree Celsius which is unchanged -TMU(Thermal Management Unit) in EXYNOS4/5 generates interrupt +TMU(Thermal Management Unit) in Exynos4/5 generates interrupt when temperature exceeds pre-defined levels. The maximum number of configurable threshold is five. The threshold levels are defined as follows:: @@ -67,7 +67,7 @@ TMU driver description: The exynos thermal driver is structured as:: Kernel Core thermal framework - (thermal_core.c, step_wise.c, cpu_cooling.c) + (thermal_core.c, step_wise.c, cpufreq_cooling.c) ^ | | diff --git a/Documentation/fb/fbcon.rst b/Documentation/fb/fbcon.rst index ebca41785abe..e57a3d1d085a 100644 --- a/Documentation/fb/fbcon.rst +++ b/Documentation/fb/fbcon.rst @@ -127,7 +127,7 @@ C. Boot options is typically located on the same video card. Thus, the consoles that are controlled by the VGA console will be garbled. -4. fbcon=rotate:<n> +5. fbcon=rotate:<n> This option changes the orientation angle of the console display. The value 'n' accepts the following: @@ -152,21 +152,21 @@ C. Boot options Actually, the underlying fb driver is totally ignorant of console rotation. -5. fbcon=margin:<color> +6. fbcon=margin:<color> This option specifies the color of the margins. The margins are the leftover area at the right and the bottom of the screen that are not used by text. By default, this area will be black. The 'color' value is an integer number that depends on the framebuffer driver being used. -6. fbcon=nodefer +7. fbcon=nodefer If the kernel is compiled with deferred fbcon takeover support, normally the framebuffer contents, left in place by the firmware/bootloader, will be preserved until there actually is some text is output to the console. This option causes fbcon to bind immediately to the fbdev device. -7. fbcon=logo-pos:<location> +8. fbcon=logo-pos:<location> The only possible 'location' is 'center' (without quotes), and when given, the bootup logo is moved from the default top-left corner @@ -174,6 +174,11 @@ C. Boot options displayed due to multiple CPUs, the collected line of logos is moved as a whole. +9. fbcon=logo-count:<n> + + The value 'n' overrides the number of bootup logos. 0 disables the + logo, and -1 gives the default which is the number of online CPUs. + C. Attaching, Detaching and Unloading Before going on to how to attach, detach and unload the framebuffer console, an diff --git a/Documentation/fb/modedb.rst b/Documentation/fb/modedb.rst index 9c4e3fd39e6d..624d08fd2856 100644 --- a/Documentation/fb/modedb.rst +++ b/Documentation/fb/modedb.rst @@ -65,6 +65,9 @@ Valid options are:: - reflect_y (boolean): Perform an axial symmetry on the Y axis - rotate (integer): Rotate the initial framebuffer by x degrees. Valid values are 0, 90, 180 and 270. + - panel_orientation, one of "normal", "upside_down", "left_side_up", or + "right_side_up". For KMS drivers only, this sets the "panel orientation" + property on the kms connector as hint for kms users. ----------------------------------------------------------------------------- diff --git a/Documentation/features/core/jump-labels/arch-support.txt b/Documentation/features/core/jump-labels/arch-support.txt index cae7be2f7725..632a1c7aefa2 100644 --- a/Documentation/features/core/jump-labels/arch-support.txt +++ b/Documentation/features/core/jump-labels/arch-support.txt @@ -7,7 +7,7 @@ | arch |status| ----------------------- | alpha: | TODO | - | arc: | TODO | + | arc: | ok | | arm: | ok | | arm64: | ok | | c6x: | TODO | diff --git a/Documentation/features/debug/kprobes-on-ftrace/arch-support.txt b/Documentation/features/debug/kprobes-on-ftrace/arch-support.txt index 4fae0464ddff..32b297295fff 100644 --- a/Documentation/features/debug/kprobes-on-ftrace/arch-support.txt +++ b/Documentation/features/debug/kprobes-on-ftrace/arch-support.txt @@ -24,7 +24,7 @@ | parisc: | ok | | powerpc: | ok | | riscv: | TODO | - | s390: | TODO | + | s390: | ok | | sh: | TODO | | sparc: | TODO | | um: | TODO | diff --git a/Documentation/filesystems/adfs.txt b/Documentation/filesystems/adfs.txt index 5949766353f7..0baa8e8c1fc1 100644 --- a/Documentation/filesystems/adfs.txt +++ b/Documentation/filesystems/adfs.txt @@ -1,3 +1,27 @@ +Filesystems supported by ADFS +----------------------------- + +The ADFS module supports the following Filecore formats which have: + +- new maps +- new directories or big directories + +In terms of the named formats, this means we support: + +- E and E+, with or without boot block +- F and F+ + +We fully support reading files from these filesystems, and writing to +existing files within their existing allocation. Essentially, we do +not support changing any of the filesystem metadata. + +This is intended to support loopback mounted Linux native filesystems +on a RISC OS Filecore filesystem, but will allow the data within files +to be changed. + +If write support (ADFS_FS_RW) is configured, we allow rudimentary +directory updates, specifically updating the access mode and timestamp. + Mount options for ADFS ---------------------- diff --git a/Documentation/filesystems/automount-support.txt b/Documentation/filesystems/automount-support.txt index b0afd3d55eaf..7d9f82607562 100644 --- a/Documentation/filesystems/automount-support.txt +++ b/Documentation/filesystems/automount-support.txt @@ -9,7 +9,7 @@ also be requested by userspace. IN-KERNEL AUTOMOUNTING ====================== -See section "Mount Traps" of Documentation/filesystems/autofs.txt +See section "Mount Traps" of Documentation/filesystems/autofs.rst Then from userspace, you can just do something like: diff --git a/Documentation/filesystems/f2fs.txt b/Documentation/filesystems/f2fs.txt index 3135b80df6da..4eb3e2ddd00e 100644 --- a/Documentation/filesystems/f2fs.txt +++ b/Documentation/filesystems/f2fs.txt @@ -235,6 +235,17 @@ checkpoint=%s[:%u[%]] Set to "disable" to turn off checkpointing. Set to "en hide up to all remaining free space. The actual space that would be unusable can be viewed at /sys/fs/f2fs/<disk>/unusable This space is reclaimed once checkpoint=enable. +compress_algorithm=%s Control compress algorithm, currently f2fs supports "lzo" + and "lz4" algorithm. +compress_log_size=%u Support configuring compress cluster size, the size will + be 4KB * (1 << %u), 16KB is minimum size, also it's + default size. +compress_extension=%s Support adding specified extension, so that f2fs can enable + compression on those corresponding files, e.g. if all files + with '.ext' has high compression rate, we can set the '.ext' + on compression extension list and enable compression on + these file by default rather than to enable it via ioctl. + For other files, we can still enable compression via ioctl. ================================================================================ DEBUGFS ENTRIES @@ -259,170 +270,6 @@ The files in each per-device directory are shown in table below. Files in /sys/fs/f2fs/<devname> (see also Documentation/ABI/testing/sysfs-fs-f2fs) -.............................................................................. - File Content - - gc_urgent_sleep_time This parameter controls sleep time for gc_urgent. - 500 ms is set by default. See above gc_urgent. - - gc_min_sleep_time This tuning parameter controls the minimum sleep - time for the garbage collection thread. Time is - in milliseconds. - - gc_max_sleep_time This tuning parameter controls the maximum sleep - time for the garbage collection thread. Time is - in milliseconds. - - gc_no_gc_sleep_time This tuning parameter controls the default sleep - time for the garbage collection thread. Time is - in milliseconds. - - gc_idle This parameter controls the selection of victim - 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. - - gc_urgent This parameter controls triggering background GCs - urgently or not. Setting gc_urgent = 0 [default] - makes back to default behavior, while if it is set - to 1, background thread starts to do GC by given - gc_urgent_sleep_time interval. - - reclaim_segments 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. - - main_blkaddr This value gives the first block address of - MAIN area in the partition. - - max_small_discards This parameter controls the number of discard - commands that consist small blocks less than 2MB. - The candidates to be discarded are cached until - checkpoint is triggered, and issued during the - checkpoint. By default, it is disabled with 0. - - discard_granularity This parameter controls the granularity of discard - command size. It will issue discard commands iif - the size is larger than given granularity. Its - unit size is 4KB, and 4 (=16KB) is set by default. - The maximum value is 128 (=512KB). - - reserved_blocks This parameter indicates the number of blocks that - f2fs reserves internally for root. - - batched_trim_sections This parameter controls the number of sections - to be trimmed out in batch mode when FITRIM - conducts. 32 sections is set by default. - - ipu_policy This parameter controls the policy of in-place - updates in f2fs. There are five policies: - 0x01: F2FS_IPU_FORCE, 0x02: F2FS_IPU_SSR, - 0x04: F2FS_IPU_UTIL, 0x08: F2FS_IPU_SSR_UTIL, - 0x10: F2FS_IPU_FSYNC. - - min_ipu_util This parameter controls the threshold to trigger - in-place-updates. The number indicates percentage - of the filesystem utilization, and used by - F2FS_IPU_UTIL and F2FS_IPU_SSR_UTIL policies. - - min_fsync_blocks This parameter controls the threshold to trigger - in-place-updates when F2FS_IPU_FSYNC mode is set. - The number indicates the number of dirty pages - when fsync needs to flush on its call path. If - the number is less than this value, it triggers - in-place-updates. - - min_seq_blocks This parameter controls the threshold to serialize - write IOs issued by multiple threads in parallel. - - min_hot_blocks This parameter controls the threshold to allocate - a hot data log for pending data blocks to write. - - min_ssr_sections This parameter adds the threshold when deciding - SSR block allocation. If this is large, SSR mode - will be enabled early. - - ram_thresh This parameter controls the memory footprint used - by free nids and cached nat entries. By default, - 1 is set, which indicates 10 MB / 1 GB RAM. - - ra_nid_pages When building free nids, F2FS reads NAT blocks - ahead for speed up. Default is 0. - - dirty_nats_ratio Given dirty ratio of cached nat entries, F2FS - determines flushing them in background. - - max_victim_search This parameter 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. - - migration_granularity For large-sized sections, F2FS can stop GC given - this granularity instead of reclaiming entire - section. - - dir_level This parameter controls the directory level to - support 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. - - cp_interval F2FS tries to do checkpoint periodically, 60 secs - by default. - - idle_interval F2FS detects system is idle, if there's no F2FS - operations during given interval, 5 secs by - default. - - discard_idle_interval F2FS detects the discard thread is idle, given - time interval. Default is 5 secs. - - gc_idle_interval F2FS detects the GC thread is idle, given time - interval. Default is 5 secs. - - umount_discard_timeout When unmounting the disk, F2FS waits for finishing - queued discard commands which can take huge time. - This gives time out for it, 5 secs by default. - - iostat_enable This controls to enable/disable iostat in F2FS. - - readdir_ra This enables/disabled readahead of inode blocks - in readdir, and default is enabled. - - gc_pin_file_thresh 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. - - extension_list This enables to change extension_list for hot/cold - files in runtime. - - inject_rate This controls injection rate of arbitrary faults. - - inject_type This controls injection type of arbitrary faults. - - dirty_segments This shows # of dirty segments. - - lifetime_write_kbytes This shows # of data written to the disk. - - features This shows current features enabled on F2FS. - - current_reserved_blocks This shows # of blocks currently reserved. - - unusable If checkpoint=disable, this shows the number of - blocks that are unusable. - If checkpoint=enable it shows the number of blocks - that would be unusable if checkpoint=disable were - to be set. - -encoding This shows the encoding used for casefolding. - If casefolding is not enabled, returns (none) ================================================================================ USAGE @@ -840,3 +687,44 @@ zero or random data, which is useful to the below scenario where: 4. address = fibmap(fd, offset) 5. open(blkdev) 6. write(blkdev, address) + +Compression implementation +-------------------------- + +- New term named cluster is defined as basic unit of compression, file can +be divided into multiple clusters logically. One cluster includes 4 << n +(n >= 0) logical pages, compression size is also cluster size, each of +cluster can be compressed or not. + +- In cluster metadata layout, one special block address is used to indicate +cluster is compressed one or normal one, for compressed cluster, following +metadata maps cluster to [1, 4 << n - 1] physical blocks, in where f2fs +stores data including compress header and compressed data. + +- In order to eliminate write amplification during overwrite, F2FS only +support compression on write-once file, data can be compressed only when +all logical blocks in file are valid and cluster compress ratio is lower +than specified threshold. + +- To enable compression on regular inode, there are three ways: +* chattr +c file +* chattr +c dir; touch dir/file +* mount w/ -o compress_extension=ext; touch file.ext + +Compress metadata layout: + [Dnode Structure] + +-----------------------------------------------+ + | cluster 1 | cluster 2 | ......... | cluster N | + +-----------------------------------------------+ + . . . . + . . . . + . Compressed Cluster . . Normal Cluster . ++----------+---------+---------+---------+ +---------+---------+---------+---------+ +|compr flag| block 1 | block 2 | block 3 | | block 1 | block 2 | block 3 | block 4 | ++----------+---------+---------+---------+ +---------+---------+---------+---------+ + . . + . . + . . + +-------------+-------------+----------+----------------------------+ + | data length | data chksum | reserved | compressed data | + +-------------+-------------+----------+----------------------------+ diff --git a/Documentation/filesystems/fscrypt.rst b/Documentation/filesystems/fscrypt.rst index 68c2bc8275cf..bd9932344804 100644 --- a/Documentation/filesystems/fscrypt.rst +++ b/Documentation/filesystems/fscrypt.rst @@ -234,8 +234,8 @@ HKDF is more flexible, is nonreversible, and evenly distributes entropy from the master key. HKDF is also standardized and widely used by other software, whereas the AES-128-ECB based KDF is ad-hoc. -Per-file keys -------------- +Per-file encryption keys +------------------------ Since each master key can protect many files, it is necessary to "tweak" the encryption of each file so that the same plaintext in two @@ -268,9 +268,9 @@ is greater than that of an AES-256-XTS key. Therefore, to improve performance and save memory, for Adiantum a "direct key" configuration is supported. When the user has enabled this by setting FSCRYPT_POLICY_FLAG_DIRECT_KEY in the fscrypt policy, -per-file keys are not used. Instead, whenever any data (contents or -filenames) is encrypted, the file's 16-byte nonce is included in the -IV. Moreover: +per-file encryption keys are not used. Instead, whenever any data +(contents or filenames) is encrypted, the file's 16-byte nonce is +included in the IV. Moreover: - For v1 encryption policies, the encryption is done directly with the master key. Because of this, users **must not** use the same master @@ -302,6 +302,16 @@ For master keys used for v2 encryption policies, a unique 16-byte "key identifier" is also derived using the KDF. This value is stored in the clear, since it is needed to reliably identify the key itself. +Dirhash keys +------------ + +For directories that are indexed using a secret-keyed dirhash over the +plaintext filenames, the KDF is also used to derive a 128-bit +SipHash-2-4 key per directory in order to hash filenames. This works +just like deriving a per-file encryption key, except that a different +KDF context is used. Currently, only casefolded ("case-insensitive") +encrypted directories use this style of hashing. + Encryption modes and usage ========================== @@ -325,11 +335,11 @@ used. Adiantum is a (primarily) stream cipher-based mode that is fast even on CPUs without dedicated crypto instructions. It's also a true wide-block mode, unlike XTS. It can also eliminate the need to derive -per-file keys. However, it depends on the security of two primitives, -XChaCha12 and AES-256, rather than just one. See the paper -"Adiantum: length-preserving encryption for entry-level processors" -(https://eprint.iacr.org/2018/720.pdf) for more details. To use -Adiantum, CONFIG_CRYPTO_ADIANTUM must be enabled. Also, fast +per-file encryption keys. However, it depends on the security of two +primitives, XChaCha12 and AES-256, rather than just one. See the +paper "Adiantum: length-preserving encryption for entry-level +processors" (https://eprint.iacr.org/2018/720.pdf) for more details. +To use Adiantum, CONFIG_CRYPTO_ADIANTUM must be enabled. Also, fast implementations of ChaCha and NHPoly1305 should be enabled, e.g. CONFIG_CRYPTO_CHACHA20_NEON and CONFIG_CRYPTO_NHPOLY1305_NEON for ARM. @@ -513,7 +523,9 @@ FS_IOC_SET_ENCRYPTION_POLICY can fail with the following errors: - ``EEXIST``: the file is already encrypted with an encryption policy different from the one specified - ``EINVAL``: an invalid encryption policy was specified (invalid - version, mode(s), or flags; or reserved bits were set) + version, mode(s), or flags; or reserved bits were set); or a v1 + encryption policy was specified but the directory has the casefold + flag enabled (casefolding is incompatible with v1 policies). - ``ENOKEY``: a v2 encryption policy was specified, but the key with the specified ``master_key_identifier`` has not been added, nor does the process have the CAP_FOWNER capability in the initial user @@ -638,7 +650,8 @@ follows:: struct fscrypt_add_key_arg { struct fscrypt_key_specifier key_spec; __u32 raw_size; - __u32 __reserved[9]; + __u32 key_id; + __u32 __reserved[8]; __u8 raw[]; }; @@ -655,6 +668,12 @@ follows:: } u; }; + struct fscrypt_provisioning_key_payload { + __u32 type; + __u32 __reserved; + __u8 raw[]; + }; + :c:type:`struct fscrypt_add_key_arg` must be zeroed, then initialized as follows: @@ -677,9 +696,26 @@ as follows: ``Documentation/security/keys/core.rst``). - ``raw_size`` must be the size of the ``raw`` key provided, in bytes. + Alternatively, if ``key_id`` is nonzero, this field must be 0, since + in that case the size is implied by the specified Linux keyring key. + +- ``key_id`` is 0 if the raw key is given directly in the ``raw`` + field. Otherwise ``key_id`` is the ID of a Linux keyring key of + type "fscrypt-provisioning" whose payload is a :c:type:`struct + fscrypt_provisioning_key_payload` whose ``raw`` field contains the + raw key and whose ``type`` field matches ``key_spec.type``. Since + ``raw`` is variable-length, the total size of this key's payload + must be ``sizeof(struct fscrypt_provisioning_key_payload)`` plus the + raw key size. The process must have Search permission on this key. + + Most users should leave this 0 and specify the raw key directly. + The support for specifying a Linux keyring key is intended mainly to + allow re-adding keys after a filesystem is unmounted and re-mounted, + without having to store the raw keys in userspace memory. - ``raw`` is a variable-length field which must contain the actual - key, ``raw_size`` bytes long. + key, ``raw_size`` bytes long. Alternatively, if ``key_id`` is + nonzero, then this field is unused. For v2 policy keys, the kernel keeps track of which user (identified by effective user ID) added the key, and only allows the key to be @@ -701,11 +737,16 @@ FS_IOC_ADD_ENCRYPTION_KEY can fail with the following errors: - ``EACCES``: FSCRYPT_KEY_SPEC_TYPE_DESCRIPTOR was specified, but the caller does not have the CAP_SYS_ADMIN capability in the initial - user namespace + user namespace; or the raw key was specified by Linux key ID but the + process lacks Search permission on the key. - ``EDQUOT``: the key quota for this user would be exceeded by adding the key - ``EINVAL``: invalid key size or key specifier type, or reserved bits were set +- ``EKEYREJECTED``: the raw key was specified by Linux key ID, but the + key has the wrong type +- ``ENOKEY``: the raw key was specified by Linux key ID, but no key + exists with that ID - ``ENOTTY``: this type of filesystem does not implement encryption - ``EOPNOTSUPP``: the kernel was not configured with encryption support for this filesystem, or the filesystem superblock has not @@ -975,9 +1016,9 @@ astute users may notice some differences in behavior: - Direct I/O is not supported on encrypted files. Attempts to use direct I/O on such files will fall back to buffered I/O. -- The fallocate operations FALLOC_FL_COLLAPSE_RANGE, - FALLOC_FL_INSERT_RANGE, and FALLOC_FL_ZERO_RANGE are not supported - on encrypted files and will fail with EOPNOTSUPP. +- The fallocate operations FALLOC_FL_COLLAPSE_RANGE and + FALLOC_FL_INSERT_RANGE are not supported on encrypted files and will + fail with EOPNOTSUPP. - Online defragmentation of encrypted files is not supported. The EXT4_IOC_MOVE_EXT and F2FS_IOC_MOVE_RANGE ioctls will fail with @@ -1108,8 +1149,8 @@ The context structs contain the same information as the corresponding policy structs (see `Setting an encryption policy`_), except that the context structs also contain a nonce. The nonce is randomly generated by the kernel and is used as KDF input or as a tweak to cause -different files to be encrypted differently; see `Per-file keys`_ and -`DIRECT_KEY policies`_. +different files to be encrypted differently; see `Per-file encryption +keys`_ and `DIRECT_KEY policies`_. Data path changes ----------------- @@ -1161,7 +1202,7 @@ filesystem-specific hash(es) needed for directory lookups. This allows the filesystem to still, with a high degree of confidence, map the filename given in ->lookup() back to a particular directory entry that was previously listed by readdir(). See :c:type:`struct -fscrypt_digested_name` in the source for more details. +fscrypt_nokey_name` in the source for more details. Note that the precise way that filenames are presented to userspace without the key is subject to change in the future. It is only meant diff --git a/Documentation/filesystems/fuse.txt b/Documentation/filesystems/fuse.rst index 13af4a49e7db..8e455065ce9e 100644 --- a/Documentation/filesystems/fuse.txt +++ b/Documentation/filesystems/fuse.rst @@ -1,41 +1,40 @@ +.. SPDX-License-Identifier: GPL-2.0 +============== +FUSE +============== + Definitions -~~~~~~~~~~~ +=========== Userspace filesystem: - A filesystem in which data and metadata are provided by an ordinary userspace process. The filesystem can be accessed normally through the kernel interface. Filesystem daemon: - The process(es) providing the data and metadata of the filesystem. Non-privileged mount (or user mount): - A userspace filesystem mounted by a non-privileged (non-root) user. The filesystem daemon is running with the privileges of the mounting user. NOTE: this is not the same as mounts allowed with the "user" option in /etc/fstab, which is not discussed here. Filesystem connection: - A connection between the filesystem daemon and the kernel. The connection exists until either the daemon dies, or the filesystem is umounted. Note that detaching (or lazy umounting) the filesystem - does _not_ break the connection, in this case it will exist until + does *not* break the connection, in this case it will exist until the last reference to the filesystem is released. Mount owner: - The user who does the mounting. User: - The user who is performing filesystem operations. What is FUSE? -~~~~~~~~~~~~~ +============= FUSE is a userspace filesystem framework. It consists of a kernel module (fuse.ko), a userspace library (libfuse.*) and a mount utility @@ -46,50 +45,41 @@ non-privileged mounts. This opens up new possibilities for the use of filesystems. A good example is sshfs: a secure network filesystem using the sftp protocol. -The userspace library and utilities are available from the FUSE -homepage: - - http://fuse.sourceforge.net/ +The userspace library and utilities are available from the +`FUSE homepage: <http://fuse.sourceforge.net/>`_ Filesystem type -~~~~~~~~~~~~~~~ +=============== The filesystem type given to mount(2) can be one of the following: -'fuse' - - This is the usual way to mount a FUSE filesystem. The first - argument of the mount system call may contain an arbitrary string, - which is not interpreted by the kernel. + fuse + This is the usual way to mount a FUSE filesystem. The first + argument of the mount system call may contain an arbitrary string, + which is not interpreted by the kernel. -'fuseblk' - - The filesystem is block device based. The first argument of the - mount system call is interpreted as the name of the device. + fuseblk + The filesystem is block device based. The first argument of the + mount system call is interpreted as the name of the device. Mount options -~~~~~~~~~~~~~ - -'fd=N' +============= +fd=N The file descriptor to use for communication between the userspace filesystem and the kernel. The file descriptor must have been obtained by opening the FUSE device ('/dev/fuse'). -'rootmode=M' - +rootmode=M The file mode of the filesystem's root in octal representation. -'user_id=N' - +user_id=N The numeric user id of the mount owner. -'group_id=N' - +group_id=N The numeric group id of the mount owner. -'default_permissions' - +default_permissions By default FUSE doesn't check file access permissions, the filesystem is free to implement its access policy or leave it to the underlying file access mechanism (e.g. in case of network @@ -97,28 +87,25 @@ Mount options access based on file mode. It is usually useful together with the 'allow_other' mount option. -'allow_other' - +allow_other This option overrides the security measure restricting file access to the user mounting the filesystem. This option is by default only allowed to root, but this restriction can be removed with a (userspace) configuration option. -'max_read=N' - +max_read=N With this option the maximum size of read operations can be set. The default is infinite. Note that the size of read requests is limited anyway to 32 pages (which is 128kbyte on i386). -'blksize=N' - +blksize=N Set the block size for the filesystem. The default is 512. This option is only valid for 'fuseblk' type mounts. Control filesystem -~~~~~~~~~~~~~~~~~~ +================== -There's a control filesystem for FUSE, which can be mounted by: +There's a control filesystem for FUSE, which can be mounted by:: mount -t fusectl none /sys/fs/fuse/connections @@ -130,53 +117,51 @@ named by a unique number. For each connection the following files exist within this directory: - 'waiting' - - The number of requests which are waiting to be transferred to - userspace or being processed by the filesystem daemon. If there is - no filesystem activity and 'waiting' is non-zero, then the - filesystem is hung or deadlocked. - - 'abort' + waiting + The number of requests which are waiting to be transferred to + userspace or being processed by the filesystem daemon. If there is + no filesystem activity and 'waiting' is non-zero, then the + filesystem is hung or deadlocked. - Writing anything into this file will abort the filesystem - connection. This means that all waiting requests will be aborted an - error returned for all aborted and new requests. + abort + Writing anything into this file will abort the filesystem + connection. This means that all waiting requests will be aborted an + error returned for all aborted and new requests. Only the owner of the mount may read or write these files. Interrupting filesystem operations -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +################################## If a process issuing a FUSE filesystem request is interrupted, the following will happen: - 1) If the request is not yet sent to userspace AND the signal is + - If the request is not yet sent to userspace AND the signal is fatal (SIGKILL or unhandled fatal signal), then the request is dequeued and returns immediately. - 2) If the request is not yet sent to userspace AND the signal is not - fatal, then an 'interrupted' flag is set for the request. When + - If the request is not yet sent to userspace AND the signal is not + fatal, then an interrupted flag is set for the request. When the request has been successfully transferred to userspace and this flag is set, an INTERRUPT request is queued. - 3) If the request is already sent to userspace, then an INTERRUPT + - If the request is already sent to userspace, then an INTERRUPT request is queued. INTERRUPT requests take precedence over other requests, so the userspace filesystem will receive queued INTERRUPTs before any others. The userspace filesystem may ignore the INTERRUPT requests entirely, -or may honor them by sending a reply to the _original_ request, with +or may honor them by sending a reply to the *original* request, with the error set to EINTR. It is also possible that there's a race between processing the original request and its INTERRUPT request. There are two possibilities: - 1) The INTERRUPT request is processed before the original request is + 1. The INTERRUPT request is processed before the original request is processed - 2) The INTERRUPT request is processed after the original request has + 2. The INTERRUPT request is processed after the original request has been answered If the filesystem cannot find the original request, it should wait for @@ -186,7 +171,7 @@ should reply to the INTERRUPT request with an EAGAIN error. In case reply will be ignored. Aborting a filesystem connection -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +================================ It is possible to get into certain situations where the filesystem is not responding. Reasons for this may be: @@ -216,7 +201,7 @@ the filesystem. There are several ways to do this: powerful method, always works. How do non-privileged mounts work? -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +================================== Since the mount() system call is a privileged operation, a helper program (fusermount) is needed, which is installed setuid root. @@ -235,15 +220,13 @@ system. Obvious requirements arising from this are: other users' or the super user's processes How are requirements fulfilled? -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +=============================== A) The mount owner could gain elevated privileges by either: - 1) creating a filesystem containing a device file, then opening - this device + 1. creating a filesystem containing a device file, then opening this device - 2) creating a filesystem containing a suid or sgid application, - then executing this application + 2. creating a filesystem containing a suid or sgid application, then executing this application The solution is not to allow opening device files and ignore setuid and setgid bits when executing programs. To ensure this @@ -275,16 +258,16 @@ How are requirements fulfilled? of other users' processes. i) It can slow down or indefinitely delay the execution of a - filesystem operation creating a DoS against the user or the - whole system. For example a suid application locking a - system file, and then accessing a file on the mount owner's - filesystem could be stopped, and thus causing the system - file to be locked forever. + filesystem operation creating a DoS against the user or the + whole system. For example a suid application locking a + system file, and then accessing a file on the mount owner's + filesystem could be stopped, and thus causing the system + file to be locked forever. ii) It can present files or directories of unlimited length, or - directory structures of unlimited depth, possibly causing a - system process to eat up diskspace, memory or other - resources, again causing DoS. + directory structures of unlimited depth, possibly causing a + system process to eat up diskspace, memory or other + resources, again causing *DoS*. The solution to this as well as B) is not to allow processes to access the filesystem, which could otherwise not be @@ -294,28 +277,27 @@ How are requirements fulfilled? ptrace can be used to check if a process is allowed to access the filesystem or not. - Note that the ptrace check is not strictly necessary to + Note that the *ptrace* check is not strictly necessary to prevent B/2/i, it is enough to check if mount owner has enough privilege to send signal to the process accessing the - filesystem, since SIGSTOP can be used to get a similar effect. + filesystem, since *SIGSTOP* can be used to get a similar effect. I think these limitations are unacceptable? -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +=========================================== If a sysadmin trusts the users enough, or can ensure through other measures, that system processes will never enter non-privileged -mounts, it can relax the last limitation with a "user_allow_other" +mounts, it can relax the last limitation with a 'user_allow_other' config option. If this config option is set, the mounting user can -add the "allow_other" mount option which disables the check for other +add the 'allow_other' mount option which disables the check for other users' processes. Kernel - userspace interface -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +============================ The following diagram shows how a filesystem operation (in this -example unlink) is performed in FUSE. +example unlink) is performed in FUSE. :: -NOTE: everything in this description is greatly simplified | "rm /mnt/fuse/file" | FUSE filesystem daemon | | @@ -357,12 +339,13 @@ NOTE: everything in this description is greatly simplified | <fuse_unlink() | | <sys_unlink() | +.. note:: Everything in the description above is greatly simplified + There are a couple of ways in which to deadlock a FUSE filesystem. Since we are talking about unprivileged userspace programs, something must be done about these. -Scenario 1 - Simple deadlock ------------------------------ +**Scenario 1 - Simple deadlock**:: | "rm /mnt/fuse/file" | FUSE filesystem daemon | | @@ -379,12 +362,12 @@ Scenario 1 - Simple deadlock The solution for this is to allow the filesystem to be aborted. -Scenario 2 - Tricky deadlock ----------------------------- +**Scenario 2 - Tricky deadlock** + This one needs a carefully crafted filesystem. It's a variation on the above, only the call back to the filesystem is not explicit, -but is caused by a pagefault. +but is caused by a pagefault. :: | Kamikaze filesystem thread 1 | Kamikaze filesystem thread 2 | | @@ -410,7 +393,7 @@ but is caused by a pagefault. | | [lock page] | | * DEADLOCK * -Solution is basically the same as above. +The solution is basically the same as above. An additional problem is that while the write buffer is being copied to the request, the request must not be interrupted/aborted. This is diff --git a/Documentation/filesystems/index.rst b/Documentation/filesystems/index.rst index ad6315a48d14..386eaad008b2 100644 --- a/Documentation/filesystems/index.rst +++ b/Documentation/filesystems/index.rst @@ -47,4 +47,7 @@ Documentation for filesystem implementations. :maxdepth: 2 autofs + fuse + overlayfs virtiofs + vfat diff --git a/Documentation/filesystems/mount_api.txt b/Documentation/filesystems/mount_api.txt index 00ff0cfccfa7..87c14bbb2b35 100644 --- a/Documentation/filesystems/mount_api.txt +++ b/Documentation/filesystems/mount_api.txt @@ -427,7 +427,6 @@ returned. fs_value_is_string, Value is a string fs_value_is_blob, Value is a binary blob fs_value_is_filename, Value is a filename* + dirfd - fs_value_is_filename_empty, Value is a filename* + dirfd + AT_EMPTY_PATH fs_value_is_file, Value is an open file (file*) If there is a value, that value is stored in a union in the struct in one @@ -519,7 +518,6 @@ Parameters are described using structures defined in linux/fs_parser.h. There's a core description struct that links everything together: struct fs_parameter_description { - const char name[16]; const struct fs_parameter_spec *specs; const struct fs_parameter_enum *enums; }; @@ -535,19 +533,13 @@ For example: }; static const struct fs_parameter_description afs_fs_parameters = { - .name = "kAFS", .specs = afs_param_specs, .enums = afs_param_enums, }; The members are as follows: - (1) const char name[16]; - - The name to be used in error messages generated by the parse helper - functions. - - (2) const struct fs_parameter_specification *specs; + (1) const struct fs_parameter_specification *specs; Table of parameter specifications, terminated with a null entry, where the entries are of type: @@ -626,7 +618,7 @@ The members are as follows: of arguments to specify the type and the flags for anything that doesn't match one of the above macros. - (6) const struct fs_parameter_enum *enums; + (2) const struct fs_parameter_enum *enums; Table of enum value names to integer mappings, terminated with a null entry. This is of type: diff --git a/Documentation/filesystems/nfs/nfs-rdma.txt b/Documentation/filesystems/nfs/nfs-rdma.txt deleted file mode 100644 index 22dc0dd6889c..000000000000 --- a/Documentation/filesystems/nfs/nfs-rdma.txt +++ /dev/null @@ -1,274 +0,0 @@ -################################################################################ -# # -# NFS/RDMA README # -# # -################################################################################ - - Author: NetApp and Open Grid Computing - Date: May 29, 2008 - -Table of Contents -~~~~~~~~~~~~~~~~~ - - Overview - - Getting Help - - Installation - - Check RDMA and NFS Setup - - NFS/RDMA Setup - -Overview -~~~~~~~~ - - This document describes how to install and setup the Linux NFS/RDMA client - and server software. - - The NFS/RDMA client was first included in Linux 2.6.24. The NFS/RDMA server - was first included in the following release, Linux 2.6.25. - - In our testing, we have obtained excellent performance results (full 10Gbit - wire bandwidth at minimal client CPU) under many workloads. The code passes - the full Connectathon test suite and operates over both Infiniband and iWARP - RDMA adapters. - -Getting Help -~~~~~~~~~~~~ - - If you get stuck, you can ask questions on the - - nfs-rdma-devel@lists.sourceforge.net - - mailing list. - -Installation -~~~~~~~~~~~~ - - These instructions are a step by step guide to building a machine for - use with NFS/RDMA. - - - Install an RDMA device - - Any device supported by the drivers in drivers/infiniband/hw is acceptable. - - Testing has been performed using several Mellanox-based IB cards, the - Ammasso AMS1100 iWARP adapter, and the Chelsio cxgb3 iWARP adapter. - - - Install a Linux distribution and tools - - The first kernel release to contain both the NFS/RDMA client and server was - Linux 2.6.25 Therefore, a distribution compatible with this and subsequent - Linux kernel release should be installed. - - The procedures described in this document have been tested with - distributions from Red Hat's Fedora Project (http://fedora.redhat.com/). - - - Install nfs-utils-1.1.2 or greater on the client - - An NFS/RDMA mount point can be obtained by using the mount.nfs command in - nfs-utils-1.1.2 or greater (nfs-utils-1.1.1 was the first nfs-utils - version with support for NFS/RDMA mounts, but for various reasons we - recommend using nfs-utils-1.1.2 or greater). To see which version of - mount.nfs you are using, type: - - $ /sbin/mount.nfs -V - - If the version is less than 1.1.2 or the command does not exist, - you should install the latest version of nfs-utils. - - Download the latest package from: - - http://www.kernel.org/pub/linux/utils/nfs - - Uncompress the package and follow the installation instructions. - - If you will not need the idmapper and gssd executables (you do not need - these to create an NFS/RDMA enabled mount command), the installation - process can be simplified by disabling these features when running - configure: - - $ ./configure --disable-gss --disable-nfsv4 - - To build nfs-utils you will need the tcp_wrappers package installed. For - more information on this see the package's README and INSTALL files. - - After building the nfs-utils package, there will be a mount.nfs binary in - the utils/mount directory. This binary can be used to initiate NFS v2, v3, - or v4 mounts. To initiate a v4 mount, the binary must be called - mount.nfs4. The standard technique is to create a symlink called - mount.nfs4 to mount.nfs. - - This mount.nfs binary should be installed at /sbin/mount.nfs as follows: - - $ sudo cp utils/mount/mount.nfs /sbin/mount.nfs - - In this location, mount.nfs will be invoked automatically for NFS mounts - by the system mount command. - - NOTE: mount.nfs and therefore nfs-utils-1.1.2 or greater is only needed - on the NFS client machine. You do not need this specific version of - nfs-utils on the server. Furthermore, only the mount.nfs command from - nfs-utils-1.1.2 is needed on the client. - - - Install a Linux kernel with NFS/RDMA - - The NFS/RDMA client and server are both included in the mainline Linux - kernel version 2.6.25 and later. This and other versions of the Linux - kernel can be found at: - - https://www.kernel.org/pub/linux/kernel/ - - Download the sources and place them in an appropriate location. - - - Configure the RDMA stack - - Make sure your kernel configuration has RDMA support enabled. Under - Device Drivers -> InfiniBand support, update the kernel configuration - to enable InfiniBand support [NOTE: the option name is misleading. Enabling - InfiniBand support is required for all RDMA devices (IB, iWARP, etc.)]. - - Enable the appropriate IB HCA support (mlx4, mthca, ehca, ipath, etc.) or - iWARP adapter support (amso, cxgb3, etc.). - - If you are using InfiniBand, be sure to enable IP-over-InfiniBand support. - - - Configure the NFS client and server - - Your kernel configuration must also have NFS file system support and/or - NFS server support enabled. These and other NFS related configuration - options can be found under File Systems -> Network File Systems. - - - Build, install, reboot - - The NFS/RDMA code will be enabled automatically if NFS and RDMA - are turned on. The NFS/RDMA client and server are configured via the hidden - SUNRPC_XPRT_RDMA config option that depends on SUNRPC and INFINIBAND. The - value of SUNRPC_XPRT_RDMA will be: - - - N if either SUNRPC or INFINIBAND are N, in this case the NFS/RDMA client - and server will not be built - - M if both SUNRPC and INFINIBAND are on (M or Y) and at least one is M, - in this case the NFS/RDMA client and server will be built as modules - - Y if both SUNRPC and INFINIBAND are Y, in this case the NFS/RDMA client - and server will be built into the kernel - - Therefore, if you have followed the steps above and turned no NFS and RDMA, - the NFS/RDMA client and server will be built. - - Build a new kernel, install it, boot it. - -Check RDMA and NFS Setup -~~~~~~~~~~~~~~~~~~~~~~~~ - - Before configuring the NFS/RDMA software, it is a good idea to test - your new kernel to ensure that the kernel is working correctly. - In particular, it is a good idea to verify that the RDMA stack - is functioning as expected and standard NFS over TCP/IP and/or UDP/IP - is working properly. - - - Check RDMA Setup - - If you built the RDMA components as modules, load them at - this time. For example, if you are using a Mellanox Tavor/Sinai/Arbel - card: - - $ modprobe ib_mthca - $ modprobe ib_ipoib - - If you are using InfiniBand, make sure there is a Subnet Manager (SM) - running on the network. If your IB switch has an embedded SM, you can - use it. Otherwise, you will need to run an SM, such as OpenSM, on one - of your end nodes. - - If an SM is running on your network, you should see the following: - - $ cat /sys/class/infiniband/driverX/ports/1/state - 4: ACTIVE - - where driverX is mthca0, ipath5, ehca3, etc. - - To further test the InfiniBand software stack, use IPoIB (this - assumes you have two IB hosts named host1 and host2): - - host1$ ip link set dev ib0 up - host1$ ip address add dev ib0 a.b.c.x - host2$ ip link set dev ib0 up - host2$ ip address add dev ib0 a.b.c.y - host1$ ping a.b.c.y - host2$ ping a.b.c.x - - For other device types, follow the appropriate procedures. - - - Check NFS Setup - - For the NFS components enabled above (client and/or server), - test their functionality over standard Ethernet using TCP/IP or UDP/IP. - -NFS/RDMA Setup -~~~~~~~~~~~~~~ - - We recommend that you use two machines, one to act as the client and - one to act as the server. - - One time configuration: - - - On the server system, configure the /etc/exports file and - start the NFS/RDMA server. - - Exports entries with the following formats have been tested: - - /vol0 192.168.0.47(fsid=0,rw,async,insecure,no_root_squash) - /vol0 192.168.0.0/255.255.255.0(fsid=0,rw,async,insecure,no_root_squash) - - The IP address(es) is(are) the client's IPoIB address for an InfiniBand - HCA or the client's iWARP address(es) for an RNIC. - - NOTE: The "insecure" option must be used because the NFS/RDMA client does - not use a reserved port. - - Each time a machine boots: - - - Load and configure the RDMA drivers - - For InfiniBand using a Mellanox adapter: - - $ modprobe ib_mthca - $ modprobe ib_ipoib - $ ip li set dev ib0 up - $ ip addr add dev ib0 a.b.c.d - - NOTE: use unique addresses for the client and server - - - Start the NFS server - - If the NFS/RDMA server was built as a module (CONFIG_SUNRPC_XPRT_RDMA=m in - kernel config), load the RDMA transport module: - - $ modprobe svcrdma - - Regardless of how the server was built (module or built-in), start the - server: - - $ /etc/init.d/nfs start - - or - - $ service nfs start - - Instruct the server to listen on the RDMA transport: - - $ echo rdma 20049 > /proc/fs/nfsd/portlist - - - On the client system - - If the NFS/RDMA client was built as a module (CONFIG_SUNRPC_XPRT_RDMA=m in - kernel config), load the RDMA client module: - - $ modprobe xprtrdma.ko - - Regardless of how the client was built (module or built-in), use this - command to mount the NFS/RDMA server: - - $ mount -o rdma,port=20049 <IPoIB-server-name-or-address>:/<export> /mnt - - To verify that the mount is using RDMA, run "cat /proc/mounts" and check - the "proto" field for the given mount. - - Congratulations! You're using NFS/RDMA! diff --git a/Documentation/filesystems/path-lookup.rst b/Documentation/filesystems/path-lookup.rst index 434a07b0002b..a3216979298b 100644 --- a/Documentation/filesystems/path-lookup.rst +++ b/Documentation/filesystems/path-lookup.rst @@ -13,6 +13,7 @@ It has subsequently been updated to reflect changes in the kernel including: - per-directory parallel name lookup. +- ``openat2()`` resolution restriction flags. Introduction to pathname lookup =============================== @@ -235,6 +236,13 @@ renamed. If ``d_lookup`` finds that a rename happened while it unsuccessfully scanned a chain in the hash table, it simply tries again. +``rename_lock`` is also used to detect and defend against potential attacks +against ``LOOKUP_BENEATH`` and ``LOOKUP_IN_ROOT`` when resolving ".." (where +the parent directory is moved outside the root, bypassing the ``path_equal()`` +check). If ``rename_lock`` is updated during the lookup and the path encounters +a "..", a potential attack occurred and ``handle_dots()`` will bail out with +``-EAGAIN``. + inode->i_rwsem ~~~~~~~~~~~~~~ @@ -348,6 +356,13 @@ any changes to any mount points while stepping up. This locking is needed to stabilize the link to the mounted-on dentry, which the refcount on the mount itself doesn't ensure. +``mount_lock`` is also used to detect and defend against potential attacks +against ``LOOKUP_BENEATH`` and ``LOOKUP_IN_ROOT`` when resolving ".." (where +the parent directory is moved outside the root, bypassing the ``path_equal()`` +check). If ``mount_lock`` is updated during the lookup and the path encounters +a "..", a potential attack occurred and ``handle_dots()`` will bail out with +``-EAGAIN``. + RCU ~~~ @@ -405,6 +420,10 @@ is requested. Keeping a reference in the ``nameidata`` ensures that only one root is in effect for the entire path walk, even if it races with a ``chroot()`` system call. +It should be noted that in the case of ``LOOKUP_IN_ROOT`` or +``LOOKUP_BENEATH``, the effective root becomes the directory file descriptor +passed to ``openat2()`` (which exposes these ``LOOKUP_`` flags). + The root is needed when either of two conditions holds: (1) either the pathname or a symbolic link starts with a "'/'", or (2) a "``..``" component is being handled, since "``..``" from the root must always stay @@ -1149,7 +1168,7 @@ so ``NULL`` is returned to indicate that the symlink can be released and the stack frame discarded. The other case involves things in ``/proc`` that look like symlinks but -aren't really:: +aren't really (and are therefore commonly referred to as "magic-links"):: $ ls -l /proc/self/fd/1 lrwx------ 1 neilb neilb 64 Jun 13 10:19 /proc/self/fd/1 -> /dev/pts/4 @@ -1286,7 +1305,9 @@ A few flags A suitable way to wrap up this tour of pathname walking is to list the various flags that can be stored in the ``nameidata`` to guide the lookup process. Many of these are only meaningful on the final -component, others reflect the current state of the pathname lookup. +component, others reflect the current state of the pathname lookup, and some +apply restrictions to all path components encountered in the path lookup. + And then there is ``LOOKUP_EMPTY``, which doesn't fit conceptually with the others. If this is not set, an empty pathname causes an error very early on. If it is set, empty pathnames are not considered to be @@ -1310,13 +1331,48 @@ longer needed. ``LOOKUP_JUMPED`` means that the current dentry was chosen not because it had the right name but for some other reason. This happens when following "``..``", following a symlink to ``/``, crossing a mount point -or accessing a "``/proc/$PID/fd/$FD``" symlink. In this case the -filesystem has not been asked to revalidate the name (with -``d_revalidate()``). In such cases the inode may still need to be -revalidated, so ``d_op->d_weak_revalidate()`` is called if +or accessing a "``/proc/$PID/fd/$FD``" symlink (also known as a "magic +link"). In this case the filesystem has not been asked to revalidate the +name (with ``d_revalidate()``). In such cases the inode may still need +to be revalidated, so ``d_op->d_weak_revalidate()`` is called if ``LOOKUP_JUMPED`` is set when the look completes - which may be at the final component or, when creating, unlinking, or renaming, at the penultimate component. +Resolution-restriction flags +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +In order to allow userspace to protect itself against certain race conditions +and attack scenarios involving changing path components, a series of flags are +available which apply restrictions to all path components encountered during +path lookup. These flags are exposed through ``openat2()``'s ``resolve`` field. + +``LOOKUP_NO_SYMLINKS`` blocks all symlink traversals (including magic-links). +This is distinctly different from ``LOOKUP_FOLLOW``, because the latter only +relates to restricting the following of trailing symlinks. + +``LOOKUP_NO_MAGICLINKS`` blocks all magic-link traversals. Filesystems must +ensure that they return errors from ``nd_jump_link()``, because that is how +``LOOKUP_NO_MAGICLINKS`` and other magic-link restrictions are implemented. + +``LOOKUP_NO_XDEV`` blocks all ``vfsmount`` traversals (this includes both +bind-mounts and ordinary mounts). Note that the ``vfsmount`` which contains the +lookup is determined by the first mountpoint the path lookup reaches -- +absolute paths start with the ``vfsmount`` of ``/``, and relative paths start +with the ``dfd``'s ``vfsmount``. Magic-links are only permitted if the +``vfsmount`` of the path is unchanged. + +``LOOKUP_BENEATH`` blocks any path components which resolve outside the +starting point of the resolution. This is done by blocking ``nd_jump_root()`` +as well as blocking ".." if it would jump outside the starting point. +``rename_lock`` and ``mount_lock`` are used to detect attacks against the +resolution of "..". Magic-links are also blocked. + +``LOOKUP_IN_ROOT`` resolves all path components as though the starting point +were the filesystem root. ``nd_jump_root()`` brings the resolution back to to +the starting point, and ".." at the starting point will act as a no-op. As with +``LOOKUP_BENEATH``, ``rename_lock`` and ``mount_lock`` are used to detect +attacks against ".." resolution. Magic-links are also blocked. + Final-component flags ~~~~~~~~~~~~~~~~~~~~~ diff --git a/Documentation/filesystems/vfat.rst b/Documentation/filesystems/vfat.rst new file mode 100644 index 000000000000..e85d74e91295 --- /dev/null +++ b/Documentation/filesystems/vfat.rst @@ -0,0 +1,387 @@ +==== +VFAT +==== + +USING VFAT +========== + +To use the vfat filesystem, use the filesystem type 'vfat'. i.e.:: + + mount -t vfat /dev/fd0 /mnt + + +No special partition formatter is required, +'mkdosfs' will work fine if you want to format from within Linux. + +VFAT MOUNT OPTIONS +================== + +**uid=###** + Set the owner of all files on this filesystem. + The default is the uid of current process. + +**gid=###** + Set the group of all files on this filesystem. + The default is the gid of current process. + +**umask=###** + The permission mask (for files and directories, see *umask(1)*). + The default is the umask of current process. + +**dmask=###** + The permission mask for the directory. + The default is the umask of current process. + +**fmask=###** + The permission mask for files. + The default is the umask of current process. + +**allow_utime=###** + This option controls the permission check of mtime/atime. + + **-20**: If current process is in group of file's group ID, + you can change timestamp. + + **-2**: Other users can change timestamp. + + The default is set from dmask option. If the directory is + writable, utime(2) is also allowed. i.e. ~dmask & 022. + + Normally utime(2) checks current process is owner of + the file, or it has CAP_FOWNER capability. But FAT + filesystem doesn't have uid/gid on disk, so normal + check is too unflexible. With this option you can + relax it. + +**codepage=###** + Sets the codepage number for converting to shortname + characters on FAT filesystem. + By default, FAT_DEFAULT_CODEPAGE setting is used. + +**iocharset=<name>** + Character set to use for converting between the + encoding is used for user visible filename and 16 bit + Unicode characters. Long filenames are stored on disk + in Unicode format, but Unix for the most part doesn't + know how to deal with Unicode. + By default, FAT_DEFAULT_IOCHARSET setting is used. + + There is also an option of doing UTF-8 translations + with the utf8 option. + +.. note:: ``iocharset=utf8`` is not recommended. If unsure, you should consider + the utf8 option instead. + +**utf8=<bool>** + UTF-8 is the filesystem safe version of Unicode that + is used by the console. It can be enabled or disabled + for the filesystem with this option. + If 'uni_xlate' gets set, UTF-8 gets disabled. + By default, FAT_DEFAULT_UTF8 setting is used. + +**uni_xlate=<bool>** + Translate unhandled Unicode characters to special + escaped sequences. This would let you backup and + restore filenames that are created with any Unicode + characters. Until Linux supports Unicode for real, + this gives you an alternative. Without this option, + a '?' is used when no translation is possible. The + escape character is ':' because it is otherwise + illegal on the vfat filesystem. The escape sequence + that gets used is ':' and the four digits of hexadecimal + unicode. + +**nonumtail=<bool>** + When creating 8.3 aliases, normally the alias will + end in '~1' or tilde followed by some number. If this + option is set, then if the filename is + "longfilename.txt" and "longfile.txt" does not + currently exist in the directory, longfile.txt will + be the short alias instead of longfi~1.txt. + +**usefree** + Use the "free clusters" value stored on FSINFO. It will + be used to determine number of free clusters without + scanning disk. But it's not used by default, because + recent Windows don't update it correctly in some + case. If you are sure the "free clusters" on FSINFO is + correct, by this option you can avoid scanning disk. + +**quiet** + Stops printing certain warning messages. + +**check=s|r|n** + Case sensitivity checking setting. + + **s**: strict, case sensitive + + **r**: relaxed, case insensitive + + **n**: normal, default setting, currently case insensitive + +**nocase** + This was deprecated for vfat. Use ``shortname=win95`` instead. + +**shortname=lower|win95|winnt|mixed** + Shortname display/create setting. + + **lower**: convert to lowercase for display, + emulate the Windows 95 rule for create. + + **win95**: emulate the Windows 95 rule for display/create. + + **winnt**: emulate the Windows NT rule for display/create. + + **mixed**: emulate the Windows NT rule for display, + emulate the Windows 95 rule for create. + + Default setting is `mixed`. + +**tz=UTC** + Interpret timestamps as UTC rather than local time. + This option disables the conversion of timestamps + between local time (as used by Windows on FAT) and UTC + (which Linux uses internally). This is particularly + useful when mounting devices (like digital cameras) + that are set to UTC in order to avoid the pitfalls of + local time. + +**time_offset=minutes** + Set offset for conversion of timestamps from local time + used by FAT to UTC. I.e. <minutes> minutes will be subtracted + from each timestamp to convert it to UTC used internally by + Linux. This is useful when time zone set in ``sys_tz`` is + not the time zone used by the filesystem. Note that this + option still does not provide correct time stamps in all + cases in presence of DST - time stamps in a different DST + setting will be off by one hour. + +**showexec** + If set, the execute permission bits of the file will be + allowed only if the extension part of the name is .EXE, + .COM, or .BAT. Not set by default. + +**debug** + Can be set, but unused by the current implementation. + +**sys_immutable** + If set, ATTR_SYS attribute on FAT is handled as + IMMUTABLE flag on Linux. Not set by default. + +**flush** + If set, the filesystem will try to flush to disk more + early than normal. Not set by default. + +**rodir** + FAT has the ATTR_RO (read-only) attribute. On Windows, + the ATTR_RO of the directory will just be ignored, + and is used only by applications as a flag (e.g. it's set + for the customized folder). + + If you want to use ATTR_RO as read-only flag even for + the directory, set this option. + +**errors=panic|continue|remount-ro** + specify FAT behavior on critical errors: panic, continue + without doing anything or remount the partition in + read-only mode (default behavior). + +**discard** + If set, issues discard/TRIM commands to the block + device when blocks are freed. This is useful for SSD devices + and sparse/thinly-provisoned LUNs. + +**nfs=stale_rw|nostale_ro** + Enable this only if you want to export the FAT filesystem + over NFS. + + **stale_rw**: This option maintains an index (cache) of directory + *inodes* by *i_logstart* which is used by the nfs-related code to + improve look-ups. Full file operations (read/write) over NFS is + supported but with cache eviction at NFS server, this could + result in ESTALE issues. + + **nostale_ro**: This option bases the *inode* number and filehandle + on the on-disk location of a file in the MS-DOS directory entry. + This ensures that ESTALE will not be returned after a file is + evicted from the inode cache. However, it means that operations + such as rename, create and unlink could cause filehandles that + previously pointed at one file to point at a different file, + potentially causing data corruption. For this reason, this + option also mounts the filesystem readonly. + + To maintain backward compatibility, ``'-o nfs'`` is also accepted, + defaulting to "stale_rw". + +**dos1xfloppy <bool>: 0,1,yes,no,true,false** + If set, use a fallback default BIOS Parameter Block + configuration, determined by backing device size. These static + parameters match defaults assumed by DOS 1.x for 160 kiB, + 180 kiB, 320 kiB, and 360 kiB floppies and floppy images. + + + +LIMITATION +========== + +The fallocated region of file is discarded at umount/evict time +when using fallocate with FALLOC_FL_KEEP_SIZE. +So, User should assume that fallocated region can be discarded at +last close if there is memory pressure resulting in eviction of +the inode from the memory. As a result, for any dependency on +the fallocated region, user should make sure to recheck fallocate +after reopening the file. + +TODO +==== +Need to get rid of the raw scanning stuff. Instead, always use +a get next directory entry approach. The only thing left that uses +raw scanning is the directory renaming code. + + +POSSIBLE PROBLEMS +================= + +- vfat_valid_longname does not properly checked reserved names. +- When a volume name is the same as a directory name in the root + directory of the filesystem, the directory name sometimes shows + up as an empty file. +- autoconv option does not work correctly. + + +TEST SUITE +========== +If you plan to make any modifications to the vfat filesystem, please +get the test suite that comes with the vfat distribution at + +`<http://web.archive.org/web/*/http://bmrc.berkeley.edu/people/chaffee/vfat.html>`_ + +This tests quite a few parts of the vfat filesystem and additional +tests for new features or untested features would be appreciated. + +NOTES ON THE STRUCTURE OF THE VFAT FILESYSTEM +============================================= +This documentation was provided by Galen C. Hunt gchunt@cs.rochester.edu and +lightly annotated by Gordon Chaffee. + +This document presents a very rough, technical overview of my +knowledge of the extended FAT file system used in Windows NT 3.5 and +Windows 95. I don't guarantee that any of the following is correct, +but it appears to be so. + +The extended FAT file system is almost identical to the FAT +file system used in DOS versions up to and including *6.223410239847* +:-). The significant change has been the addition of long file names. +These names support up to 255 characters including spaces and lower +case characters as opposed to the traditional 8.3 short names. + +Here is the description of the traditional FAT entry in the current +Windows 95 filesystem:: + + struct directory { // Short 8.3 names + unsigned char name[8]; // file name + unsigned char ext[3]; // file extension + unsigned char attr; // attribute byte + unsigned char lcase; // Case for base and extension + unsigned char ctime_ms; // Creation time, milliseconds + unsigned char ctime[2]; // Creation time + unsigned char cdate[2]; // Creation date + unsigned char adate[2]; // Last access date + unsigned char reserved[2]; // reserved values (ignored) + unsigned char time[2]; // time stamp + unsigned char date[2]; // date stamp + unsigned char start[2]; // starting cluster number + unsigned char size[4]; // size of the file + }; + + +The lcase field specifies if the base and/or the extension of an 8.3 +name should be capitalized. This field does not seem to be used by +Windows 95 but it is used by Windows NT. The case of filenames is not +completely compatible from Windows NT to Windows 95. It is not completely +compatible in the reverse direction, however. Filenames that fit in +the 8.3 namespace and are written on Windows NT to be lowercase will +show up as uppercase on Windows 95. + +.. note:: Note that the ``start`` and ``size`` values are actually little + endian integer values. The descriptions of the fields in this + structure are public knowledge and can be found elsewhere. + +With the extended FAT system, Microsoft has inserted extra +directory entries for any files with extended names. (Any name which +legally fits within the old 8.3 encoding scheme does not have extra +entries.) I call these extra entries slots. Basically, a slot is a +specially formatted directory entry which holds up to 13 characters of +a file's extended name. Think of slots as additional labeling for the +directory entry of the file to which they correspond. Microsoft +prefers to refer to the 8.3 entry for a file as its alias and the +extended slot directory entries as the file name. + +The C structure for a slot directory entry follows:: + + struct slot { // Up to 13 characters of a long name + unsigned char id; // sequence number for slot + unsigned char name0_4[10]; // first 5 characters in name + unsigned char attr; // attribute byte + unsigned char reserved; // always 0 + unsigned char alias_checksum; // checksum for 8.3 alias + unsigned char name5_10[12]; // 6 more characters in name + unsigned char start[2]; // starting cluster number + unsigned char name11_12[4]; // last 2 characters in name + }; + + +If the layout of the slots looks a little odd, it's only +because of Microsoft's efforts to maintain compatibility with old +software. The slots must be disguised to prevent old software from +panicking. To this end, a number of measures are taken: + + 1) The attribute byte for a slot directory entry is always set + to 0x0f. This corresponds to an old directory entry with + attributes of "hidden", "system", "read-only", and "volume + label". Most old software will ignore any directory + entries with the "volume label" bit set. Real volume label + entries don't have the other three bits set. + + 2) The starting cluster is always set to 0, an impossible + value for a DOS file. + +Because the extended FAT system is backward compatible, it is +possible for old software to modify directory entries. Measures must +be taken to ensure the validity of slots. An extended FAT system can +verify that a slot does in fact belong to an 8.3 directory entry by +the following: + + 1) Positioning. Slots for a file always immediately proceed + their corresponding 8.3 directory entry. In addition, each + slot has an id which marks its order in the extended file + name. Here is a very abbreviated view of an 8.3 directory + entry and its corresponding long name slots for the file + "My Big File.Extension which is long":: + + <proceeding files...> + <slot #3, id = 0x43, characters = "h is long"> + <slot #2, id = 0x02, characters = "xtension whic"> + <slot #1, id = 0x01, characters = "My Big File.E"> + <directory entry, name = "MYBIGFIL.EXT"> + + + .. note:: Note that the slots are stored from last to first. Slots + are numbered from 1 to N. The Nth slot is ``or'ed`` with + 0x40 to mark it as the last one. + + 2) Checksum. Each slot has an alias_checksum value. The + checksum is calculated from the 8.3 name using the + following algorithm:: + + for (sum = i = 0; i < 11; i++) { + sum = (((sum&1)<<7)|((sum&0xfe)>>1)) + name[i] + } + + + 3) If there is free space in the final slot, a Unicode ``NULL (0x0000)`` + is stored after the final character. After that, all unused + characters in the final slot are set to Unicode 0xFFFF. + +Finally, note that the extended name is stored in Unicode. Each Unicode +character takes either two or four bytes, UTF-16LE encoded. diff --git a/Documentation/filesystems/vfat.txt b/Documentation/filesystems/vfat.txt deleted file mode 100644 index 91031298beb1..000000000000 --- a/Documentation/filesystems/vfat.txt +++ /dev/null @@ -1,347 +0,0 @@ -USING VFAT ----------------------------------------------------------------------- -To use the vfat filesystem, use the filesystem type 'vfat'. i.e. - mount -t vfat /dev/fd0 /mnt - -No special partition formatter is required. mkdosfs will work fine -if you want to format from within Linux. - -VFAT MOUNT OPTIONS ----------------------------------------------------------------------- -uid=### -- Set the owner of all files on this filesystem. - The default is the uid of current process. - -gid=### -- Set the group of all files on this filesystem. - The default is the gid of current process. - -umask=### -- The permission mask (for files and directories, see umask(1)). - The default is the umask of current process. - -dmask=### -- The permission mask for the directory. - The default is the umask of current process. - -fmask=### -- The permission mask for files. - The default is the umask of current process. - -allow_utime=### -- This option controls the permission check of mtime/atime. - - 20 - If current process is in group of file's group ID, - you can change timestamp. - 2 - Other users can change timestamp. - - The default is set from `dmask' option. (If the directory is - writable, utime(2) is also allowed. I.e. ~dmask & 022) - - Normally utime(2) checks current process is owner of - the file, or it has CAP_FOWNER capability. But FAT - filesystem doesn't have uid/gid on disk, so normal - check is too unflexible. With this option you can - relax it. - -codepage=### -- Sets the codepage number for converting to shortname - characters on FAT filesystem. - By default, FAT_DEFAULT_CODEPAGE setting is used. - -iocharset=<name> -- Character set to use for converting between the - encoding is used for user visible filename and 16 bit - Unicode characters. Long filenames are stored on disk - in Unicode format, but Unix for the most part doesn't - know how to deal with Unicode. - By default, FAT_DEFAULT_IOCHARSET setting is used. - - There is also an option of doing UTF-8 translations - with the utf8 option. - - NOTE: "iocharset=utf8" is not recommended. If unsure, - you should consider the following option instead. - -utf8=<bool> -- UTF-8 is the filesystem safe version of Unicode that - is used by the console. It can be enabled or disabled - for the filesystem with this option. - If 'uni_xlate' gets set, UTF-8 gets disabled. - By default, FAT_DEFAULT_UTF8 setting is used. - -uni_xlate=<bool> -- Translate unhandled Unicode characters to special - escaped sequences. This would let you backup and - restore filenames that are created with any Unicode - characters. Until Linux supports Unicode for real, - this gives you an alternative. Without this option, - a '?' is used when no translation is possible. The - escape character is ':' because it is otherwise - illegal on the vfat filesystem. The escape sequence - that gets used is ':' and the four digits of hexadecimal - unicode. - -nonumtail=<bool> -- When creating 8.3 aliases, normally the alias will - end in '~1' or tilde followed by some number. If this - option is set, then if the filename is - "longfilename.txt" and "longfile.txt" does not - currently exist in the directory, 'longfile.txt' will - be the short alias instead of 'longfi~1.txt'. - -usefree -- Use the "free clusters" value stored on FSINFO. It'll - be used to determine number of free clusters without - scanning disk. But it's not used by default, because - recent Windows don't update it correctly in some - case. If you are sure the "free clusters" on FSINFO is - correct, by this option you can avoid scanning disk. - -quiet -- Stops printing certain warning messages. - -check=s|r|n -- Case sensitivity checking setting. - s: strict, case sensitive - r: relaxed, case insensitive - n: normal, default setting, currently case insensitive - -nocase -- This was deprecated for vfat. Use shortname=win95 instead. - -shortname=lower|win95|winnt|mixed - -- Shortname display/create setting. - lower: convert to lowercase for display, - emulate the Windows 95 rule for create. - win95: emulate the Windows 95 rule for display/create. - winnt: emulate the Windows NT rule for display/create. - mixed: emulate the Windows NT rule for display, - emulate the Windows 95 rule for create. - Default setting is `mixed'. - -tz=UTC -- Interpret timestamps as UTC rather than local time. - This option disables the conversion of timestamps - between local time (as used by Windows on FAT) and UTC - (which Linux uses internally). This is particularly - useful when mounting devices (like digital cameras) - that are set to UTC in order to avoid the pitfalls of - local time. -time_offset=minutes - -- Set offset for conversion of timestamps from local time - used by FAT to UTC. I.e. <minutes> minutes will be subtracted - from each timestamp to convert it to UTC used internally by - Linux. This is useful when time zone set in sys_tz is - not the time zone used by the filesystem. Note that this - option still does not provide correct time stamps in all - cases in presence of DST - time stamps in a different DST - setting will be off by one hour. - -showexec -- If set, the execute permission bits of the file will be - allowed only if the extension part of the name is .EXE, - .COM, or .BAT. Not set by default. - -debug -- Can be set, but unused by the current implementation. - -sys_immutable -- If set, ATTR_SYS attribute on FAT is handled as - IMMUTABLE flag on Linux. Not set by default. - -flush -- If set, the filesystem will try to flush to disk more - early than normal. Not set by default. - -rodir -- FAT has the ATTR_RO (read-only) attribute. On Windows, - the ATTR_RO of the directory will just be ignored, - and is used only by applications as a flag (e.g. it's set - for the customized folder). - - If you want to use ATTR_RO as read-only flag even for - the directory, set this option. - -errors=panic|continue|remount-ro - -- specify FAT behavior on critical errors: panic, continue - without doing anything or remount the partition in - read-only mode (default behavior). - -discard -- If set, issues discard/TRIM commands to the block - device when blocks are freed. This is useful for SSD devices - and sparse/thinly-provisoned LUNs. - -nfs=stale_rw|nostale_ro - Enable this only if you want to export the FAT filesystem - over NFS. - - stale_rw: This option maintains an index (cache) of directory - inodes by i_logstart which is used by the nfs-related code to - improve look-ups. Full file operations (read/write) over NFS is - supported but with cache eviction at NFS server, this could - result in ESTALE issues. - - nostale_ro: This option bases the inode number and filehandle - on the on-disk location of a file in the MS-DOS directory entry. - This ensures that ESTALE will not be returned after a file is - evicted from the inode cache. However, it means that operations - such as rename, create and unlink could cause filehandles that - previously pointed at one file to point at a different file, - potentially causing data corruption. For this reason, this - option also mounts the filesystem readonly. - - To maintain backward compatibility, '-o nfs' is also accepted, - defaulting to stale_rw - -dos1xfloppy -- If set, use a fallback default BIOS Parameter Block - configuration, determined by backing device size. These static - parameters match defaults assumed by DOS 1.x for 160 kiB, - 180 kiB, 320 kiB, and 360 kiB floppies and floppy images. - - -<bool>: 0,1,yes,no,true,false - -LIMITATION ---------------------------------------------------------------------- -* The fallocated region of file is discarded at umount/evict time - when using fallocate with FALLOC_FL_KEEP_SIZE. - So, User should assume that fallocated region can be discarded at - last close if there is memory pressure resulting in eviction of - the inode from the memory. As a result, for any dependency on - the fallocated region, user should make sure to recheck fallocate - after reopening the file. - -TODO ----------------------------------------------------------------------- -* Need to get rid of the raw scanning stuff. Instead, always use - a get next directory entry approach. The only thing left that uses - raw scanning is the directory renaming code. - - -POSSIBLE PROBLEMS ----------------------------------------------------------------------- -* vfat_valid_longname does not properly checked reserved names. -* When a volume name is the same as a directory name in the root - directory of the filesystem, the directory name sometimes shows - up as an empty file. -* autoconv option does not work correctly. - -BUG REPORTS ----------------------------------------------------------------------- -If you have trouble with the VFAT filesystem, mail bug reports to -chaffee@bmrc.cs.berkeley.edu. Please specify the filename -and the operation that gave you trouble. - -TEST SUITE ----------------------------------------------------------------------- -If you plan to make any modifications to the vfat filesystem, please -get the test suite that comes with the vfat distribution at - - http://web.archive.org/web/*/http://bmrc.berkeley.edu/ - people/chaffee/vfat.html - -This tests quite a few parts of the vfat filesystem and additional -tests for new features or untested features would be appreciated. - -NOTES ON THE STRUCTURE OF THE VFAT FILESYSTEM ----------------------------------------------------------------------- -(This documentation was provided by Galen C. Hunt <gchunt@cs.rochester.edu> - and lightly annotated by Gordon Chaffee). - -This document presents a very rough, technical overview of my -knowledge of the extended FAT file system used in Windows NT 3.5 and -Windows 95. I don't guarantee that any of the following is correct, -but it appears to be so. - -The extended FAT file system is almost identical to the FAT -file system used in DOS versions up to and including 6.223410239847 -:-). The significant change has been the addition of long file names. -These names support up to 255 characters including spaces and lower -case characters as opposed to the traditional 8.3 short names. - -Here is the description of the traditional FAT entry in the current -Windows 95 filesystem: - - struct directory { // Short 8.3 names - unsigned char name[8]; // file name - unsigned char ext[3]; // file extension - unsigned char attr; // attribute byte - unsigned char lcase; // Case for base and extension - unsigned char ctime_ms; // Creation time, milliseconds - unsigned char ctime[2]; // Creation time - unsigned char cdate[2]; // Creation date - unsigned char adate[2]; // Last access date - unsigned char reserved[2]; // reserved values (ignored) - unsigned char time[2]; // time stamp - unsigned char date[2]; // date stamp - unsigned char start[2]; // starting cluster number - unsigned char size[4]; // size of the file - }; - -The lcase field specifies if the base and/or the extension of an 8.3 -name should be capitalized. This field does not seem to be used by -Windows 95 but it is used by Windows NT. The case of filenames is not -completely compatible from Windows NT to Windows 95. It is not completely -compatible in the reverse direction, however. Filenames that fit in -the 8.3 namespace and are written on Windows NT to be lowercase will -show up as uppercase on Windows 95. - -Note that the "start" and "size" values are actually little -endian integer values. The descriptions of the fields in this -structure are public knowledge and can be found elsewhere. - -With the extended FAT system, Microsoft has inserted extra -directory entries for any files with extended names. (Any name which -legally fits within the old 8.3 encoding scheme does not have extra -entries.) I call these extra entries slots. Basically, a slot is a -specially formatted directory entry which holds up to 13 characters of -a file's extended name. Think of slots as additional labeling for the -directory entry of the file to which they correspond. Microsoft -prefers to refer to the 8.3 entry for a file as its alias and the -extended slot directory entries as the file name. - -The C structure for a slot directory entry follows: - - struct slot { // Up to 13 characters of a long name - unsigned char id; // sequence number for slot - unsigned char name0_4[10]; // first 5 characters in name - unsigned char attr; // attribute byte - unsigned char reserved; // always 0 - unsigned char alias_checksum; // checksum for 8.3 alias - unsigned char name5_10[12]; // 6 more characters in name - unsigned char start[2]; // starting cluster number - unsigned char name11_12[4]; // last 2 characters in name - }; - -If the layout of the slots looks a little odd, it's only -because of Microsoft's efforts to maintain compatibility with old -software. The slots must be disguised to prevent old software from -panicking. To this end, a number of measures are taken: - - 1) The attribute byte for a slot directory entry is always set - to 0x0f. This corresponds to an old directory entry with - attributes of "hidden", "system", "read-only", and "volume - label". Most old software will ignore any directory - entries with the "volume label" bit set. Real volume label - entries don't have the other three bits set. - - 2) The starting cluster is always set to 0, an impossible - value for a DOS file. - -Because the extended FAT system is backward compatible, it is -possible for old software to modify directory entries. Measures must -be taken to ensure the validity of slots. An extended FAT system can -verify that a slot does in fact belong to an 8.3 directory entry by -the following: - - 1) Positioning. Slots for a file always immediately proceed - their corresponding 8.3 directory entry. In addition, each - slot has an id which marks its order in the extended file - name. Here is a very abbreviated view of an 8.3 directory - entry and its corresponding long name slots for the file - "My Big File.Extension which is long": - - <proceeding files...> - <slot #3, id = 0x43, characters = "h is long"> - <slot #2, id = 0x02, characters = "xtension whic"> - <slot #1, id = 0x01, characters = "My Big File.E"> - <directory entry, name = "MYBIGFIL.EXT"> - - Note that the slots are stored from last to first. Slots - are numbered from 1 to N. The Nth slot is or'ed with 0x40 - to mark it as the last one. - - 2) Checksum. Each slot has an "alias_checksum" value. The - checksum is calculated from the 8.3 name using the - following algorithm: - - for (sum = i = 0; i < 11; i++) { - sum = (((sum&1)<<7)|((sum&0xfe)>>1)) + name[i] - } - - 3) If there is free space in the final slot, a Unicode NULL (0x0000) - is stored after the final character. After that, all unused - characters in the final slot are set to Unicode 0xFFFF. - -Finally, note that the extended name is stored in Unicode. Each Unicode -character takes either two or four bytes, UTF-16LE encoded. diff --git a/Documentation/filesystems/zonefs.txt b/Documentation/filesystems/zonefs.txt new file mode 100644 index 000000000000..d54fa98ac158 --- /dev/null +++ b/Documentation/filesystems/zonefs.txt @@ -0,0 +1,404 @@ +ZoneFS - Zone filesystem for Zoned block devices + +Introduction +============ + +zonefs is a very simple file system exposing each zone of a zoned block device +as a file. Unlike a regular POSIX-compliant file system with native zoned block +device support (e.g. f2fs), zonefs does not hide the sequential write +constraint of zoned block devices to the user. Files representing sequential +write zones of the device must be written sequentially starting from the end +of the file (append only writes). + +As such, zonefs is in essence closer to a raw block device access interface +than to a full-featured POSIX file system. The goal of zonefs is to simplify +the implementation of zoned block device support in applications by replacing +raw block device file accesses with a richer file API, avoiding relying on +direct block device file ioctls which may be more obscure to developers. One +example of this approach is the implementation of LSM (log-structured merge) +tree structures (such as used in RocksDB and LevelDB) on zoned block devices +by allowing SSTables to be stored in a zone file similarly to a regular file +system rather than as a range of sectors of the entire disk. The introduction +of the higher level construct "one file is one zone" can help reducing the +amount of changes needed in the application as well as introducing support for +different application programming languages. + +Zoned block devices +------------------- + +Zoned storage devices belong to a class of storage devices with an address +space that is divided into zones. A zone is a group of consecutive LBAs and all +zones are contiguous (there are no LBA gaps). Zones may have different types. +* Conventional zones: there are no access constraints to LBAs belonging to + conventional zones. Any read or write access can be executed, similarly to a + regular block device. +* Sequential zones: these zones accept random reads but must be written + sequentially. Each sequential zone has a write pointer maintained by the + device that keeps track of the mandatory start LBA position of the next write + to the device. As a result of this write constraint, LBAs in a sequential zone + cannot be overwritten. Sequential zones must first be erased using a special + command (zone reset) before rewriting. + +Zoned storage devices can be implemented using various recording and media +technologies. The most common form of zoned storage today uses the SCSI Zoned +Block Commands (ZBC) and Zoned ATA Commands (ZAC) interfaces on Shingled +Magnetic Recording (SMR) HDDs. + +Solid State Disks (SSD) storage devices can also implement a zoned interface +to, for instance, reduce internal write amplification due to garbage collection. +The NVMe Zoned NameSpace (ZNS) is a technical proposal of the NVMe standard +committee aiming at adding a zoned storage interface to the NVMe protocol. + +Zonefs Overview +=============== + +Zonefs exposes the zones of a zoned block device as files. The files +representing zones are grouped by zone type, which are themselves represented +by sub-directories. This file structure is built entirely using zone information +provided by the device and so does not require any complex on-disk metadata +structure. + +On-disk metadata +---------------- + +zonefs on-disk metadata is reduced to an immutable super block which +persistently stores a magic number and optional feature flags and values. On +mount, zonefs uses blkdev_report_zones() to obtain the device zone configuration +and populates the mount point with a static file tree solely based on this +information. File sizes come from the device zone type and write pointer +position managed by the device itself. + +The super block is always written on disk at sector 0. The first zone of the +device storing the super block is never exposed as a zone file by zonefs. If +the zone containing the super block is a sequential zone, the mkzonefs format +tool always "finishes" the zone, that is, it transitions the zone to a full +state to make it read-only, preventing any data write. + +Zone type sub-directories +------------------------- + +Files representing zones of the same type are grouped together under the same +sub-directory automatically created on mount. + +For conventional zones, the sub-directory "cnv" is used. This directory is +however created if and only if the device has usable conventional zones. If +the device only has a single conventional zone at sector 0, the zone will not +be exposed as a file as it will be used to store the zonefs super block. For +such devices, the "cnv" sub-directory will not be created. + +For sequential write zones, the sub-directory "seq" is used. + +These two directories are the only directories that exist in zonefs. Users +cannot create other directories and cannot rename nor delete the "cnv" and +"seq" sub-directories. + +The size of the directories indicated by the st_size field of struct stat, +obtained with the stat() or fstat() system calls, indicates the number of files +existing under the directory. + +Zone files +---------- + +Zone files are named using the number of the zone they represent within the set +of zones of a particular type. That is, both the "cnv" and "seq" directories +contain files named "0", "1", "2", ... The file numbers also represent +increasing zone start sector on the device. + +All read and write operations to zone files are not allowed beyond the file +maximum size, that is, beyond the zone size. Any access exceeding the zone +size is failed with the -EFBIG error. + +Creating, deleting, renaming or modifying any attribute of files and +sub-directories is not allowed. + +The number of blocks of a file as reported by stat() and fstat() indicates the +size of the file zone, or in other words, the maximum file size. + +Conventional zone files +----------------------- + +The size of conventional zone files is fixed to the size of the zone they +represent. Conventional zone files cannot be truncated. + +These files can be randomly read and written using any type of I/O operation: +buffered I/Os, direct I/Os, memory mapped I/Os (mmap), etc. There are no I/O +constraint for these files beyond the file size limit mentioned above. + +Sequential zone files +--------------------- + +The size of sequential zone files grouped in the "seq" sub-directory represents +the file's zone write pointer position relative to the zone start sector. + +Sequential zone files can only be written sequentially, starting from the file +end, that is, write operations can only be append writes. Zonefs makes no +attempt at accepting random writes and will fail any write request that has a +start offset not corresponding to the end of the file, or to the end of the last +write issued and still in-flight (for asynchronous I/O operations). + +Since dirty page writeback by the page cache does not guarantee a sequential +write pattern, zonefs prevents buffered writes and writeable shared mappings +on sequential files. Only direct I/O writes are accepted for these files. +zonefs relies on the sequential delivery of write I/O requests to the device +implemented by the block layer elevator. An elevator implementing the sequential +write feature for zoned block device (ELEVATOR_F_ZBD_SEQ_WRITE elevator feature) +must be used. This type of elevator (e.g. mq-deadline) is set by default +for zoned block devices on device initialization. + +There are no restrictions on the type of I/O used for read operations in +sequential zone files. Buffered I/Os, direct I/Os and shared read mappings are +all accepted. + +Truncating sequential zone files is allowed only down to 0, in which case, the +zone is reset to rewind the file zone write pointer position to the start of +the zone, or up to the zone size, in which case the file's zone is transitioned +to the FULL state (finish zone operation). + +Format options +-------------- + +Several optional features of zonefs can be enabled at format time. +* Conventional zone aggregation: ranges of contiguous conventional zones can be + aggregated into a single larger file instead of the default one file per zone. +* File ownership: The owner UID and GID of zone files is by default 0 (root) + but can be changed to any valid UID/GID. +* File access permissions: the default 640 access permissions can be changed. + +IO error handling +----------------- + +Zoned block devices may fail I/O requests for reasons similar to regular block +devices, e.g. due to bad sectors. However, in addition to such known I/O +failure pattern, the standards governing zoned block devices behavior define +additional conditions that result in I/O errors. + +* A zone may transition to the read-only condition (BLK_ZONE_COND_READONLY): + While the data already written in the zone is still readable, the zone can + no longer be written. No user action on the zone (zone management command or + read/write access) can change the zone condition back to a normal read/write + state. While the reasons for the device to transition a zone to read-only + state are not defined by the standards, a typical cause for such transition + would be a defective write head on an HDD (all zones under this head are + changed to read-only). + +* A zone may transition to the offline condition (BLK_ZONE_COND_OFFLINE): + An offline zone cannot be read nor written. No user action can transition an + offline zone back to an operational good state. Similarly to zone read-only + transitions, the reasons for a drive to transition a zone to the offline + condition are undefined. A typical cause would be a defective read-write head + on an HDD causing all zones on the platter under the broken head to be + inaccessible. + +* Unaligned write errors: These errors result from the host issuing write + requests with a start sector that does not correspond to a zone write pointer + position when the write request is executed by the device. Even though zonefs + enforces sequential file write for sequential zones, unaligned write errors + may still happen in the case of a partial failure of a very large direct I/O + operation split into multiple BIOs/requests or asynchronous I/O operations. + If one of the write request within the set of sequential write requests + issued to the device fails, all write requests queued after it will + become unaligned and fail. + +* Delayed write errors: similarly to regular block devices, if the device side + write cache is enabled, write errors may occur in ranges of previously + completed writes when the device write cache is flushed, e.g. on fsync(). + Similarly to the previous immediate unaligned write error case, delayed write + errors can propagate through a stream of cached sequential data for a zone + causing all data to be dropped after the sector that caused the error. + +All I/O errors detected by zonefs are notified to the user with an error code +return for the system call that triggered or detected the error. The recovery +actions taken by zonefs in response to I/O errors depend on the I/O type (read +vs write) and on the reason for the error (bad sector, unaligned writes or zone +condition change). + +* For read I/O errors, zonefs does not execute any particular recovery action, + but only if the file zone is still in a good condition and there is no + inconsistency between the file inode size and its zone write pointer position. + If a problem is detected, I/O error recovery is executed (see below table). + +* For write I/O errors, zonefs I/O error recovery is always executed. + +* A zone condition change to read-only or offline also always triggers zonefs + I/O error recovery. + +Zonefs minimal I/O error recovery may change a file size and file access +permissions. + +* File size changes: + Immediate or delayed write errors in a sequential zone file may cause the file + inode size to be inconsistent with the amount of data successfully written in + the file zone. For instance, the partial failure of a multi-BIO large write + operation will cause the zone write pointer to advance partially, even though + the entire write operation will be reported as failed to the user. In such + case, the file inode size must be advanced to reflect the zone write pointer + change and eventually allow the user to restart writing at the end of the + file. + A file size may also be reduced to reflect a delayed write error detected on + fsync(): in this case, the amount of data effectively written in the zone may + be less than originally indicated by the file inode size. After such I/O + error, zonefs always fixes the file inode size to reflect the amount of data + persistently stored in the file zone. + +* Access permission changes: + A zone condition change to read-only is indicated with a change in the file + access permissions to render the file read-only. This disables changes to the + file attributes and data modification. For offline zones, all permissions + (read and write) to the file are disabled. + +Further action taken by zonefs I/O error recovery can be controlled by the user +with the "errors=xxx" mount option. The table below summarizes the result of +zonefs I/O error processing depending on the mount option and on the zone +conditions. + + +--------------+-----------+-----------------------------------------+ + | | | Post error state | + | "errors=xxx" | device | access permissions | + | mount | zone | file file device zone | + | option | condition | size read write read write | + +--------------+-----------+-----------------------------------------+ + | | good | fixed yes no yes yes | + | remount-ro | read-only | fixed yes no yes no | + | (default) | offline | 0 no no no no | + +--------------+-----------+-----------------------------------------+ + | | good | fixed yes no yes yes | + | zone-ro | read-only | fixed yes no yes no | + | | offline | 0 no no no no | + +--------------+-----------+-----------------------------------------+ + | | good | 0 no no yes yes | + | zone-offline | read-only | 0 no no yes no | + | | offline | 0 no no no no | + +--------------+-----------+-----------------------------------------+ + | | good | fixed yes yes yes yes | + | repair | read-only | fixed yes no yes no | + | | offline | 0 no no no no | + +--------------+-----------+-----------------------------------------+ + +Further notes: +* The "errors=remount-ro" mount option is the default behavior of zonefs I/O + error processing if no errors mount option is specified. +* With the "errors=remount-ro" mount option, the change of the file access + permissions to read-only applies to all files. The file system is remounted + read-only. +* Access permission and file size changes due to the device transitioning zones + to the offline condition are permanent. Remounting or reformatting the device + with mkfs.zonefs (mkzonefs) will not change back offline zone files to a good + state. +* File access permission changes to read-only due to the device transitioning + zones to the read-only condition are permanent. Remounting or reformatting + the device will not re-enable file write access. +* File access permission changes implied by the remount-ro, zone-ro and + zone-offline mount options are temporary for zones in a good condition. + Unmounting and remounting the file system will restore the previous default + (format time values) access rights to the files affected. +* The repair mount option triggers only the minimal set of I/O error recovery + actions, that is, file size fixes for zones in a good condition. Zones + indicated as being read-only or offline by the device still imply changes to + the zone file access permissions as noted in the table above. + +Mount options +------------- + +zonefs define the "errors=<behavior>" mount option to allow the user to specify +zonefs behavior in response to I/O errors, inode size inconsistencies or zone +condition changes. The defined behaviors are as follow: +* remount-ro (default) +* zone-ro +* zone-offline +* repair + +The I/O error actions defined for each behavior are detailed in the previous +section. + +Zonefs User Space Tools +======================= + +The mkzonefs tool is used to format zoned block devices for use with zonefs. +This tool is available on Github at: + +https://github.com/damien-lemoal/zonefs-tools + +zonefs-tools also includes a test suite which can be run against any zoned +block device, including null_blk block device created with zoned mode. + +Examples +-------- + +The following formats a 15TB host-managed SMR HDD with 256 MB zones +with the conventional zones aggregation feature enabled. + +# mkzonefs -o aggr_cnv /dev/sdX +# mount -t zonefs /dev/sdX /mnt +# ls -l /mnt/ +total 0 +dr-xr-xr-x 2 root root 1 Nov 25 13:23 cnv +dr-xr-xr-x 2 root root 55356 Nov 25 13:23 seq + +The size of the zone files sub-directories indicate the number of files +existing for each type of zones. In this example, there is only one +conventional zone file (all conventional zones are aggregated under a single +file). + +# ls -l /mnt/cnv +total 137101312 +-rw-r----- 1 root root 140391743488 Nov 25 13:23 0 + +This aggregated conventional zone file can be used as a regular file. + +# mkfs.ext4 /mnt/cnv/0 +# mount -o loop /mnt/cnv/0 /data + +The "seq" sub-directory grouping files for sequential write zones has in this +example 55356 zones. + +# ls -lv /mnt/seq +total 14511243264 +-rw-r----- 1 root root 0 Nov 25 13:23 0 +-rw-r----- 1 root root 0 Nov 25 13:23 1 +-rw-r----- 1 root root 0 Nov 25 13:23 2 +... +-rw-r----- 1 root root 0 Nov 25 13:23 55354 +-rw-r----- 1 root root 0 Nov 25 13:23 55355 + +For sequential write zone files, the file size changes as data is appended at +the end of the file, similarly to any regular file system. + +# dd if=/dev/zero of=/mnt/seq/0 bs=4096 count=1 conv=notrunc oflag=direct +1+0 records in +1+0 records out +4096 bytes (4.1 kB, 4.0 KiB) copied, 0.00044121 s, 9.3 MB/s + +# ls -l /mnt/seq/0 +-rw-r----- 1 root root 4096 Nov 25 13:23 /mnt/seq/0 + +The written file can be truncated to the zone size, preventing any further +write operation. + +# truncate -s 268435456 /mnt/seq/0 +# ls -l /mnt/seq/0 +-rw-r----- 1 root root 268435456 Nov 25 13:49 /mnt/seq/0 + +Truncation to 0 size allows freeing the file zone storage space and restart +append-writes to the file. + +# truncate -s 0 /mnt/seq/0 +# ls -l /mnt/seq/0 +-rw-r----- 1 root root 0 Nov 25 13:49 /mnt/seq/0 + +Since files are statically mapped to zones on the disk, the number of blocks of +a file as reported by stat() and fstat() indicates the size of the file zone. + +# stat /mnt/seq/0 + File: /mnt/seq/0 + Size: 0 Blocks: 524288 IO Block: 4096 regular empty file +Device: 870h/2160d Inode: 50431 Links: 1 +Access: (0640/-rw-r-----) Uid: ( 0/ root) Gid: ( 0/ root) +Access: 2019-11-25 13:23:57.048971997 +0900 +Modify: 2019-11-25 13:52:25.553805765 +0900 +Change: 2019-11-25 13:52:25.553805765 +0900 + Birth: - + +The number of blocks of the file ("Blocks") in units of 512B blocks gives the +maximum file size of 524288 * 512 B = 256 MB, corresponding to the device zone +size in this example. Of note is that the "IO block" field always indicates the +minimum I/O size for writes and corresponds to the device physical sector size. diff --git a/Documentation/firmware-guide/acpi/enumeration.rst b/Documentation/firmware-guide/acpi/enumeration.rst index 0a72b6321f5f..c13fee8b02ba 100644 --- a/Documentation/firmware-guide/acpi/enumeration.rst +++ b/Documentation/firmware-guide/acpi/enumeration.rst @@ -71,8 +71,8 @@ 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:: +dma_request_chan() 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 */ @@ -112,15 +112,15 @@ could look like:: } #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 +dma_request_chan() 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:: +Clients must call dma_request_chan() 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) { diff --git a/Documentation/gpu/drm-internals.rst b/Documentation/gpu/drm-internals.rst index 966bd2d9f0cc..a73320576ca9 100644 --- a/Documentation/gpu/drm-internals.rst +++ b/Documentation/gpu/drm-internals.rst @@ -24,9 +24,9 @@ Driver Initialization At the core of every DRM driver is a :c:type:`struct drm_driver <drm_driver>` structure. Drivers typically statically initialize a drm_driver structure, and then pass it to -:c:func:`drm_dev_alloc()` to allocate a device instance. After the +drm_dev_alloc() to allocate a device instance. After the device instance is fully initialized it can be registered (which makes -it accessible from userspace) using :c:func:`drm_dev_register()`. +it accessible from userspace) using drm_dev_register(). The :c:type:`struct drm_driver <drm_driver>` structure contains static information that describes the driver and features it diff --git a/Documentation/gpu/drm-kms.rst b/Documentation/gpu/drm-kms.rst index 23a3c986ef6d..906771e03103 100644 --- a/Documentation/gpu/drm-kms.rst +++ b/Documentation/gpu/drm-kms.rst @@ -3,7 +3,7 @@ Kernel Mode Setting (KMS) ========================= Drivers must initialize the mode setting core by calling -:c:func:`drm_mode_config_init()` on the DRM device. The function +drm_mode_config_init() on the DRM device. The function initializes the :c:type:`struct drm_device <drm_device>` mode_config field and never fails. Once done, mode configuration must be setup by initializing the following fields. @@ -181,8 +181,7 @@ Setting`_). The somewhat surprising part here is that properties are not directly instantiated on each object, but free-standing mode objects themselves, represented by :c:type:`struct drm_property <drm_property>`, which only specify the type and value range of a property. Any given property can be attached -multiple times to different objects using :c:func:`drm_object_attach_property() -<drm_object_attach_property>`. +multiple times to different objects using drm_object_attach_property(). .. kernel-doc:: include/drm/drm_mode_object.h :internal: @@ -260,7 +259,8 @@ Taken all together there's two consequences for the atomic design: drm_connector_state <drm_connector_state>` for connectors. These are the only objects with userspace-visible and settable state. For internal state drivers can subclass these structures through embeddeding, or add entirely new state - structures for their globally shared hardware functions. + structures for their globally shared hardware functions, see :c:type:`struct + drm_private_state<drm_private_state>`. - An atomic update is assembled and validated as an entirely free-standing pile of structures within the :c:type:`drm_atomic_state <drm_atomic_state>` @@ -269,6 +269,14 @@ Taken all together there's two consequences for the atomic design: to the driver and modeset objects. This way rolling back an update boils down to releasing memory and unreferencing objects like framebuffers. +Locking of atomic state structures is internally using :c:type:`struct +drm_modeset_lock <drm_modeset_lock>`. As a general rule the locking shouldn't be +exposed to drivers, instead the right locks should be automatically acquired by +any function that duplicates or peeks into a state, like e.g. +drm_atomic_get_crtc_state(). Locking only protects the software data +structure, ordering of committing state changes to hardware is sequenced using +:c:type:`struct drm_crtc_commit <drm_crtc_commit>`. + Read on in this chapter, and also in :ref:`drm_atomic_helper` for more detailed coverage of specific topics. @@ -479,6 +487,9 @@ Color Management Properties .. kernel-doc:: drivers/gpu/drm/drm_color_mgmt.c :export: +.. kernel-doc:: include/drm/drm_color_mgmt.h + :internal: + Tile Group Property ------------------- diff --git a/Documentation/gpu/drm-mm.rst b/Documentation/gpu/drm-mm.rst index 59619296c84b..c77b32601260 100644 --- a/Documentation/gpu/drm-mm.rst +++ b/Documentation/gpu/drm-mm.rst @@ -149,19 +149,19 @@ struct :c:type:`struct drm_gem_object <drm_gem_object>`. To create a GEM object, a driver allocates memory for an instance of its specific GEM object type and initializes the embedded struct :c:type:`struct drm_gem_object <drm_gem_object>` with a call -to :c:func:`drm_gem_object_init()`. The function takes a pointer +to drm_gem_object_init(). The function takes a pointer to the DRM device, a pointer to the GEM object and the buffer object size in bytes. GEM uses shmem to allocate anonymous pageable memory. -:c:func:`drm_gem_object_init()` will create an shmfs file of the +drm_gem_object_init() will create an shmfs file of the requested size and store it into the struct :c:type:`struct drm_gem_object <drm_gem_object>` filp 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. Drivers are responsible for the actual physical pages allocation by -calling :c:func:`shmem_read_mapping_page_gfp()` for each page. +calling shmem_read_mapping_page_gfp() 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 @@ -170,20 +170,18 @@ when the driver needs to start a DMA transfer involving the memory). 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 :c:func:`drm_gem_private_object_init()` instead of -:c:func:`drm_gem_object_init()`. Storage for private GEM objects -must be managed by drivers. +no shmfs backing (called private GEM objects) by initializing them with a call +to drm_gem_private_object_init() instead of drm_gem_object_init(). Storage for +private GEM objects must be managed by drivers. GEM Objects Lifetime -------------------- All GEM objects are reference-counted by the GEM core. References can be -acquired and release by :c:func:`calling drm_gem_object_get()` and -:c:func:`drm_gem_object_put()` respectively. The caller must hold the -:c:type:`struct drm_device <drm_device>` struct_mutex lock when calling -:c:func:`drm_gem_object_get()`. As a convenience, GEM provides -:c:func:`drm_gem_object_put_unlocked()` functions that can be called without +acquired and release by calling drm_gem_object_get() and drm_gem_object_put() +respectively. The caller must hold the :c:type:`struct drm_device <drm_device>` +struct_mutex lock when calling drm_gem_object_get(). As a convenience, GEM +provides drm_gem_object_put_unlocked() functions that can be called without holding the lock. When the last reference to a GEM object is released the GEM core calls @@ -194,7 +192,7 @@ free the GEM object and all associated resources. void (\*gem_free_object) (struct drm_gem_object \*obj); Drivers are responsible for freeing all GEM object resources. This includes the resources created by the GEM core, which need to be released with -:c:func:`drm_gem_object_release()`. +drm_gem_object_release(). GEM Objects Naming ------------------ @@ -210,13 +208,11 @@ 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. -To create a handle for a GEM object drivers call -:c:func:`drm_gem_handle_create()`. 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 -:c:func:`drm_gem_handle_delete()`. Finally the GEM object -associated with a handle can be retrieved by a call to -:c:func:`drm_gem_object_lookup()`. +To create a handle for a GEM object drivers call drm_gem_handle_create(). 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 drm_gem_handle_delete(). Finally the GEM object associated with a +handle can be retrieved by a call to drm_gem_object_lookup(). 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 @@ -258,7 +254,7 @@ 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 -:c:func:`do_mmap()` under the hood. This is often considered +do_mmap() under the hood. This is often considered dubious, seems to be discouraged for new GEM-enabled drivers, and will thus not be described here. @@ -267,23 +263,22 @@ The second method uses the mmap system call on the DRM file handle. void offset); 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 :c:func:`drm_gem_create_mmap_offset()` on the object. +must call drm_gem_create_mmap_offset() on the object. Once allocated, the fake offset value must be passed to the application in a driver-specific way and can then be used as the mmap offset argument. -The GEM core provides a helper method :c:func:`drm_gem_mmap()` to +The GEM core provides a helper method drm_gem_mmap() 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 :c:type:`struct drm_driver -<drm_driver>` gem_vm_ops field. Note that -:c:func:`drm_gem_mmap()` doesn't map memory to userspace, but -relies on the driver-provided fault handler to map pages individually. +<drm_driver>` gem_vm_ops field. Note that drm_gem_mmap() doesn't map memory to +userspace, but relies on the driver-provided fault handler to map pages +individually. -To use :c:func:`drm_gem_mmap()`, drivers must fill the struct -:c:type:`struct drm_driver <drm_driver>` gem_vm_ops field -with a pointer to VM operations. +To use drm_gem_mmap(), drivers must fill the struct :c:type:`struct drm_driver +<drm_driver>` gem_vm_ops field with a pointer to VM operations. The VM operations is a :c:type:`struct vm_operations_struct <vm_operations_struct>` made up of several fields, the more interesting ones being: @@ -298,9 +293,8 @@ made up of several fields, the more interesting ones being: The open and close operations must update the GEM object reference -count. Drivers can use the :c:func:`drm_gem_vm_open()` and -:c:func:`drm_gem_vm_close()` helper functions directly as open -and close handlers. +count. Drivers can use the drm_gem_vm_open() and drm_gem_vm_close() helper +functions directly as open and close handlers. The fault operation handler is responsible for mapping individual pages to userspace when a page fault occurs. Depending on the memory @@ -312,12 +306,12 @@ Drivers that want to map the GEM object upfront instead of handling page faults can implement their own mmap file operation handler. For platforms without MMU the GEM core provides a helper method -:c:func:`drm_gem_cma_get_unmapped_area`. The mmap() routines will call -this to get a proposed address for the mapping. +drm_gem_cma_get_unmapped_area(). The mmap() routines will call this to get a +proposed address for the mapping. -To use :c:func:`drm_gem_cma_get_unmapped_area`, drivers must fill the -struct :c:type:`struct file_operations <file_operations>` get_unmapped_area -field with a pointer on :c:func:`drm_gem_cma_get_unmapped_area`. +To use drm_gem_cma_get_unmapped_area(), drivers must fill the struct +:c:type:`struct file_operations <file_operations>` get_unmapped_area field with +a pointer on drm_gem_cma_get_unmapped_area(). More detailed information about get_unmapped_area can be found in Documentation/nommu-mmap.txt diff --git a/Documentation/gpu/drm-uapi.rst b/Documentation/gpu/drm-uapi.rst index 94f90521f58c..56fec6ed1ad8 100644 --- a/Documentation/gpu/drm-uapi.rst +++ b/Documentation/gpu/drm-uapi.rst @@ -254,36 +254,45 @@ Validating changes with IGT There's a collection of tests that aims to cover the whole functionality of DRM drivers and that can be used to check that changes to DRM drivers or the core don't regress existing functionality. This test suite is called IGT and -its code can be found in https://cgit.freedesktop.org/drm/igt-gpu-tools/. +its code and instructions to build and run can be found in +https://gitlab.freedesktop.org/drm/igt-gpu-tools/. -To build IGT, start by installing its build dependencies. In Debian-based -systems:: +Using VKMS to test DRM API +-------------------------- - # apt-get build-dep intel-gpu-tools +VKMS is a software-only model of a KMS driver that is useful for testing +and for running compositors. VKMS aims to enable a virtual display without +the need for a hardware display capability. These characteristics made VKMS +a perfect tool for validating the DRM core behavior and also support the +compositor developer. VKMS makes it possible to test DRM functions in a +virtual machine without display, simplifying the validation of some of the +core changes. -And in Fedora-based systems:: +To Validate changes in DRM API with VKMS, start setting the kernel: make +sure to enable VKMS module; compile the kernel with the VKMS enabled and +install it in the target machine. VKMS can be run in a Virtual Machine +(QEMU, virtme or similar). It's recommended the use of KVM with the minimum +of 1GB of RAM and four cores. - # dnf builddep intel-gpu-tools +It's possible to run the IGT-tests in a VM in two ways: -Then clone the repository:: + 1. Use IGT inside a VM + 2. Use IGT from the host machine and write the results in a shared directory. - $ git clone git://anongit.freedesktop.org/drm/igt-gpu-tools +As follow, there is an example of using a VM with a shared directory with +the host machine to run igt-tests. As an example it's used virtme:: -Configure the build system and start the build:: + $ virtme-run --rwdir /path/for/shared_dir --kdir=path/for/kernel/directory --mods=auto - $ cd igt-gpu-tools && ./autogen.sh && make -j6 +Run the igt-tests in the guest machine, as example it's ran the 'kms_flip' +tests:: -Download the piglit dependency:: + $ /path/for/igt-gpu-tools/scripts/run-tests.sh -p -s -t "kms_flip.*" -v - $ ./scripts/run-tests.sh -d - -And run the tests:: - - $ ./scripts/run-tests.sh -t kms -t core -s - -run-tests.sh is a wrapper around piglit that will execute the tests matching -the -t options. A report in HTML format will be available in -./results/html/index.html. Results can be compared with piglit. +In this example, instead of build the igt_runner, Piglit is used +(-p option); it's created html summary of the tests results and it's saved +in the folder "igt-gpu-tools/results"; it's executed only the igt-tests +matching the -t option. Display CRC Support ------------------- diff --git a/Documentation/gpu/i915.rst b/Documentation/gpu/i915.rst index d0947c5c4ab8..e539c42a3e78 100644 --- a/Documentation/gpu/i915.rst +++ b/Documentation/gpu/i915.rst @@ -466,9 +466,6 @@ GuC-based command submission .. kernel-doc:: drivers/gpu/drm/i915/gt/uc/intel_guc_submission.c :doc: GuC-based command submission -.. kernel-doc:: drivers/gpu/drm/i915/gt/uc/intel_guc_submission.c - :internal: - HuC --- .. kernel-doc:: drivers/gpu/drm/i915/gt/uc/intel_huc.c diff --git a/Documentation/gpu/todo.rst b/Documentation/gpu/todo.rst index 6792fa9b6b6b..bc869b23fc39 100644 --- a/Documentation/gpu/todo.rst +++ b/Documentation/gpu/todo.rst @@ -142,14 +142,14 @@ Contact: Daniel Vetter, respective driver maintainers Level: Advanced -Convert instances of dev_info/dev_err/dev_warn to their DRM_DEV_* equivalent ----------------------------------------------------------------------------- +Convert logging to drm_* functions with drm_device paramater +------------------------------------------------------------ For drivers which could have multiple instances, it is necessary to differentiate between which is which in the logs. Since DRM_INFO/WARN/ERROR don't do this, drivers used dev_info/warn/err to make this differentiation. We -now have DRM_DEV_* variants of the drm print macros, so we can start to convert -those drivers back to using drm-formwatted specific log messages. +now have drm_* variants of the drm print functions, so we can start to convert +those drivers back to using drm-formatted specific log messages. Before you start this conversion please contact the relevant maintainers to make sure your work will be merged - not everyone agrees that the DRM dmesg macros @@ -171,23 +171,40 @@ Contact: Maintainer of the driver you plan to convert Level: Intermediate -Convert drivers to use drm_fb_helper_fbdev_setup/teardown() ------------------------------------------------------------ +Convert drivers to use drm_fbdev_generic_setup() +------------------------------------------------ -Most drivers can use drm_fb_helper_fbdev_setup() except maybe: +Most drivers can use drm_fbdev_generic_setup(). Driver have to implement +atomic modesetting and GEM vmap support. Current generic fbdev emulation +expects the framebuffer in system memory (or system-like memory). -- amdgpu which has special logic to decide whether to call - drm_helper_disable_unused_functions() +Contact: Maintainer of the driver you plan to convert + +Level: Intermediate -- armada which isn't atomic and doesn't call - drm_helper_disable_unused_functions() +drm_framebuffer_funcs and drm_mode_config_funcs.fb_create cleanup +----------------------------------------------------------------- -- i915 which calls drm_fb_helper_initial_config() in a worker +A lot more drivers could be switched over to the drm_gem_framebuffer helpers. +Various hold-ups: -Drivers that use drm_framebuffer_remove() to clean up the fbdev framebuffer can -probably use drm_fb_helper_fbdev_teardown(). +- Need to switch over to the generic dirty tracking code using + drm_atomic_helper_dirtyfb first (e.g. qxl). -Contact: Maintainer of the driver you plan to convert +- Need to switch to drm_fbdev_generic_setup(), otherwise a lot of the custom fb + setup code can't be deleted. + +- Many drivers wrap drm_gem_fb_create() only to check for valid formats. For + atomic drivers we could check for valid formats by calling + drm_plane_check_pixel_format() against all planes, and pass if any plane + supports the format. For non-atomic that's not possible since like the format + list for the primary plane is fake and we'd therefor reject valid formats. + +- Many drivers subclass drm_framebuffer, we'd need a embedding compatible + version of the varios drm_gem_fb_create functions. Maybe called + drm_gem_fb_create/_with_dirty/_with_funcs as needed. + +Contact: Daniel Vetter Level: Intermediate @@ -328,8 +345,8 @@ drm_fb_helper tasks these igt tests need to be fixed: kms_fbcon_fbt@psr and kms_fbcon_fbt@psr-suspend. -- The max connector argument for drm_fb_helper_init() and - drm_fb_helper_fbdev_setup() isn't used anymore and can be removed. +- The max connector argument for drm_fb_helper_init() isn't used anymore and + can be removed. - The helper doesn't keep an array of connectors anymore so these can be removed: drm_fb_helper_single_add_all_connectors(), @@ -351,6 +368,23 @@ connector register/unregister fixes Level: Intermediate +Remove load/unload callbacks from all non-DRIVER_LEGACY drivers +--------------------------------------------------------------- + +The load/unload callbacks in struct &drm_driver are very much midlayers, plus +for historical reasons they get the ordering wrong (and we can't fix that) +between setting up the &drm_driver structure and calling drm_dev_register(). + +- Rework drivers to no longer use the load/unload callbacks, directly coding the + load/unload sequence into the driver's probe function. + +- Once all non-DRIVER_LEGACY drivers are converted, disallow the load/unload + callbacks for all modern drivers. + +Contact: Daniel Vetter + +Level: Intermediate + Core refactorings ================= diff --git a/Documentation/hwmon/adm1177.rst b/Documentation/hwmon/adm1177.rst new file mode 100644 index 000000000000..c81e0b4abd28 --- /dev/null +++ b/Documentation/hwmon/adm1177.rst @@ -0,0 +1,36 @@ +Kernel driver adm1177 +===================== + +Supported chips: + * Analog Devices ADM1177 + Prefix: 'adm1177' + Datasheet: https://www.analog.com/media/en/technical-documentation/data-sheets/ADM1177.pdf + +Author: Beniamin Bia <beniamin.bia@analog.com> + + +Description +----------- + +This driver supports hardware monitoring for Analog Devices ADM1177 +Hot-Swap Controller and Digital Power Monitors with Soft Start Pin. + + +Usage Notes +----------- + +This driver does not auto-detect devices. You will have to instantiate the +devices explicitly. Please see Documentation/i2c/instantiating-devices for +details. + + +Sysfs entries +------------- + +The following attributes are supported. Current maxim attribute +is read-write, all other attributes are read-only. + +in0_input Measured voltage in microvolts. + +curr1_input Measured current in microamperes. +curr1_max_alarm Overcurrent alarm in microamperes. diff --git a/Documentation/hwmon/drivetemp.rst b/Documentation/hwmon/drivetemp.rst new file mode 100644 index 000000000000..2d37d049247f --- /dev/null +++ b/Documentation/hwmon/drivetemp.rst @@ -0,0 +1,52 @@ +.. SPDX-License-Identifier: GPL-2.0 + +Kernel driver drivetemp +======================= + + +References +---------- + +ANS T13/1699-D +Information technology - AT Attachment 8 - ATA/ATAPI Command Set (ATA8-ACS) + +ANS Project T10/BSR INCITS 513 +Information technology - SCSI Primary Commands - 4 (SPC-4) + +ANS Project INCITS 557 +Information technology - SCSI / ATA Translation - 5 (SAT-5) + + +Description +----------- + +This driver supports reporting the temperature of disk and solid state +drives with temperature sensors. + +If supported, it uses the ATA SCT Command Transport feature to read +the current drive temperature and, if available, temperature limits +as well as historic minimum and maximum temperatures. If SCT Command +Transport is not supported, the driver uses SMART attributes to read +the drive temperature. + + +Sysfs entries +------------- + +Only the temp1_input attribute is always available. Other attributes are +available only if reported by the drive. All temperatures are reported in +milli-degrees Celsius. + +======================= ===================================================== +temp1_input Current drive temperature +temp1_lcrit Minimum temperature limit. Operating the device below + this temperature may cause physical damage to the + device. +temp1_min Minimum recommended continuous operating limit +temp1_max Maximum recommended continuous operating temperature +temp1_crit Maximum temperature limit. Operating the device above + this temperature may cause physical damage to the + device. +temp1_lowest Minimum temperature seen this power cycle +temp1_highest Maximum temperature seen this power cycle +======================= ===================================================== diff --git a/Documentation/hwmon/index.rst b/Documentation/hwmon/index.rst index 43cc605741ea..b24adb67ddca 100644 --- a/Documentation/hwmon/index.rst +++ b/Documentation/hwmon/index.rst @@ -29,6 +29,7 @@ Hardware Monitoring Kernel Drivers adm1025 adm1026 adm1031 + adm1177 adm1275 adm9240 ads7828 @@ -47,6 +48,7 @@ Hardware Monitoring Kernel Drivers da9055 dell-smm-hwmon dme1737 + drivetemp ds1621 ds620 emc1403 @@ -106,8 +108,10 @@ Hardware Monitoring Kernel Drivers max1619 max1668 max197 + max20730 max20751 max31722 + max31730 max31785 max31790 max34440 @@ -177,6 +181,7 @@ Hardware Monitoring Kernel Drivers wm831x wm8350 xgene-hwmon + xdpe12284 zl6100 .. only:: subproject and html diff --git a/Documentation/hwmon/max20730.rst b/Documentation/hwmon/max20730.rst new file mode 100644 index 000000000000..cea7ae58c2f7 --- /dev/null +++ b/Documentation/hwmon/max20730.rst @@ -0,0 +1,74 @@ +.. SPDX-License-Identifier: GPL-2.0-or-later + +Kernel driver max20730 +====================== + +Supported chips: + + * Maxim MAX20730 + + Prefix: 'max20730' + + Addresses scanned: - + + Datasheet: https://datasheets.maximintegrated.com/en/ds/MAX20730.pdf + + * Maxim MAX20734 + + Prefix: 'max20734' + + Addresses scanned: - + + Datasheet: https://datasheets.maximintegrated.com/en/ds/MAX20734.pdf + + * Maxim MAX20743 + + Prefix: 'max20743' + + Addresses scanned: - + + Datasheet: https://datasheets.maximintegrated.com/en/ds/MAX20743.pdf + +Author: Guenter Roeck <linux@roeck-us.net> + + +Description +----------- + +This driver implements support for Maxim MAX20730, MAX20734, and MAX20743 +Integrated, Step-Down Switching Regulators with PMBus support. + +The driver is a client driver to the core PMBus driver. +Please see Documentation/hwmon/pmbus.rst for details on PMBus client drivers. + + +Usage Notes +----------- + +This driver does not auto-detect devices. You will have to instantiate the +devices explicitly. Please see Documentation/i2c/instantiating-devices.rst for +details. + + +Sysfs entries +------------- + +=================== ===== ======================================================= +curr1_crit RW/RO Critical output current. Please see datasheet for + supported limits. Read-only if the chip is + write protected; read-write otherwise. +curr1_crit_alarm RO Output current critical alarm +curr1_input RO Output current +curr1_label RO 'iout1' +in1_alarm RO Input voltage alarm +in1_input RO Input voltage +in1_label RO 'vin' +in2_alarm RO Output voltage alarm +in2_input RO Output voltage +in2_label RO 'vout1' +temp1_crit RW/RO Critical temeperature. Supported values are 130 or 150 + degrees C. Read-only if the chip is write protected; + read-write otherwise. +temp1_crit_alarm RO Temperature critical alarm +temp1_input RO Chip temperature +=================== ===== ======================================================= diff --git a/Documentation/hwmon/max31730.rst b/Documentation/hwmon/max31730.rst new file mode 100644 index 000000000000..def0de19dbd2 --- /dev/null +++ b/Documentation/hwmon/max31730.rst @@ -0,0 +1,44 @@ +Kernel driver max31790 +====================== + +Supported chips: + + * Maxim MAX31730 + + Prefix: 'max31730' + + Addresses scanned: 0x1c, 0x1d, 0x1e, 0x1f, 0x4c, 0x4d, 0x4e, 0x4f + + Datasheet: https://datasheets.maximintegrated.com/en/ds/MAX31730.pdf + +Author: Guenter Roeck <linux@roeck-us.net> + + +Description +----------- + +This driver implements support for Maxim MAX31730. + +The MAX31730 temperature sensor monitors its own temperature and the +temperatures of three external diode-connected transistors. The operating +supply voltage is from 3.0V to 3.6V. Resistance cancellation compensates +for high series resistance in circuit-board traces and the external thermal +diode, while beta compensation corrects for temperature-measurement +errors due to low-beta sensing transistors. + + +Sysfs entries +------------- + +=================== == ======================================================= +temp[1-4]_enable RW Temperature enable/disable + Set to 0 to enable channel, 0 to disable +temp[1-4]_input RO Temperature input +temp[2-4]_fault RO Fault indicator for remote channels +temp[1-4]_max RW Maximum temperature +temp[1-4]_max_alarm RW Maximum temperature alarm +temp[1-4]_min RW Minimum temperature. Common for all channels. + Only temp1_min is writeable. +temp[1-4]_min_alarm RO Minimum temperature alarm +temp[2-4]_offset RW Temperature offset for remote channels +=================== == ======================================================= diff --git a/Documentation/hwmon/pmbus.rst b/Documentation/hwmon/pmbus.rst index abfb9dd4857d..f787984e88a9 100644 --- a/Documentation/hwmon/pmbus.rst +++ b/Documentation/hwmon/pmbus.rst @@ -63,6 +63,16 @@ Supported chips: http://www.ti.com/lit/gpn/tps544c25 + * Maxim MAX20796 + + Prefix: 'max20796' + + Addresses scanned: - + + Datasheet: + + Not published + * Generic PMBus devices Prefix: 'pmbus' diff --git a/Documentation/hwmon/ucd9000.rst b/Documentation/hwmon/ucd9000.rst index 746f21fcb48c..704f0cbd95d3 100644 --- a/Documentation/hwmon/ucd9000.rst +++ b/Documentation/hwmon/ucd9000.rst @@ -3,9 +3,10 @@ Kernel driver ucd9000 Supported chips: - * TI UCD90120, UCD90124, UCD90160, UCD9090, and UCD90910 + * TI UCD90120, UCD90124, UCD90160, UCD90320, UCD9090, and UCD90910 - Prefixes: 'ucd90120', 'ucd90124', 'ucd90160', 'ucd9090', 'ucd90910' + Prefixes: 'ucd90120', 'ucd90124', 'ucd90160', 'ucd90320', 'ucd9090', + 'ucd90910' Addresses scanned: - @@ -14,6 +15,7 @@ Supported chips: - http://focus.ti.com/lit/ds/symlink/ucd90120.pdf - http://focus.ti.com/lit/ds/symlink/ucd90124.pdf - http://focus.ti.com/lit/ds/symlink/ucd90160.pdf + - http://focus.ti.com/lit/ds/symlink/ucd90320.pdf - http://focus.ti.com/lit/ds/symlink/ucd9090.pdf - http://focus.ti.com/lit/ds/symlink/ucd90910.pdf @@ -45,6 +47,12 @@ power-on reset signals, external interrupts, cascading, or other system functions. Twelve of these pins offer PWM functionality. Using these pins, the UCD90160 offers support for margining, and general-purpose PWM functions. +The UCD90320 is a 32-rail PMBus/I2C addressable power-supply sequencer and +monitor. The 24 integrated ADC channels (AMONx) monitor the power supply +voltage, current, and temperature. Of the 84 GPIO pins, 8 can be used as +digital monitors (DMONx), 32 to enable the power supply (ENx), 24 for margining +(MARx), 16 for logical GPO, and 32 GPIs for cascading, and system function. + The UCD9090 is a 10-rail PMBus/I2C addressable power-supply sequencer and monitor. The device integrates a 12-bit ADC for monitoring up to 10 power-supply voltage inputs. Twenty-three GPIO pins can be used for power supply enables, diff --git a/Documentation/hwmon/xdpe12284.rst b/Documentation/hwmon/xdpe12284.rst new file mode 100644 index 000000000000..67d1f87808e5 --- /dev/null +++ b/Documentation/hwmon/xdpe12284.rst @@ -0,0 +1,102 @@ +.. SPDX-License-Identifier: GPL-2.0 + +Kernel driver xdpe122 +===================== + +Supported chips: + + * Infineon XDPE12254 + + Prefix: 'xdpe12254' + + * Infineon XDPE12284 + + Prefix: 'xdpe12284' + +Authors: + + Vadim Pasternak <vadimp@mellanox.com> + +Description +----------- + +This driver implements support for Infineon Multi-phase XDPE122 family +dual loop voltage regulators. +The family includes XDPE12284 and XDPE12254 devices. +The devices from this family complaint with: + +- Intel VR13 and VR13HC rev 1.3, IMVP8 rev 1.2 and IMPVP9 rev 1.3 DC-DC + converter specification. +- Intel SVID rev 1.9. protocol. +- PMBus rev 1.3 interface. + +Devices support linear format for reading input voltage, input and output current, +input and output power and temperature. +Device supports VID format for reading output voltage. The below modes are +supported: +- VR12.0 mode, 5-mV DAC - 0x01. +- VR12.5 mode, 10-mV DAC - 0x02. +- IMVP9 mode, 5-mV DAC - 0x03. +- AMD mode 6.25mV - 0x10. + +Devices support two pages for telemetry. + +The driver provides for current: input, maximum and critical thresholds +and maximum and critical alarms. Critical thresholds and critical alarm are +supported only for current output. +The driver exports the following attributes for via the sysfs files, where +indexes 1, 2 are for "iin" and 3, 4 for "iout": + +**curr[3-4]_crit** + +**curr[3-4]_crit_alarm** + +**curr[1-4]_input** + +**curr[1-4]_label** + +**curr[1-4]_max** + +**curr[1-4]_max_alarm** + +The driver provides for voltage: input, critical and low critical thresholds +and critical and low critical alarms. +The driver exports the following attributes for via the sysfs files, where +indexes 1, 2 are for "vin" and 3, 4 for "vout": + +**in[1-4]_crit** + +**in[1-4_crit_alarm** + +**in[1-4]_input** + +**in[1-4_label** + +**in[1-4]_lcrit** + +**in[1-41_lcrit_alarm** + +The driver provides for power: input and alarms. Power alarm is supported only +for power input. +The driver exports the following attributes for via the sysfs files, where +indexes 1, 2 are for "pin" and 3, 4 for "pout": + +**power[1-2]_alarm** + +**power[1-4]_input** + +**power[1-4]_label** + +The driver provides for temperature: input, maximum and critical thresholds +and maximum and critical alarms. +The driver exports the following attributes for via the sysfs files: + +**temp[1-2]_crit** + +**temp[1-2]_crit_alarm** + +**temp[1-2]_input** + +**temp[1-2]_max** + +**temp[1-2]_max_alarm** diff --git a/Documentation/i2c/busses/i2c-parport-light.rst b/Documentation/i2c/busses/i2c-parport-light.rst deleted file mode 100644 index e73af975d2c8..000000000000 --- a/Documentation/i2c/busses/i2c-parport-light.rst +++ /dev/null @@ -1,24 +0,0 @@ -=============================== -Kernel driver i2c-parport-light -=============================== - -Author: Jean Delvare <jdelvare@suse.de> - -This driver is a light version of i2c-parport. It doesn't depend -on the parport driver, and uses direct I/O access instead. This might be -preferred on embedded systems where wasting memory for the clean but heavy -parport handling is not an option. The drawback is a reduced portability -and the impossibility to daisy-chain other parallel port devices. - -Please see i2c-parport for documentation. - -Module parameters: - -* type: type of adapter (see i2c-parport or modinfo) - -* base: base I/O address - Default is 0x378 which is fairly common for parallel ports, at least on PC. - -* irq: optional IRQ - This must be passed if you want SMBus alert support, assuming your adapter - actually supports this. diff --git a/Documentation/i2c/busses/index.rst b/Documentation/i2c/busses/index.rst index 2a26e251a335..5e4077b08d86 100644 --- a/Documentation/i2c/busses/index.rst +++ b/Documentation/i2c/busses/index.rst @@ -20,7 +20,6 @@ I2C Bus Drivers i2c-nforce2 i2c-nvidia-gpu i2c-ocores - i2c-parport-light i2c-parport i2c-pca-isa i2c-piix4 diff --git a/Documentation/i2c/dev-interface.rst b/Documentation/i2c/dev-interface.rst index 69c23a3c2b1b..bdb247f2f11a 100644 --- a/Documentation/i2c/dev-interface.rst +++ b/Documentation/i2c/dev-interface.rst @@ -1,27 +1,27 @@ -==================== -I2C Device Interface -==================== +============================================ +Implementing I2C device drivers in userspace +============================================ -Usually, i2c devices are controlled by a kernel driver. But it is also +Usually, I2C devices are controlled by a kernel driver. But it is also possible to access all devices on an adapter from userspace, through the /dev interface. You need to load module i2c-dev for this. -Each registered i2c adapter gets a number, counting from 0. You can +Each registered I2C adapter gets a number, counting from 0. You can examine /sys/class/i2c-dev/ to see what number corresponds to which adapter. Alternatively, you can run "i2cdetect -l" to obtain a formatted list of all -i2c adapters present on your system at a given time. i2cdetect is part of +I2C adapters present on your system at a given time. i2cdetect is part of the i2c-tools package. I2C device files are character device files with major device number 89 and a minor device number corresponding to the number assigned as explained above. They should be called "i2c-%d" (i2c-0, i2c-1, ..., -i2c-10, ...). All 256 minor device numbers are reserved for i2c. +i2c-10, ...). All 256 minor device numbers are reserved for I2C. C example ========= -So let's say you want to access an i2c adapter from a C program. +So let's say you want to access an I2C adapter from a C program. First, you need to include these two headers:: #include <linux/i2c-dev.h> @@ -66,7 +66,7 @@ the device supports them. Both are illustrated below:: /* Using SMBus commands */ res = i2c_smbus_read_word_data(file, reg); if (res < 0) { - /* ERROR HANDLING: i2c transaction failed */ + /* ERROR HANDLING: I2C transaction failed */ } else { /* res contains the read word */ } @@ -79,12 +79,12 @@ the device supports them. Both are illustrated below:: buf[1] = 0x43; buf[2] = 0x65; if (write(file, buf, 3) != 3) { - /* ERROR HANDLING: i2c transaction failed */ + /* ERROR HANDLING: I2C transaction failed */ } /* Using I2C Read, equivalent of i2c_smbus_read_byte(file) */ if (read(file, buf, 1) != 1) { - /* ERROR HANDLING: i2c transaction failed */ + /* ERROR HANDLING: I2C transaction failed */ } else { /* buf[0] contains the read byte */ } @@ -144,7 +144,7 @@ The following IOCTLs are defined: If possible, use the provided ``i2c_smbus_*`` methods described below instead of issuing direct ioctls. -You can do plain i2c transactions by using read(2) and write(2) calls. +You can do plain I2C transactions by using read(2) and write(2) calls. You do not need to pass the address byte; instead, set it through ioctl I2C_SLAVE before you try to access the device. diff --git a/Documentation/i2c/dma-considerations.rst b/Documentation/i2c/dma-considerations.rst index 203002054120..142d52ce9ebb 100644 --- a/Documentation/i2c/dma-considerations.rst +++ b/Documentation/i2c/dma-considerations.rst @@ -2,7 +2,7 @@ Linux I2C and DMA ================= -Given that i2c is a low-speed bus, over which the majority of messages +Given that I2C is a low-speed bus, over which the majority of messages transferred are small, it is not considered a prime user of DMA access. At this time of writing, only 10% of I2C bus master drivers have DMA support implemented. And the vast majority of transactions are so small that setting up diff --git a/Documentation/i2c/i2c-protocol.rst b/Documentation/i2c/i2c-protocol.rst index 2f8fcf671b2e..b2092f8f815d 100644 --- a/Documentation/i2c/i2c-protocol.rst +++ b/Documentation/i2c/i2c-protocol.rst @@ -1,26 +1,26 @@ -============ -I2C Protocol -============ +================ +The I2C Protocol +================ -This document describes the i2c protocol. Or will, when it is finished :-) +This document describes the I2C protocol. Or will, when it is finished :-) Key to symbols ============== =============== ============================================================= -S (1 bit) : Start bit -P (1 bit) : Stop bit -Rd/Wr (1 bit) : Read/Write bit. Rd equals 1, Wr equals 0. -A, NA (1 bit) : Accept and reverse accept bit. -Addr (7 bits): I2C 7 bit address. Note that this can be expanded as usual to +S Start condition +P Stop condition +Rd/Wr (1 bit) Read/Write bit. Rd equals 1, Wr equals 0. +A, NA (1 bit) Acknowledge (ACK) and Not Acknowledge (NACK) bit +Addr (7 bits) I2C 7 bit address. Note that this can be expanded as usual to get a 10 bit I2C address. -Comm (8 bits): Command byte, a data byte which often selects a register on +Comm (8 bits) Command byte, a data byte which often selects a register on the device. -Data (8 bits): A plain data byte. Sometimes, I write DataLow, DataHigh +Data (8 bits) A plain data byte. Sometimes, I write DataLow, DataHigh for 16 bit data. -Count (8 bits): A data byte containing the length of a block operation. +Count (8 bits) A data byte containing the length of a block operation. -[..]: Data sent by I2C device, as opposed to data sent by the +[..] Data sent by I2C device, as opposed to data sent by the host adapter. =============== ============================================================= @@ -28,7 +28,7 @@ Count (8 bits): A data byte containing the length of a block operation. Simple send transaction ======================= -This corresponds to i2c_master_send:: +Implemented by i2c_master_send():: S Addr Wr [A] Data [A] Data [A] ... [A] Data [A] P @@ -36,7 +36,7 @@ This corresponds to i2c_master_send:: Simple receive transaction ========================== -This corresponds to i2c_master_recv:: +Implemented by i2c_master_recv():: S Addr Rd [A] [Data] A [Data] A ... A [Data] NA P @@ -44,11 +44,11 @@ This corresponds to i2c_master_recv:: Combined transactions ===================== -This corresponds to i2c_transfer +Implemented by i2c_transfer(). -They are just like the above transactions, but instead of a stop bit P -a start bit S is sent and the transaction continues. An example of -a byte read, followed by a byte write:: +They are just like the above transactions, but instead of a stop +condition P a start condition S is sent and the transaction continues. +An example of a byte read, followed by a byte write:: S Addr Rd [A] [Data] NA S Addr Wr [A] Data [A] P @@ -57,7 +57,7 @@ Modified transactions ===================== The following modifications to the I2C protocol can also be generated by -setting these flags for i2c messages. With the exception of I2C_M_NOSTART, they +setting these flags for I2C messages. With the exception of I2C_M_NOSTART, they are usually only needed to work around device issues: I2C_M_IGNORE_NAK: @@ -77,8 +77,9 @@ I2C_M_NOSTART: S Addr Rd [A] [Data] NA Data [A] P If you set the I2C_M_NOSTART variable for the first partial message, - we do not generate Addr, but we do generate the startbit S. This will - probably confuse all other clients on your bus, so don't try this. + we do not generate Addr, but we do generate the start condition S. + This will probably confuse all other clients on your bus, so don't + try this. This is often used to gather transmits from multiple data buffers in system memory into something that appears as a single transfer to the diff --git a/Documentation/i2c/i2c-topology.rst b/Documentation/i2c/i2c-topology.rst index 0c1ae95f6a97..7cb53819778e 100644 --- a/Documentation/i2c/i2c-topology.rst +++ b/Documentation/i2c/i2c-topology.rst @@ -1,9 +1,9 @@ -============ -I2C topology -============ +================================ +I2C muxes and complex topologies +================================ -There are a couple of reasons for building more complex i2c topologies -than a straight-forward i2c bus with one adapter and one or more devices. +There are a couple of reasons for building more complex I2C topologies +than a straight-forward I2C bus with one adapter and one or more devices. 1. A mux may be needed on the bus to prevent address collisions. @@ -11,20 +11,20 @@ than a straight-forward i2c bus with one adapter and one or more devices. may be needed to determine if it is ok to access the bus. 3. A device (particularly RF tuners) may want to avoid the digital noise - from the i2c bus, at least most of the time, and sits behind a gate + from the I2C bus, at least most of the time, and sits behind a gate that has to be operated before the device can be accessed. Etc === -These constructs are represented as i2c adapter trees by Linux, where +These constructs are represented as I2C adapter trees by Linux, where each adapter has a parent adapter (except the root adapter) and zero or more child adapters. The root adapter is the actual adapter that issues -i2c transfers, and all adapters with a parent are part of an "i2c-mux" +I2C transfers, and all adapters with a parent are part of an "i2c-mux" object (quoted, since it can also be an arbitrator or a gate). Depending of the particular mux driver, something happens when there is -an i2c transfer on one of its child adapters. The mux driver can +an I2C transfer on one of its child adapters. The mux driver can obviously operate a mux, but it can also do arbitration with an external bus master or open a gate. The mux driver has two operations for this, select and deselect. select is called before the transfer and (the @@ -34,7 +34,7 @@ optional) deselect is called after the transfer. Locking ======= -There are two variants of locking available to i2c muxes, they can be +There are two variants of locking available to I2C muxes, they can be mux-locked or parent-locked muxes. As is evident from below, it can be useful to know if a mux is mux-locked or if it is parent-locked. The following list was correct at the time of writing: @@ -45,7 +45,7 @@ In drivers/i2c/muxes/: i2c-arb-gpio-challenge Parent-locked i2c-mux-gpio Normally parent-locked, mux-locked iff all involved gpio pins are controlled by the - same i2c root adapter that they mux. + same I2C root adapter that they mux. i2c-mux-gpmux Normally parent-locked, mux-locked iff specified in device-tree. i2c-mux-ltc4306 Mux-locked @@ -54,7 +54,7 @@ i2c-mux-pca9541 Parent-locked i2c-mux-pca954x Parent-locked i2c-mux-pinctrl Normally parent-locked, mux-locked iff all involved pinctrl devices are controlled - by the same i2c root adapter that they mux. + by the same I2C root adapter that they mux. i2c-mux-reg Parent-locked ====================== ============================================= @@ -83,9 +83,9 @@ Mux-locked muxes Mux-locked muxes does not lock the entire parent adapter during the full select-transfer-deselect transaction, only the muxes on the parent adapter are locked. Mux-locked muxes are mostly interesting if the -select and/or deselect operations must use i2c transfers to complete +select and/or deselect operations must use I2C transfers to complete their tasks. Since the parent adapter is not fully locked during the -full transaction, unrelated i2c transfers may interleave the different +full transaction, unrelated I2C transfers may interleave the different stages of the transaction. This has the benefit that the mux driver may be easier and cleaner to implement, but it has some caveats. @@ -109,14 +109,14 @@ ML2. It is not safe to build arbitrary topologies with two (or more) ML3. A mux-locked mux cannot be used by a driver for auto-closing gates/muxes, i.e. something that closes automatically after a given - number (one, in most cases) of i2c transfers. Unrelated i2c transfers + number (one, in most cases) of I2C transfers. Unrelated I2C transfers may creep in and close prematurely. -ML4. If any non-i2c operation in the mux driver changes the i2c mux state, +ML4. If any non-I2C operation in the mux driver changes the I2C mux state, the driver has to lock the root adapter during that operation. Otherwise garbage may appear on the bus as seen from devices - behind the mux, when an unrelated i2c transfer is in flight during - the non-i2c mux-changing operation. + behind the mux, when an unrelated I2C transfer is in flight during + the non-I2C mux-changing operation. ==== ===================================================================== @@ -137,14 +137,14 @@ Mux-locked Example When there is an access to D1, this happens: - 1. Someone issues an i2c-transfer to D1. + 1. Someone issues an I2C transfer to D1. 2. M1 locks muxes on its parent (the root adapter in this case). 3. M1 calls ->select to ready the mux. - 4. M1 (presumably) does some i2c-transfers as part of its select. - These transfers are normal i2c-transfers that locks the parent + 4. M1 (presumably) does some I2C transfers as part of its select. + These transfers are normal I2C transfers that locks the parent adapter. - 5. M1 feeds the i2c-transfer from step 1 to its parent adapter as a - normal i2c-transfer that locks the parent adapter. + 5. M1 feeds the I2C transfer from step 1 to its parent adapter as a + normal I2C transfer that locks the parent adapter. 6. M1 calls ->deselect, if it has one. 7. Same rules as in step 4, but for ->deselect. 8. M1 unlocks muxes on its parent. @@ -159,8 +159,8 @@ Parent-locked muxes Parent-locked muxes lock the parent adapter during the full select- transfer-deselect transaction. The implication is that the mux driver -has to ensure that any and all i2c transfers through that parent -adapter during the transaction are unlocked i2c transfers (using e.g. +has to ensure that any and all I2C transfers through that parent +adapter during the transaction are unlocked I2C transfers (using e.g. __i2c_transfer), or a deadlock will follow. There are a couple of caveats. @@ -169,12 +169,12 @@ PL1. If you build a topology with a parent-locked mux being the child of another mux, this might break a possible assumption from the child mux that the root adapter is unused between its select op and the actual transfer (e.g. if the child mux is auto-closing - and the parent mux issus i2c-transfers as part of its select). + and the parent mux issues I2C transfers as part of its select). This is especially the case if the parent mux is mux-locked, but it may also happen if the parent mux is parent-locked. PL2. If select/deselect calls out to other subsystems such as gpio, - pinctrl, regmap or iio, it is essential that any i2c transfers + pinctrl, regmap or iio, it is essential that any I2C transfers caused by these subsystems are unlocked. This can be convoluted to accomplish, maybe even impossible if an acceptably clean solution is sought. @@ -197,15 +197,15 @@ Parent-locked Example When there is an access to D1, this happens: - 1. Someone issues an i2c-transfer to D1. + 1. Someone issues an I2C transfer to D1. 2. M1 locks muxes on its parent (the root adapter in this case). 3. M1 locks its parent adapter. 4. M1 calls ->select to ready the mux. - 5. If M1 does any i2c-transfers (on this root adapter) as part of - its select, those transfers must be unlocked i2c-transfers so + 5. If M1 does any I2C transfers (on this root adapter) as part of + its select, those transfers must be unlocked I2C transfers so that they do not deadlock the root adapter. - 6. M1 feeds the i2c-transfer from step 1 to the root adapter as an - unlocked i2c-transfer, so that it does not deadlock the parent + 6. M1 feeds the I2C transfer from step 1 to the root adapter as an + unlocked I2C transfer, so that it does not deadlock the parent adapter. 7. M1 calls ->deselect, if it has one. 8. Same rules as in step 5, but for ->deselect. @@ -240,7 +240,7 @@ and specifically when M2 requests its parent to lock, M1 passes the buck to the root adapter). This topology is bad if M2 is an auto-closing mux and M1->select -issues any unlocked i2c transfers on the root adapter that may leak +issues any unlocked I2C transfers on the root adapter that may leak through and be seen by the M2 adapter, thus closing M2 prematurely. @@ -286,14 +286,14 @@ point. This kind of topology is generally not suitable and should probably be avoided. The reason is that M2 probably assumes that there will -be no i2c transfers during its calls to ->select and ->deselect, and +be no I2C transfers during its calls to ->select and ->deselect, and if there are, any such transfers might appear on the slave side of M2 -as partial i2c transfers, i.e. garbage or worse. This might cause +as partial I2C transfers, i.e. garbage or worse. This might cause device lockups and/or other problems. The topology is especially troublesome if M2 is an auto-closing mux. In that case, any interleaved accesses to D4 might close M2 -prematurely, as might any i2c-transfers part of M1->select. +prematurely, as might any I2C transfers part of M1->select. But if M2 is not making the above stated assumption, and if M2 is not auto-closing, the topology is fine. diff --git a/Documentation/i2c/i2c.svg b/Documentation/i2c/i2c.svg new file mode 100644 index 000000000000..5979405ad1c3 --- /dev/null +++ b/Documentation/i2c/i2c.svg @@ -0,0 +1,1341 @@ +<?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" + sodipodi:docname="i2c.svg" + inkscape:version="0.92.3 (2405546, 2018-03-11)" + version="1.1" + id="svg2" + viewBox="0 0 813.34215 261.01596" + height="73.664505mm" + width="229.54323mm"> + <defs + id="defs4"> + <marker + inkscape:stockid="DotM" + orient="auto" + refY="0" + refX="0" + id="marker8861" + style="overflow:visible" + inkscape:isstock="true"> + <path + inkscape:connector-curvature="0" + id="path8859" + d="m -2.5,-1 c 0,2.76 -2.24,5 -5,5 -2.76,0 -5,-2.24 -5,-5 0,-2.76 2.24,-5 5,-5 2.76,0 5,2.24 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,2.96,0.4)" /> + </marker> + <marker + inkscape:isstock="true" + style="overflow:visible" + id="marker6165" + refX="0" + refY="0" + orient="auto" + inkscape:stockid="DotM" + inkscape:collect="always"> + <path + transform="matrix(0.4,0,0,0.4,2.96,0.4)" + style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:1.00000003pt;stroke-opacity:1" + d="m -2.5,-1 c 0,2.76 -2.24,5 -5,5 -2.76,0 -5,-2.24 -5,-5 0,-2.76 2.24,-5 5,-5 2.76,0 5,2.24 5,5 z" + id="path6163" + inkscape:connector-curvature="0" /> + </marker> + <marker + inkscape:isstock="true" + style="overflow:visible" + id="marker2713" + refX="0" + refY="0" + orient="auto" + inkscape:stockid="DotM"> + <path + transform="matrix(0.4,0,0,0.4,2.96,0.4)" + style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:1.00000003pt;stroke-opacity:1" + d="m -2.5,-1 c 0,2.76 -2.24,5 -5,5 -2.76,0 -5,-2.24 -5,-5 0,-2.76 2.24,-5 5,-5 2.76,0 5,2.24 5,5 z" + id="path2711" + inkscape:connector-curvature="0" /> + </marker> + <marker + inkscape:stockid="DotM" + orient="auto" + refY="0" + refX="0" + id="DotM" + style="overflow:visible" + inkscape:isstock="true" + inkscape:collect="always"> + <path + id="path1795" + d="m -2.5,-1 c 0,2.76 -2.24,5 -5,5 -2.76,0 -5,-2.24 -5,-5 0,-2.76 2.24,-5 5,-5 2.76,0 5,2.24 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,2.96,0.4)" + inkscape:connector-curvature="0" /> + </marker> + <marker + inkscape:isstock="true" + style="overflow:visible" + id="marker6389" + refX="0" + refY="0" + orient="auto" + inkscape:stockid="Arrow2Mend"> + <path + transform="scale(-0.6)" + 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" + style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:0.625;stroke-linejoin:round;stroke-opacity:1" + id="path6387" + inkscape:connector-curvature="0" /> + </marker> + <marker + inkscape:stockid="TriangleOutM" + orient="auto" + refY="0" + refX="0" + id="TriangleOutM" + style="overflow:visible" + inkscape:isstock="true"> + <path + id="path4107" + d="M 5.77,0 -2.88,5 V -5 Z" + style="fill:#008000;fill-opacity:1;fill-rule:evenodd;stroke:#008000;stroke-width:1.00000003pt;stroke-opacity:1" + transform="scale(0.4)" + inkscape:connector-curvature="0" /> + </marker> + <marker + inkscape:stockid="TriangleOutL" + orient="auto" + refY="0" + refX="0" + id="marker5333" + style="overflow:visible" + inkscape:isstock="true"> + <path + id="path5335" + d="M 5.77,0 -2.88,5 V -5 Z" + style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:1.00000003pt;stroke-opacity:1" + transform="scale(0.8)" + inkscape:connector-curvature="0" /> + </marker> + <marker + inkscape:stockid="TriangleOutL" + orient="auto" + refY="0" + refX="0" + id="TriangleOutL" + style="overflow:visible" + inkscape:isstock="true"> + <path + id="path5049" + d="M 5.77,0 -2.88,5 V -5 Z" + style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:1.00000003pt;stroke-opacity:1" + transform="scale(0.8)" + inkscape:connector-curvature="0" /> + </marker> + <marker + inkscape:stockid="DotS" + orient="auto" + refY="0" + refX="0" + id="DotS" + style="overflow:visible" + inkscape:isstock="true"> + <path + id="path9326" + d="m -2.5,-1 c 0,2.76 -2.24,5 -5,5 -2.76,0 -5,-2.24 -5,-5 0,-2.76 2.24,-5 5,-5 2.76,0 5,2.24 5,5 z" + style="fill:#404040;fill-opacity:1;fill-rule:evenodd;stroke:#404040;stroke-width:1.00000003pt;stroke-opacity:1" + transform="matrix(0.2,0,0,0.2,1.48,0.2)" + inkscape:connector-curvature="0" /> + </marker> + <marker + inkscape:stockid="Arrow2Mstart" + orient="auto" + refY="0" + refX="0" + id="Arrow2Mstart" + style="overflow:visible" + inkscape:isstock="true"> + <path + id="path9283" + style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:0.625;stroke-linejoin:round;stroke-opacity:1" + 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)" + inkscape:connector-curvature="0" /> + </marker> + <marker + inkscape:stockid="Arrow2Mend" + orient="auto" + refY="0" + refX="0" + id="marker9095" + style="overflow:visible" + inkscape:isstock="true"> + <path + id="path9097" + style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:0.625;stroke-linejoin:round;stroke-opacity:1" + 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)" + inkscape:connector-curvature="0" /> + </marker> + <marker + inkscape:stockid="Arrow2Mend" + orient="auto" + refY="0" + refX="0" + id="marker8935" + style="overflow:visible" + inkscape:isstock="true"> + <path + id="path8937" + style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:0.625;stroke-linejoin:round;stroke-opacity:1" + 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)" + inkscape:connector-curvature="0" /> + </marker> + <marker + inkscape:stockid="Arrow2Mend" + orient="auto" + refY="0" + refX="0" + id="marker8781" + style="overflow:visible" + inkscape:isstock="true"> + <path + id="path8783" + style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:0.625;stroke-linejoin:round;stroke-opacity:1" + 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)" + inkscape:connector-curvature="0" /> + </marker> + <marker + inkscape:stockid="Arrow2Lend" + orient="auto" + refY="0" + refX="0" + id="Arrow2Lend" + style="overflow:visible" + inkscape:isstock="true"> + <path + id="path4700" + style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:0.625;stroke-linejoin:round;stroke-opacity:1" + 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="EmptyTriangleOutL" + orient="auto" + refY="0" + refX="0" + id="EmptyTriangleOutL" + style="overflow:visible" + inkscape:isstock="true"> + <path + id="path4502" + d="M 5.77,0 -2.88,5 V -5 Z" + style="fill:#ffffff;fill-rule:evenodd;stroke:#000000;stroke-width:1.00000003pt;stroke-opacity:1" + transform="matrix(0.8,0,0,0.8,-4.8,0)" + inkscape:connector-curvature="0" /> + </marker> + <marker + inkscape:stockid="EmptyTriangleOutL" + orient="auto" + refY="0" + refX="0" + id="EmptyTriangleOutL-4" + style="overflow:visible" + inkscape:isstock="true"> + <path + inkscape:connector-curvature="0" + id="path4502-7" + d="M 5.77,0 -2.88,5 V -5 Z" + style="fill:#ffffff;fill-rule:evenodd;stroke:#000000;stroke-width:1.00000003pt;stroke-opacity:1" + transform="matrix(0.8,0,0,0.8,-4.8,0)" /> + </marker> + <marker + inkscape:stockid="EmptyTriangleOutL" + orient="auto" + refY="0" + refX="0" + id="EmptyTriangleOutL-4-4" + style="overflow:visible" + inkscape:isstock="true"> + <path + inkscape:connector-curvature="0" + id="path4502-7-5" + d="M 5.77,0 -2.88,5 V -5 Z" + style="fill:#ffffff;fill-rule:evenodd;stroke:#000000;stroke-width:1.00000003pt;stroke-opacity:1" + transform="matrix(0.8,0,0,0.8,-4.8,0)" /> + </marker> + <marker + inkscape:stockid="EmptyTriangleOutL" + orient="auto" + refY="0" + refX="0" + id="EmptyTriangleOutL-7" + style="overflow:visible" + inkscape:isstock="true"> + <path + inkscape:connector-curvature="0" + id="path4502-5" + d="M 5.77,0 -2.88,5 V -5 Z" + style="fill:#ffffff;fill-rule:evenodd;stroke:#000000;stroke-width:1.00000003pt;stroke-opacity:1" + transform="matrix(0.8,0,0,0.8,-4.8,0)" /> + </marker> + <marker + inkscape:stockid="EmptyTriangleOutL" + orient="auto" + refY="0" + refX="0" + id="EmptyTriangleOutL-6" + style="overflow:visible" + inkscape:isstock="true"> + <path + inkscape:connector-curvature="0" + id="path4502-2" + d="M 5.77,0 -2.88,5 V -5 Z" + style="fill:#ffffff;fill-rule:evenodd;stroke:#000000;stroke-width:1.00000003pt;stroke-opacity:1" + transform="matrix(0.8,0,0,0.8,-4.8,0)" /> + </marker> + <marker + inkscape:stockid="EmptyTriangleOutL" + orient="auto" + refY="0" + refX="0" + id="EmptyTriangleOutL-78" + style="overflow:visible" + inkscape:isstock="true"> + <path + inkscape:connector-curvature="0" + id="path4502-57" + d="M 5.77,0 -2.88,5 V -5 Z" + style="fill:#ffffff;fill-rule:evenodd;stroke:#000000;stroke-width:1.00000003pt;stroke-opacity:1" + transform="matrix(0.8,0,0,0.8,-4.8,0)" /> + </marker> + <marker + inkscape:stockid="EmptyTriangleOutL" + orient="auto" + refY="0" + refX="0" + id="EmptyTriangleOutL-1" + style="overflow:visible" + inkscape:isstock="true"> + <path + inkscape:connector-curvature="0" + id="path4502-8" + d="M 5.77,0 -2.88,5 V -5 Z" + style="fill:#ffffff;fill-rule:evenodd;stroke:#000000;stroke-width:1.00000003pt;stroke-opacity:1" + transform="matrix(0.8,0,0,0.8,-4.8,0)" /> + </marker> + <marker + inkscape:stockid="EmptyTriangleOutL" + orient="auto" + refY="0" + refX="0" + id="EmptyTriangleOutL-9" + style="overflow:visible" + inkscape:isstock="true"> + <path + inkscape:connector-curvature="0" + id="path4502-75" + d="M 5.77,0 -2.88,5 V -5 Z" + style="fill:#ffffff;fill-rule:evenodd;stroke:#000000;stroke-width:1.00000003pt;stroke-opacity:1" + transform="matrix(0.8,0,0,0.8,-4.8,0)" /> + </marker> + <marker + inkscape:stockid="EmptyTriangleOutL" + orient="auto" + refY="0" + refX="0" + id="EmptyTriangleOutL-78-2" + style="overflow:visible" + inkscape:isstock="true"> + <path + inkscape:connector-curvature="0" + id="path4502-57-6" + d="M 5.77,0 -2.88,5 V -5 Z" + style="fill:#ffffff;fill-rule:evenodd;stroke:#000000;stroke-width:1.00000003pt;stroke-opacity:1" + transform="matrix(0.8,0,0,0.8,-4.8,0)" /> + </marker> + <marker + inkscape:stockid="Arrow2Mend" + orient="auto" + refY="0" + refX="0" + id="Arrow2Mend-3" + style="overflow:visible" + inkscape:isstock="true"> + <path + inkscape:connector-curvature="0" + id="path4369-6" + style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:0.625;stroke-linejoin:round;stroke-opacity:1" + 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)" /> + </marker> + <marker + inkscape:stockid="Arrow2Mend" + orient="auto" + refY="0" + refX="0" + id="Arrow2Mend-3-5" + style="overflow:visible" + inkscape:isstock="true"> + <path + inkscape:connector-curvature="0" + id="path4369-6-3" + style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:0.625;stroke-linejoin:round;stroke-opacity:1" + 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)" /> + </marker> + <marker + inkscape:stockid="Arrow2Mend" + orient="auto" + refY="0" + refX="0" + id="Arrow2Mend-3-5-6" + style="overflow:visible" + inkscape:isstock="true"> + <path + inkscape:connector-curvature="0" + id="path4369-6-3-2" + style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:0.625;stroke-linejoin:round;stroke-opacity:1" + 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)" /> + </marker> + <marker + inkscape:stockid="Arrow2Mend" + orient="auto" + refY="0" + refX="0" + id="Arrow2Mend-3-5-6-1" + style="overflow:visible" + inkscape:isstock="true"> + <path + inkscape:connector-curvature="0" + id="path4369-6-3-2-2" + style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:0.625;stroke-linejoin:round;stroke-opacity:1" + 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)" /> + </marker> + <marker + inkscape:stockid="Arrow2Mend" + orient="auto" + refY="0" + refX="0" + id="Arrow2Mend-3-5-7" + style="overflow:visible" + inkscape:isstock="true"> + <path + inkscape:connector-curvature="0" + id="path4369-6-3-0" + style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:0.625;stroke-linejoin:round;stroke-opacity:1" + 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)" /> + </marker> + <marker + inkscape:stockid="Arrow2Mend" + orient="auto" + refY="0" + refX="0" + id="Arrow2Mend-3-9" + style="overflow:visible" + inkscape:isstock="true"> + <path + inkscape:connector-curvature="0" + id="path4369-6-36" + style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:0.625;stroke-linejoin:round;stroke-opacity:1" + 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)" /> + </marker> + <marker + inkscape:stockid="Arrow2Mend" + orient="auto" + refY="0" + refX="0" + id="Arrow2Mend-31" + style="overflow:visible" + inkscape:isstock="true"> + <path + inkscape:connector-curvature="0" + id="path4369-9" + style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:0.625;stroke-linejoin:round;stroke-opacity:1" + 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)" /> + </marker> + <marker + inkscape:stockid="Arrow2Mend" + orient="auto" + refY="0" + refX="0" + id="Arrow2Mend-3-5-7-5" + style="overflow:visible" + inkscape:isstock="true"> + <path + inkscape:connector-curvature="0" + id="path4369-6-3-0-4" + style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:0.625;stroke-linejoin:round;stroke-opacity:1" + 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)" /> + </marker> + <marker + inkscape:stockid="Arrow2Mend" + orient="auto" + refY="0" + refX="0" + id="Arrow2Mend-3-9-6" + style="overflow:visible" + inkscape:isstock="true"> + <path + inkscape:connector-curvature="0" + id="path4369-6-36-5" + style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:0.625;stroke-linejoin:round;stroke-opacity:1" + 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)" /> + </marker> + <marker + inkscape:stockid="Arrow2Mend" + orient="auto" + refY="0" + refX="0" + id="Arrow2Mend-3-5-7-3" + style="overflow:visible" + inkscape:isstock="true"> + <path + inkscape:connector-curvature="0" + id="path4369-6-3-0-5" + style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:0.625;stroke-linejoin:round;stroke-opacity:1" + 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)" /> + </marker> + <marker + inkscape:stockid="Arrow2Mend" + orient="auto" + refY="0" + refX="0" + id="marker9095-3" + style="overflow:visible" + inkscape:isstock="true"> + <path + inkscape:connector-curvature="0" + id="path9097-1" + style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:0.625;stroke-linejoin:round;stroke-opacity:1" + 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)" /> + </marker> + <marker + inkscape:stockid="Arrow2Mend" + orient="auto" + refY="0" + refX="0" + id="marker9095-3-7" + style="overflow:visible" + inkscape:isstock="true"> + <path + inkscape:connector-curvature="0" + id="path9097-1-8" + style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:0.625;stroke-linejoin:round;stroke-opacity:1" + 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)" /> + </marker> + <marker + inkscape:stockid="Arrow2Mend" + orient="auto" + refY="0" + refX="0" + id="marker9095-1-5" + style="overflow:visible" + inkscape:isstock="true"> + <path + inkscape:connector-curvature="0" + id="path9097-2-0" + style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:0.625;stroke-linejoin:round;stroke-opacity:1" + 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)" /> + </marker> + <marker + inkscape:stockid="Arrow2Mend" + orient="auto" + refY="0" + refX="0" + id="marker9095-1-5-6" + style="overflow:visible" + inkscape:isstock="true"> + <path + inkscape:connector-curvature="0" + id="path9097-2-0-1" + style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:0.625;stroke-linejoin:round;stroke-opacity:1" + 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)" /> + </marker> + <marker + inkscape:stockid="Arrow2Mend" + orient="auto" + refY="0" + refX="0" + id="marker9095-1-5-6-6" + style="overflow:visible" + inkscape:isstock="true"> + <path + inkscape:connector-curvature="0" + id="path9097-2-0-1-3" + style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:0.625;stroke-linejoin:round;stroke-opacity:1" + 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)" /> + </marker> + <marker + inkscape:stockid="Arrow2Mend" + orient="auto" + refY="0" + refX="0" + id="marker9095-1-5-2" + style="overflow:visible" + inkscape:isstock="true"> + <path + inkscape:connector-curvature="0" + id="path9097-2-0-0" + style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:0.625;stroke-linejoin:round;stroke-opacity:1" + 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)" /> + </marker> + <marker + inkscape:stockid="Arrow2Mend" + orient="auto" + refY="0" + refX="0" + id="marker9095-1-5-6-5" + style="overflow:visible" + inkscape:isstock="true"> + <path + inkscape:connector-curvature="0" + id="path9097-2-0-1-5" + style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:0.625;stroke-linejoin:round;stroke-opacity:1" + 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)" /> + </marker> + <marker + inkscape:stockid="Arrow2Mend" + orient="auto" + refY="0" + refX="0" + id="marker9095-1-5-4" + style="overflow:visible" + inkscape:isstock="true"> + <path + inkscape:connector-curvature="0" + id="path9097-2-0-7" + style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:0.625;stroke-linejoin:round;stroke-opacity:1" + 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)" /> + </marker> + <marker + inkscape:stockid="Arrow2Mend" + orient="auto" + refY="0" + refX="0" + id="marker9095-1-5-6-5-9" + style="overflow:visible" + inkscape:isstock="true"> + <path + inkscape:connector-curvature="0" + id="path9097-2-0-1-5-3" + style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:0.625;stroke-linejoin:round;stroke-opacity:1" + 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)" /> + </marker> + <marker + inkscape:stockid="Arrow2Mend" + orient="auto" + refY="0" + refX="0" + id="marker9095-1-5-6-5-4" + style="overflow:visible" + inkscape:isstock="true"> + <path + inkscape:connector-curvature="0" + id="path9097-2-0-1-5-5" + style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:0.625;stroke-linejoin:round;stroke-opacity:1" + 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)" /> + </marker> + <marker + inkscape:stockid="Arrow2Mend" + orient="auto" + refY="0" + refX="0" + id="marker9095-1-5-6-5-4-4" + style="overflow:visible" + inkscape:isstock="true"> + <path + inkscape:connector-curvature="0" + id="path9097-2-0-1-5-5-3" + style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:0.625;stroke-linejoin:round;stroke-opacity:1" + 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)" /> + </marker> + <marker + inkscape:stockid="Arrow2Mend" + orient="auto" + refY="0" + refX="0" + id="marker9095-1-5-6-5-4-4-9" + style="overflow:visible" + inkscape:isstock="true"> + <path + inkscape:connector-curvature="0" + id="path9097-2-0-1-5-5-3-2" + style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:0.625;stroke-linejoin:round;stroke-opacity:1" + 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)" /> + </marker> + <marker + inkscape:stockid="Arrow2Mend" + orient="auto" + refY="0" + refX="0" + id="marker9095-1-5-6-5-4-4-6" + style="overflow:visible" + inkscape:isstock="true"> + <path + inkscape:connector-curvature="0" + id="path9097-2-0-1-5-5-3-8" + style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:0.625;stroke-linejoin:round;stroke-opacity:1" + 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)" /> + </marker> + <marker + inkscape:stockid="Arrow2Mend" + orient="auto" + refY="0" + refX="0" + id="marker9095-1-5-6-5-4-4-2" + style="overflow:visible" + inkscape:isstock="true"> + <path + inkscape:connector-curvature="0" + id="path9097-2-0-1-5-5-3-7" + style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:0.625;stroke-linejoin:round;stroke-opacity:1" + 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)" /> + </marker> + <marker + inkscape:stockid="Arrow2Mend" + orient="auto" + refY="0" + refX="0" + id="marker9095-1-5-3" + style="overflow:visible" + inkscape:isstock="true"> + <path + inkscape:connector-curvature="0" + id="path9097-2-0-6" + style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:0.625;stroke-linejoin:round;stroke-opacity:1" + 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)" /> + </marker> + <marker + inkscape:stockid="Arrow2Mend" + orient="auto" + refY="0" + refX="0" + id="marker9095-1-5-6-5-4-4-6-5" + style="overflow:visible" + inkscape:isstock="true"> + <path + inkscape:connector-curvature="0" + id="path9097-2-0-1-5-5-3-8-3" + style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:0.625;stroke-linejoin:round;stroke-opacity:1" + 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)" /> + </marker> + <marker + inkscape:stockid="Arrow2Mend" + orient="auto" + refY="0" + refX="0" + id="marker9095-1-5-27" + style="overflow:visible" + inkscape:isstock="true"> + <path + inkscape:connector-curvature="0" + id="path9097-2-0-09" + style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:0.625;stroke-linejoin:round;stroke-opacity:1" + 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)" /> + </marker> + <marker + inkscape:stockid="Arrow2Mend" + orient="auto" + refY="0" + refX="0" + id="marker9095-1-5-27-6" + style="overflow:visible" + inkscape:isstock="true"> + <path + inkscape:connector-curvature="0" + id="path9097-2-0-09-2" + style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:0.625;stroke-linejoin:round;stroke-opacity:1" + 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)" /> + </marker> + <marker + inkscape:stockid="Arrow2Mend" + orient="auto" + refY="0" + refX="0" + id="marker9095-1-5-27-0" + style="overflow:visible" + inkscape:isstock="true"> + <path + inkscape:connector-curvature="0" + id="path9097-2-0-09-23" + style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:0.625;stroke-linejoin:round;stroke-opacity:1" + 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)" /> + </marker> + <marker + inkscape:stockid="Arrow2Mend" + orient="auto" + refY="0" + refX="0" + id="marker9095-1-9" + style="overflow:visible" + inkscape:isstock="true"> + <path + inkscape:connector-curvature="0" + id="path9097-2-7" + style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:0.625;stroke-linejoin:round;stroke-opacity:1" + 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)" /> + </marker> + <marker + inkscape:stockid="Arrow2Mend" + orient="auto" + refY="0" + refX="0" + id="marker9095-1-5-4-6" + style="overflow:visible" + inkscape:isstock="true"> + <path + inkscape:connector-curvature="0" + id="path9097-2-0-7-7" + style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:0.625;stroke-linejoin:round;stroke-opacity:1" + 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)" /> + </marker> + <marker + inkscape:stockid="Arrow2Mend" + orient="auto" + refY="0" + refX="0" + id="marker9095-1-5-4-6-3" + style="overflow:visible" + inkscape:isstock="true"> + <path + inkscape:connector-curvature="0" + id="path9097-2-0-7-7-5" + style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:0.625;stroke-linejoin:round;stroke-opacity:1" + 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)" /> + </marker> + <marker + inkscape:stockid="Arrow2Mend" + orient="auto" + refY="0" + refX="0" + id="marker9095-1-5-4-6-2" + style="overflow:visible" + inkscape:isstock="true"> + <path + inkscape:connector-curvature="0" + id="path9097-2-0-7-7-9" + style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:0.625;stroke-linejoin:round;stroke-opacity:1" + 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)" /> + </marker> + <marker + inkscape:stockid="TriangleOutM" + orient="auto" + refY="0" + refX="0" + id="TriangleOutM-2" + style="overflow:visible" + inkscape:isstock="true"> + <path + inkscape:connector-curvature="0" + id="path4107-7" + d="M 5.77,0 -2.88,5 V -5 Z" + style="fill:#008000;fill-opacity:1;fill-rule:evenodd;stroke:#008000;stroke-width:1.00000003pt;stroke-opacity:1" + transform="scale(0.4)" /> + </marker> + <marker + inkscape:stockid="Arrow2Mstart" + orient="auto" + refY="0" + refX="0" + id="Arrow2Mstart-9" + style="overflow:visible" + inkscape:isstock="true"> + <path + inkscape:connector-curvature="0" + id="path9283-3" + style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:0.625;stroke-linejoin:round;stroke-opacity:1" + 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)" /> + </marker> + <marker + inkscape:stockid="Arrow2Mend" + orient="auto" + refY="0" + refX="0" + id="marker9095-1-5-4-6-6" + style="overflow:visible" + inkscape:isstock="true"> + <path + inkscape:connector-curvature="0" + id="path9097-2-0-7-7-0" + style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:0.625;stroke-linejoin:round;stroke-opacity:1" + 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)" /> + </marker> + <marker + inkscape:stockid="DotM" + orient="auto" + refY="0" + refX="0" + id="DotM-3" + style="overflow:visible" + inkscape:isstock="true"> + <path + inkscape:connector-curvature="0" + id="path1795-7" + d="m -2.5,-1 c 0,2.76 -2.24,5 -5,5 -2.76,0 -5,-2.24 -5,-5 0,-2.76 2.24,-5 5,-5 2.76,0 5,2.24 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,2.96,0.4)" /> + </marker> + <marker + inkscape:isstock="true" + style="overflow:visible" + id="marker2713-9" + refX="0" + refY="0" + orient="auto" + inkscape:stockid="DotM"> + <path + inkscape:connector-curvature="0" + transform="matrix(0.4,0,0,0.4,2.96,0.4)" + style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:1.00000003pt;stroke-opacity:1" + d="m -2.5,-1 c 0,2.76 -2.24,5 -5,5 -2.76,0 -5,-2.24 -5,-5 0,-2.76 2.24,-5 5,-5 2.76,0 5,2.24 5,5 z" + id="path2711-2" /> + </marker> + <marker + inkscape:stockid="DotM" + orient="auto" + refY="0" + refX="0" + id="DotM-2" + style="overflow:visible" + inkscape:isstock="true" + inkscape:collect="always"> + <path + inkscape:connector-curvature="0" + id="path1795-8" + d="m -2.5,-1 c 0,2.76 -2.24,5 -5,5 -2.76,0 -5,-2.24 -5,-5 0,-2.76 2.24,-5 5,-5 2.76,0 5,2.24 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,2.96,0.4)" /> + </marker> + <marker + inkscape:isstock="true" + style="overflow:visible" + id="marker2713-3" + refX="0" + refY="0" + orient="auto" + inkscape:stockid="DotM"> + <path + inkscape:connector-curvature="0" + transform="matrix(0.4,0,0,0.4,2.96,0.4)" + style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:1.00000003pt;stroke-opacity:1" + d="m -2.5,-1 c 0,2.76 -2.24,5 -5,5 -2.76,0 -5,-2.24 -5,-5 0,-2.76 2.24,-5 5,-5 2.76,0 5,2.24 5,5 z" + id="path2711-6" /> + </marker> + <marker + inkscape:stockid="DotM" + orient="auto" + refY="0" + refX="0" + id="DotM-1" + style="overflow:visible" + inkscape:isstock="true" + inkscape:collect="always"> + <path + inkscape:connector-curvature="0" + id="path1795-2" + d="m -2.5,-1 c 0,2.76 -2.24,5 -5,5 -2.76,0 -5,-2.24 -5,-5 0,-2.76 2.24,-5 5,-5 2.76,0 5,2.24 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,2.96,0.4)" /> + </marker> + <marker + inkscape:isstock="true" + style="overflow:visible" + id="marker2713-94" + refX="0" + refY="0" + orient="auto" + inkscape:stockid="DotM"> + <path + inkscape:connector-curvature="0" + transform="matrix(0.4,0,0,0.4,2.96,0.4)" + style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:1.00000003pt;stroke-opacity:1" + d="m -2.5,-1 c 0,2.76 -2.24,5 -5,5 -2.76,0 -5,-2.24 -5,-5 0,-2.76 2.24,-5 5,-5 2.76,0 5,2.24 5,5 z" + id="path2711-7" /> + </marker> + <marker + inkscape:stockid="DotM" + orient="auto" + refY="0" + refX="0" + id="DotM-8" + style="overflow:visible" + inkscape:isstock="true" + inkscape:collect="always"> + <path + inkscape:connector-curvature="0" + id="path1795-4" + d="m -2.5,-1 c 0,2.76 -2.24,5 -5,5 -2.76,0 -5,-2.24 -5,-5 0,-2.76 2.24,-5 5,-5 2.76,0 5,2.24 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,2.96,0.4)" /> + </marker> + <marker + inkscape:isstock="true" + style="overflow:visible" + id="marker2713-36" + refX="0" + refY="0" + orient="auto" + inkscape:stockid="DotM"> + <path + inkscape:connector-curvature="0" + transform="matrix(0.4,0,0,0.4,2.96,0.4)" + style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:1.00000003pt;stroke-opacity:1" + d="m -2.5,-1 c 0,2.76 -2.24,5 -5,5 -2.76,0 -5,-2.24 -5,-5 0,-2.76 2.24,-5 5,-5 2.76,0 5,2.24 5,5 z" + id="path2711-1" /> + </marker> + <marker + inkscape:isstock="true" + style="overflow:visible" + id="marker6165-5" + refX="0" + refY="0" + orient="auto" + inkscape:stockid="DotM"> + <path + transform="matrix(0.4,0,0,0.4,2.96,0.4)" + style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:1.00000003pt;stroke-opacity:1" + d="m -2.5,-1 c 0,2.76 -2.24,5 -5,5 -2.76,0 -5,-2.24 -5,-5 0,-2.76 2.24,-5 5,-5 2.76,0 5,2.24 5,5 z" + id="path6163-5" + inkscape:connector-curvature="0" /> + </marker> + </defs> + <sodipodi:namedview + showguides="true" + inkscape:window-maximized="1" + inkscape:window-y="0" + inkscape:window-x="0" + inkscape:window-height="1015" + inkscape:window-width="1920" + showgrid="true" + inkscape:current-layer="layer1" + inkscape:document-units="px" + inkscape:cy="214.66765" + inkscape:cx="-167.56857" + inkscape:zoom="0.70710678" + inkscape:pageshadow="2" + inkscape:pageopacity="0.0" + borderopacity="1.0" + bordercolor="#666666" + pagecolor="#ffffff" + id="base" + inkscape:snap-to-guides="true" + inkscape:snap-grids="true" + inkscape:snap-bbox="false" + inkscape:object-nodes="true" + fit-margin-top="5" + fit-margin-left="5" + fit-margin-right="5" + fit-margin-bottom="5"> + <inkscape:grid + type="xygrid" + id="grid4451" + originx="-93.377219" + originy="-347.2523" /> + </sodipodi:namedview> + <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> + <dc:creator> + <cc:Agent> + <dc:title>Luca Ceresoli</dc:title> + </cc:Agent> + </dc:creator> + <dc:date>2020</dc:date> + <cc:license + rdf:resource="http://creativecommons.org/licenses/by-sa/4.0/" /> + </cc:Work> + <cc:License + rdf:about="http://creativecommons.org/licenses/by-sa/4.0/"> + <cc:permits + rdf:resource="http://creativecommons.org/ns#Reproduction" /> + <cc:permits + rdf:resource="http://creativecommons.org/ns#Distribution" /> + <cc:requires + rdf:resource="http://creativecommons.org/ns#Notice" /> + <cc:requires + rdf:resource="http://creativecommons.org/ns#Attribution" /> + <cc:permits + rdf:resource="http://creativecommons.org/ns#DerivativeWorks" /> + <cc:requires + rdf:resource="http://creativecommons.org/ns#ShareAlike" /> + </cc:License> + </rdf:RDF> + </metadata> + <g + inkscape:label="Livello 1" + inkscape:groupmode="layer" + id="layer1" + transform="translate(-93.377215,-444.09395)"> + <rect + style="opacity:1;fill:#ffb9b9;fill-opacity:1;stroke:#f00000;stroke-width:2.8125;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1" + id="rect4424-3-2-9-7" + width="112.5" + height="113.75008" + x="112.5" + y="471.11221" + rx="0" + ry="0" /> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" + x="167.5354" + y="521.46259" + id="text4349"><tspan + sodipodi:role="line" + x="167.5354" + y="521.46259" + style="font-size:25px;line-height:1.25;font-family:sans-serif;text-align:center;text-anchor:middle" + id="tspan1273">I2C</tspan><tspan + sodipodi:role="line" + x="167.5354" + y="552.71259" + style="font-size:25px;line-height:1.25;font-family:sans-serif;text-align:center;text-anchor:middle" + id="tspan1285">Master</tspan></text> + <rect + style="color:#000000;clip-rule:nonzero;display:inline;overflow:visible;visibility:visible;opacity:1;isolation:auto;mix-blend-mode:normal;color-interpolation:sRGB;color-interpolation-filters:linearRGB;solid-color:#000000;solid-opacity:1;fill:#b9ffb9;fill-opacity:1;fill-rule:nonzero;stroke:#006400;stroke-width:2.8125;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1;color-rendering:auto;image-rendering:auto;shape-rendering:auto;text-rendering:auto;enable-background:accumulate" + id="rect4424-3-2-9-7-3-3-5-3" + width="112.49998" + height="112.50001" + x="262.5" + y="471.11218" + rx="0" + ry="0" /> + <path + style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1.99968767;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1" + d="m 112.50002,639.86223 c 712.50002,0 712.50002,0 712.50002,0" + id="path4655-9-3-65-5-6" + inkscape:connector-curvature="0" /> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:12px;line-height:0%;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" + x="318.59131" + y="520.83752" + id="text4349-26"><tspan + sodipodi:role="line" + x="318.59131" + y="520.83752" + style="font-size:25.00000191px;line-height:1.25;font-family:sans-serif;text-align:center;text-anchor:middle;stroke-width:1px" + id="tspan1273-8">I2C</tspan><tspan + sodipodi:role="line" + x="318.59131" + y="552.08752" + style="font-size:25.00000191px;line-height:1.25;font-family:sans-serif;text-align:center;text-anchor:middle;stroke-width:1px" + id="tspan1287">Slave</tspan></text> + <path + style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1.99968767;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1" + d="m 112.49995,677.36223 c 712.50005,0 712.50005,0 712.50005,0" + id="path4655-9-3-65-5-6-2" + inkscape:connector-curvature="0" /> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:12px;line-height:0%;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" + x="861.07312" + y="687.03937" + id="text4349-7"><tspan + sodipodi:role="line" + x="861.07312" + y="687.03937" + style="font-size:25.00000191px;line-height:1.25;font-family:sans-serif;text-align:center;writing-mode:lr-tb;direction:ltr;text-anchor:middle;stroke-width:1px" + id="tspan1285-9">SCL</tspan></text> + <flowRoot + xml:space="preserve" + id="flowRoot1627" + style="font-style:normal;font-weight:normal;font-size:40px;line-height:125%;font-family:Sans;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"><flowRegion + id="flowRegion1629"><rect + id="rect1631" + width="220" + height="120" + x="140" + y="-126.29921" /></flowRegion><flowPara + id="flowPara1633" /></flowRoot> <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:12px;line-height:0%;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" + x="863.31921" + y="648.96735" + id="text4349-7-3"><tspan + sodipodi:role="line" + x="863.31921" + y="648.96735" + style="font-size:25.00000191px;line-height:1.25;font-family:sans-serif;text-align:center;text-anchor:middle;stroke-width:1px" + id="tspan1285-9-6">SDA</tspan></text> + <rect + style="color:#000000;clip-rule:nonzero;display:inline;overflow:visible;visibility:visible;opacity:1;isolation:auto;mix-blend-mode:normal;color-interpolation:sRGB;color-interpolation-filters:linearRGB;solid-color:#000000;solid-opacity:1;vector-effect:none;fill:#b9ffb9;fill-opacity:1;fill-rule:nonzero;stroke:#006400;stroke-width:2.8125;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1;color-rendering:auto;image-rendering:auto;shape-rendering:auto;text-rendering:auto;enable-background:accumulate" + id="rect4424-3-2-9-7-3-3-5-3-0" + width="112.49998" + height="112.50002" + x="412.5" + y="471.11215" + rx="0" + ry="0" /> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:12px;line-height:0%;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" + x="468.59131" + y="520.83746" + id="text4349-26-6"><tspan + sodipodi:role="line" + x="468.59131" + y="520.83746" + style="font-size:25.00000191px;line-height:1.25;font-family:sans-serif;text-align:center;text-anchor:middle;stroke-width:1px" + id="tspan1273-8-2">I2C</tspan><tspan + sodipodi:role="line" + x="468.59131" + y="552.08746" + style="font-size:25.00000191px;line-height:1.25;font-family:sans-serif;text-align:center;text-anchor:middle;stroke-width:1px" + id="tspan1287-6">Slave</tspan></text> + <rect + style="color:#000000;clip-rule:nonzero;display:inline;overflow:visible;visibility:visible;opacity:1;isolation:auto;mix-blend-mode:normal;color-interpolation:sRGB;color-interpolation-filters:linearRGB;solid-color:#000000;solid-opacity:1;vector-effect:none;fill:#b9ffb9;fill-opacity:1;fill-rule:nonzero;stroke:#006400;stroke-width:2.8125;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1;color-rendering:auto;image-rendering:auto;shape-rendering:auto;text-rendering:auto;enable-background:accumulate" + id="rect4424-3-2-9-7-3-3-5-3-1" + width="112.49998" + height="112.50002" + x="562.5" + y="471.11215" + rx="0" + ry="0" /> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:12px;line-height:0%;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" + x="618.59131" + y="520.83746" + id="text4349-26-8"><tspan + sodipodi:role="line" + x="618.59131" + y="520.83746" + style="font-size:25.00000191px;line-height:1.25;font-family:sans-serif;text-align:center;text-anchor:middle;stroke-width:1px" + id="tspan1273-8-7">I2C</tspan><tspan + sodipodi:role="line" + x="618.59131" + y="552.08746" + style="font-size:25.00000191px;line-height:1.25;font-family:sans-serif;text-align:center;text-anchor:middle;stroke-width:1px" + id="tspan1287-9">Slave</tspan></text> + <path + style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1.99968743;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1;marker-end:url(#DotM)" + d="m 150,583.61221 v 93.75" + id="path4655-9-3-65-5-6-20" + inkscape:connector-curvature="0" + sodipodi:nodetypes="cc" /> + <path + style="opacity:1;vector-effect:none;fill:none;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:1.99968743;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1;marker-end:url(#marker2713)" + d="m 187.5,583.61221 v 56.25" + id="path4655-9-3-65-5-6-20-2" + inkscape:connector-curvature="0" + sodipodi:nodetypes="cc" /> + <path + style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1.99968743;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1;marker-end:url(#DotM-2)" + d="m 300,583.61221 v 93.75" + id="path4655-9-3-65-5-6-20-9" + inkscape:connector-curvature="0" + sodipodi:nodetypes="cc" /> + <path + style="opacity:1;vector-effect:none;fill:none;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:1.99968743;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1;marker-end:url(#marker2713-9)" + d="m 337.5,583.61221 v 56.25" + id="path4655-9-3-65-5-6-20-2-7" + inkscape:connector-curvature="0" + sodipodi:nodetypes="cc" /> + <path + style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1.99968743;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1;marker-end:url(#DotM-1)" + d="m 450,583.61221 v 93.75" + id="path4655-9-3-65-5-6-20-93" + inkscape:connector-curvature="0" + sodipodi:nodetypes="cc" /> + <path + style="opacity:1;vector-effect:none;fill:none;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:1.99968743;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1;marker-end:url(#marker2713-3)" + d="m 487.5,583.61221 v 56.25" + id="path4655-9-3-65-5-6-20-2-1" + inkscape:connector-curvature="0" + sodipodi:nodetypes="cc" /> + <path + style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1.99968743;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1;marker-end:url(#DotM-8)" + d="m 600,583.61221 v 93.75" + id="path4655-9-3-65-5-6-20-5" + inkscape:connector-curvature="0" + sodipodi:nodetypes="cc" /> + <path + style="opacity:1;vector-effect:none;fill:none;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:1.99968743;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1;marker-end:url(#marker2713-94)" + d="m 637.5,583.61221 v 56.25" + id="path4655-9-3-65-5-6-20-2-0" + inkscape:connector-curvature="0" + sodipodi:nodetypes="cc" /> + <path + style="opacity:1;vector-effect:none;fill:none;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:1.99968743;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1;marker-start:url(#marker6165);marker-end:url(#marker6165)" + d="m 750,471.11221 v 28.125 l 9.375,9.375 -18.74999,18.75 18.74999,18.75 -18.74999,18.75 18.74999,18.75 -9.375,9.375 v 28.125 0 0 56.25" + id="path6135" + inkscape:connector-curvature="0" + sodipodi:nodetypes="cccccccccccc" /> + <path + style="opacity:1;vector-effect:none;fill:none;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:1.99968743;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1;marker-start:url(#marker8861);marker-end:url(#marker6165-5)" + d="m 787.49999,471.11221 v 28.125 l 9.375,9.375 -18.74999,18.75 18.74999,18.75 -18.74999,18.75 18.74999,18.75 -9.375,9.375 v 28.125 0 0 18.75001" + id="path6135-4" + inkscape:connector-curvature="0" + sodipodi:nodetypes="cccccccccccc" /> + <path + style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1.99968719;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1" + d="m 712.5,471.11221 c 112.49999,0 112.49999,0 112.49999,0" + id="path4655-9-3-65-5-6-7" + inkscape:connector-curvature="0" /> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:12px;line-height:0%;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" + x="859.94275" + y="480.03558" + id="text4349-7-3-6"><tspan + sodipodi:role="line" + x="859.94275" + y="480.03558" + style="font-size:25.00000191px;line-height:1.25;font-family:sans-serif;text-align:center;text-anchor:middle;stroke-width:1px" + id="tspan1285-9-6-5">V<tspan + style="font-size:64.99999762%;baseline-shift:sub" + id="tspan9307">DD</tspan></tspan></text> + </g> +</svg> diff --git a/Documentation/i2c/index.rst b/Documentation/i2c/index.rst index a0fbaf6d0675..fee4744475df 100644 --- a/Documentation/i2c/index.rst +++ b/Documentation/i2c/index.rst @@ -4,30 +4,66 @@ I2C/SMBus Subsystem =================== +Introduction +============ + .. toctree:: :maxdepth: 1 + summary + i2c-protocol + smbus-protocol + instantiating-devices + busses/index + i2c-topology + muxes/i2c-mux-gpio + +Writing device drivers +====================== + +.. toctree:: + :maxdepth: 1 + + writing-clients dev-interface dma-considerations fault-codes functionality + +Debugging +========= + +.. toctree:: + :maxdepth: 1 + gpio-fault-injection - i2c-protocol i2c-stub - i2c-topology - instantiating-devices - old-module-parameters - slave-eeprom-backend + +Slave I2C +========= + +.. toctree:: + :maxdepth: 1 + slave-interface - smbus-protocol - summary + slave-eeprom-backend + +Advanced topics +=============== + +.. toctree:: + :maxdepth: 1 + ten-bit-addresses - upgrading-clients - writing-clients - muxes/i2c-mux-gpio +Legacy documentation +==================== - busses/index +.. toctree:: + :maxdepth: 1 + + upgrading-clients + old-module-parameters .. only:: subproject and html diff --git a/Documentation/i2c/instantiating-devices.rst b/Documentation/i2c/instantiating-devices.rst index 875ebe9e78e3..e558e0a77e0c 100644 --- a/Documentation/i2c/instantiating-devices.rst +++ b/Documentation/i2c/instantiating-devices.rst @@ -9,54 +9,27 @@ reason, the kernel code must instantiate I2C devices explicitly. There are several ways to achieve this, depending on the context and requirements. -Method 1a: Declare the I2C devices by bus number ------------------------------------------------- +Method 1: Declare the I2C devices statically +-------------------------------------------- This method is appropriate when the I2C bus is a system bus as is the case -for many embedded systems. On such systems, each I2C bus has a number -which is known in advance. It is thus possible to pre-declare the I2C -devices which live on this bus. This is done with an array of struct -i2c_board_info which is registered by calling i2c_register_board_info(). +for many embedded systems. On such systems, each I2C bus has a number which +is known in advance. It is thus possible to pre-declare the I2C devices +which live on this bus. -Example (from omap2 h4):: +This information is provided to the kernel in a different way on different +architectures: device tree, ACPI or board files. - static struct i2c_board_info h4_i2c_board_info[] __initdata = { - { - I2C_BOARD_INFO("isp1301_omap", 0x2d), - .irq = OMAP_GPIO_IRQ(125), - }, - { /* EEPROM on mainboard */ - I2C_BOARD_INFO("24c01", 0x52), - .platform_data = &m24c01, - }, - { /* EEPROM on cpu card */ - I2C_BOARD_INFO("24c01", 0x57), - .platform_data = &m24c01, - }, - }; - - static void __init omap_h4_init(void) - { - (...) - i2c_register_board_info(1, h4_i2c_board_info, - ARRAY_SIZE(h4_i2c_board_info)); - (...) - } - -The above code declares 3 devices on I2C bus 1, including their respective -addresses and custom data needed by their drivers. When the I2C bus in -question is registered, the I2C devices will be instantiated automatically -by i2c-core. +When the I2C bus in question is registered, the I2C devices will be +instantiated automatically by i2c-core. The devices will be automatically +unbound and destroyed when the I2C bus they sit on goes away (if ever). -The devices will be automatically unbound and destroyed when the I2C bus -they sit on goes away (if ever.) +Declare the I2C devices via devicetree +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Method 1b: Declare the I2C devices via devicetree -------------------------------------------------- - -This method has the same implications as method 1a. The declaration of I2C -devices is here done via devicetree as subnodes of the master controller. +On platforms using devicetree, the declaration of I2C devices is done in +subnodes of the master controller. Example:: @@ -82,11 +55,49 @@ additional properties which might be needed to set up the device, please refer to its devicetree documentation in Documentation/devicetree/bindings/. -Method 1c: Declare the I2C devices via ACPI -------------------------------------------- +Declare the I2C devices via ACPI +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ACPI can also describe I2C devices. There is special documentation for this -which is currently located at Documentation/firmware-guide/acpi/enumeration.rst. +which is currently located at :doc:`../firmware-guide/acpi/enumeration`. + + +Declare the I2C devices in board files +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +In many embedded architectures, devicetree has replaced the old hardware +description based on board files, but the latter are still used in old +code. Instantiating I2C devices via board files is done with an array of +struct i2c_board_info which is registered by calling +i2c_register_board_info(). + +Example (from omap2 h4):: + + static struct i2c_board_info h4_i2c_board_info[] __initdata = { + { + I2C_BOARD_INFO("isp1301_omap", 0x2d), + .irq = OMAP_GPIO_IRQ(125), + }, + { /* EEPROM on mainboard */ + I2C_BOARD_INFO("24c01", 0x52), + .platform_data = &m24c01, + }, + { /* EEPROM on cpu card */ + I2C_BOARD_INFO("24c01", 0x57), + .platform_data = &m24c01, + }, + }; + + static void __init omap_h4_init(void) + { + (...) + i2c_register_board_info(1, h4_i2c_board_info, + ARRAY_SIZE(h4_i2c_board_info)); + (...) + } + +The above code declares 3 devices on I2C bus 1, including their respective +addresses and custom data needed by their drivers. Method 2: Instantiate the devices explicitly @@ -98,7 +109,7 @@ tuner, a video decoder, an audio decoder, etc. usually connected to the main chip by the means of an I2C bus. You won't know the number of the I2C bus in advance, so the method 1 described above can't be used. Instead, you can instantiate your I2C devices explicitly. This is done by filling -a struct i2c_board_info and calling i2c_new_device(). +a struct i2c_board_info and calling i2c_new_client_device(). Example (from the sfe4001 network driver):: @@ -110,7 +121,7 @@ Example (from the sfe4001 network driver):: { (...) efx->board_info.hwmon_client = - i2c_new_device(&efx->i2c_adap, &sfe4001_hwmon_info); + i2c_new_client_device(&efx->i2c_adap, &sfe4001_hwmon_info); (...) } @@ -123,7 +134,7 @@ present or not (for example for an optional feature which is not present on cheap variants of a board but you have no way to tell them apart), or it may have different addresses from one board to the next (manufacturer changing its design without notice). In this case, you can call -i2c_new_scanned_device() instead of i2c_new_device(). +i2c_new_scanned_device() instead of i2c_new_client_device(). Example (from the nxp OHCI driver):: @@ -152,7 +163,7 @@ simply gives up. The driver which instantiated the I2C device is responsible for destroying it on cleanup. This is done by calling i2c_unregister_device() on the -pointer that was earlier returned by i2c_new_device() or +pointer that was earlier returned by i2c_new_client_device() or i2c_new_scanned_device(). @@ -188,7 +199,7 @@ destroyed automatically when the driver which detected them is removed, or when the underlying I2C bus is itself destroyed, whichever happens first. -Those of you familiar with the i2c subsystem of 2.4 kernels and early 2.6 +Those of you familiar with the I2C subsystem of 2.4 kernels and early 2.6 kernels will find out that this method 3 is essentially similar to what was done there. Two significant differences are: @@ -214,15 +225,15 @@ In general, the kernel should know which I2C devices are connected and what addresses they live at. However, in certain cases, it does not, so a sysfs interface was added to let the user provide the information. This interface is made of 2 attribute files which are created in every I2C bus -directory: new_device and delete_device. Both files are write only and you -must write the right parameters to them in order to properly instantiate, -respectively delete, an I2C device. +directory: ``new_device`` and ``delete_device``. Both files are write +only and you must write the right parameters to them in order to properly +instantiate, respectively delete, an I2C device. -File new_device takes 2 parameters: the name of the I2C device (a string) -and the address of the I2C device (a number, typically expressed in -hexadecimal starting with 0x, but can also be expressed in decimal.) +File ``new_device`` takes 2 parameters: the name of the I2C device (a +string) and the address of the I2C device (a number, typically expressed +in hexadecimal starting with 0x, but can also be expressed in decimal.) -File delete_device takes a single parameter: the address of the I2C +File ``delete_device`` takes a single parameter: the address of the I2C device. As no two devices can live at the same address on a given I2C segment, the address is sufficient to uniquely identify the device to be deleted. diff --git a/Documentation/i2c/old-module-parameters.rst b/Documentation/i2c/old-module-parameters.rst index a1939512ad66..38e55829dee8 100644 --- a/Documentation/i2c/old-module-parameters.rst +++ b/Documentation/i2c/old-module-parameters.rst @@ -1,19 +1,24 @@ -================================================= -I2C device driver binding control from user-space -================================================= +================================================================ +I2C device driver binding control from user-space in old kernels +================================================================ -Up to kernel 2.6.32, many i2c drivers used helper macros provided by +.. NOTE:: + Note: this section is only relevant if you are handling some old code + found in kernel 2.6. If you work with more recent kernels, you can + safely skip this section. + +Up to kernel 2.6.32, many I2C drivers used helper macros provided by <linux/i2c.h> which created standard module parameters to let the user -control how the driver would probe i2c buses and attach to devices. These -parameters were known as "probe" (to let the driver probe for an extra -address), "force" (to forcibly attach the driver to a given device) and -"ignore" (to prevent a driver from probing a given address). +control how the driver would probe I2C buses and attach to devices. These +parameters were known as ``probe`` (to let the driver probe for an extra +address), ``force`` (to forcibly attach the driver to a given device) and +``ignore`` (to prevent a driver from probing a given address). -With the conversion of the i2c subsystem to the standard device driver +With the conversion of the I2C subsystem to the standard device driver binding model, it became clear that these per-module parameters were no longer needed, and that a centralized implementation was possible. The new, -sysfs-based interface is described in the documentation file -"instantiating-devices", section "Method 4: Instantiate from user-space". +sysfs-based interface is described in :doc:`instantiating-devices`, section +"Method 4: Instantiate from user-space". Below is a mapping from the old module parameters to the new interface. @@ -42,8 +47,8 @@ New method (sysfs interface):: # echo dummy 0x2f > /sys/bus/i2c/devices/i2c-1/new_device # modprobe <driver> -Of course, it is important to instantiate the "dummy" device before loading +Of course, it is important to instantiate the ``dummy`` device before loading the driver. The dummy device will be handled by i2c-core itself, preventing other drivers from binding to it later on. If there is a real device at the problematic address, and you want another driver to bind to it, then simply -pass the name of the device in question instead of "dummy". +pass the name of the device in question instead of ``dummy``. diff --git a/Documentation/i2c/slave-interface.rst b/Documentation/i2c/slave-interface.rst index c769bd6a15bf..82ea3e1d6fe4 100644 --- a/Documentation/i2c/slave-interface.rst +++ b/Documentation/i2c/slave-interface.rst @@ -59,7 +59,7 @@ The bus driver sends an event to the backend using the following function:: ret = i2c_slave_event(client, event, &val) -'client' describes the i2c slave device. 'event' is one of the special event +'client' describes the I2C slave device. 'event' is one of the special event types described hereafter. 'val' holds an u8 value for the data byte to be read/written and is thus bidirectional. The pointer to val must always be provided even if val is not used for an event, i.e. don't use NULL here. 'ret' @@ -143,7 +143,7 @@ Bus driver support If you want to add slave support to the bus driver: * implement calls to register/unregister the slave and add those to the - struct i2c_algorithm. When registering, you probably need to set the i2c + struct i2c_algorithm. When registering, you probably need to set the I2C slave address and enable slave specific interrupts. If you use runtime pm, you should use pm_runtime_get_sync() because your device usually needs to be powered on always to be able to detect its slave address. When unregistering, diff --git a/Documentation/i2c/smbus-protocol.rst b/Documentation/i2c/smbus-protocol.rst index e30eb1d274c6..c122ed239f7f 100644 --- a/Documentation/i2c/smbus-protocol.rst +++ b/Documentation/i2c/smbus-protocol.rst @@ -1,6 +1,6 @@ -====================== -SMBus Protocol Summary -====================== +================== +The SMBus Protocol +================== The following is a summary of the SMBus protocol. It applies to all revisions of the protocol (1.0, 1.1, and 2.0). @@ -27,27 +27,27 @@ a different protocol operation entirely. Each transaction type corresponds to a functionality flag. Before calling a transaction function, a device driver should always check (just once) for the corresponding functionality flag to ensure that the underlying I2C -adapter supports the transaction in question. See -<file:Documentation/i2c/functionality.rst> for the details. +adapter supports the transaction in question. See :doc:`functionality` for +the details. Key to symbols ============== =============== ============================================================= -S (1 bit) : Start bit -P (1 bit) : Stop bit -Rd/Wr (1 bit) : Read/Write bit. Rd equals 1, Wr equals 0. -A, NA (1 bit) : Accept and reverse accept bit. -Addr (7 bits): I2C 7 bit address. Note that this can be expanded as usual to +S Start condition +P Stop condition +Rd/Wr (1 bit) Read/Write bit. Rd equals 1, Wr equals 0. +A, NA (1 bit) Acknowledge (ACK) and Not Acknowledge (NACK) bit +Addr (7 bits) I2C 7 bit address. Note that this can be expanded as usual to get a 10 bit I2C address. -Comm (8 bits): Command byte, a data byte which often selects a register on +Comm (8 bits) Command byte, a data byte which often selects a register on the device. -Data (8 bits): A plain data byte. Sometimes, I write DataLow, DataHigh +Data (8 bits) A plain data byte. Sometimes, I write DataLow, DataHigh for 16 bit data. -Count (8 bits): A data byte containing the length of a block operation. +Count (8 bits) A data byte containing the length of a block operation. -[..]: Data sent by I2C device, as opposed to data sent by the host +[..] Data sent by I2C device, as opposed to data sent by the host adapter. =============== ============================================================= @@ -62,8 +62,10 @@ This sends a single bit to the device, at the place of the Rd/Wr bit:: Functionality flag: I2C_FUNC_SMBUS_QUICK -SMBus Receive Byte: i2c_smbus_read_byte() -========================================== +SMBus Receive Byte +================== + +Implemented by i2c_smbus_read_byte() This reads a single byte from a device, without specifying a device register. Some devices are so simple that this interface is enough; for @@ -75,8 +77,10 @@ the previous SMBus command:: Functionality flag: I2C_FUNC_SMBUS_READ_BYTE -SMBus Send Byte: i2c_smbus_write_byte() -======================================== +SMBus Send Byte +=============== + +Implemented by i2c_smbus_write_byte() This operation is the reverse of Receive Byte: it sends a single byte to a device. See Receive Byte for more information. @@ -88,8 +92,10 @@ to a device. See Receive Byte for more information. Functionality flag: I2C_FUNC_SMBUS_WRITE_BYTE -SMBus Read Byte: i2c_smbus_read_byte_data() -============================================ +SMBus Read Byte +=============== + +Implemented by i2c_smbus_read_byte_data() This reads a single byte from a device, from a designated register. The register is specified through the Comm byte:: @@ -99,8 +105,10 @@ The register is specified through the Comm byte:: Functionality flag: I2C_FUNC_SMBUS_READ_BYTE_DATA -SMBus Read Word: i2c_smbus_read_word_data() -============================================ +SMBus Read Word +=============== + +Implemented by i2c_smbus_read_word_data() This operation is very like Read Byte; again, data is read from a device, from a designated register that is specified through the Comm @@ -110,13 +118,15 @@ byte. But this time, the data is a complete word (16 bits):: Functionality flag: I2C_FUNC_SMBUS_READ_WORD_DATA -Note the convenience function i2c_smbus_read_word_swapped is +Note the convenience function i2c_smbus_read_word_swapped() is available for reads where the two data bytes are the other way around (not SMBus compliant, but very popular.) -SMBus Write Byte: i2c_smbus_write_byte_data() -============================================== +SMBus Write Byte +================ + +Implemented by i2c_smbus_write_byte_data() This writes a single byte to a device, to a designated register. The register is specified through the Comm byte. This is the opposite of @@ -129,24 +139,26 @@ the Read Byte operation. Functionality flag: I2C_FUNC_SMBUS_WRITE_BYTE_DATA -SMBus Write Word: i2c_smbus_write_word_data() -============================================== +SMBus Write Word +================ + +Implemented by i2c_smbus_write_word_data() This is the opposite of the Read Word operation. 16 bits -of data is written to a device, to the designated register that is -specified through the Comm byte.:: +of data are written to a device, to the designated register that is +specified through the Comm byte:: S Addr Wr [A] Comm [A] DataLow [A] DataHigh [A] P Functionality flag: I2C_FUNC_SMBUS_WRITE_WORD_DATA -Note the convenience function i2c_smbus_write_word_swapped is +Note the convenience function i2c_smbus_write_word_swapped() is available for writes where the two data bytes are the other way around (not SMBus compliant, but very popular.) -SMBus Process Call: -=================== +SMBus Process Call +================== This command selects a device register (through the Comm byte), sends 16 bits of data to it, and reads 16 bits of data in return:: @@ -157,8 +169,10 @@ This command selects a device register (through the Comm byte), sends Functionality flag: I2C_FUNC_SMBUS_PROC_CALL -SMBus Block Read: i2c_smbus_read_block_data() -============================================== +SMBus Block Read +================ + +Implemented by i2c_smbus_read_block_data() This command reads a block of up to 32 bytes from a device, from a designated register that is specified through the Comm byte. The amount @@ -172,8 +186,10 @@ of data is specified by the device in the Count byte. Functionality flag: I2C_FUNC_SMBUS_READ_BLOCK_DATA -SMBus Block Write: i2c_smbus_write_block_data() -================================================ +SMBus Block Write +================= + +Implemented by i2c_smbus_write_block_data() The opposite of the Block Read command, this writes up to 32 bytes to a device, to a designated register that is specified through the @@ -266,16 +282,19 @@ This is implemented the following way in the Linux kernel: I2C Block Transactions ====================== -The following I2C block transactions are supported by the -SMBus layer and are described here for completeness. -They are *NOT* defined by the SMBus specification. +The following I2C block transactions are similar to the SMBus Block Read +and Write operations, except these do not have a Count byte. They are +supported by the SMBus layer and are described here for completeness, but +they are *NOT* defined by the SMBus specification. I2C block transactions do not limit the number of bytes transferred but the SMBus layer places a limit of 32 bytes. -I2C Block Read: i2c_smbus_read_i2c_block_data() -================================================ +I2C Block Read +============== + +Implemented by i2c_smbus_read_i2c_block_data() This command reads a block of bytes from a device, from a designated register that is specified through the Comm byte:: @@ -286,8 +305,10 @@ designated register that is specified through the Comm byte:: Functionality flag: I2C_FUNC_SMBUS_READ_I2C_BLOCK -I2C Block Write: i2c_smbus_write_i2c_block_data() -================================================== +I2C Block Write +=============== + +Implemented by i2c_smbus_write_i2c_block_data() The opposite of the Block Read command, this writes bytes to a device, to a designated register that is specified through the diff --git a/Documentation/i2c/summary.rst b/Documentation/i2c/summary.rst index 3a24eac17375..ce7230025b33 100644 --- a/Documentation/i2c/summary.rst +++ b/Documentation/i2c/summary.rst @@ -1,13 +1,19 @@ -============= -I2C and SMBus -============= - -I2C (pronounce: I squared C) is a protocol developed by Philips. It is a -slow two-wire protocol (variable speed, up to 400 kHz), with a high speed -extension (3.4 MHz). It provides an inexpensive bus for connecting many -types of devices with infrequent or low bandwidth communications needs. -I2C is widely used with embedded systems. Some systems use variants that -don't meet branding requirements, and so are not advertised as being I2C. +============================= +Introduction to I2C and SMBus +============================= + +I²C (pronounce: I squared C and written I2C in the kernel documentation) is +a protocol developed by Philips. It is a slow two-wire protocol (variable +speed, up to 400 kHz), with a high speed extension (3.4 MHz). It provides +an inexpensive bus for connecting many types of devices with infrequent or +low bandwidth communications needs. I2C is widely used with embedded +systems. Some systems use variants that don't meet branding requirements, +and so are not advertised as being I2C but come under different names, +e.g. TWI (Two Wire Interface), IIC. + +The official I2C specification is the `"I2C-bus specification and user +manual" (UM10204) <https://www.nxp.com/docs/en/user-guide/UM10204.pdf>`_ +published by NXP Semiconductors. SMBus (System Management Bus) is based on the I2C protocol, and is mostly a subset of I2C protocols and signaling. Many I2C devices will work on an @@ -25,21 +31,29 @@ implement all the common SMBus protocol semantics or messages. Terminology =========== -When we talk about I2C, we use the following terms:: +Using the terminology from the official documentation, the I2C bus connects +one or more *master* chips and one or more *slave* chips. + +.. kernel-figure:: i2c.svg + :alt: Simple I2C bus with one master and 3 slaves + + Simple I2C bus - Bus -> Algorithm - Adapter - Device -> Driver - Client +A **master** chip is a node that starts communications with slaves. In the +Linux kernel implementation it is called an **adapter** or bus. Adapter +drivers are in the ``drivers/i2c/busses/`` subdirectory. -An Algorithm driver contains general code that can be used for a whole class -of I2C adapters. Each specific adapter driver either depends on one algorithm -driver, or includes its own implementation. +An **algorithm** contains general code that can be used to implement a +whole class of I2C adapters. Each specific adapter driver either depends on +an algorithm driver in the ``drivers/i2c/algos/`` subdirectory, or includes +its own implementation. -A Driver driver (yes, this sounds ridiculous, sorry) contains the general -code to access some type of device. Each detected device gets its own -data in the Client structure. Usually, Driver and Client are more closely -integrated than Algorithm and Adapter. +A **slave** chip is a node that responds to communications when addressed +by the master. In Linux it is called a **client**. Client drivers are kept +in a directory specific to the feature they provide, for example +``drivers/media/gpio/`` for GPIO expanders and ``drivers/media/i2c/`` for +video-related chips. -For a given configuration, you will need a driver for your I2C bus, and -drivers for your I2C devices (usually one driver for each device). +For the example configuration in figure, you will need a driver for your +I2C adapter, and drivers for your I2C devices (usually one driver for each +device). diff --git a/Documentation/i2c/writing-clients.rst b/Documentation/i2c/writing-clients.rst index ced309b5e0cc..978cc8210bf3 100644 --- a/Documentation/i2c/writing-clients.rst +++ b/Documentation/i2c/writing-clients.rst @@ -1,6 +1,6 @@ -=================== -Writing I2C Clients -=================== +=============================== +Implementing I2C device drivers +=============================== This is a small guide for those who want to write kernel drivers for I2C or SMBus devices, using Linux as the protocol host/master (not slave). @@ -95,7 +95,7 @@ to gather information from the client, or write new information to the client. I have found it useful to define foo_read and foo_write functions for this. -For some cases, it will be easier to call the i2c functions directly, +For some cases, it will be easier to call the I2C functions directly, but many chips have some kind of register-value idea that can easily be encapsulated. @@ -175,8 +175,8 @@ Device Creation If you know for a fact that an I2C device is connected to a given I2C bus, you can instantiate that device by simply filling an i2c_board_info structure with the device address and driver name, and calling -i2c_new_device(). This will create the device, then the driver core will -take care of finding the right driver and will call its probe() method. +i2c_new_client_device(). This will create the device, then the driver core +will take care of finding the right driver and will call its probe() method. If a driver supports different device types, you can specify the type you want using the type field. You can also specify an IRQ and platform data if needed. @@ -186,14 +186,14 @@ don't know the exact address it uses. This happens on TV adapters for example, where the same driver supports dozens of slightly different models, and I2C device addresses change from one model to the next. In that case, you can use the i2c_new_scanned_device() variant, which is -similar to i2c_new_device(), except that it takes an additional list of -possible I2C addresses to probe. A device is created for the first +similar to i2c_new_client_device(), except that it takes an additional list +of possible I2C addresses to probe. A device is created for the first responsive address in the list. If you expect more than one device to be present in the address range, simply call i2c_new_scanned_device() that many times. -The call to i2c_new_device() or i2c_new_scanned_device() typically happens -in the I2C bus driver. You may want to save the returned i2c_client +The call to i2c_new_client_device() or i2c_new_scanned_device() typically +happens in the I2C bus driver. You may want to save the returned i2c_client reference for later use. @@ -236,11 +236,11 @@ possible. Device Deletion --------------- -Each I2C device which has been created using i2c_new_device() or -i2c_new_scanned_device() can be unregistered by calling +Each I2C device which has been created using i2c_new_client_device() +or i2c_new_scanned_device() can be unregistered by calling i2c_unregister_device(). If you don't call it explicitly, it will be -called automatically before the underlying I2C bus itself is removed, as a -device can't survive its parent in the device driver model. +called automatically before the underlying I2C bus itself is removed, +as a device can't survive its parent in the device driver model. Initializing the driver @@ -344,7 +344,7 @@ Plain I2C communication int i2c_master_recv(struct i2c_client *client, char *buf, int count); These routines read and write some bytes from/to a client. The client -contains the i2c address, so you do not have to include it. The second +contains the I2C address, so you do not have to include it. The second parameter contains the bytes to read/write, the third the number of bytes to read/write (must be less than the length of the buffer, also should be less than 64k since msg.len is u16.) Returned is the actual number of bytes @@ -357,9 +357,9 @@ read/written. This sends a series of messages. Each message can be a read or write, and they can be mixed in any way. The transactions are combined: no -stop bit is sent between transaction. The i2c_msg structure contains -for each message the client address, the number of bytes of the message -and the message data itself. +stop condition is issued between transaction. The i2c_msg structure +contains for each message the client address, the number of bytes of the +message and the message data itself. You can read the file ``i2c-protocol`` for more information about the actual I2C protocol. diff --git a/Documentation/isdn/avmb1.rst b/Documentation/isdn/avmb1.rst deleted file mode 100644 index de3961e67553..000000000000 --- a/Documentation/isdn/avmb1.rst +++ /dev/null @@ -1,246 +0,0 @@ -================================ -Driver for active AVM Controller -================================ - -The driver provides a kernel capi2.0 Interface (kernelcapi) and -on top of this a User-Level-CAPI2.0-interface (capi) -and a driver to connect isdn4linux with CAPI2.0 (capidrv). -The lowlevel interface can be used to implement a CAPI2.0 -also for passive cards since July 1999. - -The author can be reached at calle@calle.in-berlin.de. -The command avmcapictrl is part of the isdn4k-utils. -t4-files can be found at ftp://ftp.avm.de/cardware/b1/linux/firmware - -Currently supported cards: - - - B1 ISA (all versions) - - B1 PCI - - T1/T1B (HEMA card) - - M1 - - M2 - - B1 PCMCIA - -Installing ----------- - -You need at least /dev/capi20 to load the firmware. - -:: - - mknod /dev/capi20 c 68 0 - mknod /dev/capi20.00 c 68 1 - mknod /dev/capi20.01 c 68 2 - . - . - . - mknod /dev/capi20.19 c 68 20 - -Running -------- - -To use the card you need the t4-files to download the firmware. -AVM GmbH provides several t4-files for the different D-channel -protocols (b1.t4 for Euro-ISDN). Install these file in /lib/isdn. - -if you configure as modules load the modules this way:: - - insmod /lib/modules/current/misc/capiutil.o - insmod /lib/modules/current/misc/b1.o - insmod /lib/modules/current/misc/kernelcapi.o - insmod /lib/modules/current/misc/capidrv.o - insmod /lib/modules/current/misc/capi.o - -if you have an B1-PCI card load the module b1pci.o:: - - insmod /lib/modules/current/misc/b1pci.o - -and load the firmware with:: - - avmcapictrl load /lib/isdn/b1.t4 1 - -if you have an B1-ISA card load the module b1isa.o -and add the card by calling:: - - avmcapictrl add 0x150 15 - -and load the firmware by calling:: - - avmcapictrl load /lib/isdn/b1.t4 1 - -if you have an T1-ISA card load the module t1isa.o -and add the card by calling:: - - avmcapictrl add 0x450 15 T1 0 - -and load the firmware by calling:: - - avmcapictrl load /lib/isdn/t1.t4 1 - -if you have an PCMCIA card (B1/M1/M2) load the module b1pcmcia.o -before you insert the card. - -Leased Lines with B1 --------------------- - -Init card and load firmware. - -For an D64S use "FV: 1" as phone number - -For an D64S2 use "FV: 1" and "FV: 2" for multilink -or "FV: 1,2" to use CAPI channel bundling. - -/proc-Interface ------------------ - -/proc/capi:: - - dr-xr-xr-x 2 root root 0 Jul 1 14:03 . - dr-xr-xr-x 82 root root 0 Jun 30 19:08 .. - -r--r--r-- 1 root root 0 Jul 1 14:03 applications - -r--r--r-- 1 root root 0 Jul 1 14:03 applstats - -r--r--r-- 1 root root 0 Jul 1 14:03 capi20 - -r--r--r-- 1 root root 0 Jul 1 14:03 capidrv - -r--r--r-- 1 root root 0 Jul 1 14:03 controller - -r--r--r-- 1 root root 0 Jul 1 14:03 contrstats - -r--r--r-- 1 root root 0 Jul 1 14:03 driver - -r--r--r-- 1 root root 0 Jul 1 14:03 ncci - -r--r--r-- 1 root root 0 Jul 1 14:03 users - -/proc/capi/applications: - applid level3cnt datablkcnt datablklen ncci-cnt recvqueuelen - level3cnt: - capi_register parameter - datablkcnt: - capi_register parameter - ncci-cnt: - current number of nccis (connections) - recvqueuelen: - number of messages on receive queue - - for example:: - - 1 -2 16 2048 1 0 - 2 2 7 2048 1 0 - -/proc/capi/applstats: - applid recvctlmsg nrecvdatamsg nsentctlmsg nsentdatamsg - recvctlmsg: - capi messages received without DATA_B3_IND - recvdatamsg: - capi DATA_B3_IND received - sentctlmsg: - capi messages sent without DATA_B3_REQ - sentdatamsg: - capi DATA_B3_REQ sent - - for example:: - - 1 2057 1699 1721 1699 - -/proc/capi/capi20: statistics of capi.o (/dev/capi20) - minor nopen nrecvdropmsg nrecvctlmsg nrecvdatamsg sentctlmsg sentdatamsg - minor: - minor device number of capi device - nopen: - number of calls to devices open - nrecvdropmsg: - capi messages dropped (messages in recvqueue in close) - nrecvctlmsg: - capi messages received without DATA_B3_IND - nrecvdatamsg: - capi DATA_B3_IND received - nsentctlmsg: - capi messages sent without DATA_B3_REQ - nsentdatamsg: - capi DATA_B3_REQ sent - - for example:: - - 1 2 18 0 16 2 - -/proc/capi/capidrv: statistics of capidrv.o (capi messages) - nrecvctlmsg nrecvdatamsg sentctlmsg sentdatamsg - nrecvctlmsg: - capi messages received without DATA_B3_IND - nrecvdatamsg: - capi DATA_B3_IND received - nsentctlmsg: - capi messages sent without DATA_B3_REQ - nsentdatamsg: - capi DATA_B3_REQ sent - - for example: - 2780 2226 2256 2226 - -/proc/capi/controller: - controller drivername state cardname controllerinfo - - for example:: - - 1 b1pci running b1pci-e000 B1 3.07-01 0xe000 19 - 2 t1isa running t1isa-450 B1 3.07-01 0x450 11 0 - 3 b1pcmcia running m2-150 B1 3.07-01 0x150 5 - -/proc/capi/contrstats: - controller nrecvctlmsg nrecvdatamsg sentctlmsg sentdatamsg - nrecvctlmsg: - capi messages received without DATA_B3_IND - nrecvdatamsg: - capi DATA_B3_IND received - nsentctlmsg: - capi messages sent without DATA_B3_REQ - nsentdatamsg: - capi DATA_B3_REQ sent - - for example:: - - 1 2845 2272 2310 2274 - 2 2 0 2 0 - 3 2 0 2 0 - -/proc/capi/driver: - drivername ncontroller - - for example:: - - b1pci 1 - t1isa 1 - b1pcmcia 1 - b1isa 0 - -/proc/capi/ncci: - apllid ncci winsize sendwindow - - for example:: - - 1 0x10101 8 0 - -/proc/capi/users: kernelmodules that use the kernelcapi. - name - - for example:: - - capidrv - capi20 - -Questions ---------- - -Check out the FAQ (ftp.isdn4linux.de) or subscribe to the -linux-avmb1@calle.in-berlin.de mailing list by sending -a mail to majordomo@calle.in-berlin.de with -subscribe linux-avmb1 -in the body. - -German documentation and several scripts can be found at -ftp://ftp.avm.de/cardware/b1/linux/ - -Bugs ----- - -If you find any please let me know. - -Enjoy, - -Carsten Paeth (calle@calle.in-berlin.de) diff --git a/Documentation/isdn/gigaset.rst b/Documentation/isdn/gigaset.rst deleted file mode 100644 index 98b4ec521c51..000000000000 --- a/Documentation/isdn/gigaset.rst +++ /dev/null @@ -1,465 +0,0 @@ -========================== -GigaSet 307x Device Driver -========================== - -1. Requirements -================= - -1.1. Hardware -------------- - - This driver supports the connection of the Gigaset 307x/417x family of - ISDN DECT bases via Gigaset M101 Data, Gigaset M105 Data or direct USB - connection. The following devices are reported to be compatible: - - Bases: - - Siemens Gigaset 3070/3075 isdn - - Siemens Gigaset 4170/4175 isdn - - Siemens Gigaset SX205/255 - - Siemens Gigaset SX353 - - T-Com Sinus 45 [AB] isdn - - T-Com Sinus 721X[A] [SE] - - Vox Chicago 390 ISDN (KPN Telecom) - - RS232 data boxes: - - Siemens Gigaset M101 Data - - T-Com Sinus 45 Data 1 - - USB data boxes: - - Siemens Gigaset M105 Data - - Siemens Gigaset USB Adapter DECT - - T-Com Sinus 45 Data 2 - - T-Com Sinus 721 data - - Chicago 390 USB (KPN) - - See also http://www.erbze.info/sinus_gigaset.htm - (archived at https://web.archive.org/web/20100717020421/http://www.erbze.info:80/sinus_gigaset.htm ) and - http://gigaset307x.sourceforge.net/ - - We had also reports from users of Gigaset M105 who could use the drivers - with SX 100 and CX 100 ISDN bases (only in unimodem mode, see section 2.5.) - If you have another device that works with our driver, please let us know. - - Chances of getting an USB device to work are good if the output of:: - - lsusb - - at the command line contains one of the following:: - - ID 0681:0001 - ID 0681:0002 - ID 0681:0009 - ID 0681:0021 - ID 0681:0022 - -1.2. Software -------------- - - The driver works with the Kernel CAPI subsystem and can be used with any - software which is able to use CAPI 2.0 for ISDN connections (voice or data). - - There are some user space tools available at - https://sourceforge.net/projects/gigaset307x/ - which provide access to additional device specific functions like SMS, - phonebook or call journal. - - -2. How to use the driver -========================== - -2.1. Modules ------------- - - For the devices to work, the proper kernel modules have to be loaded. - This normally happens automatically when the system detects the USB - device (base, M105) or when the line discipline is attached (M101). It - can also be triggered manually using the modprobe(8) command, for example - for troubleshooting or to pass module parameters. - - The module ser_gigaset provides a serial line discipline N_GIGASET_M101 - which uses the regular serial port driver to access the device, and must - therefore be attached to the serial device to which the M101 is connected. - The ldattach(8) command (included in util-linux-ng release 2.14 or later) - can be used for that purpose, for example:: - - ldattach GIGASET_M101 /dev/ttyS1 - - This will open the device file, attach the line discipline to it, and - then sleep in the background, keeping the device open so that the line - discipline remains active. To deactivate it, kill the daemon, for example - with:: - - killall ldattach - - before disconnecting the device. To have this happen automatically at - system startup/shutdown on an LSB compatible system, create and activate - an appropriate LSB startup script /etc/init.d/gigaset. (The init name - 'gigaset' is officially assigned to this project by LANANA.) - Alternatively, just add the 'ldattach' command line to /etc/rc.local. - - The modules accept the following parameters: - - =============== ========== ========================================== - Module Parameter Meaning - - gigaset debug debug level (see section 3.2.) - - startmode initial operation mode (see section 2.5.): - bas_gigaset ) 1=CAPI (default), 0=Unimodem - ser_gigaset ) - usb_gigaset ) cidmode initial Call-ID mode setting (see section - 2.5.): 1=on (default), 0=off - - =============== ========== ========================================== - - Depending on your distribution you may want to create a separate module - configuration file like /etc/modprobe.d/gigaset.conf for these. - -2.2. Device nodes for user space programs ------------------------------------------ - - The device can be accessed from user space (eg. by the user space tools - mentioned in 1.2.) through the device nodes: - - - /dev/ttyGS0 for M101 (RS232 data boxes) - - /dev/ttyGU0 for M105 (USB data boxes) - - /dev/ttyGB0 for the base driver (direct USB connection) - - If you connect more than one device of a type, they will get consecutive - device nodes, eg. /dev/ttyGU1 for a second M105. - - You can also set a "default device" for the user space tools to use when - no device node is given as parameter, by creating a symlink /dev/ttyG to - one of them, eg.:: - - ln -s /dev/ttyGB0 /dev/ttyG - - The devices accept the following device specific ioctl calls - (defined in gigaset_dev.h): - - ``ioctl(int fd, GIGASET_REDIR, int *cmd);`` - - If cmd==1, the device is set to be controlled exclusively through the - character device node; access from the ISDN subsystem is blocked. - - If cmd==0, the device is set to be used from the ISDN subsystem and does - not communicate through the character device node. - - ``ioctl(int fd, GIGASET_CONFIG, int *cmd);`` - - (ser_gigaset and usb_gigaset only) - - If cmd==1, the device is set to adapter configuration mode where commands - are interpreted by the M10x DECT adapter itself instead of being - forwarded to the base station. In this mode, the device accepts the - commands described in Siemens document "AT-Kommando Alignment M10x Data" - for setting the operation mode, associating with a base station and - querying parameters like field strengh and signal quality. - - Note that there is no ioctl command for leaving adapter configuration - mode and returning to regular operation. In order to leave adapter - configuration mode, write the command ATO to the device. - - ``ioctl(int fd, GIGASET_BRKCHARS, unsigned char brkchars[6]);`` - - (usb_gigaset only) - - Set the break characters on an M105's internal serial adapter to the six - bytes stored in brkchars[]. Unused bytes should be set to zero. - - ioctl(int fd, GIGASET_VERSION, unsigned version[4]); - Retrieve version information from the driver. version[0] must be set to - one of: - - - GIGVER_DRIVER: retrieve driver version - - GIGVER_COMPAT: retrieve interface compatibility version - - GIGVER_FWBASE: retrieve the firmware version of the base - - Upon return, version[] is filled with the requested version information. - -2.3. CAPI ---------- - - The devices will show up as CAPI controllers as soon as the - corresponding driver module is loaded, and can then be used with - CAPI 2.0 kernel and user space applications. For user space access, - the module capi.ko must be loaded. - - Most distributions handle loading and unloading of the various CAPI - modules automatically via the command capiinit(1) from the capi4k-utils - package or a similar mechanism. Note that capiinit(1) cannot unload the - Gigaset drivers because it doesn't support more than one module per - driver. - -2.5. Unimodem mode ------------------- - - In this mode the device works like a modem connected to a serial port - (the /dev/ttyGU0, ... mentioned above) which understands the commands:: - - ATZ init, reset - => OK or ERROR - ATD - ATDT dial - => OK, CONNECT, - BUSY, - NO DIAL TONE, - NO CARRIER, - NO ANSWER - <pause>+++<pause> change to command mode when connected - ATH hangup - - You can use some configuration tool of your distribution to configure this - "modem" or configure pppd/wvdial manually. There are some example ppp - configuration files and chat scripts in the gigaset-VERSION/ppp directory - in the driver packages from https://sourceforge.net/projects/gigaset307x/. - Please note that the USB drivers are not able to change the state of the - control lines. This means you must use "Stupid Mode" if you are using - wvdial or you should use the nocrtscts option of pppd. - You must also assure that the ppp_async module is loaded with the parameter - flag_time=0. You can do this e.g. by adding a line like:: - - options ppp_async flag_time=0 - - to an appropriate module configuration file, like:: - - /etc/modprobe.d/gigaset.conf. - - Unimodem mode is needed for making some devices [e.g. SX100] work which - do not support the regular Gigaset command set. If debug output (see - section 3.2.) shows something like this when dialing:: - - CMD Received: ERROR - Available Params: 0 - Connection State: 0, Response: -1 - gigaset_process_response: resp_code -1 in ConState 0 ! - Timeout occurred - - then switching to unimodem mode may help. - - If you have installed the command line tool gigacontr, you can enter - unimodem mode using:: - - gigacontr --mode unimodem - - You can switch back using:: - - gigacontr --mode isdn - - You can also put the driver directly into Unimodem mode when it's loaded, - by passing the module parameter startmode=0 to the hardware specific - module, e.g.:: - - modprobe usb_gigaset startmode=0 - - or by adding a line like:: - - options usb_gigaset startmode=0 - - to an appropriate module configuration file, like:: - - /etc/modprobe.d/gigaset.conf - -2.6. Call-ID (CID) mode ------------------------ - - Call-IDs are numbers used to tag commands to, and responses from, the - Gigaset base in order to support the simultaneous handling of multiple - ISDN calls. Their use can be enabled ("CID mode") or disabled ("Unimodem - mode"). Without Call-IDs (in Unimodem mode), only a very limited set of - functions is available. It allows outgoing data connections only, but - does not signal incoming calls or other base events. - - DECT cordless data devices (M10x) permanently occupy the cordless - connection to the base while Call-IDs are activated. As the Gigaset - bases only support one DECT data connection at a time, this prevents - other DECT cordless data devices from accessing the base. - - During active operation, the driver switches to the necessary mode - automatically. However, for the reasons above, the mode chosen when - the device is not in use (idle) can be selected by the user. - - - If you want to receive incoming calls, you can use the default - settings (CID mode). - - If you have several DECT data devices (M10x) which you want to use - in turn, select Unimodem mode by passing the parameter "cidmode=0" to - the appropriate driver module (ser_gigaset or usb_gigaset). - - If you want both of these at once, you are out of luck. - - You can also use the tty class parameter "cidmode" of the device to - change its CID mode while the driver is loaded, eg.:: - - echo 0 > /sys/class/tty/ttyGU0/cidmode - -2.7. Dialing Numbers --------------------- -provided by an application for dialing out must - be a public network number according to the local dialing plan, without - any dial prefix for getting an outside line. - - Internal calls can be made by providing an internal extension number - prefixed with ``**`` (two asterisks) as the called party number. So to dial - eg. the first registered DECT handset, give ``**11`` as the called party - number. Dialing ``***`` (three asterisks) calls all extensions - simultaneously (global call). - - Unimodem mode does not support internal calls. - -2.8. Unregistered Wireless Devices (M101/M105) ----------------------------------------------- - - The main purpose of the ser_gigaset and usb_gigaset drivers is to allow - the M101 and M105 wireless devices to be used as ISDN devices for ISDN - connections through a Gigaset base. Therefore they assume that the device - is registered to a DECT base. - - If the M101/M105 device is not registered to a base, initialization of - the device fails, and a corresponding error message is logged by the - driver. In that situation, a restricted set of functions is available - which includes, in particular, those necessary for registering the device - to a base or for switching it between Fixed Part and Portable Part - modes. See the gigacontr(8) manpage for details. - -3. Troubleshooting -==================== - -3.1. Solutions to frequently reported problems ----------------------------------------------- - - Problem: - You have a slow provider and isdn4linux gives up dialing too early. - Solution: - Load the isdn module using the dialtimeout option. You can do this e.g. - by adding a line like:: - - options isdn dialtimeout=15 - - to /etc/modprobe.d/gigaset.conf or a similar file. - - Problem: - The isdnlog program emits error messages or just doesn't work. - Solution: - Isdnlog supports only the HiSax driver. Do not attempt to use it with - other drivers such as Gigaset. - - Problem: - You have two or more DECT data adapters (M101/M105) and only the - first one you turn on works. - Solution: - Select Unimodem mode for all DECT data adapters. (see section 2.5.) - - Problem: - Messages like this:: - - usb_gigaset 3-2:1.0: Could not initialize the device. - - appear in your syslog. - Solution: - Check whether your M10x wireless device is correctly registered to the - Gigaset base. (see section 2.7.) - -3.2. Telling the driver to provide more information ---------------------------------------------------- - Building the driver with the "Gigaset debugging" kernel configuration - option (CONFIG_GIGASET_DEBUG) gives it the ability to produce additional - information useful for debugging. - - You can control the amount of debugging information the driver produces by - writing an appropriate value to /sys/module/gigaset/parameters/debug, - e.g.:: - - echo 0 > /sys/module/gigaset/parameters/debug - - switches off debugging output completely, - - :: - - echo 0x302020 > /sys/module/gigaset/parameters/debug - - enables a reasonable set of debugging output messages. These values are - bit patterns where every bit controls a certain type of debugging output. - See the constants DEBUG_* in the source file gigaset.h for details. - - The initial value can be set using the debug parameter when loading the - module "gigaset", e.g. by adding a line:: - - options gigaset debug=0 - - to your module configuration file, eg. /etc/modprobe.d/gigaset.conf - - Generated debugging information can be found - - as output of the command:: - - dmesg - - - in system log files written by your syslog daemon, usually - in /var/log/, e.g. /var/log/messages. - -3.3. Reporting problems and bugs --------------------------------- - If you can't solve problems with the driver on your own, feel free to - use one of the forums, bug trackers, or mailing lists on - - https://sourceforge.net/projects/gigaset307x - - or write an electronic mail to the maintainers. - - Try to provide as much information as possible, such as - - - distribution - - kernel version (uname -r) - - gcc version (gcc --version) - - hardware architecture (uname -m, ...) - - type and firmware version of your device (base and wireless module, - if any) - - output of "lsusb -v" (if using an USB device) - - error messages - - relevant system log messages (it would help if you activate debug - output as described in 3.2.) - - For help with general configuration problems not specific to our driver, - such as isdn4linux and network configuration issues, please refer to the - appropriate forums and newsgroups. - -3.4. Reporting problem solutions --------------------------------- - If you solved a problem with our drivers, wrote startup scripts for your - distribution, ... feel free to contact us (using one of the places - mentioned in 3.3.). We'd like to add scripts, hints, documentation - to the driver and/or the project web page. - - -4. Links, other software -========================== - - - Sourceforge project developing this driver and associated tools - https://sourceforge.net/projects/gigaset307x - - Yahoo! Group on the Siemens Gigaset family of devices - https://de.groups.yahoo.com/group/Siemens-Gigaset - - Siemens Gigaset/T-Sinus compatibility table - http://www.erbze.info/sinus_gigaset.htm - (archived at https://web.archive.org/web/20100717020421/http://www.erbze.info:80/sinus_gigaset.htm ) - - -5. Credits -============ - - Thanks to - - Karsten Keil - for his help with isdn4linux - Deti Fliegl - for his base driver code - Dennis Dietrich - for his kernel 2.6 patches - Andreas Rummel - for his work and logs to get unimodem mode working - Andreas Degert - for his logs and patches to get cx 100 working - Dietrich Feist - for his generous donation of one M105 and two M101 cordless adapters - Christoph Schweers - for his generous donation of a M34 device - - and all the other people who sent logs and other information. diff --git a/Documentation/isdn/hysdn.rst b/Documentation/isdn/hysdn.rst deleted file mode 100644 index 0a168d1cbffc..000000000000 --- a/Documentation/isdn/hysdn.rst +++ /dev/null @@ -1,196 +0,0 @@ -============ -Hysdn Driver -============ - -The hysdn driver has been written by -Werner Cornelius (werner@isdn4linux.de or werner@titro.de) -for Hypercope GmbH Aachen Germany. Hypercope agreed to publish this driver -under the GNU General Public License. - -The CAPI 2.0-support was added by Ulrich Albrecht (ualbrecht@hypercope.de) -for Hypercope GmbH Aachen, Germany. - - - 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., 675 Mass Ave, Cambridge, MA 02139, USA. - -.. Table of contents - - 1. About the driver - - 2. Loading/Unloading the driver - - 3. Entries in the /proc filesystem - - 4. The /proc/net/hysdn/cardconfX file - - 5. The /proc/net/hysdn/cardlogX file - - 6. Where to get additional info and help - - -1. About the driver -=================== - - The drivers/isdn/hysdn subdir contains a driver for HYPERCOPEs active - PCI isdn cards Champ, Ergo and Metro. To enable support for this cards - enable ISDN support in the kernel config and support for HYSDN cards in - the active cards submenu. The driver may only be compiled and used if - support for loadable modules and the process filesystem have been enabled. - - These cards provide two different interfaces to the kernel. Without the - optional CAPI 2.0 support, they register as ethernet card. IP-routing - to a ISDN-destination is performed on the card itself. All necessary - handlers for various protocols like ppp and others as well as config info - and firmware may be fetched from Hypercopes WWW-Site www.hypercope.de. - - With CAPI 2.0 support enabled, the card can also be used as a CAPI 2.0 - compliant devices with either CAPI 2.0 applications - (check isdn4k-utils) or -using the capidrv module- as a regular - isdn4linux device. This is done via the same mechanism as with the - active AVM cards and in fact uses the same module. - - -2. Loading/Unloading the driver -=============================== - - The module has no command line parameters and auto detects up to 10 cards - in the id-range 0-9. - If a loaded driver shall be unloaded all open files in the /proc/net/hysdn - subdir need to be closed and all ethernet interfaces allocated by this - driver must be shut down. Otherwise the module counter will avoid a module - unload. - - If you are using the CAPI 2.0-interface, make sure to load/modprobe the - kernelcapi-module first. - - If you plan to use the capidrv-link to isdn4linux, make sure to load - capidrv.o after all modules using this driver (i.e. after hysdn and - any avm-specific modules). - -3. Entries in the /proc filesystem -================================== - - When the module has been loaded it adds the directory hysdn in the - /proc/net tree. This directory contains exactly 2 file entries for each - card. One is called cardconfX and the other cardlogX, where X is the - card id number from 0 to 9. - The cards are numbered in the order found in the PCI config data. - -4. The /proc/net/hysdn/cardconfX file -===================================== - - This file may be read to get by everyone to get info about the cards type, - actual state, available features and used resources. - The first 3 entries (id, bus and slot) are PCI info fields, the following - type field gives the information about the cards type: - - - 4 -> Ergo card (server card with 2 b-chans) - - 5 -> Metro card (server card with 4 or 8 b-chans) - - 6 -> Champ card (client card with 2 b-chans) - - The following 3 fields show the hardware assignments for irq, iobase and the - dual ported memory (dp-mem). - - The fields b-chans and fax-chans announce the available card resources of - this types for the user. - - The state variable indicates the actual drivers state for this card with the - following assignments. - - - 0 -> card has not been booted since driver load - - 1 -> card booting is actually in progess - - 2 -> card is in an error state due to a previous boot failure - - 3 -> card is booted and active - - And the last field (device) shows the name of the ethernet device assigned - to this card. Up to the first successful boot this field only shows a - - to tell that no net device has been allocated up to now. Once a net device - has been allocated it remains assigned to this card, even if a card is - rebooted and an boot error occurs. - - Writing to the cardconfX file boots the card or transfers config lines to - the cards firmware. The type of data is automatically detected when the - first data is written. Only root has write access to this file. - The firmware boot files are normally called hyclient.pof for client cards - and hyserver.pof for server cards. - After successfully writing the boot file, complete config files or single - config lines may be copied to this file. - If an error occurs the return value given to the writing process has the - following additional codes (decimal): - - ==== ============================================ - 1000 Another process is currently bootng the card - 1001 Invalid firmware header - 1002 Boards dual-port RAM test failed - 1003 Internal firmware handler error - 1004 Boot image size invalid - 1005 First boot stage (bootstrap loader) failed - 1006 Second boot stage failure - 1007 Timeout waiting for card ready during boot - 1008 Operation only allowed in booted state - 1009 Config line too long - 1010 Invalid channel number - 1011 Timeout sending config data - ==== ============================================ - - Additional info about error reasons may be fetched from the log output. - -5. The /proc/net/hysdn/cardlogX file -==================================== - - The cardlogX file entry may be opened multiple for reading by everyone to - get the cards and drivers log data. Card messages always start with the - keyword LOG. All other lines are output from the driver. - The driver log data may be redirected to the syslog by selecting the - appropriate bitmask. The cards log messages will always be send to this - interface but never to the syslog. - - A root user may write a decimal or hex (with 0x) value t this file to select - desired output options. As mentioned above the cards log dat is always - written to the cardlog file independent of the following options only used - to check and debug the driver itself: - - For example:: - - echo "0x34560078" > /proc/net/hysdn/cardlog0 - - to output the hex log mask 34560078 for card 0. - - The written value is regarded as an unsigned 32-Bit value, bit ored for - desired output. The following bits are already assigned: - - ========== ============================================================ - 0x80000000 All driver log data is alternatively via syslog - 0x00000001 Log memory allocation errors - 0x00000010 Firmware load start and close are logged - 0x00000020 Log firmware record parser - 0x00000040 Log every firmware write actions - 0x00000080 Log all card related boot messages - 0x00000100 Output all config data sent for debugging purposes - 0x00000200 Only non comment config lines are shown wth channel - 0x00000400 Additional conf log output - 0x00001000 Log the asynchronous scheduler actions (config and log) - 0x00100000 Log all open and close actions to /proc/net/hysdn/card files - 0x00200000 Log all actions from /proc file entries - 0x00010000 Log network interface init and deinit - ========== ============================================================ - -6. Where to get additional info and help -======================================== - - If you have any problems concerning the driver or configuration contact - the Hypercope support team (support@hypercope.de) and or the authors - Werner Cornelius (werner@isdn4linux or cornelius@titro.de) or - Ulrich Albrecht (ualbrecht@hypercope.de). diff --git a/Documentation/isdn/index.rst b/Documentation/isdn/index.rst index 407e74b78372..9622939fa526 100644 --- a/Documentation/isdn/index.rst +++ b/Documentation/isdn/index.rst @@ -9,9 +9,6 @@ ISDN interface_capi - avmb1 - gigaset - hysdn m_isdn credits diff --git a/Documentation/isdn/interface_capi.rst b/Documentation/isdn/interface_capi.rst index 01a4b5ade9a4..fe2421444b76 100644 --- a/Documentation/isdn/interface_capi.rst +++ b/Documentation/isdn/interface_capi.rst @@ -26,13 +26,6 @@ This standard is freely available from https://www.capi.org. 2. Driver and Device Registration ================================= -CAPI drivers optionally register themselves with Kernel CAPI by calling the -Kernel CAPI function register_capi_driver() with a pointer to a struct -capi_driver. This structure must be filled with the name and revision of the -driver, and optionally a pointer to a callback function, add_card(). The -registration can be revoked by calling the function unregister_capi_driver() -with a pointer to the same struct capi_driver. - CAPI drivers must register each of the ISDN devices they control with Kernel CAPI by calling the Kernel CAPI function attach_capi_ctr() with a pointer to a struct capi_ctr before they can be used. This structure must be filled with @@ -89,9 +82,6 @@ register_capi_driver(): the name of the driver, as a zero-terminated ASCII string ``char revision[32]`` the revision number of the driver, as a zero-terminated ASCII string -``int (*add_card)(struct capi_driver *driver, capicardparams *data)`` - a callback function pointer (may be NULL) - 4.2 struct capi_ctr ------------------- @@ -178,12 +168,6 @@ to be set by the driver before calling attach_capi_ctr(): pointer to a callback function returning the entry for the device in the CAPI controller info table, /proc/capi/controller -``const struct file_operations *proc_fops`` - pointers to callback functions for the device's proc file - system entry, /proc/capi/controllers/<n>; pointer to the device's - capi_ctr structure is available from struct proc_dir_entry::data - which is available from struct inode. - Note: Callback functions except send_message() are never called in interrupt context. @@ -267,25 +251,10 @@ _cmstruct alternative representation for CAPI parameters of type 'struct' _cmsg structure members. =========== ================================================================= -Functions capi_cmsg2message() and capi_message2cmsg() are provided to convert -messages between their transport encoding described in the CAPI 2.0 standard -and their _cmsg structure representation. Note that capi_cmsg2message() does -not know or check the size of its destination buffer. The caller must make -sure it is big enough to accommodate the resulting CAPI message. - 5. Lower Layer Interface Functions ================================== -(declared in <linux/isdn/capilli.h>) - -:: - - void register_capi_driver(struct capi_driver *drvr) - void unregister_capi_driver(struct capi_driver *drvr) - -register/unregister a driver with Kernel CAPI - :: int attach_capi_ctr(struct capi_ctr *ctrlr) @@ -302,13 +271,6 @@ signal controller ready/not ready :: - void capi_ctr_suspend_output(struct capi_ctr *ctrlr) - void capi_ctr_resume_output(struct capi_ctr *ctrlr) - -signal suspend/resume - -:: - void capi_ctr_handle_message(struct capi_ctr * ctrlr, u16 applid, struct sk_buff *skb) @@ -319,21 +281,6 @@ for forwarding to the specified application 6. Helper Functions and Macros ============================== -Library functions (from <linux/isdn/capilli.h>): - -:: - - void capilib_new_ncci(struct list_head *head, u16 applid, - u32 ncci, u32 winsize) - void capilib_free_ncci(struct list_head *head, u16 applid, u32 ncci) - void capilib_release_appl(struct list_head *head, u16 applid) - void capilib_release(struct list_head *head) - void capilib_data_b3_conf(struct list_head *head, u16 applid, - u32 ncci, u16 msgid) - u16 capilib_data_b3_req(struct list_head *head, u16 applid, - u32 ncci, u16 msgid) - - Macros to extract/set element values from/in a CAPI message header (from <linux/isdn/capiutil.h>): @@ -357,24 +304,6 @@ CAPIMSG_DATALEN(m) CAPIMSG_SETDATALEN(m, len) Data Length (u16) Library functions for working with _cmsg structures (from <linux/isdn/capiutil.h>): -``unsigned capi_cmsg2message(_cmsg *cmsg, u8 *msg)`` - Assembles a CAPI 2.0 message from the parameters in ``*cmsg``, - storing the result in ``*msg``. - -``unsigned capi_message2cmsg(_cmsg *cmsg, u8 *msg)`` - Disassembles the CAPI 2.0 message in ``*msg``, storing the parameters - in ``*cmsg``. - -``unsigned capi_cmsg_header(_cmsg *cmsg, u16 ApplId, u8 Command, u8 Subcommand, u16 Messagenumber, u32 Controller)`` - Fills the header part and address field of the _cmsg structure ``*cmsg`` - with the given values, zeroing the remainder of the structure so only - parameters with non-default values need to be changed before sending - the message. - -``void capi_cmsg_answer(_cmsg *cmsg)`` - Sets the low bit of the Subcommand field in ``*cmsg``, thereby - converting ``_REQ`` to ``_CONF`` and ``_IND`` to ``_RESP``. - ``char *capi_cmd2str(u8 Command, u8 Subcommand)`` Returns the CAPI 2.0 message name corresponding to the given command and subcommand values, as a static ASCII string. The return value may diff --git a/Documentation/kbuild/kconfig-language.rst b/Documentation/kbuild/kconfig-language.rst index 231e6a64957f..d0111dd26410 100644 --- a/Documentation/kbuild/kconfig-language.rst +++ b/Documentation/kbuild/kconfig-language.rst @@ -591,7 +591,8 @@ The two different resolutions for b) can be tested in the sample Kconfig file Documentation/kbuild/Kconfig.recursion-issue-02. Below is a list of examples of prior fixes for these types of recursive issues; -all errors appear to involve one or more select's and one or more "depends on". +all errors appear to involve one or more "select" statements and one or more +"depends on". ============ =================================== commit fix @@ -653,7 +654,7 @@ the use of the xconfig configurator [1]_. Work should be done to confirm if the deduced semantics matches our intended Kconfig design goals. Having well defined semantics can be useful for tools for practical -evaluation of depenencies, for instance one such use known case was work to +evaluation of dependencies, for instance one such case was work to express in boolean abstraction of the inferred semantics of Kconfig to translate Kconfig logic into boolean formulas and run a SAT solver on this to find dead code / features (always inactive), 114 dead features were found in @@ -680,7 +681,7 @@ abstraction the inferred semantics of Kconfig to translate Kconfig logic into boolean formulas and run a SAT solver on it [5]_. Another known related project is CADOS [6]_ (former VAMOS [7]_) and the tools, mainly undertaker [8]_, which has been introduced first with [9]_. The basic concept of undertaker is to -exract variability models from Kconfig, and put them together with a +extract variability models from Kconfig and put them together with a propositional formula extracted from CPP #ifdefs and build-rules into a SAT solver in order to find dead code, dead files, and dead symbols. If using a SAT solver is desirable on Kconfig one approach would be to evaluate repurposing diff --git a/Documentation/kbuild/kconfig.rst b/Documentation/kbuild/kconfig.rst index a9a855f894b3..dce6801d66c9 100644 --- a/Documentation/kbuild/kconfig.rst +++ b/Documentation/kbuild/kconfig.rst @@ -154,11 +154,6 @@ KCONFIG_AUTOCONFIG This environment variable can be set to specify the path & name of the "auto.conf" file. Its default value is "include/config/auto.conf". -KCONFIG_TRISTATE ----------------- -This environment variable can be set to specify the path & name of the -"tristate.conf" file. Its default value is "include/config/tristate.conf". - KCONFIG_AUTOHEADER ------------------ This environment variable can be set to specify the path & name of the diff --git a/Documentation/kbuild/makefiles.rst b/Documentation/kbuild/makefiles.rst index d7e6534a8505..0e0eb2c8da7d 100644 --- a/Documentation/kbuild/makefiles.rst +++ b/Documentation/kbuild/makefiles.rst @@ -28,7 +28,6 @@ This document describes the Linux kernel Makefiles. --- 4.3 Using C++ for host programs --- 4.4 Controlling compiler options for host programs --- 4.5 When host programs are actually built - --- 4.6 Using hostprogs-$(CONFIG_FOO) === 5 Kbuild clean infrastructure @@ -595,11 +594,11 @@ compilation stage. Two steps are required in order to use a host executable. The first step is to tell kbuild that a host program exists. This is -done utilising the variable hostprogs-y. +done utilising the variable "hostprogs". The second step is to add an explicit dependency to the executable. This can be done in two ways. Either add the dependency in a rule, -or utilise the variable $(always). +or utilise the variable "always-y". Both possibilities are described in the following. 4.1 Simple Host Program @@ -612,7 +611,7 @@ Both possibilities are described in the following. Example:: - hostprogs-y := bin2hex + hostprogs := bin2hex Kbuild assumes in the above example that bin2hex is made from a single c-source file named bin2hex.c located in the same directory as @@ -630,7 +629,7 @@ Both possibilities are described in the following. Example:: #scripts/lxdialog/Makefile - hostprogs-y := lxdialog + hostprogs := lxdialog lxdialog-objs := checklist.o lxdialog.o Objects with extension .o are compiled from the corresponding .c @@ -650,7 +649,7 @@ Both possibilities are described in the following. Example:: #scripts/kconfig/Makefile - hostprogs-y := qconf + hostprogs := qconf qconf-cxxobjs := qconf.o In the example above the executable is composed of the C++ file @@ -662,7 +661,7 @@ Both possibilities are described in the following. Example:: #scripts/kconfig/Makefile - hostprogs-y := qconf + hostprogs := qconf qconf-cxxobjs := qconf.o qconf-objs := check.o @@ -710,7 +709,7 @@ Both possibilities are described in the following. Example:: #drivers/pci/Makefile - hostprogs-y := gen-devlist + hostprogs := gen-devlist $(obj)/devlist.h: $(src)/pci.ids $(obj)/gen-devlist ( cd $(obj); ./gen-devlist ) < $< @@ -718,47 +717,31 @@ Both possibilities are described in the following. $(obj)/gen-devlist is updated. Note that references to the host programs in special rules must be prefixed with $(obj). - (2) Use $(always) + (2) Use always-y When there is no suitable special rule, and the host program - shall be built when a makefile is entered, the $(always) + shall be built when a makefile is entered, the always-y variable shall be used. Example:: #scripts/lxdialog/Makefile - hostprogs-y := lxdialog - always := $(hostprogs-y) + hostprogs := lxdialog + always-y := $(hostprogs) This will tell kbuild to build lxdialog even if not referenced in any rule. -4.6 Using hostprogs-$(CONFIG_FOO) ---------------------------------- - - A typical pattern in a Kbuild file looks like this: - - Example:: - - #scripts/Makefile - hostprogs-$(CONFIG_KALLSYMS) += kallsyms - - Kbuild knows about both 'y' for built-in and 'm' for module. - So if a config symbol evaluates to 'm', kbuild will still build - the binary. In other words, Kbuild handles hostprogs-m exactly - like hostprogs-y. But only hostprogs-y is recommended to be used - when no CONFIG symbols are involved. - 5 Kbuild clean infrastructure ============================= "make clean" deletes most generated files in the obj tree where the kernel is compiled. This includes generated files such as host programs. -Kbuild knows targets listed in $(hostprogs-y), $(hostprogs-m), $(always), -$(extra-y) and $(targets). They are all deleted during "make clean". -Files matching the patterns "*.[oas]", "*.ko", plus some additional files -generated by kbuild are deleted all over the kernel src tree when -"make clean" is executed. +Kbuild knows targets listed in $(hostprogs), $(always-y), $(always-m), +$(always-), $(extra-y), $(extra-) and $(targets). They are all deleted +during "make clean". Files matching the patterns "*.[oas]", "*.ko", plus +some additional files generated by kbuild are deleted all over the kernel +source tree when "make clean" is executed. Additional files or directories can be specified in kbuild makefiles by use of $(clean-files). @@ -1269,12 +1252,12 @@ When kbuild executes, the following steps are followed (roughly): Example:: #arch/x86/kernel/Makefile - always := vmlinux.lds + extra-y := vmlinux.lds #Makefile export CPPFLAGS_vmlinux.lds += -P -C -U$(ARCH) - The assignment to $(always) is used to tell kbuild to build the + The assignment to extra-y is used to tell kbuild to build the target vmlinux.lds. The assignment to $(CPPFLAGS_vmlinux.lds) tells kbuild to use the specified options when building the target vmlinux.lds. diff --git a/Documentation/kernel-hacking/hacking.rst b/Documentation/kernel-hacking/hacking.rst index a3ddb213a5e1..d62aacb2822a 100644 --- a/Documentation/kernel-hacking/hacking.rst +++ b/Documentation/kernel-hacking/hacking.rst @@ -601,7 +601,7 @@ Defined in ``include/linux/export.h`` This is the variant of `EXPORT_SYMBOL()` that allows specifying a symbol namespace. Symbol Namespaces are documented in -``Documentation/kbuild/namespaces.rst``. +``Documentation/core-api/symbol-namespaces.rst``. :c:func:`EXPORT_SYMBOL_NS_GPL()` -------------------------------- @@ -610,7 +610,7 @@ Defined in ``include/linux/export.h`` This is the variant of `EXPORT_SYMBOL_GPL()` that allows specifying a symbol namespace. Symbol Namespaces are documented in -``Documentation/kbuild/namespaces.rst``. +``Documentation/core-api/symbol-namespaces.rst``. Routines and Conventions ======================== diff --git a/Documentation/locking/locktorture.rst b/Documentation/locking/locktorture.rst index e79eeeca3ac6..5bcb99ba7bd9 100644 --- a/Documentation/locking/locktorture.rst +++ b/Documentation/locking/locktorture.rst @@ -103,8 +103,7 @@ stat_interval Number of seconds between statistics-related printk()s. By default, locktorture will report stats every 60 seconds. Setting the interval to zero causes the statistics to - be printed -only- when the module is unloaded, and this - is the default. + be printed -only- when the module is unloaded. stutter The length of time to run the test before pausing for this diff --git a/Documentation/locking/spinlocks.rst b/Documentation/locking/spinlocks.rst index 66e3792f8a36..bec96f7a9f2d 100644 --- a/Documentation/locking/spinlocks.rst +++ b/Documentation/locking/spinlocks.rst @@ -25,9 +25,9 @@ worry about UP vs SMP issues: the spinlocks work correctly under both. Documentation/memory-barriers.txt - (5) LOCK operations. + (5) ACQUIRE operations. - (6) UNLOCK operations. + (6) RELEASE operations. The above is usually pretty simple (you usually need and want only one spinlock for most things - using more than one spinlock can make things a diff --git a/Documentation/maintainer/maintainer-entry-profile.rst b/Documentation/maintainer/maintainer-entry-profile.rst index 3eaddc8ac56d..11ebe3682771 100644 --- a/Documentation/maintainer/maintainer-entry-profile.rst +++ b/Documentation/maintainer/maintainer-entry-profile.rst @@ -99,4 +99,5 @@ to do something different in the near future. .. toctree:: :maxdepth: 1 + ../doc-guide/maintainer-profile ../nvdimm/maintainer-entry-profile diff --git a/Documentation/media/kapi/dtv-frontend.rst b/Documentation/media/kapi/dtv-frontend.rst index fbc5517c8d5a..b362109bb131 100644 --- a/Documentation/media/kapi/dtv-frontend.rst +++ b/Documentation/media/kapi/dtv-frontend.rst @@ -15,8 +15,8 @@ The header file for this API is named ``dvb_frontend.h`` and located in Demodulator driver ^^^^^^^^^^^^^^^^^^ -The demodulator driver is responsible to talk with the decoding part of the -hardware. Such driver should implement :c:type:`dvb_frontend_ops`, with +The demodulator driver is responsible for talking with the decoding part of the +hardware. Such driver should implement :c:type:`dvb_frontend_ops`, which tells what type of digital TV standards are supported, and points to a series of functions that allow the DVB core to command the hardware via the code under ``include/media/dvb_frontend.c``. @@ -120,7 +120,7 @@ Satellite TV reception is:: .. |delta| unicode:: U+00394 -The ``include/media/dvb_frontend.c`` has a kernel thread with is +The ``include/media/dvb_frontend.c`` has a kernel thread which is responsible for tuning the device. It supports multiple algorithms to detect a channel, as defined at enum :c:func:`dvbfe_algo`. @@ -220,11 +220,11 @@ Signal strength (:ref:`DTV-STAT-SIGNAL-STRENGTH`) - As the gain is visible through the set of registers that adjust the gain, typically, this statistics is always available [#f3]_. - - Drivers should try to make it available all the times, as this statistics + - Drivers should try to make it available all the times, as these statistics can be used when adjusting an antenna position and to check for troubles at the cabling. - .. [#f3] On a few devices, the gain keeps floating if no carrier. + .. [#f3] On a few devices, the gain keeps floating if there is no carrier. On such devices, strength report should check first if carrier is detected at the tuner (``FE_HAS_CARRIER``, see :c:type:`fe_status`), and otherwise return the lowest possible value. @@ -232,7 +232,7 @@ Signal strength (:ref:`DTV-STAT-SIGNAL-STRENGTH`) Carrier Signal to Noise ratio (:ref:`DTV-STAT-CNR`) - Signal to Noise ratio for the main carrier. - - Signal to Noise measurement depends on the device. On some hardware, is + - Signal to Noise measurement depends on the device. On some hardware, it is available when the main carrier is detected. On those hardware, CNR measurement usually comes from the tuner (e. g. after ``FE_HAS_CARRIER``, see :c:type:`fe_status`). @@ -323,8 +323,8 @@ A typical example of the logic that handle status and statistics is:: .read_status = foo_get_status_and_stats, }; -Statistics collect -^^^^^^^^^^^^^^^^^^ +Statistics collection +^^^^^^^^^^^^^^^^^^^^^ On almost all frontend hardware, the bit and byte counts are stored by the hardware after a certain amount of time or after the total bit/block diff --git a/Documentation/media/uapi/cec/cec-ioc-g-mode.rst b/Documentation/media/uapi/cec/cec-ioc-g-mode.rst index d0902f356d65..2535b77e3459 100644 --- a/Documentation/media/uapi/cec/cec-ioc-g-mode.rst +++ b/Documentation/media/uapi/cec/cec-ioc-g-mode.rst @@ -177,7 +177,7 @@ Available follower modes are: - ``CEC_MODE_MONITOR`` - 0xe0 - Put the file descriptor into monitor mode. Can only be used in - combination with :ref:`CEC_MODE_NO_INITIATOR <CEC-MODE-NO-INITIATOR>`,i + combination with :ref:`CEC_MODE_NO_INITIATOR <CEC-MODE-NO-INITIATOR>`, otherwise the ``EINVAL`` error code will be returned. In monitor mode all messages this CEC device transmits and all messages it receives (both broadcast diff --git a/Documentation/media/uapi/dvb/video-get-event.rst b/Documentation/media/uapi/dvb/video-get-event.rst index def6c40db601..7f03fbe3d3b0 100644 --- a/Documentation/media/uapi/dvb/video-get-event.rst +++ b/Documentation/media/uapi/dvb/video-get-event.rst @@ -81,7 +81,7 @@ for this ioctl call. #define VIDEO_EVENT_FRAME_RATE_CHANGED 2 #define VIDEO_EVENT_DECODER_STOPPED 3 #define VIDEO_EVENT_VSYNC 4 - __kernel_time_t timestamp; + long timestamp; union { video_size_t size; unsigned int frame_rate; /* in frames per 1000sec */ diff --git a/Documentation/media/uapi/dvb/video_types.rst b/Documentation/media/uapi/dvb/video_types.rst index 479942ce6fb8..2697400ccf62 100644 --- a/Documentation/media/uapi/dvb/video_types.rst +++ b/Documentation/media/uapi/dvb/video_types.rst @@ -170,7 +170,7 @@ VIDEO_GET_EVENT call. #define VIDEO_EVENT_FRAME_RATE_CHANGED 2 #define VIDEO_EVENT_DECODER_STOPPED 3 #define VIDEO_EVENT_VSYNC 4 - __kernel_time_t timestamp; + long timestamp; union { video_size_t size; unsigned int frame_rate; /* in frames per 1000sec */ diff --git a/Documentation/media/uapi/v4l/pixfmt-reserved.rst b/Documentation/media/uapi/v4l/pixfmt-reserved.rst index b2cd155e691b..7d98a7bf9f1f 100644 --- a/Documentation/media/uapi/v4l/pixfmt-reserved.rst +++ b/Documentation/media/uapi/v4l/pixfmt-reserved.rst @@ -55,8 +55,7 @@ please make a proposal on the linux-media mailing list. - ``V4L2_PIX_FMT_HM12`` - 'HM12' - - YUV 4:2:0 format used by the IVTV driver, - `http://www.ivtvdriver.org/ <http://www.ivtvdriver.org/>`__ + - YUV 4:2:0 format used by the IVTV driver. The format is documented in the kernel sources in the file ``Documentation/media/v4l-drivers/cx2341x.rst`` diff --git a/Documentation/media/uapi/v4l/pixfmt-srggb12p.rst b/Documentation/media/uapi/v4l/pixfmt-srggb12p.rst index 960851275f23..045540bc0d86 100644 --- a/Documentation/media/uapi/v4l/pixfmt-srggb12p.rst +++ b/Documentation/media/uapi/v4l/pixfmt-srggb12p.rst @@ -13,7 +13,7 @@ .. _v4l2-pix-fmt-sgrbg12p: ******************************************************************************************************************************* -V4L2_PIX_FMT_SRGGB12P ('pRAA'), V4L2_PIX_FMT_SGRBG12P ('pgAA'), V4L2_PIX_FMT_SGBRG12P ('pGAA'), V4L2_PIX_FMT_SBGGR12P ('pBAA'), +V4L2_PIX_FMT_SRGGB12P ('pRCC'), V4L2_PIX_FMT_SGRBG12P ('pgCC'), V4L2_PIX_FMT_SGBRG12P ('pGCC'), V4L2_PIX_FMT_SBGGR12P ('pBCC'), ******************************************************************************************************************************* diff --git a/Documentation/media/uapi/v4l/pixfmt-srggb14p.rst b/Documentation/media/uapi/v4l/pixfmt-srggb14p.rst index 1a988d7e7ff8..051ae3d05bc3 100644 --- a/Documentation/media/uapi/v4l/pixfmt-srggb14p.rst +++ b/Documentation/media/uapi/v4l/pixfmt-srggb14p.rst @@ -13,7 +13,7 @@ .. _v4l2-pix-fmt-sgrbg14p: ******************************************************************************************************************************* -V4L2_PIX_FMT_SRGGB14P ('pRCC'), V4L2_PIX_FMT_SGRBG14P ('pgCC'), V4L2_PIX_FMT_SGBRG14P ('pGCC'), V4L2_PIX_FMT_SBGGR14P ('pBCC'), +V4L2_PIX_FMT_SRGGB14P ('pREE'), V4L2_PIX_FMT_SGRBG14P ('pgEE'), V4L2_PIX_FMT_SGBRG14P ('pGEE'), V4L2_PIX_FMT_SBGGR14P ('pBEE'), ******************************************************************************************************************************* *man V4L2_PIX_FMT_SRGGB14P(2)* diff --git a/Documentation/media/uapi/v4l/pixfmt-tch-td16.rst b/Documentation/media/uapi/v4l/pixfmt-tch-td16.rst index 4031b175257c..6f1be873bec1 100644 --- a/Documentation/media/uapi/v4l/pixfmt-tch-td16.rst +++ b/Documentation/media/uapi/v4l/pixfmt-tch-td16.rst @@ -15,7 +15,7 @@ V4L2_TCH_FMT_DELTA_TD16 ('TD16') *man V4L2_TCH_FMT_DELTA_TD16(2)* -16-bit signed Touch Delta +16-bit signed little endian Touch Delta Description @@ -37,38 +37,38 @@ Each cell is one byte. :widths: 2 1 1 1 1 1 1 1 1 * - start + 0: - - D'\ :sub:`00high` - D'\ :sub:`00low` - - D'\ :sub:`01high` + - D'\ :sub:`00high` - D'\ :sub:`01low` - - D'\ :sub:`02high` + - D'\ :sub:`01high` - D'\ :sub:`02low` - - D'\ :sub:`03high` + - D'\ :sub:`02high` - D'\ :sub:`03low` + - D'\ :sub:`03high` * - start + 8: - - D'\ :sub:`10high` - D'\ :sub:`10low` - - D'\ :sub:`11high` + - D'\ :sub:`10high` - D'\ :sub:`11low` - - D'\ :sub:`12high` + - D'\ :sub:`11high` - D'\ :sub:`12low` - - D'\ :sub:`13high` + - D'\ :sub:`12high` - D'\ :sub:`13low` + - D'\ :sub:`13high` * - start + 16: - - D'\ :sub:`20high` - D'\ :sub:`20low` - - D'\ :sub:`21high` + - D'\ :sub:`20high` - D'\ :sub:`21low` - - D'\ :sub:`22high` + - D'\ :sub:`21high` - D'\ :sub:`22low` - - D'\ :sub:`23high` + - D'\ :sub:`22high` - D'\ :sub:`23low` + - D'\ :sub:`23high` * - start + 24: - - D'\ :sub:`30high` - D'\ :sub:`30low` - - D'\ :sub:`31high` + - D'\ :sub:`30high` - D'\ :sub:`31low` - - D'\ :sub:`32high` + - D'\ :sub:`31high` - D'\ :sub:`32low` - - D'\ :sub:`33high` + - D'\ :sub:`32high` - D'\ :sub:`33low` + - D'\ :sub:`33high` diff --git a/Documentation/media/uapi/v4l/pixfmt-tch-tu16.rst b/Documentation/media/uapi/v4l/pixfmt-tch-tu16.rst index 8278543be99a..cb3da6687a58 100644 --- a/Documentation/media/uapi/v4l/pixfmt-tch-tu16.rst +++ b/Documentation/media/uapi/v4l/pixfmt-tch-tu16.rst @@ -15,7 +15,7 @@ V4L2_TCH_FMT_TU16 ('TU16') *man V4L2_TCH_FMT_TU16(2)* -16-bit unsigned raw touch data +16-bit unsigned little endian raw touch data Description @@ -36,38 +36,38 @@ Each cell is one byte. :widths: 2 1 1 1 1 1 1 1 1 * - start + 0: - - R'\ :sub:`00high` - R'\ :sub:`00low` - - R'\ :sub:`01high` + - R'\ :sub:`00high` - R'\ :sub:`01low` - - R'\ :sub:`02high` + - R'\ :sub:`01high` - R'\ :sub:`02low` - - R'\ :sub:`03high` + - R'\ :sub:`02high` - R'\ :sub:`03low` + - R'\ :sub:`03high` * - start + 8: - - R'\ :sub:`10high` - R'\ :sub:`10low` - - R'\ :sub:`11high` + - R'\ :sub:`10high` - R'\ :sub:`11low` - - R'\ :sub:`12high` + - R'\ :sub:`11high` - R'\ :sub:`12low` - - R'\ :sub:`13high` + - R'\ :sub:`12high` - R'\ :sub:`13low` + - R'\ :sub:`13high` * - start + 16: - - R'\ :sub:`20high` - R'\ :sub:`20low` - - R'\ :sub:`21high` + - R'\ :sub:`20high` - R'\ :sub:`21low` - - R'\ :sub:`22high` + - R'\ :sub:`21high` - R'\ :sub:`22low` - - R'\ :sub:`23high` + - R'\ :sub:`22high` - R'\ :sub:`23low` + - R'\ :sub:`23high` * - start + 24: - - R'\ :sub:`30high` - R'\ :sub:`30low` - - R'\ :sub:`31high` + - R'\ :sub:`30high` - R'\ :sub:`31low` - - R'\ :sub:`32high` + - R'\ :sub:`31high` - R'\ :sub:`32low` - - R'\ :sub:`33high` + - R'\ :sub:`32high` - R'\ :sub:`33low` + - R'\ :sub:`33high` diff --git a/Documentation/media/uapi/v4l/vidioc-enum-fmt.rst b/Documentation/media/uapi/v4l/vidioc-enum-fmt.rst index 399ef1062bac..8ca6ab701e4a 100644 --- a/Documentation/media/uapi/v4l/vidioc-enum-fmt.rst +++ b/Documentation/media/uapi/v4l/vidioc-enum-fmt.rst @@ -44,7 +44,9 @@ To enumerate image formats applications initialize the ``type`` and the :ref:`VIDIOC_ENUM_FMT` ioctl with a pointer to this structure. Drivers fill the rest of the structure or return an ``EINVAL`` error code. All formats are enumerable by beginning at index zero and incrementing by -one until ``EINVAL`` is returned. +one until ``EINVAL`` is returned. If applicable, drivers shall return +formats in preference order, where preferred formats are returned before +(that is, with lower ``index`` value) less-preferred formats. .. note:: diff --git a/Documentation/media/uapi/v4l/vidioc-g-dv-timings.rst b/Documentation/media/uapi/v4l/vidioc-g-dv-timings.rst index 5712bd48e687..5c675cbac4cf 100644 --- a/Documentation/media/uapi/v4l/vidioc-g-dv-timings.rst +++ b/Documentation/media/uapi/v4l/vidioc-g-dv-timings.rst @@ -279,7 +279,7 @@ EBUSY then it will set this flag to signal this to the application. * - ``V4L2_DV_FL_HALF_LINE`` - Specific to interlaced formats: if set, then the vertical - backporch of field 1 (aka the odd field) is really one half-line + 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 diff --git a/Documentation/media/v4l-drivers/cx18.rst b/Documentation/media/v4l-drivers/cx18.rst deleted file mode 100644 index 16895a734bae..000000000000 --- a/Documentation/media/v4l-drivers/cx18.rst +++ /dev/null @@ -1,39 +0,0 @@ -.. SPDX-License-Identifier: GPL-2.0 - -The cx18 driver -=============== - -.. note:: - - This documentation is outdated. - -Some notes regarding the cx18 driver for the Conexant CX23418 MPEG -encoder chip: - -1) Currently supported are: - - - Hauppauge HVR-1600 - - Compro VideoMate H900 - - Yuan MPC718 - - Conexant Raptor PAL/SECAM devkit - -2) Some people have problems getting the i2c bus to work. - The symptom is that the eeprom cannot be read and the card is - unusable. This is probably fixed, but if you have problems - then post to the video4linux or ivtv-users mailing list. - -3) VBI (raw or sliced) has not yet been implemented. - -4) MPEG indexing is not yet implemented. - -5) The driver is still a bit rough around the edges, this should - improve over time. - - -Firmware: - -You can obtain the firmware files here: - -http://dl.ivtvdriver.org/ivtv/firmware/cx18-firmware.tar.gz - -Untar and copy the .fw files to your firmware directory. diff --git a/Documentation/media/v4l-drivers/index.rst b/Documentation/media/v4l-drivers/index.rst index c4c78a28654c..b41fea23fe5d 100644 --- a/Documentation/media/v4l-drivers/index.rst +++ b/Documentation/media/v4l-drivers/index.rst @@ -38,7 +38,6 @@ For more details see the file COPYING in the source distribution of Linux. bttv cafe_ccic cpia2 - cx18 cx2341x cx88 davinci-vpbe diff --git a/Documentation/media/v4l-drivers/meye.rst b/Documentation/media/v4l-drivers/meye.rst index a572996cdbf6..dc57a6a91b43 100644 --- a/Documentation/media/v4l-drivers/meye.rst +++ b/Documentation/media/v4l-drivers/meye.rst @@ -95,7 +95,7 @@ so all video4linux tools (like xawtv) should work with this driver. Besides the video4linux interface, the driver has a private interface for accessing the Motion Eye extended parameters (camera sharpness, -agc, video framerate), the shapshot and the MJPEG capture facilities. +agc, video framerate), the snapshot and the MJPEG capture facilities. This interface consists of several ioctls (prototypes and structures can be found in include/linux/meye.h): diff --git a/Documentation/memory-barriers.txt b/Documentation/memory-barriers.txt index ec3b5865c1be..7146da061693 100644 --- a/Documentation/memory-barriers.txt +++ b/Documentation/memory-barriers.txt @@ -1868,12 +1868,16 @@ There are some more advanced barrier functions: (*) smp_mb__before_atomic(); (*) smp_mb__after_atomic(); - These are for use with atomic (such as add, subtract, increment and - decrement) functions that don't return a value, especially when used for - reference counting. These functions do not imply memory barriers. - - These are also used for atomic bitop functions that do not return a - value (such as set_bit and clear_bit). + These are for use with atomic RMW functions that do not imply memory + barriers, but where the code needs a memory barrier. Examples for atomic + RMW functions that do not imply are memory barrier are e.g. add, + subtract, (failed) conditional operations, _relaxed functions, + but not atomic_read or atomic_set. A common example where a memory + barrier may be required is when atomic ops are used for reference + counting. + + These are also used for atomic RMW bitop functions that do not imply a + memory barrier (such as set_bit and clear_bit). As an example, consider a piece of code that marks an object as being dead and then decrements the object's reference count: diff --git a/Documentation/misc-devices/xilinx_sdfec.rst b/Documentation/misc-devices/xilinx_sdfec.rst index 2245fcfa224d..7a47075c171c 100644 --- a/Documentation/misc-devices/xilinx_sdfec.rst +++ b/Documentation/misc-devices/xilinx_sdfec.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GPL-2.0+ + ==================== Xilinx SD-FEC Driver ==================== diff --git a/Documentation/networking/device_drivers/index.rst b/Documentation/networking/device_drivers/index.rst index c1f7f75e5fd9..a191faaf97de 100644 --- a/Documentation/networking/device_drivers/index.rst +++ b/Documentation/networking/device_drivers/index.rst @@ -22,9 +22,11 @@ Contents: intel/iavf intel/ice google/gve + marvell/octeontx2 mellanox/mlx5 netronome/nfp pensando/ionic + stmicro/stmmac .. only:: subproject and html diff --git a/Documentation/networking/device_drivers/marvell/octeontx2.rst b/Documentation/networking/device_drivers/marvell/octeontx2.rst new file mode 100644 index 000000000000..88f508338c5f --- /dev/null +++ b/Documentation/networking/device_drivers/marvell/octeontx2.rst @@ -0,0 +1,159 @@ +.. SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) + +==================================== +Marvell OcteonTx2 RVU Kernel Drivers +==================================== + +Copyright (c) 2020 Marvell International Ltd. + +Contents +======== + +- `Overview`_ +- `Drivers`_ +- `Basic packet flow`_ + +Overview +======== + +Resource virtualization unit (RVU) on Marvell's OcteonTX2 SOC maps HW +resources from the network, crypto and other functional blocks into +PCI-compatible physical and virtual functions. Each functional block +again has multiple local functions (LFs) for provisioning to PCI devices. +RVU supports multiple PCIe SRIOV physical functions (PFs) and virtual +functions (VFs). PF0 is called the administrative / admin function (AF) +and has privileges to provision RVU functional block's LFs to each of the +PF/VF. + +RVU managed networking functional blocks + - Network pool or buffer allocator (NPA) + - Network interface controller (NIX) + - Network parser CAM (NPC) + - Schedule/Synchronize/Order unit (SSO) + - Loopback interface (LBK) + +RVU managed non-networking functional blocks + - Crypto accelerator (CPT) + - Scheduled timers unit (TIM) + - Schedule/Synchronize/Order unit (SSO) + Used for both networking and non networking usecases + +Resource provisioning examples + - A PF/VF with NIX-LF & NPA-LF resources works as a pure network device + - A PF/VF with CPT-LF resource works as a pure crypto offload device. + +RVU functional blocks are highly configurable as per software requirements. + +Firmware setups following stuff before kernel boots + - Enables required number of RVU PFs based on number of physical links. + - Number of VFs per PF are either static or configurable at compile time. + Based on config, firmware assigns VFs to each of the PFs. + - Also assigns MSIX vectors to each of PF and VFs. + - These are not changed after kernel boot. + +Drivers +======= + +Linux kernel will have multiple drivers registering to different PF and VFs +of RVU. Wrt networking there will be 3 flavours of drivers. + +Admin Function driver +--------------------- + +As mentioned above RVU PF0 is called the admin function (AF), this driver +supports resource provisioning and configuration of functional blocks. +Doesn't handle any I/O. It sets up few basic stuff but most of the +funcionality is achieved via configuration requests from PFs and VFs. + +PF/VFs communicates with AF via a shared memory region (mailbox). Upon +receiving requests AF does resource provisioning and other HW configuration. +AF is always attached to host kernel, but PFs and their VFs may be used by host +kernel itself, or attached to VMs or to userspace applications like +DPDK etc. So AF has to handle provisioning/configuration requests sent +by any device from any domain. + +AF driver also interacts with underlying firmware to + - Manage physical ethernet links ie CGX LMACs. + - Retrieve information like speed, duplex, autoneg etc + - Retrieve PHY EEPROM and stats. + - Configure FEC, PAM modes + - etc + +From pure networking side AF driver supports following functionality. + - Map a physical link to a RVU PF to which a netdev is registered. + - Attach NIX and NPA block LFs to RVU PF/VF which provide buffer pools, RQs, SQs + for regular networking functionality. + - Flow control (pause frames) enable/disable/config. + - HW PTP timestamping related config. + - NPC parser profile config, basically how to parse pkt and what info to extract. + - NPC extract profile config, what to extract from the pkt to match data in MCAM entries. + - Manage NPC MCAM entries, upon request can frame and install requested packet forwarding rules. + - Defines receive side scaling (RSS) algorithms. + - Defines segmentation offload algorithms (eg TSO) + - VLAN stripping, capture and insertion config. + - SSO and TIM blocks config which provide packet scheduling support. + - Debugfs support, to check current resource provising, current status of + NPA pools, NIX RQ, SQ and CQs, various stats etc which helps in debugging issues. + - And many more. + +Physical Function driver +------------------------ + +This RVU PF handles IO, is mapped to a physical ethernet link and this +driver registers a netdev. This supports SR-IOV. As said above this driver +communicates with AF with a mailbox. To retrieve information from physical +links this driver talks to AF and AF gets that info from firmware and responds +back ie cannot talk to firmware directly. + +Supports ethtool for configuring links, RSS, queue count, queue size, +flow control, ntuple filters, dump PHY EEPROM, config FEC etc. + +Virtual Function driver +----------------------- + +There are two types VFs, VFs that share the physical link with their parent +SR-IOV PF and the VFs which work in pairs using internal HW loopback channels (LBK). + +Type1: + - These VFs and their parent PF share a physical link and used for outside communication. + - VFs cannot communicate with AF directly, they send mbox message to PF and PF + forwards that to AF. AF after processing, responds back to PF and PF forwards + the reply to VF. + - From functionality point of view there is no difference between PF and VF as same type + HW resources are attached to both. But user would be able to configure few stuff only + from PF as PF is treated as owner/admin of the link. + +Type2: + - RVU PF0 ie admin function creates these VFs and maps them to loopback block's channels. + - A set of two VFs (VF0 & VF1, VF2 & VF3 .. so on) works as a pair ie pkts sent out of + VF0 will be received by VF1 and viceversa. + - These VFs can be used by applications or virtual machines to communicate between them + without sending traffic outside. There is no switch present in HW, hence the support + for loopback VFs. + - These communicate directly with AF (PF0) via mbox. + +Except for the IO channels or links used for packet reception and transmission there is +no other difference between these VF types. AF driver takes care of IO channel mapping, +hence same VF driver works for both types of devices. + +Basic packet flow +================= + +Ingress +------- + +1. CGX LMAC receives packet. +2. Forwards the packet to the NIX block. +3. Then submitted to NPC block for parsing and then MCAM lookup to get the destination RVU device. +4. NIX LF attached to the destination RVU device allocates a buffer from RQ mapped buffer pool of NPA block LF. +5. RQ may be selected by RSS or by configuring MCAM rule with a RQ number. +6. Packet is DMA'ed and driver is notified. + +Egress +------ + +1. Driver prepares a send descriptor and submits to SQ for transmission. +2. The SQ is already configured (by AF) to transmit on a specific link/channel. +3. The SQ descriptor ring is maintained in buffers allocated from SQ mapped pool of NPA block LF. +4. NIX block transmits the pkt on the designated channel. +5. NPC MCAM entries can be installed to divert pkt onto a different channel. diff --git a/Documentation/networking/device_drivers/microsoft/netvsc.txt b/Documentation/networking/device_drivers/microsoft/netvsc.txt index 3bfa635bbbd5..cd63556b27a0 100644 --- a/Documentation/networking/device_drivers/microsoft/netvsc.txt +++ b/Documentation/networking/device_drivers/microsoft/netvsc.txt @@ -82,3 +82,24 @@ Features contain one or more packets. The send buffer is an optimization, the driver will use slower method to handle very large packets or if the send buffer area is exhausted. + + XDP support + ----------- + XDP (eXpress Data Path) is a feature that runs eBPF bytecode at the early + stage when packets arrive at a NIC card. The goal is to increase performance + for packet processing, reducing the overhead of SKB allocation and other + upper network layers. + + hv_netvsc supports XDP in native mode, and transparently sets the XDP + program on the associated VF NIC as well. + + Setting / unsetting XDP program on synthetic NIC (netvsc) propagates to + VF NIC automatically. Setting / unsetting XDP program on VF NIC directly + is not recommended, also not propagated to synthetic NIC, and may be + overwritten by setting of synthetic NIC. + + XDP program cannot run with LRO (RSC) enabled, so you need to disable LRO + before running XDP: + ethtool -K eth0 lro off + + XDP_REDIRECT action is not yet supported. diff --git a/Documentation/networking/device_drivers/netronome/nfp.rst b/Documentation/networking/device_drivers/netronome/nfp.rst index 6c08ac8b5147..ada611fb427c 100644 --- a/Documentation/networking/device_drivers/netronome/nfp.rst +++ b/Documentation/networking/device_drivers/netronome/nfp.rst @@ -131,3 +131,119 @@ abi_drv_reset abi_drv_load_ifc Defines a list of PF devices allowed to load FW on the device. This variable is not currently user configurable. + +Statistics +========== + +Following device statistics are available through the ``ethtool -S`` interface: + +.. flat-table:: NFP device statistics + :header-rows: 1 + :widths: 3 1 11 + + * - Name + - ID + - Meaning + + * - dev_rx_discards + - 1 + - Packet can be discarded on the RX path for one of the following reasons: + + * The NIC is not in promisc mode, and the destination MAC address + doesn't match the interfaces' MAC address. + * The received packet is larger than the max buffer size on the host. + I.e. it exceeds the Layer 3 MRU. + * There is no freelist descriptor available on the host for the packet. + It is likely that the NIC couldn't cache one in time. + * A BPF program discarded the packet. + * The datapath drop action was executed. + * The MAC discarded the packet due to lack of ingress buffer space + on the NIC. + + * - dev_rx_errors + - 2 + - A packet can be counted (and dropped) as RX error for the following + reasons: + + * A problem with the VEB lookup (only when SR-IOV is used). + * A physical layer problem that causes Ethernet errors, like FCS or + alignment errors. The cause is usually faulty cables or SFPs. + + * - dev_rx_bytes + - 3 + - Total number of bytes received. + + * - dev_rx_uc_bytes + - 4 + - Unicast bytes received. + + * - dev_rx_mc_bytes + - 5 + - Multicast bytes received. + + * - dev_rx_bc_bytes + - 6 + - Broadcast bytes received. + + * - dev_rx_pkts + - 7 + - Total number of packets received. + + * - dev_rx_mc_pkts + - 8 + - Multicast packets received. + + * - dev_rx_bc_pkts + - 9 + - Broadcast packets received. + + * - dev_tx_discards + - 10 + - A packet can be discarded in the TX direction if the MAC is + being flow controlled and the NIC runs out of TX queue space. + + * - dev_tx_errors + - 11 + - A packet can be counted as TX error (and dropped) for one for the + following reasons: + + * The packet is an LSO segment, but the Layer 3 or Layer 4 offset + could not be determined. Therefore LSO could not continue. + * An invalid packet descriptor was received over PCIe. + * The packet Layer 3 length exceeds the device MTU. + * An error on the MAC/physical layer. Usually due to faulty cables or + SFPs. + * A CTM buffer could not be allocated. + * The packet offset was incorrect and could not be fixed by the NIC. + + * - dev_tx_bytes + - 12 + - Total number of bytes transmitted. + + * - dev_tx_uc_bytes + - 13 + - Unicast bytes transmitted. + + * - dev_tx_mc_bytes + - 14 + - Multicast bytes transmitted. + + * - dev_tx_bc_bytes + - 15 + - Broadcast bytes transmitted. + + * - dev_tx_pkts + - 16 + - Total number of packets transmitted. + + * - dev_tx_mc_pkts + - 17 + - Multicast packets transmitted. + + * - dev_tx_bc_pkts + - 18 + - Broadcast packets transmitted. + +Note that statistics unknown to the driver will be displayed as +``dev_unknown_stat$ID``, where ``$ID`` refers to the second column +above. diff --git a/Documentation/networking/device_drivers/stmicro/stmmac.rst b/Documentation/networking/device_drivers/stmicro/stmmac.rst new file mode 100644 index 000000000000..c34bab3d2df0 --- /dev/null +++ b/Documentation/networking/device_drivers/stmicro/stmmac.rst @@ -0,0 +1,697 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +============================================================== +Linux Driver for the Synopsys(R) Ethernet Controllers "stmmac" +============================================================== + +Authors: Giuseppe Cavallaro <peppe.cavallaro@st.com>, +Alexandre Torgue <alexandre.torgue@st.com>, Jose Abreu <joabreu@synopsys.com> + +Contents +======== + +- In This Release +- Feature List +- Kernel Configuration +- Command Line Parameters +- Driver Information and Notes +- Debug Information +- Support + +In This Release +=============== + +This file describes the stmmac Linux Driver for all the Synopsys(R) Ethernet +Controllers. + +Currently, this network device driver is for all STi embedded MAC/GMAC +(i.e. 7xxx/5xxx SoCs), SPEAr (arm), Loongson1B (mips) and XILINX XC2V3000 +FF1152AMT0221 D1215994A VIRTEX FPGA board. The Synopsys Ethernet QoS 5.0 IPK +is also supported. + +DesignWare(R) Cores Ethernet MAC 10/100/1000 Universal version 3.70a +(and older) and DesignWare(R) Cores Ethernet Quality-of-Service version 4.0 +(and upper) have been used for developing this driver as well as +DesignWare(R) Cores XGMAC - 10G Ethernet MAC. + +This driver supports both the platform bus and PCI. + +This driver includes support for the following Synopsys(R) DesignWare(R) +Cores Ethernet Controllers and corresponding minimum and maximum versions: + ++-------------------------------+--------------+--------------+--------------+ +| Controller Name | Min. Version | Max. Version | Abbrev. Name | ++===============================+==============+==============+==============+ +| Ethernet MAC Universal | N/A | 3.73a | GMAC | ++-------------------------------+--------------+--------------+--------------+ +| Ethernet Quality-of-Service | 4.00a | N/A | GMAC4+ | ++-------------------------------+--------------+--------------+--------------+ +| XGMAC - 10G Ethernet MAC | 2.10a | N/A | XGMAC2+ | ++-------------------------------+--------------+--------------+--------------+ + +For questions related to hardware requirements, refer to the documentation +supplied with your Ethernet adapter. All hardware requirements listed apply +to use with Linux. + +Feature List +============ + +The following features are available in this driver: + - GMII/MII/RGMII/SGMII/RMII/XGMII Interface + - Half-Duplex / Full-Duplex Operation + - Energy Efficient Ethernet (EEE) + - IEEE 802.3x PAUSE Packets (Flow Control) + - RMON/MIB Counters + - IEEE 1588 Timestamping (PTP) + - Pulse-Per-Second Output (PPS) + - MDIO Clause 22 / Clause 45 Interface + - MAC Loopback + - ARP Offloading + - Automatic CRC / PAD Insertion and Checking + - Checksum Offload for Received and Transmitted Packets + - Standard or Jumbo Ethernet Packets + - Source Address Insertion / Replacement + - VLAN TAG Insertion / Replacement / Deletion / Filtering (HASH and PERFECT) + - Programmable TX and RX Watchdog and Coalesce Settings + - Destination Address Filtering (PERFECT) + - HASH Filtering (Multicast) + - Layer 3 / Layer 4 Filtering + - Remote Wake-Up Detection + - Receive Side Scaling (RSS) + - Frame Preemption for TX and RX + - Programmable Burst Length, Threshold, Queue Size + - Multiple Queues (up to 8) + - Multiple Scheduling Algorithms (TX: WRR, DWRR, WFQ, SP, CBS, EST, TBS; + RX: WRR, SP) + - Flexible RX Parser + - TCP / UDP Segmentation Offload (TSO, USO) + - Split Header (SPH) + - Safety Features (ECC Protection, Data Parity Protection) + - Selftests using Ethtool + +Kernel Configuration +==================== + +The kernel configuration option is ``CONFIG_STMMAC_ETH``: + - ``CONFIG_STMMAC_PLATFORM``: is to enable the platform driver. + - ``CONFIG_STMMAC_PCI``: is to enable the pci driver. + +Command Line Parameters +======================= + +If the driver is built as a module the following optional parameters are used +by entering them on the command line with the modprobe command using this +syntax (e.g. for PCI module):: + + modprobe stmmac_pci [<option>=<VAL1>,<VAL2>,...] + +Driver parameters can be also passed in command line by using:: + + stmmaceth=watchdog:100,chain_mode=1 + +The default value for each parameter is generally the recommended setting, +unless otherwise noted. + +watchdog +-------- +:Valid Range: 5000-None +:Default Value: 5000 + +This parameter overrides the transmit timeout in milliseconds. + +debug +----- +:Valid Range: 0-16 (0=none,...,16=all) +:Default Value: 0 + +This parameter adjusts the level of debug messages displayed in the system +logs. + +phyaddr +------- +:Valid Range: 0-31 +:Default Value: -1 + +This parameter overrides the physical address of the PHY device. + +flow_ctrl +--------- +:Valid Range: 0-3 (0=off,1=rx,2=tx,3=rx/tx) +:Default Value: 3 + +This parameter changes the default Flow Control ability. + +pause +----- +:Valid Range: 0-65535 +:Default Value: 65535 + +This parameter changes the default Flow Control Pause time. + +tc +-- +:Valid Range: 64-256 +:Default Value: 64 + +This parameter changes the default HW FIFO Threshold control value. + +buf_sz +------ +:Valid Range: 1536-16384 +:Default Value: 1536 + +This parameter changes the default RX DMA packet buffer size. + +eee_timer +--------- +:Valid Range: 0-None +:Default Value: 1000 + +This parameter changes the default LPI TX Expiration time in milliseconds. + +chain_mode +---------- +:Valid Range: 0-1 (0=off,1=on) +:Default Value: 0 + +This parameter changes the default mode of operation from Ring Mode to +Chain Mode. + +Driver Information and Notes +============================ + +Transmit Process +---------------- + +The xmit method is invoked when the kernel needs to transmit a packet; it sets +the descriptors in the ring and informs the DMA engine that there is a packet +ready to be transmitted. + +By default, the driver sets the ``NETIF_F_SG`` bit in the features field of +the ``net_device`` structure, enabling the scatter-gather feature. This is +true on chips and configurations where the checksum can be done in hardware. + +Once the controller has finished transmitting the packet, timer will be +scheduled to release the transmit resources. + +Receive Process +--------------- + +When one or more packets are received, an interrupt happens. The interrupts +are not queued, so the driver has to scan all the descriptors in the ring +during the receive process. + +This is based on NAPI, so the interrupt handler signals only if there is work +to be done, and it exits. Then the poll method will be scheduled at some +future point. + +The incoming packets are stored, by the DMA, in a list of pre-allocated socket +buffers in order to avoid the memcpy (zero-copy). + +Interrupt Mitigation +-------------------- + +The driver is able to mitigate the number of its DMA interrupts using NAPI for +the reception on chips older than the 3.50. New chips have an HW RX Watchdog +used for this mitigation. + +Mitigation parameters can be tuned by ethtool. + +WoL +--- + +Wake up on Lan feature through Magic and Unicast frames are supported for the +GMAC, GMAC4/5 and XGMAC core. + +DMA Descriptors +--------------- + +Driver handles both normal and alternate descriptors. The latter has been only +tested on DesignWare(R) Cores Ethernet MAC Universal version 3.41a and later. + +stmmac supports DMA descriptor to operate both in dual buffer (RING) and +linked-list(CHAINED) mode. In RING each descriptor points to two data buffer +pointers whereas in CHAINED mode they point to only one data buffer pointer. +RING mode is the default. + +In CHAINED mode each descriptor will have pointer to next descriptor in the +list, hence creating the explicit chaining in the descriptor itself, whereas +such explicit chaining is not possible in RING mode. + +Extended Descriptors +-------------------- + +The extended descriptors give us information about the Ethernet payload when +it is carrying PTP packets or TCP/UDP/ICMP over IP. These are not available on +GMAC Synopsys(R) chips older than the 3.50. At probe time the driver will +decide if these can be actually used. This support also is mandatory for PTPv2 +because the extra descriptors are used for saving the hardware timestamps and +Extended Status. + +Ethtool Support +--------------- + +Ethtool is supported. For example, driver statistics (including RMON), +internal errors can be taken using:: + + ethtool -S ethX + +Ethtool selftests are also supported. This allows to do some early sanity +checks to the HW using MAC and PHY loopback mechanisms:: + + ethtool -t ethX + +Jumbo and Segmentation Offloading +--------------------------------- + +Jumbo frames are supported and tested for the GMAC. The GSO has been also +added but it's performed in software. LRO is not supported. + +TSO Support +----------- + +TSO (TCP Segmentation Offload) feature is supported by GMAC > 4.x and XGMAC +chip family. When a packet is sent through TCP protocol, the TCP stack ensures +that the SKB provided to the low level driver (stmmac in our case) matches +with the maximum frame len (IP header + TCP header + payload <= 1500 bytes +(for MTU set to 1500)). It means that if an application using TCP want to send +a packet which will have a length (after adding headers) > 1514 the packet +will be split in several TCP packets: The data payload is split and headers +(TCP/IP ..) are added. It is done by software. + +When TSO is enabled, the TCP stack doesn't care about the maximum frame length +and provide SKB packet to stmmac as it is. The GMAC IP will have to perform +the segmentation by it self to match with maximum frame length. + +This feature can be enabled in device tree through ``snps,tso`` entry. + +Energy Efficient Ethernet +------------------------- + +Energy Efficient Ethernet (EEE) enables IEEE 802.3 MAC sublayer along with a +family of Physical layer to operate in the Low Power Idle (LPI) mode. The EEE +mode supports the IEEE 802.3 MAC operation at 100Mbps, 1000Mbps and 1Gbps. + +The LPI mode allows power saving by switching off parts of the communication +device functionality when there is no data to be transmitted & received. +The system on both the side of the link can disable some functionalities and +save power during the period of low-link utilization. The MAC controls whether +the system should enter or exit the LPI mode and communicate this to PHY. + +As soon as the interface is opened, the driver verifies if the EEE can be +supported. This is done by looking at both the DMA HW capability register and +the PHY devices MCD registers. + +To enter in TX LPI mode the driver needs to have a software timer that enable +and disable the LPI mode when there is nothing to be transmitted. + +Precision Time Protocol (PTP) +----------------------------- + +The driver supports the IEEE 1588-2002, Precision Time Protocol (PTP), which +enables precise synchronization of clocks in measurement and control systems +implemented with technologies such as network communication. + +In addition to the basic timestamp features mentioned in IEEE 1588-2002 +Timestamps, new GMAC cores support the advanced timestamp features. +IEEE 1588-2008 can be enabled when configuring the Kernel. + +SGMII/RGMII Support +------------------- + +New GMAC devices provide own way to manage RGMII/SGMII. This information is +available at run-time by looking at the HW capability register. This means +that the stmmac can manage auto-negotiation and link status w/o using the +PHYLIB stuff. In fact, the HW provides a subset of extended registers to +restart the ANE, verify Full/Half duplex mode and Speed. Thanks to these +registers, it is possible to look at the Auto-negotiated Link Parter Ability. + +Physical +-------- + +The driver is compatible with Physical Abstraction Layer to be connected with +PHY and GPHY devices. + +Platform Information +-------------------- + +Several information can be passed through the platform and device-tree. + +:: + + struct plat_stmmacenet_data { + +1) Bus identifier:: + + int bus_id; + +2) PHY Physical Address. If set to -1 the driver will pick the first PHY it +finds:: + + int phy_addr; + +3) PHY Device Interface:: + + int interface; + +4) Specific platform fields for the MDIO bus:: + + struct stmmac_mdio_bus_data *mdio_bus_data; + +5) Internal DMA parameters:: + + struct stmmac_dma_cfg *dma_cfg; + +6) Fixed CSR Clock Range selection:: + + int clk_csr; + +7) HW uses the GMAC core:: + + int has_gmac; + +8) If set the MAC will use Enhanced Descriptors:: + + int enh_desc; + +9) Core is able to perform TX Checksum and/or RX Checksum in HW:: + + int tx_coe; + int rx_coe; + +11) Some HWs are not able to perform the csum in HW for over-sized frames due +to limited buffer sizes. Setting this flag the csum will be done in SW on +JUMBO frames:: + + int bugged_jumbo; + +12) Core has the embedded power module:: + + int pmt; + +13) Force DMA to use the Store and Forward mode or Threshold mode:: + + int force_sf_dma_mode; + int force_thresh_dma_mode; + +15) Force to disable the RX Watchdog feature and switch to NAPI mode:: + + int riwt_off; + +16) Limit the maximum operating speed and MTU:: + + int max_speed; + int maxmtu; + +18) Number of Multicast/Unicast filters:: + + int multicast_filter_bins; + int unicast_filter_entries; + +20) Limit the maximum TX and RX FIFO size:: + + int tx_fifo_size; + int rx_fifo_size; + +21) Use the specified number of TX and RX Queues:: + + u32 rx_queues_to_use; + u32 tx_queues_to_use; + +22) Use the specified TX and RX scheduling algorithm:: + + u8 rx_sched_algorithm; + u8 tx_sched_algorithm; + +23) Internal TX and RX Queue parameters:: + + struct stmmac_rxq_cfg rx_queues_cfg[MTL_MAX_RX_QUEUES]; + struct stmmac_txq_cfg tx_queues_cfg[MTL_MAX_TX_QUEUES]; + +24) This callback is used for modifying some syscfg registers (on ST SoCs) +according to the link speed negotiated by the physical layer:: + + void (*fix_mac_speed)(void *priv, unsigned int speed); + +25) Callbacks used for calling a custom initialization; This is sometimes +necessary on some platforms (e.g. ST boxes) where the HW needs to have set +some PIO lines or system cfg registers. init/exit callbacks should not use +or modify platform data:: + + int (*init)(struct platform_device *pdev, void *priv); + void (*exit)(struct platform_device *pdev, void *priv); + +26) Perform HW setup of the bus. For example, on some ST platforms this field +is used to configure the AMBA bridge to generate more efficient STBus traffic:: + + struct mac_device_info *(*setup)(void *priv); + void *bsp_priv; + +27) Internal clocks and rates:: + + struct clk *stmmac_clk; + struct clk *pclk; + struct clk *clk_ptp_ref; + unsigned int clk_ptp_rate; + unsigned int clk_ref_rate; + s32 ptp_max_adj; + +28) Main reset:: + + struct reset_control *stmmac_rst; + +29) AXI Internal Parameters:: + + struct stmmac_axi *axi; + +30) HW uses GMAC>4 cores:: + + int has_gmac4; + +31) HW is sun8i based:: + + bool has_sun8i; + +32) Enables TSO feature:: + + bool tso_en; + +33) Enables Receive Side Scaling (RSS) feature:: + + int rss_en; + +34) MAC Port selection:: + + int mac_port_sel_speed; + +35) Enables TX LPI Clock Gating:: + + bool en_tx_lpi_clockgating; + +36) HW uses XGMAC>2.10 cores:: + + int has_xgmac; + +:: + + } + +For MDIO bus data, we have: + +:: + + struct stmmac_mdio_bus_data { + +1) PHY mask passed when MDIO bus is registered:: + + unsigned int phy_mask; + +2) List of IRQs, one per PHY:: + + int *irqs; + +3) If IRQs is NULL, use this for probed PHY:: + + int probed_phy_irq; + +4) Set to true if PHY needs reset:: + + bool needs_reset; + +:: + + } + +For DMA engine configuration, we have: + +:: + + struct stmmac_dma_cfg { + +1) Programmable Burst Length (TX and RX):: + + int pbl; + +2) If set, DMA TX / RX will use this value rather than pbl:: + + int txpbl; + int rxpbl; + +3) Enable 8xPBL:: + + bool pblx8; + +4) Enable Fixed or Mixed burst:: + + int fixed_burst; + int mixed_burst; + +5) Enable Address Aligned Beats:: + + bool aal; + +6) Enable Enhanced Addressing (> 32 bits):: + + bool eame; + +:: + + } + +For DMA AXI parameters, we have: + +:: + + struct stmmac_axi { + +1) Enable AXI LPI:: + + bool axi_lpi_en; + bool axi_xit_frm; + +2) Set AXI Write / Read maximum outstanding requests:: + + u32 axi_wr_osr_lmt; + u32 axi_rd_osr_lmt; + +3) Set AXI 4KB bursts:: + + bool axi_kbbe; + +4) Set AXI maximum burst length map:: + + u32 axi_blen[AXI_BLEN]; + +5) Set AXI Fixed burst / mixed burst:: + + bool axi_fb; + bool axi_mb; + +6) Set AXI rebuild incrx mode:: + + bool axi_rb; + +:: + + } + +For the RX Queues configuration, we have: + +:: + + struct stmmac_rxq_cfg { + +1) Mode to use (DCB or AVB):: + + u8 mode_to_use; + +2) DMA channel to use:: + + u32 chan; + +3) Packet routing, if applicable:: + + u8 pkt_route; + +4) Use priority routing, and priority to route:: + + bool use_prio; + u32 prio; + +:: + + } + +For the TX Queues configuration, we have: + +:: + + struct stmmac_txq_cfg { + +1) Queue weight in scheduler:: + + u32 weight; + +2) Mode to use (DCB or AVB):: + + u8 mode_to_use; + +3) Credit Base Shaper Parameters:: + + u32 send_slope; + u32 idle_slope; + u32 high_credit; + u32 low_credit; + +4) Use priority scheduling, and priority:: + + bool use_prio; + u32 prio; + +:: + + } + +Device Tree Information +----------------------- + +Please refer to the following document: +Documentation/devicetree/bindings/net/snps,dwmac.yaml + +HW Capabilities +--------------- + +Note that, starting from new chips, where it is available the HW capability +register, many configurations are discovered at run-time for example to +understand if EEE, HW csum, PTP, enhanced descriptor etc are actually +available. As strategy adopted in this driver, the information from the HW +capability register can replace what has been passed from the platform. + +Debug Information +================= + +The driver exports many information i.e. internal statistics, debug +information, MAC and DMA registers etc. + +These can be read in several ways depending on the type of the information +actually needed. + +For example a user can be use the ethtool support to get statistics: e.g. +using: ``ethtool -S ethX`` (that shows the Management counters (MMC) if +supported) or sees the MAC/DMA registers: e.g. using: ``ethtool -d ethX`` + +Compiling the Kernel with ``CONFIG_DEBUG_FS`` the driver will export the +following debugfs entries: + + - ``descriptors_status``: To show the DMA TX/RX descriptor rings + - ``dma_cap``: To show the HW Capabilities + +Developer can also use the ``debug`` module parameter to get further debug +information (please see: NETIF Msg Level). + +Support +======= + +If an issue is identified with the released source code on a supported kernel +with a supported adapter, email the specific information related to the +issue to netdev@vger.kernel.org diff --git a/Documentation/networking/device_drivers/stmicro/stmmac.txt b/Documentation/networking/device_drivers/stmicro/stmmac.txt deleted file mode 100644 index 1ae979fd90d2..000000000000 --- a/Documentation/networking/device_drivers/stmicro/stmmac.txt +++ /dev/null @@ -1,401 +0,0 @@ - STMicroelectronics 10/100/1000 Synopsys Ethernet driver - -Copyright (C) 2007-2015 STMicroelectronics Ltd -Author: Giuseppe Cavallaro <peppe.cavallaro@st.com> - -This is the driver for the MAC 10/100/1000 on-chip Ethernet controllers -(Synopsys IP blocks). - -Currently this network device driver is for all STi embedded MAC/GMAC -(i.e. 7xxx/5xxx SoCs), SPEAr (arm), Loongson1B (mips) and XLINX XC2V3000 -FF1152AMT0221 D1215994A VIRTEX FPGA board. - -DWC Ether MAC 10/100/1000 Universal version 3.70a (and older) and DWC Ether -MAC 10/100 Universal version 4.0 have been used for developing this driver. - -This driver supports both the platform bus and PCI. - -Please, for more information also visit: www.stlinux.com - -1) Kernel Configuration -The kernel configuration option is STMMAC_ETH: - Device Drivers ---> Network device support ---> Ethernet (1000 Mbit) ---> - STMicroelectronics 10/100/1000 Ethernet driver (STMMAC_ETH) - -CONFIG_STMMAC_PLATFORM: is to enable the platform driver. -CONFIG_STMMAC_PCI: is to enable the pci driver. - -2) Driver parameters list: - debug: message level (0: no output, 16: all); - phyaddr: to manually provide the physical address to the PHY device; - buf_sz: DMA buffer size; - tc: control the HW FIFO threshold; - watchdog: transmit timeout (in milliseconds); - flow_ctrl: Flow control ability [on/off]; - pause: Flow Control Pause Time; - eee_timer: tx EEE timer; - chain_mode: select chain mode instead of ring. - -3) Command line options -Driver parameters can be also passed in command line by using: - stmmaceth=watchdog:100,chain_mode=1 - -4) Driver information and notes - -4.1) Transmit process -The xmit method is invoked when the kernel needs to transmit a packet; it sets -the descriptors in the ring and informs the DMA engine, that there is a packet -ready to be transmitted. -By default, the driver sets the NETIF_F_SG bit in the features field of the -net_device structure, enabling the scatter-gather feature. This is true on -chips and configurations where the checksum can be done in hardware. -Once the controller has finished transmitting the packet, timer will be -scheduled to release the transmit resources. - -4.2) Receive process -When one or more packets are received, an interrupt happens. The interrupts -are not queued, so the driver has to scan all the descriptors in the ring during -the receive process. -This is based on NAPI, so the interrupt handler signals only if there is work -to be done, and it exits. -Then the poll method will be scheduled at some future point. -The incoming packets are stored, by the DMA, in a list of pre-allocated socket -buffers in order to avoid the memcpy (zero-copy). - -4.3) Interrupt mitigation -The driver is able to mitigate the number of its DMA interrupts -using NAPI for the reception on chips older than the 3.50. -New chips have an HW RX-Watchdog used for this mitigation. -Mitigation parameters can be tuned by ethtool. - -4.4) WOL -Wake up on Lan feature through Magic and Unicast frames are supported for the -GMAC core. - -4.5) DMA descriptors -Driver handles both normal and alternate descriptors. The latter has been only -tested on DWC Ether MAC 10/100/1000 Universal version 3.41a and later. - -STMMAC supports DMA descriptor to operate both in dual buffer (RING) -and linked-list(CHAINED) mode. In RING each descriptor points to two -data buffer pointers whereas in CHAINED mode they point to only one data -buffer pointer. RING mode is the default. - -In CHAINED mode each descriptor will have pointer to next descriptor in -the list, hence creating the explicit chaining in the descriptor itself, -whereas such explicit chaining is not possible in RING mode. - -4.5.1) Extended descriptors -The extended descriptors give us information about the Ethernet payload -when it is carrying PTP packets or TCP/UDP/ICMP over IP. -These are not available on GMAC Synopsys chips older than the 3.50. -At probe time the driver will decide if these can be actually used. -This support also is mandatory for PTPv2 because the extra descriptors -are used for saving the hardware timestamps and Extended Status. - -4.6) Ethtool support -Ethtool is supported. - -For example, driver statistics (including RMON), internal errors can be taken -using: - # ethtool -S ethX -command - -4.7) Jumbo and Segmentation Offloading -Jumbo frames are supported and tested for the GMAC. -The GSO has been also added but it's performed in software. -LRO is not supported. - -4.8) Physical -The driver is compatible with Physical Abstraction Layer to be connected with -PHY and GPHY devices. - -4.9) Platform information -Several information can be passed through the platform and device-tree. - -struct plat_stmmacenet_data { - char *phy_bus_name; - int bus_id; - int phy_addr; - int interface; - struct stmmac_mdio_bus_data *mdio_bus_data; - struct stmmac_dma_cfg *dma_cfg; - int clk_csr; - int has_gmac; - int enh_desc; - int tx_coe; - int rx_coe; - int bugged_jumbo; - int pmt; - int force_sf_dma_mode; - int force_thresh_dma_mode; - int riwt_off; - int max_speed; - int maxmtu; - void (*fix_mac_speed)(void *priv, unsigned int speed); - void (*bus_setup)(void __iomem *ioaddr); - int (*init)(struct platform_device *pdev, void *priv); - void (*exit)(struct platform_device *pdev, void *priv); - void *bsp_priv; - int has_gmac4; - bool tso_en; -}; - -Where: - o phy_bus_name: phy bus name to attach to the stmmac. - o bus_id: bus identifier. - o phy_addr: the physical address can be passed from the platform. - If it is set to -1 the driver will automatically - detect it at run-time by probing all the 32 addresses. - o interface: PHY device's interface. - o mdio_bus_data: specific platform fields for the MDIO bus. - o dma_cfg: internal DMA parameters - o pbl: the Programmable Burst Length is maximum number of beats to - be transferred in one DMA transaction. - GMAC also enables the 4xPBL by default. (8xPBL for GMAC 3.50 and newer) - o txpbl/rxpbl: GMAC and newer supports independent DMA pbl for tx/rx. - o pblx8: Enable 8xPBL (4xPBL for core rev < 3.50). Enabled by default. - o fixed_burst/mixed_burst/aal - o clk_csr: fixed CSR Clock range selection. - o has_gmac: uses the GMAC core. - o enh_desc: if sets the MAC will use the enhanced descriptor structure. - o tx_coe: core is able to perform the tx csum in HW. - o rx_coe: the supports three check sum offloading engine types: - type_1, type_2 (full csum) and no RX coe. - o bugged_jumbo: some HWs are not able to perform the csum in HW for - over-sized frames due to limited buffer sizes. - Setting this flag the csum will be done in SW on - JUMBO frames. - o pmt: core has the embedded power module (optional). - o force_sf_dma_mode: force DMA to use the Store and Forward mode - instead of the Threshold. - o force_thresh_dma_mode: force DMA to use the Threshold mode other than - the Store and Forward mode. - o riwt_off: force to disable the RX watchdog feature and switch to NAPI mode. - o fix_mac_speed: this callback is used for modifying some syscfg registers - (on ST SoCs) according to the link speed negotiated by the - physical layer . - o bus_setup: perform HW setup of the bus. For example, on some ST platforms - this field is used to configure the AMBA bridge to generate more - efficient STBus traffic. - o init/exit: callbacks used for calling a custom initialization; - this is sometime necessary on some platforms (e.g. ST boxes) - where the HW needs to have set some PIO lines or system cfg - registers. init/exit callbacks should not use or modify - platform data. - o bsp_priv: another private pointer. - o has_gmac4: uses GMAC4 core. - o tso_en: Enables TSO (TCP Segmentation Offload) feature. - -For MDIO bus The we have: - - struct stmmac_mdio_bus_data { - int (*phy_reset)(void *priv); - unsigned int phy_mask; - int *irqs; - int probed_phy_irq; - }; - -Where: - o phy_reset: hook to reset the phy device attached to the bus. - o phy_mask: phy mask passed when register the MDIO bus within the driver. - o irqs: list of IRQs, one per PHY. - o probed_phy_irq: if irqs is NULL, use this for probed PHY. - -For DMA engine we have the following internal fields that should be -tuned according to the HW capabilities. - -struct stmmac_dma_cfg { - int pbl; - int txpbl; - int rxpbl; - bool pblx8; - int fixed_burst; - int mixed_burst; - bool aal; -}; - -Where: - o pbl: Programmable Burst Length (tx and rx) - o txpbl: Transmit Programmable Burst Length. Only for GMAC and newer. - If set, DMA tx will use this value rather than pbl. - o rxpbl: Receive Programmable Burst Length. Only for GMAC and newer. - If set, DMA rx will use this value rather than pbl. - o pblx8: Enable 8xPBL (4xPBL for core rev < 3.50). Enabled by default. - o fixed_burst: program the DMA to use the fixed burst mode - o mixed_burst: program the DMA to use the mixed burst mode - o aal: Address-Aligned Beats - ---- - -Below an example how the structures above are using on ST platforms. - - static struct plat_stmmacenet_data stxYYY_ethernet_platform_data = { - .has_gmac = 0, - .enh_desc = 0, - .fix_mac_speed = stxYYY_ethernet_fix_mac_speed, - | - |-> to write an internal syscfg - | on this platform when the - | link speed changes from 10 to - | 100 and viceversa - .init = &stmmac_claim_resource, - | - |-> On ST SoC this calls own "PAD" - | manager framework to claim - | all the resources necessary - | (GPIO ...). The .custom_cfg field - | is used to pass a custom config. -}; - -Below the usage of the stmmac_mdio_bus_data: on this SoC, in fact, -there are two MAC cores: one MAC is for MDIO Bus/PHY emulation -with fixed_link support. - -static struct stmmac_mdio_bus_data stmmac1_mdio_bus = { - .phy_reset = phy_reset; - | - |-> function to provide the phy_reset on this board - .phy_mask = 0, -}; - -static struct fixed_phy_status stmmac0_fixed_phy_status = { - .link = 1, - .speed = 100, - .duplex = 1, -}; - -During the board's device_init we can configure the first -MAC for fixed_link by calling: - fixed_phy_add(PHY_POLL, 1, &stmmac0_fixed_phy_status); -and the second one, with a real PHY device attached to the bus, -by using the stmmac_mdio_bus_data structure (to provide the id, the -reset procedure etc). - -Note that, starting from new chips, where it is available the HW capability -register, many configurations are discovered at run-time for example to -understand if EEE, HW csum, PTP, enhanced descriptor etc are actually -available. As strategy adopted in this driver, the information from the HW -capability register can replace what has been passed from the platform. - -4.10) Device-tree support. - -Please see the following document: - Documentation/devicetree/bindings/net/stmmac.txt - -4.11) This is a summary of the content of some relevant files: - o stmmac_main.c: implements the main network device driver; - o stmmac_mdio.c: provides MDIO functions; - o stmmac_pci: this is the PCI driver; - o stmmac_platform.c: this the platform driver (OF supported); - o stmmac_ethtool.c: implements the ethtool support; - o stmmac.h: private driver structure; - o common.h: common definitions and VFTs; - o mmc_core.c/mmc.h: Management MAC Counters; - o stmmac_hwtstamp.c: HW timestamp support for PTP; - o stmmac_ptp.c: PTP 1588 clock; - o stmmac_pcs.h: Physical Coding Sublayer common implementation; - o dwmac-<XXX>.c: these are for the platform glue-logic file; e.g. dwmac-sti.c - for STMicroelectronics SoCs. - -- GMAC 3.x - o descs.h: descriptor structure definitions; - o dwmac1000_core.c: dwmac GiGa core functions; - o dwmac1000_dma.c: dma functions for the GMAC chip; - o dwmac1000.h: specific header file for the dwmac GiGa; - o dwmac100_core: dwmac 100 core code; - o dwmac100_dma.c: dma functions for the dwmac 100 chip; - o dwmac1000.h: specific header file for the MAC; - o dwmac_lib.c: generic DMA functions; - o enh_desc.c: functions for handling enhanced descriptors; - o norm_desc.c: functions for handling normal descriptors; - o chain_mode.c/ring_mode.c:: functions to manage RING/CHAINED modes; - -- GMAC4.x generation - o dwmac4_core.c: dwmac GMAC4.x core functions; - o dwmac4_desc.c: functions for handling GMAC4.x descriptors; - o dwmac4_descs.h: descriptor definitions; - o dwmac4_dma.c: dma functions for the GMAC4.x chip; - o dwmac4_dma.h: dma definitions for the GMAC4.x chip; - o dwmac4.h: core definitions for the GMAC4.x chip; - o dwmac4_lib.c: generic GMAC4.x functions; - -4.12) TSO support (GMAC4.x) - -TSO (Tcp Segmentation Offload) feature is supported by GMAC 4.x chip family. -When a packet is sent through TCP protocol, the TCP stack ensures that -the SKB provided to the low level driver (stmmac in our case) matches with -the maximum frame len (IP header + TCP header + payload <= 1500 bytes (for -MTU set to 1500)). It means that if an application using TCP want to send a -packet which will have a length (after adding headers) > 1514 the packet -will be split in several TCP packets: The data payload is split and headers -(TCP/IP ..) are added. It is done by software. - -When TSO is enabled, the TCP stack doesn't care about the maximum frame -length and provide SKB packet to stmmac as it is. The GMAC IP will have to -perform the segmentation by it self to match with maximum frame length. - -This feature can be enabled in device tree through "snps,tso" entry. - -5) Debug Information - -The driver exports many information i.e. internal statistics, -debug information, MAC and DMA registers etc. - -These can be read in several ways depending on the -type of the information actually needed. - -For example a user can be use the ethtool support -to get statistics: e.g. using: ethtool -S ethX -(that shows the Management counters (MMC) if supported) -or sees the MAC/DMA registers: e.g. using: ethtool -d ethX - -Compiling the Kernel with CONFIG_DEBUG_FS the driver will export the following -debugfs entries: - -/sys/kernel/debug/stmmaceth/descriptors_status - To show the DMA TX/RX descriptor rings - -Developer can also use the "debug" module parameter to get further debug -information (please see: NETIF Msg Level). - -6) Energy Efficient Ethernet - -Energy Efficient Ethernet(EEE) enables IEEE 802.3 MAC sublayer along -with a family of Physical layer to operate in the Low power Idle(LPI) -mode. The EEE mode supports the IEEE 802.3 MAC operation at 100Mbps, -1000Mbps & 10Gbps. - -The LPI mode allows power saving by switching off parts of the -communication device functionality when there is no data to be -transmitted & received. The system on both the side of the link can -disable some functionalities & save power during the period of low-link -utilization. The MAC controls whether the system should enter or exit -the LPI mode & communicate this to PHY. - -As soon as the interface is opened, the driver verifies if the EEE can -be supported. This is done by looking at both the DMA HW capability -register and the PHY devices MCD registers. -To enter in Tx LPI mode the driver needs to have a software timer -that enable and disable the LPI mode when there is nothing to be -transmitted. - -7) Precision Time Protocol (PTP) -The driver supports the IEEE 1588-2002, Precision Time Protocol (PTP), -which enables precise synchronization of clocks in measurement and -control systems implemented with technologies such as network -communication. - -In addition to the basic timestamp features mentioned in IEEE 1588-2002 -Timestamps, new GMAC cores support the advanced timestamp features. -IEEE 1588-2008 that can be enabled when configure the Kernel. - -8) SGMII/RGMII support -New GMAC devices provide own way to manage RGMII/SGMII. -This information is available at run-time by looking at the -HW capability register. This means that the stmmac can manage -auto-negotiation and link status w/o using the PHYLIB stuff. -In fact, the HW provides a subset of extended registers to -restart the ANE, verify Full/Half duplex mode and Speed. -Thanks to these registers, it is possible to look at the -Auto-negotiated Link Parter Ability. diff --git a/Documentation/networking/device_drivers/ti/cpsw_switchdev.txt b/Documentation/networking/device_drivers/ti/cpsw_switchdev.txt index 5c8cee17fca9..12855ab268b8 100644 --- a/Documentation/networking/device_drivers/ti/cpsw_switchdev.txt +++ b/Documentation/networking/device_drivers/ti/cpsw_switchdev.txt @@ -39,7 +39,7 @@ but without enabling "switch" mode, or to different bridges. Devlink configuration parameters ==================== -See Documentation/networking/devlink-params-ti-cpsw-switch.txt +See Documentation/networking/devlink/ti-cpsw-switch.rst ==================== # Bridging in dual mac mode diff --git a/Documentation/networking/devlink-health.txt b/Documentation/networking/devlink-health.txt deleted file mode 100644 index 1db3fbea0831..000000000000 --- a/Documentation/networking/devlink-health.txt +++ /dev/null @@ -1,86 +0,0 @@ -The health mechanism is targeted for Real Time Alerting, in order to know when -something bad had happened to a PCI device -- Provide alert debug information -- Self healing -- If problem needs vendor support, provide a way to gather all needed debugging - information. - -The main idea is to unify and centralize driver health reports in the -generic devlink instance and allow the user to set different -attributes of the health reporting and recovery procedures. - -The devlink health reporter: -Device driver creates a "health reporter" per each error/health type. -Error/Health type can be a known/generic (eg pci error, fw error, rx/tx error) -or unknown (driver specific). -For each registered health reporter a driver can issue error/health reports -asynchronously. All health reports handling is done by devlink. -Device driver can provide specific callbacks for each "health reporter", e.g. - - Recovery procedures - - Diagnostics and object dump procedures - - OOB initial parameters -Different parts of the driver can register different types of health reporters -with different handlers. - -Once an error is reported, devlink health will do the following actions: - * A log is being send to the kernel trace events buffer - * Health status and statistics are being updated for the reporter instance - * Object dump is being taken and saved at the reporter instance (as long as - there is no other dump which is already stored) - * Auto recovery attempt is being done. Depends on: - - Auto-recovery configuration - - Grace period vs. time passed since last recover - -The user interface: -User can access/change each reporter's parameters and driver specific callbacks -via devlink, e.g per error type (per health reporter) - - Configure reporter's generic parameters (like: disable/enable auto recovery) - - Invoke recovery procedure - - Run diagnostics - - Object dump - -The devlink health interface (via netlink): -DEVLINK_CMD_HEALTH_REPORTER_GET - Retrieves status and configuration info per DEV and reporter. -DEVLINK_CMD_HEALTH_REPORTER_SET - Allows reporter-related configuration setting. -DEVLINK_CMD_HEALTH_REPORTER_RECOVER - Triggers a reporter's recovery procedure. -DEVLINK_CMD_HEALTH_REPORTER_DIAGNOSE - Retrieves diagnostics data from a reporter on a device. -DEVLINK_CMD_HEALTH_REPORTER_DUMP_GET - Retrieves the last stored dump. Devlink health - saves a single dump. If an dump is not already stored by the devlink - for this reporter, devlink generates a new dump. - dump output is defined by the reporter. -DEVLINK_CMD_HEALTH_REPORTER_DUMP_CLEAR - Clears the last saved dump file for the specified reporter. - - - netlink - +--------------------------+ - | | - | + | - | | | - +--------------------------+ - |request for ops - |(diagnose, - mlx5_core devlink |recover, - |dump) -+--------+ +--------------------------+ -| | | reporter| | -| | | +---------v----------+ | -| | ops execution | | | | -| <----------------------------------+ | | -| | | | | | -| | | + ^------------------+ | -| | | | request for ops | -| | | | (recover, dump) | -| | | | | -| | | +-+------------------+ | -| | health report | | health handler | | -| +-------------------------------> | | -| | | +--------------------+ | -| | health reporter create | | -| +----------------------------> | -+--------+ +--------------------------+ diff --git a/Documentation/networking/devlink-info-versions.rst b/Documentation/networking/devlink-info-versions.rst deleted file mode 100644 index 4914f581b1fd..000000000000 --- a/Documentation/networking/devlink-info-versions.rst +++ /dev/null @@ -1,64 +0,0 @@ -.. SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) - -===================== -Devlink info versions -===================== - -board.id -======== - -Unique identifier of the board design. - -board.rev -========= - -Board design revision. - -asic.id -======= - -ASIC design identifier. - -asic.rev -======== - -ASIC design revision. - -board.manufacture -================= - -An identifier of the company or the facility which produced the part. - -fw -== - -Overall firmware version, often representing the collection of -fw.mgmt, fw.app, etc. - -fw.mgmt -======= - -Control unit firmware version. This firmware is responsible for house -keeping tasks, PHY control etc. but not the packet-by-packet data path -operation. - -fw.app -====== - -Data path microcode controlling high-speed packet processing. - -fw.undi -======= - -UNDI software, may include the UEFI driver, firmware or both. - -fw.ncsi -======= - -Version of the software responsible for supporting/handling the -Network Controller Sideband Interface. - -fw.psid -======= - -Unique identifier of the firmware parameter set. diff --git a/Documentation/networking/devlink-params-bnxt.txt b/Documentation/networking/devlink-params-bnxt.txt deleted file mode 100644 index 481aa303d5b4..000000000000 --- a/Documentation/networking/devlink-params-bnxt.txt +++ /dev/null @@ -1,18 +0,0 @@ -enable_sriov [DEVICE, GENERIC] - Configuration mode: Permanent - -ignore_ari [DEVICE, GENERIC] - Configuration mode: Permanent - -msix_vec_per_pf_max [DEVICE, GENERIC] - Configuration mode: Permanent - -msix_vec_per_pf_min [DEVICE, GENERIC] - Configuration mode: Permanent - -gre_ver_check [DEVICE, DRIVER-SPECIFIC] - Generic Routing Encapsulation (GRE) version check will - be enabled in the device. If disabled, device skips - version checking for incoming packets. - Type: Boolean - Configuration mode: Permanent diff --git a/Documentation/networking/devlink-params-mlx5.txt b/Documentation/networking/devlink-params-mlx5.txt deleted file mode 100644 index 5071467118bd..000000000000 --- a/Documentation/networking/devlink-params-mlx5.txt +++ /dev/null @@ -1,17 +0,0 @@ -flow_steering_mode [DEVICE, DRIVER-SPECIFIC] - Controls the flow steering mode of the driver. - Two modes are supported: - 1. 'dmfs' - Device managed flow steering. - 2. 'smfs - Software/Driver managed flow steering. - In DMFS mode, the HW steering entities are created and - managed through the Firmware. - In SMFS mode, the HW steering entities are created and - managed though by the driver directly into Hardware - without firmware intervention. - Type: String - Configuration mode: runtime - -enable_roce [DEVICE, GENERIC] - Enable handling of RoCE traffic in the device. - Defaultly enabled. - Configuration mode: driverinit diff --git a/Documentation/networking/devlink-params-mlxsw.txt b/Documentation/networking/devlink-params-mlxsw.txt deleted file mode 100644 index c63ea9fc7009..000000000000 --- a/Documentation/networking/devlink-params-mlxsw.txt +++ /dev/null @@ -1,10 +0,0 @@ -fw_load_policy [DEVICE, GENERIC] - Configuration mode: driverinit - -acl_region_rehash_interval [DEVICE, DRIVER-SPECIFIC] - Sets an interval for periodic ACL region rehashes. - The value is in milliseconds, minimal value is "3000". - Value "0" disables the periodic work. - The first rehash will be run right after value is set. - Type: u32 - Configuration mode: runtime diff --git a/Documentation/networking/devlink-params-mv88e6xxx.txt b/Documentation/networking/devlink-params-mv88e6xxx.txt deleted file mode 100644 index 21c4b3556ef2..000000000000 --- a/Documentation/networking/devlink-params-mv88e6xxx.txt +++ /dev/null @@ -1,7 +0,0 @@ -ATU_hash [DEVICE, DRIVER-SPECIFIC] - Select one of four possible hashing algorithms for - MAC addresses in the Address Translation Unit. - A value of 3 seems to work better than the default of - 1 when many MAC addresses have the same OUI. - Configuration mode: runtime - Type: u8. 0-3 valid. diff --git a/Documentation/networking/devlink-params-nfp.txt b/Documentation/networking/devlink-params-nfp.txt deleted file mode 100644 index 43e4d4034865..000000000000 --- a/Documentation/networking/devlink-params-nfp.txt +++ /dev/null @@ -1,5 +0,0 @@ -fw_load_policy [DEVICE, GENERIC] - Configuration mode: permanent - -reset_dev_on_drv_probe [DEVICE, GENERIC] - Configuration mode: permanent diff --git a/Documentation/networking/devlink-params-ti-cpsw-switch.txt b/Documentation/networking/devlink-params-ti-cpsw-switch.txt deleted file mode 100644 index 4037458499f7..000000000000 --- a/Documentation/networking/devlink-params-ti-cpsw-switch.txt +++ /dev/null @@ -1,10 +0,0 @@ -ale_bypass [DEVICE, DRIVER-SPECIFIC] - Allows to enable ALE_CONTROL(4).BYPASS mode for debug purposes. - All packets will be sent to the Host port only if enabled. - Type: bool - Configuration mode: runtime - -switch_mode [DEVICE, DRIVER-SPECIFIC] - Enable switch mode - Type: bool - Configuration mode: runtime diff --git a/Documentation/networking/devlink-params.txt b/Documentation/networking/devlink-params.txt deleted file mode 100644 index 04e234e9acc9..000000000000 --- a/Documentation/networking/devlink-params.txt +++ /dev/null @@ -1,71 +0,0 @@ -Devlink configuration parameters -================================ -Following is the list of configuration parameters via devlink interface. -Each parameter can be generic or driver specific and are device level -parameters. - -Note that the driver-specific files should contain the generic params -they support to, with supported config modes. - -Each parameter can be set in different configuration modes: - runtime - set while driver is running, no reset required. - driverinit - applied while driver initializes, requires restart - driver by devlink reload command. - permanent - written to device's non-volatile memory, hard reset - required. - -Following is the list of parameters: -==================================== -enable_sriov [DEVICE, GENERIC] - Enable Single Root I/O Virtualisation (SRIOV) in - the device. - Type: Boolean - -ignore_ari [DEVICE, GENERIC] - Ignore Alternative Routing-ID Interpretation (ARI) - capability. If enabled, adapter will ignore ARI - capability even when platforms has the support - enabled and creates same number of partitions when - platform does not support ARI. - Type: Boolean - -msix_vec_per_pf_max [DEVICE, GENERIC] - Provides the maximum number of MSIX interrupts that - a device can create. Value is same across all - physical functions (PFs) in the device. - Type: u32 - -msix_vec_per_pf_min [DEVICE, GENERIC] - Provides the minimum number of MSIX interrupts required - for the device initialization. Value is same across all - physical functions (PFs) in the device. - Type: u32 - -fw_load_policy [DEVICE, GENERIC] - Controls the device's firmware loading policy. - Valid values: - * DEVLINK_PARAM_FW_LOAD_POLICY_VALUE_DRIVER (0) - Load firmware version preferred by the driver. - * DEVLINK_PARAM_FW_LOAD_POLICY_VALUE_FLASH (1) - Load firmware currently stored in flash. - * DEVLINK_PARAM_FW_LOAD_POLICY_VALUE_DISK (2) - Load firmware currently available on host's disk. - Type: u8 - -reset_dev_on_drv_probe [DEVICE, GENERIC] - Controls the device's reset policy on driver probe. - Valid values: - * DEVLINK_PARAM_RESET_DEV_ON_DRV_PROBE_VALUE_UNKNOWN (0) - Unknown or invalid value. - * DEVLINK_PARAM_RESET_DEV_ON_DRV_PROBE_VALUE_ALWAYS (1) - Always reset device on driver probe. - * DEVLINK_PARAM_RESET_DEV_ON_DRV_PROBE_VALUE_NEVER (2) - Never reset device on driver probe. - * DEVLINK_PARAM_RESET_DEV_ON_DRV_PROBE_VALUE_DISK (3) - Reset only if device firmware can be found in the - filesystem. - Type: u8 - -enable_roce [DEVICE, GENERIC] - Enable handling of RoCE traffic in the device. - Type: Boolean diff --git a/Documentation/networking/devlink-trap-netdevsim.rst b/Documentation/networking/devlink-trap-netdevsim.rst deleted file mode 100644 index b721c9415473..000000000000 --- a/Documentation/networking/devlink-trap-netdevsim.rst +++ /dev/null @@ -1,20 +0,0 @@ -.. SPDX-License-Identifier: GPL-2.0 - -====================== -Devlink Trap netdevsim -====================== - -Driver-specific Traps -===================== - -.. list-table:: List of Driver-specific Traps Registered by ``netdevsim`` - :widths: 5 5 90 - - * - Name - - Type - - Description - * - ``fid_miss`` - - ``exception`` - - When a packet enters the device it is classified to a filtering - indentifier (FID) based on the ingress port and VLAN. This trap is used - to trap packets for which a FID could not be found diff --git a/Documentation/networking/devlink/bnxt.rst b/Documentation/networking/devlink/bnxt.rst new file mode 100644 index 000000000000..82ef9ec46707 --- /dev/null +++ b/Documentation/networking/devlink/bnxt.rst @@ -0,0 +1,74 @@ +.. SPDX-License-Identifier: GPL-2.0 + +==================== +bnxt devlink support +==================== + +This document describes the devlink features implemented by the ``bnxt`` +device driver. + +Parameters +========== + +.. list-table:: Generic parameters implemented + + * - Name + - Mode + * - ``enable_sriov`` + - Permanent + * - ``ignore_ari`` + - Permanent + * - ``msix_vec_per_pf_max`` + - Permanent + * - ``msix_vec_per_pf_min`` + - Permanent + +The ``bnxt`` driver also implements the following driver-specific +parameters. + +.. list-table:: Driver-specific parameters implemented + :widths: 5 5 5 85 + + * - Name + - Type + - Mode + - Description + * - ``gre_ver_check`` + - Boolean + - Permanent + - Generic Routing Encapsulation (GRE) version check will be enabled in + the device. If disabled, the device will skip the version check for + incoming packets. + +Info versions +============= + +The ``bnxt_en`` driver reports the following versions + +.. list-table:: devlink info versions implemented + :widths: 5 5 90 + + * - Name + - Type + - Description + * - ``asic.id`` + - fixed + - ASIC design identifier + * - ``asic.rev`` + - fixed + - ASIC design revision + * - ``fw.psid`` + - stored, running + - Firmware parameter set version of the board + * - ``fw`` + - stored, running + - Overall board firmware version + * - ``fw.app`` + - stored, running + - Data path firmware version + * - ``fw.mgmt`` + - stored, running + - Management firmware version + * - ``fw.roce`` + - stored, running + - RoCE management firmware version diff --git a/Documentation/networking/devlink/devlink-dpipe.rst b/Documentation/networking/devlink/devlink-dpipe.rst new file mode 100644 index 000000000000..468fe1001b74 --- /dev/null +++ b/Documentation/networking/devlink/devlink-dpipe.rst @@ -0,0 +1,252 @@ +.. SPDX-License-Identifier: GPL-2.0 + +============= +Devlink DPIPE +============= + +Background +========== + +While performing the hardware offloading process, much of the hardware +specifics cannot be presented. These details are useful for debugging, and +``devlink-dpipe`` provides a standardized way to provide visibility into the +offloading process. + +For example, the routing longest prefix match (LPM) algorithm used by the +Linux kernel may differ from the hardware implementation. The pipeline debug +API (DPIPE) is aimed at providing the user visibility into the ASIC's +pipeline in a generic way. + +The hardware offload process is expected to be done in a way that the user +should not be able to distinguish between the hardware vs. software +implementation. In this process, hardware specifics are neglected. In +reality those details can have lots of meaning and should be exposed in some +standard way. + +This problem is made even more complex when one wishes to offload the +control path of the whole networking stack to a switch ASIC. Due to +differences in the hardware and software models some processes cannot be +represented correctly. + +One example is the kernel's LPM algorithm which in many cases differs +greatly to the hardware implementation. The configuration API is the same, +but one cannot rely on the Forward Information Base (FIB) to look like the +Level Path Compression trie (LPC-trie) in hardware. + +In many situations trying to analyze systems failure solely based on the +kernel's dump may not be enough. By combining this data with complementary +information about the underlying hardware, this debugging can be made +easier; additionally, the information can be useful when debugging +performance issues. + +Overview +======== + +The ``devlink-dpipe`` interface closes this gap. The hardware's pipeline is +modeled as a graph of match/action tables. Each table represents a specific +hardware block. This model is not new, first being used by the P4 language. + +Traditionally it has been used as an alternative model for hardware +configuration, but the ``devlink-dpipe`` interface uses it for visibility +purposes as a standard complementary tool. The system's view from +``devlink-dpipe`` should change according to the changes done by the +standard configuration tools. + +For example, it’s quiet common to implement Access Control Lists (ACL) +using Ternary Content Addressable Memory (TCAM). The TCAM memory can be +divided into TCAM regions. Complex TC filters can have multiple rules with +different priorities and different lookup keys. On the other hand hardware +TCAM regions have a predefined lookup key. Offloading the TC filter rules +using TCAM engine can result in multiple TCAM regions being interconnected +in a chain (which may affect the data path latency). In response to a new TC +filter new tables should be created describing those regions. + +Model +===== + +The ``DPIPE`` model introduces several objects: + + * headers + * tables + * entries + +A ``header`` describes packet formats and provides names for fields within +the packet. A ``table`` describes hardware blocks. An ``entry`` describes +the actual content of a specific table. + +The hardware pipeline is not port specific, but rather describes the whole +ASIC. Thus it is tied to the top of the ``devlink`` infrastructure. + +Drivers can register and unregister tables at run time, in order to support +dynamic behavior. This dynamic behavior is mandatory for describing hardware +blocks like TCAM regions which can be allocated and freed dynamically. + +``devlink-dpipe`` generally is not intended for configuration. The exception +is hardware counting for a specific table. + +The following commands are used to obtain the ``dpipe`` objects from +userspace: + + * ``table_get``: Receive a table's description. + * ``headers_get``: Receive a device's supported headers. + * ``entries_get``: Receive a table's current entries. + * ``counters_set``: Enable or disable counters on a table. + +Table +----- + +The driver should implement the following operations for each table: + + * ``matches_dump``: Dump the supported matches. + * ``actions_dump``: Dump the supported actions. + * ``entries_dump``: Dump the actual content of the table. + * ``counters_set_update``: Synchronize hardware with counters enabled or + disabled. + +Header/Field +------------ + +In a similar way to P4 headers and fields are used to describe a table's +behavior. There is a slight difference between the standard protocol headers +and specific ASIC metadata. The protocol headers should be declared in the +``devlink`` core API. On the other hand ASIC meta data is driver specific +and should be defined in the driver. Additionally, each driver-specific +devlink documentation file should document the driver-specific ``dpipe`` +headers it implements. The headers and fields are identified by enumeration. + +In order to provide further visibility some ASIC metadata fields could be +mapped to kernel objects. For example, internal router interface indexes can +be directly mapped to the net device ifindex. FIB table indexes used by +different Virtual Routing and Forwarding (VRF) tables can be mapped to +internal routing table indexes. + +Match +----- + +Matches are kept primitive and close to hardware operation. Match types like +LPM are not supported due to the fact that this is exactly a process we wish +to describe in full detail. Example of matches: + + * ``field_exact``: Exact match on a specific field. + * ``field_exact_mask``: Exact match on a specific field after masking. + * ``field_range``: Match on a specific range. + +The id's of the header and the field should be specified in order to +identify the specific field. Furthermore, the header index should be +specified in order to distinguish multiple headers of the same type in a +packet (tunneling). + +Action +------ + +Similar to match, the actions are kept primitive and close to hardware +operation. For example: + + * ``field_modify``: Modify the field value. + * ``field_inc``: Increment the field value. + * ``push_header``: Add a header. + * ``pop_header``: Remove a header. + +Entry +----- + +Entries of a specific table can be dumped on demand. Each eentry is +identified with an index and its properties are described by a list of +match/action values and specific counter. By dumping the tables content the +interactions between tables can be resolved. + +Abstraction Example +=================== + +The following is an example of the abstraction model of the L3 part of +Mellanox Spectrum ASIC. The blocks are described in the order they appear in +the pipeline. The table sizes in the following examples are not real +hardware sizes and are provided for demonstration purposes. + +LPM +--- + +The LPM algorithm can be implemented as a list of hash tables. Each hash +table contains routes with the same prefix length. The root of the list is +/32, and in case of a miss the hardware will continue to the next hash +table. The depth of the search will affect the data path latency. + +In case of a hit the entry contains information about the next stage of the +pipeline which resolves the MAC address. The next stage can be either local +host table for directly connected routes, or adjacency table for next-hops. +The ``meta.lpm_prefix`` field is used to connect two LPM tables. + +.. code:: + + table lpm_prefix_16 { + size: 4096, + counters_enabled: true, + match: { meta.vr_id: exact, + ipv4.dst_addr: exact_mask, + ipv6.dst_addr: exact_mask, + meta.lpm_prefix: exact }, + action: { meta.adj_index: set, + meta.adj_group_size: set, + meta.rif_port: set, + meta.lpm_prefix: set }, + } + +Local Host +---------- + +In the case of local routes the LPM lookup already resolves the egress +router interface (RIF), yet the exact MAC address is not known. The local +host table is a hash table combining the output interface id with +destination IP address as a key. The result is the MAC address. + +.. code:: + + table local_host { + size: 4096, + counters_enabled: true, + match: { meta.rif_port: exact, + ipv4.dst_addr: exact}, + action: { ethernet.daddr: set } + } + +Adjacency +--------- + +In case of remote routes this table does the ECMP. The LPM lookup results in +ECMP group size and index that serves as a global offset into this table. +Concurrently a hash of the packet is generated. Based on the ECMP group size +and the packet's hash a local offset is generated. Multiple LPM entries can +point to the same adjacency group. + +.. code:: + + table adjacency { + size: 4096, + counters_enabled: true, + match: { meta.adj_index: exact, + meta.adj_group_size: exact, + meta.packet_hash_index: exact }, + action: { ethernet.daddr: set, + meta.erif: set } + } + +ERIF +---- + +In case the egress RIF and destination MAC have been resolved by previous +tables this table does multiple operations like TTL decrease and MTU check. +Then the decision of forward/drop is taken and the port L3 statistics are +updated based on the packet's type (broadcast, unicast, multicast). + +.. code:: + + table erif { + size: 800, + counters_enabled: true, + match: { meta.rif_port: exact, + meta.is_l3_unicast: exact, + meta.is_l3_broadcast: exact, + meta.is_l3_multicast, exact }, + action: { meta.l3_drop: set, + meta.l3_forward: set } + } diff --git a/Documentation/networking/devlink/devlink-health.rst b/Documentation/networking/devlink/devlink-health.rst new file mode 100644 index 000000000000..0c99b11f05f9 --- /dev/null +++ b/Documentation/networking/devlink/devlink-health.rst @@ -0,0 +1,114 @@ +.. SPDX-License-Identifier: GPL-2.0 + +============== +Devlink Health +============== + +Background +========== + +The ``devlink`` health mechanism is targeted for Real Time Alerting, in +order to know when something bad happened to a PCI device. + + * Provide alert debug information. + * Self healing. + * If problem needs vendor support, provide a way to gather all needed + debugging information. + +Overview +======== + +The main idea is to unify and centralize driver health reports in the +generic ``devlink`` instance and allow the user to set different +attributes of the health reporting and recovery procedures. + +The ``devlink`` health reporter: +Device driver creates a "health reporter" per each error/health type. +Error/Health type can be a known/generic (eg pci error, fw error, rx/tx error) +or unknown (driver specific). +For each registered health reporter a driver can issue error/health reports +asynchronously. All health reports handling is done by ``devlink``. +Device driver can provide specific callbacks for each "health reporter", e.g.: + + * Recovery procedures + * Diagnostics procedures + * Object dump procedures + * OOB initial parameters + +Different parts of the driver can register different types of health reporters +with different handlers. + +Actions +======= + +Once an error is reported, devlink health will perform the following actions: + + * A log is being send to the kernel trace events buffer + * Health status and statistics are being updated for the reporter instance + * Object dump is being taken and saved at the reporter instance (as long as + there is no other dump which is already stored) + * Auto recovery attempt is being done. Depends on: + - Auto-recovery configuration + - Grace period vs. time passed since last recover + +User Interface +============== + +User can access/change each reporter's parameters and driver specific callbacks +via ``devlink``, e.g per error type (per health reporter): + + * Configure reporter's generic parameters (like: disable/enable auto recovery) + * Invoke recovery procedure + * Run diagnostics + * Object dump + +.. list-table:: List of devlink health interfaces + :widths: 10 90 + + * - Name + - Description + * - ``DEVLINK_CMD_HEALTH_REPORTER_GET`` + - Retrieves status and configuration info per DEV and reporter. + * - ``DEVLINK_CMD_HEALTH_REPORTER_SET`` + - Allows reporter-related configuration setting. + * - ``DEVLINK_CMD_HEALTH_REPORTER_RECOVER`` + - Triggers a reporter's recovery procedure. + * - ``DEVLINK_CMD_HEALTH_REPORTER_DIAGNOSE`` + - Retrieves diagnostics data from a reporter on a device. + * - ``DEVLINK_CMD_HEALTH_REPORTER_DUMP_GET`` + - Retrieves the last stored dump. Devlink health + saves a single dump. If an dump is not already stored by the devlink + for this reporter, devlink generates a new dump. + dump output is defined by the reporter. + * - ``DEVLINK_CMD_HEALTH_REPORTER_DUMP_CLEAR`` + - Clears the last saved dump file for the specified reporter. + +The following diagram provides a general overview of ``devlink-health``:: + + netlink + +--------------------------+ + | | + | + | + | | | + +--------------------------+ + |request for ops + |(diagnose, + mlx5_core devlink |recover, + |dump) + +--------+ +--------------------------+ + | | | reporter| | + | | | +---------v----------+ | + | | ops execution | | | | + | <----------------------------------+ | | + | | | | | | + | | | + ^------------------+ | + | | | | request for ops | + | | | | (recover, dump) | + | | | | | + | | | +-+------------------+ | + | | health report | | health handler | | + | +-------------------------------> | | + | | | +--------------------+ | + | | health reporter create | | + | +----------------------------> | + +--------+ +--------------------------+ diff --git a/Documentation/networking/devlink/devlink-info.rst b/Documentation/networking/devlink/devlink-info.rst new file mode 100644 index 000000000000..70981dd1b981 --- /dev/null +++ b/Documentation/networking/devlink/devlink-info.rst @@ -0,0 +1,100 @@ +.. SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) + +============ +Devlink Info +============ + +The ``devlink-info`` mechanism enables device drivers to report device +information in a generic fashion. It is extensible, and enables exporting +even device or driver specific information. + +devlink supports representing the following types of versions + +.. list-table:: List of version types + :widths: 5 95 + + * - Type + - Description + * - ``fixed`` + - Represents fixed versions, which cannot change. For example, + component identifiers or the board version reported in the PCI VPD. + * - ``running`` + - Represents the version of the currently running component. For + example the running version of firmware. These versions generally + only update after a reboot. + * - ``stored`` + - Represents the version of a component as stored, such as after a + flash update. Stored values should update to reflect changes in the + flash even if a reboot has not yet occurred. + +Generic Versions +================ + +It is expected that drivers use the following generic names for exporting +version information. Other information may be exposed using driver-specific +names, but these should be documented in the driver-specific file. + +board.id +-------- + +Unique identifier of the board design. + +board.rev +--------- + +Board design revision. + +asic.id +------- + +ASIC design identifier. + +asic.rev +-------- + +ASIC design revision. + +board.manufacture +----------------- + +An identifier of the company or the facility which produced the part. + +fw +-- + +Overall firmware version, often representing the collection of +fw.mgmt, fw.app, etc. + +fw.mgmt +------- + +Control unit firmware version. This firmware is responsible for house +keeping tasks, PHY control etc. but not the packet-by-packet data path +operation. + +fw.app +------ + +Data path microcode controlling high-speed packet processing. + +fw.undi +------- + +UNDI software, may include the UEFI driver, firmware or both. + +fw.ncsi +------- + +Version of the software responsible for supporting/handling the +Network Controller Sideband Interface. + +fw.psid +------- + +Unique identifier of the firmware parameter set. + +fw.roce +------- + +RoCE firmware version which is responsible for handling roce +management. diff --git a/Documentation/networking/devlink/devlink-params.rst b/Documentation/networking/devlink/devlink-params.rst new file mode 100644 index 000000000000..da2f85c0fa21 --- /dev/null +++ b/Documentation/networking/devlink/devlink-params.rst @@ -0,0 +1,108 @@ +.. SPDX-License-Identifier: GPL-2.0 + +============== +Devlink Params +============== + +``devlink`` provides capability for a driver to expose device parameters for low +level device functionality. Since devlink can operate at the device-wide +level, it can be used to provide configuration that may affect multiple +ports on a single device. + +This document describes a number of generic parameters that are supported +across multiple drivers. Each driver is also free to add their own +parameters. Each driver must document the specific parameters they support, +whether generic or not. + +Configuration modes +=================== + +Parameters may be set in different configuration modes. + +.. list-table:: Possible configuration modes + :widths: 5 90 + + * - Name + - Description + * - ``runtime`` + - set while the driver is running, and takes effect immediately. No + reset is required. + * - ``driverinit`` + - applied while the driver initializes. Requires the user to restart + the driver using the ``devlink`` reload command. + * - ``permanent`` + - written to the device's non-volatile memory. A hard reset is required + for it to take effect. + +Reloading +--------- + +In order for ``driverinit`` parameters to take effect, the driver must +support reloading via the ``devlink-reload`` command. This command will +request a reload of the device driver. + +Generic configuration parameters +================================ +The following is a list of generic configuration parameters that drivers may +add. Use of generic parameters is preferred over each driver creating their +own name. + +.. list-table:: List of generic parameters + :widths: 5 5 90 + + * - Name + - Type + - Description + * - ``enable_sriov`` + - Boolean + - Enable Single Root I/O Virtualization (SRIOV) in the device. + * - ``ignore_ari`` + - Boolean + - Ignore Alternative Routing-ID Interpretation (ARI) capability. If + enabled, the adapter will ignore ARI capability even when the + platform has support enabled. The device will create the same number + of partitions as when the platform does not support ARI. + * - ``msix_vec_per_pf_max`` + - u32 + - Provides the maximum number of MSI-X interrupts that a device can + create. Value is the same across all physical functions (PFs) in the + device. + * - ``msix_vec_per_pf_min`` + - u32 + - Provides the minimum number of MSI-X interrupts required for the + device to initialize. Value is the same across all physical functions + (PFs) in the device. + * - ``fw_load_policy`` + - u8 + - Control the device's firmware loading policy. + - ``DEVLINK_PARAM_FW_LOAD_POLICY_VALUE_DRIVER`` (0) + Load firmware version preferred by the driver. + - ``DEVLINK_PARAM_FW_LOAD_POLICY_VALUE_FLASH`` (1) + Load firmware currently stored in flash. + - ``DEVLINK_PARAM_FW_LOAD_POLICY_VALUE_DISK`` (2) + Load firmware currently available on host's disk. + * - ``reset_dev_on_drv_probe`` + - u8 + - Controls the device's reset policy on driver probe. + - ``DEVLINK_PARAM_RESET_DEV_ON_DRV_PROBE_VALUE_UNKNOWN`` (0) + Unknown or invalid value. + - ``DEVLINK_PARAM_RESET_DEV_ON_DRV_PROBE_VALUE_ALWAYS`` (1) + Always reset device on driver probe. + - ``DEVLINK_PARAM_RESET_DEV_ON_DRV_PROBE_VALUE_NEVER`` (2) + Never reset device on driver probe. + - ``DEVLINK_PARAM_RESET_DEV_ON_DRV_PROBE_VALUE_DISK`` (3) + Reset the device only if firmware can be found in the filesystem. + * - ``enable_roce`` + - Boolean + - Enable handling of RoCE traffic in the device. + * - ``internal_err_reset`` + - Boolean + - When enabled, the device driver will reset the device on internal + errors. + * - ``max_macs`` + - u32 + - Specifies the maximum number of MAC addresses per ethernet port of + this device. + * - ``region_snapshot_enable`` + - Boolean + - Enable capture of ``devlink-region`` snapshots. diff --git a/Documentation/networking/devlink/devlink-region.rst b/Documentation/networking/devlink/devlink-region.rst new file mode 100644 index 000000000000..1a7683e7acb2 --- /dev/null +++ b/Documentation/networking/devlink/devlink-region.rst @@ -0,0 +1,60 @@ +.. SPDX-License-Identifier: GPL-2.0 + +============== +Devlink Region +============== + +``devlink`` regions enable access to driver defined address regions using +devlink. + +Each device can create and register its own supported address regions. The +region can then be accessed via the devlink region interface. + +Region snapshots are collected by the driver, and can be accessed via read +or dump commands. This allows future analysis on the created snapshots. +Regions may optionally support triggering snapshots on demand. + +The major benefit to creating a region is to provide access to internal +address regions that are otherwise inaccessible to the user. + +Regions may also be used to provide an additional way to debug complex error +states, but see also :doc:`devlink-health` + +example usage +------------- + +.. code:: shell + + $ devlink region help + $ devlink region show [ DEV/REGION ] + $ devlink region del DEV/REGION snapshot SNAPSHOT_ID + $ devlink region dump DEV/REGION [ snapshot SNAPSHOT_ID ] + $ devlink region read DEV/REGION [ snapshot SNAPSHOT_ID ] + address ADDRESS length length + + # Show all of the exposed regions with region sizes: + $ devlink region show + pci/0000:00:05.0/cr-space: size 1048576 snapshot [1 2] + pci/0000:00:05.0/fw-health: size 64 snapshot [1 2] + + # Delete a snapshot using: + $ devlink region del pci/0000:00:05.0/cr-space snapshot 1 + + # Trigger (request) a snapshot be taken: + $ devlink region trigger pci/0000:00:05.0/cr-space + + # Dump a snapshot: + $ devlink region dump pci/0000:00:05.0/fw-health snapshot 1 + 0000000000000000 0014 95dc 0014 9514 0035 1670 0034 db30 + 0000000000000010 0000 0000 ffff ff04 0029 8c00 0028 8cc8 + 0000000000000020 0016 0bb8 0016 1720 0000 0000 c00f 3ffc + 0000000000000030 bada cce5 bada cce5 bada cce5 bada cce5 + + # Read a specific part of a snapshot: + $ devlink region read pci/0000:00:05.0/fw-health snapshot 1 address 0 + length 16 + 0000000000000000 0014 95dc 0014 9514 0035 1670 0034 db30 + +As regions are likely very device or driver specific, no generic regions are +defined. See the driver-specific documentation files for information on the +specific regions a driver supports. diff --git a/Documentation/networking/devlink/devlink-resource.rst b/Documentation/networking/devlink/devlink-resource.rst new file mode 100644 index 000000000000..93e92d2f0752 --- /dev/null +++ b/Documentation/networking/devlink/devlink-resource.rst @@ -0,0 +1,62 @@ +.. SPDX-License-Identifier: GPL-2.0 + +================ +Devlink Resource +================ + +``devlink`` provides the ability for drivers to register resources, which +can allow administrators to see the device restrictions for a given +resource, as well as how much of the given resource is currently +in use. Additionally, these resources can optionally have configurable size. +This could enable the administrator to limit the number of resources that +are used. + +For example, the ``netdevsim`` driver enables ``/IPv4/fib`` and +``/IPv4/fib-rules`` as resources to limit the number of IPv4 FIB entries and +rules for a given device. + +Resource Ids +============ + +Each resource is represented by an id, and contains information about its +current size and related sub resources. To access a sub resource, you +specify the path of the resource. For example ``/IPv4/fib`` is the id for +the ``fib`` sub-resource under the ``IPv4`` resource. + +example usage +------------- + +The resources exposed by the driver can be observed, for example: + +.. code:: shell + + $devlink resource show pci/0000:03:00.0 + pci/0000:03:00.0: + name kvd size 245760 unit entry + resources: + name linear size 98304 occ 0 unit entry size_min 0 size_max 147456 size_gran 128 + name hash_double size 60416 unit entry size_min 32768 size_max 180224 size_gran 128 + name hash_single size 87040 unit entry size_min 65536 size_max 212992 size_gran 128 + +Some resource's size can be changed. Examples: + +.. code:: shell + + $devlink resource set pci/0000:03:00.0 path /kvd/hash_single size 73088 + $devlink resource set pci/0000:03:00.0 path /kvd/hash_double size 74368 + +The changes do not apply immediately, this can be validated by the 'size_new' +attribute, which represents the pending change in size. For example: + +.. code:: shell + + $devlink resource show pci/0000:03:00.0 + pci/0000:03:00.0: + name kvd size 245760 unit entry size_valid false + resources: + name linear size 98304 size_new 147456 occ 0 unit entry size_min 0 size_max 147456 size_gran 128 + name hash_double size 60416 unit entry size_min 32768 size_max 180224 size_gran 128 + name hash_single size 87040 unit entry size_min 65536 size_max 212992 size_gran 128 + +Note that changes in resource size may require a device reload to properly +take effect. diff --git a/Documentation/networking/devlink-trap.rst b/Documentation/networking/devlink/devlink-trap.rst index 03311849bfb1..47a429bb8658 100644 --- a/Documentation/networking/devlink-trap.rst +++ b/Documentation/networking/devlink/devlink-trap.rst @@ -223,6 +223,21 @@ be added to the following table: * - ``ipv6_lpm_miss`` - ``exception`` - Traps unicast IPv6 packets that did not match any route + * - ``non_routable_packet`` + - ``drop`` + - Traps packets that the device decided to drop because they are not + supposed to be routed. For example, IGMP queries can be flooded by the + device in layer 2 and reach the router. Such packets should not be + routed and instead dropped + * - ``decap_error`` + - ``exception`` + - Traps NVE and IPinIP packets that the device decided to drop because of + failure during decapsulation (e.g., packet being too short, reserved + bits set in VXLAN header) + * - ``overlay_smac_is_mc`` + - ``drop`` + - Traps NVE packets that the device decided to drop because their overlay + source MAC is multicast Driver-specific Packet Traps ============================ @@ -233,7 +248,8 @@ help debug packet drops caused by these exceptions. The following list includes links to the description of driver-specific traps registered by various device drivers: - * :doc:`devlink-trap-netdevsim` + * :doc:`netdevsim` + * :doc:`mlxsw` Generic Packet Trap Groups ========================== @@ -258,6 +274,9 @@ narrow. The description of these groups must be added to the following table: * - ``buffer_drops`` - Contains packet traps for packets that were dropped by the device due to an enqueue decision + * - ``tunnel_drops`` + - Contains packet traps for packets that were dropped by the device during + tunnel encapsulation / decapsulation Testing ======= diff --git a/Documentation/networking/devlink/index.rst b/Documentation/networking/devlink/index.rst new file mode 100644 index 000000000000..087ff54d53fc --- /dev/null +++ b/Documentation/networking/devlink/index.rst @@ -0,0 +1,42 @@ +Linux Devlink Documentation +=========================== + +devlink is an API to expose device information and resources not directly +related to any device class, such as chip-wide/switch-ASIC-wide configuration. + +Interface documentation +----------------------- + +The following pages describe various interfaces available through devlink in +general. + +.. toctree:: + :maxdepth: 1 + + devlink-dpipe + devlink-health + devlink-info + devlink-params + devlink-region + devlink-resource + devlink-trap + +Driver-specific documentation +----------------------------- + +Each driver that implements ``devlink`` is expected to document what +parameters, info versions, and other features it supports. + +.. toctree:: + :maxdepth: 1 + + bnxt + ionic + mlx4 + mlx5 + mlxsw + mv88e6xxx + netdevsim + nfp + qed + ti-cpsw-switch diff --git a/Documentation/networking/devlink/ionic.rst b/Documentation/networking/devlink/ionic.rst new file mode 100644 index 000000000000..48da9c92d584 --- /dev/null +++ b/Documentation/networking/devlink/ionic.rst @@ -0,0 +1,29 @@ +.. SPDX-License-Identifier: GPL-2.0 + +===================== +ionic devlink support +===================== + +This document describes the devlink features implemented by the ``ionic`` +device driver. + +Info versions +============= + +The ``ionic`` driver reports the following versions + +.. list-table:: devlink info versions implemented + :widths: 5 5 90 + + * - Name + - Type + - Description + * - ``fw`` + - running + - Version of firmware running on the device + * - ``asic.id`` + - fixed + - The ASIC type for this device + * - ``asic.rev`` + - fixed + - The revision of the ASIC for this device diff --git a/Documentation/networking/devlink/mlx4.rst b/Documentation/networking/devlink/mlx4.rst new file mode 100644 index 000000000000..7b2d17ea5471 --- /dev/null +++ b/Documentation/networking/devlink/mlx4.rst @@ -0,0 +1,56 @@ +.. SPDX-License-Identifier: GPL-2.0 + +==================== +mlx4 devlink support +==================== + +This document describes the devlink features implemented by the ``mlx4`` +device driver. + +Parameters +========== + +.. list-table:: Generic parameters implemented + + * - Name + - Mode + * - ``internal_err_reset`` + - driverinit, runtime + * - ``max_macs`` + - driverinit + * - ``region_snapshot_enable`` + - driverinit, runtime + +The ``mlx4`` driver also implements the following driver-specific +parameters. + +.. list-table:: Driver-specific parameters implemented + :widths: 5 5 5 85 + + * - Name + - Type + - Mode + - Description + * - ``enable_64b_cqe_eqe`` + - Boolean + - driverinit + - Enable 64 byte CQEs/EQEs, if the FW supports it. + * - ``enable_4k_uar`` + - Boolean + - driverinit + - Enable using the 4k UAR. + +The ``mlx4`` driver supports reloading via ``DEVLINK_CMD_RELOAD`` + +Regions +======= + +The ``mlx4`` driver supports dumping the firmware PCI crspace and health +buffer during a critical firmware issue. + +In case a firmware command times out, firmware getting stuck, or a non zero +value on the catastrophic buffer, a snapshot will be taken by the driver. + +The ``cr-space`` region will contain the firmware PCI crspace contents. The +``fw-health`` region will contain the device firmware's health buffer. +Snapshots for both of these regions are taken on the same event triggers. diff --git a/Documentation/networking/devlink/mlx5.rst b/Documentation/networking/devlink/mlx5.rst new file mode 100644 index 000000000000..629a6e69c036 --- /dev/null +++ b/Documentation/networking/devlink/mlx5.rst @@ -0,0 +1,59 @@ +.. SPDX-License-Identifier: GPL-2.0 + +==================== +mlx5 devlink support +==================== + +This document describes the devlink features implemented by the ``mlx5`` +device driver. + +Parameters +========== + +.. list-table:: Generic parameters implemented + + * - Name + - Mode + * - ``enable_roce`` + - driverinit + +The ``mlx5`` driver also implements the following driver-specific +parameters. + +.. list-table:: Driver-specific parameters implemented + :widths: 5 5 5 85 + + * - Name + - Type + - Mode + - Description + * - ``flow_steering_mode`` + - string + - runtime + - Controls the flow steering mode of the driver + + * ``dmfs`` Device managed flow steering. In DMFS mode, the HW + steering entities are created and managed through firmware. + * ``smfs`` Software managed flow steering. In SMFS mode, the HW + steering entities are created and manage through the driver without + firmware intervention. + +The ``mlx5`` driver supports reloading via ``DEVLINK_CMD_RELOAD`` + +Info versions +============= + +The ``mlx5`` driver reports the following versions + +.. list-table:: devlink info versions implemented + :widths: 5 5 90 + + * - Name + - Type + - Description + * - ``fw.psid`` + - fixed + - Used to represent the board id of the device. + * - ``fw.version`` + - stored, running + - Three digit major.minor.subminor firmware version number. diff --git a/Documentation/networking/devlink/mlxsw.rst b/Documentation/networking/devlink/mlxsw.rst new file mode 100644 index 000000000000..cf857cb4ba8f --- /dev/null +++ b/Documentation/networking/devlink/mlxsw.rst @@ -0,0 +1,81 @@ +.. SPDX-License-Identifier: GPL-2.0 + +===================== +mlxsw devlink support +===================== + +This document describes the devlink features implemented by the ``mlxsw`` +device driver. + +Parameters +========== + +.. list-table:: Generic parameters implemented + + * - Name + - Mode + * - ``fw_load_policy`` + - driverinit + +The ``mlxsw`` driver also implements the following driver-specific +parameters. + +.. list-table:: Driver-specific parameters implemented + :widths: 5 5 5 85 + + * - Name + - Type + - Mode + - Description + * - ``acl_region_rehash_interval`` + - u32 + - runtime + - Sets an interval for periodic ACL region rehashes. The value is + specified in milliseconds, with a minimum of ``3000``. The value of + ``0`` disables periodic work entirely. The first rehash will be run + immediately after the value is set. + +The ``mlxsw`` driver supports reloading via ``DEVLINK_CMD_RELOAD`` + +Info versions +============= + +The ``mlxsw`` driver reports the following versions + +.. list-table:: devlink info versions implemented + :widths: 5 5 90 + + * - Name + - Type + - Description + * - ``hw.revision`` + - fixed + - The hardware revision for this board + * - ``fw.psid`` + - fixed + - Firmware PSID + * - ``fw.version`` + - running + - Three digit firmware version + +Driver-specific Traps +===================== + +.. list-table:: List of Driver-specific Traps Registered by ``mlxsw`` + :widths: 5 5 90 + + * - Name + - Type + - Description + * - ``irif_disabled`` + - ``drop`` + - Traps packets that the device decided to drop because they need to be + routed from a disabled router interface (RIF). This can happen during + RIF dismantle, when the RIF is first disabled before being removed + completely + * - ``erif_disabled`` + - ``drop`` + - Traps packets that the device decided to drop because they need to be + routed through a disabled router interface (RIF). This can happen during + RIF dismantle, when the RIF is first disabled before being removed + completely diff --git a/Documentation/networking/devlink/mv88e6xxx.rst b/Documentation/networking/devlink/mv88e6xxx.rst new file mode 100644 index 000000000000..c621212a47a1 --- /dev/null +++ b/Documentation/networking/devlink/mv88e6xxx.rst @@ -0,0 +1,28 @@ +.. SPDX-License-Identifier: GPL-2.0 + +========================= +mv88e6xxx devlink support +========================= + +This document describes the devlink features implemented by the ``mv88e6xxx`` +device driver. + +Parameters +========== + +The ``mv88e6xxx`` driver implements the following driver-specific parameters. + +.. list-table:: Driver-specific parameters implemented + :widths: 5 5 5 85 + + * - Name + - Type + - Mode + - Description + * - ``ATU_hash`` + - u8 + - runtime + - Select one of four possible hashing algorithms for MAC addresses in + the Address Translation Unit. A value of 3 may work better than the + default of 1 when many MAC addresses have the same OUI. Only the + values 0 to 3 are valid for this parameter. diff --git a/Documentation/networking/devlink/netdevsim.rst b/Documentation/networking/devlink/netdevsim.rst new file mode 100644 index 000000000000..2a266b7e7b38 --- /dev/null +++ b/Documentation/networking/devlink/netdevsim.rst @@ -0,0 +1,72 @@ +.. SPDX-License-Identifier: GPL-2.0 + +========================= +netdevsim devlink support +========================= + +This document describes the ``devlink`` features supported by the +``netdevsim`` device driver. + +Parameters +========== + +.. list-table:: Generic parameters implemented + + * - Name + - Mode + * - ``max_macs`` + - driverinit + +The ``netdevsim`` driver also implements the following driver-specific +parameters. + +.. list-table:: Driver-specific parameters implemented + :widths: 5 5 5 85 + + * - Name + - Type + - Mode + - Description + * - ``test1`` + - Boolean + - driverinit + - Test parameter used to show how a driver-specific devlink parameter + can be implemented. + +The ``netdevsim`` driver supports reloading via ``DEVLINK_CMD_RELOAD`` + +Regions +======= + +The ``netdevsim`` driver exposes a ``dummy`` region as an example of how the +devlink-region interfaces work. A snapshot is taken whenever the +``take_snapshot`` debugfs file is written to. + +Resources +========= + +The ``netdevsim`` driver exposes resources to control the number of FIB +entries and FIB rule entries that the driver will allow. + +.. code:: shell + + $ devlink resource set netdevsim/netdevsim0 path /IPv4/fib size 96 + $ devlink resource set netdevsim/netdevsim0 path /IPv4/fib-rules size 16 + $ devlink resource set netdevsim/netdevsim0 path /IPv6/fib size 64 + $ devlink resource set netdevsim/netdevsim0 path /IPv6/fib-rules size 16 + $ devlink dev reload netdevsim/netdevsim0 + +Driver-specific Traps +===================== + +.. list-table:: List of Driver-specific Traps Registered by ``netdevsim`` + :widths: 5 5 90 + + * - Name + - Type + - Description + * - ``fid_miss`` + - ``exception`` + - When a packet enters the device it is classified to a filtering + indentifier (FID) based on the ingress port and VLAN. This trap is used + to trap packets for which a FID could not be found diff --git a/Documentation/networking/devlink/nfp.rst b/Documentation/networking/devlink/nfp.rst new file mode 100644 index 000000000000..a1717db0dfcc --- /dev/null +++ b/Documentation/networking/devlink/nfp.rst @@ -0,0 +1,65 @@ +.. SPDX-License-Identifier: GPL-2.0 + +=================== +nfp devlink support +=================== + +This document describes the devlink features implemented by the ``nfp`` +device driver. + +Parameters +========== + +.. list-table:: Generic parameters implemented + + * - Name + - Mode + * - ``fw_load_policy`` + - permanent + * - ``reset_dev_on_drv_probe`` + - permanent + +Info versions +============= + +The ``nfp`` driver reports the following versions + +.. list-table:: devlink info versions implemented + :widths: 5 5 90 + + * - Name + - Type + - Description + * - ``board.id`` + - fixed + - Part number identifying the board design + * - ``board.rev`` + - fixed + - Revision of the board design + * - ``board.manufacture`` + - fixed + - Vendor of the board design + * - ``board.model`` + - fixed + - Model name of the board design + * - ``fw.bundle_id`` + - stored, running + - Firmware bundle id + * - ``fw.mgmt`` + - stored, running + - Version of the management firmware + * - ``fw.cpld`` + - stored, running + - The CPLD firmware component version + * - ``fw.app`` + - stored, running + - The APP firmware component version + * - ``fw.undi`` + - stored, running + - The UNDI firmware component version + * - ``fw.ncsi`` + - stored, running + - The NSCI firmware component version + * - ``chip.init`` + - stored, running + - The CFGR firmware component version diff --git a/Documentation/networking/devlink/qed.rst b/Documentation/networking/devlink/qed.rst new file mode 100644 index 000000000000..805c6f63621a --- /dev/null +++ b/Documentation/networking/devlink/qed.rst @@ -0,0 +1,26 @@ +.. SPDX-License-Identifier: GPL-2.0 + +=================== +qed devlink support +=================== + +This document describes the devlink features implemented by the ``qed`` core +device driver. + +Parameters +========== + +The ``qed`` driver implements the following driver-specific parameters. + +.. list-table:: Driver-specific parameters implemented + :widths: 5 5 5 85 + + * - Name + - Type + - Mode + - Description + * - ``iwarp_cmt`` + - Boolean + - runtime + - Enable iWARP functionality for 100g devices. Note that this impacts + L2 performance, and is therefore not enabled by default. diff --git a/Documentation/networking/devlink/ti-cpsw-switch.rst b/Documentation/networking/devlink/ti-cpsw-switch.rst new file mode 100644 index 000000000000..dc399e32abaa --- /dev/null +++ b/Documentation/networking/devlink/ti-cpsw-switch.rst @@ -0,0 +1,31 @@ +.. SPDX-License-Identifier: GPL-2.0 + +============================== +ti-cpsw-switch devlink support +============================== + +This document describes the devlink features implemented by the ``ti-cpsw-switch`` +device driver. + +Parameters +========== + +The ``ti-cpsw-switch`` driver implements the following driver-specific +parameters. + +.. list-table:: Driver-specific parameters implemented + :widths: 5 5 5 85 + + * - Name + - Type + - Mode + - Description + * - ``ale_bypass`` + - Boolean + - runtime + - Enables ALE_CONTROL(4).BYPASS mode for debugging purposes. In this + mode, all packets will be sent to the host port only. + * - ``switch_mode`` + - Boolean + - runtime + - Enable switch mode diff --git a/Documentation/networking/ethtool-netlink.rst b/Documentation/networking/ethtool-netlink.rst new file mode 100644 index 000000000000..f1f868479ceb --- /dev/null +++ b/Documentation/networking/ethtool-netlink.rst @@ -0,0 +1,618 @@ +============================= +Netlink interface for ethtool +============================= + + +Basic information +================= + +Netlink interface for ethtool uses generic netlink family ``ethtool`` +(userspace application should use macros ``ETHTOOL_GENL_NAME`` and +``ETHTOOL_GENL_VERSION`` defined in ``<linux/ethtool_netlink.h>`` uapi +header). This family does not use a specific header, all information in +requests and replies is passed using netlink attributes. + +The ethtool netlink interface uses extended ACK for error and warning +reporting, userspace application developers are encouraged to make these +messages available to user in a suitable way. + +Requests can be divided into three categories: "get" (retrieving information), +"set" (setting parameters) and "action" (invoking an action). + +All "set" and "action" type requests require admin privileges +(``CAP_NET_ADMIN`` in the namespace). Most "get" type requests are allowed for +anyone but there are exceptions (where the response contains sensitive +information). In some cases, the request as such is allowed for anyone but +unprivileged users have attributes with sensitive information (e.g. +wake-on-lan password) omitted. + + +Conventions +=========== + +Attributes which represent a boolean value usually use NLA_U8 type so that we +can distinguish three states: "on", "off" and "not present" (meaning the +information is not available in "get" requests or value is not to be changed +in "set" requests). For these attributes, the "true" value should be passed as +number 1 but any non-zero value should be understood as "true" by recipient. +In the tables below, "bool" denotes NLA_U8 attributes interpreted in this way. + +In the message structure descriptions below, if an attribute name is suffixed +with "+", parent nest can contain multiple attributes of the same type. This +implements an array of entries. + + +Request header +============== + +Each request or reply message contains a nested attribute with common header. +Structure of this header is + + ============================== ====== ============================= + ``ETHTOOL_A_HEADER_DEV_INDEX`` u32 device ifindex + ``ETHTOOL_A_HEADER_DEV_NAME`` string device name + ``ETHTOOL_A_HEADER_FLAGS`` u32 flags common for all requests + ============================== ====== ============================= + +``ETHTOOL_A_HEADER_DEV_INDEX`` and ``ETHTOOL_A_HEADER_DEV_NAME`` identify the +device message relates to. One of them is sufficient in requests, if both are +used, they must identify the same device. Some requests, e.g. global string +sets, do not require device identification. Most ``GET`` requests also allow +dump requests without device identification to query the same information for +all devices providing it (each device in a separate message). + +``ETHTOOL_A_HEADER_FLAGS`` is a bitmap of request flags common for all request +types. The interpretation of these flags is the same for all request types but +the flags may not apply to requests. Recognized flags are: + + ================================= =================================== + ``ETHTOOL_FLAG_COMPACT_BITSETS`` use compact format bitsets in reply + ``ETHTOOL_FLAG_OMIT_REPLY`` omit optional reply (_SET and _ACT) + ================================= =================================== + +New request flags should follow the general idea that if the flag is not set, +the behaviour is backward compatible, i.e. requests from old clients not aware +of the flag should be interpreted the way the client expects. A client must +not set flags it does not understand. + + +Bit sets +======== + +For short bitmaps of (reasonably) fixed length, standard ``NLA_BITFIELD32`` +type is used. For arbitrary length bitmaps, ethtool netlink uses a nested +attribute with contents of one of two forms: compact (two binary bitmaps +representing bit values and mask of affected bits) and bit-by-bit (list of +bits identified by either index or name). + +Verbose (bit-by-bit) bitsets allow sending symbolic names for bits together +with their values which saves a round trip (when the bitset is passed in a +request) or at least a second request (when the bitset is in a reply). This is +useful for one shot applications like traditional ethtool command. On the +other hand, long running applications like ethtool monitor (displaying +notifications) or network management daemons may prefer fetching the names +only once and using compact form to save message size. Notifications from +ethtool netlink interface always use compact form for bitsets. + +A bitset can represent either a value/mask pair (``ETHTOOL_A_BITSET_NOMASK`` +not set) or a single bitmap (``ETHTOOL_A_BITSET_NOMASK`` set). In requests +modifying a bitmap, the former changes the bit set in mask to values set in +value and preserves the rest; the latter sets the bits set in the bitmap and +clears the rest. + +Compact form: nested (bitset) atrribute contents: + + ============================ ====== ============================ + ``ETHTOOL_A_BITSET_NOMASK`` flag no mask, only a list + ``ETHTOOL_A_BITSET_SIZE`` u32 number of significant bits + ``ETHTOOL_A_BITSET_VALUE`` binary bitmap of bit values + ``ETHTOOL_A_BITSET_MASK`` binary bitmap of valid bits + ============================ ====== ============================ + +Value and mask must have length at least ``ETHTOOL_A_BITSET_SIZE`` bits +rounded up to a multiple of 32 bits. They consist of 32-bit words in host byte +order, words ordered from least significant to most significant (i.e. the same +way as bitmaps are passed with ioctl interface). + +For compact form, ``ETHTOOL_A_BITSET_SIZE`` and ``ETHTOOL_A_BITSET_VALUE`` are +mandatory. ``ETHTOOL_A_BITSET_MASK`` attribute is mandatory if +``ETHTOOL_A_BITSET_NOMASK`` is not set (bitset represents a value/mask pair); +if ``ETHTOOL_A_BITSET_NOMASK`` is not set, ``ETHTOOL_A_BITSET_MASK`` is not +allowed (bitset represents a single bitmap. + +Kernel bit set length may differ from userspace length if older application is +used on newer kernel or vice versa. If userspace bitmap is longer, an error is +issued only if the request actually tries to set values of some bits not +recognized by kernel. + +Bit-by-bit form: nested (bitset) attribute contents: + + +------------------------------------+--------+-----------------------------+ + | ``ETHTOOL_A_BITSET_NOMASK`` | flag | no mask, only a list | + +------------------------------------+--------+-----------------------------+ + | ``ETHTOOL_A_BITSET_SIZE`` | u32 | number of significant bits | + +------------------------------------+--------+-----------------------------+ + | ``ETHTOOL_A_BITSET_BITS`` | nested | array of bits | + +-+----------------------------------+--------+-----------------------------+ + | | ``ETHTOOL_A_BITSET_BITS_BIT+`` | nested | one bit | + +-+-+--------------------------------+--------+-----------------------------+ + | | | ``ETHTOOL_A_BITSET_BIT_INDEX`` | u32 | bit index (0 for LSB) | + +-+-+--------------------------------+--------+-----------------------------+ + | | | ``ETHTOOL_A_BITSET_BIT_NAME`` | string | bit name | + +-+-+--------------------------------+--------+-----------------------------+ + | | | ``ETHTOOL_A_BITSET_BIT_VALUE`` | flag | present if bit is set | + +-+-+--------------------------------+--------+-----------------------------+ + +Bit size is optional for bit-by-bit form. ``ETHTOOL_A_BITSET_BITS`` nest can +only contain ``ETHTOOL_A_BITSET_BITS_BIT`` attributes but there can be an +arbitrary number of them. A bit may be identified by its index or by its +name. When used in requests, listed bits are set to 0 or 1 according to +``ETHTOOL_A_BITSET_BIT_VALUE``, the rest is preserved. A request fails if +index exceeds kernel bit length or if name is not recognized. + +When ``ETHTOOL_A_BITSET_NOMASK`` flag is present, bitset is interpreted as +a simple bitmap. ``ETHTOOL_A_BITSET_BIT_VALUE`` attributes are not used in +such case. Such bitset represents a bitmap with listed bits set and the rest +zero. + +In requests, application can use either form. Form used by kernel in reply is +determined by ``ETHTOOL_FLAG_COMPACT_BITSETS`` flag in flags field of request +header. Semantics of value and mask depends on the attribute. + + +List of message types +===================== + +All constants identifying message types use ``ETHTOOL_CMD_`` prefix and suffix +according to message purpose: + + ============== ====================================== + ``_GET`` userspace request to retrieve data + ``_SET`` userspace request to set data + ``_ACT`` userspace request to perform an action + ``_GET_REPLY`` kernel reply to a ``GET`` request + ``_SET_REPLY`` kernel reply to a ``SET`` request + ``_ACT_REPLY`` kernel reply to an ``ACT`` request + ``_NTF`` kernel notification + ============== ====================================== + +Userspace to kernel: + + ===================================== ================================ + ``ETHTOOL_MSG_STRSET_GET`` get string set + ``ETHTOOL_MSG_LINKINFO_GET`` get link settings + ``ETHTOOL_MSG_LINKINFO_SET`` set link settings + ``ETHTOOL_MSG_LINKMODES_GET`` get link modes info + ``ETHTOOL_MSG_LINKMODES_SET`` set link modes info + ``ETHTOOL_MSG_LINKSTATE_GET`` get link state + ``ETHTOOL_MSG_DEBUG_GET`` get debugging settings + ``ETHTOOL_MSG_DEBUG_SET`` set debugging settings + ``ETHTOOL_MSG_WOL_GET`` get wake-on-lan settings + ``ETHTOOL_MSG_WOL_SET`` set wake-on-lan settings + ===================================== ================================ + +Kernel to userspace: + + ===================================== ================================= + ``ETHTOOL_MSG_STRSET_GET_REPLY`` string set contents + ``ETHTOOL_MSG_LINKINFO_GET_REPLY`` link settings + ``ETHTOOL_MSG_LINKINFO_NTF`` link settings notification + ``ETHTOOL_MSG_LINKMODES_GET_REPLY`` link modes info + ``ETHTOOL_MSG_LINKMODES_NTF`` link modes notification + ``ETHTOOL_MSG_LINKSTATE_GET_REPLY`` link state info + ``ETHTOOL_MSG_DEBUG_GET_REPLY`` debugging settings + ``ETHTOOL_MSG_DEBUG_NTF`` debugging settings notification + ``ETHTOOL_MSG_WOL_GET_REPLY`` wake-on-lan settings + ``ETHTOOL_MSG_WOL_NTF`` wake-on-lan settings notification + ===================================== ================================= + +``GET`` requests are sent by userspace applications to retrieve device +information. They usually do not contain any message specific attributes. +Kernel replies with corresponding "GET_REPLY" message. For most types, ``GET`` +request with ``NLM_F_DUMP`` and no device identification can be used to query +the information for all devices supporting the request. + +If the data can be also modified, corresponding ``SET`` message with the same +layout as corresponding ``GET_REPLY`` is used to request changes. Only +attributes where a change is requested are included in such request (also, not +all attributes may be changed). Replies to most ``SET`` request consist only +of error code and extack; if kernel provides additional data, it is sent in +the form of corresponding ``SET_REPLY`` message which can be suppressed by +setting ``ETHTOOL_FLAG_OMIT_REPLY`` flag in request header. + +Data modification also triggers sending a ``NTF`` message with a notification. +These usually bear only a subset of attributes which was affected by the +change. The same notification is issued if the data is modified using other +means (mostly ioctl ethtool interface). Unlike notifications from ethtool +netlink code which are only sent if something actually changed, notifications +triggered by ioctl interface may be sent even if the request did not actually +change any data. + +``ACT`` messages request kernel (driver) to perform a specific action. If some +information is reported by kernel (which can be suppressed by setting +``ETHTOOL_FLAG_OMIT_REPLY`` flag in request header), the reply takes form of +an ``ACT_REPLY`` message. Performing an action also triggers a notification +(``NTF`` message). + +Later sections describe the format and semantics of these messages. + + +STRSET_GET +========== + +Requests contents of a string set as provided by ioctl commands +``ETHTOOL_GSSET_INFO`` and ``ETHTOOL_GSTRINGS.`` String sets are not user +writeable so that the corresponding ``STRSET_SET`` message is only used in +kernel replies. There are two types of string sets: global (independent of +a device, e.g. device feature names) and device specific (e.g. device private +flags). + +Request contents: + + +---------------------------------------+--------+------------------------+ + | ``ETHTOOL_A_STRSET_HEADER`` | nested | request header | + +---------------------------------------+--------+------------------------+ + | ``ETHTOOL_A_STRSET_STRINGSETS`` | nested | string set to request | + +-+-------------------------------------+--------+------------------------+ + | | ``ETHTOOL_A_STRINGSETS_STRINGSET+`` | nested | one string set | + +-+-+-----------------------------------+--------+------------------------+ + | | | ``ETHTOOL_A_STRINGSET_ID`` | u32 | set id | + +-+-+-----------------------------------+--------+------------------------+ + +Kernel response contents: + + +---------------------------------------+--------+-----------------------+ + | ``ETHTOOL_A_STRSET_HEADER`` | nested | reply header | + +---------------------------------------+--------+-----------------------+ + | ``ETHTOOL_A_STRSET_STRINGSETS`` | nested | array of string sets | + +-+-------------------------------------+--------+-----------------------+ + | | ``ETHTOOL_A_STRINGSETS_STRINGSET+`` | nested | one string set | + +-+-+-----------------------------------+--------+-----------------------+ + | | | ``ETHTOOL_A_STRINGSET_ID`` | u32 | set id | + +-+-+-----------------------------------+--------+-----------------------+ + | | | ``ETHTOOL_A_STRINGSET_COUNT`` | u32 | number of strings | + +-+-+-----------------------------------+--------+-----------------------+ + | | | ``ETHTOOL_A_STRINGSET_STRINGS`` | nested | array of strings | + +-+-+-+---------------------------------+--------+-----------------------+ + | | | | ``ETHTOOL_A_STRINGS_STRING+`` | nested | one string | + +-+-+-+-+-------------------------------+--------+-----------------------+ + | | | | | ``ETHTOOL_A_STRING_INDEX`` | u32 | string index | + +-+-+-+-+-------------------------------+--------+-----------------------+ + | | | | | ``ETHTOOL_A_STRING_VALUE`` | string | string value | + +-+-+-+-+-------------------------------+--------+-----------------------+ + | ``ETHTOOL_A_STRSET_COUNTS_ONLY`` | flag | return only counts | + +---------------------------------------+--------+-----------------------+ + +Device identification in request header is optional. Depending on its presence +a and ``NLM_F_DUMP`` flag, there are three type of ``STRSET_GET`` requests: + + - no ``NLM_F_DUMP,`` no device: get "global" stringsets + - no ``NLM_F_DUMP``, with device: get string sets related to the device + - ``NLM_F_DUMP``, no device: get device related string sets for all devices + +If there is no ``ETHTOOL_A_STRSET_STRINGSETS`` array, all string sets of +requested type are returned, otherwise only those specified in the request. +Flag ``ETHTOOL_A_STRSET_COUNTS_ONLY`` tells kernel to only return string +counts of the sets, not the actual strings. + + +LINKINFO_GET +============ + +Requests link settings as provided by ``ETHTOOL_GLINKSETTINGS`` except for +link modes and autonegotiation related information. The request does not use +any attributes. + +Request contents: + + ==================================== ====== ========================== + ``ETHTOOL_A_LINKINFO_HEADER`` nested request header + ==================================== ====== ========================== + +Kernel response contents: + + ==================================== ====== ========================== + ``ETHTOOL_A_LINKINFO_HEADER`` nested reply header + ``ETHTOOL_A_LINKINFO_PORT`` u8 physical port + ``ETHTOOL_A_LINKINFO_PHYADDR`` u8 phy MDIO address + ``ETHTOOL_A_LINKINFO_TP_MDIX`` u8 MDI(-X) status + ``ETHTOOL_A_LINKINFO_TP_MDIX_CTRL`` u8 MDI(-X) control + ``ETHTOOL_A_LINKINFO_TRANSCEIVER`` u8 transceiver + ==================================== ====== ========================== + +Attributes and their values have the same meaning as matching members of the +corresponding ioctl structures. + +``LINKINFO_GET`` allows dump requests (kernel returns reply message for all +devices supporting the request). + + +LINKINFO_SET +============ + +``LINKINFO_SET`` request allows setting some of the attributes reported by +``LINKINFO_GET``. + +Request contents: + + ==================================== ====== ========================== + ``ETHTOOL_A_LINKINFO_HEADER`` nested request header + ``ETHTOOL_A_LINKINFO_PORT`` u8 physical port + ``ETHTOOL_A_LINKINFO_PHYADDR`` u8 phy MDIO address + ``ETHTOOL_A_LINKINFO_TP_MDIX_CTRL`` u8 MDI(-X) control + ==================================== ====== ========================== + +MDI(-X) status and transceiver cannot be set, request with the corresponding +attributes is rejected. + + +LINKMODES_GET +============= + +Requests link modes (supported, advertised and peer advertised) and related +information (autonegotiation status, link speed and duplex) as provided by +``ETHTOOL_GLINKSETTINGS``. The request does not use any attributes. + +Request contents: + + ==================================== ====== ========================== + ``ETHTOOL_A_LINKMODES_HEADER`` nested request header + ==================================== ====== ========================== + +Kernel response contents: + + ==================================== ====== ========================== + ``ETHTOOL_A_LINKMODES_HEADER`` nested reply header + ``ETHTOOL_A_LINKMODES_AUTONEG`` u8 autonegotiation status + ``ETHTOOL_A_LINKMODES_OURS`` bitset advertised link modes + ``ETHTOOL_A_LINKMODES_PEER`` bitset partner link modes + ``ETHTOOL_A_LINKMODES_SPEED`` u32 link speed (Mb/s) + ``ETHTOOL_A_LINKMODES_DUPLEX`` u8 duplex mode + ==================================== ====== ========================== + +For ``ETHTOOL_A_LINKMODES_OURS``, value represents advertised modes and mask +represents supported modes. ``ETHTOOL_A_LINKMODES_PEER`` in the reply is a bit +list. + +``LINKMODES_GET`` allows dump requests (kernel returns reply messages for all +devices supporting the request). + + +LINKMODES_SET +============= + +Request contents: + + ==================================== ====== ========================== + ``ETHTOOL_A_LINKMODES_HEADER`` nested request header + ``ETHTOOL_A_LINKMODES_AUTONEG`` u8 autonegotiation status + ``ETHTOOL_A_LINKMODES_OURS`` bitset advertised link modes + ``ETHTOOL_A_LINKMODES_PEER`` bitset partner link modes + ``ETHTOOL_A_LINKMODES_SPEED`` u32 link speed (Mb/s) + ``ETHTOOL_A_LINKMODES_DUPLEX`` u8 duplex mode + ==================================== ====== ========================== + +``ETHTOOL_A_LINKMODES_OURS`` bit set allows setting advertised link modes. If +autonegotiation is on (either set now or kept from before), advertised modes +are not changed (no ``ETHTOOL_A_LINKMODES_OURS`` attribute) and at least one +of speed and duplex is specified, kernel adjusts advertised modes to all +supported modes matching speed, duplex or both (whatever is specified). This +autoselection is done on ethtool side with ioctl interface, netlink interface +is supposed to allow requesting changes without knowing what exactly kernel +supports. + + +LINKSTATE_GET +============= + +Requests link state information. At the moment, only link up/down flag (as +provided by ``ETHTOOL_GLINK`` ioctl command) is provided but some future +extensions are planned (e.g. link down reason). This request does not have any +attributes. + +Request contents: + + ==================================== ====== ========================== + ``ETHTOOL_A_LINKSTATE_HEADER`` nested request header + ==================================== ====== ========================== + +Kernel response contents: + + ==================================== ====== ========================== + ``ETHTOOL_A_LINKSTATE_HEADER`` nested reply header + ``ETHTOOL_A_LINKSTATE_LINK`` bool link state (up/down) + ==================================== ====== ========================== + +For most NIC drivers, the value of ``ETHTOOL_A_LINKSTATE_LINK`` returns +carrier flag provided by ``netif_carrier_ok()`` but there are drivers which +define their own handler. + +``LINKSTATE_GET`` allows dump requests (kernel returns reply messages for all +devices supporting the request). + + +DEBUG_GET +========= + +Requests debugging settings of a device. At the moment, only message mask is +provided. + +Request contents: + + ==================================== ====== ========================== + ``ETHTOOL_A_DEBUG_HEADER`` nested request header + ==================================== ====== ========================== + +Kernel response contents: + + ==================================== ====== ========================== + ``ETHTOOL_A_DEBUG_HEADER`` nested reply header + ``ETHTOOL_A_DEBUG_MSGMASK`` bitset message mask + ==================================== ====== ========================== + +The message mask (``ETHTOOL_A_DEBUG_MSGMASK``) is equal to message level as +provided by ``ETHTOOL_GMSGLVL`` and set by ``ETHTOOL_SMSGLVL`` in ioctl +interface. While it is called message level there for historical reasons, most +drivers and almost all newer drivers use it as a mask of enabled message +classes (represented by ``NETIF_MSG_*`` constants); therefore netlink +interface follows its actual use in practice. + +``DEBUG_GET`` allows dump requests (kernel returns reply messages for all +devices supporting the request). + + +DEBUG_SET +========= + +Set or update debugging settings of a device. At the moment, only message mask +is supported. + +Request contents: + + ==================================== ====== ========================== + ``ETHTOOL_A_DEBUG_HEADER`` nested request header + ``ETHTOOL_A_DEBUG_MSGMASK`` bitset message mask + ==================================== ====== ========================== + +``ETHTOOL_A_DEBUG_MSGMASK`` bit set allows setting or modifying mask of +enabled debugging message types for the device. + + +WOL_GET +======= + +Query device wake-on-lan settings. Unlike most "GET" type requests, +``ETHTOOL_MSG_WOL_GET`` requires (netns) ``CAP_NET_ADMIN`` privileges as it +(potentially) provides SecureOn(tm) password which is confidential. + +Request contents: + + ==================================== ====== ========================== + ``ETHTOOL_A_WOL_HEADER`` nested request header + ==================================== ====== ========================== + +Kernel response contents: + + ==================================== ====== ========================== + ``ETHTOOL_A_WOL_HEADER`` nested reply header + ``ETHTOOL_A_WOL_MODES`` bitset mask of enabled WoL modes + ``ETHTOOL_A_WOL_SOPASS`` binary SecureOn(tm) password + ==================================== ====== ========================== + +In reply, ``ETHTOOL_A_WOL_MODES`` mask consists of modes supported by the +device, value of modes which are enabled. ``ETHTOOL_A_WOL_SOPASS`` is only +included in reply if ``WAKE_MAGICSECURE`` mode is supported. + + +WOL_SET +======= + +Set or update wake-on-lan settings. + +Request contents: + + ==================================== ====== ========================== + ``ETHTOOL_A_WOL_HEADER`` nested request header + ``ETHTOOL_A_WOL_MODES`` bitset enabled WoL modes + ``ETHTOOL_A_WOL_SOPASS`` binary SecureOn(tm) password + ==================================== ====== ========================== + +``ETHTOOL_A_WOL_SOPASS`` is only allowed for devices supporting +``WAKE_MAGICSECURE`` mode. + + +Request translation +=================== + +The following table maps ioctl commands to netlink commands providing their +functionality. Entries with "n/a" in right column are commands which do not +have their netlink replacement yet. + + =================================== ===================================== + ioctl command netlink command + =================================== ===================================== + ``ETHTOOL_GSET`` ``ETHTOOL_MSG_LINKINFO_GET`` + ``ETHTOOL_MSG_LINKMODES_GET`` + ``ETHTOOL_SSET`` ``ETHTOOL_MSG_LINKINFO_SET`` + ``ETHTOOL_MSG_LINKMODES_SET`` + ``ETHTOOL_GDRVINFO`` n/a + ``ETHTOOL_GREGS`` n/a + ``ETHTOOL_GWOL`` ``ETHTOOL_MSG_WOL_GET`` + ``ETHTOOL_SWOL`` ``ETHTOOL_MSG_WOL_SET`` + ``ETHTOOL_GMSGLVL`` ``ETHTOOL_MSG_DEBUG_GET`` + ``ETHTOOL_SMSGLVL`` ``ETHTOOL_MSG_DEBUG_SET`` + ``ETHTOOL_NWAY_RST`` n/a + ``ETHTOOL_GLINK`` ``ETHTOOL_MSG_LINKSTATE_GET`` + ``ETHTOOL_GEEPROM`` n/a + ``ETHTOOL_SEEPROM`` n/a + ``ETHTOOL_GCOALESCE`` n/a + ``ETHTOOL_SCOALESCE`` n/a + ``ETHTOOL_GRINGPARAM`` n/a + ``ETHTOOL_SRINGPARAM`` n/a + ``ETHTOOL_GPAUSEPARAM`` n/a + ``ETHTOOL_SPAUSEPARAM`` n/a + ``ETHTOOL_GRXCSUM`` n/a + ``ETHTOOL_SRXCSUM`` n/a + ``ETHTOOL_GTXCSUM`` n/a + ``ETHTOOL_STXCSUM`` n/a + ``ETHTOOL_GSG`` n/a + ``ETHTOOL_SSG`` n/a + ``ETHTOOL_TEST`` n/a + ``ETHTOOL_GSTRINGS`` ``ETHTOOL_MSG_STRSET_GET`` + ``ETHTOOL_PHYS_ID`` n/a + ``ETHTOOL_GSTATS`` n/a + ``ETHTOOL_GTSO`` n/a + ``ETHTOOL_STSO`` n/a + ``ETHTOOL_GPERMADDR`` rtnetlink ``RTM_GETLINK`` + ``ETHTOOL_GUFO`` n/a + ``ETHTOOL_SUFO`` n/a + ``ETHTOOL_GGSO`` n/a + ``ETHTOOL_SGSO`` n/a + ``ETHTOOL_GFLAGS`` n/a + ``ETHTOOL_SFLAGS`` n/a + ``ETHTOOL_GPFLAGS`` n/a + ``ETHTOOL_SPFLAGS`` n/a + ``ETHTOOL_GRXFH`` n/a + ``ETHTOOL_SRXFH`` n/a + ``ETHTOOL_GGRO`` n/a + ``ETHTOOL_SGRO`` n/a + ``ETHTOOL_GRXRINGS`` n/a + ``ETHTOOL_GRXCLSRLCNT`` n/a + ``ETHTOOL_GRXCLSRULE`` n/a + ``ETHTOOL_GRXCLSRLALL`` n/a + ``ETHTOOL_SRXCLSRLDEL`` n/a + ``ETHTOOL_SRXCLSRLINS`` n/a + ``ETHTOOL_FLASHDEV`` n/a + ``ETHTOOL_RESET`` n/a + ``ETHTOOL_SRXNTUPLE`` n/a + ``ETHTOOL_GRXNTUPLE`` n/a + ``ETHTOOL_GSSET_INFO`` ``ETHTOOL_MSG_STRSET_GET`` + ``ETHTOOL_GRXFHINDIR`` n/a + ``ETHTOOL_SRXFHINDIR`` n/a + ``ETHTOOL_GFEATURES`` n/a + ``ETHTOOL_SFEATURES`` n/a + ``ETHTOOL_GCHANNELS`` n/a + ``ETHTOOL_SCHANNELS`` n/a + ``ETHTOOL_SET_DUMP`` n/a + ``ETHTOOL_GET_DUMP_FLAG`` n/a + ``ETHTOOL_GET_DUMP_DATA`` n/a + ``ETHTOOL_GET_TS_INFO`` n/a + ``ETHTOOL_GMODULEINFO`` n/a + ``ETHTOOL_GMODULEEEPROM`` n/a + ``ETHTOOL_GEEE`` n/a + ``ETHTOOL_SEEE`` n/a + ``ETHTOOL_GRSSH`` n/a + ``ETHTOOL_SRSSH`` n/a + ``ETHTOOL_GTUNABLE`` n/a + ``ETHTOOL_STUNABLE`` n/a + ``ETHTOOL_GPHYSTATS`` n/a + ``ETHTOOL_PERQUEUE`` n/a + ``ETHTOOL_GLINKSETTINGS`` ``ETHTOOL_MSG_LINKINFO_GET`` + ``ETHTOOL_MSG_LINKMODES_GET`` + ``ETHTOOL_SLINKSETTINGS`` ``ETHTOOL_MSG_LINKINFO_SET`` + ``ETHTOOL_MSG_LINKMODES_SET`` + ``ETHTOOL_PHY_GTUNABLE`` n/a + ``ETHTOOL_PHY_STUNABLE`` n/a + ``ETHTOOL_GFECPARAM`` n/a + ``ETHTOOL_SFECPARAM`` n/a + =================================== ===================================== diff --git a/Documentation/networking/index.rst b/Documentation/networking/index.rst index 5acab1290e03..d07d9855dcd3 100644 --- a/Documentation/networking/index.rst +++ b/Documentation/networking/index.rst @@ -13,9 +13,8 @@ Contents: can_ucan_protocol device_drivers/index dsa/index - devlink-info-versions - devlink-trap - devlink-trap-netdevsim + devlink/index + ethtool-netlink ieee802154 j1939 kapi diff --git a/Documentation/networking/ip-sysctl.txt b/Documentation/networking/ip-sysctl.txt index 48ccb1b31160..5f53faff4e25 100644 --- a/Documentation/networking/ip-sysctl.txt +++ b/Documentation/networking/ip-sysctl.txt @@ -479,6 +479,10 @@ tcp_no_metrics_save - BOOLEAN degradation. If set, TCP will not cache metrics on closing connections. +tcp_no_ssthresh_metrics_save - BOOLEAN + Controls whether TCP saves ssthresh metrics in the route cache. + Default is 1, which disables ssthresh metrics. + tcp_orphan_retries - INTEGER This value influences the timeout of a locally closed TCP connection, when RTO retransmissions remain unacknowledged. diff --git a/Documentation/networking/nf_flowtable.txt b/Documentation/networking/nf_flowtable.txt index ca2136c76042..0bf32d1121be 100644 --- a/Documentation/networking/nf_flowtable.txt +++ b/Documentation/networking/nf_flowtable.txt @@ -76,7 +76,7 @@ flowtable and add one rule to your forward chain. table inet x { flowtable f { - hook ingress priority 0 devices = { eth0, eth1 }; + hook ingress priority 0; devices = { eth0, eth1 }; } chain y { type filter hook forward priority 0; policy accept; diff --git a/Documentation/networking/phy.rst b/Documentation/networking/phy.rst index e0a7c7af6525..1e4735cc0553 100644 --- a/Documentation/networking/phy.rst +++ b/Documentation/networking/phy.rst @@ -267,6 +267,24 @@ Some of the interface modes are described below: duplex, pause or other settings. This is dependent on the MAC and/or PHY behaviour. +``PHY_INTERFACE_MODE_10GBASER`` + This is the IEEE 802.3 Clause 49 defined 10GBASE-R protocol used with + various different mediums. Please refer to the IEEE standard for a + definition of this. + + Note: 10GBASE-R is just one protocol that can be used with XFI and SFI. + XFI and SFI permit multiple protocols over a single SERDES lane, and + also defines the electrical characteristics of the signals with a host + compliance board plugged into the host XFP/SFP connector. Therefore, + XFI and SFI are not PHY interface types in their own right. + +``PHY_INTERFACE_MODE_10GKR`` + This is the IEEE 802.3 Clause 49 defined 10GBASE-R with Clause 73 + autonegotiation. Please refer to the IEEE standard for further + information. + + Note: due to legacy usage, some 10GBASE-R usage incorrectly makes + use of this definition. Pause frames / flow control =========================== diff --git a/Documentation/networking/sfp-phylink.rst b/Documentation/networking/sfp-phylink.rst index a5e00a159d21..d753a309f9d1 100644 --- a/Documentation/networking/sfp-phylink.rst +++ b/Documentation/networking/sfp-phylink.rst @@ -251,7 +251,8 @@ this documentation. phylink_mac_change(priv->phylink, link_is_up); where ``link_is_up`` is true if the link is currently up or false - otherwise. + otherwise. If a MAC is unable to provide these interrupts, then + it should set ``priv->phylink_config.pcs_poll = true;`` in step 9. 11. Verify that the driver does not call:: diff --git a/Documentation/nvdimm/maintainer-entry-profile.rst b/Documentation/nvdimm/maintainer-entry-profile.rst index 77081fd9be95..efe37adadcea 100644 --- a/Documentation/nvdimm/maintainer-entry-profile.rst +++ b/Documentation/nvdimm/maintainer-entry-profile.rst @@ -33,7 +33,8 @@ Those tests need to be passed before the patches go upstream, but not necessarily before initial posting. Contact the list if you need help getting the test environment set up. -### ACPI Device Specific Methods (_DSM) +ACPI Device Specific Methods (_DSM) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Before patches enabling for a new _DSM family will be considered it must be assigned a format-interface-code from the NVDIMM Sub-team of the ACPI Specification Working Group. In general, the stance of the subsystem is diff --git a/Documentation/padata.txt b/Documentation/padata.txt deleted file mode 100644 index b37ba1eaace3..000000000000 --- a/Documentation/padata.txt +++ /dev/null @@ -1,163 +0,0 @@ -======================================= -The padata parallel execution mechanism -======================================= - -:Last updated: for 2.6.36 - -Padata is a mechanism by which the kernel can farm work out to be done in -parallel on multiple CPUs while retaining the ordering of tasks. It was -developed for use with the IPsec code, which needs to be able to perform -encryption and decryption on large numbers of packets without reordering -those packets. The crypto developers made a point of writing padata in a -sufficiently general fashion that it could be put to other uses as well. - -The first step in using padata is to set up a padata_instance structure for -overall control of how tasks are to be run:: - - #include <linux/padata.h> - - struct padata_instance *padata_alloc(const char *name, - const struct cpumask *pcpumask, - const struct cpumask *cbcpumask); - -'name' simply identifies the instance. - -The pcpumask describes which processors will be used to execute work -submitted to this instance in parallel. The cbcpumask defines which -processors are allowed to be used as the serialization callback processor. -The workqueue wq is where the work will actually be done; it should be -a multithreaded queue, naturally. - -To allocate a padata instance with the cpu_possible_mask for both -cpumasks this helper function can be used:: - - struct padata_instance *padata_alloc_possible(struct workqueue_struct *wq); - -Note: Padata maintains two kinds of cpumasks internally. The user supplied -cpumasks, submitted by padata_alloc/padata_alloc_possible and the 'usable' -cpumasks. The usable cpumasks are always a subset of active CPUs in the -user supplied cpumasks; these are the cpumasks padata actually uses. So -it is legal to supply a cpumask to padata that contains offline CPUs. -Once an offline CPU in the user supplied cpumask comes online, padata -is going to use it. - -There are functions for enabling and disabling the instance:: - - int padata_start(struct padata_instance *pinst); - void padata_stop(struct padata_instance *pinst); - -These functions are setting or clearing the "PADATA_INIT" flag; -if that flag is not set, other functions will refuse to work. -padata_start returns zero on success (flag set) or -EINVAL if the -padata cpumask contains no active CPU (flag not set). -padata_stop clears the flag and blocks until the padata instance -is unused. - -The list of CPUs to be used can be adjusted with these functions:: - - int padata_set_cpumasks(struct padata_instance *pinst, - cpumask_var_t pcpumask, - cpumask_var_t cbcpumask); - int padata_set_cpumask(struct padata_instance *pinst, int cpumask_type, - cpumask_var_t cpumask); - int padata_add_cpu(struct padata_instance *pinst, int cpu, int mask); - int padata_remove_cpu(struct padata_instance *pinst, int cpu, int mask); - -Changing the CPU masks are expensive operations, though, so it should not be -done with great frequency. - -It's possible to change both cpumasks of a padata instance with -padata_set_cpumasks by specifying the cpumasks for parallel execution (pcpumask) -and for the serial callback function (cbcpumask). padata_set_cpumask is used to -change just one of the cpumasks. Here cpumask_type is one of PADATA_CPU_SERIAL, -PADATA_CPU_PARALLEL and cpumask specifies the new cpumask to use. -To simply add or remove one CPU from a certain cpumask the functions -padata_add_cpu/padata_remove_cpu are used. cpu specifies the CPU to add or -remove and mask is one of PADATA_CPU_SERIAL, PADATA_CPU_PARALLEL. - -If a user is interested in padata cpumask changes, he can register to -the padata cpumask change notifier:: - - int padata_register_cpumask_notifier(struct padata_instance *pinst, - struct notifier_block *nblock); - -To unregister from that notifier:: - - int padata_unregister_cpumask_notifier(struct padata_instance *pinst, - struct notifier_block *nblock); - -The padata cpumask change notifier notifies about changes of the usable -cpumasks, i.e. the subset of active CPUs in the user supplied cpumask. - -Padata calls the notifier chain with:: - - blocking_notifier_call_chain(&pinst->cpumask_change_notifier, - notification_mask, - &pd_new->cpumask); - -Here cpumask_change_notifier is registered notifier, notification_mask -is one of PADATA_CPU_SERIAL, PADATA_CPU_PARALLEL and cpumask is a pointer -to a struct padata_cpumask that contains the new cpumask information. - -Actually submitting work to the padata instance requires the creation of a -padata_priv structure:: - - struct padata_priv { - /* Other stuff here... */ - void (*parallel)(struct padata_priv *padata); - void (*serial)(struct padata_priv *padata); - }; - -This structure will almost certainly be embedded within some larger -structure specific to the work to be done. Most of its fields are private to -padata, but the structure should be zeroed at initialisation time, and the -parallel() and serial() functions should be provided. Those functions will -be called in the process of getting the work done as we will see -momentarily. - -The submission of work is done with:: - - int padata_do_parallel(struct padata_instance *pinst, - struct padata_priv *padata, int cb_cpu); - -The pinst and padata structures must be set up as described above; cb_cpu -specifies which CPU will be used for the final callback when the work is -done; it must be in the current instance's CPU mask. The return value from -padata_do_parallel() is zero on success, indicating that the work is in -progress. -EBUSY means that somebody, somewhere else is messing with the -instance's CPU mask, while -EINVAL is a complaint about cb_cpu not being -in that CPU mask or about a not running instance. - -Each task submitted to padata_do_parallel() will, in turn, be passed to -exactly one call to the above-mentioned parallel() function, on one CPU, so -true parallelism is achieved by submitting multiple tasks. parallel() runs with -software interrupts disabled and thus cannot sleep. The parallel() -function gets the padata_priv structure pointer as its lone parameter; -information about the actual work to be done is probably obtained by using -container_of() to find the enclosing structure. - -Note that parallel() has no return value; the padata subsystem assumes that -parallel() will take responsibility for the task from this point. The work -need not be completed during this call, but, if parallel() leaves work -outstanding, it should be prepared to be called again with a new job before -the previous one completes. When a task does complete, parallel() (or -whatever function actually finishes the job) should inform padata of the -fact with a call to:: - - void padata_do_serial(struct padata_priv *padata); - -At some point in the future, padata_do_serial() will trigger a call to the -serial() function in the padata_priv structure. That call will happen on -the CPU requested in the initial call to padata_do_parallel(); it, too, is -run with local software interrupts disabled. -Note that this call may be deferred for a while since the padata code takes -pains to ensure that tasks are completed in the order in which they were -submitted. - -The one remaining function in the padata API should be called to clean up -when a padata instance is no longer needed:: - - void padata_free(struct padata_instance *pinst); - -This function will busy-wait while any remaining tasks are completed, so it -might be best not to call it while there is work outstanding. diff --git a/Documentation/power/interface.rst b/Documentation/power/interface.rst deleted file mode 100644 index 8d270ed27228..000000000000 --- a/Documentation/power/interface.rst +++ /dev/null @@ -1,79 +0,0 @@ -=========================================== -Power Management Interface for System Sleep -=========================================== - -Copyright (c) 2016 Intel Corp., Rafael J. Wysocki <rafael.j.wysocki@intel.com> - -The power management subsystem provides userspace with a unified sysfs interface -for system sleep regardless of the underlying system architecture or platform. -The interface is located in the /sys/power/ directory (assuming that sysfs is -mounted at /sys). - -/sys/power/state is the system sleep state control file. - -Reading from it returns a list of supported sleep states, encoded as: - -- 'freeze' (Suspend-to-Idle) -- 'standby' (Power-On Suspend) -- 'mem' (Suspend-to-RAM) -- 'disk' (Suspend-to-Disk) - -Suspend-to-Idle is always supported. Suspend-to-Disk is always supported -too as long the kernel has been configured to support hibernation at all -(ie. CONFIG_HIBERNATION is set in the kernel configuration file). Support -for Suspend-to-RAM and Power-On Suspend depends on the capabilities of the -platform. - -If one of the strings listed in /sys/power/state is written to it, the system -will attempt to transition into the corresponding sleep state. Refer to -Documentation/admin-guide/pm/sleep-states.rst for a description of each of -those states. - -/sys/power/disk controls the operating mode of hibernation (Suspend-to-Disk). -Specifically, it tells the kernel what to do after creating a hibernation image. - -Reading from it returns a list of supported options encoded as: - -- 'platform' (put the system into sleep using a platform-provided method) -- 'shutdown' (shut the system down) -- 'reboot' (reboot the system) -- 'suspend' (trigger a Suspend-to-RAM transition) -- 'test_resume' (resume-after-hibernation test mode) - -The currently selected option is printed in square brackets. - -The 'platform' option is only available if the platform provides a special -mechanism to put the system to sleep after creating a hibernation image (ACPI -does that, for example). The 'suspend' option is available if Suspend-to-RAM -is supported. Refer to Documentation/power/basic-pm-debugging.rst for the -description of the 'test_resume' option. - -To select an option, write the string representing it to /sys/power/disk. - -/sys/power/image_size controls the size of hibernation images. - -It can be written a string representing a non-negative integer that will be -used as a best-effort upper limit of the image size, in bytes. The hibernation -core will do its best to ensure that the image size will not exceed that number. -However, if that turns out to be impossible to achieve, a hibernation image will -still be created and its size will be as small as possible. In particular, -writing '0' to this file will enforce hibernation images to be as small as -possible. - -Reading from this file returns the current image size limit, which is set to -around 2/5 of available RAM by default. - -/sys/power/pm_trace controls the PM trace mechanism saving the last suspend -or resume event point in the RTC across reboots. - -It helps to debug hard lockups or reboots due to device driver failures that -occur during system suspend or resume (which is more common) more effectively. - -If /sys/power/pm_trace contains '1', the fingerprint of each suspend/resume -event point in turn will be stored in the RTC memory (overwriting the actual -RTC information), so it will survive a system crash if one occurs right after -storing it and it can be used later to identify the driver that caused the crash -to happen (see Documentation/power/s2ram.rst for more information). - -Initially it contains '0' which may be changed to '1' by writing a string -representing a nonzero integer into it. diff --git a/Documentation/powerpc/imc.rst b/Documentation/powerpc/imc.rst new file mode 100644 index 000000000000..633bcee7dc85 --- /dev/null +++ b/Documentation/powerpc/imc.rst @@ -0,0 +1,199 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. _imc: + +=================================== +IMC (In-Memory Collection Counters) +=================================== + +Anju T Sudhakar, 10 May 2019 + +.. contents:: + :depth: 3 + + +Basic overview +============== + +IMC (In-Memory collection counters) is a hardware monitoring facility that +collects large numbers of hardware performance events at Nest level (these are +on-chip but off-core), Core level and Thread level. + +The Nest PMU counters are handled by a Nest IMC microcode which runs in the OCC +(On-Chip Controller) complex. The microcode collects the counter data and moves +the nest IMC counter data to memory. + +The Core and Thread IMC PMU counters are handled in the core. Core level PMU +counters give us the IMC counters' data per core and thread level PMU counters +give us the IMC counters' data per CPU thread. + +OPAL obtains the IMC PMU and supported events information from the IMC Catalog +and passes on to the kernel via the device tree. The event's information +contains: + +- Event name +- Event Offset +- Event description + +and possibly also: + +- Event scale +- Event unit + +Some PMUs may have a common scale and unit values for all their supported +events. For those cases, the scale and unit properties for those events must be +inherited from the PMU. + +The event offset in the memory is where the counter data gets accumulated. + +IMC catalog is available at: + https://github.com/open-power/ima-catalog + +The kernel discovers the IMC counters information in the device tree at the +`imc-counters` device node which has a compatible field +`ibm,opal-in-memory-counters`. From the device tree, the kernel parses the PMUs +and their event's information and register the PMU and its attributes in the +kernel. + +IMC example usage +================= + +.. code-block:: sh + + # perf list + [...] + nest_mcs01/PM_MCS01_64B_RD_DISP_PORT01/ [Kernel PMU event] + nest_mcs01/PM_MCS01_64B_RD_DISP_PORT23/ [Kernel PMU event] + [...] + core_imc/CPM_0THRD_NON_IDLE_PCYC/ [Kernel PMU event] + core_imc/CPM_1THRD_NON_IDLE_INST/ [Kernel PMU event] + [...] + thread_imc/CPM_0THRD_NON_IDLE_PCYC/ [Kernel PMU event] + thread_imc/CPM_1THRD_NON_IDLE_INST/ [Kernel PMU event] + +To see per chip data for nest_mcs0/PM_MCS_DOWN_128B_DATA_XFER_MC0/: + +.. code-block:: sh + + # ./perf stat -e "nest_mcs01/PM_MCS01_64B_WR_DISP_PORT01/" -a --per-socket + +To see non-idle instructions for core 0: + +.. code-block:: sh + + # ./perf stat -e "core_imc/CPM_NON_IDLE_INST/" -C 0 -I 1000 + +To see non-idle instructions for a "make": + +.. code-block:: sh + + # ./perf stat -e "thread_imc/CPM_NON_IDLE_PCYC/" make + + +IMC Trace-mode +=============== + +POWER9 supports two modes for IMC which are the Accumulation mode and Trace +mode. In Accumulation mode, event counts are accumulated in system Memory. +Hypervisor then reads the posted counts periodically or when requested. In IMC +Trace mode, the 64 bit trace SCOM value is initialized with the event +information. The CPMCxSEL and CPMC_LOAD in the trace SCOM, specifies the event +to be monitored and the sampling duration. On each overflow in the CPMCxSEL, +hardware snapshots the program counter along with event counts and writes into +memory pointed by LDBAR. + +LDBAR is a 64 bit special purpose per thread register, it has bits to indicate +whether hardware is configured for accumulation or trace mode. + +LDBAR Register Layout +--------------------- + + +-------+----------------------+ + | 0 | Enable/Disable | + +-------+----------------------+ + | 1 | 0: Accumulation Mode | + | +----------------------+ + | | 1: Trace Mode | + +-------+----------------------+ + | 2:3 | Reserved | + +-------+----------------------+ + | 4-6 | PB scope | + +-------+----------------------+ + | 7 | Reserved | + +-------+----------------------+ + | 8:50 | Counter Address | + +-------+----------------------+ + | 51:63 | Reserved | + +-------+----------------------+ + +TRACE_IMC_SCOM bit representation +--------------------------------- + + +-------+------------+ + | 0:1 | SAMPSEL | + +-------+------------+ + | 2:33 | CPMC_LOAD | + +-------+------------+ + | 34:40 | CPMC1SEL | + +-------+------------+ + | 41:47 | CPMC2SEL | + +-------+------------+ + | 48:50 | BUFFERSIZE | + +-------+------------+ + | 51:63 | RESERVED | + +-------+------------+ + +CPMC_LOAD contains the sampling duration. SAMPSEL and CPMCxSEL determines the +event to count. BUFFERSIZE indicates the memory range. On each overflow, +hardware snapshots the program counter along with event counts and updates the +memory and reloads the CMPC_LOAD value for the next sampling duration. IMC +hardware does not support exceptions, so it quietly wraps around if memory +buffer reaches the end. + +*Currently the event monitored for trace-mode is fixed as cycle.* + +Trace IMC example usage +======================= + +.. code-block:: sh + + # perf list + [....] + trace_imc/trace_cycles/ [Kernel PMU event] + +To record an application/process with trace-imc event: + +.. code-block:: sh + + # perf record -e trace_imc/trace_cycles/ yes > /dev/null + [ perf record: Woken up 1 times to write data ] + [ perf record: Captured and wrote 0.012 MB perf.data (21 samples) ] + +The `perf.data` generated, can be read using perf report. + +Benefits of using IMC trace-mode +================================ + +PMI (Performance Monitoring Interrupts) interrupt handling is avoided, since IMC +trace mode snapshots the program counter and updates to the memory. And this +also provide a way for the operating system to do instruction sampling in real +time without PMI processing overhead. + +Performance data using `perf top` with and without trace-imc event. + +PMI interrupts count when `perf top` command is executed without trace-imc event. + +.. code-block:: sh + + # grep PMI /proc/interrupts + PMI: 0 0 0 0 Performance monitoring interrupts + # ./perf top + ... + # grep PMI /proc/interrupts + PMI: 39735 8710 17338 17801 Performance monitoring interrupts + # ./perf top -e trace_imc/trace_cycles/ + ... + # grep PMI /proc/interrupts + PMI: 39735 8710 17338 17801 Performance monitoring interrupts + + +That is, the PMI interrupt counts do not increment when using the `trace_imc` event. diff --git a/Documentation/powerpc/index.rst b/Documentation/powerpc/index.rst index ba5edb3211c0..0d45f0fc8e57 100644 --- a/Documentation/powerpc/index.rst +++ b/Documentation/powerpc/index.rst @@ -18,9 +18,11 @@ powerpc elfnote firmware-assisted-dump hvcs + imc isa-versions kaslr-booke32 mpc52xx + papr_hcalls pci_iov_resource_on_powernv pmu-ebb ptrace diff --git a/Documentation/powerpc/papr_hcalls.rst b/Documentation/powerpc/papr_hcalls.rst new file mode 100644 index 000000000000..3493631a60f8 --- /dev/null +++ b/Documentation/powerpc/papr_hcalls.rst @@ -0,0 +1,250 @@ +.. SPDX-License-Identifier: GPL-2.0 + +=========================== +Hypercall Op-codes (hcalls) +=========================== + +Overview +========= + +Virtualization on 64-bit Power Book3S Platforms is based on the PAPR +specification [1]_ which describes the run-time environment for a guest +operating system and how it should interact with the hypervisor for +privileged operations. Currently there are two PAPR compliant hypervisors: + +- **IBM PowerVM (PHYP)**: IBM's proprietary hypervisor that supports AIX, + IBM-i and Linux as supported guests (termed as Logical Partitions + or LPARS). It supports the full PAPR specification. + +- **Qemu/KVM**: Supports PPC64 linux guests running on a PPC64 linux host. + Though it only implements a subset of PAPR specification called LoPAPR [2]_. + +On PPC64 arch a guest kernel running on top of a PAPR hypervisor is called +a *pSeries guest*. A pseries guest runs in a supervisor mode (HV=0) and must +issue hypercalls to the hypervisor whenever it needs to perform an action +that is hypervisor priviledged [3]_ or for other services managed by the +hypervisor. + +Hence a Hypercall (hcall) is essentially a request by the pseries guest +asking hypervisor to perform a privileged operation on behalf of the guest. The +guest issues a with necessary input operands. The hypervisor after performing +the privilege operation returns a status code and output operands back to the +guest. + +HCALL ABI +========= +The ABI specification for a hcall between a pseries guest and PAPR hypervisor +is covered in section 14.5.3 of ref [2]_. Switch to the Hypervisor context is +done via the instruction **HVCS** that expects the Opcode for hcall is set in *r3* +and any in-arguments for the hcall are provided in registers *r4-r12*. If values +have to be passed through a memory buffer, the data stored in that buffer should be +in Big-endian byte order. + +Once control is returns back to the guest after hypervisor has serviced the +'HVCS' instruction the return value of the hcall is available in *r3* and any +out values are returned in registers *r4-r12*. Again like in case of in-arguments, +any out values stored in a memory buffer will be in Big-endian byte order. + +Powerpc arch code provides convenient wrappers named **plpar_hcall_xxx** defined +in a arch specific header [4]_ to issue hcalls from the linux kernel +running as pseries guest. + +Register Conventions +==================== + +Any hcall should follow same register convention as described in section 2.2.1.1 +of "64-Bit ELF V2 ABI Specification: Power Architecture"[5]_. Table below +summarizes these conventions: + ++----------+----------+-------------------------------------------+ +| Register |Volatile | Purpose | +| Range |(Y/N) | | ++==========+==========+===========================================+ +| r0 | Y | Optional-usage | ++----------+----------+-------------------------------------------+ +| r1 | N | Stack Pointer | ++----------+----------+-------------------------------------------+ +| r2 | N | TOC | ++----------+----------+-------------------------------------------+ +| r3 | Y | hcall opcode/return value | ++----------+----------+-------------------------------------------+ +| r4-r10 | Y | in and out values | ++----------+----------+-------------------------------------------+ +| r11 | Y | Optional-usage/Environmental pointer | ++----------+----------+-------------------------------------------+ +| r12 | Y | Optional-usage/Function entry address at | +| | | global entry point | ++----------+----------+-------------------------------------------+ +| r13 | N | Thread-Pointer | ++----------+----------+-------------------------------------------+ +| r14-r31 | N | Local Variables | ++----------+----------+-------------------------------------------+ +| LR | Y | Link Register | ++----------+----------+-------------------------------------------+ +| CTR | Y | Loop Counter | ++----------+----------+-------------------------------------------+ +| XER | Y | Fixed-point exception register. | ++----------+----------+-------------------------------------------+ +| CR0-1 | Y | Condition register fields. | ++----------+----------+-------------------------------------------+ +| CR2-4 | N | Condition register fields. | ++----------+----------+-------------------------------------------+ +| CR5-7 | Y | Condition register fields. | ++----------+----------+-------------------------------------------+ +| Others | N | | ++----------+----------+-------------------------------------------+ + +DRC & DRC Indexes +================= +:: + + DR1 Guest + +--+ +------------+ +---------+ + | | <----> | | | User | + +--+ DRC1 | | DRC | Space | + | PAPR | Index +---------+ + DR2 | Hypervisor | | | + +--+ | | <-----> | Kernel | + | | <----> | | Hcall | | + +--+ DRC2 +------------+ +---------+ + +PAPR hypervisor terms shared hardware resources like PCI devices, NVDIMMs etc +available for use by LPARs as Dynamic Resource (DR). When a DR is allocated to +an LPAR, PHYP creates a data-structure called Dynamic Resource Connector (DRC) +to manage LPAR access. An LPAR refers to a DRC via an opaque 32-bit number +called DRC-Index. The DRC-index value is provided to the LPAR via device-tree +where its present as an attribute in the device tree node associated with the +DR. + +HCALL Return-values +=================== + +After servicing the hcall, hypervisor sets the return-value in *r3* indicating +success or failure of the hcall. In case of a failure an error code indicates +the cause for error. These codes are defined and documented in arch specific +header [4]_. + +In some cases a hcall can potentially take a long time and need to be issued +multiple times in order to be completely serviced. These hcalls will usually +accept an opaque value *continue-token* within there argument list and a +return value of *H_CONTINUE* indicates that hypervisor hasn't still finished +servicing the hcall yet. + +To make such hcalls the guest need to set *continue-token == 0* for the +initial call and use the hypervisor returned value of *continue-token* +for each subsequent hcall until hypervisor returns a non *H_CONTINUE* +return value. + +HCALL Op-codes +============== + +Below is a partial list of HCALLs that are supported by PHYP. For the +corresponding opcode values please look into the arch specific header [4]_: + +**H_SCM_READ_METADATA** + +| Input: *drcIndex, offset, buffer-address, numBytesToRead* +| Out: *numBytesRead* +| Return Value: *H_Success, H_Parameter, H_P2, H_P3, H_Hardware* + +Given a DRC Index of an NVDIMM, read N-bytes from the the metadata area +associated with it, at a specified offset and copy it to provided buffer. +The metadata area stores configuration information such as label information, +bad-blocks etc. The metadata area is located out-of-band of NVDIMM storage +area hence a separate access semantics is provided. + +**H_SCM_WRITE_METADATA** + +| Input: *drcIndex, offset, data, numBytesToWrite* +| Out: *None* +| Return Value: *H_Success, H_Parameter, H_P2, H_P4, H_Hardware* + +Given a DRC Index of an NVDIMM, write N-bytes to the metadata area +associated with it, at the specified offset and from the provided buffer. + +**H_SCM_BIND_MEM** + +| Input: *drcIndex, startingScmBlockIndex, numScmBlocksToBind,* +| *targetLogicalMemoryAddress, continue-token* +| Out: *continue-token, targetLogicalMemoryAddress, numScmBlocksToBound* +| Return Value: *H_Success, H_Parameter, H_P2, H_P3, H_P4, H_Overlap,* +| *H_Too_Big, H_P5, H_Busy* + +Given a DRC-Index of an NVDIMM, map a continuous SCM blocks range +*(startingScmBlockIndex, startingScmBlockIndex+numScmBlocksToBind)* to the guest +at *targetLogicalMemoryAddress* within guest physical address space. In +case *targetLogicalMemoryAddress == 0xFFFFFFFF_FFFFFFFF* then hypervisor +assigns a target address to the guest. The HCALL can fail if the Guest has +an active PTE entry to the SCM block being bound. + +**H_SCM_UNBIND_MEM** +| Input: drcIndex, startingScmLogicalMemoryAddress, numScmBlocksToUnbind +| Out: numScmBlocksUnbound +| Return Value: *H_Success, H_Parameter, H_P2, H_P3, H_In_Use, H_Overlap,* +| *H_Busy, H_LongBusyOrder1mSec, H_LongBusyOrder10mSec* + +Given a DRC-Index of an NVDimm, unmap *numScmBlocksToUnbind* SCM blocks starting +at *startingScmLogicalMemoryAddress* from guest physical address space. The +HCALL can fail if the Guest has an active PTE entry to the SCM block being +unbound. + +**H_SCM_QUERY_BLOCK_MEM_BINDING** + +| Input: *drcIndex, scmBlockIndex* +| Out: *Guest-Physical-Address* +| Return Value: *H_Success, H_Parameter, H_P2, H_NotFound* + +Given a DRC-Index and an SCM Block index return the guest physical address to +which the SCM block is mapped to. + +**H_SCM_QUERY_LOGICAL_MEM_BINDING** + +| Input: *Guest-Physical-Address* +| Out: *drcIndex, scmBlockIndex* +| Return Value: *H_Success, H_Parameter, H_P2, H_NotFound* + +Given a guest physical address return which DRC Index and SCM block is mapped +to that address. + +**H_SCM_UNBIND_ALL** + +| Input: *scmTargetScope, drcIndex* +| Out: *None* +| Return Value: *H_Success, H_Parameter, H_P2, H_P3, H_In_Use, H_Busy,* +| *H_LongBusyOrder1mSec, H_LongBusyOrder10mSec* + +Depending on the Target scope unmap all SCM blocks belonging to all NVDIMMs +or all SCM blocks belonging to a single NVDIMM identified by its drcIndex +from the LPAR memory. + +**H_SCM_HEALTH** + +| Input: drcIndex +| Out: *health-bitmap, health-bit-valid-bitmap* +| Return Value: *H_Success, H_Parameter, H_Hardware* + +Given a DRC Index return the info on predictive failure and overall health of +the NVDIMM. The asserted bits in the health-bitmap indicate a single predictive +failure and health-bit-valid-bitmap indicate which bits in health-bitmap are +valid. + +**H_SCM_PERFORMANCE_STATS** + +| Input: drcIndex, resultBuffer Addr +| Out: None +| Return Value: *H_Success, H_Parameter, H_Unsupported, H_Hardware, H_Authority, H_Privilege* + +Given a DRC Index collect the performance statistics for NVDIMM and copy them +to the resultBuffer. + +References +========== +.. [1] "Power Architecture Platform Reference" + https://en.wikipedia.org/wiki/Power_Architecture_Platform_Reference +.. [2] "Linux on Power Architecture Platform Reference" + https://members.openpowerfoundation.org/document/dl/469 +.. [3] "Definitions and Notation" Book III-Section 14.5.3 + https://openpowerfoundation.org/?resource_lib=power-isa-version-3-0 +.. [4] arch/powerpc/include/asm/hvcall.h +.. [5] "64-Bit ELF V2 ABI Specification: Power Architecture" + https://openpowerfoundation.org/?resource_lib=64-bit-elf-v2-abi-specification-power-architecture diff --git a/Documentation/powerpc/ultravisor.rst b/Documentation/powerpc/ultravisor.rst index 730854f73830..363736d7fd36 100644 --- a/Documentation/powerpc/ultravisor.rst +++ b/Documentation/powerpc/ultravisor.rst @@ -948,6 +948,66 @@ Use cases up its internal state for this virtual machine. +H_SVM_INIT_ABORT +---------------- + + Abort the process of securing an SVM. + +Syntax +~~~~~~ + +.. code-block:: c + + uint64_t hypercall(const uint64_t H_SVM_INIT_ABORT) + +Return values +~~~~~~~~~~~~~ + + One of the following values: + + * H_PARAMETER on successfully cleaning up the state, + Hypervisor will return this value to the + **guest**, to indicate that the underlying + UV_ESM ultracall failed. + + * H_STATE if called after a VM has gone secure (i.e + H_SVM_INIT_DONE hypercall was successful). + + * H_UNSUPPORTED if called from a wrong context (e.g. from a + normal VM). + +Description +~~~~~~~~~~~ + + Abort the process of securing a virtual machine. This call must + be made after a prior call to ``H_SVM_INIT_START`` hypercall and + before a call to ``H_SVM_INIT_DONE``. + + On entry into this hypercall the non-volatile GPRs and FPRs are + expected to contain the values they had at the time the VM issued + the UV_ESM ultracall. Further ``SRR0`` is expected to contain the + address of the instruction after the ``UV_ESM`` ultracall and ``SRR1`` + the MSR value with which to return to the VM. + + This hypercall will cleanup any partial state that was established for + the VM since the prior ``H_SVM_INIT_START`` hypercall, including paging + out pages that were paged-into secure memory, and issue the + ``UV_SVM_TERMINATE`` ultracall to terminate the VM. + + After the partial state is cleaned up, control returns to the VM + (**not Ultravisor**), at the address specified in ``SRR0`` with the + MSR values set to the value in ``SRR1``. + +Use cases +~~~~~~~~~ + + If after a successful call to ``H_SVM_INIT_START``, the Ultravisor + encounters an error while securing a virtual machine, either due + to lack of resources or because the VM's security information could + not be validated, Ultravisor informs the Hypervisor about it. + Hypervisor should use this call to clean up any internal state for + this virtual machine and return to the VM. + H_SVM_PAGE_IN ------------- diff --git a/Documentation/process/changes.rst b/Documentation/process/changes.rst index 2284f2221f02..e47863575917 100644 --- a/Documentation/process/changes.rst +++ b/Documentation/process/changes.rst @@ -383,7 +383,8 @@ Mkinitrd E2fsprogs --------- -- <http://prdownloads.sourceforge.net/e2fsprogs/e2fsprogs-1.29.tar.gz> +- <https://www.kernel.org/pub/linux/kernel/people/tytso/e2fsprogs/> +- <https://git.kernel.org/pub/scm/fs/ext2/e2fsprogs.git/> JFSutils -------- @@ -393,12 +394,13 @@ JFSutils Reiserfsprogs ------------- -- <http://www.kernel.org/pub/linux/utils/fs/reiserfs/> +- <https://git.kernel.org/pub/scm/linux/kernel/git/jeffm/reiserfsprogs.git/> Xfsprogs -------- -- <ftp://oss.sgi.com/projects/xfs/> +- <https://git.kernel.org/pub/scm/fs/xfs/xfsprogs-dev.git> +- <https://www.kernel.org/pub/linux/utils/fs/xfs/xfsprogs/> Pcmciautils ----------- @@ -437,7 +439,9 @@ Networking PPP --- -- <ftp://ftp.samba.org/pub/ppp/> +- <https://download.samba.org/pub/ppp/> +- <https://git.ozlabs.org/?p=ppp.git> +- <https://github.com/paulusmack/ppp/> NFS-utils --------- @@ -447,7 +451,7 @@ NFS-utils Iptables -------- -- <http://www.iptables.org/downloads.html> +- <https://netfilter.org/projects/iptables/index.html> Ip-route2 --------- diff --git a/Documentation/process/embargoed-hardware-issues.rst b/Documentation/process/embargoed-hardware-issues.rst index 799580acc8de..a19d084f9b2c 100644 --- a/Documentation/process/embargoed-hardware-issues.rst +++ b/Documentation/process/embargoed-hardware-issues.rst @@ -1,3 +1,5 @@ +.. _embargoed_hardware_issues: + Embargoed hardware issues ========================= @@ -36,7 +38,10 @@ issue according to our documented process. The list is encrypted and email to the list can be sent by either PGP or S/MIME encrypted and must be signed with the reporter's PGP key or S/MIME certificate. The list's PGP key and S/MIME certificate are available from -https://www.kernel.org/.... +the following URLs: + + - PGP: https://www.kernel.org/static/files/hardware-security.asc + - S/MIME: https://www.kernel.org/static/files/hardware-security.crt While hardware security issues are often handled by the affected hardware vendor, we welcome contact from researchers or individuals who have @@ -55,14 +60,14 @@ Operation of mailing-lists ^^^^^^^^^^^^^^^^^^^^^^^^^^ The encrypted mailing-lists which are used in our process are hosted on -Linux Foundation's IT infrastructure. By providing this service Linux -Foundation's director of IT Infrastructure security technically has the -ability to access the embargoed information, but is obliged to -confidentiality by his employment contract. Linux Foundation's director of -IT Infrastructure security is also responsible for the kernel.org -infrastructure. - -The Linux Foundation's current director of IT Infrastructure security is +Linux Foundation's IT infrastructure. By providing this service, members +of Linux Foundation's IT operations personnel technically have the +ability to access the embargoed information, but are obliged to +confidentiality by their employment contract. Linux Foundation IT +personnel are also responsible for operating and managing the rest of +kernel.org infrastructure. + +The Linux Foundation's current director of IT Project infrastructure is Konstantin Ryabitsev. @@ -239,17 +244,17 @@ disclosure of a particular issue, unless requested by a response team or by an involved disclosed party. The current ambassadors list: ============= ======================================================== - ARM + ARM Grant Likely <grant.likely@arm.com> AMD Tom Lendacky <tom.lendacky@amd.com> IBM Intel Tony Luck <tony.luck@intel.com> Qualcomm Trilok Soni <tsoni@codeaurora.org> - Microsoft Sasha Levin <sashal@kernel.org> + Microsoft James Morris <jamorris@linux.microsoft.com> VMware Xen Andrew Cooper <andrew.cooper3@citrix.com> - Canonical Tyler Hicks <tyhicks@canonical.com> + Canonical John Johansen <john.johansen@canonical.com> Debian Ben Hutchings <ben@decadent.org.uk> Oracle Konrad Rzeszutek Wilk <konrad.wilk@oracle.com> Red Hat Josh Poimboeuf <jpoimboe@redhat.com> @@ -274,7 +279,7 @@ software decrypts the email and re-encrypts it individually for each subscriber with the subscriber's PGP key or S/MIME certificate. Details about the mailing-list software and the setup which is used to ensure the security of the lists and protection of the data can be found here: -https://www.kernel.org/.... +https://korg.wiki.kernel.org/userdoc/remail. List keys ^^^^^^^^^ diff --git a/Documentation/riscv/boot-image-header.rst b/Documentation/riscv/boot-image-header.rst index 518d46d2389d..d7752533865f 100644 --- a/Documentation/riscv/boot-image-header.rst +++ b/Documentation/riscv/boot-image-header.rst @@ -22,7 +22,7 @@ The following 64-byte header is present in decompressed Linux kernel image:: u64 res2 = 0; /* Reserved */ u64 magic = 0x5643534952; /* Magic number, little endian, "RISCV" */ u32 magic2 = 0x05435352; /* Magic number 2, little endian, "RSC\x05" */ - u32 res4; /* Reserved for PE COFF offset */ + u32 res3; /* Reserved for PE COFF offset */ This header format is compliant with PE/COFF header and largely inspired from ARM64 header. Thus, both ARM64 & RISC-V header can be combined into one common @@ -34,7 +34,7 @@ Notes - This header can also be reused to support EFI stub for RISC-V in future. EFI specification needs PE/COFF image header in the beginning of the kernel image in order to load it as an EFI application. In order to support EFI stub, - code0 should be replaced with "MZ" magic string and res5(at offset 0x3c) should + code0 should be replaced with "MZ" magic string and res3(at offset 0x3c) should point to the rest of the PE/COFF header. - version field indicate header version number diff --git a/Documentation/sound/alsa-configuration.rst b/Documentation/sound/alsa-configuration.rst index 02aacd69ab96..392875a1b94e 100644 --- a/Documentation/sound/alsa-configuration.rst +++ b/Documentation/sound/alsa-configuration.rst @@ -495,7 +495,8 @@ Module for C-Media CMI8338/8738/8768/8770 PCI sound cards. mpu_port port address of MIDI interface (8338 only): 0x300,0x310,0x320,0x330 = legacy port, - 0 = disable (default) + 1 = integrated PCI port (default on 8738), + 0 = disable fm_port port address of OPL-3 FM synthesizer (8x38 only): 0x388 = legacy port, diff --git a/Documentation/sound/kernel-api/writing-an-alsa-driver.rst b/Documentation/sound/kernel-api/writing-an-alsa-driver.rst index f169d58ca019..fa4968817696 100644 --- a/Documentation/sound/kernel-api/writing-an-alsa-driver.rst +++ b/Documentation/sound/kernel-api/writing-an-alsa-driver.rst @@ -259,7 +259,7 @@ to details explained in the following section. { struct mychip *chip; int err; - static struct snd_device_ops ops = { + static const struct snd_device_ops ops = { .dev_free = snd_mychip_dev_free, }; @@ -675,7 +675,7 @@ low-level device with a specified ``ops``, :: - static struct snd_device_ops ops = { + static const struct snd_device_ops ops = { .dev_free = snd_mychip_dev_free, }; .... @@ -761,7 +761,7 @@ destructor and PCI entries. Example code is shown first, below. { struct mychip *chip; int err; - static struct snd_device_ops ops = { + static const struct snd_device_ops ops = { .dev_free = snd_mychip_dev_free, }; @@ -1058,7 +1058,7 @@ and the allocation would be like below: return err; } chip->iobase_phys = pci_resource_start(pci, 0); - chip->iobase_virt = ioremap_nocache(chip->iobase_phys, + chip->iobase_virt = ioremap(chip->iobase_phys, pci_resource_len(pci, 0)); and the corresponding destructor would be: @@ -3912,7 +3912,7 @@ For a raw-data proc-file, set the attributes as follows: :: - static struct snd_info_entry_ops my_file_io_ops = { + static const struct snd_info_entry_ops my_file_io_ops = { .read = my_file_io_read, }; diff --git a/Documentation/sphinx/automarkup.py b/Documentation/sphinx/automarkup.py index 5b6119ff69f4..b18236370742 100644 --- a/Documentation/sphinx/automarkup.py +++ b/Documentation/sphinx/automarkup.py @@ -5,8 +5,13 @@ # has been done. # from docutils import nodes +import sphinx from sphinx import addnodes -from sphinx.environment import NoUri +if sphinx.version_info[0] < 2 or \ + sphinx.version_info[0] == 2 and sphinx.version_info[1] < 1: + from sphinx.environment import NoUri +else: + from sphinx.errors import NoUri import re # diff --git a/Documentation/tee.txt b/Documentation/tee.txt index afacdf2fd1de..c8fad81c4563 100644 --- a/Documentation/tee.txt +++ b/Documentation/tee.txt @@ -112,6 +112,83 @@ kernel are handled by the kernel driver. Other RPC messages will be forwarded to tee-supplicant without further involvement of the driver, except switching shared memory buffer representation. +AMD-TEE driver +============== + +The AMD-TEE driver handles the communication with AMD's TEE environment. The +TEE environment is provided by AMD Secure Processor. + +The AMD Secure Processor (formerly called Platform Security Processor or PSP) +is a dedicated processor that features ARM TrustZone technology, along with a +software-based Trusted Execution Environment (TEE) designed to enable +third-party Trusted Applications. This feature is currently enabled only for +APUs. + +The following picture shows a high level overview of AMD-TEE:: + + | + x86 | + | + User space (Kernel space) | AMD Secure Processor (PSP) + ~~~~~~~~~~ ~~~~~~~~~~~~~~ | ~~~~~~~~~~~~~~~~~~~~~~~~~~ + | + +--------+ | +-------------+ + | Client | | | Trusted | + +--------+ | | Application | + /\ | +-------------+ + || | /\ + || | || + || | \/ + || | +----------+ + || | | TEE | + || | | Internal | + \/ | | API | + +---------+ +-----------+---------+ +----------+ + | TEE | | TEE | AMD-TEE | | AMD-TEE | + | Client | | subsystem | driver | | Trusted | + | API | | | | | OS | + +---------+-----------+----+------+---------+---------+----------+ + | Generic TEE API | | ASP | Mailbox | + | IOCTL (TEE_IOC_*) | | driver | Register Protocol | + +--------------------------+ +---------+--------------------+ + +At the lowest level (in x86), the AMD Secure Processor (ASP) driver uses the +CPU to PSP mailbox regsister to submit commands to the PSP. The format of the +command buffer is opaque to the ASP driver. It's role is to submit commands to +the secure processor and return results to AMD-TEE driver. The interface +between AMD-TEE driver and AMD Secure Processor driver can be found in [6]. + +The AMD-TEE driver packages the command buffer payload for processing in TEE. +The command buffer format for the different TEE commands can be found in [7]. + +The TEE commands supported by AMD-TEE Trusted OS are: +* TEE_CMD_ID_LOAD_TA - loads a Trusted Application (TA) binary into + TEE environment. +* TEE_CMD_ID_UNLOAD_TA - unloads TA binary from TEE environment. +* TEE_CMD_ID_OPEN_SESSION - opens a session with a loaded TA. +* TEE_CMD_ID_CLOSE_SESSION - closes session with loaded TA +* TEE_CMD_ID_INVOKE_CMD - invokes a command with loaded TA +* TEE_CMD_ID_MAP_SHARED_MEM - maps shared memory +* TEE_CMD_ID_UNMAP_SHARED_MEM - unmaps shared memory + +AMD-TEE Trusted OS is the firmware running on AMD Secure Processor. + +The AMD-TEE driver registers itself with TEE subsystem and implements the +following driver function callbacks: + +* get_version - returns the driver implementation id and capability. +* open - sets up the driver context data structure. +* release - frees up driver resources. +* open_session - loads the TA binary and opens session with loaded TA. +* close_session - closes session with loaded TA and unloads it. +* invoke_func - invokes a command with loaded TA. + +cancel_req driver callback is not supported by AMD-TEE. + +The GlobalPlatform TEE Client API [5] can be used by the user space (client) to +talk to AMD's TEE. AMD's TEE provides a secure environment for loading, opening +a session, invoking commands and clossing session with TA. + References ========== @@ -125,3 +202,7 @@ References [5] http://www.globalplatform.org/specificationsdevice.asp look for "TEE Client API Specification v1.0" and click download. + +[6] include/linux/psp-tee.h + +[7] drivers/tee/amdtee/amdtee_if.h diff --git a/Documentation/trace/ftrace.rst b/Documentation/trace/ftrace.rst index d2b5657ed33e..ff658e27d25b 100644 --- a/Documentation/trace/ftrace.rst +++ b/Documentation/trace/ftrace.rst @@ -95,7 +95,8 @@ of ftrace. Here is a list of some of the key files: current_tracer: This is used to set or display the current tracer - that is configured. + that is configured. Changing the current tracer clears + the ring buffer content as well as the "snapshot" buffer. available_tracers: @@ -126,7 +127,8 @@ of ftrace. Here is a list of some of the key files: This file holds the output of the trace in a human readable format (described below). Note, tracing is temporarily disabled when the file is open for reading. Once all readers - are closed, tracing is re-enabled. + are closed, tracing is re-enabled. Opening this file for + writing with the O_TRUNC flag clears the ring buffer content. trace_pipe: @@ -185,7 +187,8 @@ of ftrace. Here is a list of some of the key files: CPU buffer and not total size of all buffers. The trace buffers are allocated in pages (blocks of memory that the kernel uses for allocation, usually 4 KB in size). - If the last page allocated has room for more bytes + A few extra pages may be allocated to accommodate buffer management + meta-data. If the last page allocated has room for more bytes than requested, the rest of the page will be used, making the actual allocation bigger than requested or shown. ( Note, the size may not be a multiple of the page size @@ -235,7 +238,7 @@ of ftrace. Here is a list of some of the key files: This interface also allows for commands to be used. See the "Filter commands" section for more details. - As a speed up, since processing strings can't be quite expensive + As a speed up, since processing strings can be quite expensive and requires a check of all functions registered to tracing, instead an index can be written into this file. A number (starting with "1") written will instead select the same corresponding at the line position @@ -382,7 +385,7 @@ of ftrace. Here is a list of some of the key files: By default, 128 comms are saved (see "saved_cmdlines" above). To increase or decrease the amount of comms that are cached, echo - in a the number of comms to cache, into this file. + the number of comms to cache into this file. saved_tgids: @@ -490,6 +493,9 @@ of ftrace. Here is a list of some of the key files: # echo global > trace_clock + Setting a clock clears the ring buffer content as well as the + "snapshot" buffer. + trace_marker: This is a very useful file for synchronizing user space @@ -3324,7 +3330,7 @@ directories after it is created. As you can see, the new directory looks similar to the tracing directory itself. In fact, it is very similar, except that the buffer and -events are agnostic from the main director, or from any other +events are agnostic from the main directory, or from any other instances that are created. The files in the new directory work just like the files with the diff --git a/Documentation/trace/kprobetrace.rst b/Documentation/trace/kprobetrace.rst index 705d73087099..cc4c5fc313df 100644 --- a/Documentation/trace/kprobetrace.rst +++ b/Documentation/trace/kprobetrace.rst @@ -253,4 +253,3 @@ And you can see the traced information via /sys/kernel/debug/tracing/trace. Each line shows when the kernel hits an event, and <- SYMBOL means kernel returns from SYMBOL(e.g. "sys_open+0x1b/0x1d <- do_sys_open" means kernel returns from do_sys_open to sys_open+0x1b). - diff --git a/Documentation/trace/ring-buffer-design.txt b/Documentation/trace/ring-buffer-design.txt index ff747b6fa39b..2d53c6f25b91 100644 --- a/Documentation/trace/ring-buffer-design.txt +++ b/Documentation/trace/ring-buffer-design.txt @@ -37,7 +37,7 @@ commit_page - a pointer to the page with the last finished non-nested write. cmpxchg - hardware-assisted atomic transaction that performs the following: - A = B iff previous A == C + A = B if previous A == C R = cmpxchg(A, C, B) is saying that we replace A with B if and only if current A is equal to C, and we put the old (current) A into R diff --git a/Documentation/translations/it_IT/process/changes.rst b/Documentation/translations/it_IT/process/changes.rst index 94a6499742ac..37da4447a40d 100644 --- a/Documentation/translations/it_IT/process/changes.rst +++ b/Documentation/translations/it_IT/process/changes.rst @@ -390,7 +390,8 @@ Mkinitrd E2fsprogs --------- -- <http://prdownloads.sourceforge.net/e2fsprogs/e2fsprogs-1.29.tar.gz> +- <https://www.kernel.org/pub/linux/kernel/people/tytso/e2fsprogs/> +- <https://git.kernel.org/pub/scm/fs/ext2/e2fsprogs.git/> JFSutils -------- @@ -400,12 +401,13 @@ JFSutils Reiserfsprogs ------------- -- <http://www.kernel.org/pub/linux/utils/fs/reiserfs/> +- <https://git.kernel.org/pub/scm/linux/kernel/git/jeffm/reiserfsprogs.git/> Xfsprogs -------- -- <ftp://oss.sgi.com/projects/xfs/> +- <https://git.kernel.org/pub/scm/fs/xfs/xfsprogs-dev.git> +- <https://www.kernel.org/pub/linux/utils/fs/xfs/xfsprogs/> Pcmciautils ----------- @@ -444,7 +446,9 @@ Rete PPP --- -- <ftp://ftp.samba.org/pub/ppp/> +- <https://download.samba.org/pub/ppp/> +- <https://git.ozlabs.org/?p=ppp.git> +- <https://github.com/paulusmack/ppp/> NFS-utils @@ -455,7 +459,7 @@ NFS-utils Iptables -------- -- <http://www.iptables.org/downloads.html> +- <https://netfilter.org/projects/iptables/index.html> Ip-route2 --------- diff --git a/Documentation/translations/ko_KR/howto.rst b/Documentation/translations/ko_KR/howto.rst index ae3ad897d2ae..71d4823e41e1 100644 --- a/Documentation/translations/ko_KR/howto.rst +++ b/Documentation/translations/ko_KR/howto.rst @@ -318,8 +318,8 @@ Andrew Mortonì˜ ê¸€ì´ ìžˆë‹¤. 리뷰 프로세스는 patchworkë¼ëŠ” ë„구를 통해 추ì ëœë‹¤. patchworkì€ ë“±ë¡ëœ 패치와 íŒ¨ì¹˜ì— ëŒ€í•œ 코멘트, íŒ¨ì¹˜ì˜ ë²„ì „ì„ ë³¼ 수 있는 웹 ì¸í„°íŽ˜ì´ìŠ¤ë¥¼ ì œê³µí•˜ê³ , ë©”ì¸í…Œì´ë„ˆëŠ” 패치를 리뷰 중, 리뷰 통과, ë˜ëŠ” ë°˜ë ¤ë¨ìœ¼ë¡œ í‘œì‹œí• ìˆ˜ 있다. -ëŒ€ë¶€ë¶„ì˜ ì´ëŸ¬í•œ patchwork 사ì´íŠ¸ëŠ” https://patchwork.kernel.org/ ë˜ëŠ” -http://patchwork.ozlabs.org/ ì— ë‚˜ì—´ë˜ì–´ 있다. +ëŒ€ë¶€ë¶„ì˜ ì´ëŸ¬í•œ patchwork 사ì´íŠ¸ëŠ” https://patchwork.kernel.org/ ì— ë‚˜ì—´ë˜ì–´ +있다. 통합 테스트를 위한 linux-next ì»¤ë„ íŠ¸ë¦¬ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -328,7 +328,7 @@ http://patchwork.ozlabs.org/ ì— ë‚˜ì—´ë˜ì–´ 있다. ê±°ì³ì•¼ 한다. ì´ëŸ° 목ì 으로, ëª¨ë“ ì„œë¸Œì‹œìŠ¤í…œ íŠ¸ë¦¬ì˜ ë³€ê²½ì‚¬í•ì„ ê±°ì˜ ë§¤ì¼ ë°›ì•„ê°€ëŠ” 특수한 테스트 ì €ìž¥ì†Œê°€ 존재한다: - https://git.kernel.org/?p=linux/kernel/git/sfr/linux-next.git + https://git.kernel.org/?p=linux/kernel/git/next/linux-next.git ì´ëŸ° ì‹ìœ¼ë¡œ, linux-next 커ë„ì„ í†µí•´ ë‹¤ìŒ ë¨¸ì§€ ê¸°ê°„ì— ë©”ì¸ë¼ì¸ 커ë„ì— ì–´ë–¤ ë³€ê²½ì´ ê°€í•´ì§ˆ 것ì¸ì§€ 간략히 ì•Œ 수 있다. 모험심 ê°•í•œ 테스터ë¼ë©´ linux-next diff --git a/Documentation/translations/ko_KR/memory-barriers.txt b/Documentation/translations/ko_KR/memory-barriers.txt index f07c40a068b5..2e831ece6e26 100644 --- a/Documentation/translations/ko_KR/memory-barriers.txt +++ b/Documentation/translations/ko_KR/memory-barriers.txt @@ -2413,7 +2413,7 @@ _않습니다_. ì•Œê³ ìžˆëŠ”, - inb() 나 writel() ê³¼ ê°™ì€ - ì ì ˆí•œ 액세스 ë£¨í‹´ì„ í†µí•´ ì´ë£¨ì–´ì ¸ì•¼ë§Œ 합니다. ì´ê²ƒë“¤ì€ ëŒ€ë¶€ë¶„ì˜ ê²½ìš°ì—는 명시ì 메모리 배리어 와 함께 사용ë 필요가 없습니다만, ì™„í™”ëœ ë©”ëª¨ë¦¬ 액세스 ì†ì„±ìœ¼ë¡œ I/O 메모리 윈ë„ìš°ë¡œì˜ ì°¸ì¡°ë¥¼ 위해 -액세스 함수가 사용ëœë‹¤ë©´ 순서를 ê°•ì œí•˜ê¸° 위해 _madatory_ 메모리 배리어가 +액세스 함수가 사용ëœë‹¤ë©´ 순서를 ê°•ì œí•˜ê¸° 위해 _mandatory_ 메모리 배리어가 필요합니다. ë” ë§Žì€ ì •ë³´ë¥¼ ìœ„í•´ì„ Documentation/driver-api/device-io.rst 를 ì°¸ê³ í•˜ì‹ì‹œì˜¤. @@ -2528,7 +2528,7 @@ I/O 액세스를 통한 ì£¼ë³€ìž¥ì¹˜ì™€ì˜ í†µì‹ ì€ ì•„í‚¤í…ì³ì™€ ê¸°ê¸°ì— ë ì´ê²ƒë“¤ì€ readX() 와 writeX() ëž‘ 비슷하지만, ë” ì™„í™”ëœ ë©”ëª¨ë¦¬ 순서 ë³´ìž¥ì„ ì œê³µí•©ë‹ˆë‹¤. 구체ì 으로, ì´ê²ƒë“¤ì€ ì¼ë°˜ì 메모리 액세스나 delay() 루프 (예:ì•žì˜ 2-5 í•ëª©) ì— ëŒ€í•´ 순서를 보장하지 않습니다만 ë””í´íŠ¸ I/O - 기능으로 ë§¤í•‘ëœ __iomem í¬ì¸í„°ì— 대해 ë™ìž‘í• ë•Œ, ê°™ì€ CPU ì“°ë ˆë“œì— ì˜í•´ + 기능으로 ë§¤í•‘ëœ __iomem í¬ì¸í„°ì— 대해 ë™ìž‘í• ë•Œ, ê°™ì€ CPU ì“°ë ˆë“œì— ì˜í•œ ê°™ì€ ì£¼ë³€ìž¥ì¹˜ë¡œì˜ ì•¡ì„¸ìŠ¤ì—는 순서가 맞춰질 ê²ƒì´ ë³´ìž¥ë©ë‹ˆë‹¤. (*) readsX(), writesX(): diff --git a/Documentation/translations/zh_CN/process/embargoed-hardware-issues.rst b/Documentation/translations/zh_CN/process/embargoed-hardware-issues.rst new file mode 100644 index 000000000000..88273ebe7823 --- /dev/null +++ b/Documentation/translations/zh_CN/process/embargoed-hardware-issues.rst @@ -0,0 +1,228 @@ +.. include:: ../disclaimer-zh_CN.rst + +:Original: :ref:`Documentation/process/embargoed-hardware-issues.rst <embargoed_hardware_issues>` +:Translator: Alex Shi <alex.shi@linux.alibaba.com> + +被é™åˆ¶çš„硬件问题 +================ + +范围 +---- + +导致安全问题的硬件问题与åªå½±å“Linuxå†…æ ¸çš„çº¯è½¯ä»¶é”™è¯¯æ˜¯ä¸åŒçš„安全错误类别。 + +必须区别对待诸如熔æ¯(Meltdown)ã€Spectreã€L1TFç‰ç¡¬ä»¶é—®é¢˜ï¼Œå› ä¸ºå®ƒä»¬é€šå¸¸ä¼šå½±å“ +所有æ“作系统（“OSâ€ï¼‰ï¼Œå› æ¤éœ€è¦åœ¨ä¸åŒçš„OS供应商ã€å‘行版ã€ç¡¬ä»¶ä¾›åº”商和其他å„æ–¹ +之间进行å调。对于æŸäº›é—®é¢˜ï¼Œè½¯ä»¶ç¼“解å¯èƒ½ä¾èµ–于微ç 或固件更新，这需è¦è¿›ä¸€æ¥çš„ +å调。 + +.. _zh_Contact: + +接触 +---- + +Linuxå†…æ ¸ç¡¬ä»¶å®‰å…¨å°ç»„独立于普通的Linuxå†…æ ¸å®‰å…¨å°ç»„。 + +该å°ç»„åªè´Ÿè´£å调被é™åˆ¶çš„硬件安全问题。Linuxå†…æ ¸ä¸çº¯è½¯ä»¶å®‰å…¨æ¼æ´žçš„报告ä¸ç”±è¯¥ +å°ç»„处ç†ï¼ŒæŠ¥å‘Šè€…将被引导至常规Linuxå†…æ ¸å®‰å…¨å°ç»„(:ref:`Documentation/admin-guide/ +<securitybugs>`)è”系。 + +å¯ä»¥é€šè¿‡ç”µå邮件 <hardware-security@kernel.org> 与å°ç»„è”系。这是一份ç§å¯†çš„安全 +官åå•ï¼Œä»–ä»¬å°†å¸®åŠ©æ‚¨æ ¹æ®æˆ‘们的文档化æµç¨‹å调问题。 + +é‚®ä»¶åˆ—è¡¨æ˜¯åŠ å¯†çš„ï¼Œå‘é€åˆ°åˆ—表的电å邮件å¯ä»¥é€šè¿‡PGP或S/MIMEåŠ å¯†ï¼Œå¹¶ä¸”å¿…é¡»ä½¿ç”¨æŠ¥å‘Š +者的PGP密钥或S/MIMEè¯ä¹¦ç¾å。该列表的PGP密钥和S/MIMEè¯ä¹¦å¯ä»Ž +https://www.kernel.org/.... 获得。 + +虽然硬件安全问题通常由å—å½±å“的硬件供应商处ç†ï¼Œä½†æˆ‘们欢迎å‘çŽ°æ½œåœ¨ç¡¬ä»¶ç¼ºé™·çš„ç ”ç©¶ +人员或个人与我们è”系。 + +硬件安全官 +^^^^^^^^^^ + +ç›®å‰çš„硬件安全官å°ç»„: + + - Linus Torvalds（Linux基金会院士） + - Greg Kroah Hartman（Linux基金会院士） + - Thomas Gleixner（Linux基金会院士） + +邮件列表的æ“作 +^^^^^^^^^^^^^^ + +处ç†æµç¨‹ä¸ä½¿ç”¨çš„åŠ å¯†é‚®ä»¶åˆ—è¡¨æ‰˜ç®¡åœ¨Linux Foundationçš„IT基础设施上。通过æ供这项 +æœåŠ¡ï¼ŒLinux基金会的IT基础设施安全总监在技术上有能力访问被é™åˆ¶çš„ä¿¡æ¯ï¼Œä½†æ ¹æ®ä»– +的雇佣åˆåŒï¼Œä»–å¿…é¡»ä¿å¯†ã€‚Linux基金会的IT基础设施安全总监还负责 kernel.org 基础 +设施。 + +Linux基金会目å‰çš„IT基础设施安全总监是 Konstantin Ryabitsev。 + +ä¿å¯†åè®® +-------- + +Linuxå†…æ ¸ç¡¬ä»¶å®‰å…¨å°ç»„ä¸æ˜¯æ£å¼çš„æœºæž„ï¼Œå› æ¤æ— 法ç¾è®¢ä»»ä½•ä¿å¯†åè®®ã€‚æ ¸å¿ƒç¤¾åŒºæ„识到 +这些问题的æ•æ„Ÿæ€§ï¼Œå¹¶æ供了一份谅解备忘录。 + +谅解备忘录 +---------- + +Linuxå†…æ ¸ç¤¾åŒºæ·±åˆ»ç†è§£åœ¨ä¸åŒæ“作系统供应商ã€å‘行商ã€ç¡¬ä»¶ä¾›åº”商和其他å„方之间 +进行å调时，ä¿æŒç¡¬ä»¶å®‰å…¨é—®é¢˜å¤„于é™åˆ¶çŠ¶æ€çš„è¦æ±‚。 + +Linuxå†…æ ¸ç¤¾åŒºåœ¨è¿‡åŽ»å·²ç»æˆåŠŸåœ°å¤„ç†äº†ç¡¬ä»¶å®‰å…¨é—®é¢˜ï¼Œå¹¶ä¸”有必è¦çš„机制å…许在é™åˆ¶ +é™åˆ¶ä¸‹è¿›è¡Œç¬¦åˆç¤¾åŒºçš„å¼€å‘。 + +Linuxå†…æ ¸ç¤¾åŒºæœ‰ä¸€ä¸ªä¸“é—¨çš„ç¡¬ä»¶å®‰å…¨å°ç»„è´Ÿè´£åˆå§‹è”系，并监ç£åœ¨é™åˆ¶è§„åˆ™ä¸‹å¤„ç† +æ¤ç±»é—®é¢˜çš„过程。 + +硬件安全å°ç»„确定开å‘人员（领域专家），他们将组æˆç‰¹å®šé—®é¢˜çš„åˆå§‹å“应å°ç»„ã€‚æœ€åˆ +çš„å“应å°ç»„å¯ä»¥å¼•å…¥æ›´å¤šçš„å¼€å‘人员（领域专家）以最佳的技术方å¼è§£å†³è¿™ä¸ªé—®é¢˜ã€‚ + +所有相关开å‘商承诺éµå®ˆé™åˆ¶è§„定，并对收到的信æ¯ä¿å¯†ã€‚è¿å承诺将导致立å³ä»Žå½“å‰ +问题ä¸æŽ’除，并从所有相关邮件列表ä¸åˆ 除。æ¤å¤–，硬件安全å°ç»„还将把è¿å者排除在 +未æ¥çš„问题之外。这一åŽæžœçš„å½±å“在我们社区是一ç§éžå¸¸æœ‰æ•ˆçš„å¨æ…‘。如果å‘生è¿è§„ +情况，硬件安全å°ç»„将立å³é€šçŸ¥ç›¸å…³æ–¹ã€‚如果您或任何人å‘现潜在的è¿è§„è¡Œä¸ºï¼Œè¯·ç«‹å³ +å‘硬件安全人员报告。 + +æµç¨‹ +^^^^ + +由于Linuxå†…æ ¸å¼€å‘çš„å…¨çƒåˆ†å¸ƒå¼ç‰¹æ€§ï¼Œé¢å¯¹é¢çš„ä¼šè®®å‡ ä¹Žä¸å¯èƒ½è§£å†³ç¡¬ä»¶å®‰å…¨é—®é¢˜ã€‚ +ç”±äºŽæ—¶åŒºå’Œå…¶ä»–å› ç´ ï¼Œç”µè¯ä¼šè®®å¾ˆéš¾å调，åªèƒ½åœ¨ç»å¯¹å¿…è¦æ—¶ä½¿ç”¨ã€‚åŠ å¯†ç”µå邮件已被 +è¯æ˜Žæ˜¯è§£å†³æ¤ç±»é—®é¢˜çš„最有效和最安全的通信方法。 + +开始披露 +"""""""" + +披露内容首先通过电å邮件è”ç³»Linuxå†…æ ¸ç¡¬ä»¶å®‰å…¨å°ç»„。æ¤åˆå§‹è”系人应包å«é—®é¢˜çš„ +æ述和任何已知å—å½±å“ç¡¬ä»¶çš„åˆ—è¡¨ã€‚å¦‚æžœæ‚¨çš„ç»„ç»‡åˆ¶é€ æˆ–åˆ†å‘å—å½±å“的硬件，我们建议 +您也考虑哪些其他硬件å¯èƒ½ä¼šå—到影å“。 + +硬件安全å°ç»„å°†æä¾›ä¸€ä¸ªç‰¹å®šäºŽäº‹ä»¶çš„åŠ å¯†é‚®ä»¶åˆ—è¡¨ï¼Œç”¨äºŽä¸ŽæŠ¥å‘Šè€…è¿›è¡Œåˆæ¥è®¨è®ºã€ +进一æ¥æŠ«éœ²å’Œå调。 + +硬件安全å°ç»„å°†å‘披露方æ供一份开å‘人员（领域专家）åå•ï¼Œåœ¨ä¸Žå¼€å‘人员确认他们 +å°†éµå®ˆæœ¬è°…解备忘录和文件化æµç¨‹åŽï¼Œåº”首先告知开å‘人员有关该问题的信æ¯ã€‚è¿™äº›å¼€å‘ +人员组æˆåˆå§‹å“应å°ç»„，并在åˆå§‹æŽ¥è§¦åŽè´Ÿè´£å¤„ç†é—®é¢˜ã€‚硬件安全å°ç»„支æŒå“应å°ç»„， +但ä¸ä¸€å®šå‚与缓解开å‘过程。 + +虽然个别开å‘人员å¯èƒ½é€šè¿‡å…¶é›‡ä¸»å—到ä¿å¯†å议的ä¿æŠ¤ï¼Œä½†ä»–们ä¸èƒ½ä»¥Linuxå†…æ ¸å¼€å‘ +人员的身份ç¾è®¢ä¸ªåˆ«ä¿å¯†å议。但是，他们将åŒæ„éµå®ˆè¿™ä¸€ä¹¦é¢ç¨‹åºå’Œè°…解备忘录。 + +披露方应æ供已ç»æˆ–应该被告知该问题的所有其他实体的è”系人åå•ã€‚è¿™æœ‰å‡ ä¸ªç›®çš„: + + - 披露的实体列表å…许跨行业通信，例如其他æ“作系统供应商ã€ç¡¬ä»¶ä¾›åº”商ç‰ã€‚ + + - å¯è”系已披露的实体，指定应å‚与缓解措施开å‘的专家。 + + - 如果需è¦å¤„ç†æŸä¸€é—®é¢˜çš„专家å—雇于æŸä¸€ä¸Šå¸‚实体或æŸä¸€ä¸Šå¸‚实体的æˆå‘˜ï¼Œåˆ™å“应 + å°ç»„å¯è¦æ±‚该实体披露该专家。这确ä¿ä¸“家也是实体å应å°ç»„的一部分。 + +披露 +"""" + +æŠ«éœ²æ–¹é€šè¿‡ç‰¹å®šçš„åŠ å¯†é‚®ä»¶åˆ—è¡¨å‘åˆå§‹å“应å°ç»„æ供详细信æ¯ã€‚ + +æ ¹æ®æˆ‘们的ç»éªŒï¼Œè¿™äº›é—®é¢˜çš„技术文档通常是一个足够的起点，最好通过电å邮件进行 +进一æ¥çš„技术澄清。 + +ç¼“è§£å¼€å‘ +"""""""" + +åˆå§‹å“应å°ç»„è®¾ç½®åŠ å¯†é‚®ä»¶åˆ—è¡¨ï¼Œæˆ–åœ¨é€‚å½“çš„æƒ…å†µä¸‹é‡æ–°ä¿®æ”¹çŽ°æœ‰é‚®ä»¶åˆ—表。 + +使用邮件列表接近于æ£å¸¸çš„Linuxå¼€å‘过程，并且在过去已ç»æˆåŠŸåœ°ç”¨äºŽä¸ºå„ç§ç¡¬ä»¶å®‰å…¨ +问题开å‘缓解措施。 + +邮件列表的æ“作方å¼ä¸Žæ£å¸¸çš„Linuxå¼€å‘相åŒã€‚å‘布ã€è®¨è®ºå’Œå®¡æŸ¥ä¿®è¡¥ç¨‹åºï¼Œå¦‚æžœåŒæ„， +则应用于éžå…¬å…±gitå˜å‚¨åº“，å‚与开å‘人员åªèƒ½é€šè¿‡å®‰å…¨è¿žæŽ¥è®¿é—®è¯¥å˜å‚¨åº“。å˜å‚¨åº“åŒ…å« +é’ˆå¯¹ä¸»çº¿å†…æ ¸çš„ä¸»å¼€å‘åˆ†æ”¯ï¼Œå¹¶æ ¹æ®éœ€è¦ä¸ºç¨³å®šçš„å†…æ ¸ç‰ˆæœ¬æä¾›å‘åŽç§»æ¤åˆ†æ”¯ã€‚ + +最åˆçš„å“应å°ç»„å°†æ ¹æ®éœ€è¦ä»ŽLinuxå†…æ ¸å¼€å‘人员社区ä¸ç¡®å®šæ›´å¤šçš„专家。引进专家å¯ä»¥ +在开å‘过程ä¸çš„任何时候å‘生，需è¦åŠæ—¶å¤„ç†ã€‚ + +如果专家å—雇于披露方æ供的披露清å•ä¸Šçš„实体或其æˆå‘˜ï¼Œåˆ™ç›¸å…³å®žä½“å°†è¦æ±‚å…¶å‚与。 + +å¦åˆ™ï¼ŒæŠ«éœ²æ–¹å°†è¢«å‘ŠçŸ¥ä¸“家å‚与的情况。谅解备忘录涵盖了专家，è¦æ±‚披露方确认å‚与。 +如果披露方有令人信æœçš„ç†ç”±æ出异议，则必须在五个工作日内æ出异议，并立å³ä¸Žäº‹ä»¶ +å°ç»„解决。如果披露方在五个工作日内未作出回应，则视为默许。 + +在确认或解决异议åŽï¼Œä¸“家由事件å°ç»„披露，并进入开å‘过程。 + +åè°ƒå‘布 +"""""""" + +有关å„方将å商é™åˆ¶ç»“æŸçš„日期和时间。æ¤æ—¶ï¼Œå‡†å¤‡å¥½çš„缓解措施集æˆåˆ°ç›¸å…³çš„å†…æ ¸æ ‘ä¸ +并å‘布。 + +虽然我们ç†è§£ç¡¬ä»¶å®‰å…¨é—®é¢˜éœ€è¦åè°ƒé™åˆ¶æ—¶é—´ï¼Œä½†é™åˆ¶æ—¶é—´åº”é™åˆ¶åœ¨æ‰€æœ‰æœ‰å…³å„方制定〠+测试和准备缓解措施所需的最çŸæ—¶é—´å†…。人为地延长é™åˆ¶æ—¶é—´ä»¥æ»¡è¶³ä¼šè®®è®¨è®ºæ—¥æœŸæˆ–其他 +éžæŠ€æœ¯åŽŸå› ，会给相关的开å‘人员和å“应å°ç»„带æ¥äº†æ›´å¤šçš„å·¥ä½œå’Œè´Ÿæ‹…ï¼Œå› ä¸ºè¡¥ä¸éœ€è¦ +ä¿æŒæœ€æ–°ï¼Œä»¥ä¾¿è·Ÿè¸ªæ£åœ¨è¿›è¡Œçš„ä¸Šæ¸¸å†…æ ¸å¼€å‘，这å¯èƒ½ä¼šé€ æˆå†²çªçš„更改。 + +CVEåˆ†é… +""""""" + +硬件安全å°ç»„å’Œåˆå§‹å“应å°ç»„都ä¸åˆ†é…CVE，开å‘过程也ä¸éœ€è¦CVE。如果CVE是由披露方 +æ供的，则å¯ç”¨äºŽæ–‡æ¡£ä¸ã€‚ + +æµç¨‹ä¸“使 +-------- + +为了å助这一进程，我们在å„组织设立了专使，他们å¯ä»¥å›žç”有关报告æµç¨‹å’Œè¿›ä¸€æ¥å¤„ç† +的问题或æ供指导。专使ä¸å‚与特定问题的披露，除éžå“应å°ç»„或相关披露方æ出è¦æ±‚。 +现任专使åå•: + + ============= ======================================================== + ARM + AMD Tom Lendacky <tom.lendacky@amd.com> + IBM + Intel Tony Luck <tony.luck@intel.com> + Qualcomm Trilok Soni <tsoni@codeaurora.org> + + Microsoft Sasha Levin <sashal@kernel.org> + VMware + Xen Andrew Cooper <andrew.cooper3@citrix.com> + + Canonical John Johansen <john.johansen@canonical.com> + Debian Ben Hutchings <ben@decadent.org.uk> + Oracle Konrad Rzeszutek Wilk <konrad.wilk@oracle.com> + Red Hat Josh Poimboeuf <jpoimboe@redhat.com> + SUSE Jiri Kosina <jkosina@suse.cz> + + Amazon + Google Kees Cook <keescook@chromium.org> + ============= ======================================================== + +如果è¦å°†æ‚¨çš„ç»„ç»‡æ·»åŠ åˆ°ä¸“ä½¿åå•ä¸ï¼Œè¯·ä¸Žç¡¬ä»¶å®‰å…¨å°ç»„è”系。被æå的专使必须完全 +ç†è§£å’Œæ”¯æŒæˆ‘们的过程，并且在Linuxå†…æ ¸ç¤¾åŒºä¸å¾ˆå®¹æ˜“è”系。 + +åŠ å¯†é‚®ä»¶åˆ—è¡¨ +------------ + +æˆ‘ä»¬ä½¿ç”¨åŠ å¯†é‚®ä»¶åˆ—è¡¨è¿›è¡Œé€šä¿¡ã€‚è¿™äº›åˆ—è¡¨çš„å·¥ä½œåŽŸç†æ˜¯ï¼Œå‘é€åˆ°åˆ—表的电å邮件使用 +列表的PGP密钥或列表的/MIMEè¯ä¹¦è¿›è¡ŒåŠ 密。邮件列表软件对电å邮件进行解密，并 +使用订阅者的PGP密钥或S/MIMEè¯ä¹¦ä¸ºæ¯ä¸ªè®¢é˜…者分别对其进行é‡æ–°åŠ 密。有关邮件列表 +软件和用于确ä¿åˆ—表安全和数æ®ä¿æŠ¤çš„设置的详细信æ¯ï¼Œè¯·è®¿é—®: +https://www.kernel.org/.... + +关键点 +^^^^^^ + +åˆæ¬¡æŽ¥è§¦è§ :ref:`zh_Contact`. 对于特定于事件的邮件列表，密钥和S/MIMEè¯ä¹¦é€šè¿‡ +特定列表å‘é€çš„电åé‚®ä»¶ä¼ é€’ç»™è®¢é˜…è€…ã€‚ + +订阅事件特定列表 +^^^^^^^^^^^^^^^^ + +订阅由å“应å°ç»„处ç†ã€‚希望å‚与通信的披露方将潜在订户的列表å‘é€ç»™å“应组，以便 +å“应组å¯ä»¥éªŒè¯è®¢é˜…请求。 + +æ¯ä¸ªè®¢æˆ·éƒ½éœ€è¦é€šè¿‡ç”µå邮件å‘å“应å°ç»„å‘é€è®¢é˜…请求。电å邮件必须使用订阅æœåŠ¡å™¨ +çš„PGP密钥或S/MIMEè¯ä¹¦ç¾å。如果使用PGP密钥，则必须从公钥æœåŠ¡å™¨èŽ·å¾—该密钥， +并且ç†æƒ³æƒ…况下该密钥连接到Linuxå†…æ ¸çš„PGP信任网。å¦è¯·å‚è§: +https://www.kernel.org/signature.html. + +å“应å°ç»„验è¯è®¢é˜…è€…ï¼Œå¹¶å°†è®¢é˜…è€…æ·»åŠ åˆ°åˆ—è¡¨ä¸ã€‚订阅åŽï¼Œè®¢é˜…者将收到æ¥è‡ªé‚®ä»¶åˆ—表 +的电å邮件，该邮件列表使用列表的PGP密钥或列表的/MIMEè¯ä¹¦ç¾å。订阅者的电å邮件 +客户端å¯ä»¥ä»Žç¾åä¸æå–PGP密钥或S/MIMEè¯ä¹¦ï¼Œä»¥ä¾¿è®¢é˜…者å¯ä»¥å‘列表å‘é€åŠ 密电å +邮件。 diff --git a/Documentation/translations/zh_CN/process/index.rst b/Documentation/translations/zh_CN/process/index.rst index be1e764a80d2..8051a7b322c5 100644 --- a/Documentation/translations/zh_CN/process/index.rst +++ b/Documentation/translations/zh_CN/process/index.rst @@ -31,6 +31,8 @@ development-process email-clients license-rules + kernel-enforcement-statement + kernel-driver-statement 其它大多数开å‘人员感兴趣的社区指å—： @@ -43,6 +45,7 @@ stable-api-nonsense stable-kernel-rules management-style + embargoed-hardware-issues 这些是一些总体技术指å—，由于缺ä¹æ›´å¥½çš„地方，现在已ç»æ”¾åœ¨è¿™é‡Œ diff --git a/Documentation/translations/zh_CN/process/kernel-driver-statement.rst b/Documentation/translations/zh_CN/process/kernel-driver-statement.rst new file mode 100644 index 000000000000..2b3375bcccfd --- /dev/null +++ b/Documentation/translations/zh_CN/process/kernel-driver-statement.rst @@ -0,0 +1,199 @@ +.. _cn_process_statement_driver: + +.. include:: ../disclaimer-zh_CN.rst + +:Original: :ref:`Documentation/process/kernel-driver-statement.rst <process_statement_driver>` +:Translator: Alex Shi <alex.shi@linux.alibaba.com> + +å†…æ ¸é©±åŠ¨å£°æ˜Ž +------------ + +关于Linuxå†…æ ¸æ¨¡å—的立场声明 +=========================== + +我们，以下署åçš„Linuxå†…æ ¸å¼€å‘人员，认为任何å°é—æºLinuxå†…æ ¸æ¨¡å—或驱动程åºéƒ½æ˜¯ +有害的和ä¸å¯å–的。我们已ç»ä¸€å†å‘现它们对Linux用户，ä¼ä¸šå’Œæ›´å¤§çš„Linux生æ€ç³»ç»Ÿ +æœ‰å®³ã€‚è¿™æ ·çš„æ¨¡å—å¦å®šäº†Linuxå¼€å‘模型的开放性，稳定性，çµæ´»æ€§å’Œå¯ç»´æŠ¤æ€§ï¼Œå¹¶ä½¿ +ä»–ä»¬çš„ç”¨æˆ·æ— æ³•ä½¿ç”¨Linux社区的专业知识。æä¾›é—æºå†…æ ¸æ¨¡å—的供应商迫使其客户 +放弃Linux的主è¦ä¼˜åŠ¿æˆ–é€‰æ‹©æ–°çš„ä¾›åº”å•†ã€‚å› æ¤ï¼Œä¸ºäº†å……分利用开æºæ‰€æ供的æˆæœ¬èŠ‚çœå’Œ +共享支æŒä¼˜åŠ¿ï¼Œæˆ‘们敦促供应商采å–措施，以开æºå†…æ ¸ä»£ç 在Linux上为其客户æ供支æŒã€‚ + +我们åªä¸ºè‡ªå·±è¯´è¯ï¼Œè€Œä¸æ˜¯æˆ‘们今天å¯èƒ½ä¼šä¸ºä¹‹å·¥ä½œï¼Œè¿‡åŽ»æˆ–å°†æ¥ä¼šä¸ºä¹‹å·¥ä½œçš„任何公å¸ã€‚ + + - Dave Airlie + - Nick Andrew + - Jens Axboe + - Ralf Baechle + - Felipe Balbi + - Ohad Ben-Cohen + - Muli Ben-Yehuda + - Jiri Benc + - Arnd Bergmann + - Thomas Bogendoerfer + - Vitaly Bordug + - James Bottomley + - Josh Boyer + - Neil Brown + - Mark Brown + - David Brownell + - Michael Buesch + - Franck Bui-Huu + - Adrian Bunk + - François Cami + - Ralph Campbell + - Luiz Fernando N. Capitulino + - Mauro Carvalho Chehab + - Denis Cheng + - Jonathan Corbet + - Glauber Costa + - Alan Cox + - Magnus Damm + - Ahmed S. Darwish + - Robert P. J. Day + - Hans de Goede + - Arnaldo Carvalho de Melo + - Helge Deller + - Jean Delvare + - Mathieu Desnoyers + - Sven-Thorsten Dietrich + - Alexey Dobriyan + - Daniel Drake + - Alex Dubov + - Randy Dunlap + - Michael Ellerman + - Pekka Enberg + - Jan Engelhardt + - Mark Fasheh + - J. Bruce Fields + - Larry Finger + - Jeremy Fitzhardinge + - Mike Frysinger + - Kumar Gala + - Robin Getz + - Liam Girdwood + - Jan-Benedict Glaw + - Thomas Gleixner + - Brice Goglin + - Cyrill Gorcunov + - Andy Gospodarek + - Thomas Graf + - Krzysztof Halasa + - Harvey Harrison + - Stephen Hemminger + - Michael Hennerich + - Tejun Heo + - Benjamin Herrenschmidt + - Kristian Høgsberg + - Henrique de Moraes Holschuh + - Marcel Holtmann + - Mike Isely + - Takashi Iwai + - Olof Johansson + - Dave Jones + - Jesper Juhl + - Matthias Kaehlcke + - Kenji Kaneshige + - Jan Kara + - Jeremy Kerr + - Russell King + - Olaf Kirch + - Roel Kluin + - Hans-Jürgen Koch + - Auke Kok + - Peter Korsgaard + - Jiri Kosina + - Aaro Koskinen + - Mariusz Kozlowski + - Greg Kroah-Hartman + - Michael Krufky + - Aneesh Kumar + - Clemens Ladisch + - Christoph Lameter + - Gunnar Larisch + - Anders Larsen + - Grant Likely + - John W. Linville + - Yinghai Lu + - Tony Luck + - Pavel Machek + - Matt Mackall + - Paul Mackerras + - Roland McGrath + - Patrick McHardy + - Kyle McMartin + - Paul Menage + - Thierry Merle + - Eric Miao + - Akinobu Mita + - Ingo Molnar + - James Morris + - Andrew Morton + - Paul Mundt + - Oleg Nesterov + - Luca Olivetti + - S.ÇaÄŸlar Onur + - Pierre Ossman + - Keith Owens + - Venkatesh Pallipadi + - Nick Piggin + - Nicolas Pitre + - Evgeniy Polyakov + - Richard Purdie + - Mike Rapoport + - Sam Ravnborg + - Gerrit Renker + - Stefan Richter + - David Rientjes + - Luis R. Rodriguez + - Stefan Roese + - Francois Romieu + - Rami Rosen + - Stephen Rothwell + - Maciej W. Rozycki + - Mark Salyzyn + - Yoshinori Sato + - Deepak Saxena + - Holger Schurig + - Amit Shah + - Yoshihiro Shimoda + - Sergei Shtylyov + - Kay Sievers + - Sebastian Siewior + - Rik Snel + - Jes Sorensen + - Alexey Starikovskiy + - Alan Stern + - Timur Tabi + - Hirokazu Takata + - Eliezer Tamir + - Eugene Teo + - Doug Thompson + - FUJITA Tomonori + - Dmitry Torokhov + - Marcelo Tosatti + - Steven Toth + - Theodore Tso + - Matthias Urlichs + - Geert Uytterhoeven + - Arjan van de Ven + - Ivo van Doorn + - Rik van Riel + - Wim Van Sebroeck + - Hans Verkuil + - Horst H. von Brand + - Dmitri Vorobiev + - Anton Vorontsov + - Daniel Walker + - Johannes Weiner + - Harald Welte + - Matthew Wilcox + - Dan J. Williams + - Darrick J. Wong + - David Woodhouse + - Chris Wright + - Bryan Wu + - Rafael J. Wysocki + - Herbert Xu + - Vlad Yasevich + - Peter Zijlstra + - Bartlomiej Zolnierkiewicz diff --git a/Documentation/translations/zh_CN/process/kernel-enforcement-statement.rst b/Documentation/translations/zh_CN/process/kernel-enforcement-statement.rst new file mode 100644 index 000000000000..75f7b7b9137c --- /dev/null +++ b/Documentation/translations/zh_CN/process/kernel-enforcement-statement.rst @@ -0,0 +1,151 @@ +.. _cn_process_statement_kernel: + +.. include:: ../disclaimer-zh_CN.rst + +:Original: :ref:`Documentation/process/kernel-enforcement-statement.rst <process_statement_kernel>` +:Translator: Alex Shi <alex.shi@linux.alibaba.com> + +Linux å†…æ ¸æ‰§è¡Œå£°æ˜Ž +------------------ + +作为Linuxå†…æ ¸çš„å¼€å‘人员，我们对如何使用我们的软件以åŠå¦‚何实施软件许å¯è¯æœ‰ç€ +浓厚的兴趣。éµå®ˆGPL-2.0çš„äº’æƒ å…±äº«ä¹‰åŠ¡å¯¹æˆ‘ä»¬è½¯ä»¶å’Œç¤¾åŒºçš„é•¿æœŸå¯æŒç»æ€§è‡³å…³é‡è¦ã€‚ + +虽然有æƒå¼ºåˆ¶æ‰§è¡Œå¯¹æˆ‘们社区的贡献ä¸çš„å•ç‹¬ç‰ˆæƒæƒç›Šï¼Œä½†æˆ‘们有共åŒçš„利益，å³ç¡®ä¿ +个人强制执行行动的方å¼æœ‰åˆ©äºŽæˆ‘们的社区，ä¸ä¼šå¯¹æˆ‘们软件生æ€ç³»ç»Ÿçš„å¥åº·å’Œå¢žé•¿ +产生æ„外的负é¢å½±å“。为了阻æ¢æ— 益的执法行动，我们åŒæ„ä»£è¡¨æˆ‘ä»¬è‡ªå·±å’Œæˆ‘ä»¬ç‰ˆæƒ +利益的任何继承人对Linuxå†…æ ¸ç”¨æˆ·ä½œå‡ºä»¥ä¸‹ç¬¦åˆæˆ‘们开å‘社区最大利益的承诺: + + 尽管有GPL-2.0的终æ¢æ¡æ¬¾ï¼Œæˆ‘们åŒæ„，采用以下GPL-3.0æ¡æ¬¾ä½œä¸ºæˆ‘们许å¯è¯ä¸‹çš„ + é™„åŠ è®¸å¯ï¼Œä½œä¸ºä»»ä½•å¯¹è®¸å¯è¯ä¸‹æƒåˆ©çš„éžé˜²å¾¡æ€§ä¸»å¼ ，这符åˆæˆ‘们开å‘社区的最佳 + 利益。 + + 但是，如果您åœæ¢æ‰€æœ‰è¿å本许å¯è¯çš„行为，则您从特定版æƒæŒæœ‰äººå¤„获得的 + 许å¯è¯å°†è¢«æ¢å¤ï¼šï¼ˆa）暂时æ¢å¤ï¼Œé™¤éžç‰ˆæƒæŒæœ‰äººæ˜Žç¡®å¹¶æœ€ç»ˆç»ˆæ¢æ‚¨çš„许å¯è¯ï¼› + 以åŠï¼ˆb）永久æ¢å¤, 如果版æƒæŒæœ‰äººæœªèƒ½åœ¨ä½ 终æ¢è¿ååŽ60天内以åˆç†æ–¹å¼ + 通知您è¿å本许å¯è¯çš„行为，则永久æ¢å¤æ‚¨çš„许å¯è¯ã€‚ + + æ¤å¤–，如果版æƒæ‰€æœ‰è€…以æŸç§åˆç†çš„æ–¹å¼é€šçŸ¥æ‚¨è¿å了本许å¯ï¼Œè¿™æ˜¯æ‚¨ç¬¬ä¸€æ¬¡ + 从该版æƒæ‰€æœ‰è€…处收到è¿å本许å¯çš„通知（对于任何作å“），并且您在收到通知 + åŽçš„30å¤©å†…çº æ£è¿è§„行为。则您从特定版æƒæ‰€æœ‰è€…处获得的许å¯å°†æ°¸ä¹…æ¢å¤. + +我们æ供这些ä¿è¯çš„目的是鼓励更多地使用该软件。我们希望公å¸å’Œä¸ªäººä½¿ç”¨ã€ä¿®æ”¹å’Œ +分å‘æ¤è½¯ä»¶ã€‚我们希望以公开和é€æ˜Žçš„æ–¹å¼ä¸Žç”¨æˆ·åˆä½œï¼Œä»¥æ¶ˆé™¤æˆ‘们对法规éµä»Žæ€§æˆ–强制 +执行的任何ä¸ç¡®å®šæ€§ï¼Œè¿™äº›ä¸ç¡®å®šæ€§å¯èƒ½ä¼šé™åˆ¶æˆ‘们软件的采用。我们将法律行动视为 +最åŽæ‰‹æ®µï¼Œåªæœ‰åœ¨å…¶ä»–社区努力未能解决这一问题时æ‰é‡‡å–行动。 + +最åŽï¼Œä¸€æ—¦ä¸€ä¸ªä¸åˆè§„é—®é¢˜å¾—åˆ°è§£å†³ï¼Œæˆ‘ä»¬å¸Œæœ›ç”¨æˆ·ä¼šæ„Ÿåˆ°æ¬¢è¿Žï¼ŒåŠ å…¥æˆ‘ä»¬ä¸ºä¹‹åŠªåŠ›çš„ +这个项目。共åŒåŠªåŠ›ï¼Œæˆ‘们会更强大。 + +除了下é¢æ到的以外，我们åªä¸ºè‡ªå·±è¯´è¯ï¼Œè€Œä¸æ˜¯ä¸ºä»Šå¤©ã€è¿‡åŽ»æˆ–å°†æ¥å¯èƒ½ä¸ºä¹‹å·¥ä½œçš„ +任何公å¸è¯´è¯ã€‚ + + - Laura Abbott + - Bjorn Andersson (Linaro) + - Andrea Arcangeli + - Neil Armstrong + - Jens Axboe + - Pablo Neira Ayuso + - Khalid Aziz + - Ralf Baechle + - Felipe Balbi + - Arnd Bergmann + - Ard Biesheuvel + - Tim Bird + - Paolo Bonzini + - Christian Borntraeger + - Mark Brown (Linaro) + - Paul Burton + - Javier Martinez Canillas + - Rob Clark + - Kees Cook (Google) + - Jonathan Corbet + - Dennis Dalessandro + - Vivien Didelot (Savoir-faire Linux) + - Hans de Goede + - Mel Gorman (SUSE) + - Sven Eckelmann + - Alex Elder (Linaro) + - Fabio Estevam + - Larry Finger + - Bhumika Goyal + - Andy Gross + - Juergen Gross + - Shawn Guo + - Ulf Hansson + - Stephen Hemminger (Microsoft) + - Tejun Heo + - Rob Herring + - Masami Hiramatsu + - Michal Hocko + - Simon Horman + - Johan Hovold (Hovold Consulting AB) + - Christophe JAILLET + - Olof Johansson + - Lee Jones (Linaro) + - Heiner Kallweit + - Srinivas Kandagatla + - Jan Kara + - Shuah Khan (Samsung) + - David Kershner + - Jaegeuk Kim + - Namhyung Kim + - Colin Ian King + - Jeff Kirsher + - Greg Kroah-Hartman (Linux Foundation) + - Christian König + - Vinod Koul + - Krzysztof Kozlowski + - Viresh Kumar + - Aneesh Kumar K.V + - Julia Lawall + - Doug Ledford + - Chuck Lever (Oracle) + - Daniel Lezcano + - Shaohua Li + - Xin Long + - Tony Luck + - Catalin Marinas (Arm Ltd) + - Mike Marshall + - Chris Mason + - Paul E. McKenney + - Arnaldo Carvalho de Melo + - David S. Miller + - Ingo Molnar + - Kuninori Morimoto + - Trond Myklebust + - Martin K. Petersen (Oracle) + - Borislav Petkov + - Jiri Pirko + - Josh Poimboeuf + - Sebastian Reichel (Collabora) + - Guenter Roeck + - Joerg Roedel + - Leon Romanovsky + - Steven Rostedt (VMware) + - Frank Rowand + - Ivan Safonov + - Anna Schumaker + - Jes Sorensen + - K.Y. Srinivasan + - David Sterba (SUSE) + - Heiko Stuebner + - Jiri Kosina (SUSE) + - Willy Tarreau + - Dmitry Torokhov + - Linus Torvalds + - Thierry Reding + - Rik van Riel + - Luis R. Rodriguez + - Geert Uytterhoeven (Glider bvba) + - Eduardo Valentin (Amazon.com) + - Daniel Vetter + - Linus Walleij + - Richard Weinberger + - Dan Williams + - Rafael J. Wysocki + - Arvind Yadav + - Masahiro Yamada + - Wei Yongjun + - Lv Zheng + - Marc Zyngier (Arm Ltd) diff --git a/Documentation/usb/index.rst b/Documentation/usb/index.rst index e55386a4abfb..36b6ebd9a9d9 100644 --- a/Documentation/usb/index.rst +++ b/Documentation/usb/index.rst @@ -22,11 +22,9 @@ USB support misc_usbsevseg mtouchusb ohci - rio usbip_protocol usbmon usb-serial - wusb-design-overview usb-help text_files diff --git a/Documentation/usb/text_files.rst b/Documentation/usb/text_files.rst index 6a8d3fcf64b6..1c18c05c3920 100644 --- a/Documentation/usb/text_files.rst +++ b/Documentation/usb/text_files.rst @@ -16,12 +16,6 @@ USB devfs drop permissions source .. literalinclude:: usbdevfs-drop-permissions.c :language: c -WUSB command line script to manipulate auth credentials -------------------------------------------------------- - -.. literalinclude:: wusb-cbaf - :language: shell - Credits ------- diff --git a/Documentation/userspace-api/ioctl/ioctl-number.rst b/Documentation/userspace-api/ioctl/ioctl-number.rst index 4ef86433bd67..2e91370dc159 100644 --- a/Documentation/userspace-api/ioctl/ioctl-number.rst +++ b/Documentation/userspace-api/ioctl/ioctl-number.rst @@ -132,7 +132,6 @@ Code Seq# Include File Comments 'F' 80-8F linux/arcfb.h conflict! 'F' DD video/sstfb.h conflict! 'G' 00-3F drivers/misc/sgi-gru/grulib.h conflict! -'G' 00-0F linux/gigaset_dev.h conflict! 'H' 00-7F linux/hiddev.h conflict! 'H' 00-0F linux/hidraw.h conflict! 'H' 01 linux/mei.h conflict! diff --git a/Documentation/virtual/guest-halt-polling.txt b/Documentation/virt/guest-halt-polling.rst index b3a2a294532d..b4e747942417 100644 --- a/Documentation/virtual/guest-halt-polling.txt +++ b/Documentation/virt/guest-halt-polling.rst @@ -1,9 +1,11 @@ +================== Guest halt polling ================== The cpuidle_haltpoll driver, with the haltpoll governor, allows the guest vcpus to poll for a specified amount of time before halting. + This provides the following benefits to host side polling: 1) The POLL flag is set while polling is performed, which allows @@ -29,18 +31,21 @@ Module Parameters The haltpoll governor has 5 tunable module parameters: 1) guest_halt_poll_ns: + Maximum amount of time, in nanoseconds, that polling is performed before halting. Default: 200000 2) guest_halt_poll_shrink: + Division factor used to shrink per-cpu guest_halt_poll_ns when wakeup event occurs after the global guest_halt_poll_ns. Default: 2 3) guest_halt_poll_grow: + Multiplication factor used to grow per-cpu guest_halt_poll_ns when event occurs after per-cpu guest_halt_poll_ns but before global guest_halt_poll_ns. @@ -48,6 +53,7 @@ but before global guest_halt_poll_ns. Default: 2 4) guest_halt_poll_grow_start: + The per-cpu guest_halt_poll_ns eventually reaches zero in case of an idle system. This value sets the initial per-cpu guest_halt_poll_ns when growing. This can @@ -66,7 +72,7 @@ high once achieves global guest_halt_poll_ns value). Default: Y -The module parameters can be set from the debugfs files in: +The module parameters can be set from the debugfs files in:: /sys/module/haltpoll/parameters/ @@ -74,5 +80,5 @@ Further Notes ============= - Care should be taken when setting the guest_halt_poll_ns parameter as a -large value has the potential to drive the cpu usage to 100% on a machine which -would be almost entirely idle otherwise. + large value has the potential to drive the cpu usage to 100% on a machine + which would be almost entirely idle otherwise. diff --git a/Documentation/virt/index.rst b/Documentation/virt/index.rst index 062ffb527043..de1ab81df958 100644 --- a/Documentation/virt/index.rst +++ b/Documentation/virt/index.rst @@ -8,7 +8,9 @@ Linux Virtualization Support :maxdepth: 2 kvm/index + uml/user_mode_linux paravirt_ops + guest-halt-polling .. only:: html and subproject diff --git a/Documentation/virt/kvm/api.txt b/Documentation/virt/kvm/api.rst index ebb37b34dcfc..ebd383fba939 100644 --- a/Documentation/virt/kvm/api.txt +++ b/Documentation/virt/kvm/api.rst @@ -1,8 +1,11 @@ +.. SPDX-License-Identifier: GPL-2.0 + +=================================================================== The Definitive KVM (Kernel-based Virtual Machine) API Documentation =================================================================== 1. General description ----------------------- +====================== The kvm API is a set of ioctls that are issued to control various aspects of a virtual machine. The ioctls belong to the following classes: @@ -33,7 +36,7 @@ of a virtual machine. The ioctls belong to the following classes: was used to create the VM. 2. File descriptors -------------------- +=================== The kvm API is centered around file descriptors. An initial open("/dev/kvm") obtains a handle to the kvm subsystem; this handle @@ -70,7 +73,7 @@ the VM is shut down. 3. Extensions -------------- +============= As of Linux 2.6.22, the KVM ABI has been stabilized: no backward incompatible change are allowed. However, there is an extension @@ -84,13 +87,14 @@ set of ioctls is available for application use. 4. API description ------------------- +================== This section describes ioctls that can be used to control kvm guests. For each ioctl, the following information is provided along with a description: - Capability: which KVM extension provides this ioctl. Can be 'basic', + Capability: + which KVM extension provides this ioctl. Can be 'basic', which means that is will be provided by any kernel that supports API version 12 (see section 4.1), a KVM_CAP_xyz constant, which means availability needs to be checked with KVM_CHECK_EXTENSION @@ -99,24 +103,29 @@ description: availability: for kernels that don't support the ioctl, the ioctl returns -ENOTTY. - Architectures: which instruction set architectures provide this ioctl. + Architectures: + which instruction set architectures provide this ioctl. x86 includes both i386 and x86_64. - Type: system, vm, or vcpu. + Type: + system, vm, or vcpu. - Parameters: what parameters are accepted by the ioctl. + Parameters: + what parameters are accepted by the ioctl. - Returns: the return value. General error numbers (EBADF, ENOMEM, EINVAL) + Returns: + the return value. General error numbers (EBADF, ENOMEM, EINVAL) are not detailed, but errors with specific meanings are. 4.1 KVM_GET_API_VERSION +----------------------- -Capability: basic -Architectures: all -Type: system ioctl -Parameters: none -Returns: the constant KVM_API_VERSION (=12) +:Capability: basic +:Architectures: all +:Type: system ioctl +:Parameters: none +:Returns: the constant KVM_API_VERSION (=12) This identifies the API version as the stable kvm API. It is not expected that this number will change. However, Linux 2.6.20 and @@ -127,12 +136,13 @@ described as 'basic' will be available. 4.2 KVM_CREATE_VM +----------------- -Capability: basic -Architectures: all -Type: system ioctl -Parameters: machine type identifier (KVM_VM_*) -Returns: a VM fd that can be used to control the new virtual machine. +:Capability: basic +:Architectures: all +:Type: system ioctl +:Parameters: machine type identifier (KVM_VM_*) +:Returns: a VM fd that can be used to control the new virtual machine. The new VM has no virtual cpus and no memory. You probably want to use 0 as machine type. @@ -155,17 +165,17 @@ identifier, where IPA_Bits is the maximum width of any physical address used by the VM. The IPA_Bits is encoded in bits[7-0] of the machine type identifier. -e.g, to configure a guest to use 48bit physical address size : +e.g, to configure a guest to use 48bit physical address size:: vm_fd = ioctl(dev_fd, KVM_CREATE_VM, KVM_VM_TYPE_ARM_IPA_SIZE(48)); -The requested size (IPA_Bits) must be : - 0 - Implies default size, 40bits (for backward compatibility) +The requested size (IPA_Bits) must be: - or - - N - Implies N bits, where N is a positive integer such that, + == ========================================================= + 0 Implies default size, 40bits (for backward compatibility) + N Implies N bits, where N is a positive integer such that, 32 <= N <= Host_IPA_Limit + == ========================================================= Host_IPA_Limit is the maximum possible value for IPA_Bits on the host and is dependent on the CPU capability and the kernel configuration. The limit can @@ -179,21 +189,28 @@ host physical address translations). 4.3 KVM_GET_MSR_INDEX_LIST, KVM_GET_MSR_FEATURE_INDEX_LIST +---------------------------------------------------------- + +:Capability: basic, KVM_CAP_GET_MSR_FEATURES for KVM_GET_MSR_FEATURE_INDEX_LIST +:Architectures: x86 +:Type: system ioctl +:Parameters: struct kvm_msr_list (in/out) +:Returns: 0 on success; -1 on error -Capability: basic, KVM_CAP_GET_MSR_FEATURES for KVM_GET_MSR_FEATURE_INDEX_LIST -Architectures: x86 -Type: system ioctl -Parameters: struct kvm_msr_list (in/out) -Returns: 0 on success; -1 on error Errors: - EFAULT: the msr index list cannot be read from or written to - E2BIG: the msr index list is to be to fit in the array specified by + + ====== ============================================================ + EFAULT the msr index list cannot be read from or written to + E2BIG the msr index list is to be to fit in the array specified by the user. + ====== ============================================================ -struct kvm_msr_list { +:: + + struct kvm_msr_list { __u32 nmsrs; /* number of msrs in entries */ __u32 indices[0]; -}; + }; The user fills in the size of the indices array in nmsrs, and in return kvm adjusts nmsrs to reflect the actual number of msrs and fills in the @@ -214,12 +231,13 @@ otherwise. 4.4 KVM_CHECK_EXTENSION +----------------------- -Capability: basic, KVM_CAP_CHECK_EXTENSION_VM for vm ioctl -Architectures: all -Type: system ioctl, vm ioctl -Parameters: extension identifier (KVM_CAP_*) -Returns: 0 if unsupported; 1 (or some other positive integer) if supported +:Capability: basic, KVM_CAP_CHECK_EXTENSION_VM for vm ioctl +:Architectures: all +:Type: system ioctl, vm ioctl +:Parameters: extension identifier (KVM_CAP_*) +:Returns: 0 if unsupported; 1 (or some other positive integer) if supported The API allows the application to query about extensions to the core kvm API. Userspace passes an extension identifier (an integer) and @@ -232,12 +250,13 @@ It is thus encouraged to use the vm ioctl to query for capabilities (available with KVM_CAP_CHECK_EXTENSION_VM on the vm fd) 4.5 KVM_GET_VCPU_MMAP_SIZE +-------------------------- -Capability: basic -Architectures: all -Type: system ioctl -Parameters: none -Returns: size of vcpu mmap area, in bytes +:Capability: basic +:Architectures: all +:Type: system ioctl +:Parameters: none +:Returns: size of vcpu mmap area, in bytes The KVM_RUN ioctl (cf.) communicates with userspace via a shared memory region. This ioctl returns the size of that region. See the @@ -245,23 +264,25 @@ KVM_RUN documentation for details. 4.6 KVM_SET_MEMORY_REGION +------------------------- -Capability: basic -Architectures: all -Type: vm ioctl -Parameters: struct kvm_memory_region (in) -Returns: 0 on success, -1 on error +:Capability: basic +:Architectures: all +:Type: vm ioctl +:Parameters: struct kvm_memory_region (in) +:Returns: 0 on success, -1 on error This ioctl is obsolete and has been removed. 4.7 KVM_CREATE_VCPU +------------------- -Capability: basic -Architectures: all -Type: vm ioctl -Parameters: vcpu id (apic id on x86) -Returns: vcpu fd on success, -1 on error +:Capability: basic +:Architectures: all +:Type: vm ioctl +:Parameters: vcpu id (apic id on x86) +:Returns: vcpu fd on success, -1 on error This API adds a vcpu to a virtual machine. No more than max_vcpus may be added. The vcpu id is an integer in the range [0, max_vcpu_id). @@ -302,22 +323,25 @@ cpu's hardware control block. 4.8 KVM_GET_DIRTY_LOG (vm ioctl) +-------------------------------- -Capability: basic -Architectures: all -Type: vm ioctl -Parameters: struct kvm_dirty_log (in/out) -Returns: 0 on success, -1 on error +:Capability: basic +:Architectures: all +:Type: vm ioctl +:Parameters: struct kvm_dirty_log (in/out) +:Returns: 0 on success, -1 on error -/* for KVM_GET_DIRTY_LOG */ -struct kvm_dirty_log { +:: + + /* for KVM_GET_DIRTY_LOG */ + struct kvm_dirty_log { __u32 slot; __u32 padding; union { void __user *dirty_bitmap; /* one bit per page */ __u64 padding; }; -}; + }; Given a memory slot, return a bitmap containing any pages dirtied since the last call to this ioctl. Bit 0 is the first page in the @@ -334,25 +358,31 @@ KVM_CAP_MANUAL_DIRTY_LOG_PROTECT2 is enabled. For more information, see the description of the capability. 4.9 KVM_SET_MEMORY_ALIAS +------------------------ -Capability: basic -Architectures: x86 -Type: vm ioctl -Parameters: struct kvm_memory_alias (in) -Returns: 0 (success), -1 (error) +:Capability: basic +:Architectures: x86 +:Type: vm ioctl +:Parameters: struct kvm_memory_alias (in) +:Returns: 0 (success), -1 (error) This ioctl is obsolete and has been removed. 4.10 KVM_RUN +------------ + +:Capability: basic +:Architectures: all +:Type: vcpu ioctl +:Parameters: none +:Returns: 0 on success, -1 on error -Capability: basic -Architectures: all -Type: vcpu ioctl -Parameters: none -Returns: 0 on success, -1 on error Errors: - EINTR: an unmasked signal is pending + + ===== ============================= + EINTR an unmasked signal is pending + ===== ============================= This ioctl is used to run a guest virtual cpu. While there are no explicit parameters, there is an implicit parameter block that can be @@ -362,42 +392,46 @@ kvm_run' (see below). 4.11 KVM_GET_REGS +----------------- -Capability: basic -Architectures: all except ARM, arm64 -Type: vcpu ioctl -Parameters: struct kvm_regs (out) -Returns: 0 on success, -1 on error +:Capability: basic +:Architectures: all except ARM, arm64 +:Type: vcpu ioctl +:Parameters: struct kvm_regs (out) +:Returns: 0 on success, -1 on error Reads the general purpose registers from the vcpu. -/* x86 */ -struct kvm_regs { +:: + + /* x86 */ + struct kvm_regs { /* out (KVM_GET_REGS) / in (KVM_SET_REGS) */ __u64 rax, rbx, rcx, rdx; __u64 rsi, rdi, rsp, rbp; __u64 r8, r9, r10, r11; __u64 r12, r13, r14, r15; __u64 rip, rflags; -}; + }; -/* mips */ -struct kvm_regs { + /* mips */ + struct kvm_regs { /* out (KVM_GET_REGS) / in (KVM_SET_REGS) */ __u64 gpr[32]; __u64 hi; __u64 lo; __u64 pc; -}; + }; 4.12 KVM_SET_REGS +----------------- -Capability: basic -Architectures: all except ARM, arm64 -Type: vcpu ioctl -Parameters: struct kvm_regs (in) -Returns: 0 on success, -1 on error +:Capability: basic +:Architectures: all except ARM, arm64 +:Type: vcpu ioctl +:Parameters: struct kvm_regs (in) +:Returns: 0 on success, -1 on error Writes the general purpose registers into the vcpu. @@ -405,17 +439,20 @@ See KVM_GET_REGS for the data structure. 4.13 KVM_GET_SREGS +------------------ -Capability: basic -Architectures: x86, ppc -Type: vcpu ioctl -Parameters: struct kvm_sregs (out) -Returns: 0 on success, -1 on error +:Capability: basic +:Architectures: x86, ppc +:Type: vcpu ioctl +:Parameters: struct kvm_sregs (out) +:Returns: 0 on success, -1 on error Reads special registers from the vcpu. -/* x86 */ -struct kvm_sregs { +:: + + /* x86 */ + struct kvm_sregs { struct kvm_segment cs, ds, es, fs, gs, ss; struct kvm_segment tr, ldt; struct kvm_dtable gdt, idt; @@ -423,9 +460,9 @@ struct kvm_sregs { __u64 efer; __u64 apic_base; __u64 interrupt_bitmap[(KVM_NR_INTERRUPTS + 63) / 64]; -}; + }; -/* ppc -- see arch/powerpc/include/uapi/asm/kvm.h */ + /* ppc -- see arch/powerpc/include/uapi/asm/kvm.h */ interrupt_bitmap is a bitmap of pending external interrupts. At most one bit may be set. This interrupt has been acknowledged by the APIC @@ -433,29 +470,33 @@ but not yet injected into the cpu core. 4.14 KVM_SET_SREGS +------------------ -Capability: basic -Architectures: x86, ppc -Type: vcpu ioctl -Parameters: struct kvm_sregs (in) -Returns: 0 on success, -1 on error +:Capability: basic +:Architectures: x86, ppc +:Type: vcpu ioctl +:Parameters: struct kvm_sregs (in) +:Returns: 0 on success, -1 on error Writes special registers into the vcpu. See KVM_GET_SREGS for the data structures. 4.15 KVM_TRANSLATE +------------------ -Capability: basic -Architectures: x86 -Type: vcpu ioctl -Parameters: struct kvm_translation (in/out) -Returns: 0 on success, -1 on error +:Capability: basic +:Architectures: x86 +:Type: vcpu ioctl +:Parameters: struct kvm_translation (in/out) +:Returns: 0 on success, -1 on error Translates a virtual address according to the vcpu's current address translation mode. -struct kvm_translation { +:: + + struct kvm_translation { /* in */ __u64 linear_address; @@ -465,59 +506,68 @@ struct kvm_translation { __u8 writeable; __u8 usermode; __u8 pad[5]; -}; + }; 4.16 KVM_INTERRUPT +------------------ -Capability: basic -Architectures: x86, ppc, mips -Type: vcpu ioctl -Parameters: struct kvm_interrupt (in) -Returns: 0 on success, negative on failure. +:Capability: basic +:Architectures: x86, ppc, mips +:Type: vcpu ioctl +:Parameters: struct kvm_interrupt (in) +:Returns: 0 on success, negative on failure. Queues a hardware interrupt vector to be injected. -/* for KVM_INTERRUPT */ -struct kvm_interrupt { +:: + + /* for KVM_INTERRUPT */ + struct kvm_interrupt { /* in */ __u32 irq; -}; + }; X86: +^^^^ + +:Returns: -Returns: 0 on success, - -EEXIST if an interrupt is already enqueued - -EINVAL the the irq number is invalid - -ENXIO if the PIC is in the kernel - -EFAULT if the pointer is invalid + ========= =================================== + 0 on success, + -EEXIST if an interrupt is already enqueued + -EINVAL the the irq number is invalid + -ENXIO if the PIC is in the kernel + -EFAULT if the pointer is invalid + ========= =================================== Note 'irq' is an interrupt vector, not an interrupt pin or line. This ioctl is useful if the in-kernel PIC is not used. PPC: +^^^^ Queues an external interrupt to be injected. This ioctl is overleaded with 3 different irq values: a) KVM_INTERRUPT_SET - This injects an edge type external interrupt into the guest once it's ready - to receive interrupts. When injected, the interrupt is done. + This injects an edge type external interrupt into the guest once it's ready + to receive interrupts. When injected, the interrupt is done. b) KVM_INTERRUPT_UNSET - This unsets any pending interrupt. + This unsets any pending interrupt. - Only available with KVM_CAP_PPC_UNSET_IRQ. + Only available with KVM_CAP_PPC_UNSET_IRQ. c) KVM_INTERRUPT_SET_LEVEL - This injects a level type external interrupt into the guest context. The - interrupt stays pending until a specific ioctl with KVM_INTERRUPT_UNSET - is triggered. + This injects a level type external interrupt into the guest context. The + interrupt stays pending until a specific ioctl with KVM_INTERRUPT_UNSET + is triggered. - Only available with KVM_CAP_PPC_IRQ_LEVEL. + Only available with KVM_CAP_PPC_IRQ_LEVEL. Note that any value for 'irq' other than the ones stated above is invalid and incurs unexpected behavior. @@ -525,6 +575,7 @@ and incurs unexpected behavior. This is an asynchronous vcpu ioctl and can be invoked from any thread. MIPS: +^^^^^ Queues an external interrupt to be injected into the virtual CPU. A negative interrupt number dequeues the interrupt. @@ -533,24 +584,26 @@ This is an asynchronous vcpu ioctl and can be invoked from any thread. 4.17 KVM_DEBUG_GUEST +-------------------- -Capability: basic -Architectures: none -Type: vcpu ioctl -Parameters: none) -Returns: -1 on error +:Capability: basic +:Architectures: none +:Type: vcpu ioctl +:Parameters: none) +:Returns: -1 on error Support for this has been removed. Use KVM_SET_GUEST_DEBUG instead. 4.18 KVM_GET_MSRS +----------------- -Capability: basic (vcpu), KVM_CAP_GET_MSR_FEATURES (system) -Architectures: x86 -Type: system ioctl, vcpu ioctl -Parameters: struct kvm_msrs (in/out) -Returns: number of msrs successfully returned; - -1 on error +:Capability: basic (vcpu), KVM_CAP_GET_MSR_FEATURES (system) +:Architectures: x86 +:Type: system ioctl, vcpu ioctl +:Parameters: struct kvm_msrs (in/out) +:Returns: number of msrs successfully returned; + -1 on error When used as a system ioctl: Reads the values of MSR-based features that are available for the VM. This @@ -562,18 +615,20 @@ When used as a vcpu ioctl: Reads model-specific registers from the vcpu. Supported msr indices can be obtained using KVM_GET_MSR_INDEX_LIST in a system ioctl. -struct kvm_msrs { +:: + + struct kvm_msrs { __u32 nmsrs; /* number of msrs in entries */ __u32 pad; struct kvm_msr_entry entries[0]; -}; + }; -struct kvm_msr_entry { + struct kvm_msr_entry { __u32 index; __u32 reserved; __u64 data; -}; + }; Application code should set the 'nmsrs' member (which indicates the size of the entries array) and the 'index' member of each array entry. @@ -581,12 +636,13 @@ kvm will fill in the 'data' member. 4.19 KVM_SET_MSRS +----------------- -Capability: basic -Architectures: x86 -Type: vcpu ioctl -Parameters: struct kvm_msrs (in) -Returns: number of msrs successfully set (see below), -1 on error +:Capability: basic +:Architectures: x86 +:Type: vcpu ioctl +:Parameters: struct kvm_msrs (in) +:Returns: number of msrs successfully set (see below), -1 on error Writes model-specific registers to the vcpu. See KVM_GET_MSRS for the data structures. @@ -602,41 +658,44 @@ MSRs that have been set successfully. 4.20 KVM_SET_CPUID +------------------ -Capability: basic -Architectures: x86 -Type: vcpu ioctl -Parameters: struct kvm_cpuid (in) -Returns: 0 on success, -1 on error +:Capability: basic +:Architectures: x86 +:Type: vcpu ioctl +:Parameters: struct kvm_cpuid (in) +:Returns: 0 on success, -1 on error Defines the vcpu responses to the cpuid instruction. Applications should use the KVM_SET_CPUID2 ioctl if available. +:: -struct kvm_cpuid_entry { + struct kvm_cpuid_entry { __u32 function; __u32 eax; __u32 ebx; __u32 ecx; __u32 edx; __u32 padding; -}; + }; -/* for KVM_SET_CPUID */ -struct kvm_cpuid { + /* for KVM_SET_CPUID */ + struct kvm_cpuid { __u32 nent; __u32 padding; struct kvm_cpuid_entry entries[0]; -}; + }; 4.21 KVM_SET_SIGNAL_MASK +------------------------ -Capability: basic -Architectures: all -Type: vcpu ioctl -Parameters: struct kvm_signal_mask (in) -Returns: 0 on success, -1 on error +:Capability: basic +:Architectures: all +:Type: vcpu ioctl +:Parameters: struct kvm_signal_mask (in) +:Returns: 0 on success, -1 on error Defines which signals are blocked during execution of KVM_RUN. This signal mask temporarily overrides the threads signal mask. Any @@ -646,25 +705,30 @@ their traditional behaviour) will cause KVM_RUN to return with -EINTR. Note the signal will only be delivered if not blocked by the original signal mask. -/* for KVM_SET_SIGNAL_MASK */ -struct kvm_signal_mask { +:: + + /* for KVM_SET_SIGNAL_MASK */ + struct kvm_signal_mask { __u32 len; __u8 sigset[0]; -}; + }; 4.22 KVM_GET_FPU +---------------- -Capability: basic -Architectures: x86 -Type: vcpu ioctl -Parameters: struct kvm_fpu (out) -Returns: 0 on success, -1 on error +:Capability: basic +:Architectures: x86 +:Type: vcpu ioctl +:Parameters: struct kvm_fpu (out) +:Returns: 0 on success, -1 on error Reads the floating point state from the vcpu. -/* for KVM_GET_FPU and KVM_SET_FPU */ -struct kvm_fpu { +:: + + /* for KVM_GET_FPU and KVM_SET_FPU */ + struct kvm_fpu { __u8 fpr[8][16]; __u16 fcw; __u16 fsw; @@ -676,21 +740,24 @@ struct kvm_fpu { __u8 xmm[16][16]; __u32 mxcsr; __u32 pad2; -}; + }; 4.23 KVM_SET_FPU +---------------- -Capability: basic -Architectures: x86 -Type: vcpu ioctl -Parameters: struct kvm_fpu (in) -Returns: 0 on success, -1 on error +:Capability: basic +:Architectures: x86 +:Type: vcpu ioctl +:Parameters: struct kvm_fpu (in) +:Returns: 0 on success, -1 on error Writes the floating point state to the vcpu. -/* for KVM_GET_FPU and KVM_SET_FPU */ -struct kvm_fpu { +:: + + /* for KVM_GET_FPU and KVM_SET_FPU */ + struct kvm_fpu { __u8 fpr[8][16]; __u16 fcw; __u16 fsw; @@ -702,16 +769,17 @@ struct kvm_fpu { __u8 xmm[16][16]; __u32 mxcsr; __u32 pad2; -}; + }; 4.24 KVM_CREATE_IRQCHIP +----------------------- -Capability: KVM_CAP_IRQCHIP, KVM_CAP_S390_IRQCHIP (s390) -Architectures: x86, ARM, arm64, s390 -Type: vm ioctl -Parameters: none -Returns: 0 on success, -1 on error +:Capability: KVM_CAP_IRQCHIP, KVM_CAP_S390_IRQCHIP (s390) +:Architectures: x86, ARM, arm64, s390 +:Type: vm ioctl +:Parameters: none +:Returns: 0 on success, -1 on error Creates an interrupt controller model in the kernel. On x86, creates a virtual ioapic, a virtual PIC (two PICs, nested), and sets up @@ -727,12 +795,13 @@ before KVM_CREATE_IRQCHIP can be used. 4.25 KVM_IRQ_LINE +----------------- -Capability: KVM_CAP_IRQCHIP -Architectures: x86, arm, arm64 -Type: vm ioctl -Parameters: struct kvm_irq_level -Returns: 0 on success, -1 on error +:Capability: KVM_CAP_IRQCHIP +:Architectures: x86, arm, arm64 +:Type: vm ioctl +:Parameters: struct kvm_irq_level +:Returns: 0 on success, -1 on error Sets the level of a GSI input to the interrupt controller model in the kernel. On some architectures it is required that an interrupt controller model has @@ -756,16 +825,20 @@ of course). ARM/arm64 can signal an interrupt either at the CPU level, or at the in-kernel irqchip (GIC), and for in-kernel irqchip can tell the GIC to use PPIs designated for specific cpus. The irq field is interpreted -like this: +like this::  bits: | 31 ... 28 | 27 ... 24 | 23 ... 16 | 15 ... 0 | field: | vcpu2_index | irq_type | vcpu_index | irq_id | The irq_type field has the following values: -- irq_type[0]: out-of-kernel GIC: irq_id 0 is IRQ, irq_id 1 is FIQ -- irq_type[1]: in-kernel GIC: SPI, irq_id between 32 and 1019 (incl.) + +- irq_type[0]: + out-of-kernel GIC: irq_id 0 is IRQ, irq_id 1 is FIQ +- irq_type[1]: + in-kernel GIC: SPI, irq_id between 32 and 1019 (incl.) (the vcpu_index field is ignored) -- irq_type[2]: in-kernel GIC: PPI, irq_id between 16 and 31 (incl.) +- irq_type[2]: + in-kernel GIC: PPI, irq_id between 16 and 31 (incl.) (The irq_id field thus corresponds nicely to the IRQ ID in the ARM GIC specs) @@ -779,27 +852,32 @@ Note that on arm/arm64, the KVM_CAP_IRQCHIP capability only conditions injection of interrupts for the in-kernel irqchip. KVM_IRQ_LINE can always be used for a userspace interrupt controller. -struct kvm_irq_level { +:: + + struct kvm_irq_level { union { __u32 irq; /* GSI */ __s32 status; /* not used for KVM_IRQ_LEVEL */ }; __u32 level; /* 0 or 1 */ -}; + }; 4.26 KVM_GET_IRQCHIP +-------------------- -Capability: KVM_CAP_IRQCHIP -Architectures: x86 -Type: vm ioctl -Parameters: struct kvm_irqchip (in/out) -Returns: 0 on success, -1 on error +:Capability: KVM_CAP_IRQCHIP +:Architectures: x86 +:Type: vm ioctl +:Parameters: struct kvm_irqchip (in/out) +:Returns: 0 on success, -1 on error Reads the state of a kernel interrupt controller created with KVM_CREATE_IRQCHIP into a buffer provided by the caller. -struct kvm_irqchip { +:: + + struct kvm_irqchip { __u32 chip_id; /* 0 = PIC1, 1 = PIC2, 2 = IOAPIC */ __u32 pad; union { @@ -807,21 +885,24 @@ struct kvm_irqchip { struct kvm_pic_state pic; struct kvm_ioapic_state ioapic; } chip; -}; + }; 4.27 KVM_SET_IRQCHIP +-------------------- -Capability: KVM_CAP_IRQCHIP -Architectures: x86 -Type: vm ioctl -Parameters: struct kvm_irqchip (in) -Returns: 0 on success, -1 on error +:Capability: KVM_CAP_IRQCHIP +:Architectures: x86 +:Type: vm ioctl +:Parameters: struct kvm_irqchip (in) +:Returns: 0 on success, -1 on error Sets the state of a kernel interrupt controller created with KVM_CREATE_IRQCHIP from a buffer provided by the caller. -struct kvm_irqchip { +:: + + struct kvm_irqchip { __u32 chip_id; /* 0 = PIC1, 1 = PIC2, 2 = IOAPIC */ __u32 pad; union { @@ -829,16 +910,17 @@ struct kvm_irqchip { struct kvm_pic_state pic; struct kvm_ioapic_state ioapic; } chip; -}; + }; 4.28 KVM_XEN_HVM_CONFIG +----------------------- -Capability: KVM_CAP_XEN_HVM -Architectures: x86 -Type: vm ioctl -Parameters: struct kvm_xen_hvm_config (in) -Returns: 0 on success, -1 on error +:Capability: KVM_CAP_XEN_HVM +:Architectures: x86 +:Type: vm ioctl +:Parameters: struct kvm_xen_hvm_config (in) +:Returns: 0 on success, -1 on error Sets the MSR that the Xen HVM guest uses to initialize its hypercall page, and provides the starting address and size of the hypercall @@ -846,7 +928,9 @@ blobs in userspace. When the guest writes the MSR, kvm copies one page of a blob (32- or 64-bit, depending on the vcpu mode) to guest memory. -struct kvm_xen_hvm_config { +:: + + struct kvm_xen_hvm_config { __u32 flags; __u32 msr; __u64 blob_addr_32; @@ -854,16 +938,17 @@ struct kvm_xen_hvm_config { __u8 blob_size_32; __u8 blob_size_64; __u8 pad2[30]; -}; + }; 4.29 KVM_GET_CLOCK +------------------ -Capability: KVM_CAP_ADJUST_CLOCK -Architectures: x86 -Type: vm ioctl -Parameters: struct kvm_clock_data (out) -Returns: 0 on success, -1 on error +:Capability: KVM_CAP_ADJUST_CLOCK +:Architectures: x86 +:Type: vm ioctl +:Parameters: struct kvm_clock_data (out) +:Returns: 0 on success, -1 on error Gets the current timestamp of kvmclock as seen by the current guest. In conjunction with KVM_SET_CLOCK, it is used to ensure monotonicity on scenarios @@ -880,47 +965,56 @@ with KVM_SET_CLOCK. KVM will try to make all VCPUs follow this clock, but the exact value read by each VCPU could differ, because the host TSC is not stable. -struct kvm_clock_data { +:: + + struct kvm_clock_data { __u64 clock; /* kvmclock current value */ __u32 flags; __u32 pad[9]; -}; + }; 4.30 KVM_SET_CLOCK +------------------ -Capability: KVM_CAP_ADJUST_CLOCK -Architectures: x86 -Type: vm ioctl -Parameters: struct kvm_clock_data (in) -Returns: 0 on success, -1 on error +:Capability: KVM_CAP_ADJUST_CLOCK +:Architectures: x86 +:Type: vm ioctl +:Parameters: struct kvm_clock_data (in) +:Returns: 0 on success, -1 on error Sets the current timestamp of kvmclock to the value specified in its parameter. In conjunction with KVM_GET_CLOCK, it is used to ensure monotonicity on scenarios such as migration. -struct kvm_clock_data { +:: + + struct kvm_clock_data { __u64 clock; /* kvmclock current value */ __u32 flags; __u32 pad[9]; -}; + }; 4.31 KVM_GET_VCPU_EVENTS +------------------------ -Capability: KVM_CAP_VCPU_EVENTS -Extended by: KVM_CAP_INTR_SHADOW -Architectures: x86, arm, arm64 -Type: vcpu ioctl -Parameters: struct kvm_vcpu_event (out) -Returns: 0 on success, -1 on error +:Capability: KVM_CAP_VCPU_EVENTS +:Extended by: KVM_CAP_INTR_SHADOW +:Architectures: x86, arm, arm64 +:Type: vcpu ioctl +:Parameters: struct kvm_vcpu_event (out) +:Returns: 0 on success, -1 on error X86: +^^^^ Gets currently pending exceptions, interrupts, and NMIs as well as related states of the vcpu. -struct kvm_vcpu_events { +:: + + struct kvm_vcpu_events { struct { __u8 injected; __u8 nr; @@ -951,7 +1045,7 @@ struct kvm_vcpu_events { __u8 reserved[27]; __u8 exception_has_payload; __u64 exception_payload; -}; + }; The following bits are defined in the flags field: @@ -967,6 +1061,7 @@ The following bits are defined in the flags field: KVM_CAP_EXCEPTION_PAYLOAD is enabled. ARM/ARM64: +^^^^^^^^^^ If the guest accesses a device that is being emulated by the host kernel in such a way that a real device would generate a physical SError, KVM may make @@ -1006,8 +1101,9 @@ It is not possible to read back a pending external abort (injected via KVM_SET_VCPU_EVENTS or otherwise) because such an exception is always delivered directly to the virtual CPU). +:: -struct kvm_vcpu_events { + struct kvm_vcpu_events { struct { __u8 serror_pending; __u8 serror_has_esr; @@ -1017,18 +1113,20 @@ struct kvm_vcpu_events { __u64 serror_esr; } exception; __u32 reserved[12]; -}; + }; 4.32 KVM_SET_VCPU_EVENTS +------------------------ -Capability: KVM_CAP_VCPU_EVENTS -Extended by: KVM_CAP_INTR_SHADOW -Architectures: x86, arm, arm64 -Type: vcpu ioctl -Parameters: struct kvm_vcpu_event (in) -Returns: 0 on success, -1 on error +:Capability: KVM_CAP_VCPU_EVENTS +:Extended by: KVM_CAP_INTR_SHADOW +:Architectures: x86, arm, arm64 +:Type: vcpu ioctl +:Parameters: struct kvm_vcpu_event (in) +:Returns: 0 on success, -1 on error X86: +^^^^ Set pending exceptions, interrupts, and NMIs as well as related states of the vcpu. @@ -1040,9 +1138,11 @@ from the update. These fields are nmi.pending, sipi_vector, smi.smm, smi.pending. Keep the corresponding bits in the flags field cleared to suppress overwriting the current in-kernel state. The bits are: -KVM_VCPUEVENT_VALID_NMI_PENDING - transfer nmi.pending to the kernel -KVM_VCPUEVENT_VALID_SIPI_VECTOR - transfer sipi_vector -KVM_VCPUEVENT_VALID_SMM - transfer the smi sub-struct. +=============================== ================================== +KVM_VCPUEVENT_VALID_NMI_PENDING transfer nmi.pending to the kernel +KVM_VCPUEVENT_VALID_SIPI_VECTOR transfer sipi_vector +KVM_VCPUEVENT_VALID_SMM transfer the smi sub-struct. +=============================== ================================== If KVM_CAP_INTR_SHADOW is available, KVM_VCPUEVENT_VALID_SHADOW can be set in the flags field to signal that interrupt.shadow contains a valid state and @@ -1056,6 +1156,7 @@ exception_has_payload, exception_payload, and exception.pending fields contain a valid state and shall be written into the VCPU. ARM/ARM64: +^^^^^^^^^^ User space may need to inject several types of events to the guest. @@ -1078,31 +1179,35 @@ See KVM_GET_VCPU_EVENTS for the data structure. 4.33 KVM_GET_DEBUGREGS +---------------------- -Capability: KVM_CAP_DEBUGREGS -Architectures: x86 -Type: vm ioctl -Parameters: struct kvm_debugregs (out) -Returns: 0 on success, -1 on error +:Capability: KVM_CAP_DEBUGREGS +:Architectures: x86 +:Type: vm ioctl +:Parameters: struct kvm_debugregs (out) +:Returns: 0 on success, -1 on error Reads debug registers from the vcpu. -struct kvm_debugregs { +:: + + struct kvm_debugregs { __u64 db[4]; __u64 dr6; __u64 dr7; __u64 flags; __u64 reserved[9]; -}; + }; 4.34 KVM_SET_DEBUGREGS +---------------------- -Capability: KVM_CAP_DEBUGREGS -Architectures: x86 -Type: vm ioctl -Parameters: struct kvm_debugregs (in) -Returns: 0 on success, -1 on error +:Capability: KVM_CAP_DEBUGREGS +:Architectures: x86 +:Type: vm ioctl +:Parameters: struct kvm_debugregs (in) +:Returns: 0 on success, -1 on error Writes debug registers into the vcpu. @@ -1111,24 +1216,27 @@ yet and must be cleared on entry. 4.35 KVM_SET_USER_MEMORY_REGION +------------------------------- + +:Capability: KVM_CAP_USER_MEMORY +:Architectures: all +:Type: vm ioctl +:Parameters: struct kvm_userspace_memory_region (in) +:Returns: 0 on success, -1 on error -Capability: KVM_CAP_USER_MEMORY -Architectures: all -Type: vm ioctl -Parameters: struct kvm_userspace_memory_region (in) -Returns: 0 on success, -1 on error +:: -struct kvm_userspace_memory_region { + struct kvm_userspace_memory_region { __u32 slot; __u32 flags; __u64 guest_phys_addr; __u64 memory_size; /* bytes */ __u64 userspace_addr; /* start of the userspace allocated memory */ -}; + }; -/* for kvm_memory_region::flags */ -#define KVM_MEM_LOG_DIRTY_PAGES (1UL << 0) -#define KVM_MEM_READONLY (1UL << 1) + /* for kvm_memory_region::flags */ + #define KVM_MEM_LOG_DIRTY_PAGES (1UL << 0) + #define KVM_MEM_READONLY (1UL << 1) This ioctl allows the user to create, modify or delete a guest physical memory slot. Bits 0-15 of "slot" specify the slot id and this value @@ -1174,12 +1282,13 @@ allocation and is deprecated. 4.36 KVM_SET_TSS_ADDR +--------------------- -Capability: KVM_CAP_SET_TSS_ADDR -Architectures: x86 -Type: vm ioctl -Parameters: unsigned long tss_address (in) -Returns: 0 on success, -1 on error +:Capability: KVM_CAP_SET_TSS_ADDR +:Architectures: x86 +:Type: vm ioctl +:Parameters: unsigned long tss_address (in) +:Returns: 0 on success, -1 on error This ioctl defines the physical address of a three-page region in the guest physical address space. The region must be within the first 4GB of the @@ -1193,21 +1302,24 @@ documentation when it pops into existence). 4.37 KVM_ENABLE_CAP +------------------- + +:Capability: KVM_CAP_ENABLE_CAP +:Architectures: mips, ppc, s390 +:Type: vcpu ioctl +:Parameters: struct kvm_enable_cap (in) +:Returns: 0 on success; -1 on error -Capability: KVM_CAP_ENABLE_CAP -Architectures: mips, ppc, s390 -Type: vcpu ioctl -Parameters: struct kvm_enable_cap (in) -Returns: 0 on success; -1 on error +:Capability: KVM_CAP_ENABLE_CAP_VM +:Architectures: all +:Type: vcpu ioctl +:Parameters: struct kvm_enable_cap (in) +:Returns: 0 on success; -1 on error -Capability: KVM_CAP_ENABLE_CAP_VM -Architectures: all -Type: vcpu ioctl -Parameters: struct kvm_enable_cap (in) -Returns: 0 on success; -1 on error +.. note:: -+Not all extensions are enabled by default. Using this ioctl the application -can enable an extension, making it available to the guest. + Not all extensions are enabled by default. Using this ioctl the application + can enable an extension, making it available to the guest. On systems that do not support this ioctl, it always fails. On systems that do support it, it only works for extensions that are supported for enablement. @@ -1215,76 +1327,91 @@ do support it, it only works for extensions that are supported for enablement. To check if a capability can be enabled, the KVM_CHECK_EXTENSION ioctl should be used. -struct kvm_enable_cap { +:: + + struct kvm_enable_cap { /* in */ __u32 cap; The capability that is supposed to get enabled. +:: + __u32 flags; A bitfield indicating future enhancements. Has to be 0 for now. +:: + __u64 args[4]; Arguments for enabling a feature. If a feature needs initial values to function properly, this is the place to put them. +:: + __u8 pad[64]; -}; + }; The vcpu ioctl should be used for vcpu-specific capabilities, the vm ioctl for vm-wide capabilities. 4.38 KVM_GET_MP_STATE +--------------------- + +:Capability: KVM_CAP_MP_STATE +:Architectures: x86, s390, arm, arm64 +:Type: vcpu ioctl +:Parameters: struct kvm_mp_state (out) +:Returns: 0 on success; -1 on error -Capability: KVM_CAP_MP_STATE -Architectures: x86, s390, arm, arm64 -Type: vcpu ioctl -Parameters: struct kvm_mp_state (out) -Returns: 0 on success; -1 on error +:: -struct kvm_mp_state { + struct kvm_mp_state { __u32 mp_state; -}; + }; Returns the vcpu's current "multiprocessing state" (though also valid on uniprocessor guests). Possible values are: - - KVM_MP_STATE_RUNNABLE: the vcpu is currently running [x86,arm/arm64] - - KVM_MP_STATE_UNINITIALIZED: the vcpu is an application processor (AP) + ========================== =============================================== + KVM_MP_STATE_RUNNABLE the vcpu is currently running [x86,arm/arm64] + KVM_MP_STATE_UNINITIALIZED the vcpu is an application processor (AP) which has not yet received an INIT signal [x86] - - KVM_MP_STATE_INIT_RECEIVED: the vcpu has received an INIT signal, and is + KVM_MP_STATE_INIT_RECEIVED the vcpu has received an INIT signal, and is now ready for a SIPI [x86] - - KVM_MP_STATE_HALTED: the vcpu has executed a HLT instruction and + KVM_MP_STATE_HALTED the vcpu has executed a HLT instruction and is waiting for an interrupt [x86] - - KVM_MP_STATE_SIPI_RECEIVED: the vcpu has just received a SIPI (vector + KVM_MP_STATE_SIPI_RECEIVED the vcpu has just received a SIPI (vector accessible via KVM_GET_VCPU_EVENTS) [x86] - - KVM_MP_STATE_STOPPED: the vcpu is stopped [s390,arm/arm64] - - KVM_MP_STATE_CHECK_STOP: the vcpu is in a special error state [s390] - - KVM_MP_STATE_OPERATING: the vcpu is operating (running or halted) + KVM_MP_STATE_STOPPED the vcpu is stopped [s390,arm/arm64] + KVM_MP_STATE_CHECK_STOP the vcpu is in a special error state [s390] + KVM_MP_STATE_OPERATING the vcpu is operating (running or halted) [s390] - - KVM_MP_STATE_LOAD: the vcpu is in a special load/startup state + KVM_MP_STATE_LOAD the vcpu is in a special load/startup state [s390] + ========================== =============================================== On x86, this ioctl is only useful after KVM_CREATE_IRQCHIP. Without an in-kernel irqchip, the multiprocessing state must be maintained by userspace on these architectures. For arm/arm64: +^^^^^^^^^^^^^^ The only states that are valid are KVM_MP_STATE_STOPPED and KVM_MP_STATE_RUNNABLE which reflect if the vcpu is paused or not. 4.39 KVM_SET_MP_STATE +--------------------- -Capability: KVM_CAP_MP_STATE -Architectures: x86, s390, arm, arm64 -Type: vcpu ioctl -Parameters: struct kvm_mp_state (in) -Returns: 0 on success; -1 on error +:Capability: KVM_CAP_MP_STATE +:Architectures: x86, s390, arm, arm64 +:Type: vcpu ioctl +:Parameters: struct kvm_mp_state (in) +:Returns: 0 on success; -1 on error Sets the vcpu's current "multiprocessing state"; see KVM_GET_MP_STATE for arguments. @@ -1294,17 +1421,19 @@ in-kernel irqchip, the multiprocessing state must be maintained by userspace on these architectures. For arm/arm64: +^^^^^^^^^^^^^^ The only states that are valid are KVM_MP_STATE_STOPPED and KVM_MP_STATE_RUNNABLE which reflect if the vcpu should be paused or not. 4.40 KVM_SET_IDENTITY_MAP_ADDR +------------------------------ -Capability: KVM_CAP_SET_IDENTITY_MAP_ADDR -Architectures: x86 -Type: vm ioctl -Parameters: unsigned long identity (in) -Returns: 0 on success, -1 on error +:Capability: KVM_CAP_SET_IDENTITY_MAP_ADDR +:Architectures: x86 +:Type: vm ioctl +:Parameters: unsigned long identity (in) +:Returns: 0 on success, -1 on error This ioctl defines the physical address of a one-page region in the guest physical address space. The region must be within the first 4GB of the @@ -1322,12 +1451,13 @@ documentation when it pops into existence). Fails if any VCPU has already been created. 4.41 KVM_SET_BOOT_CPU_ID +------------------------ -Capability: KVM_CAP_SET_BOOT_CPU_ID -Architectures: x86 -Type: vm ioctl -Parameters: unsigned long vcpu_id -Returns: 0 on success, -1 on error +:Capability: KVM_CAP_SET_BOOT_CPU_ID +:Architectures: x86 +:Type: vm ioctl +:Parameters: unsigned long vcpu_id +:Returns: 0 on success, -1 on error Define which vcpu is the Bootstrap Processor (BSP). Values are the same as the vcpu id in KVM_CREATE_VCPU. If this ioctl is not called, the default @@ -1335,102 +1465,119 @@ is vcpu 0. 4.42 KVM_GET_XSAVE +------------------ + +:Capability: KVM_CAP_XSAVE +:Architectures: x86 +:Type: vcpu ioctl +:Parameters: struct kvm_xsave (out) +:Returns: 0 on success, -1 on error -Capability: KVM_CAP_XSAVE -Architectures: x86 -Type: vcpu ioctl -Parameters: struct kvm_xsave (out) -Returns: 0 on success, -1 on error -struct kvm_xsave { +:: + + struct kvm_xsave { __u32 region[1024]; -}; + }; This ioctl would copy current vcpu's xsave struct to the userspace. 4.43 KVM_SET_XSAVE +------------------ + +:Capability: KVM_CAP_XSAVE +:Architectures: x86 +:Type: vcpu ioctl +:Parameters: struct kvm_xsave (in) +:Returns: 0 on success, -1 on error -Capability: KVM_CAP_XSAVE -Architectures: x86 -Type: vcpu ioctl -Parameters: struct kvm_xsave (in) -Returns: 0 on success, -1 on error +:: -struct kvm_xsave { + + struct kvm_xsave { __u32 region[1024]; -}; + }; This ioctl would copy userspace's xsave struct to the kernel. 4.44 KVM_GET_XCRS +----------------- + +:Capability: KVM_CAP_XCRS +:Architectures: x86 +:Type: vcpu ioctl +:Parameters: struct kvm_xcrs (out) +:Returns: 0 on success, -1 on error -Capability: KVM_CAP_XCRS -Architectures: x86 -Type: vcpu ioctl -Parameters: struct kvm_xcrs (out) -Returns: 0 on success, -1 on error +:: -struct kvm_xcr { + struct kvm_xcr { __u32 xcr; __u32 reserved; __u64 value; -}; + }; -struct kvm_xcrs { + struct kvm_xcrs { __u32 nr_xcrs; __u32 flags; struct kvm_xcr xcrs[KVM_MAX_XCRS]; __u64 padding[16]; -}; + }; This ioctl would copy current vcpu's xcrs to the userspace. 4.45 KVM_SET_XCRS +----------------- -Capability: KVM_CAP_XCRS -Architectures: x86 -Type: vcpu ioctl -Parameters: struct kvm_xcrs (in) -Returns: 0 on success, -1 on error +:Capability: KVM_CAP_XCRS +:Architectures: x86 +:Type: vcpu ioctl +:Parameters: struct kvm_xcrs (in) +:Returns: 0 on success, -1 on error -struct kvm_xcr { +:: + + struct kvm_xcr { __u32 xcr; __u32 reserved; __u64 value; -}; + }; -struct kvm_xcrs { + struct kvm_xcrs { __u32 nr_xcrs; __u32 flags; struct kvm_xcr xcrs[KVM_MAX_XCRS]; __u64 padding[16]; -}; + }; This ioctl would set vcpu's xcr to the value userspace specified. 4.46 KVM_GET_SUPPORTED_CPUID +---------------------------- + +:Capability: KVM_CAP_EXT_CPUID +:Architectures: x86 +:Type: system ioctl +:Parameters: struct kvm_cpuid2 (in/out) +:Returns: 0 on success, -1 on error -Capability: KVM_CAP_EXT_CPUID -Architectures: x86 -Type: system ioctl -Parameters: struct kvm_cpuid2 (in/out) -Returns: 0 on success, -1 on error +:: -struct kvm_cpuid2 { + struct kvm_cpuid2 { __u32 nent; __u32 padding; struct kvm_cpuid_entry2 entries[0]; -}; + }; -#define KVM_CPUID_FLAG_SIGNIFCANT_INDEX BIT(0) -#define KVM_CPUID_FLAG_STATEFUL_FUNC BIT(1) -#define KVM_CPUID_FLAG_STATE_READ_NEXT BIT(2) + #define KVM_CPUID_FLAG_SIGNIFCANT_INDEX BIT(0) + #define KVM_CPUID_FLAG_STATEFUL_FUNC BIT(1) + #define KVM_CPUID_FLAG_STATE_READ_NEXT BIT(2) -struct kvm_cpuid_entry2 { + struct kvm_cpuid_entry2 { __u32 function; __u32 index; __u32 flags; @@ -1439,7 +1586,7 @@ struct kvm_cpuid_entry2 { __u32 ecx; __u32 edx; __u32 padding[3]; -}; + }; This ioctl returns x86 cpuid features which are supported by both the hardware and kvm in its default configuration. Userspace can use the @@ -1467,10 +1614,16 @@ with unknown or unsupported features masked out. Some features (for example, x2apic), may not be present in the host cpu, but are exposed by kvm if it can emulate them efficiently. The fields in each entry are defined as follows: - function: the eax value used to obtain the entry - index: the ecx value used to obtain the entry (for entries that are + function: + the eax value used to obtain the entry + + index: + the ecx value used to obtain the entry (for entries that are affected by ecx) - flags: an OR of zero or more of the following: + + flags: + an OR of zero or more of the following: + KVM_CPUID_FLAG_SIGNIFCANT_INDEX: if the index field is valid KVM_CPUID_FLAG_STATEFUL_FUNC: @@ -1480,12 +1633,14 @@ emulate them efficiently. The fields in each entry are defined as follows: KVM_CPUID_FLAG_STATE_READ_NEXT: for KVM_CPUID_FLAG_STATEFUL_FUNC entries, set if this entry is the first entry to be read by a cpu - eax, ebx, ecx, edx: the values returned by the cpuid instruction for + + eax, ebx, ecx, edx: + the values returned by the cpuid instruction for this function/index combination The TSC deadline timer feature (CPUID leaf 1, ecx[24]) is always returned as false, since the feature depends on KVM_CREATE_IRQCHIP for local APIC -support. Instead it is reported via +support. Instead it is reported via:: ioctl(KVM_CHECK_EXTENSION, KVM_CAP_TSC_DEADLINE_TIMER) @@ -1494,18 +1649,21 @@ feature in userspace, then you can enable the feature for KVM_SET_CPUID2. 4.47 KVM_PPC_GET_PVINFO +----------------------- + +:Capability: KVM_CAP_PPC_GET_PVINFO +:Architectures: ppc +:Type: vm ioctl +:Parameters: struct kvm_ppc_pvinfo (out) +:Returns: 0 on success, !0 on error -Capability: KVM_CAP_PPC_GET_PVINFO -Architectures: ppc -Type: vm ioctl -Parameters: struct kvm_ppc_pvinfo (out) -Returns: 0 on success, !0 on error +:: -struct kvm_ppc_pvinfo { + struct kvm_ppc_pvinfo { __u32 flags; __u32 hcall[4]; __u8 pad[108]; -}; + }; This ioctl fetches PV specific information that need to be passed to the guest using the device tree or other means from vm context. @@ -1515,33 +1673,39 @@ The hcall array defines 4 instructions that make up a hypercall. If any additional field gets added to this structure later on, a bit for that additional piece of information will be set in the flags bitmap. -The flags bitmap is defined as: +The flags bitmap is defined as:: /* the host supports the ePAPR idle hcall #define KVM_PPC_PVINFO_FLAGS_EV_IDLE (1<<0) 4.52 KVM_SET_GSI_ROUTING +------------------------ -Capability: KVM_CAP_IRQ_ROUTING -Architectures: x86 s390 arm arm64 -Type: vm ioctl -Parameters: struct kvm_irq_routing (in) -Returns: 0 on success, -1 on error +:Capability: KVM_CAP_IRQ_ROUTING +:Architectures: x86 s390 arm arm64 +:Type: vm ioctl +:Parameters: struct kvm_irq_routing (in) +:Returns: 0 on success, -1 on error Sets the GSI routing table entries, overwriting any previously set entries. On arm/arm64, GSI routing has the following limitation: + - GSI routing does not apply to KVM_IRQ_LINE but only to KVM_IRQFD. -struct kvm_irq_routing { +:: + + struct kvm_irq_routing { __u32 nr; __u32 flags; struct kvm_irq_routing_entry entries[0]; -}; + }; No flags are specified so far, the corresponding field must be set to zero. -struct kvm_irq_routing_entry { +:: + + struct kvm_irq_routing_entry { __u32 gsi; __u32 type; __u32 flags; @@ -1553,15 +1717,16 @@ struct kvm_irq_routing_entry { struct kvm_irq_routing_hv_sint hv_sint; __u32 pad[8]; } u; -}; + }; -/* gsi routing entry types */ -#define KVM_IRQ_ROUTING_IRQCHIP 1 -#define KVM_IRQ_ROUTING_MSI 2 -#define KVM_IRQ_ROUTING_S390_ADAPTER 3 -#define KVM_IRQ_ROUTING_HV_SINT 4 + /* gsi routing entry types */ + #define KVM_IRQ_ROUTING_IRQCHIP 1 + #define KVM_IRQ_ROUTING_MSI 2 + #define KVM_IRQ_ROUTING_S390_ADAPTER 3 + #define KVM_IRQ_ROUTING_HV_SINT 4 flags: + - KVM_MSI_VALID_DEVID: used along with KVM_IRQ_ROUTING_MSI routing entry type, specifies that the devid field contains a valid value. The per-VM KVM_CAP_MSI_DEVID capability advertises the requirement to provide @@ -1569,12 +1734,14 @@ flags: never set the KVM_MSI_VALID_DEVID flag as the ioctl might fail. - zero otherwise -struct kvm_irq_routing_irqchip { +:: + + struct kvm_irq_routing_irqchip { __u32 irqchip; __u32 pin; -}; + }; -struct kvm_irq_routing_msi { + struct kvm_irq_routing_msi { __u32 address_lo; __u32 address_hi; __u32 data; @@ -1582,7 +1749,7 @@ struct kvm_irq_routing_msi { __u32 pad; __u32 devid; }; -}; + }; If KVM_MSI_VALID_DEVID is set, devid contains a unique device identifier for the device that wrote the MSI message. For PCI, this is usually a @@ -1593,39 +1760,43 @@ feature of KVM_CAP_X2APIC_API capability is enabled. If it is enabled, address_hi bits 31-8 provide bits 31-8 of the destination id. Bits 7-0 of address_hi must be zero. -struct kvm_irq_routing_s390_adapter { +:: + + struct kvm_irq_routing_s390_adapter { __u64 ind_addr; __u64 summary_addr; __u64 ind_offset; __u32 summary_offset; __u32 adapter_id; -}; + }; -struct kvm_irq_routing_hv_sint { + struct kvm_irq_routing_hv_sint { __u32 vcpu; __u32 sint; -}; + }; 4.55 KVM_SET_TSC_KHZ +-------------------- -Capability: KVM_CAP_TSC_CONTROL -Architectures: x86 -Type: vcpu ioctl -Parameters: virtual tsc_khz -Returns: 0 on success, -1 on error +:Capability: KVM_CAP_TSC_CONTROL +:Architectures: x86 +:Type: vcpu ioctl +:Parameters: virtual tsc_khz +:Returns: 0 on success, -1 on error Specifies the tsc frequency for the virtual machine. The unit of the frequency is KHz. 4.56 KVM_GET_TSC_KHZ +-------------------- -Capability: KVM_CAP_GET_TSC_KHZ -Architectures: x86 -Type: vcpu ioctl -Parameters: none -Returns: virtual tsc-khz on success, negative value on error +:Capability: KVM_CAP_GET_TSC_KHZ +:Architectures: x86 +:Type: vcpu ioctl +:Parameters: none +:Returns: virtual tsc-khz on success, negative value on error Returns the tsc frequency of the guest. The unit of the return value is KHz. If the host has unstable tsc this ioctl returns -EIO instead as an @@ -1633,17 +1804,20 @@ error. 4.57 KVM_GET_LAPIC +------------------ -Capability: KVM_CAP_IRQCHIP -Architectures: x86 -Type: vcpu ioctl -Parameters: struct kvm_lapic_state (out) -Returns: 0 on success, -1 on error +:Capability: KVM_CAP_IRQCHIP +:Architectures: x86 +:Type: vcpu ioctl +:Parameters: struct kvm_lapic_state (out) +:Returns: 0 on success, -1 on error -#define KVM_APIC_REG_SIZE 0x400 -struct kvm_lapic_state { +:: + + #define KVM_APIC_REG_SIZE 0x400 + struct kvm_lapic_state { char regs[KVM_APIC_REG_SIZE]; -}; + }; Reads the Local APIC registers and copies them into the input argument. The data format and layout are the same as documented in the architecture manual. @@ -1661,17 +1835,20 @@ always uses xAPIC format. 4.58 KVM_SET_LAPIC +------------------ + +:Capability: KVM_CAP_IRQCHIP +:Architectures: x86 +:Type: vcpu ioctl +:Parameters: struct kvm_lapic_state (in) +:Returns: 0 on success, -1 on error -Capability: KVM_CAP_IRQCHIP -Architectures: x86 -Type: vcpu ioctl -Parameters: struct kvm_lapic_state (in) -Returns: 0 on success, -1 on error +:: -#define KVM_APIC_REG_SIZE 0x400 -struct kvm_lapic_state { + #define KVM_APIC_REG_SIZE 0x400 + struct kvm_lapic_state { char regs[KVM_APIC_REG_SIZE]; -}; + }; Copies the input argument into the Local APIC registers. The data format and layout are the same as documented in the architecture manual. @@ -1682,35 +1859,38 @@ See the note in KVM_GET_LAPIC. 4.59 KVM_IOEVENTFD +------------------ -Capability: KVM_CAP_IOEVENTFD -Architectures: all -Type: vm ioctl -Parameters: struct kvm_ioeventfd (in) -Returns: 0 on success, !0 on error +:Capability: KVM_CAP_IOEVENTFD +:Architectures: all +:Type: vm ioctl +:Parameters: struct kvm_ioeventfd (in) +:Returns: 0 on success, !0 on error This ioctl attaches or detaches an ioeventfd to a legal pio/mmio address within the guest. A guest write in the registered address will signal the provided event instead of triggering an exit. -struct kvm_ioeventfd { +:: + + struct kvm_ioeventfd { __u64 datamatch; __u64 addr; /* legal pio/mmio address */ __u32 len; /* 0, 1, 2, 4, or 8 bytes */ __s32 fd; __u32 flags; __u8 pad[36]; -}; + }; For the special case of virtio-ccw devices on s390, the ioevent is matched to a subchannel/virtqueue tuple instead. -The following flags are defined: +The following flags are defined:: -#define KVM_IOEVENTFD_FLAG_DATAMATCH (1 << kvm_ioeventfd_flag_nr_datamatch) -#define KVM_IOEVENTFD_FLAG_PIO (1 << kvm_ioeventfd_flag_nr_pio) -#define KVM_IOEVENTFD_FLAG_DEASSIGN (1 << kvm_ioeventfd_flag_nr_deassign) -#define KVM_IOEVENTFD_FLAG_VIRTIO_CCW_NOTIFY \ + #define KVM_IOEVENTFD_FLAG_DATAMATCH (1 << kvm_ioeventfd_flag_nr_datamatch) + #define KVM_IOEVENTFD_FLAG_PIO (1 << kvm_ioeventfd_flag_nr_pio) + #define KVM_IOEVENTFD_FLAG_DEASSIGN (1 << kvm_ioeventfd_flag_nr_deassign) + #define KVM_IOEVENTFD_FLAG_VIRTIO_CCW_NOTIFY \ (1 << kvm_ioeventfd_flag_nr_virtio_ccw_notify) If datamatch flag is set, the event will be signaled only if the written value @@ -1725,17 +1905,20 @@ The speedup may only apply to specific architectures, but the ioeventfd will work anyway. 4.60 KVM_DIRTY_TLB +------------------ + +:Capability: KVM_CAP_SW_TLB +:Architectures: ppc +:Type: vcpu ioctl +:Parameters: struct kvm_dirty_tlb (in) +:Returns: 0 on success, -1 on error -Capability: KVM_CAP_SW_TLB -Architectures: ppc -Type: vcpu ioctl -Parameters: struct kvm_dirty_tlb (in) -Returns: 0 on success, -1 on error +:: -struct kvm_dirty_tlb { + struct kvm_dirty_tlb { __u64 bitmap; __u32 num_dirty; -}; + }; This must be called whenever userspace has changed an entry in the shared TLB, prior to calling KVM_RUN on the associated vcpu. @@ -1758,23 +1941,26 @@ be set to the number of set bits in the bitmap. 4.62 KVM_CREATE_SPAPR_TCE +------------------------- -Capability: KVM_CAP_SPAPR_TCE -Architectures: powerpc -Type: vm ioctl -Parameters: struct kvm_create_spapr_tce (in) -Returns: file descriptor for manipulating the created TCE table +:Capability: KVM_CAP_SPAPR_TCE +:Architectures: powerpc +:Type: vm ioctl +:Parameters: struct kvm_create_spapr_tce (in) +:Returns: file descriptor for manipulating the created TCE table This creates a virtual TCE (translation control entry) table, which is an IOMMU for PAPR-style virtual I/O. It is used to translate logical addresses used in virtual I/O into guest physical addresses, and provides a scatter/gather capability for PAPR virtual I/O. -/* for KVM_CAP_SPAPR_TCE */ -struct kvm_create_spapr_tce { +:: + + /* for KVM_CAP_SPAPR_TCE */ + struct kvm_create_spapr_tce { __u64 liobn; __u32 window_size; -}; + }; The liobn field gives the logical IO bus number for which to create a TCE table. The window_size field specifies the size of the DMA window @@ -1794,12 +1980,13 @@ circumstances. 4.63 KVM_ALLOCATE_RMA +--------------------- -Capability: KVM_CAP_PPC_RMA -Architectures: powerpc -Type: vm ioctl -Parameters: struct kvm_allocate_rma (out) -Returns: file descriptor for mapping the allocated RMA +:Capability: KVM_CAP_PPC_RMA +:Architectures: powerpc +:Type: vm ioctl +:Parameters: struct kvm_allocate_rma (out) +:Returns: file descriptor for mapping the allocated RMA This allocates a Real Mode Area (RMA) from the pool allocated at boot time by the kernel. An RMA is a physically-contiguous, aligned region @@ -1808,10 +1995,12 @@ will be accessed by real-mode (MMU off) accesses in a KVM guest. POWER processors support a set of sizes for the RMA that usually includes 64MB, 128MB, 256MB and some larger powers of two. -/* for KVM_ALLOCATE_RMA */ -struct kvm_allocate_rma { +:: + + /* for KVM_ALLOCATE_RMA */ + struct kvm_allocate_rma { __u64 rma_size; -}; + }; The return value is a file descriptor which can be passed to mmap(2) to map the allocated RMA into userspace. The mapped area can then be @@ -1827,12 +2016,13 @@ because it supports the Virtual RMA (VRMA) facility. 4.64 KVM_NMI +------------ -Capability: KVM_CAP_USER_NMI -Architectures: x86 -Type: vcpu ioctl -Parameters: none -Returns: 0 on success, -1 on error +:Capability: KVM_CAP_USER_NMI +:Architectures: x86 +:Type: vcpu ioctl +:Parameters: none +:Returns: 0 on success, -1 on error Queues an NMI on the thread's vcpu. Note this is well defined only when KVM_CREATE_IRQCHIP has not been called, since this is an interface @@ -1853,14 +2043,16 @@ debugging. 4.65 KVM_S390_UCAS_MAP +---------------------- -Capability: KVM_CAP_S390_UCONTROL -Architectures: s390 -Type: vcpu ioctl -Parameters: struct kvm_s390_ucas_mapping (in) -Returns: 0 in case of success +:Capability: KVM_CAP_S390_UCONTROL +:Architectures: s390 +:Type: vcpu ioctl +:Parameters: struct kvm_s390_ucas_mapping (in) +:Returns: 0 in case of success + +The parameter is defined like this:: -The parameter is defined like this: struct kvm_s390_ucas_mapping { __u64 user_addr; __u64 vcpu_addr; @@ -1873,14 +2065,16 @@ be aligned by 1 megabyte. 4.66 KVM_S390_UCAS_UNMAP +------------------------ -Capability: KVM_CAP_S390_UCONTROL -Architectures: s390 -Type: vcpu ioctl -Parameters: struct kvm_s390_ucas_mapping (in) -Returns: 0 in case of success +:Capability: KVM_CAP_S390_UCONTROL +:Architectures: s390 +:Type: vcpu ioctl +:Parameters: struct kvm_s390_ucas_mapping (in) +:Returns: 0 in case of success + +The parameter is defined like this:: -The parameter is defined like this: struct kvm_s390_ucas_mapping { __u64 user_addr; __u64 vcpu_addr; @@ -1893,12 +2087,13 @@ All parameters need to be aligned by 1 megabyte. 4.67 KVM_S390_VCPU_FAULT +------------------------ -Capability: KVM_CAP_S390_UCONTROL -Architectures: s390 -Type: vcpu ioctl -Parameters: vcpu absolute address (in) -Returns: 0 in case of success +:Capability: KVM_CAP_S390_UCONTROL +:Architectures: s390 +:Type: vcpu ioctl +:Parameters: vcpu absolute address (in) +:Returns: 0 in case of success This call creates a page table entry on the virtual cpu's address space (for user controlled virtual machines) or the virtual machine's address @@ -1910,23 +2105,31 @@ prior to calling the KVM_RUN ioctl. 4.68 KVM_SET_ONE_REG +-------------------- + +:Capability: KVM_CAP_ONE_REG +:Architectures: all +:Type: vcpu ioctl +:Parameters: struct kvm_one_reg (in) +:Returns: 0 on success, negative value on failure -Capability: KVM_CAP_ONE_REG -Architectures: all -Type: vcpu ioctl -Parameters: struct kvm_one_reg (in) -Returns: 0 on success, negative value on failure Errors: -  ENOENT:   no such register -  EINVAL:   invalid register ID, or no such register -  EPERM:    (arm64) register access not allowed before vcpu finalization + + ====== ============================================================ +  ENOENT   no such register +  EINVAL   invalid register ID, or no such register +  EPERM    (arm64) register access not allowed before vcpu finalization + ====== ============================================================ + (These error codes are indicative only: do not rely on a specific error code being returned in a specific situation.) -struct kvm_one_reg { +:: + + struct kvm_one_reg { __u64 id; __u64 addr; -}; + }; Using this ioctl, a single vcpu register can be set to a specific value defined by user space with the passed in struct kvm_one_reg, where id @@ -1936,217 +2139,226 @@ and architecture specific registers. Each have their own range of operation and their own constants and width. To keep track of the implemented registers, find a list below: - Arch | Register | Width (bits) - | | - PPC | KVM_REG_PPC_HIOR | 64 - PPC | KVM_REG_PPC_IAC1 | 64 - PPC | KVM_REG_PPC_IAC2 | 64 - PPC | KVM_REG_PPC_IAC3 | 64 - PPC | KVM_REG_PPC_IAC4 | 64 - PPC | KVM_REG_PPC_DAC1 | 64 - PPC | KVM_REG_PPC_DAC2 | 64 - PPC | KVM_REG_PPC_DABR | 64 - PPC | KVM_REG_PPC_DSCR | 64 - PPC | KVM_REG_PPC_PURR | 64 - PPC | KVM_REG_PPC_SPURR | 64 - PPC | KVM_REG_PPC_DAR | 64 - PPC | KVM_REG_PPC_DSISR | 32 - PPC | KVM_REG_PPC_AMR | 64 - PPC | KVM_REG_PPC_UAMOR | 64 - PPC | KVM_REG_PPC_MMCR0 | 64 - PPC | KVM_REG_PPC_MMCR1 | 64 - PPC | KVM_REG_PPC_MMCRA | 64 - PPC | KVM_REG_PPC_MMCR2 | 64 - PPC | KVM_REG_PPC_MMCRS | 64 - PPC | KVM_REG_PPC_SIAR | 64 - PPC | KVM_REG_PPC_SDAR | 64 - PPC | KVM_REG_PPC_SIER | 64 - PPC | KVM_REG_PPC_PMC1 | 32 - PPC | KVM_REG_PPC_PMC2 | 32 - PPC | KVM_REG_PPC_PMC3 | 32 - PPC | KVM_REG_PPC_PMC4 | 32 - PPC | KVM_REG_PPC_PMC5 | 32 - PPC | KVM_REG_PPC_PMC6 | 32 - PPC | KVM_REG_PPC_PMC7 | 32 - PPC | KVM_REG_PPC_PMC8 | 32 - PPC | KVM_REG_PPC_FPR0 | 64 - ... - PPC | KVM_REG_PPC_FPR31 | 64 - PPC | KVM_REG_PPC_VR0 | 128 - ... - PPC | KVM_REG_PPC_VR31 | 128 - PPC | KVM_REG_PPC_VSR0 | 128 - ... - PPC | KVM_REG_PPC_VSR31 | 128 - PPC | KVM_REG_PPC_FPSCR | 64 - PPC | KVM_REG_PPC_VSCR | 32 - PPC | KVM_REG_PPC_VPA_ADDR | 64 - PPC | KVM_REG_PPC_VPA_SLB | 128 - PPC | KVM_REG_PPC_VPA_DTL | 128 - PPC | KVM_REG_PPC_EPCR | 32 - PPC | KVM_REG_PPC_EPR | 32 - PPC | KVM_REG_PPC_TCR | 32 - PPC | KVM_REG_PPC_TSR | 32 - PPC | KVM_REG_PPC_OR_TSR | 32 - PPC | KVM_REG_PPC_CLEAR_TSR | 32 - PPC | KVM_REG_PPC_MAS0 | 32 - PPC | KVM_REG_PPC_MAS1 | 32 - PPC | KVM_REG_PPC_MAS2 | 64 - PPC | KVM_REG_PPC_MAS7_3 | 64 - PPC | KVM_REG_PPC_MAS4 | 32 - PPC | KVM_REG_PPC_MAS6 | 32 - PPC | KVM_REG_PPC_MMUCFG | 32 - PPC | KVM_REG_PPC_TLB0CFG | 32 - PPC | KVM_REG_PPC_TLB1CFG | 32 - PPC | KVM_REG_PPC_TLB2CFG | 32 - PPC | KVM_REG_PPC_TLB3CFG | 32 - PPC | KVM_REG_PPC_TLB0PS | 32 - PPC | KVM_REG_PPC_TLB1PS | 32 - PPC | KVM_REG_PPC_TLB2PS | 32 - PPC | KVM_REG_PPC_TLB3PS | 32 - PPC | KVM_REG_PPC_EPTCFG | 32 - PPC | KVM_REG_PPC_ICP_STATE | 64 - PPC | KVM_REG_PPC_VP_STATE | 128 - PPC | KVM_REG_PPC_TB_OFFSET | 64 - PPC | KVM_REG_PPC_SPMC1 | 32 - PPC | KVM_REG_PPC_SPMC2 | 32 - PPC | KVM_REG_PPC_IAMR | 64 - PPC | KVM_REG_PPC_TFHAR | 64 - PPC | KVM_REG_PPC_TFIAR | 64 - PPC | KVM_REG_PPC_TEXASR | 64 - PPC | KVM_REG_PPC_FSCR | 64 - PPC | KVM_REG_PPC_PSPB | 32 - PPC | KVM_REG_PPC_EBBHR | 64 - PPC | KVM_REG_PPC_EBBRR | 64 - PPC | KVM_REG_PPC_BESCR | 64 - PPC | KVM_REG_PPC_TAR | 64 - PPC | KVM_REG_PPC_DPDES | 64 - PPC | KVM_REG_PPC_DAWR | 64 - PPC | KVM_REG_PPC_DAWRX | 64 - PPC | KVM_REG_PPC_CIABR | 64 - PPC | KVM_REG_PPC_IC | 64 - PPC | KVM_REG_PPC_VTB | 64 - PPC | KVM_REG_PPC_CSIGR | 64 - PPC | KVM_REG_PPC_TACR | 64 - PPC | KVM_REG_PPC_TCSCR | 64 - PPC | KVM_REG_PPC_PID | 64 - PPC | KVM_REG_PPC_ACOP | 64 - PPC | KVM_REG_PPC_VRSAVE | 32 - PPC | KVM_REG_PPC_LPCR | 32 - PPC | KVM_REG_PPC_LPCR_64 | 64 - PPC | KVM_REG_PPC_PPR | 64 - PPC | KVM_REG_PPC_ARCH_COMPAT | 32 - PPC | KVM_REG_PPC_DABRX | 32 - PPC | KVM_REG_PPC_WORT | 64 - PPC | KVM_REG_PPC_SPRG9 | 64 - PPC | KVM_REG_PPC_DBSR | 32 - PPC | KVM_REG_PPC_TIDR | 64 - PPC | KVM_REG_PPC_PSSCR | 64 - PPC | KVM_REG_PPC_DEC_EXPIRY | 64 - PPC | KVM_REG_PPC_PTCR | 64 - PPC | KVM_REG_PPC_TM_GPR0 | 64 - ... - PPC | KVM_REG_PPC_TM_GPR31 | 64 - PPC | KVM_REG_PPC_TM_VSR0 | 128 - ... - PPC | KVM_REG_PPC_TM_VSR63 | 128 - PPC | KVM_REG_PPC_TM_CR | 64 - PPC | KVM_REG_PPC_TM_LR | 64 - PPC | KVM_REG_PPC_TM_CTR | 64 - PPC | KVM_REG_PPC_TM_FPSCR | 64 - PPC | KVM_REG_PPC_TM_AMR | 64 - PPC | KVM_REG_PPC_TM_PPR | 64 - PPC | KVM_REG_PPC_TM_VRSAVE | 64 - PPC | KVM_REG_PPC_TM_VSCR | 32 - PPC | KVM_REG_PPC_TM_DSCR | 64 - PPC | KVM_REG_PPC_TM_TAR | 64 - PPC | KVM_REG_PPC_TM_XER | 64 - | | - MIPS | KVM_REG_MIPS_R0 | 64 - ... - MIPS | KVM_REG_MIPS_R31 | 64 - MIPS | KVM_REG_MIPS_HI | 64 - MIPS | KVM_REG_MIPS_LO | 64 - MIPS | KVM_REG_MIPS_PC | 64 - MIPS | KVM_REG_MIPS_CP0_INDEX | 32 - MIPS | KVM_REG_MIPS_CP0_ENTRYLO0 | 64 - MIPS | KVM_REG_MIPS_CP0_ENTRYLO1 | 64 - MIPS | KVM_REG_MIPS_CP0_CONTEXT | 64 - MIPS | KVM_REG_MIPS_CP0_CONTEXTCONFIG| 32 - MIPS | KVM_REG_MIPS_CP0_USERLOCAL | 64 - MIPS | KVM_REG_MIPS_CP0_XCONTEXTCONFIG| 64 - MIPS | KVM_REG_MIPS_CP0_PAGEMASK | 32 - MIPS | KVM_REG_MIPS_CP0_PAGEGRAIN | 32 - MIPS | KVM_REG_MIPS_CP0_SEGCTL0 | 64 - MIPS | KVM_REG_MIPS_CP0_SEGCTL1 | 64 - MIPS | KVM_REG_MIPS_CP0_SEGCTL2 | 64 - MIPS | KVM_REG_MIPS_CP0_PWBASE | 64 - MIPS | KVM_REG_MIPS_CP0_PWFIELD | 64 - MIPS | KVM_REG_MIPS_CP0_PWSIZE | 64 - MIPS | KVM_REG_MIPS_CP0_WIRED | 32 - MIPS | KVM_REG_MIPS_CP0_PWCTL | 32 - MIPS | KVM_REG_MIPS_CP0_HWRENA | 32 - MIPS | KVM_REG_MIPS_CP0_BADVADDR | 64 - MIPS | KVM_REG_MIPS_CP0_BADINSTR | 32 - MIPS | KVM_REG_MIPS_CP0_BADINSTRP | 32 - MIPS | KVM_REG_MIPS_CP0_COUNT | 32 - MIPS | KVM_REG_MIPS_CP0_ENTRYHI | 64 - MIPS | KVM_REG_MIPS_CP0_COMPARE | 32 - MIPS | KVM_REG_MIPS_CP0_STATUS | 32 - MIPS | KVM_REG_MIPS_CP0_INTCTL | 32 - MIPS | KVM_REG_MIPS_CP0_CAUSE | 32 - MIPS | KVM_REG_MIPS_CP0_EPC | 64 - MIPS | KVM_REG_MIPS_CP0_PRID | 32 - MIPS | KVM_REG_MIPS_CP0_EBASE | 64 - MIPS | KVM_REG_MIPS_CP0_CONFIG | 32 - MIPS | KVM_REG_MIPS_CP0_CONFIG1 | 32 - MIPS | KVM_REG_MIPS_CP0_CONFIG2 | 32 - MIPS | KVM_REG_MIPS_CP0_CONFIG3 | 32 - MIPS | KVM_REG_MIPS_CP0_CONFIG4 | 32 - MIPS | KVM_REG_MIPS_CP0_CONFIG5 | 32 - MIPS | KVM_REG_MIPS_CP0_CONFIG7 | 32 - MIPS | KVM_REG_MIPS_CP0_XCONTEXT | 64 - MIPS | KVM_REG_MIPS_CP0_ERROREPC | 64 - MIPS | KVM_REG_MIPS_CP0_KSCRATCH1 | 64 - MIPS | KVM_REG_MIPS_CP0_KSCRATCH2 | 64 - MIPS | KVM_REG_MIPS_CP0_KSCRATCH3 | 64 - MIPS | KVM_REG_MIPS_CP0_KSCRATCH4 | 64 - MIPS | KVM_REG_MIPS_CP0_KSCRATCH5 | 64 - MIPS | KVM_REG_MIPS_CP0_KSCRATCH6 | 64 - MIPS | KVM_REG_MIPS_CP0_MAAR(0..63) | 64 - MIPS | KVM_REG_MIPS_COUNT_CTL | 64 - MIPS | KVM_REG_MIPS_COUNT_RESUME | 64 - MIPS | KVM_REG_MIPS_COUNT_HZ | 64 - MIPS | KVM_REG_MIPS_FPR_32(0..31) | 32 - MIPS | KVM_REG_MIPS_FPR_64(0..31) | 64 - MIPS | KVM_REG_MIPS_VEC_128(0..31) | 128 - MIPS | KVM_REG_MIPS_FCR_IR | 32 - MIPS | KVM_REG_MIPS_FCR_CSR | 32 - MIPS | KVM_REG_MIPS_MSA_IR | 32 - MIPS | KVM_REG_MIPS_MSA_CSR | 32 + ======= =============================== ============ + Arch Register Width (bits) + ======= =============================== ============ + PPC KVM_REG_PPC_HIOR 64 + PPC KVM_REG_PPC_IAC1 64 + PPC KVM_REG_PPC_IAC2 64 + PPC KVM_REG_PPC_IAC3 64 + PPC KVM_REG_PPC_IAC4 64 + PPC KVM_REG_PPC_DAC1 64 + PPC KVM_REG_PPC_DAC2 64 + PPC KVM_REG_PPC_DABR 64 + PPC KVM_REG_PPC_DSCR 64 + PPC KVM_REG_PPC_PURR 64 + PPC KVM_REG_PPC_SPURR 64 + PPC KVM_REG_PPC_DAR 64 + PPC KVM_REG_PPC_DSISR 32 + PPC KVM_REG_PPC_AMR 64 + PPC KVM_REG_PPC_UAMOR 64 + PPC KVM_REG_PPC_MMCR0 64 + PPC KVM_REG_PPC_MMCR1 64 + PPC KVM_REG_PPC_MMCRA 64 + PPC KVM_REG_PPC_MMCR2 64 + PPC KVM_REG_PPC_MMCRS 64 + PPC KVM_REG_PPC_SIAR 64 + PPC KVM_REG_PPC_SDAR 64 + PPC KVM_REG_PPC_SIER 64 + PPC KVM_REG_PPC_PMC1 32 + PPC KVM_REG_PPC_PMC2 32 + PPC KVM_REG_PPC_PMC3 32 + PPC KVM_REG_PPC_PMC4 32 + PPC KVM_REG_PPC_PMC5 32 + PPC KVM_REG_PPC_PMC6 32 + PPC KVM_REG_PPC_PMC7 32 + PPC KVM_REG_PPC_PMC8 32 + PPC KVM_REG_PPC_FPR0 64 + ... + PPC KVM_REG_PPC_FPR31 64 + PPC KVM_REG_PPC_VR0 128 + ... + PPC KVM_REG_PPC_VR31 128 + PPC KVM_REG_PPC_VSR0 128 + ... + PPC KVM_REG_PPC_VSR31 128 + PPC KVM_REG_PPC_FPSCR 64 + PPC KVM_REG_PPC_VSCR 32 + PPC KVM_REG_PPC_VPA_ADDR 64 + PPC KVM_REG_PPC_VPA_SLB 128 + PPC KVM_REG_PPC_VPA_DTL 128 + PPC KVM_REG_PPC_EPCR 32 + PPC KVM_REG_PPC_EPR 32 + PPC KVM_REG_PPC_TCR 32 + PPC KVM_REG_PPC_TSR 32 + PPC KVM_REG_PPC_OR_TSR 32 + PPC KVM_REG_PPC_CLEAR_TSR 32 + PPC KVM_REG_PPC_MAS0 32 + PPC KVM_REG_PPC_MAS1 32 + PPC KVM_REG_PPC_MAS2 64 + PPC KVM_REG_PPC_MAS7_3 64 + PPC KVM_REG_PPC_MAS4 32 + PPC KVM_REG_PPC_MAS6 32 + PPC KVM_REG_PPC_MMUCFG 32 + PPC KVM_REG_PPC_TLB0CFG 32 + PPC KVM_REG_PPC_TLB1CFG 32 + PPC KVM_REG_PPC_TLB2CFG 32 + PPC KVM_REG_PPC_TLB3CFG 32 + PPC KVM_REG_PPC_TLB0PS 32 + PPC KVM_REG_PPC_TLB1PS 32 + PPC KVM_REG_PPC_TLB2PS 32 + PPC KVM_REG_PPC_TLB3PS 32 + PPC KVM_REG_PPC_EPTCFG 32 + PPC KVM_REG_PPC_ICP_STATE 64 + PPC KVM_REG_PPC_VP_STATE 128 + PPC KVM_REG_PPC_TB_OFFSET 64 + PPC KVM_REG_PPC_SPMC1 32 + PPC KVM_REG_PPC_SPMC2 32 + PPC KVM_REG_PPC_IAMR 64 + PPC KVM_REG_PPC_TFHAR 64 + PPC KVM_REG_PPC_TFIAR 64 + PPC KVM_REG_PPC_TEXASR 64 + PPC KVM_REG_PPC_FSCR 64 + PPC KVM_REG_PPC_PSPB 32 + PPC KVM_REG_PPC_EBBHR 64 + PPC KVM_REG_PPC_EBBRR 64 + PPC KVM_REG_PPC_BESCR 64 + PPC KVM_REG_PPC_TAR 64 + PPC KVM_REG_PPC_DPDES 64 + PPC KVM_REG_PPC_DAWR 64 + PPC KVM_REG_PPC_DAWRX 64 + PPC KVM_REG_PPC_CIABR 64 + PPC KVM_REG_PPC_IC 64 + PPC KVM_REG_PPC_VTB 64 + PPC KVM_REG_PPC_CSIGR 64 + PPC KVM_REG_PPC_TACR 64 + PPC KVM_REG_PPC_TCSCR 64 + PPC KVM_REG_PPC_PID 64 + PPC KVM_REG_PPC_ACOP 64 + PPC KVM_REG_PPC_VRSAVE 32 + PPC KVM_REG_PPC_LPCR 32 + PPC KVM_REG_PPC_LPCR_64 64 + PPC KVM_REG_PPC_PPR 64 + PPC KVM_REG_PPC_ARCH_COMPAT 32 + PPC KVM_REG_PPC_DABRX 32 + PPC KVM_REG_PPC_WORT 64 + PPC KVM_REG_PPC_SPRG9 64 + PPC KVM_REG_PPC_DBSR 32 + PPC KVM_REG_PPC_TIDR 64 + PPC KVM_REG_PPC_PSSCR 64 + PPC KVM_REG_PPC_DEC_EXPIRY 64 + PPC KVM_REG_PPC_PTCR 64 + PPC KVM_REG_PPC_TM_GPR0 64 + ... + PPC KVM_REG_PPC_TM_GPR31 64 + PPC KVM_REG_PPC_TM_VSR0 128 + ... + PPC KVM_REG_PPC_TM_VSR63 128 + PPC KVM_REG_PPC_TM_CR 64 + PPC KVM_REG_PPC_TM_LR 64 + PPC KVM_REG_PPC_TM_CTR 64 + PPC KVM_REG_PPC_TM_FPSCR 64 + PPC KVM_REG_PPC_TM_AMR 64 + PPC KVM_REG_PPC_TM_PPR 64 + PPC KVM_REG_PPC_TM_VRSAVE 64 + PPC KVM_REG_PPC_TM_VSCR 32 + PPC KVM_REG_PPC_TM_DSCR 64 + PPC KVM_REG_PPC_TM_TAR 64 + PPC KVM_REG_PPC_TM_XER 64 + + MIPS KVM_REG_MIPS_R0 64 + ... + MIPS KVM_REG_MIPS_R31 64 + MIPS KVM_REG_MIPS_HI 64 + MIPS KVM_REG_MIPS_LO 64 + MIPS KVM_REG_MIPS_PC 64 + MIPS KVM_REG_MIPS_CP0_INDEX 32 + MIPS KVM_REG_MIPS_CP0_ENTRYLO0 64 + MIPS KVM_REG_MIPS_CP0_ENTRYLO1 64 + MIPS KVM_REG_MIPS_CP0_CONTEXT 64 + MIPS KVM_REG_MIPS_CP0_CONTEXTCONFIG 32 + MIPS KVM_REG_MIPS_CP0_USERLOCAL 64 + MIPS KVM_REG_MIPS_CP0_XCONTEXTCONFIG 64 + MIPS KVM_REG_MIPS_CP0_PAGEMASK 32 + MIPS KVM_REG_MIPS_CP0_PAGEGRAIN 32 + MIPS KVM_REG_MIPS_CP0_SEGCTL0 64 + MIPS KVM_REG_MIPS_CP0_SEGCTL1 64 + MIPS KVM_REG_MIPS_CP0_SEGCTL2 64 + MIPS KVM_REG_MIPS_CP0_PWBASE 64 + MIPS KVM_REG_MIPS_CP0_PWFIELD 64 + MIPS KVM_REG_MIPS_CP0_PWSIZE 64 + MIPS KVM_REG_MIPS_CP0_WIRED 32 + MIPS KVM_REG_MIPS_CP0_PWCTL 32 + MIPS KVM_REG_MIPS_CP0_HWRENA 32 + MIPS KVM_REG_MIPS_CP0_BADVADDR 64 + MIPS KVM_REG_MIPS_CP0_BADINSTR 32 + MIPS KVM_REG_MIPS_CP0_BADINSTRP 32 + MIPS KVM_REG_MIPS_CP0_COUNT 32 + MIPS KVM_REG_MIPS_CP0_ENTRYHI 64 + MIPS KVM_REG_MIPS_CP0_COMPARE 32 + MIPS KVM_REG_MIPS_CP0_STATUS 32 + MIPS KVM_REG_MIPS_CP0_INTCTL 32 + MIPS KVM_REG_MIPS_CP0_CAUSE 32 + MIPS KVM_REG_MIPS_CP0_EPC 64 + MIPS KVM_REG_MIPS_CP0_PRID 32 + MIPS KVM_REG_MIPS_CP0_EBASE 64 + MIPS KVM_REG_MIPS_CP0_CONFIG 32 + MIPS KVM_REG_MIPS_CP0_CONFIG1 32 + MIPS KVM_REG_MIPS_CP0_CONFIG2 32 + MIPS KVM_REG_MIPS_CP0_CONFIG3 32 + MIPS KVM_REG_MIPS_CP0_CONFIG4 32 + MIPS KVM_REG_MIPS_CP0_CONFIG5 32 + MIPS KVM_REG_MIPS_CP0_CONFIG7 32 + MIPS KVM_REG_MIPS_CP0_XCONTEXT 64 + MIPS KVM_REG_MIPS_CP0_ERROREPC 64 + MIPS KVM_REG_MIPS_CP0_KSCRATCH1 64 + MIPS KVM_REG_MIPS_CP0_KSCRATCH2 64 + MIPS KVM_REG_MIPS_CP0_KSCRATCH3 64 + MIPS KVM_REG_MIPS_CP0_KSCRATCH4 64 + MIPS KVM_REG_MIPS_CP0_KSCRATCH5 64 + MIPS KVM_REG_MIPS_CP0_KSCRATCH6 64 + MIPS KVM_REG_MIPS_CP0_MAAR(0..63) 64 + MIPS KVM_REG_MIPS_COUNT_CTL 64 + MIPS KVM_REG_MIPS_COUNT_RESUME 64 + MIPS KVM_REG_MIPS_COUNT_HZ 64 + MIPS KVM_REG_MIPS_FPR_32(0..31) 32 + MIPS KVM_REG_MIPS_FPR_64(0..31) 64 + MIPS KVM_REG_MIPS_VEC_128(0..31) 128 + MIPS KVM_REG_MIPS_FCR_IR 32 + MIPS KVM_REG_MIPS_FCR_CSR 32 + MIPS KVM_REG_MIPS_MSA_IR 32 + MIPS KVM_REG_MIPS_MSA_CSR 32 + ======= =============================== ============ ARM registers are mapped using the lower 32 bits. The upper 16 of that is the register group type, or coprocessor number: -ARM core registers have the following id bit patterns: +ARM core registers have the following id bit patterns:: + 0x4020 0000 0010 <index into the kvm_regs struct:16> -ARM 32-bit CP15 registers have the following id bit patterns: +ARM 32-bit CP15 registers have the following id bit patterns:: + 0x4020 0000 000F <zero:1> <crn:4> <crm:4> <opc1:4> <opc2:3> -ARM 64-bit CP15 registers have the following id bit patterns: +ARM 64-bit CP15 registers have the following id bit patterns:: + 0x4030 0000 000F <zero:1> <zero:4> <crm:4> <opc1:4> <zero:3> -ARM CCSIDR registers are demultiplexed by CSSELR value: +ARM CCSIDR registers are demultiplexed by CSSELR value:: + 0x4020 0000 0011 00 <csselr:8> -ARM 32-bit VFP control registers have the following id bit patterns: +ARM 32-bit VFP control registers have the following id bit patterns:: + 0x4020 0000 0012 1 <regno:12> -ARM 64-bit FP registers have the following id bit patterns: +ARM 64-bit FP registers have the following id bit patterns:: + 0x4030 0000 0012 0 <regno:12> -ARM firmware pseudo-registers have the following bit pattern: +ARM firmware pseudo-registers have the following bit pattern:: + 0x4030 0000 0014 <regno:16> @@ -2156,15 +2368,18 @@ that is the register group type, or coprocessor number: arm64 core/FP-SIMD registers have the following id bit patterns. Note that the size of the access is variable, as the kvm_regs structure contains elements ranging from 32 to 128 bits. The index is a 32bit -value in the kvm_regs structure seen as a 32bit array. +value in the kvm_regs structure seen as a 32bit array:: + 0x60x0 0000 0010 <index into the kvm_regs struct:16> Specifically: + +======================= ========= ===== ======================================= Encoding Register Bits kvm_regs member ----------------------------------------------------------------- +======================= ========= ===== ======================================= 0x6030 0000 0010 0000 X0 64 regs.regs[0] 0x6030 0000 0010 0002 X1 64 regs.regs[1] - ... + ... 0x6030 0000 0010 003c X30 64 regs.regs[30] 0x6030 0000 0010 003e SP 64 regs.sp 0x6030 0000 0010 0040 PC 64 regs.pc @@ -2176,30 +2391,45 @@ Specifically: 0x6030 0000 0010 004c SPSR_UND 64 spsr[KVM_SPSR_UND] 0x6030 0000 0010 004e SPSR_IRQ 64 spsr[KVM_SPSR_IRQ] 0x6060 0000 0010 0050 SPSR_FIQ 64 spsr[KVM_SPSR_FIQ] - 0x6040 0000 0010 0054 V0 128 fp_regs.vregs[0] (*) - 0x6040 0000 0010 0058 V1 128 fp_regs.vregs[1] (*) - ... - 0x6040 0000 0010 00d0 V31 128 fp_regs.vregs[31] (*) + 0x6040 0000 0010 0054 V0 128 fp_regs.vregs[0] [1]_ + 0x6040 0000 0010 0058 V1 128 fp_regs.vregs[1] [1]_ + ... + 0x6040 0000 0010 00d0 V31 128 fp_regs.vregs[31] [1]_ 0x6020 0000 0010 00d4 FPSR 32 fp_regs.fpsr 0x6020 0000 0010 00d5 FPCR 32 fp_regs.fpcr +======================= ========= ===== ======================================= -(*) These encodings are not accepted for SVE-enabled vcpus. See - KVM_ARM_VCPU_INIT. +.. [1] These encodings are not accepted for SVE-enabled vcpus. See + KVM_ARM_VCPU_INIT. - The equivalent register content can be accessed via bits [127:0] of - the corresponding SVE Zn registers instead for vcpus that have SVE - enabled (see below). + The equivalent register content can be accessed via bits [127:0] of + the corresponding SVE Zn registers instead for vcpus that have SVE + enabled (see below). + +arm64 CCSIDR registers are demultiplexed by CSSELR value:: -arm64 CCSIDR registers are demultiplexed by CSSELR value: 0x6020 0000 0011 00 <csselr:8> -arm64 system registers have the following id bit patterns: +arm64 system registers have the following id bit patterns:: + 0x6030 0000 0013 <op0:2> <op1:3> <crn:4> <crm:4> <op2:3> -arm64 firmware pseudo-registers have the following bit pattern: +.. warning:: + + Two system register IDs do not follow the specified pattern. These + are KVM_REG_ARM_TIMER_CVAL and KVM_REG_ARM_TIMER_CNT, which map to + system registers CNTV_CVAL_EL0 and CNTVCT_EL0 respectively. These + two had their values accidentally swapped, which means TIMER_CVAL is + derived from the register encoding for CNTVCT_EL0 and TIMER_CNT is + derived from the register encoding for CNTV_CVAL_EL0. As this is + API, it must remain this way. + +arm64 firmware pseudo-registers have the following bit pattern:: + 0x6030 0000 0014 <regno:16> -arm64 SVE registers have the following bit patterns: +arm64 SVE registers have the following bit patterns:: + 0x6080 0000 0015 00 <n:5> <slice:5> Zn bits[2048*slice + 2047 : 2048*slice] 0x6050 0000 0015 04 <n:4> <slice:5> Pn bits[256*slice + 255 : 256*slice] 0x6050 0000 0015 060 <slice:5> FFR bits[256*slice + 255 : 256*slice] @@ -2207,7 +2437,7 @@ arm64 SVE registers have the following bit patterns: Access to register IDs where 2048 * slice >= 128 * max_vq will fail with ENOENT. max_vq is the vcpu's maximum supported vector length in 128-bit -quadwords: see (**) below. +quadwords: see [2]_ below. These registers are only accessible on vcpus for which SVE is enabled. See KVM_ARM_VCPU_INIT for details. @@ -2222,21 +2452,21 @@ lengths supported by the vcpu to be discovered and configured by userspace. When transferred to or from user memory via KVM_GET_ONE_REG or KVM_SET_ONE_REG, the value of this register is of type __u64[KVM_ARM64_SVE_VLS_WORDS], and encodes the set of vector lengths as -follows: +follows:: -__u64 vector_lengths[KVM_ARM64_SVE_VLS_WORDS]; + __u64 vector_lengths[KVM_ARM64_SVE_VLS_WORDS]; -if (vq >= SVE_VQ_MIN && vq <= SVE_VQ_MAX && - ((vector_lengths[(vq - KVM_ARM64_SVE_VQ_MIN) / 64] >> + if (vq >= SVE_VQ_MIN && vq <= SVE_VQ_MAX && + ((vector_lengths[(vq - KVM_ARM64_SVE_VQ_MIN) / 64] >> ((vq - KVM_ARM64_SVE_VQ_MIN) % 64)) & 1)) /* Vector length vq * 16 bytes supported */ -else + else /* Vector length vq * 16 bytes not supported */ -(**) The maximum value vq for which the above condition is true is -max_vq. This is the maximum vector length available to the guest on -this vcpu, and determines which register slices are visible through -this ioctl interface. +.. [2] The maximum value vq for which the above condition is true is + max_vq. This is the maximum vector length available to the guest on + this vcpu, and determines which register slices are visible through + this ioctl interface. (See Documentation/arm64/sve.rst for an explanation of the "vq" nomenclature.) @@ -2261,11 +2491,13 @@ write this register will fail with EPERM. MIPS registers are mapped using the lower 32 bits. The upper 16 of that is the register group type: -MIPS core registers (see above) have the following id bit patterns: +MIPS core registers (see above) have the following id bit patterns:: + 0x7030 0000 0000 <reg:16> MIPS CP0 registers (see KVM_REG_MIPS_CP0_* above) have the following id bit -patterns depending on whether they're 32-bit or 64-bit registers: +patterns depending on whether they're 32-bit or 64-bit registers:: + 0x7020 0000 0001 00 <reg:5> <sel:3> (32-bit) 0x7030 0000 0001 00 <reg:5> <sel:3> (64-bit) @@ -2276,10 +2508,12 @@ with the RI and XI bits (if they exist) in bits 63 and 62 respectively, and the PFNX field starting at bit 30. MIPS MAARs (see KVM_REG_MIPS_CP0_MAAR(*) above) have the following id bit -patterns: +patterns:: + 0x7030 0000 0001 01 <reg:8> -MIPS KVM control registers (see above) have the following id bit patterns: +MIPS KVM control registers (see above) have the following id bit patterns:: + 0x7030 0000 0002 <reg:16> MIPS FPU registers (see KVM_REG_MIPS_FPR_{32,64}() above) have the following @@ -2288,31 +2522,40 @@ always accessed according to the current guest FPU mode (Status.FR and Config5.FRE), i.e. as the guest would see them, and they become unpredictable if the guest FPU mode is changed. MIPS SIMD Architecture (MSA) vector registers (see KVM_REG_MIPS_VEC_128() above) have similar patterns as they -overlap the FPU registers: +overlap the FPU registers:: + 0x7020 0000 0003 00 <0:3> <reg:5> (32-bit FPU registers) 0x7030 0000 0003 00 <0:3> <reg:5> (64-bit FPU registers) 0x7040 0000 0003 00 <0:3> <reg:5> (128-bit MSA vector registers) MIPS FPU control registers (see KVM_REG_MIPS_FCR_{IR,CSR} above) have the -following id bit patterns: +following id bit patterns:: + 0x7020 0000 0003 01 <0:3> <reg:5> MIPS MSA control registers (see KVM_REG_MIPS_MSA_{IR,CSR} above) have the -following id bit patterns: +following id bit patterns:: + 0x7020 0000 0003 02 <0:3> <reg:5> 4.69 KVM_GET_ONE_REG +-------------------- + +:Capability: KVM_CAP_ONE_REG +:Architectures: all +:Type: vcpu ioctl +:Parameters: struct kvm_one_reg (in and out) +:Returns: 0 on success, negative value on failure -Capability: KVM_CAP_ONE_REG -Architectures: all -Type: vcpu ioctl -Parameters: struct kvm_one_reg (in and out) -Returns: 0 on success, negative value on failure Errors include: -  ENOENT:   no such register -  EINVAL:   invalid register ID, or no such register -  EPERM:    (arm64) register access not allowed before vcpu finalization + + ======== ============================================================ +  ENOENT   no such register +  EINVAL   invalid register ID, or no such register +  EPERM    (arm64) register access not allowed before vcpu finalization + ======== ============================================================ + (These error codes are indicative only: do not rely on a specific error code being returned in a specific situation.) @@ -2326,12 +2569,13 @@ list in 4.68. 4.70 KVM_KVMCLOCK_CTRL +---------------------- -Capability: KVM_CAP_KVMCLOCK_CTRL -Architectures: Any that implement pvclocks (currently x86 only) -Type: vcpu ioctl -Parameters: None -Returns: 0 on success, -1 on error +:Capability: KVM_CAP_KVMCLOCK_CTRL +:Architectures: Any that implement pvclocks (currently x86 only) +:Type: vcpu ioctl +:Parameters: None +:Returns: 0 on success, -1 on error This signals to the host kernel that the specified guest is being paused by userspace. The host will set a flag in the pvclock structure that is checked @@ -2347,26 +2591,30 @@ after pausing the vcpu, but before it is resumed. 4.71 KVM_SIGNAL_MSI +------------------- -Capability: KVM_CAP_SIGNAL_MSI -Architectures: x86 arm arm64 -Type: vm ioctl -Parameters: struct kvm_msi (in) -Returns: >0 on delivery, 0 if guest blocked the MSI, and -1 on error +:Capability: KVM_CAP_SIGNAL_MSI +:Architectures: x86 arm arm64 +:Type: vm ioctl +:Parameters: struct kvm_msi (in) +:Returns: >0 on delivery, 0 if guest blocked the MSI, and -1 on error Directly inject a MSI message. Only valid with in-kernel irqchip that handles MSI messages. -struct kvm_msi { +:: + + struct kvm_msi { __u32 address_lo; __u32 address_hi; __u32 data; __u32 flags; __u32 devid; __u8 pad[12]; -}; + }; -flags: KVM_MSI_VALID_DEVID: devid contains a valid value. The per-VM +flags: + KVM_MSI_VALID_DEVID: devid contains a valid value. The per-VM KVM_CAP_MSI_DEVID capability advertises the requirement to provide the device ID. If this capability is not available, userspace should never set the KVM_MSI_VALID_DEVID flag as the ioctl might fail. @@ -2382,30 +2630,31 @@ address_hi must be zero. 4.71 KVM_CREATE_PIT2 +-------------------- -Capability: KVM_CAP_PIT2 -Architectures: x86 -Type: vm ioctl -Parameters: struct kvm_pit_config (in) -Returns: 0 on success, -1 on error +:Capability: KVM_CAP_PIT2 +:Architectures: x86 +:Type: vm ioctl +:Parameters: struct kvm_pit_config (in) +:Returns: 0 on success, -1 on error Creates an in-kernel device model for the i8254 PIT. This call is only valid after enabling in-kernel irqchip support via KVM_CREATE_IRQCHIP. The following -parameters have to be passed: +parameters have to be passed:: -struct kvm_pit_config { + struct kvm_pit_config { __u32 flags; __u32 pad[15]; -}; + }; -Valid flags are: +Valid flags are:: -#define KVM_PIT_SPEAKER_DUMMY 1 /* emulate speaker port stub */ + #define KVM_PIT_SPEAKER_DUMMY 1 /* emulate speaker port stub */ PIT timer interrupts may use a per-VM kernel thread for injection. If it -exists, this thread will have a name of the following pattern: +exists, this thread will have a name of the following pattern:: -kvm-pit/<owner-process-pid> + kvm-pit/<owner-process-pid> When running a guest with elevated priorities, the scheduling parameters of this thread may have to be adjusted accordingly. @@ -2414,37 +2663,39 @@ This IOCTL replaces the obsolete KVM_CREATE_PIT. 4.72 KVM_GET_PIT2 +----------------- -Capability: KVM_CAP_PIT_STATE2 -Architectures: x86 -Type: vm ioctl -Parameters: struct kvm_pit_state2 (out) -Returns: 0 on success, -1 on error +:Capability: KVM_CAP_PIT_STATE2 +:Architectures: x86 +:Type: vm ioctl +:Parameters: struct kvm_pit_state2 (out) +:Returns: 0 on success, -1 on error Retrieves the state of the in-kernel PIT model. Only valid after -KVM_CREATE_PIT2. The state is returned in the following structure: +KVM_CREATE_PIT2. The state is returned in the following structure:: -struct kvm_pit_state2 { + struct kvm_pit_state2 { struct kvm_pit_channel_state channels[3]; __u32 flags; __u32 reserved[9]; -}; + }; -Valid flags are: +Valid flags are:: -/* disable PIT in HPET legacy mode */ -#define KVM_PIT_FLAGS_HPET_LEGACY 0x00000001 + /* disable PIT in HPET legacy mode */ + #define KVM_PIT_FLAGS_HPET_LEGACY 0x00000001 This IOCTL replaces the obsolete KVM_GET_PIT. 4.73 KVM_SET_PIT2 +----------------- -Capability: KVM_CAP_PIT_STATE2 -Architectures: x86 -Type: vm ioctl -Parameters: struct kvm_pit_state2 (in) -Returns: 0 on success, -1 on error +:Capability: KVM_CAP_PIT_STATE2 +:Architectures: x86 +:Type: vm ioctl +:Parameters: struct kvm_pit_state2 (in) +:Returns: 0 on success, -1 on error Sets the state of the in-kernel PIT model. Only valid after KVM_CREATE_PIT2. See KVM_GET_PIT2 for details on struct kvm_pit_state2. @@ -2453,12 +2704,13 @@ This IOCTL replaces the obsolete KVM_SET_PIT. 4.74 KVM_PPC_GET_SMMU_INFO +-------------------------- -Capability: KVM_CAP_PPC_GET_SMMU_INFO -Architectures: powerpc -Type: vm ioctl -Parameters: None -Returns: 0 on success, -1 on error +:Capability: KVM_CAP_PPC_GET_SMMU_INFO +:Architectures: powerpc +:Type: vm ioctl +:Parameters: None +:Returns: 0 on success, -1 on error This populates and returns a structure describing the features of the "Server" class MMU emulation supported by KVM. @@ -2466,7 +2718,7 @@ This can in turn be used by userspace to generate the appropriate device-tree properties for the guest operating system. The structure contains some global information, followed by an -array of supported segment page sizes: +array of supported segment page sizes:: struct kvm_ppc_smmu_info { __u64 flags; @@ -2494,7 +2746,7 @@ The "slb_size" field indicates how many SLB entries are supported The "sps" array contains 8 entries indicating the supported base page sizes for a segment in increasing order. Each entry is defined -as follow: +as follow:: struct kvm_ppc_one_seg_page_size { __u32 page_shift; /* Base page shift of segment (or 0) */ @@ -2515,7 +2767,7 @@ size provides the list of supported actual page sizes (which can be only larger or equal to the base page size), along with the corresponding encoding in the hash PTE. Similarly, the array is 8 entries sorted by increasing sizes and an entry with a "0" shift -is an empty entry and a terminator: +is an empty entry and a terminator:: struct kvm_ppc_one_page_size { __u32 page_shift; /* Page shift (or 0) */ @@ -2527,12 +2779,13 @@ PTE's RPN field (ie, it needs to be shifted left by 12 to OR it into the hash PTE second double word). 4.75 KVM_IRQFD +-------------- -Capability: KVM_CAP_IRQFD -Architectures: x86 s390 arm arm64 -Type: vm ioctl -Parameters: struct kvm_irqfd (in) -Returns: 0 on success, -1 on error +:Capability: KVM_CAP_IRQFD +:Architectures: x86 s390 arm arm64 +:Type: vm ioctl +:Parameters: struct kvm_irqfd (in) +:Returns: 0 on success, -1 on error Allows setting an eventfd to directly trigger a guest interrupt. kvm_irqfd.fd specifies the file descriptor to use as the eventfd and @@ -2556,6 +2809,7 @@ irqfd. The KVM_IRQFD_FLAG_RESAMPLE is only necessary on assignment and need not be specified with KVM_IRQFD_FLAG_DEASSIGN. On arm/arm64, gsi routing being supported, the following can happen: + - in case no routing entry is associated to this gsi, injection fails - in case the gsi is associated to an irqchip routing entry, irqchip.pin + 32 corresponds to the injected SPI ID. @@ -2564,12 +2818,13 @@ On arm/arm64, gsi routing being supported, the following can happen: to GICv3 ITS in-kernel emulation). 4.76 KVM_PPC_ALLOCATE_HTAB +-------------------------- -Capability: KVM_CAP_PPC_ALLOC_HTAB -Architectures: powerpc -Type: vm ioctl -Parameters: Pointer to u32 containing hash table order (in/out) -Returns: 0 on success, -1 on error +:Capability: KVM_CAP_PPC_ALLOC_HTAB +:Architectures: powerpc +:Type: vm ioctl +:Parameters: Pointer to u32 containing hash table order (in/out) +:Returns: 0 on success, -1 on error This requests the host kernel to allocate an MMU hash table for a guest using the PAPR paravirtualization interface. This only does @@ -2600,75 +2855,88 @@ real-mode area (VRMA) facility, the kernel will re-create the VMRA HPTEs on the next KVM_RUN of any vcpu. 4.77 KVM_S390_INTERRUPT +----------------------- -Capability: basic -Architectures: s390 -Type: vm ioctl, vcpu ioctl -Parameters: struct kvm_s390_interrupt (in) -Returns: 0 on success, -1 on error +:Capability: basic +:Architectures: s390 +:Type: vm ioctl, vcpu ioctl +:Parameters: struct kvm_s390_interrupt (in) +:Returns: 0 on success, -1 on error Allows to inject an interrupt to the guest. Interrupts can be floating (vm ioctl) or per cpu (vcpu ioctl), depending on the interrupt type. -Interrupt parameters are passed via kvm_s390_interrupt: +Interrupt parameters are passed via kvm_s390_interrupt:: -struct kvm_s390_interrupt { + struct kvm_s390_interrupt { __u32 type; __u32 parm; __u64 parm64; -}; + }; type can be one of the following: -KVM_S390_SIGP_STOP (vcpu) - sigp stop; optional flags in parm -KVM_S390_PROGRAM_INT (vcpu) - program check; code in parm -KVM_S390_SIGP_SET_PREFIX (vcpu) - sigp set prefix; prefix address in parm -KVM_S390_RESTART (vcpu) - restart -KVM_S390_INT_CLOCK_COMP (vcpu) - clock comparator interrupt -KVM_S390_INT_CPU_TIMER (vcpu) - CPU timer interrupt -KVM_S390_INT_VIRTIO (vm) - virtio external interrupt; external interrupt - parameters in parm and parm64 -KVM_S390_INT_SERVICE (vm) - sclp external interrupt; sclp parameter in parm -KVM_S390_INT_EMERGENCY (vcpu) - sigp emergency; source cpu in parm -KVM_S390_INT_EXTERNAL_CALL (vcpu) - sigp external call; source cpu in parm -KVM_S390_INT_IO(ai,cssid,ssid,schid) (vm) - compound value to indicate an - I/O interrupt (ai - adapter interrupt; cssid,ssid,schid - subchannel); - I/O interruption parameters in parm (subchannel) and parm64 (intparm, - interruption subclass) -KVM_S390_MCHK (vm, vcpu) - machine check interrupt; cr 14 bits in parm, - machine check interrupt code in parm64 (note that - machine checks needing further payload are not - supported by this ioctl) +KVM_S390_SIGP_STOP (vcpu) + - sigp stop; optional flags in parm +KVM_S390_PROGRAM_INT (vcpu) + - program check; code in parm +KVM_S390_SIGP_SET_PREFIX (vcpu) + - sigp set prefix; prefix address in parm +KVM_S390_RESTART (vcpu) + - restart +KVM_S390_INT_CLOCK_COMP (vcpu) + - clock comparator interrupt +KVM_S390_INT_CPU_TIMER (vcpu) + - CPU timer interrupt +KVM_S390_INT_VIRTIO (vm) + - virtio external interrupt; external interrupt + parameters in parm and parm64 +KVM_S390_INT_SERVICE (vm) + - sclp external interrupt; sclp parameter in parm +KVM_S390_INT_EMERGENCY (vcpu) + - sigp emergency; source cpu in parm +KVM_S390_INT_EXTERNAL_CALL (vcpu) + - sigp external call; source cpu in parm +KVM_S390_INT_IO(ai,cssid,ssid,schid) (vm) + - compound value to indicate an + I/O interrupt (ai - adapter interrupt; cssid,ssid,schid - subchannel); + I/O interruption parameters in parm (subchannel) and parm64 (intparm, + interruption subclass) +KVM_S390_MCHK (vm, vcpu) + - machine check interrupt; cr 14 bits in parm, machine check interrupt + code in parm64 (note that machine checks needing further payload are not + supported by this ioctl) This is an asynchronous vcpu ioctl and can be invoked from any thread. 4.78 KVM_PPC_GET_HTAB_FD +------------------------ -Capability: KVM_CAP_PPC_HTAB_FD -Architectures: powerpc -Type: vm ioctl -Parameters: Pointer to struct kvm_get_htab_fd (in) -Returns: file descriptor number (>= 0) on success, -1 on error +:Capability: KVM_CAP_PPC_HTAB_FD +:Architectures: powerpc +:Type: vm ioctl +:Parameters: Pointer to struct kvm_get_htab_fd (in) +:Returns: file descriptor number (>= 0) on success, -1 on error This returns a file descriptor that can be used either to read out the entries in the guest's hashed page table (HPT), or to write entries to initialize the HPT. The returned fd can only be written to if the KVM_GET_HTAB_WRITE bit is set in the flags field of the argument, and can only be read if that bit is clear. The argument struct looks like -this: +this:: -/* For KVM_PPC_GET_HTAB_FD */ -struct kvm_get_htab_fd { + /* For KVM_PPC_GET_HTAB_FD */ + struct kvm_get_htab_fd { __u64 flags; __u64 start_index; __u64 reserved[2]; -}; + }; -/* Values for kvm_get_htab_fd.flags */ -#define KVM_GET_HTAB_BOLTED_ONLY ((__u64)0x1) -#define KVM_GET_HTAB_WRITE ((__u64)0x2) + /* Values for kvm_get_htab_fd.flags */ + #define KVM_GET_HTAB_BOLTED_ONLY ((__u64)0x1) + #define KVM_GET_HTAB_WRITE ((__u64)0x2) -The `start_index' field gives the index in the HPT of the entry at +The 'start_index' field gives the index in the HPT of the entry at which to start reading. It is ignored when writing. Reads on the fd will initially supply information about all @@ -2683,29 +2951,34 @@ Data read or written is structured as a header (8 bytes) followed by a series of valid HPT entries (16 bytes) each. The header indicates how many valid HPT entries there are and how many invalid entries follow the valid entries. The invalid entries are not represented explicitly -in the stream. The header format is: +in the stream. The header format is:: -struct kvm_get_htab_header { + struct kvm_get_htab_header { __u32 index; __u16 n_valid; __u16 n_invalid; -}; + }; Writes to the fd create HPT entries starting at the index given in the -header; first `n_valid' valid entries with contents from the data -written, then `n_invalid' invalid entries, invalidating any previously +header; first 'n_valid' valid entries with contents from the data +written, then 'n_invalid' invalid entries, invalidating any previously valid entries found. 4.79 KVM_CREATE_DEVICE +---------------------- + +:Capability: KVM_CAP_DEVICE_CTRL +:Type: vm ioctl +:Parameters: struct kvm_create_device (in/out) +:Returns: 0 on success, -1 on error -Capability: KVM_CAP_DEVICE_CTRL -Type: vm ioctl -Parameters: struct kvm_create_device (in/out) -Returns: 0 on success, -1 on error Errors: - ENODEV: The device type is unknown or unsupported - EEXIST: Device already created, and this type of device may not + + ====== ======================================================= + ENODEV The device type is unknown or unsupported + EEXIST Device already created, and this type of device may not be instantiated multiple times + ====== ======================================================= Other error conditions may be defined by individual device types or have their standard meanings. @@ -2721,25 +2994,32 @@ Individual devices should not define flags. Attributes should be used for specifying any behavior that is not implied by the device type number. -struct kvm_create_device { +:: + + struct kvm_create_device { __u32 type; /* in: KVM_DEV_TYPE_xxx */ __u32 fd; /* out: device handle */ __u32 flags; /* in: KVM_CREATE_DEVICE_xxx */ -}; + }; 4.80 KVM_SET_DEVICE_ATTR/KVM_GET_DEVICE_ATTR +-------------------------------------------- + +:Capability: KVM_CAP_DEVICE_CTRL, KVM_CAP_VM_ATTRIBUTES for vm device, + KVM_CAP_VCPU_ATTRIBUTES for vcpu device +:Type: device ioctl, vm ioctl, vcpu ioctl +:Parameters: struct kvm_device_attr +:Returns: 0 on success, -1 on error -Capability: KVM_CAP_DEVICE_CTRL, KVM_CAP_VM_ATTRIBUTES for vm device, - KVM_CAP_VCPU_ATTRIBUTES for vcpu device -Type: device ioctl, vm ioctl, vcpu ioctl -Parameters: struct kvm_device_attr -Returns: 0 on success, -1 on error Errors: - ENXIO: The group or attribute is unknown/unsupported for this device + + ===== ============================================================= + ENXIO The group or attribute is unknown/unsupported for this device or hardware support is missing. - EPERM: The attribute cannot (currently) be accessed this way + EPERM The attribute cannot (currently) be accessed this way (e.g. read-only attribute, or attribute that only makes sense when the device is in a different state) + ===== ============================================================= Other error conditions may be defined by individual device types. @@ -2748,23 +3028,30 @@ semantics are device-specific. See individual device documentation in the "devices" directory. As with ONE_REG, the size of the data transferred is defined by the particular attribute. -struct kvm_device_attr { +:: + + struct kvm_device_attr { __u32 flags; /* no flags currently defined */ __u32 group; /* device-defined */ __u64 attr; /* group-defined */ __u64 addr; /* userspace address of attr data */ -}; + }; 4.81 KVM_HAS_DEVICE_ATTR +------------------------ + +:Capability: KVM_CAP_DEVICE_CTRL, KVM_CAP_VM_ATTRIBUTES for vm device, + KVM_CAP_VCPU_ATTRIBUTES for vcpu device +:Type: device ioctl, vm ioctl, vcpu ioctl +:Parameters: struct kvm_device_attr +:Returns: 0 on success, -1 on error -Capability: KVM_CAP_DEVICE_CTRL, KVM_CAP_VM_ATTRIBUTES for vm device, - KVM_CAP_VCPU_ATTRIBUTES for vcpu device -Type: device ioctl, vm ioctl, vcpu ioctl -Parameters: struct kvm_device_attr -Returns: 0 on success, -1 on error Errors: - ENXIO: The group or attribute is unknown/unsupported for this device + + ===== ============================================================= + ENXIO The group or attribute is unknown/unsupported for this device or hardware support is missing. + ===== ============================================================= Tests whether a device supports a particular attribute. A successful return indicates the attribute is implemented. It does not necessarily @@ -2772,15 +3059,20 @@ indicate that the attribute can be read or written in the device's current state. "addr" is ignored. 4.82 KVM_ARM_VCPU_INIT +---------------------- + +:Capability: basic +:Architectures: arm, arm64 +:Type: vcpu ioctl +:Parameters: struct kvm_vcpu_init (in) +:Returns: 0 on success; -1 on error -Capability: basic -Architectures: arm, arm64 -Type: vcpu ioctl -Parameters: struct kvm_vcpu_init (in) -Returns: 0 on success; -1 on error Errors: -  EINVAL:    the target is unknown, or the combination of features is invalid. -  ENOENT:    a features bit specified is unknown. + + ====== ================================================================= +  EINVAL    the target is unknown, or the combination of features is invalid. +  ENOENT    a features bit specified is unknown. + ====== ================================================================= This tells KVM what type of CPU to present to the guest, and what optional features it should have.  This will cause a reset of the cpu @@ -2796,6 +3088,7 @@ state. All calls to this function after the initial call must use the same target and same set of feature flags, otherwise EINVAL will be returned. Possible features: + - KVM_ARM_VCPU_POWER_OFF: Starts the CPU in a power-off state. Depends on KVM_CAP_ARM_PSCI. If not set, the CPU will be powered on and execute guest code when KVM_RUN is called. @@ -2852,14 +3145,19 @@ Possible features: no longer be written using KVM_SET_ONE_REG. 4.83 KVM_ARM_PREFERRED_TARGET +----------------------------- + +:Capability: basic +:Architectures: arm, arm64 +:Type: vm ioctl +:Parameters: struct struct kvm_vcpu_init (out) +:Returns: 0 on success; -1 on error -Capability: basic -Architectures: arm, arm64 -Type: vm ioctl -Parameters: struct struct kvm_vcpu_init (out) -Returns: 0 on success; -1 on error Errors: - ENODEV: no preferred target available for the host + + ====== ========================================== + ENODEV no preferred target available for the host + ====== ========================================== This queries KVM for preferred CPU target type which can be emulated by KVM on underlying host. @@ -2876,43 +3174,57 @@ in VCPU matching underlying host. 4.84 KVM_GET_REG_LIST +--------------------- + +:Capability: basic +:Architectures: arm, arm64, mips +:Type: vcpu ioctl +:Parameters: struct kvm_reg_list (in/out) +:Returns: 0 on success; -1 on error -Capability: basic -Architectures: arm, arm64, mips -Type: vcpu ioctl -Parameters: struct kvm_reg_list (in/out) -Returns: 0 on success; -1 on error Errors: -  E2BIG:     the reg index list is too big to fit in the array specified by + + ===== ============================================================== +  E2BIG     the reg index list is too big to fit in the array specified by             the user (the number required will be written into n). + ===== ============================================================== + +:: -struct kvm_reg_list { + struct kvm_reg_list { __u64 n; /* number of registers in reg[] */ __u64 reg[0]; -}; + }; This ioctl returns the guest registers that are supported for the KVM_GET_ONE_REG/KVM_SET_ONE_REG calls. 4.85 KVM_ARM_SET_DEVICE_ADDR (deprecated) +----------------------------------------- + +:Capability: KVM_CAP_ARM_SET_DEVICE_ADDR +:Architectures: arm, arm64 +:Type: vm ioctl +:Parameters: struct kvm_arm_device_address (in) +:Returns: 0 on success, -1 on error -Capability: KVM_CAP_ARM_SET_DEVICE_ADDR -Architectures: arm, arm64 -Type: vm ioctl -Parameters: struct kvm_arm_device_address (in) -Returns: 0 on success, -1 on error Errors: - ENODEV: The device id is unknown - ENXIO: Device not supported on current system - EEXIST: Address already set - E2BIG: Address outside guest physical address space - EBUSY: Address overlaps with other device range -struct kvm_arm_device_addr { + ====== ============================================ + ENODEV The device id is unknown + ENXIO Device not supported on current system + EEXIST Address already set + E2BIG Address outside guest physical address space + EBUSY Address overlaps with other device range + ====== ============================================ + +:: + + struct kvm_arm_device_addr { __u64 id; __u64 addr; -}; + }; Specify a device address in the guest's physical address space where guests can access emulated or directly exposed devices, which the host kernel needs @@ -2920,7 +3232,7 @@ to know about. The id field is an architecture specific identifier for a specific device. ARM/arm64 divides the id field into two parts, a device id and an -address type id specific to the individual device. +address type id specific to the individual device::  bits: | 63 ... 32 | 31 ... 16 | 15 ... 0 | field: | 0x00000000 | device id | addr type id | @@ -2938,12 +3250,13 @@ should be used instead. 4.86 KVM_PPC_RTAS_DEFINE_TOKEN +------------------------------ -Capability: KVM_CAP_PPC_RTAS -Architectures: ppc -Type: vm ioctl -Parameters: struct kvm_rtas_token_args -Returns: 0 on success, -1 on error +:Capability: KVM_CAP_PPC_RTAS +:Architectures: ppc +:Type: vm ioctl +:Parameters: struct kvm_rtas_token_args +:Returns: 0 on success, -1 on error Defines a token value for a RTAS (Run Time Abstraction Services) service in order to allow it to be handled in the kernel. The @@ -2957,18 +3270,21 @@ calls by the guest for that service will be passed to userspace to be handled. 4.87 KVM_SET_GUEST_DEBUG +------------------------ + +:Capability: KVM_CAP_SET_GUEST_DEBUG +:Architectures: x86, s390, ppc, arm64 +:Type: vcpu ioctl +:Parameters: struct kvm_guest_debug (in) +:Returns: 0 on success; -1 on error -Capability: KVM_CAP_SET_GUEST_DEBUG -Architectures: x86, s390, ppc, arm64 -Type: vcpu ioctl -Parameters: struct kvm_guest_debug (in) -Returns: 0 on success; -1 on error +:: -struct kvm_guest_debug { + struct kvm_guest_debug { __u32 control; __u32 pad; struct kvm_guest_debug_arch arch; -}; + }; Set up the processor specific debug registers and configure vcpu for handling guest debug events. There are two parts to the structure, the @@ -3010,26 +3326,31 @@ KVM_EXIT_DEBUG with the kvm_debug_exit_arch part of the kvm_run structure containing architecture specific debug information. 4.88 KVM_GET_EMULATED_CPUID +--------------------------- -Capability: KVM_CAP_EXT_EMUL_CPUID -Architectures: x86 -Type: system ioctl -Parameters: struct kvm_cpuid2 (in/out) -Returns: 0 on success, -1 on error +:Capability: KVM_CAP_EXT_EMUL_CPUID +:Architectures: x86 +:Type: system ioctl +:Parameters: struct kvm_cpuid2 (in/out) +:Returns: 0 on success, -1 on error -struct kvm_cpuid2 { +:: + + struct kvm_cpuid2 { __u32 nent; __u32 flags; struct kvm_cpuid_entry2 entries[0]; -}; + }; The member 'flags' is used for passing flags from userspace. -#define KVM_CPUID_FLAG_SIGNIFCANT_INDEX BIT(0) -#define KVM_CPUID_FLAG_STATEFUL_FUNC BIT(1) -#define KVM_CPUID_FLAG_STATE_READ_NEXT BIT(2) +:: + + #define KVM_CPUID_FLAG_SIGNIFCANT_INDEX BIT(0) + #define KVM_CPUID_FLAG_STATEFUL_FUNC BIT(1) + #define KVM_CPUID_FLAG_STATE_READ_NEXT BIT(2) -struct kvm_cpuid_entry2 { + struct kvm_cpuid_entry2 { __u32 function; __u32 index; __u32 flags; @@ -3038,7 +3359,7 @@ struct kvm_cpuid_entry2 { __u32 ecx; __u32 edx; __u32 padding[3]; -}; + }; This ioctl returns x86 cpuid features which are emulated by kvm.Userspace can use the information returned by this ioctl to query @@ -3063,10 +3384,14 @@ emulated efficiently and thus not included here. The fields in each entry are defined as follows: - function: the eax value used to obtain the entry - index: the ecx value used to obtain the entry (for entries that are + function: + the eax value used to obtain the entry + index: + the ecx value used to obtain the entry (for entries that are affected by ecx) - flags: an OR of zero or more of the following: + flags: + an OR of zero or more of the following: + KVM_CPUID_FLAG_SIGNIFCANT_INDEX: if the index field is valid KVM_CPUID_FLAG_STATEFUL_FUNC: @@ -3076,24 +3401,28 @@ The fields in each entry are defined as follows: KVM_CPUID_FLAG_STATE_READ_NEXT: for KVM_CPUID_FLAG_STATEFUL_FUNC entries, set if this entry is the first entry to be read by a cpu - eax, ebx, ecx, edx: the values returned by the cpuid instruction for + + eax, ebx, ecx, edx: + + the values returned by the cpuid instruction for this function/index combination 4.89 KVM_S390_MEM_OP +-------------------- -Capability: KVM_CAP_S390_MEM_OP -Architectures: s390 -Type: vcpu ioctl -Parameters: struct kvm_s390_mem_op (in) -Returns: = 0 on success, - < 0 on generic error (e.g. -EFAULT or -ENOMEM), - > 0 if an exception occurred while walking the page tables +:Capability: KVM_CAP_S390_MEM_OP +:Architectures: s390 +:Type: vcpu ioctl +:Parameters: struct kvm_s390_mem_op (in) +:Returns: = 0 on success, + < 0 on generic error (e.g. -EFAULT or -ENOMEM), + > 0 if an exception occurred while walking the page tables Read or write data from/to the logical (virtual) memory of a VCPU. -Parameters are specified via the following structure: +Parameters are specified via the following structure:: -struct kvm_s390_mem_op { + struct kvm_s390_mem_op { __u64 gaddr; /* the guest address */ __u64 flags; /* flags */ __u32 size; /* amount of bytes */ @@ -3101,7 +3430,7 @@ struct kvm_s390_mem_op { __u64 buf; /* buffer in userspace */ __u8 ar; /* the access register number */ __u8 reserved[31]; /* should be set to 0 */ -}; + }; The type of operation is specified in the "op" field. It is either KVM_S390_MEMOP_LOGICAL_READ for reading from logical memory space or @@ -3128,24 +3457,25 @@ The "reserved" field is meant for future extensions. It is not used by KVM with the currently defined set of flags. 4.90 KVM_S390_GET_SKEYS +----------------------- -Capability: KVM_CAP_S390_SKEYS -Architectures: s390 -Type: vm ioctl -Parameters: struct kvm_s390_skeys -Returns: 0 on success, KVM_S390_GET_KEYS_NONE if guest is not using storage - keys, negative value on error +:Capability: KVM_CAP_S390_SKEYS +:Architectures: s390 +:Type: vm ioctl +:Parameters: struct kvm_s390_skeys +:Returns: 0 on success, KVM_S390_GET_KEYS_NONE if guest is not using storage + keys, negative value on error This ioctl is used to get guest storage key values on the s390 -architecture. The ioctl takes parameters via the kvm_s390_skeys struct. +architecture. The ioctl takes parameters via the kvm_s390_skeys struct:: -struct kvm_s390_skeys { + struct kvm_s390_skeys { __u64 start_gfn; __u64 count; __u64 skeydata_addr; __u32 flags; __u32 reserved[9]; -}; + }; The start_gfn field is the number of the first guest frame whose storage keys you want to get. @@ -3159,12 +3489,13 @@ The skeydata_addr field is the address to a buffer large enough to hold count bytes. This buffer will be filled with storage key data by the ioctl. 4.91 KVM_S390_SET_SKEYS +----------------------- -Capability: KVM_CAP_S390_SKEYS -Architectures: s390 -Type: vm ioctl -Parameters: struct kvm_s390_skeys -Returns: 0 on success, negative value on error +:Capability: KVM_CAP_S390_SKEYS +:Architectures: s390 +:Type: vm ioctl +:Parameters: struct kvm_s390_skeys +:Returns: 0 on success, negative value on error This ioctl is used to set guest storage key values on the s390 architecture. The ioctl takes parameters via the kvm_s390_skeys struct. @@ -3186,21 +3517,27 @@ Note: If any architecturally invalid key value is found in the given data then the ioctl will return -EINVAL. 4.92 KVM_S390_IRQ +----------------- + +:Capability: KVM_CAP_S390_INJECT_IRQ +:Architectures: s390 +:Type: vcpu ioctl +:Parameters: struct kvm_s390_irq (in) +:Returns: 0 on success, -1 on error -Capability: KVM_CAP_S390_INJECT_IRQ -Architectures: s390 -Type: vcpu ioctl -Parameters: struct kvm_s390_irq (in) -Returns: 0 on success, -1 on error Errors: - EINVAL: interrupt type is invalid - type is KVM_S390_SIGP_STOP and flag parameter is invalid value + + + ====== ================================================================= + EINVAL interrupt type is invalid + type is KVM_S390_SIGP_STOP and flag parameter is invalid value, type is KVM_S390_INT_EXTERNAL_CALL and code is bigger - than the maximum of VCPUs - EBUSY: type is KVM_S390_SIGP_SET_PREFIX and vcpu is not stopped - type is KVM_S390_SIGP_STOP and a stop irq is already pending + than the maximum of VCPUs + EBUSY type is KVM_S390_SIGP_SET_PREFIX and vcpu is not stopped, + type is KVM_S390_SIGP_STOP and a stop irq is already pending, type is KVM_S390_INT_EXTERNAL_CALL and an external call interrupt - is already pending + is already pending + ====== ================================================================= Allows to inject an interrupt to the guest. @@ -3208,9 +3545,9 @@ Using struct kvm_s390_irq as a parameter allows to inject additional payload which is not possible via KVM_S390_INTERRUPT. -Interrupt parameters are passed via kvm_s390_irq: +Interrupt parameters are passed via kvm_s390_irq:: -struct kvm_s390_irq { + struct kvm_s390_irq { __u64 type; union { struct kvm_s390_io_info io; @@ -3223,44 +3560,45 @@ struct kvm_s390_irq { struct kvm_s390_mchk_info mchk; char reserved[64]; } u; -}; + }; type can be one of the following: -KVM_S390_SIGP_STOP - sigp stop; parameter in .stop -KVM_S390_PROGRAM_INT - program check; parameters in .pgm -KVM_S390_SIGP_SET_PREFIX - sigp set prefix; parameters in .prefix -KVM_S390_RESTART - restart; no parameters -KVM_S390_INT_CLOCK_COMP - clock comparator interrupt; no parameters -KVM_S390_INT_CPU_TIMER - CPU timer interrupt; no parameters -KVM_S390_INT_EMERGENCY - sigp emergency; parameters in .emerg -KVM_S390_INT_EXTERNAL_CALL - sigp external call; parameters in .extcall -KVM_S390_MCHK - machine check interrupt; parameters in .mchk +- KVM_S390_SIGP_STOP - sigp stop; parameter in .stop +- KVM_S390_PROGRAM_INT - program check; parameters in .pgm +- KVM_S390_SIGP_SET_PREFIX - sigp set prefix; parameters in .prefix +- KVM_S390_RESTART - restart; no parameters +- KVM_S390_INT_CLOCK_COMP - clock comparator interrupt; no parameters +- KVM_S390_INT_CPU_TIMER - CPU timer interrupt; no parameters +- KVM_S390_INT_EMERGENCY - sigp emergency; parameters in .emerg +- KVM_S390_INT_EXTERNAL_CALL - sigp external call; parameters in .extcall +- KVM_S390_MCHK - machine check interrupt; parameters in .mchk This is an asynchronous vcpu ioctl and can be invoked from any thread. 4.94 KVM_S390_GET_IRQ_STATE +--------------------------- -Capability: KVM_CAP_S390_IRQ_STATE -Architectures: s390 -Type: vcpu ioctl -Parameters: struct kvm_s390_irq_state (out) -Returns: >= number of bytes copied into buffer, - -EINVAL if buffer size is 0, - -ENOBUFS if buffer size is too small to fit all pending interrupts, - -EFAULT if the buffer address was invalid +:Capability: KVM_CAP_S390_IRQ_STATE +:Architectures: s390 +:Type: vcpu ioctl +:Parameters: struct kvm_s390_irq_state (out) +:Returns: >= number of bytes copied into buffer, + -EINVAL if buffer size is 0, + -ENOBUFS if buffer size is too small to fit all pending interrupts, + -EFAULT if the buffer address was invalid This ioctl allows userspace to retrieve the complete state of all currently pending interrupts in a single buffer. Use cases include migration and introspection. The parameter structure contains the address of a -userspace buffer and its length: +userspace buffer and its length:: -struct kvm_s390_irq_state { + struct kvm_s390_irq_state { __u64 buf; __u32 flags; /* will stay unused for compatibility reasons */ __u32 len; __u32 reserved[4]; /* will stay unused for compatibility reasons */ -}; + }; Userspace passes in the above struct and for each pending interrupt a struct kvm_s390_irq is copied to the provided buffer. @@ -3274,29 +3612,30 @@ If -ENOBUFS is returned the buffer provided was too small and userspace may retry with a bigger buffer. 4.95 KVM_S390_SET_IRQ_STATE - -Capability: KVM_CAP_S390_IRQ_STATE -Architectures: s390 -Type: vcpu ioctl -Parameters: struct kvm_s390_irq_state (in) -Returns: 0 on success, - -EFAULT if the buffer address was invalid, - -EINVAL for an invalid buffer length (see below), - -EBUSY if there were already interrupts pending, - errors occurring when actually injecting the +--------------------------- + +:Capability: KVM_CAP_S390_IRQ_STATE +:Architectures: s390 +:Type: vcpu ioctl +:Parameters: struct kvm_s390_irq_state (in) +:Returns: 0 on success, + -EFAULT if the buffer address was invalid, + -EINVAL for an invalid buffer length (see below), + -EBUSY if there were already interrupts pending, + errors occurring when actually injecting the interrupt. See KVM_S390_IRQ. This ioctl allows userspace to set the complete state of all cpu-local interrupts currently pending for the vcpu. It is intended for restoring interrupt state after a migration. The input parameter is a userspace buffer -containing a struct kvm_s390_irq_state: +containing a struct kvm_s390_irq_state:: -struct kvm_s390_irq_state { + struct kvm_s390_irq_state { __u64 buf; __u32 flags; /* will stay unused for compatibility reasons */ __u32 len; __u32 reserved[4]; /* will stay unused for compatibility reasons */ -}; + }; The restrictions for flags and reserved apply as well. (see KVM_S390_GET_IRQ_STATE) @@ -3311,20 +3650,22 @@ and it must not exceed (max_vcpus + 32) * sizeof(struct kvm_s390_irq), which is the maximum number of possibly pending cpu-local interrupts. 4.96 KVM_SMI +------------ -Capability: KVM_CAP_X86_SMM -Architectures: x86 -Type: vcpu ioctl -Parameters: none -Returns: 0 on success, -1 on error +:Capability: KVM_CAP_X86_SMM +:Architectures: x86 +:Type: vcpu ioctl +:Parameters: none +:Returns: 0 on success, -1 on error Queues an SMI on the thread's vcpu. 4.97 KVM_CAP_PPC_MULTITCE +------------------------- -Capability: KVM_CAP_PPC_MULTITCE -Architectures: ppc -Type: vm +:Capability: KVM_CAP_PPC_MULTITCE +:Architectures: ppc +:Type: vm This capability means the kernel is capable of handling hypercalls H_PUT_TCE_INDIRECT and H_STUFF_TCE without passing those into the user @@ -3346,26 +3687,27 @@ an implementation for these despite the in kernel acceleration. This capability is always enabled. 4.98 KVM_CREATE_SPAPR_TCE_64 +---------------------------- -Capability: KVM_CAP_SPAPR_TCE_64 -Architectures: powerpc -Type: vm ioctl -Parameters: struct kvm_create_spapr_tce_64 (in) -Returns: file descriptor for manipulating the created TCE table +:Capability: KVM_CAP_SPAPR_TCE_64 +:Architectures: powerpc +:Type: vm ioctl +:Parameters: struct kvm_create_spapr_tce_64 (in) +:Returns: file descriptor for manipulating the created TCE table This is an extension for KVM_CAP_SPAPR_TCE which only supports 32bit windows, described in 4.62 KVM_CREATE_SPAPR_TCE -This capability uses extended struct in ioctl interface: +This capability uses extended struct in ioctl interface:: -/* for KVM_CAP_SPAPR_TCE_64 */ -struct kvm_create_spapr_tce_64 { + /* for KVM_CAP_SPAPR_TCE_64 */ + struct kvm_create_spapr_tce_64 { __u64 liobn; __u32 page_shift; __u32 flags; __u64 offset; /* in pages */ __u64 size; /* in pages */ -}; + }; The aim of extension is to support an additional bigger DMA window with a variable page size. @@ -3378,12 +3720,13 @@ of IOMMU pages. The rest of functionality is identical to KVM_CREATE_SPAPR_TCE. 4.99 KVM_REINJECT_CONTROL +------------------------- -Capability: KVM_CAP_REINJECT_CONTROL -Architectures: x86 -Type: vm ioctl -Parameters: struct kvm_reinject_control (in) -Returns: 0 on success, +:Capability: KVM_CAP_REINJECT_CONTROL +:Architectures: x86 +:Type: vm ioctl +:Parameters: struct kvm_reinject_control (in) +:Returns: 0 on success, -EFAULT if struct kvm_reinject_control cannot be read, -ENXIO if KVM_CREATE_PIT or KVM_CREATE_PIT2 didn't succeed earlier. @@ -3393,21 +3736,24 @@ vector(s) that i8254 injects. Reinject mode dequeues a tick and injects its interrupt whenever there isn't a pending interrupt from i8254. !reinject mode injects an interrupt as soon as a tick arrives. -struct kvm_reinject_control { +:: + + struct kvm_reinject_control { __u8 pit_reinject; __u8 reserved[31]; -}; + }; pit_reinject = 0 (!reinject mode) is recommended, unless running an old operating system that uses the PIT for timing (e.g. Linux 2.4.x). 4.100 KVM_PPC_CONFIGURE_V3_MMU +------------------------------ -Capability: KVM_CAP_PPC_RADIX_MMU or KVM_CAP_PPC_HASH_MMU_V3 -Architectures: ppc -Type: vm ioctl -Parameters: struct kvm_ppc_mmuv3_cfg (in) -Returns: 0 on success, +:Capability: KVM_CAP_PPC_RADIX_MMU or KVM_CAP_PPC_HASH_MMU_V3 +:Architectures: ppc +:Type: vm ioctl +:Parameters: struct kvm_ppc_mmuv3_cfg (in) +:Returns: 0 on success, -EFAULT if struct kvm_ppc_mmuv3_cfg cannot be read, -EINVAL if the configuration is invalid @@ -3415,10 +3761,12 @@ This ioctl controls whether the guest will use radix or HPT (hashed page table) translation, and sets the pointer to the process table for the guest. -struct kvm_ppc_mmuv3_cfg { +:: + + struct kvm_ppc_mmuv3_cfg { __u64 flags; __u64 process_table; -}; + }; There are two bits that can be set in flags; KVM_PPC_MMUV3_RADIX and KVM_PPC_MMUV3_GTSE. KVM_PPC_MMUV3_RADIX, if set, configures the guest @@ -3433,12 +3781,13 @@ as the second doubleword of the partition table entry, as defined in the Power ISA V3.00, Book III section 5.7.6.1. 4.101 KVM_PPC_GET_RMMU_INFO +--------------------------- -Capability: KVM_CAP_PPC_RADIX_MMU -Architectures: ppc -Type: vm ioctl -Parameters: struct kvm_ppc_rmmu_info (out) -Returns: 0 on success, +:Capability: KVM_CAP_PPC_RADIX_MMU +:Architectures: ppc +:Type: vm ioctl +:Parameters: struct kvm_ppc_rmmu_info (out) +:Returns: 0 on success, -EFAULT if struct kvm_ppc_rmmu_info cannot be written, -EINVAL if no useful information can be returned @@ -3447,14 +3796,16 @@ containing supported radix tree geometries, and (b) a list that maps page sizes to put in the "AP" (actual page size) field for the tlbie (TLB invalidate entry) instruction. -struct kvm_ppc_rmmu_info { +:: + + struct kvm_ppc_rmmu_info { struct kvm_ppc_radix_geom { __u8 page_shift; __u8 level_bits[4]; __u8 pad[3]; } geometries[8]; __u32 ap_encodings[8]; -}; + }; The geometries[] field gives up to 8 supported geometries for the radix page table, in terms of the log base 2 of the smallest page @@ -3467,19 +3818,54 @@ encodings, encoded with the AP value in the top 3 bits and the log base 2 of the page size in the bottom 6 bits. 4.102 KVM_PPC_RESIZE_HPT_PREPARE +-------------------------------- -Capability: KVM_CAP_SPAPR_RESIZE_HPT -Architectures: powerpc -Type: vm ioctl -Parameters: struct kvm_ppc_resize_hpt (in) -Returns: 0 on successful completion, +:Capability: KVM_CAP_SPAPR_RESIZE_HPT +:Architectures: powerpc +:Type: vm ioctl +:Parameters: struct kvm_ppc_resize_hpt (in) +:Returns: 0 on successful completion, >0 if a new HPT is being prepared, the value is an estimated - number of milliseconds until preparation is complete + number of milliseconds until preparation is complete, -EFAULT if struct kvm_reinject_control cannot be read, - -EINVAL if the supplied shift or flags are invalid - -ENOMEM if unable to allocate the new HPT - -ENOSPC if there was a hash collision when moving existing - HPT entries to the new HPT + -EINVAL if the supplied shift or flags are invalid, + -ENOMEM if unable to allocate the new HPT, + -ENOSPC if there was a hash collision + +:: + + struct kvm_ppc_rmmu_info { + struct kvm_ppc_radix_geom { + __u8 page_shift; + __u8 level_bits[4]; + __u8 pad[3]; + } geometries[8]; + __u32 ap_encodings[8]; + }; + +The geometries[] field gives up to 8 supported geometries for the +radix page table, in terms of the log base 2 of the smallest page +size, and the number of bits indexed at each level of the tree, from +the PTE level up to the PGD level in that order. Any unused entries +will have 0 in the page_shift field. + +The ap_encodings gives the supported page sizes and their AP field +encodings, encoded with the AP value in the top 3 bits and the log +base 2 of the page size in the bottom 6 bits. + +4.102 KVM_PPC_RESIZE_HPT_PREPARE +-------------------------------- + +:Capability: KVM_CAP_SPAPR_RESIZE_HPT +:Architectures: powerpc +:Type: vm ioctl +:Parameters: struct kvm_ppc_resize_hpt (in) +:Returns: 0 on successful completion, + >0 if a new HPT is being prepared, the value is an estimated + number of milliseconds until preparation is complete, + -EFAULT if struct kvm_reinject_control cannot be read, + -EINVAL if the supplied shift or flags are invalid,when moving existing + HPT entries to the new HPT, -EIO on other error conditions Used to implement the PAPR extension for runtime resizing of a guest's @@ -3497,6 +3883,7 @@ requested in the parameters, discards the existing pending HPT and creates a new one as above. If called when there is a pending HPT of the size requested, will: + * If preparation of the pending HPT is already complete, return 0 * If preparation of the pending HPT has failed, return an error code, then discard the pending HPT. @@ -3513,26 +3900,29 @@ Normally this will be called repeatedly with the same parameters until it returns <= 0. The first call will initiate preparation, subsequent ones will monitor preparation until it completes or fails. -struct kvm_ppc_resize_hpt { +:: + + struct kvm_ppc_resize_hpt { __u64 flags; __u32 shift; __u32 pad; -}; + }; 4.103 KVM_PPC_RESIZE_HPT_COMMIT +------------------------------- -Capability: KVM_CAP_SPAPR_RESIZE_HPT -Architectures: powerpc -Type: vm ioctl -Parameters: struct kvm_ppc_resize_hpt (in) -Returns: 0 on successful completion, +:Capability: KVM_CAP_SPAPR_RESIZE_HPT +:Architectures: powerpc +:Type: vm ioctl +:Parameters: struct kvm_ppc_resize_hpt (in) +:Returns: 0 on successful completion, -EFAULT if struct kvm_reinject_control cannot be read, - -EINVAL if the supplied shift or flags are invalid + -EINVAL if the supplied shift or flags are invalid, -ENXIO is there is no pending HPT, or the pending HPT doesn't - have the requested size - -EBUSY if the pending HPT is not fully prepared + have the requested size, + -EBUSY if the pending HPT is not fully prepared, -ENOSPC if there was a hash collision when moving existing - HPT entries to the new HPT + HPT entries to the new HPT, -EIO on other error conditions Used to implement the PAPR extension for runtime resizing of a guest's @@ -3555,31 +3945,35 @@ HPT and the previous HPT will be discarded. On failure, the guest will still be operating on its previous HPT. -struct kvm_ppc_resize_hpt { +:: + + struct kvm_ppc_resize_hpt { __u64 flags; __u32 shift; __u32 pad; -}; + }; 4.104 KVM_X86_GET_MCE_CAP_SUPPORTED +----------------------------------- -Capability: KVM_CAP_MCE -Architectures: x86 -Type: system ioctl -Parameters: u64 mce_cap (out) -Returns: 0 on success, -1 on error +:Capability: KVM_CAP_MCE +:Architectures: x86 +:Type: system ioctl +:Parameters: u64 mce_cap (out) +:Returns: 0 on success, -1 on error Returns supported MCE capabilities. The u64 mce_cap parameter has the same format as the MSR_IA32_MCG_CAP register. Supported capabilities will have the corresponding bits set. 4.105 KVM_X86_SETUP_MCE +----------------------- -Capability: KVM_CAP_MCE -Architectures: x86 -Type: vcpu ioctl -Parameters: u64 mcg_cap (in) -Returns: 0 on success, +:Capability: KVM_CAP_MCE +:Architectures: x86 +:Type: vcpu ioctl +:Parameters: u64 mcg_cap (in) +:Returns: 0 on success, -EFAULT if u64 mcg_cap cannot be read, -EINVAL if the requested number of banks is invalid, -EINVAL if requested MCE capability is not supported. @@ -3592,20 +3986,21 @@ checking for KVM_CAP_MCE. The supported capabilities can be retrieved with KVM_X86_GET_MCE_CAP_SUPPORTED. 4.106 KVM_X86_SET_MCE +--------------------- -Capability: KVM_CAP_MCE -Architectures: x86 -Type: vcpu ioctl -Parameters: struct kvm_x86_mce (in) -Returns: 0 on success, +:Capability: KVM_CAP_MCE +:Architectures: x86 +:Type: vcpu ioctl +:Parameters: struct kvm_x86_mce (in) +:Returns: 0 on success, -EFAULT if struct kvm_x86_mce cannot be read, -EINVAL if the bank number is invalid, -EINVAL if VAL bit is not set in status field. Inject a machine check error (MCE) into the guest. The input -parameter is: +parameter is:: -struct kvm_x86_mce { + struct kvm_x86_mce { __u64 status; __u64 addr; __u64 misc; @@ -3613,7 +4008,7 @@ struct kvm_x86_mce { __u8 bank; __u8 pad1[7]; __u64 pad2[3]; -}; + }; If the MCE being reported is an uncorrected error, KVM will inject it as an MCE exception into the guest. If the guest @@ -3625,15 +4020,17 @@ store it in the corresponding bank (provided this bank is not holding a previously reported uncorrected error). 4.107 KVM_S390_GET_CMMA_BITS +---------------------------- -Capability: KVM_CAP_S390_CMMA_MIGRATION -Architectures: s390 -Type: vm ioctl -Parameters: struct kvm_s390_cmma_log (in, out) -Returns: 0 on success, a negative value on error +:Capability: KVM_CAP_S390_CMMA_MIGRATION +:Architectures: s390 +:Type: vm ioctl +:Parameters: struct kvm_s390_cmma_log (in, out) +:Returns: 0 on success, a negative value on error This ioctl is used to get the values of the CMMA bits on the s390 architecture. It is meant to be used in two scenarios: + - During live migration to save the CMMA values. Live migration needs to be enabled via the KVM_REQ_START_MIGRATION VM property. - To non-destructively peek at the CMMA values, with the flag @@ -3643,9 +4040,12 @@ The ioctl takes parameters via the kvm_s390_cmma_log struct. The desired values are written to a buffer whose location is indicated via the "values" member in the kvm_s390_cmma_log struct. The values in the input struct are also updated as needed. + Each CMMA value takes up one byte. -struct kvm_s390_cmma_log { +:: + + struct kvm_s390_cmma_log { __u64 start_gfn; __u32 count; __u32 flags; @@ -3654,7 +4054,7 @@ struct kvm_s390_cmma_log { __u64 mask; }; __u64 values; -}; + }; start_gfn is the number of the first guest frame whose CMMA values are to be retrieved, @@ -3715,12 +4115,13 @@ KVM_S390_CMMA_PEEK is not set but migration mode was not enabled, with present for the addresses (e.g. when using hugepages). 4.108 KVM_S390_SET_CMMA_BITS +---------------------------- -Capability: KVM_CAP_S390_CMMA_MIGRATION -Architectures: s390 -Type: vm ioctl -Parameters: struct kvm_s390_cmma_log (in) -Returns: 0 on success, a negative value on error +:Capability: KVM_CAP_S390_CMMA_MIGRATION +:Architectures: s390 +:Type: vm ioctl +:Parameters: struct kvm_s390_cmma_log (in) +:Returns: 0 on success, a negative value on error This ioctl is used to set the values of the CMMA bits on the s390 architecture. It is meant to be used during live migration to restore @@ -3728,16 +4129,18 @@ the CMMA values, but there are no restrictions on its use. The ioctl takes parameters via the kvm_s390_cmma_values struct. Each CMMA value takes up one byte. -struct kvm_s390_cmma_log { +:: + + struct kvm_s390_cmma_log { __u64 start_gfn; __u32 count; __u32 flags; union { __u64 remaining; __u64 mask; - }; + }; __u64 values; -}; + }; start_gfn indicates the starting guest frame number, @@ -3760,26 +4163,27 @@ or if no page table is present for the addresses (e.g. when using hugepages). 4.109 KVM_PPC_GET_CPU_CHAR +-------------------------- -Capability: KVM_CAP_PPC_GET_CPU_CHAR -Architectures: powerpc -Type: vm ioctl -Parameters: struct kvm_ppc_cpu_char (out) -Returns: 0 on successful completion +:Capability: KVM_CAP_PPC_GET_CPU_CHAR +:Architectures: powerpc +:Type: vm ioctl +:Parameters: struct kvm_ppc_cpu_char (out) +:Returns: 0 on successful completion, -EFAULT if struct kvm_ppc_cpu_char cannot be written This ioctl gives userspace information about certain characteristics of the CPU relating to speculative execution of instructions and possible information leakage resulting from speculative execution (see CVE-2017-5715, CVE-2017-5753 and CVE-2017-5754). The information is -returned in struct kvm_ppc_cpu_char, which looks like this: +returned in struct kvm_ppc_cpu_char, which looks like this:: -struct kvm_ppc_cpu_char { + struct kvm_ppc_cpu_char { __u64 character; /* characteristics of the CPU */ __u64 behaviour; /* recommended software behaviour */ __u64 character_mask; /* valid bits in character */ __u64 behaviour_mask; /* valid bits in behaviour */ -}; + }; For extensibility, the character_mask and behaviour_mask fields indicate which bits of character and behaviour have been filled in by @@ -3806,12 +4210,13 @@ These fields use the same bit definitions as the new H_GET_CPU_CHARACTERISTICS hypercall. 4.110 KVM_MEMORY_ENCRYPT_OP +--------------------------- -Capability: basic -Architectures: x86 -Type: system -Parameters: an opaque platform specific structure (in/out) -Returns: 0 on success; -1 on error +:Capability: basic +:Architectures: x86 +:Type: system +:Parameters: an opaque platform specific structure (in/out) +:Returns: 0 on success; -1 on error If the platform supports creating encrypted VMs then this ioctl can be used for issuing platform-specific memory encryption commands to manage those @@ -3822,12 +4227,13 @@ Currently, this ioctl is used for issuing Secure Encrypted Virtualization Documentation/virt/kvm/amd-memory-encryption.rst. 4.111 KVM_MEMORY_ENCRYPT_REG_REGION +----------------------------------- -Capability: basic -Architectures: x86 -Type: system -Parameters: struct kvm_enc_region (in) -Returns: 0 on success; -1 on error +:Capability: basic +:Architectures: x86 +:Type: system +:Parameters: struct kvm_enc_region (in) +:Returns: 0 on success; -1 on error This ioctl can be used to register a guest memory region which may contain encrypted data (e.g. guest RAM, SMRAM etc). @@ -3845,60 +4251,71 @@ swap or migrate (move) ciphertext pages. Hence, for now we pin the guest memory region registered with the ioctl. 4.112 KVM_MEMORY_ENCRYPT_UNREG_REGION +------------------------------------- -Capability: basic -Architectures: x86 -Type: system -Parameters: struct kvm_enc_region (in) -Returns: 0 on success; -1 on error +:Capability: basic +:Architectures: x86 +:Type: system +:Parameters: struct kvm_enc_region (in) +:Returns: 0 on success; -1 on error This ioctl can be used to unregister the guest memory region registered with KVM_MEMORY_ENCRYPT_REG_REGION ioctl above. 4.113 KVM_HYPERV_EVENTFD +------------------------ -Capability: KVM_CAP_HYPERV_EVENTFD -Architectures: x86 -Type: vm ioctl -Parameters: struct kvm_hyperv_eventfd (in) +:Capability: KVM_CAP_HYPERV_EVENTFD +:Architectures: x86 +:Type: vm ioctl +:Parameters: struct kvm_hyperv_eventfd (in) This ioctl (un)registers an eventfd to receive notifications from the guest on the specified Hyper-V connection id through the SIGNAL_EVENT hypercall, without causing a user exit. SIGNAL_EVENT hypercall with non-zero event flag number (bits 24-31) still triggers a KVM_EXIT_HYPERV_HCALL user exit. -struct kvm_hyperv_eventfd { +:: + + struct kvm_hyperv_eventfd { __u32 conn_id; __s32 fd; __u32 flags; __u32 padding[3]; -}; + }; -The conn_id field should fit within 24 bits: +The conn_id field should fit within 24 bits:: -#define KVM_HYPERV_CONN_ID_MASK 0x00ffffff + #define KVM_HYPERV_CONN_ID_MASK 0x00ffffff -The acceptable values for the flags field are: +The acceptable values for the flags field are:: -#define KVM_HYPERV_EVENTFD_DEASSIGN (1 << 0) + #define KVM_HYPERV_EVENTFD_DEASSIGN (1 << 0) -Returns: 0 on success, - -EINVAL if conn_id or flags is outside the allowed range - -ENOENT on deassign if the conn_id isn't registered - -EEXIST on assign if the conn_id is already registered +:Returns: 0 on success, + -EINVAL if conn_id or flags is outside the allowed range, + -ENOENT on deassign if the conn_id isn't registered, + -EEXIST on assign if the conn_id is already registered 4.114 KVM_GET_NESTED_STATE +-------------------------- + +:Capability: KVM_CAP_NESTED_STATE +:Architectures: x86 +:Type: vcpu ioctl +:Parameters: struct kvm_nested_state (in/out) +:Returns: 0 on success, -1 on error -Capability: KVM_CAP_NESTED_STATE -Architectures: x86 -Type: vcpu ioctl -Parameters: struct kvm_nested_state (in/out) -Returns: 0 on success, -1 on error Errors: - E2BIG: the total state size exceeds the value of 'size' specified by + + ===== ============================================================= + E2BIG the total state size exceeds the value of 'size' specified by the user; the size required will be written into size. + ===== ============================================================= + +:: -struct kvm_nested_state { + struct kvm_nested_state { __u16 flags; __u16 format; __u32 size; @@ -3915,33 +4332,33 @@ struct kvm_nested_state { struct kvm_vmx_nested_state_data vmx[0]; struct kvm_svm_nested_state_data svm[0]; } data; -}; + }; -#define KVM_STATE_NESTED_GUEST_MODE 0x00000001 -#define KVM_STATE_NESTED_RUN_PENDING 0x00000002 -#define KVM_STATE_NESTED_EVMCS 0x00000004 + #define KVM_STATE_NESTED_GUEST_MODE 0x00000001 + #define KVM_STATE_NESTED_RUN_PENDING 0x00000002 + #define KVM_STATE_NESTED_EVMCS 0x00000004 -#define KVM_STATE_NESTED_FORMAT_VMX 0 -#define KVM_STATE_NESTED_FORMAT_SVM 1 + #define KVM_STATE_NESTED_FORMAT_VMX 0 + #define KVM_STATE_NESTED_FORMAT_SVM 1 -#define KVM_STATE_NESTED_VMX_VMCS_SIZE 0x1000 + #define KVM_STATE_NESTED_VMX_VMCS_SIZE 0x1000 -#define KVM_STATE_NESTED_VMX_SMM_GUEST_MODE 0x00000001 -#define KVM_STATE_NESTED_VMX_SMM_VMXON 0x00000002 + #define KVM_STATE_NESTED_VMX_SMM_GUEST_MODE 0x00000001 + #define KVM_STATE_NESTED_VMX_SMM_VMXON 0x00000002 -struct kvm_vmx_nested_state_hdr { + struct kvm_vmx_nested_state_hdr { __u64 vmxon_pa; __u64 vmcs12_pa; struct { __u16 flags; } smm; -}; + }; -struct kvm_vmx_nested_state_data { + struct kvm_vmx_nested_state_data { __u8 vmcs12[KVM_STATE_NESTED_VMX_VMCS_SIZE]; __u8 shadow_vmcs12[KVM_STATE_NESTED_VMX_VMCS_SIZE]; -}; + }; This ioctl copies the vcpu's nested virtualization state from the kernel to userspace. @@ -3950,24 +4367,26 @@ The maximum size of the state can be retrieved by passing KVM_CAP_NESTED_STATE to the KVM_CHECK_EXTENSION ioctl(). 4.115 KVM_SET_NESTED_STATE +-------------------------- -Capability: KVM_CAP_NESTED_STATE -Architectures: x86 -Type: vcpu ioctl -Parameters: struct kvm_nested_state (in) -Returns: 0 on success, -1 on error +:Capability: KVM_CAP_NESTED_STATE +:Architectures: x86 +:Type: vcpu ioctl +:Parameters: struct kvm_nested_state (in) +:Returns: 0 on success, -1 on error This copies the vcpu's kvm_nested_state struct from userspace to the kernel. For the definition of struct kvm_nested_state, see KVM_GET_NESTED_STATE. 4.116 KVM_(UN)REGISTER_COALESCED_MMIO +------------------------------------- -Capability: KVM_CAP_COALESCED_MMIO (for coalesced mmio) - KVM_CAP_COALESCED_PIO (for coalesced pio) -Architectures: all -Type: vm ioctl -Parameters: struct kvm_coalesced_mmio_zone -Returns: 0 on success, < 0 on error +:Capability: KVM_CAP_COALESCED_MMIO (for coalesced mmio) + KVM_CAP_COALESCED_PIO (for coalesced pio) +:Architectures: all +:Type: vm ioctl +:Parameters: struct kvm_coalesced_mmio_zone +:Returns: 0 on success, < 0 on error Coalesced I/O is a performance optimization that defers hardware register write emulation so that userspace exits are avoided. It is @@ -3989,15 +4408,18 @@ between coalesced mmio and pio except that coalesced pio records accesses to I/O ports. 4.117 KVM_CLEAR_DIRTY_LOG (vm ioctl) +------------------------------------ + +:Capability: KVM_CAP_MANUAL_DIRTY_LOG_PROTECT2 +:Architectures: x86, arm, arm64, mips +:Type: vm ioctl +:Parameters: struct kvm_dirty_log (in) +:Returns: 0 on success, -1 on error -Capability: KVM_CAP_MANUAL_DIRTY_LOG_PROTECT2 -Architectures: x86, arm, arm64, mips -Type: vm ioctl -Parameters: struct kvm_dirty_log (in) -Returns: 0 on success, -1 on error +:: -/* for KVM_CLEAR_DIRTY_LOG */ -struct kvm_clear_dirty_log { + /* for KVM_CLEAR_DIRTY_LOG */ + struct kvm_clear_dirty_log { __u32 slot; __u32 num_pages; __u64 first_page; @@ -4005,7 +4427,7 @@ struct kvm_clear_dirty_log { void __user *dirty_bitmap; /* one bit per page */ __u64 padding; }; -}; + }; The ioctl clears the dirty status of pages in a memory slot, according to the bitmap that is passed in struct kvm_clear_dirty_log's dirty_bitmap @@ -4029,20 +4451,23 @@ However, it can always be used as long as KVM_CHECK_EXTENSION confirms that KVM_CAP_MANUAL_DIRTY_LOG_PROTECT2 is present. 4.118 KVM_GET_SUPPORTED_HV_CPUID +-------------------------------- -Capability: KVM_CAP_HYPERV_CPUID -Architectures: x86 -Type: vcpu ioctl -Parameters: struct kvm_cpuid2 (in/out) -Returns: 0 on success, -1 on error +:Capability: KVM_CAP_HYPERV_CPUID +:Architectures: x86 +:Type: vcpu ioctl +:Parameters: struct kvm_cpuid2 (in/out) +:Returns: 0 on success, -1 on error -struct kvm_cpuid2 { +:: + + struct kvm_cpuid2 { __u32 nent; __u32 padding; struct kvm_cpuid_entry2 entries[0]; -}; + }; -struct kvm_cpuid_entry2 { + struct kvm_cpuid_entry2 { __u32 function; __u32 index; __u32 flags; @@ -4051,7 +4476,7 @@ struct kvm_cpuid_entry2 { __u32 ecx; __u32 edx; __u32 padding[3]; -}; + }; This ioctl returns x86 cpuid features leaves related to Hyper-V emulation in KVM. Userspace can use the information returned by this ioctl to construct @@ -4064,13 +4489,13 @@ KVM_GET_SUPPORTED_CPUID ioctl because some of them intersect with KVM feature leaves (0x40000000, 0x40000001). Currently, the following list of CPUID leaves are returned: - HYPERV_CPUID_VENDOR_AND_MAX_FUNCTIONS - HYPERV_CPUID_INTERFACE - HYPERV_CPUID_VERSION - HYPERV_CPUID_FEATURES - HYPERV_CPUID_ENLIGHTMENT_INFO - HYPERV_CPUID_IMPLEMENT_LIMITS - HYPERV_CPUID_NESTED_FEATURES + - HYPERV_CPUID_VENDOR_AND_MAX_FUNCTIONS + - HYPERV_CPUID_INTERFACE + - HYPERV_CPUID_VERSION + - HYPERV_CPUID_FEATURES + - HYPERV_CPUID_ENLIGHTMENT_INFO + - HYPERV_CPUID_IMPLEMENT_LIMITS + - HYPERV_CPUID_NESTED_FEATURES HYPERV_CPUID_NESTED_FEATURES leaf is only exposed when Enlightened VMCS was enabled on the corresponding vCPU (KVM_CAP_HYPERV_ENLIGHTENED_VMCS). @@ -4086,17 +4511,25 @@ number of valid entries in the 'entries' array, which is then filled. userspace should not expect to get any particular value there. 4.119 KVM_ARM_VCPU_FINALIZE +--------------------------- + +:Architectures: arm, arm64 +:Type: vcpu ioctl +:Parameters: int feature (in) +:Returns: 0 on success, -1 on error -Architectures: arm, arm64 -Type: vcpu ioctl -Parameters: int feature (in) -Returns: 0 on success, -1 on error Errors: - EPERM: feature not enabled, needs configuration, or already finalized - EINVAL: feature unknown or not present + + ====== ============================================================== + EPERM feature not enabled, needs configuration, or already finalized + EINVAL feature unknown or not present + ====== ============================================================== Recognised values for feature: + + ===== =========================================== arm64 KVM_ARM_VCPU_SVE (requires KVM_CAP_ARM_SVE) + ===== =========================================== Finalizes the configuration of the specified vcpu feature. @@ -4120,21 +4553,24 @@ See KVM_ARM_VCPU_INIT for details of vcpu features that require finalization using this ioctl. 4.120 KVM_SET_PMU_EVENT_FILTER +------------------------------ + +:Capability: KVM_CAP_PMU_EVENT_FILTER +:Architectures: x86 +:Type: vm ioctl +:Parameters: struct kvm_pmu_event_filter (in) +:Returns: 0 on success, -1 on error -Capability: KVM_CAP_PMU_EVENT_FILTER -Architectures: x86 -Type: vm ioctl -Parameters: struct kvm_pmu_event_filter (in) -Returns: 0 on success, -1 on error +:: -struct kvm_pmu_event_filter { + struct kvm_pmu_event_filter { __u32 action; __u32 nevents; __u32 fixed_counter_bitmap; __u32 flags; __u32 pad[4]; __u64 events[0]; -}; + }; This ioctl restricts the set of PMU events that the guest can program. The argument holds a list of events which will be allowed or denied. @@ -4145,20 +4581,26 @@ counters are controlled by the fixed_counter_bitmap. No flags are defined yet, the field must be zero. -Valid values for 'action': -#define KVM_PMU_EVENT_ALLOW 0 -#define KVM_PMU_EVENT_DENY 1 +Valid values for 'action':: + + #define KVM_PMU_EVENT_ALLOW 0 + #define KVM_PMU_EVENT_DENY 1 4.121 KVM_PPC_SVM_OFF +--------------------- + +:Capability: basic +:Architectures: powerpc +:Type: vm ioctl +:Parameters: none +:Returns: 0 on successful completion, -Capability: basic -Architectures: powerpc -Type: vm ioctl -Parameters: none -Returns: 0 on successful completion, Errors: - EINVAL: if ultravisor failed to terminate the secure guest - ENOMEM: if hypervisor failed to allocate new radix page tables for guest + + ====== ================================================================ + EINVAL if ultravisor failed to terminate the secure guest + ENOMEM if hypervisor failed to allocate new radix page tables for guest + ====== ================================================================ This ioctl is used to turn off the secure mode of the guest or transition the guest from secure mode to normal mode. This is invoked when the guest @@ -4168,8 +4610,47 @@ This ioctl issues an ultravisor call to terminate the secure guest, unpins the VPA pages and releases all the device pages that are used to track the secure pages by hypervisor. +4.122 KVM_S390_NORMAL_RESET +--------------------------- + +:Capability: KVM_CAP_S390_VCPU_RESETS +:Architectures: s390 +:Type: vcpu ioctl +:Parameters: none +:Returns: 0 + +This ioctl resets VCPU registers and control structures according to +the cpu reset definition in the POP (Principles Of Operation). + +4.123 KVM_S390_INITIAL_RESET +---------------------------- + +:Capability: none +:Architectures: s390 +:Type: vcpu ioctl +:Parameters: none +:Returns: 0 + +This ioctl resets VCPU registers and control structures according to +the initial cpu reset definition in the POP. However, the cpu is not +put into ESA mode. This reset is a superset of the normal reset. + +4.124 KVM_S390_CLEAR_RESET +-------------------------- + +:Capability: KVM_CAP_S390_VCPU_RESETS +:Architectures: s390 +:Type: vcpu ioctl +:Parameters: none +:Returns: 0 + +This ioctl resets VCPU registers and control structures according to +the clear cpu reset definition in the POP. However, the cpu is not put +into ESA mode. This reset is a superset of the initial reset. + + 5. The kvm_run structure ------------------------- +======================== Application code obtains a pointer to the kvm_run structure by mmap()ing a vcpu fd. From that point, application code can control @@ -4177,13 +4658,17 @@ execution by changing fields in kvm_run prior to calling the KVM_RUN ioctl, and obtain information about the reason KVM_RUN returned by looking up structure members. -struct kvm_run { +:: + + struct kvm_run { /* in */ __u8 request_interrupt_window; Request that KVM_RUN return when it becomes possible to inject external interrupts into the guest. Useful in conjunction with KVM_INTERRUPT. +:: + __u8 immediate_exit; This field is polled once when KVM_RUN starts; if non-zero, KVM_RUN @@ -4195,6 +4680,8 @@ a signal handler that sets run->immediate_exit to a non-zero value. This field is ignored if KVM_CAP_IMMEDIATE_EXIT is not available. +:: + __u8 padding1[6]; /* out */ @@ -4204,16 +4691,22 @@ When KVM_RUN has returned successfully (return value 0), this informs application code why KVM_RUN has returned. Allowable values for this field are detailed below. +:: + __u8 ready_for_interrupt_injection; If request_interrupt_window has been specified, this field indicates an interrupt can be injected now with KVM_INTERRUPT. +:: + __u8 if_flag; The value of the current interrupt flag. Only valid if in-kernel local APIC is not used. +:: + __u16 flags; More architecture-specific flags detailing state of the VCPU that may @@ -4221,17 +4714,23 @@ affect the device's behavior. The only currently defined flag is KVM_RUN_X86_SMM, which is valid on x86 machines and is set if the VCPU is in system management mode. +:: + /* in (pre_kvm_run), out (post_kvm_run) */ __u64 cr8; The value of the cr8 register. Only valid if in-kernel local APIC is not used. Both input and output. +:: + __u64 apic_base; The value of the APIC BASE msr. Only valid if in-kernel local APIC is not used. Both input and output. +:: + union { /* KVM_EXIT_UNKNOWN */ struct { @@ -4242,6 +4741,8 @@ If exit_reason is KVM_EXIT_UNKNOWN, the vcpu has exited due to unknown reasons. Further architecture-specific information is available in hardware_exit_reason. +:: + /* KVM_EXIT_FAIL_ENTRY */ struct { __u64 hardware_entry_failure_reason; @@ -4251,6 +4752,8 @@ If exit_reason is KVM_EXIT_FAIL_ENTRY, the vcpu could not be run due to unknown reasons. Further architecture-specific information is available in hardware_entry_failure_reason. +:: + /* KVM_EXIT_EXCEPTION */ struct { __u32 exception; @@ -4259,10 +4762,12 @@ available in hardware_entry_failure_reason. Unused. +:: + /* KVM_EXIT_IO */ struct { -#define KVM_EXIT_IO_IN 0 -#define KVM_EXIT_IO_OUT 1 + #define KVM_EXIT_IO_IN 0 + #define KVM_EXIT_IO_OUT 1 __u8 direction; __u8 size; /* bytes */ __u16 port; @@ -4276,6 +4781,8 @@ data_offset describes where the data is located (KVM_EXIT_IO_OUT) or where kvm expects application code to place the data for the next KVM_RUN invocation (KVM_EXIT_IO_IN). Data format is a packed array. +:: + /* KVM_EXIT_DEBUG */ struct { struct kvm_debug_exit_arch arch; @@ -4284,6 +4791,8 @@ KVM_RUN invocation (KVM_EXIT_IO_IN). Data format is a packed array. If the exit_reason is KVM_EXIT_DEBUG, then a vcpu is processing a debug event for which architecture specific information is returned. +:: + /* KVM_EXIT_MMIO */ struct { __u64 phys_addr; @@ -4301,14 +4810,19 @@ The 'data' member contains, in its first 'len' bytes, the value as it would appear if the VCPU performed a load or store of the appropriate width directly to the byte array. -NOTE: For KVM_EXIT_IO, KVM_EXIT_MMIO, KVM_EXIT_OSI, KVM_EXIT_PAPR and +.. note:: + + For KVM_EXIT_IO, KVM_EXIT_MMIO, KVM_EXIT_OSI, KVM_EXIT_PAPR and KVM_EXIT_EPR the corresponding + operations are complete (and guest state is consistent) only after userspace has re-entered the kernel with KVM_RUN. The kernel side will first finish incomplete operations and then check for pending signals. Userspace can re-enter the guest with an unmasked signal pending to complete pending operations. +:: + /* KVM_EXIT_HYPERCALL */ struct { __u64 nr; @@ -4320,7 +4834,10 @@ pending operations. Unused. This was once used for 'hypercall to userspace'. To implement such functionality, use KVM_EXIT_IO (x86) or KVM_EXIT_MMIO (all except s390). -Note KVM_EXIT_IO is significantly faster than KVM_EXIT_MMIO. + +.. note:: KVM_EXIT_IO is significantly faster than KVM_EXIT_MMIO. + +:: /* KVM_EXIT_TPR_ACCESS */ struct { @@ -4331,6 +4848,8 @@ Note KVM_EXIT_IO is significantly faster than KVM_EXIT_MMIO. To be documented (KVM_TPR_ACCESS_REPORTING). +:: + /* KVM_EXIT_S390_SIEIC */ struct { __u8 icptcode; @@ -4342,16 +4861,20 @@ To be documented (KVM_TPR_ACCESS_REPORTING). s390 specific. +:: + /* KVM_EXIT_S390_RESET */ -#define KVM_S390_RESET_POR 1 -#define KVM_S390_RESET_CLEAR 2 -#define KVM_S390_RESET_SUBSYSTEM 4 -#define KVM_S390_RESET_CPU_INIT 8 -#define KVM_S390_RESET_IPL 16 + #define KVM_S390_RESET_POR 1 + #define KVM_S390_RESET_CLEAR 2 + #define KVM_S390_RESET_SUBSYSTEM 4 + #define KVM_S390_RESET_CPU_INIT 8 + #define KVM_S390_RESET_IPL 16 __u64 s390_reset_flags; s390 specific. +:: + /* KVM_EXIT_S390_UCONTROL */ struct { __u64 trans_exc_code; @@ -4366,6 +4889,8 @@ in the cpu's lowcore are presented here as defined by the z Architecture Principles of Operation Book in the Chapter for Dynamic Address Translation (DAT) +:: + /* KVM_EXIT_DCR */ struct { __u32 dcrn; @@ -4375,6 +4900,8 @@ Principles of Operation Book in the Chapter for Dynamic Address Translation Deprecated - was used for 440 KVM. +:: + /* KVM_EXIT_OSI */ struct { __u64 gprs[32]; @@ -4388,6 +4915,8 @@ Userspace can now handle the hypercall and when it's done modify the gprs as necessary. Upon guest entry all guest GPRs will then be replaced by the values in this struct. +:: + /* KVM_EXIT_PAPR_HCALL */ struct { __u64 nr; @@ -4405,6 +4934,8 @@ The possible hypercalls are defined in the Power Architecture Platform Requirements (PAPR) document available from www.power.org (free developer registration required to access it). +:: + /* KVM_EXIT_S390_TSCH */ struct { __u16 subchannel_id; @@ -4421,6 +4952,8 @@ interrupt for the target subchannel has been dequeued and subchannel_id, subchannel_nr, io_int_parm and io_int_word contain the parameters for that interrupt. ipb is needed for instruction parameter decoding. +:: + /* KVM_EXIT_EPR */ struct { __u32 epr; @@ -4440,11 +4973,13 @@ It gets triggered whenever both KVM_CAP_PPC_EPR are enabled and an external interrupt has just been delivered into the guest. User space should put the acknowledged interrupt vector into the 'epr' field. +:: + /* KVM_EXIT_SYSTEM_EVENT */ struct { -#define KVM_SYSTEM_EVENT_SHUTDOWN 1 -#define KVM_SYSTEM_EVENT_RESET 2 -#define KVM_SYSTEM_EVENT_CRASH 3 + #define KVM_SYSTEM_EVENT_SHUTDOWN 1 + #define KVM_SYSTEM_EVENT_RESET 2 + #define KVM_SYSTEM_EVENT_CRASH 3 __u32 type; __u64 flags; } system_event; @@ -4457,18 +4992,21 @@ the system-level event type. The 'flags' field describes architecture specific flags for the system-level event. Valid values for 'type' are: - KVM_SYSTEM_EVENT_SHUTDOWN -- the guest has requested a shutdown of the + + - KVM_SYSTEM_EVENT_SHUTDOWN -- the guest has requested a shutdown of the VM. Userspace is not obliged to honour this, and if it does honour this does not need to destroy the VM synchronously (ie it may call KVM_RUN again before shutdown finally occurs). - KVM_SYSTEM_EVENT_RESET -- the guest has requested a reset of the VM. + - KVM_SYSTEM_EVENT_RESET -- the guest has requested a reset of the VM. As with SHUTDOWN, userspace can choose to ignore the request, or to schedule the reset to occur in the future and may call KVM_RUN again. - KVM_SYSTEM_EVENT_CRASH -- the guest crash occurred and the guest + - KVM_SYSTEM_EVENT_CRASH -- the guest crash occurred and the guest has requested a crash condition maintenance. Userspace can choose to ignore the request, or to gather VM memory core dump and/or reset/shutdown of the VM. +:: + /* KVM_EXIT_IOAPIC_EOI */ struct { __u8 vector; @@ -4481,9 +5019,11 @@ the userspace IOAPIC should process the EOI and retrigger the interrupt if it is still asserted. Vector is the LAPIC interrupt vector for which the EOI was received. +:: + struct kvm_hyperv_exit { -#define KVM_EXIT_HYPERV_SYNIC 1 -#define KVM_EXIT_HYPERV_HCALL 2 + #define KVM_EXIT_HYPERV_SYNIC 1 + #define KVM_EXIT_HYPERV_HCALL 2 __u32 type; union { struct { @@ -4501,14 +5041,20 @@ EOI was received. }; /* KVM_EXIT_HYPERV */ struct kvm_hyperv_exit hyperv; + Indicates that the VCPU exits into userspace to process some tasks related to Hyper-V emulation. + Valid values for 'type' are: - KVM_EXIT_HYPERV_SYNIC -- synchronously notify user-space about + + - KVM_EXIT_HYPERV_SYNIC -- synchronously notify user-space about + Hyper-V SynIC state change. Notification is used to remap SynIC event/message pages and to enable/disable SynIC messages/events processing in userspace. +:: + /* KVM_EXIT_ARM_NISV */ struct { __u64 esr_iss; @@ -4542,6 +5088,8 @@ Note that KVM does not skip the faulting instruction as it does for KVM_EXIT_MMIO, but userspace has to emulate any change to the processing state if it decides to decode and emulate the instruction. +:: + /* Fix the size of the union. */ char padding[256]; }; @@ -4566,18 +5114,20 @@ avoid some system call overhead if userspace has to handle the exit. Userspace can query the validity of the structure by checking kvm_valid_regs for specific bits. These bits are architecture specific and usually define the validity of a groups of registers. (e.g. one bit - for general purpose registers) +for general purpose registers) Please note that the kernel is allowed to use the kvm_run structure as the primary storage for certain register types. Therefore, the kernel may use the values in kvm_run even if the corresponding bit in kvm_dirty_regs is not set. -}; +:: + + }; 6. Capabilities that can be enabled on vCPUs --------------------------------------------- +============================================ There are certain capabilities that change the behavior of the virtual CPU or the virtual machine when enabled. To enable them, please see section 4.37. @@ -4586,23 +5136,28 @@ the virtual machine is when enabling them. The following information is provided along with the description: - Architectures: which instruction set architectures provide this ioctl. + Architectures: + which instruction set architectures provide this ioctl. x86 includes both i386 and x86_64. - Target: whether this is a per-vcpu or per-vm capability. + Target: + whether this is a per-vcpu or per-vm capability. - Parameters: what parameters are accepted by the capability. + Parameters: + what parameters are accepted by the capability. - Returns: the return value. General error numbers (EBADF, ENOMEM, EINVAL) + Returns: + the return value. General error numbers (EBADF, ENOMEM, EINVAL) are not detailed, but errors with specific meanings are. 6.1 KVM_CAP_PPC_OSI +------------------- -Architectures: ppc -Target: vcpu -Parameters: none -Returns: 0 on success; -1 on error +:Architectures: ppc +:Target: vcpu +:Parameters: none +:Returns: 0 on success; -1 on error This capability enables interception of OSI hypercalls that otherwise would be treated as normal system calls to be injected into the guest. OSI hypercalls @@ -4613,11 +5168,12 @@ When this capability is enabled, KVM_EXIT_OSI can occur. 6.2 KVM_CAP_PPC_PAPR +-------------------- -Architectures: ppc -Target: vcpu -Parameters: none -Returns: 0 on success; -1 on error +:Architectures: ppc +:Target: vcpu +:Parameters: none +:Returns: 0 on success; -1 on error This capability enables interception of PAPR hypercalls. PAPR hypercalls are done using the hypercall instruction "sc 1". @@ -4633,18 +5189,21 @@ When this capability is enabled, KVM_EXIT_PAPR_HCALL can occur. 6.3 KVM_CAP_SW_TLB +------------------ + +:Architectures: ppc +:Target: vcpu +:Parameters: args[0] is the address of a struct kvm_config_tlb +:Returns: 0 on success; -1 on error -Architectures: ppc -Target: vcpu -Parameters: args[0] is the address of a struct kvm_config_tlb -Returns: 0 on success; -1 on error +:: -struct kvm_config_tlb { + struct kvm_config_tlb { __u64 params; __u64 array; __u32 mmu_type; __u32 array_len; -}; + }; Configures the virtual CPU's TLB array, establishing a shared memory area between userspace and KVM. The "params" and "array" fields are userspace @@ -4663,6 +5222,7 @@ to tell KVM which entries have been changed, prior to calling KVM_RUN again on this vcpu. For mmu types KVM_MMU_FSL_BOOKE_NOHV and KVM_MMU_FSL_BOOKE_HV: + - The "params" field is of type "struct kvm_book3e_206_tlb_params". - The "array" field points to an array of type "struct kvm_book3e_206_tlb_entry". @@ -4676,11 +5236,12 @@ For mmu types KVM_MMU_FSL_BOOKE_NOHV and KVM_MMU_FSL_BOOKE_HV: hardware ignores this value for TLB0. 6.4 KVM_CAP_S390_CSS_SUPPORT +---------------------------- -Architectures: s390 -Target: vcpu -Parameters: none -Returns: 0 on success; -1 on error +:Architectures: s390 +:Target: vcpu +:Parameters: none +:Returns: 0 on success; -1 on error This capability enables support for handling of channel I/O instructions. @@ -4694,11 +5255,12 @@ Note that even though this capability is enabled per-vcpu, the complete virtual machine is affected. 6.5 KVM_CAP_PPC_EPR +------------------- -Architectures: ppc -Target: vcpu -Parameters: args[0] defines whether the proxy facility is active -Returns: 0 on success; -1 on error +:Architectures: ppc +:Target: vcpu +:Parameters: args[0] defines whether the proxy facility is active +:Returns: 0 on success; -1 on error This capability enables or disables the delivery of interrupts through the external proxy facility. @@ -4712,62 +5274,70 @@ When disabled (args[0] == 0), behavior is as if this facility is unsupported. When this capability is enabled, KVM_EXIT_EPR can occur. 6.6 KVM_CAP_IRQ_MPIC +-------------------- -Architectures: ppc -Parameters: args[0] is the MPIC device fd - args[1] is the MPIC CPU number for this vcpu +:Architectures: ppc +:Parameters: args[0] is the MPIC device fd; + args[1] is the MPIC CPU number for this vcpu This capability connects the vcpu to an in-kernel MPIC device. 6.7 KVM_CAP_IRQ_XICS +-------------------- -Architectures: ppc -Target: vcpu -Parameters: args[0] is the XICS device fd - args[1] is the XICS CPU number (server ID) for this vcpu +:Architectures: ppc +:Target: vcpu +:Parameters: args[0] is the XICS device fd; + args[1] is the XICS CPU number (server ID) for this vcpu This capability connects the vcpu to an in-kernel XICS device. 6.8 KVM_CAP_S390_IRQCHIP +------------------------ -Architectures: s390 -Target: vm -Parameters: none +:Architectures: s390 +:Target: vm +:Parameters: none This capability enables the in-kernel irqchip for s390. Please refer to "4.24 KVM_CREATE_IRQCHIP" for details. 6.9 KVM_CAP_MIPS_FPU +-------------------- -Architectures: mips -Target: vcpu -Parameters: args[0] is reserved for future use (should be 0). +:Architectures: mips +:Target: vcpu +:Parameters: args[0] is reserved for future use (should be 0). This capability allows the use of the host Floating Point Unit by the guest. It allows the Config1.FP bit to be set to enable the FPU in the guest. Once this is -done the KVM_REG_MIPS_FPR_* and KVM_REG_MIPS_FCR_* registers can be accessed -(depending on the current guest FPU register mode), and the Status.FR, +done the ``KVM_REG_MIPS_FPR_*`` and ``KVM_REG_MIPS_FCR_*`` registers can be +accessed (depending on the current guest FPU register mode), and the Status.FR, Config5.FRE bits are accessible via the KVM API and also from the guest, depending on them being supported by the FPU. 6.10 KVM_CAP_MIPS_MSA +--------------------- -Architectures: mips -Target: vcpu -Parameters: args[0] is reserved for future use (should be 0). +:Architectures: mips +:Target: vcpu +:Parameters: args[0] is reserved for future use (should be 0). This capability allows the use of the MIPS SIMD Architecture (MSA) by the guest. It allows the Config3.MSAP bit to be set to enable the use of MSA by the guest. -Once this is done the KVM_REG_MIPS_VEC_* and KVM_REG_MIPS_MSA_* registers can be -accessed, and the Config5.MSAEn bit is accessible via the KVM API and also from -the guest. +Once this is done the ``KVM_REG_MIPS_VEC_*`` and ``KVM_REG_MIPS_MSA_*`` +registers can be accessed, and the Config5.MSAEn bit is accessible via the +KVM API and also from the guest. 6.74 KVM_CAP_SYNC_REGS -Architectures: s390, x86 -Target: s390: always enabled, x86: vcpu -Parameters: none -Returns: x86: KVM_CHECK_EXTENSION returns a bit-array indicating which register -sets are supported (bitfields defined in arch/x86/include/uapi/asm/kvm.h). +---------------------- + +:Architectures: s390, x86 +:Target: s390: always enabled, x86: vcpu +:Parameters: none +:Returns: x86: KVM_CHECK_EXTENSION returns a bit-array indicating which register + sets are supported + (bitfields defined in arch/x86/include/uapi/asm/kvm.h). As described above in the kvm_sync_regs struct info in section 5 (kvm_run): KVM_CAP_SYNC_REGS "allow[s] userspace to access certain guest registers @@ -4780,6 +5350,7 @@ userspace. For s390 specifics, please refer to the source code. For x86: + - the register sets to be copied out to kvm_run are selectable by userspace (rather that all sets being copied out for every exit). - vcpu_events are available in addition to regs and sregs. @@ -4796,23 +5367,26 @@ into the vCPU even if they've been modified. Unused bitfields in the bitarrays must be set to zero. -struct kvm_sync_regs { +:: + + struct kvm_sync_regs { struct kvm_regs regs; struct kvm_sregs sregs; struct kvm_vcpu_events events; -}; + }; 6.75 KVM_CAP_PPC_IRQ_XIVE +------------------------- -Architectures: ppc -Target: vcpu -Parameters: args[0] is the XIVE device fd - args[1] is the XIVE CPU number (server ID) for this vcpu +:Architectures: ppc +:Target: vcpu +:Parameters: args[0] is the XIVE device fd; + args[1] is the XIVE CPU number (server ID) for this vcpu This capability connects the vcpu to an in-kernel XIVE device. 7. Capabilities that can be enabled on VMs ------------------------------------------- +========================================== There are certain capabilities that change the behavior of the virtual machine when enabled. To enable them, please see section 4.37. Below @@ -4821,20 +5395,24 @@ is when enabling them. The following information is provided along with the description: - Architectures: which instruction set architectures provide this ioctl. + Architectures: + which instruction set architectures provide this ioctl. x86 includes both i386 and x86_64. - Parameters: what parameters are accepted by the capability. + Parameters: + what parameters are accepted by the capability. - Returns: the return value. General error numbers (EBADF, ENOMEM, EINVAL) + Returns: + the return value. General error numbers (EBADF, ENOMEM, EINVAL) are not detailed, but errors with specific meanings are. 7.1 KVM_CAP_PPC_ENABLE_HCALL +---------------------------- -Architectures: ppc -Parameters: args[0] is the sPAPR hcall number - args[1] is 0 to disable, 1 to enable in-kernel handling +:Architectures: ppc +:Parameters: args[0] is the sPAPR hcall number; + args[1] is 0 to disable, 1 to enable in-kernel handling This capability controls whether individual sPAPR hypercalls (hcalls) get handled by the kernel or not. Enabling or disabling in-kernel @@ -4852,13 +5430,15 @@ implementation, the KVM_ENABLE_CAP ioctl will fail with an EINVAL error. 7.2 KVM_CAP_S390_USER_SIGP +-------------------------- -Architectures: s390 -Parameters: none +:Architectures: s390 +:Parameters: none This capability controls which SIGP orders will be handled completely in user space. With this capability enabled, all fast orders will be handled completely in the kernel: + - SENSE - SENSE RUNNING - EXTERNAL CALL @@ -4872,48 +5452,52 @@ in the hardware prior to interception). If this capability is not enabled, the old way of handling SIGP orders is used (partially in kernel and user space). 7.3 KVM_CAP_S390_VECTOR_REGISTERS +--------------------------------- -Architectures: s390 -Parameters: none -Returns: 0 on success, negative value on error +:Architectures: s390 +:Parameters: none +:Returns: 0 on success, negative value on error Allows use of the vector registers introduced with z13 processor, and provides for the synchronization between host and user space. Will return -EINVAL if the machine does not support vectors. 7.4 KVM_CAP_S390_USER_STSI +-------------------------- -Architectures: s390 -Parameters: none +:Architectures: s390 +:Parameters: none This capability allows post-handlers for the STSI instruction. After initial handling in the kernel, KVM exits to user space with KVM_EXIT_S390_STSI to allow user space to insert further data. Before exiting to userspace, kvm handlers should fill in s390_stsi field of -vcpu->run: -struct { +vcpu->run:: + + struct { __u64 addr; __u8 ar; __u8 reserved; __u8 fc; __u8 sel1; __u16 sel2; -} s390_stsi; + } s390_stsi; -@addr - guest address of STSI SYSIB -@fc - function code -@sel1 - selector 1 -@sel2 - selector 2 -@ar - access register number + @addr - guest address of STSI SYSIB + @fc - function code + @sel1 - selector 1 + @sel2 - selector 2 + @ar - access register number KVM handlers should exit to userspace with rc = -EREMOTE. 7.5 KVM_CAP_SPLIT_IRQCHIP +------------------------- -Architectures: x86 -Parameters: args[0] - number of routes reserved for userspace IOAPICs -Returns: 0 on success, -1 on error +:Architectures: x86 +:Parameters: args[0] - number of routes reserved for userspace IOAPICs +:Returns: 0 on success, -1 on error Create a local apic for each processor in the kernel. This can be used instead of KVM_CREATE_IRQCHIP if the userspace VMM wishes to emulate the @@ -4930,24 +5514,26 @@ Fails if VCPU has already been created, or if the irqchip is already in the kernel (i.e. KVM_CREATE_IRQCHIP has already been called). 7.6 KVM_CAP_S390_RI +------------------- -Architectures: s390 -Parameters: none +:Architectures: s390 +:Parameters: none Allows use of runtime-instrumentation introduced with zEC12 processor. Will return -EINVAL if the machine does not support runtime-instrumentation. Will return -EBUSY if a VCPU has already been created. 7.7 KVM_CAP_X2APIC_API +---------------------- -Architectures: x86 -Parameters: args[0] - features that should be enabled -Returns: 0 on success, -EINVAL when args[0] contains invalid features +:Architectures: x86 +:Parameters: args[0] - features that should be enabled +:Returns: 0 on success, -EINVAL when args[0] contains invalid features -Valid feature flags in args[0] are +Valid feature flags in args[0] are:: -#define KVM_X2APIC_API_USE_32BIT_IDS (1ULL << 0) -#define KVM_X2APIC_API_DISABLE_BROADCAST_QUIRK (1ULL << 1) + #define KVM_X2APIC_API_USE_32BIT_IDS (1ULL << 0) + #define KVM_X2APIC_API_DISABLE_BROADCAST_QUIRK (1ULL << 1) Enabling KVM_X2APIC_API_USE_32BIT_IDS changes the behavior of KVM_SET_GSI_ROUTING, KVM_SIGNAL_MSI, KVM_SET_LAPIC, and KVM_GET_LAPIC, @@ -4961,9 +5547,10 @@ without interrupt remapping. This is undesirable in logical mode, where 0xff represents CPUs 0-7 in cluster 0. 7.8 KVM_CAP_S390_USER_INSTR0 +---------------------------- -Architectures: s390 -Parameters: none +:Architectures: s390 +:Parameters: none With this capability enabled, all illegal instructions 0x0000 (2 bytes) will be intercepted and forwarded to user space. User space can use this @@ -4975,26 +5562,29 @@ This capability can be enabled dynamically even if VCPUs were already created and are running. 7.9 KVM_CAP_S390_GS +------------------- -Architectures: s390 -Parameters: none -Returns: 0 on success; -EINVAL if the machine does not support - guarded storage; -EBUSY if a VCPU has already been created. +:Architectures: s390 +:Parameters: none +:Returns: 0 on success; -EINVAL if the machine does not support + guarded storage; -EBUSY if a VCPU has already been created. Allows use of guarded storage for the KVM guest. 7.10 KVM_CAP_S390_AIS +--------------------- -Architectures: s390 -Parameters: none +:Architectures: s390 +:Parameters: none Allow use of adapter-interruption suppression. -Returns: 0 on success; -EBUSY if a VCPU has already been created. +:Returns: 0 on success; -EBUSY if a VCPU has already been created. 7.11 KVM_CAP_PPC_SMT +-------------------- -Architectures: ppc -Parameters: vsmt_mode, flags +:Architectures: ppc +:Parameters: vsmt_mode, flags Enabling this capability on a VM provides userspace with a way to set the desired virtual SMT mode (i.e. the number of virtual CPUs per @@ -5009,9 +5599,10 @@ The KVM_CAP_PPC_SMT_POSSIBLE capability indicates which virtual SMT modes are available. 7.12 KVM_CAP_PPC_FWNMI +---------------------- -Architectures: ppc -Parameters: none +:Architectures: ppc +:Parameters: none With this capability a machine check exception in the guest address space will cause KVM to exit the guest with NMI exit reason. This @@ -5020,17 +5611,18 @@ machine check handling routine. Without this capability KVM will branch to guests' 0x200 interrupt vector. 7.13 KVM_CAP_X86_DISABLE_EXITS +------------------------------ -Architectures: x86 -Parameters: args[0] defines which exits are disabled -Returns: 0 on success, -EINVAL when args[0] contains invalid exits +:Architectures: x86 +:Parameters: args[0] defines which exits are disabled +:Returns: 0 on success, -EINVAL when args[0] contains invalid exits -Valid bits in args[0] are +Valid bits in args[0] are:: -#define KVM_X86_DISABLE_EXITS_MWAIT (1 << 0) -#define KVM_X86_DISABLE_EXITS_HLT (1 << 1) -#define KVM_X86_DISABLE_EXITS_PAUSE (1 << 2) -#define KVM_X86_DISABLE_EXITS_CSTATE (1 << 3) + #define KVM_X86_DISABLE_EXITS_MWAIT (1 << 0) + #define KVM_X86_DISABLE_EXITS_HLT (1 << 1) + #define KVM_X86_DISABLE_EXITS_PAUSE (1 << 2) + #define KVM_X86_DISABLE_EXITS_CSTATE (1 << 3) Enabling this capability on a VM provides userspace with a way to no longer intercept some instructions for improved latency in some @@ -5042,12 +5634,13 @@ all such vmexits. Do not enable KVM_FEATURE_PV_UNHALT if you disable HLT exits. 7.14 KVM_CAP_S390_HPAGE_1M +-------------------------- -Architectures: s390 -Parameters: none -Returns: 0 on success, -EINVAL if hpage module parameter was not set - or cmma is enabled, or the VM has the KVM_VM_S390_UCONTROL - flag set +:Architectures: s390 +:Parameters: none +:Returns: 0 on success, -EINVAL if hpage module parameter was not set + or cmma is enabled, or the VM has the KVM_VM_S390_UCONTROL + flag set With this capability the KVM support for memory backing with 1m pages through hugetlbfs can be enabled for a VM. After the capability is @@ -5059,20 +5652,22 @@ While it is generally possible to create a huge page backed VM without this capability, the VM will not be able to run. 7.15 KVM_CAP_MSR_PLATFORM_INFO +------------------------------ -Architectures: x86 -Parameters: args[0] whether feature should be enabled or not +:Architectures: x86 +:Parameters: args[0] whether feature should be enabled or not With this capability, a guest may read the MSR_PLATFORM_INFO MSR. Otherwise, a #GP would be raised when the guest tries to access. Currently, this capability does not enable write permissions of this MSR for the guest. 7.16 KVM_CAP_PPC_NESTED_HV +-------------------------- -Architectures: ppc -Parameters: none -Returns: 0 on success, -EINVAL when the implementation doesn't support - nested-HV virtualization. +:Architectures: ppc +:Parameters: none +:Returns: 0 on success, -EINVAL when the implementation doesn't support + nested-HV virtualization. HV-KVM on POWER9 and later systems allows for "nested-HV" virtualization, which provides a way for a guest VM to run guests that @@ -5082,9 +5677,10 @@ the necessary functionality and on the facility being enabled with a kvm-hv module parameter. 7.17 KVM_CAP_EXCEPTION_PAYLOAD +------------------------------ -Architectures: x86 -Parameters: args[0] whether feature should be enabled or not +:Architectures: x86 +:Parameters: args[0] whether feature should be enabled or not With this capability enabled, CR2 will not be modified prior to the emulated VM-exit when L1 intercepts a #PF exception that occurs in @@ -5095,21 +5691,21 @@ L2. As a result, when KVM_GET_VCPU_EVENTS reports a pending #PF (or faulting address (or the new DR6 bits*) will be reported in the exception_payload field. Similarly, when userspace injects a #PF (or #DB) into L2 using KVM_SET_VCPU_EVENTS, it is expected to set -exception.has_payload and to put the faulting address (or the new DR6 -bits*) in the exception_payload field. +exception.has_payload and to put the faulting address - or the new DR6 +bits\ [#]_ - in the exception_payload field. This capability also enables exception.pending in struct kvm_vcpu_events, which allows userspace to distinguish between pending and injected exceptions. -* For the new DR6 bits, note that bit 16 is set iff the #DB exception - will clear DR6.RTM. +.. [#] For the new DR6 bits, note that bit 16 is set iff the #DB exception + will clear DR6.RTM. 7.18 KVM_CAP_MANUAL_DIRTY_LOG_PROTECT2 -Architectures: x86, arm, arm64, mips -Parameters: args[0] whether feature should be enabled or not +:Architectures: x86, arm, arm64, mips +:Parameters: args[0] whether feature should be enabled or not With this capability enabled, KVM_GET_DIRTY_LOG will not automatically clear and write-protect all pages that are returned as dirty. @@ -5136,14 +5732,15 @@ KVM_CAP_MANUAL_DIRTY_LOG_PROTECT2 signals that those bugs are fixed. Userspace should not try to use KVM_CAP_MANUAL_DIRTY_LOG_PROTECT. 8. Other capabilities. ----------------------- +====================== This section lists capabilities that give information about other features of the KVM implementation. 8.1 KVM_CAP_PPC_HWRNG +--------------------- -Architectures: ppc +:Architectures: ppc This capability, if KVM_CHECK_EXTENSION indicates that it is available, means that that the kernel has an implementation of the @@ -5152,8 +5749,10 @@ If present, the kernel H_RANDOM handler can be enabled for guest use with the KVM_CAP_PPC_ENABLE_HCALL capability. 8.2 KVM_CAP_HYPERV_SYNIC +------------------------ + +:Architectures: x86 -Architectures: x86 This capability, if KVM_CHECK_EXTENSION indicates that it is available, means that that the kernel has an implementation of the Hyper-V Synthetic interrupt controller(SynIC). Hyper-V SynIC is @@ -5165,8 +5764,9 @@ will disable the use of APIC hardware virtualization even if supported by the CPU, as it's incompatible with SynIC auto-EOI behavior. 8.3 KVM_CAP_PPC_RADIX_MMU +------------------------- -Architectures: ppc +:Architectures: ppc This capability, if KVM_CHECK_EXTENSION indicates that it is available, means that that the kernel can support guests using the @@ -5174,8 +5774,9 @@ radix MMU defined in Power ISA V3.00 (as implemented in the POWER9 processor). 8.4 KVM_CAP_PPC_HASH_MMU_V3 +--------------------------- -Architectures: ppc +:Architectures: ppc This capability, if KVM_CHECK_EXTENSION indicates that it is available, means that that the kernel can support guests using the @@ -5183,8 +5784,9 @@ hashed page table MMU defined in Power ISA V3.00 (as implemented in the POWER9 processor), including in-memory segment tables. 8.5 KVM_CAP_MIPS_VZ +------------------- -Architectures: mips +:Architectures: mips This capability, if KVM_CHECK_EXTENSION on the main kvm handle indicates that it is available, means that full hardware assisted virtualization capabilities @@ -5202,16 +5804,19 @@ values (see below). All other values are reserved. This is to allow for the possibility of other hardware assisted virtualization implementations which may be incompatible with the MIPS VZ ASE. - 0: The trap & emulate implementation is in use to run guest code in user +== ========================================================================== + 0 The trap & emulate implementation is in use to run guest code in user mode. Guest virtual memory segments are rearranged to fit the guest in the user mode address space. - 1: The MIPS VZ ASE is in use, providing full hardware assisted + 1 The MIPS VZ ASE is in use, providing full hardware assisted virtualization, including standard guest virtual memory segments. +== ========================================================================== 8.6 KVM_CAP_MIPS_TE +------------------- -Architectures: mips +:Architectures: mips This capability, if KVM_CHECK_EXTENSION on the main kvm handle indicates that it is available, means that the trap & emulate implementation is available to @@ -5223,8 +5828,9 @@ If KVM_CHECK_EXTENSION on a kvm VM handle indicates that this capability is available, it means that the VM is using trap & emulate. 8.7 KVM_CAP_MIPS_64BIT +---------------------- -Architectures: mips +:Architectures: mips This capability indicates the supported architecture type of the guest, i.e. the supported register and address width. @@ -5234,22 +5840,26 @@ kvm VM handle correspond roughly to the CP0_Config.AT register field, and should be checked specifically against known values (see below). All other values are reserved. - 0: MIPS32 or microMIPS32. +== ======================================================================== + 0 MIPS32 or microMIPS32. Both registers and addresses are 32-bits wide. It will only be possible to run 32-bit guest code. - 1: MIPS64 or microMIPS64 with access only to 32-bit compatibility segments. + 1 MIPS64 or microMIPS64 with access only to 32-bit compatibility segments. Registers are 64-bits wide, but addresses are 32-bits wide. 64-bit guest code may run but cannot access MIPS64 memory segments. It will also be possible to run 32-bit guest code. - 2: MIPS64 or microMIPS64 with access to all address segments. + 2 MIPS64 or microMIPS64 with access to all address segments. Both registers and addresses are 64-bits wide. It will be possible to run 64-bit or 32-bit guest code. +== ======================================================================== 8.9 KVM_CAP_ARM_USER_IRQ +------------------------ + +:Architectures: arm, arm64 -Architectures: arm, arm64 This capability, if KVM_CHECK_EXTENSION indicates that it is available, means that if userspace creates a VM without an in-kernel interrupt controller, it will be notified of changes to the output level of in-kernel emulated devices, @@ -5276,7 +5886,7 @@ If KVM_CAP_ARM_USER_IRQ is supported, the KVM_CHECK_EXTENSION ioctl returns a number larger than 0 indicating the version of this capability is implemented and thereby which bits in in run->s.regs.device_irq_level can signal values. -Currently the following bits are defined for the device_irq_level bitmap: +Currently the following bits are defined for the device_irq_level bitmap:: KVM_CAP_ARM_USER_IRQ >= 1: @@ -5289,8 +5899,9 @@ indicated by returning a higher number from KVM_CHECK_EXTENSION and will be listed above. 8.10 KVM_CAP_PPC_SMT_POSSIBLE +----------------------------- -Architectures: ppc +:Architectures: ppc Querying this capability returns a bitmap indicating the possible virtual SMT modes that can be set using KVM_CAP_PPC_SMT. If bit N @@ -5298,8 +5909,9 @@ virtual SMT modes that can be set using KVM_CAP_PPC_SMT. If bit N available. 8.11 KVM_CAP_HYPERV_SYNIC2 +-------------------------- -Architectures: x86 +:Architectures: x86 This capability enables a newer version of Hyper-V Synthetic interrupt controller (SynIC). The only difference with KVM_CAP_HYPERV_SYNIC is that KVM @@ -5307,8 +5919,9 @@ doesn't clear SynIC message and event flags pages when they are enabled by writing to the respective MSRs. 8.12 KVM_CAP_HYPERV_VP_INDEX +---------------------------- -Architectures: x86 +:Architectures: x86 This capability indicates that userspace can load HV_X64_MSR_VP_INDEX msr. Its value is used to denote the target vcpu for a SynIC interrupt. For @@ -5316,47 +5929,53 @@ compatibilty, KVM initializes this msr to KVM's internal vcpu index. When this capability is absent, userspace can still query this msr's value. 8.13 KVM_CAP_S390_AIS_MIGRATION +------------------------------- -Architectures: s390 -Parameters: none +:Architectures: s390 +:Parameters: none This capability indicates if the flic device will be able to get/set the AIS states for migration via the KVM_DEV_FLIC_AISM_ALL attribute and allows to discover this without having to create a flic device. 8.14 KVM_CAP_S390_PSW +--------------------- -Architectures: s390 +:Architectures: s390 This capability indicates that the PSW is exposed via the kvm_run structure. 8.15 KVM_CAP_S390_GMAP +---------------------- -Architectures: s390 +:Architectures: s390 This capability indicates that the user space memory used as guest mapping can be anywhere in the user memory address space, as long as the memory slots are aligned and sized to a segment (1MB) boundary. 8.16 KVM_CAP_S390_COW +--------------------- -Architectures: s390 +:Architectures: s390 This capability indicates that the user space memory used as guest mapping can use copy-on-write semantics as well as dirty pages tracking via read-only page tables. 8.17 KVM_CAP_S390_BPB +--------------------- -Architectures: s390 +:Architectures: s390 This capability indicates that kvm will implement the interfaces to handle reset, migration and nested KVM for branch prediction blocking. The stfle facility 82 should not be provided to the guest without this capability. 8.18 KVM_CAP_HYPERV_TLBFLUSH +---------------------------- -Architectures: x86 +:Architectures: x86 This capability indicates that KVM supports paravirtualized Hyper-V TLB Flush hypercalls: @@ -5364,8 +5983,9 @@ HvFlushVirtualAddressSpace, HvFlushVirtualAddressSpaceEx, HvFlushVirtualAddressList, HvFlushVirtualAddressListEx. 8.19 KVM_CAP_ARM_INJECT_SERROR_ESR +---------------------------------- -Architectures: arm, arm64 +:Architectures: arm, arm64 This capability indicates that userspace can specify (via the KVM_SET_VCPU_EVENTS ioctl) the syndrome value reported to the guest when it @@ -5376,16 +5996,20 @@ CPU when the exception is taken. If this virtual SError is taken to EL1 using AArch64, this value will be reported in the ISS field of ESR_ELx. See KVM_CAP_VCPU_EVENTS for more details. + 8.20 KVM_CAP_HYPERV_SEND_IPI +---------------------------- -Architectures: x86 +:Architectures: x86 This capability indicates that KVM supports paravirtualized Hyper-V IPI send hypercalls: HvCallSendSyntheticClusterIpi, HvCallSendSyntheticClusterIpiEx. + 8.21 KVM_CAP_HYPERV_DIRECT_TLBFLUSH +----------------------------------- -Architecture: x86 +:Architecture: x86 This capability indicates that KVM running on top of Hyper-V hypervisor enables Direct TLB flush for its guests meaning that TLB flush @@ -5396,3 +6020,10 @@ handling by KVM (as some KVM hypercall may be mistakenly treated as TLB flush hypercalls by Hyper-V) so userspace should disable KVM identification in CPUID and only exposes Hyper-V identification. In this case, guest thinks it's running on Hyper-V and only use Hyper-V hypercalls. + +8.22 KVM_CAP_S390_VCPU_RESETS + +Architectures: s390 + +This capability indicates that the KVM_S390_NORMAL_RESET and +KVM_S390_CLEAR_RESET ioctls are available. diff --git a/Documentation/virt/kvm/arm/hyp-abi.txt b/Documentation/virt/kvm/arm/hyp-abi.rst index a20a0bee268d..d1fc27d848e9 100644 --- a/Documentation/virt/kvm/arm/hyp-abi.txt +++ b/Documentation/virt/kvm/arm/hyp-abi.rst @@ -1,4 +1,8 @@ -* Internal ABI between the kernel and HYP +.. SPDX-License-Identifier: GPL-2.0 + +======================================= +Internal ABI between the kernel and HYP +======================================= This file documents the interaction between the Linux kernel and the hypervisor layer when running Linux as a hypervisor (for example @@ -19,25 +23,31 @@ and only act on individual CPUs. Unless specified otherwise, any built-in hypervisor must implement these functions (see arch/arm{,64}/include/asm/virt.h): -* r0/x0 = HVC_SET_VECTORS - r1/x1 = vectors +* :: + + r0/x0 = HVC_SET_VECTORS + r1/x1 = vectors Set HVBAR/VBAR_EL2 to 'vectors' to enable a hypervisor. 'vectors' must be a physical address, and respect the alignment requirements of the architecture. Only implemented by the initial stubs, not by Linux hypervisors. -* r0/x0 = HVC_RESET_VECTORS +* :: + + r0/x0 = HVC_RESET_VECTORS Turn HYP/EL2 MMU off, and reset HVBAR/VBAR_EL2 to the initials stubs' exception vector value. This effectively disables an existing hypervisor. -* r0/x0 = HVC_SOFT_RESTART - r1/x1 = restart address - x2 = x0's value when entering the next payload (arm64) - x3 = x1's value when entering the next payload (arm64) - x4 = x2's value when entering the next payload (arm64) +* :: + + r0/x0 = HVC_SOFT_RESTART + r1/x1 = restart address + x2 = x0's value when entering the next payload (arm64) + x3 = x1's value when entering the next payload (arm64) + x4 = x2's value when entering the next payload (arm64) Mask all exceptions, disable the MMU, move the arguments into place (arm64 only), and jump to the restart address while at HYP/EL2. This diff --git a/Documentation/virt/kvm/arm/index.rst b/Documentation/virt/kvm/arm/index.rst new file mode 100644 index 000000000000..3e2b2aba90fc --- /dev/null +++ b/Documentation/virt/kvm/arm/index.rst @@ -0,0 +1,12 @@ +.. SPDX-License-Identifier: GPL-2.0 + +=== +ARM +=== + +.. toctree:: + :maxdepth: 2 + + hyp-abi + psci + pvtime diff --git a/Documentation/virt/kvm/arm/psci.txt b/Documentation/virt/kvm/arm/psci.rst index 559586fc9d37..d52c2e83b5b8 100644 --- a/Documentation/virt/kvm/arm/psci.txt +++ b/Documentation/virt/kvm/arm/psci.rst @@ -1,3 +1,9 @@ +.. SPDX-License-Identifier: GPL-2.0 + +========================================= +Power State Coordination Interface (PSCI) +========================================= + KVM implements the PSCI (Power State Coordination Interface) specification in order to provide services such as CPU on/off, reset and power-off to the guest. @@ -30,32 +36,42 @@ The following register is defined: - Affects the whole VM (even if the register view is per-vcpu) * KVM_REG_ARM_SMCCC_ARCH_WORKAROUND_1: - Holds the state of the firmware support to mitigate CVE-2017-5715, as - offered by KVM to the guest via a HVC call. The workaround is described - under SMCCC_ARCH_WORKAROUND_1 in [1]. + Holds the state of the firmware support to mitigate CVE-2017-5715, as + offered by KVM to the guest via a HVC call. The workaround is described + under SMCCC_ARCH_WORKAROUND_1 in [1]. + Accepted values are: - KVM_REG_ARM_SMCCC_ARCH_WORKAROUND_1_NOT_AVAIL: KVM does not offer + + KVM_REG_ARM_SMCCC_ARCH_WORKAROUND_1_NOT_AVAIL: + KVM does not offer firmware support for the workaround. The mitigation status for the guest is unknown. - KVM_REG_ARM_SMCCC_ARCH_WORKAROUND_1_AVAIL: The workaround HVC call is + KVM_REG_ARM_SMCCC_ARCH_WORKAROUND_1_AVAIL: + The workaround HVC call is available to the guest and required for the mitigation. - KVM_REG_ARM_SMCCC_ARCH_WORKAROUND_1_NOT_REQUIRED: The workaround HVC call + KVM_REG_ARM_SMCCC_ARCH_WORKAROUND_1_NOT_REQUIRED: + The workaround HVC call is available to the guest, but it is not needed on this VCPU. * KVM_REG_ARM_SMCCC_ARCH_WORKAROUND_2: - Holds the state of the firmware support to mitigate CVE-2018-3639, as - offered by KVM to the guest via a HVC call. The workaround is described - under SMCCC_ARCH_WORKAROUND_2 in [1]. + Holds the state of the firmware support to mitigate CVE-2018-3639, as + offered by KVM to the guest via a HVC call. The workaround is described + under SMCCC_ARCH_WORKAROUND_2 in [1]_. + Accepted values are: - KVM_REG_ARM_SMCCC_ARCH_WORKAROUND_2_NOT_AVAIL: A workaround is not + + KVM_REG_ARM_SMCCC_ARCH_WORKAROUND_2_NOT_AVAIL: + A workaround is not available. KVM does not offer firmware support for the workaround. - KVM_REG_ARM_SMCCC_ARCH_WORKAROUND_2_UNKNOWN: The workaround state is + KVM_REG_ARM_SMCCC_ARCH_WORKAROUND_2_UNKNOWN: + The workaround state is unknown. KVM does not offer firmware support for the workaround. - KVM_REG_ARM_SMCCC_ARCH_WORKAROUND_2_AVAIL: The workaround is available, + KVM_REG_ARM_SMCCC_ARCH_WORKAROUND_2_AVAIL: + The workaround is available, and can be disabled by a vCPU. If KVM_REG_ARM_SMCCC_ARCH_WORKAROUND_2_ENABLED is set, it is active for this vCPU. - KVM_REG_ARM_SMCCC_ARCH_WORKAROUND_2_NOT_REQUIRED: The workaround is - always active on this vCPU or it is not needed. + KVM_REG_ARM_SMCCC_ARCH_WORKAROUND_2_NOT_REQUIRED: + The workaround is always active on this vCPU or it is not needed. -[1] https://developer.arm.com/-/media/developer/pdf/ARM_DEN_0070A_Firmware_interfaces_for_mitigating_CVE-2017-5715.pdf +.. [1] https://developer.arm.com/-/media/developer/pdf/ARM_DEN_0070A_Firmware_interfaces_for_mitigating_CVE-2017-5715.pdf diff --git a/Documentation/virt/kvm/devices/arm-vgic-its.txt b/Documentation/virt/kvm/devices/arm-vgic-its.rst index eeaa95b893a8..6c304fd2b1b4 100644 --- a/Documentation/virt/kvm/devices/arm-vgic-its.txt +++ b/Documentation/virt/kvm/devices/arm-vgic-its.rst @@ -1,3 +1,6 @@ +.. SPDX-License-Identifier: GPL-2.0 + +=============================================== ARM Virtual Interrupt Translation Service (ITS) =============================================== @@ -12,22 +15,32 @@ There can be multiple ITS controllers per guest, each of them has to have a separate, non-overlapping MMIO region. -Groups: - KVM_DEV_ARM_VGIC_GRP_ADDR +Groups +====== + +KVM_DEV_ARM_VGIC_GRP_ADDR +------------------------- + Attributes: KVM_VGIC_ITS_ADDR_TYPE (rw, 64-bit) Base address in the guest physical address space of the GICv3 ITS control register frame. This address needs to be 64K aligned and the region covers 128K. + Errors: - -E2BIG: Address outside of addressable IPA range - -EINVAL: Incorrectly aligned address - -EEXIST: Address already configured - -EFAULT: Invalid user pointer for attr->addr. - -ENODEV: Incorrect attribute or the ITS is not supported. + ======= ================================================= + -E2BIG Address outside of addressable IPA range + -EINVAL Incorrectly aligned address + -EEXIST Address already configured + -EFAULT Invalid user pointer for attr->addr. + -ENODEV Incorrect attribute or the ITS is not supported. + ======= ================================================= + + +KVM_DEV_ARM_VGIC_GRP_CTRL +------------------------- - KVM_DEV_ARM_VGIC_GRP_CTRL Attributes: KVM_DEV_ARM_VGIC_CTRL_INIT request the initialization of the ITS, no additional parameter in @@ -58,16 +71,21 @@ Groups: "ITS Restore Sequence". Errors: - -ENXIO: ITS not properly configured as required prior to setting + + ======= ========================================================== + -ENXIO ITS not properly configured as required prior to setting this attribute - -ENOMEM: Memory shortage when allocating ITS internal data - -EINVAL: Inconsistent restored data - -EFAULT: Invalid guest ram access - -EBUSY: One or more VCPUS are running - -EACCES: The virtual ITS is backed by a physical GICv4 ITS, and the + -ENOMEM Memory shortage when allocating ITS internal data + -EINVAL Inconsistent restored data + -EFAULT Invalid guest ram access + -EBUSY One or more VCPUS are running + -EACCES The virtual ITS is backed by a physical GICv4 ITS, and the state is not available + ======= ========================================================== + +KVM_DEV_ARM_VGIC_GRP_ITS_REGS +----------------------------- - KVM_DEV_ARM_VGIC_GRP_ITS_REGS Attributes: The attr field of kvm_device_attr encodes the offset of the ITS register, relative to the ITS control frame base address @@ -78,6 +96,7 @@ Groups: be accessed with full length. Writes to read-only registers are ignored by the kernel except for: + - GITS_CREADR. It must be restored otherwise commands in the queue will be re-executed after restoring CWRITER. GITS_CREADR must be restored before restoring the GITS_CTLR which is likely to enable the @@ -91,30 +110,36 @@ Groups: For other registers, getting or setting a register has the same effect as reading/writing the register on real hardware. + Errors: - -ENXIO: Offset does not correspond to any supported register - -EFAULT: Invalid user pointer for attr->addr - -EINVAL: Offset is not 64-bit aligned - -EBUSY: one or more VCPUS are running - ITS Restore Sequence: - ------------------------- + ======= ==================================================== + -ENXIO Offset does not correspond to any supported register + -EFAULT Invalid user pointer for attr->addr + -EINVAL Offset is not 64-bit aligned + -EBUSY one or more VCPUS are running + ======= ==================================================== + +ITS Restore Sequence: +--------------------- The following ordering must be followed when restoring the GIC and the ITS: + a) restore all guest memory and create vcpus b) restore all redistributors c) provide the ITS base address (KVM_DEV_ARM_VGIC_GRP_ADDR) d) restore the ITS in the following order: - 1. Restore GITS_CBASER - 2. Restore all other GITS_ registers, except GITS_CTLR! - 3. Load the ITS table data (KVM_DEV_ARM_ITS_RESTORE_TABLES) - 4. Restore GITS_CTLR + + 1. Restore GITS_CBASER + 2. Restore all other ``GITS_`` registers, except GITS_CTLR! + 3. Load the ITS table data (KVM_DEV_ARM_ITS_RESTORE_TABLES) + 4. Restore GITS_CTLR Then vcpus can be started. - ITS Table ABI REV0: - ------------------- +ITS Table ABI REV0: +------------------- Revision 0 of the ABI only supports the features of a virtual GICv3, and does not support a virtual GICv4 with support for direct injection of virtual @@ -125,12 +150,13 @@ Then vcpus can be started. entries in the collection are listed in no particular order. All entries are 8 bytes. - Device Table Entry (DTE): + Device Table Entry (DTE):: - bits: | 63| 62 ... 49 | 48 ... 5 | 4 ... 0 | - values: | V | next | ITT_addr | Size | + bits: | 63| 62 ... 49 | 48 ... 5 | 4 ... 0 | + values: | V | next | ITT_addr | Size | + + where: - where; - V indicates whether the entry is valid. If not, other fields are not meaningful. - next: equals to 0 if this entry is the last one; otherwise it @@ -140,32 +166,34 @@ Then vcpus can be started. - Size specifies the supported number of bits for the EventID, minus one - Collection Table Entry (CTE): + Collection Table Entry (CTE):: - bits: | 63| 62 .. 52 | 51 ... 16 | 15 ... 0 | - values: | V | RES0 | RDBase | ICID | + bits: | 63| 62 .. 52 | 51 ... 16 | 15 ... 0 | + values: | V | RES0 | RDBase | ICID | where: + - V indicates whether the entry is valid. If not, other fields are not meaningful. - RES0: reserved field with Should-Be-Zero-or-Preserved behavior. - RDBase is the PE number (GICR_TYPER.Processor_Number semantic), - ICID is the collection ID - Interrupt Translation Entry (ITE): + Interrupt Translation Entry (ITE):: - bits: | 63 ... 48 | 47 ... 16 | 15 ... 0 | - values: | next | pINTID | ICID | + bits: | 63 ... 48 | 47 ... 16 | 15 ... 0 | + values: | next | pINTID | ICID | where: + - next: equals to 0 if this entry is the last one; otherwise it corresponds to the EventID offset to the next ITE capped by 2^16 -1. - pINTID is the physical LPI ID; if zero, it means the entry is not valid and other fields are not meaningful. - ICID is the collection ID - ITS Reset State: - ---------------- +ITS Reset State: +---------------- RESET returns the ITS to the same state that it was when first created and initialized. When the RESET command returns, the following things are diff --git a/Documentation/virt/kvm/devices/arm-vgic-v3.txt b/Documentation/virt/kvm/devices/arm-vgic-v3.rst index ff290b43c8e5..5dd3bff51978 100644 --- a/Documentation/virt/kvm/devices/arm-vgic-v3.txt +++ b/Documentation/virt/kvm/devices/arm-vgic-v3.rst @@ -1,9 +1,12 @@ +.. SPDX-License-Identifier: GPL-2.0 + +============================================================== ARM Virtual Generic Interrupt Controller v3 and later (VGICv3) ============================================================== Device types supported: - KVM_DEV_TYPE_ARM_VGIC_V3 ARM Generic Interrupt Controller v3.0 + - KVM_DEV_TYPE_ARM_VGIC_V3 ARM Generic Interrupt Controller v3.0 Only one VGIC instance may be instantiated through this API. The created VGIC will act as the VM interrupt controller, requiring emulated user-space devices @@ -15,7 +18,8 @@ Creating a guest GICv3 device requires a host GICv3 as well. Groups: KVM_DEV_ARM_VGIC_GRP_ADDR - Attributes: + Attributes: + KVM_VGIC_V3_ADDR_TYPE_DIST (rw, 64-bit) Base address in the guest physical address space of the GICv3 distributor register mappings. Only valid for KVM_DEV_TYPE_ARM_VGIC_V3. @@ -29,21 +33,25 @@ Groups: This address needs to be 64K aligned. KVM_VGIC_V3_ADDR_TYPE_REDIST_REGION (rw, 64-bit) - The attribute data pointed to by kvm_device_attr.addr is a __u64 value: - bits: | 63 .... 52 | 51 .... 16 | 15 - 12 |11 - 0 - values: | count | base | flags | index + The attribute data pointed to by kvm_device_attr.addr is a __u64 value:: + + bits: | 63 .... 52 | 51 .... 16 | 15 - 12 |11 - 0 + values: | count | base | flags | index + - index encodes the unique redistributor region index - flags: reserved for future use, currently 0 - base field encodes bits [51:16] of the guest physical base address of the first redistributor in the region. - count encodes the number of redistributors in the region. Must be greater than 0. + There are two 64K pages for each redistributor in the region and redistributors are laid out contiguously within the region. Regions are filled with redistributors in the index order. The sum of all region count fields must be greater than or equal to the number of VCPUs. Redistributor regions must be registered in the incremental index order, starting from index 0. + The characteristics of a specific redistributor region can be read by presetting the index field in the attr data. Only valid for KVM_DEV_TYPE_ARM_VGIC_V3. @@ -52,23 +60,27 @@ Groups: KVM_VGIC_V3_ADDR_TYPE_REDIST_REGION attributes. Errors: - -E2BIG: Address outside of addressable IPA range - -EINVAL: Incorrectly aligned address, bad redistributor region + + ======= ============================================================= + -E2BIG Address outside of addressable IPA range + -EINVAL Incorrectly aligned address, bad redistributor region count/index, mixed redistributor region attribute usage - -EEXIST: Address already configured - -ENOENT: Attempt to read the characteristics of a non existing + -EEXIST Address already configured + -ENOENT Attempt to read the characteristics of a non existing redistributor region - -ENXIO: The group or attribute is unknown/unsupported for this device + -ENXIO The group or attribute is unknown/unsupported for this device or hardware support is missing. - -EFAULT: Invalid user pointer for attr->addr. + -EFAULT Invalid user pointer for attr->addr. + ======= ============================================================= + + KVM_DEV_ARM_VGIC_GRP_DIST_REGS, KVM_DEV_ARM_VGIC_GRP_REDIST_REGS + Attributes: - KVM_DEV_ARM_VGIC_GRP_DIST_REGS - KVM_DEV_ARM_VGIC_GRP_REDIST_REGS - Attributes: - The attr field of kvm_device_attr encodes two values: - bits: | 63 .... 32 | 31 .... 0 | - values: | mpidr | offset | + The attr field of kvm_device_attr encodes two values:: + + bits: | 63 .... 32 | 31 .... 0 | + values: | mpidr | offset | All distributor regs are (rw, 32-bit) and kvm_device_attr.addr points to a __u32 value. 64-bit registers must be accessed by separately accessing the @@ -93,7 +105,8 @@ Groups: redistributor is accessed. The mpidr is ignored for the distributor. The mpidr encoding is based on the affinity information in the - architecture defined MPIDR, and the field is encoded as follows: + architecture defined MPIDR, and the field is encoded as follows:: + | 63 .... 56 | 55 .... 48 | 47 .... 40 | 39 .... 32 | | Aff3 | Aff2 | Aff1 | Aff0 | @@ -148,24 +161,30 @@ Groups: ignored. Errors: - -ENXIO: Getting or setting this register is not yet supported - -EBUSY: One or more VCPUs are running + + ====== ===================================================== + -ENXIO Getting or setting this register is not yet supported + -EBUSY One or more VCPUs are running + ====== ===================================================== KVM_DEV_ARM_VGIC_GRP_CPU_SYSREGS - Attributes: - The attr field of kvm_device_attr encodes two values: - bits: | 63 .... 32 | 31 .... 16 | 15 .... 0 | - values: | mpidr | RES | instr | + Attributes: + + The attr field of kvm_device_attr encodes two values:: + + bits: | 63 .... 32 | 31 .... 16 | 15 .... 0 | + values: | mpidr | RES | instr | The mpidr field encodes the CPU ID based on the affinity information in the - architecture defined MPIDR, and the field is encoded as follows: + architecture defined MPIDR, and the field is encoded as follows:: + | 63 .... 56 | 55 .... 48 | 47 .... 40 | 39 .... 32 | | Aff3 | Aff2 | Aff1 | Aff0 | The instr field encodes the system register to access based on the fields defined in the A64 instruction set encoding for system register access - (RES means the bits are reserved for future use and should be zero): + (RES means the bits are reserved for future use and should be zero):: | 15 ... 14 | 13 ... 11 | 10 ... 7 | 6 ... 3 | 2 ... 0 | | Op 0 | Op1 | CRn | CRm | Op2 | @@ -178,26 +197,35 @@ Groups: CPU interface registers access is not implemented for AArch32 mode. Error -ENXIO is returned when accessed in AArch32 mode. + Errors: - -ENXIO: Getting or setting this register is not yet supported - -EBUSY: VCPU is running - -EINVAL: Invalid mpidr or register value supplied + + ======= ===================================================== + -ENXIO Getting or setting this register is not yet supported + -EBUSY VCPU is running + -EINVAL Invalid mpidr or register value supplied + ======= ===================================================== KVM_DEV_ARM_VGIC_GRP_NR_IRQS - Attributes: + Attributes: + A value describing the number of interrupts (SGI, PPI and SPI) for this GIC instance, ranging from 64 to 1024, in increments of 32. kvm_device_attr.addr points to a __u32 value. Errors: - -EINVAL: Value set is out of the expected range - -EBUSY: Value has already be set. + + ======= ====================================== + -EINVAL Value set is out of the expected range + -EBUSY Value has already be set. + ======= ====================================== KVM_DEV_ARM_VGIC_GRP_CTRL - Attributes: + Attributes: + KVM_DEV_ARM_VGIC_CTRL_INIT request the initialization of the VGIC, no additional parameter in kvm_device_attr.addr. @@ -205,20 +233,26 @@ Groups: save all LPI pending bits into guest RAM pending tables. The first kB of the pending table is not altered by this operation. + Errors: - -ENXIO: VGIC not properly configured as required prior to calling - this attribute - -ENODEV: no online VCPU - -ENOMEM: memory shortage when allocating vgic internal data - -EFAULT: Invalid guest ram access - -EBUSY: One or more VCPUS are running + + ======= ======================================================== + -ENXIO VGIC not properly configured as required prior to calling + this attribute + -ENODEV no online VCPU + -ENOMEM memory shortage when allocating vgic internal data + -EFAULT Invalid guest ram access + -EBUSY One or more VCPUS are running + ======= ======================================================== KVM_DEV_ARM_VGIC_GRP_LEVEL_INFO - Attributes: - The attr field of kvm_device_attr encodes the following values: - bits: | 63 .... 32 | 31 .... 10 | 9 .... 0 | - values: | mpidr | info | vINTID | + Attributes: + + The attr field of kvm_device_attr encodes the following values:: + + bits: | 63 .... 32 | 31 .... 10 | 9 .... 0 | + values: | mpidr | info | vINTID | The vINTID specifies which set of IRQs is reported on. @@ -228,6 +262,7 @@ Groups: VGIC_LEVEL_INFO_LINE_LEVEL: Get/Set the input level of the IRQ line for a set of 32 contiguously numbered interrupts. + vINTID must be a multiple of 32. kvm_device_attr.addr points to a __u32 value which will contain a @@ -243,9 +278,14 @@ Groups: reported with the same value regardless of the mpidr specified. The mpidr field encodes the CPU ID based on the affinity information in the - architecture defined MPIDR, and the field is encoded as follows: + architecture defined MPIDR, and the field is encoded as follows:: + | 63 .... 56 | 55 .... 48 | 47 .... 40 | 39 .... 32 | | Aff3 | Aff2 | Aff1 | Aff0 | + Errors: - -EINVAL: vINTID is not multiple of 32 or - info field is not VGIC_LEVEL_INFO_LINE_LEVEL + + ======= ============================================= + -EINVAL vINTID is not multiple of 32 or info field is + not VGIC_LEVEL_INFO_LINE_LEVEL + ======= ============================================= diff --git a/Documentation/virt/kvm/devices/arm-vgic.txt b/Documentation/virt/kvm/devices/arm-vgic.rst index 97b6518148f8..40bdeea1d86e 100644 --- a/Documentation/virt/kvm/devices/arm-vgic.txt +++ b/Documentation/virt/kvm/devices/arm-vgic.rst @@ -1,8 +1,12 @@ +.. SPDX-License-Identifier: GPL-2.0 + +================================================== ARM Virtual Generic Interrupt Controller v2 (VGIC) ================================================== Device types supported: - KVM_DEV_TYPE_ARM_VGIC_V2 ARM Generic Interrupt Controller v2.0 + + - KVM_DEV_TYPE_ARM_VGIC_V2 ARM Generic Interrupt Controller v2.0 Only one VGIC instance may be instantiated through either this API or the legacy KVM_CREATE_IRQCHIP API. The created VGIC will act as the VM interrupt @@ -17,7 +21,8 @@ create both a GICv3 and GICv2 device on the same VM. Groups: KVM_DEV_ARM_VGIC_GRP_ADDR - Attributes: + Attributes: + KVM_VGIC_V2_ADDR_TYPE_DIST (rw, 64-bit) Base address in the guest physical address space of the GIC distributor register mappings. Only valid for KVM_DEV_TYPE_ARM_VGIC_V2. @@ -27,19 +32,25 @@ Groups: Base address in the guest physical address space of the GIC virtual cpu interface register mappings. Only valid for KVM_DEV_TYPE_ARM_VGIC_V2. This address needs to be 4K aligned and the region covers 4 KByte. + Errors: - -E2BIG: Address outside of addressable IPA range - -EINVAL: Incorrectly aligned address - -EEXIST: Address already configured - -ENXIO: The group or attribute is unknown/unsupported for this device + + ======= ============================================================= + -E2BIG Address outside of addressable IPA range + -EINVAL Incorrectly aligned address + -EEXIST Address already configured + -ENXIO The group or attribute is unknown/unsupported for this device or hardware support is missing. - -EFAULT: Invalid user pointer for attr->addr. + -EFAULT Invalid user pointer for attr->addr. + ======= ============================================================= KVM_DEV_ARM_VGIC_GRP_DIST_REGS - Attributes: - The attr field of kvm_device_attr encodes two values: - bits: | 63 .... 40 | 39 .. 32 | 31 .... 0 | - values: | reserved | vcpu_index | offset | + Attributes: + + The attr field of kvm_device_attr encodes two values:: + + bits: | 63 .... 40 | 39 .. 32 | 31 .... 0 | + values: | reserved | vcpu_index | offset | All distributor regs are (rw, 32-bit) @@ -58,16 +69,22 @@ Groups: KVM_DEV_ARM_VGIC_GRP_DIST_REGS and KVM_DEV_ARM_VGIC_GRP_CPU_REGS) to ensure the expected behavior. Unless GICD_IIDR has been set from userspace, writes to the interrupt group registers (GICD_IGROUPR) are ignored. + Errors: - -ENXIO: Getting or setting this register is not yet supported - -EBUSY: One or more VCPUs are running - -EINVAL: Invalid vcpu_index supplied + + ======= ===================================================== + -ENXIO Getting or setting this register is not yet supported + -EBUSY One or more VCPUs are running + -EINVAL Invalid vcpu_index supplied + ======= ===================================================== KVM_DEV_ARM_VGIC_GRP_CPU_REGS - Attributes: - The attr field of kvm_device_attr encodes two values: - bits: | 63 .... 40 | 39 .. 32 | 31 .... 0 | - values: | reserved | vcpu_index | offset | + Attributes: + + The attr field of kvm_device_attr encodes two values:: + + bits: | 63 .... 40 | 39 .. 32 | 31 .... 0 | + values: | reserved | vcpu_index | offset | All CPU interface regs are (rw, 32-bit) @@ -101,27 +118,39 @@ Groups: value left by 3 places to obtain the actual priority mask level. Errors: - -ENXIO: Getting or setting this register is not yet supported - -EBUSY: One or more VCPUs are running - -EINVAL: Invalid vcpu_index supplied + + ======= ===================================================== + -ENXIO Getting or setting this register is not yet supported + -EBUSY One or more VCPUs are running + -EINVAL Invalid vcpu_index supplied + ======= ===================================================== KVM_DEV_ARM_VGIC_GRP_NR_IRQS - Attributes: + Attributes: + A value describing the number of interrupts (SGI, PPI and SPI) for this GIC instance, ranging from 64 to 1024, in increments of 32. Errors: - -EINVAL: Value set is out of the expected range - -EBUSY: Value has already be set, or GIC has already been initialized - with default values. + + ======= ============================================================= + -EINVAL Value set is out of the expected range + -EBUSY Value has already be set, or GIC has already been initialized + with default values. + ======= ============================================================= KVM_DEV_ARM_VGIC_GRP_CTRL - Attributes: + Attributes: + KVM_DEV_ARM_VGIC_CTRL_INIT request the initialization of the VGIC or ITS, no additional parameter in kvm_device_attr.addr. + Errors: - -ENXIO: VGIC not properly configured as required prior to calling - this attribute - -ENODEV: no online VCPU - -ENOMEM: memory shortage when allocating vgic internal data + + ======= ========================================================= + -ENXIO VGIC not properly configured as required prior to calling + this attribute + -ENODEV no online VCPU + -ENOMEM memory shortage when allocating vgic internal data + ======= ========================================================= diff --git a/Documentation/virt/kvm/devices/index.rst b/Documentation/virt/kvm/devices/index.rst new file mode 100644 index 000000000000..192cda7405c8 --- /dev/null +++ b/Documentation/virt/kvm/devices/index.rst @@ -0,0 +1,19 @@ +.. SPDX-License-Identifier: GPL-2.0 + +======= +Devices +======= + +.. toctree:: + :maxdepth: 2 + + arm-vgic-its + arm-vgic + arm-vgic-v3 + mpic + s390_flic + vcpu + vfio + vm + xics + xive diff --git a/Documentation/virt/kvm/devices/mpic.txt b/Documentation/virt/kvm/devices/mpic.rst index 8257397adc3c..55cefe030d41 100644 --- a/Documentation/virt/kvm/devices/mpic.txt +++ b/Documentation/virt/kvm/devices/mpic.rst @@ -1,9 +1,13 @@ +.. SPDX-License-Identifier: GPL-2.0 + +========================= MPIC interrupt controller ========================= Device types supported: - KVM_DEV_TYPE_FSL_MPIC_20 Freescale MPIC v2.0 - KVM_DEV_TYPE_FSL_MPIC_42 Freescale MPIC v4.2 + + - KVM_DEV_TYPE_FSL_MPIC_20 Freescale MPIC v2.0 + - KVM_DEV_TYPE_FSL_MPIC_42 Freescale MPIC v4.2 Only one MPIC instance, of any type, may be instantiated. The created MPIC will act as the system interrupt controller, connecting to each @@ -11,7 +15,8 @@ vcpu's interrupt inputs. Groups: KVM_DEV_MPIC_GRP_MISC - Attributes: + Attributes: + KVM_DEV_MPIC_BASE_ADDR (rw, 64-bit) Base address of the 256 KiB MPIC register space. Must be naturally aligned. A value of zero disables the mapping. diff --git a/Documentation/virt/kvm/devices/s390_flic.txt b/Documentation/virt/kvm/devices/s390_flic.rst index a4e20a090174..954190da7d04 100644 --- a/Documentation/virt/kvm/devices/s390_flic.txt +++ b/Documentation/virt/kvm/devices/s390_flic.rst @@ -1,3 +1,6 @@ +.. SPDX-License-Identifier: GPL-2.0 + +==================================== FLIC (floating interrupt controller) ==================================== @@ -31,8 +34,10 @@ Groups: Copies all floating interrupts into a buffer provided by userspace. When the buffer is too small it returns -ENOMEM, which is the indication for userspace to try again with a bigger buffer. + -ENOBUFS is returned when the allocation of a kernelspace buffer has failed. + -EFAULT is returned when copying data to userspace failed. All interrupts remain pending, i.e. are not deleted from the list of currently pending interrupts. @@ -60,38 +65,41 @@ Groups: KVM_DEV_FLIC_ADAPTER_REGISTER Register an I/O adapter interrupt source. Takes a kvm_s390_io_adapter - describing the adapter to register: + describing the adapter to register:: -struct kvm_s390_io_adapter { - __u32 id; - __u8 isc; - __u8 maskable; - __u8 swap; - __u8 flags; -}; + struct kvm_s390_io_adapter { + __u32 id; + __u8 isc; + __u8 maskable; + __u8 swap; + __u8 flags; + }; id contains the unique id for the adapter, isc the I/O interruption subclass to use, maskable whether this adapter may be masked (interrupts turned off), swap whether the indicators need to be byte swapped, and flags contains further characteristics of the adapter. + Currently defined values for 'flags' are: + - KVM_S390_ADAPTER_SUPPRESSIBLE: adapter is subject to AIS (adapter-interrupt-suppression) facility. This flag only has an effect if the AIS capability is enabled. + Unknown flag values are ignored. KVM_DEV_FLIC_ADAPTER_MODIFY Modifies attributes of an existing I/O adapter interrupt source. Takes - a kvm_s390_io_adapter_req specifying the adapter and the operation: + a kvm_s390_io_adapter_req specifying the adapter and the operation:: -struct kvm_s390_io_adapter_req { - __u32 id; - __u8 type; - __u8 mask; - __u16 pad0; - __u64 addr; -}; + struct kvm_s390_io_adapter_req { + __u32 id; + __u8 type; + __u8 mask; + __u16 pad0; + __u64 addr; + }; id specifies the adapter and type the operation. The supported operations are: @@ -103,8 +111,9 @@ struct kvm_s390_io_adapter_req { perform a gmap translation for the guest address provided in addr, pin a userspace page for the translated address and add it to the list of mappings - Note: A new mapping will be created unconditionally; therefore, - the calling code should avoid making duplicate mappings. + + .. note:: A new mapping will be created unconditionally; therefore, + the calling code should avoid making duplicate mappings. KVM_S390_IO_ADAPTER_UNMAP release a userspace page for the translated address specified in addr @@ -112,16 +121,17 @@ struct kvm_s390_io_adapter_req { KVM_DEV_FLIC_AISM modify the adapter-interruption-suppression mode for a given isc if the - AIS capability is enabled. Takes a kvm_s390_ais_req describing: + AIS capability is enabled. Takes a kvm_s390_ais_req describing:: -struct kvm_s390_ais_req { - __u8 isc; - __u16 mode; -}; + struct kvm_s390_ais_req { + __u8 isc; + __u16 mode; + }; isc contains the target I/O interruption subclass, mode the target adapter-interruption-suppression mode. The following modes are currently supported: + - KVM_S390_AIS_MODE_ALL: ALL-Interruptions Mode, i.e. airq injection is always allowed; - KVM_S390_AIS_MODE_SINGLE: SINGLE-Interruption Mode, i.e. airq @@ -139,12 +149,12 @@ struct kvm_s390_ais_req { KVM_DEV_FLIC_AISM_ALL Gets or sets the adapter-interruption-suppression mode for all ISCs. Takes - a kvm_s390_ais_all describing: + a kvm_s390_ais_all describing:: -struct kvm_s390_ais_all { - __u8 simm; /* Single-Interruption-Mode mask */ - __u8 nimm; /* No-Interruption-Mode mask * -}; + struct kvm_s390_ais_all { + __u8 simm; /* Single-Interruption-Mode mask */ + __u8 nimm; /* No-Interruption-Mode mask * + }; simm contains Single-Interruption-Mode mask for all ISCs, nimm contains No-Interruption-Mode mask for all ISCs. Each bit in simm and nimm corresponds @@ -159,5 +169,5 @@ ENXIO, as specified in the API documentation). It is not possible to conclude that a FLIC operation is unavailable based on the error code resulting from a usage attempt. -Note: The KVM_DEV_FLIC_CLEAR_IO_IRQ ioctl will return EINVAL in case a zero -schid is specified. +.. note:: The KVM_DEV_FLIC_CLEAR_IO_IRQ ioctl will return EINVAL in case a + zero schid is specified. diff --git a/Documentation/virt/kvm/devices/vcpu.rst b/Documentation/virt/kvm/devices/vcpu.rst new file mode 100644 index 000000000000..9963e680770a --- /dev/null +++ b/Documentation/virt/kvm/devices/vcpu.rst @@ -0,0 +1,114 @@ +.. SPDX-License-Identifier: GPL-2.0 + +====================== +Generic vcpu interface +====================== + +The virtual cpu "device" also accepts the ioctls KVM_SET_DEVICE_ATTR, +KVM_GET_DEVICE_ATTR, and KVM_HAS_DEVICE_ATTR. The interface uses the same struct +kvm_device_attr as other devices, but targets VCPU-wide settings and controls. + +The groups and attributes per virtual cpu, if any, are architecture specific. + +1. GROUP: KVM_ARM_VCPU_PMU_V3_CTRL +================================== + +:Architectures: ARM64 + +1.1. ATTRIBUTE: KVM_ARM_VCPU_PMU_V3_IRQ +--------------------------------------- + +:Parameters: in kvm_device_attr.addr the address for PMU overflow interrupt is a + pointer to an int + +Returns: + + ======= ======================================================== + -EBUSY The PMU overflow interrupt is already set + -ENXIO The overflow interrupt not set when attempting to get it + -ENODEV PMUv3 not supported + -EINVAL Invalid PMU overflow interrupt number supplied or + trying to set the IRQ number without using an in-kernel + irqchip. + ======= ======================================================== + +A value describing the PMUv3 (Performance Monitor Unit v3) overflow interrupt +number for this vcpu. This interrupt could be a PPI or SPI, but the interrupt +type must be same for each vcpu. As a PPI, the interrupt number is the same for +all vcpus, while as an SPI it must be a separate number per vcpu. + +1.2 ATTRIBUTE: KVM_ARM_VCPU_PMU_V3_INIT +--------------------------------------- + +:Parameters: no additional parameter in kvm_device_attr.addr + +Returns: + + ======= ====================================================== + -ENODEV PMUv3 not supported or GIC not initialized + -ENXIO PMUv3 not properly configured or in-kernel irqchip not + configured as required prior to calling this attribute + -EBUSY PMUv3 already initialized + ======= ====================================================== + +Request the initialization of the PMUv3. If using the PMUv3 with an in-kernel +virtual GIC implementation, this must be done after initializing the in-kernel +irqchip. + + +2. GROUP: KVM_ARM_VCPU_TIMER_CTRL +================================= + +:Architectures: ARM, ARM64 + +2.1. ATTRIBUTES: KVM_ARM_VCPU_TIMER_IRQ_VTIMER, KVM_ARM_VCPU_TIMER_IRQ_PTIMER +----------------------------------------------------------------------------- + +:Parameters: in kvm_device_attr.addr the address for the timer interrupt is a + pointer to an int + +Returns: + + ======= ================================= + -EINVAL Invalid timer interrupt number + -EBUSY One or more VCPUs has already run + ======= ================================= + +A value describing the architected timer interrupt number when connected to an +in-kernel virtual GIC. These must be a PPI (16 <= intid < 32). Setting the +attribute overrides the default values (see below). + +============================= ========================================== +KVM_ARM_VCPU_TIMER_IRQ_VTIMER The EL1 virtual timer intid (default: 27) +KVM_ARM_VCPU_TIMER_IRQ_PTIMER The EL1 physical timer intid (default: 30) +============================= ========================================== + +Setting the same PPI for different timers will prevent the VCPUs from running. +Setting the interrupt number on a VCPU configures all VCPUs created at that +time to use the number provided for a given timer, overwriting any previously +configured values on other VCPUs. Userspace should configure the interrupt +numbers on at least one VCPU after creating all VCPUs and before running any +VCPUs. + +3. GROUP: KVM_ARM_VCPU_PVTIME_CTRL +================================== + +:Architectures: ARM64 + +3.1 ATTRIBUTE: KVM_ARM_VCPU_PVTIME_IPA +-------------------------------------- + +:Parameters: 64-bit base address + +Returns: + + ======= ====================================== + -ENXIO Stolen time not implemented + -EEXIST Base address already set for this VCPU + -EINVAL Base address not 64 byte aligned + ======= ====================================== + +Specifies the base address of the stolen time structure for this VCPU. The +base address must be 64 byte aligned and exist within a valid guest memory +region. See Documentation/virt/kvm/arm/pvtime.txt for more information +including the layout of the stolen time structure. diff --git a/Documentation/virt/kvm/devices/vcpu.txt b/Documentation/virt/kvm/devices/vcpu.txt deleted file mode 100644 index 6f3bd64a05b0..000000000000 --- a/Documentation/virt/kvm/devices/vcpu.txt +++ /dev/null @@ -1,76 +0,0 @@ -Generic vcpu interface -==================================== - -The virtual cpu "device" also accepts the ioctls KVM_SET_DEVICE_ATTR, -KVM_GET_DEVICE_ATTR, and KVM_HAS_DEVICE_ATTR. The interface uses the same struct -kvm_device_attr as other devices, but targets VCPU-wide settings and controls. - -The groups and attributes per virtual cpu, if any, are architecture specific. - -1. GROUP: KVM_ARM_VCPU_PMU_V3_CTRL -Architectures: ARM64 - -1.1. ATTRIBUTE: KVM_ARM_VCPU_PMU_V3_IRQ -Parameters: in kvm_device_attr.addr the address for PMU overflow interrupt is a - pointer to an int -Returns: -EBUSY: The PMU overflow interrupt is already set - -ENXIO: The overflow interrupt not set when attempting to get it - -ENODEV: PMUv3 not supported - -EINVAL: Invalid PMU overflow interrupt number supplied or - trying to set the IRQ number without using an in-kernel - irqchip. - -A value describing the PMUv3 (Performance Monitor Unit v3) overflow interrupt -number for this vcpu. This interrupt could be a PPI or SPI, but the interrupt -type must be same for each vcpu. As a PPI, the interrupt number is the same for -all vcpus, while as an SPI it must be a separate number per vcpu. - -1.2 ATTRIBUTE: KVM_ARM_VCPU_PMU_V3_INIT -Parameters: no additional parameter in kvm_device_attr.addr -Returns: -ENODEV: PMUv3 not supported or GIC not initialized - -ENXIO: PMUv3 not properly configured or in-kernel irqchip not - configured as required prior to calling this attribute - -EBUSY: PMUv3 already initialized - -Request the initialization of the PMUv3. If using the PMUv3 with an in-kernel -virtual GIC implementation, this must be done after initializing the in-kernel -irqchip. - - -2. GROUP: KVM_ARM_VCPU_TIMER_CTRL -Architectures: ARM,ARM64 - -2.1. ATTRIBUTE: KVM_ARM_VCPU_TIMER_IRQ_VTIMER -2.2. ATTRIBUTE: KVM_ARM_VCPU_TIMER_IRQ_PTIMER -Parameters: in kvm_device_attr.addr the address for the timer interrupt is a - pointer to an int -Returns: -EINVAL: Invalid timer interrupt number - -EBUSY: One or more VCPUs has already run - -A value describing the architected timer interrupt number when connected to an -in-kernel virtual GIC. These must be a PPI (16 <= intid < 32). Setting the -attribute overrides the default values (see below). - -KVM_ARM_VCPU_TIMER_IRQ_VTIMER: The EL1 virtual timer intid (default: 27) -KVM_ARM_VCPU_TIMER_IRQ_PTIMER: The EL1 physical timer intid (default: 30) - -Setting the same PPI for different timers will prevent the VCPUs from running. -Setting the interrupt number on a VCPU configures all VCPUs created at that -time to use the number provided for a given timer, overwriting any previously -configured values on other VCPUs. Userspace should configure the interrupt -numbers on at least one VCPU after creating all VCPUs and before running any -VCPUs. - -3. GROUP: KVM_ARM_VCPU_PVTIME_CTRL -Architectures: ARM64 - -3.1 ATTRIBUTE: KVM_ARM_VCPU_PVTIME_IPA -Parameters: 64-bit base address -Returns: -ENXIO: Stolen time not implemented - -EEXIST: Base address already set for this VCPU - -EINVAL: Base address not 64 byte aligned - -Specifies the base address of the stolen time structure for this VCPU. The -base address must be 64 byte aligned and exist within a valid guest memory -region. See Documentation/virt/kvm/arm/pvtime.txt for more information -including the layout of the stolen time structure. diff --git a/Documentation/virt/kvm/devices/vfio.txt b/Documentation/virt/kvm/devices/vfio.rst index 528c77c8022c..2d20dc561069 100644 --- a/Documentation/virt/kvm/devices/vfio.txt +++ b/Documentation/virt/kvm/devices/vfio.rst @@ -1,8 +1,12 @@ +.. SPDX-License-Identifier: GPL-2.0 + +=================== VFIO virtual device =================== Device types supported: - KVM_DEV_TYPE_VFIO + + - KVM_DEV_TYPE_VFIO Only one VFIO instance may be created per VM. The created device tracks VFIO groups in use by the VM and features of those groups @@ -23,14 +27,15 @@ KVM_DEV_VFIO_GROUP attributes: for the VFIO group. KVM_DEV_VFIO_GROUP_SET_SPAPR_TCE: attaches a guest visible TCE table allocated by sPAPR KVM. - kvm_device_attr.addr points to a struct: + kvm_device_attr.addr points to a struct:: + + struct kvm_vfio_spapr_tce { + __s32 groupfd; + __s32 tablefd; + }; - struct kvm_vfio_spapr_tce { - __s32 groupfd; - __s32 tablefd; - }; + where: - where - @groupfd is a file descriptor for a VFIO group; - @tablefd is a file descriptor for a TCE table allocated via - KVM_CREATE_SPAPR_TCE. + - @groupfd is a file descriptor for a VFIO group; + - @tablefd is a file descriptor for a TCE table allocated via + KVM_CREATE_SPAPR_TCE. diff --git a/Documentation/virt/kvm/devices/vm.txt b/Documentation/virt/kvm/devices/vm.rst index 4ffb82b02468..0aa5b1cfd700 100644 --- a/Documentation/virt/kvm/devices/vm.txt +++ b/Documentation/virt/kvm/devices/vm.rst @@ -1,5 +1,8 @@ +.. SPDX-License-Identifier: GPL-2.0 + +==================== Generic vm interface -==================================== +==================== The virtual machine "device" also accepts the ioctls KVM_SET_DEVICE_ATTR, KVM_GET_DEVICE_ATTR, and KVM_HAS_DEVICE_ATTR. The interface uses the same @@ -10,30 +13,38 @@ The groups and attributes per virtual machine, if any, are architecture specific. 1. GROUP: KVM_S390_VM_MEM_CTRL -Architectures: s390 +============================== + +:Architectures: s390 1.1. ATTRIBUTE: KVM_S390_VM_MEM_ENABLE_CMMA -Parameters: none -Returns: -EBUSY if a vcpu is already defined, otherwise 0 +------------------------------------------- + +:Parameters: none +:Returns: -EBUSY if a vcpu is already defined, otherwise 0 Enables Collaborative Memory Management Assist (CMMA) for the virtual machine. 1.2. ATTRIBUTE: KVM_S390_VM_MEM_CLR_CMMA -Parameters: none -Returns: -EINVAL if CMMA was not enabled - 0 otherwise +---------------------------------------- + +:Parameters: none +:Returns: -EINVAL if CMMA was not enabled; + 0 otherwise Clear the CMMA status for all guest pages, so any pages the guest marked as unused are again used any may not be reclaimed by the host. 1.3. ATTRIBUTE KVM_S390_VM_MEM_LIMIT_SIZE -Parameters: in attr->addr the address for the new limit of guest memory -Returns: -EFAULT if the given address is not accessible - -EINVAL if the virtual machine is of type UCONTROL - -E2BIG if the given guest memory is to big for that machine - -EBUSY if a vcpu is already defined - -ENOMEM if not enough memory is available for a new shadow guest mapping - 0 otherwise +----------------------------------------- + +:Parameters: in attr->addr the address for the new limit of guest memory +:Returns: -EFAULT if the given address is not accessible; + -EINVAL if the virtual machine is of type UCONTROL; + -E2BIG if the given guest memory is to big for that machine; + -EBUSY if a vcpu is already defined; + -ENOMEM if not enough memory is available for a new shadow guest mapping; + 0 otherwise. Allows userspace to query the actual limit and set a new limit for the maximum guest memory size. The limit will be rounded up to @@ -42,78 +53,92 @@ the number of page table levels. In the case that there is no limit we will set the limit to KVM_S390_NO_MEM_LIMIT (U64_MAX). 2. GROUP: KVM_S390_VM_CPU_MODEL -Architectures: s390 +=============================== + +:Architectures: s390 2.1. ATTRIBUTE: KVM_S390_VM_CPU_MACHINE (r/o) +--------------------------------------------- -Allows user space to retrieve machine and kvm specific cpu related information: +Allows user space to retrieve machine and kvm specific cpu related information:: -struct kvm_s390_vm_cpu_machine { + struct kvm_s390_vm_cpu_machine { __u64 cpuid; # CPUID of host __u32 ibc; # IBC level range offered by host __u8 pad[4]; __u64 fac_mask[256]; # set of cpu facilities enabled by KVM __u64 fac_list[256]; # set of cpu facilities offered by host -} + } -Parameters: address of buffer to store the machine related cpu data - of type struct kvm_s390_vm_cpu_machine* -Returns: -EFAULT if the given address is not accessible from kernel space - -ENOMEM if not enough memory is available to process the ioctl - 0 in case of success +:Parameters: address of buffer to store the machine related cpu data + of type struct kvm_s390_vm_cpu_machine* +:Returns: -EFAULT if the given address is not accessible from kernel space; + -ENOMEM if not enough memory is available to process the ioctl; + 0 in case of success. 2.2. ATTRIBUTE: KVM_S390_VM_CPU_PROCESSOR (r/w) +=============================================== -Allows user space to retrieve or request to change cpu related information for a vcpu: +Allows user space to retrieve or request to change cpu related information for a vcpu:: -struct kvm_s390_vm_cpu_processor { + struct kvm_s390_vm_cpu_processor { __u64 cpuid; # CPUID currently (to be) used by this vcpu __u16 ibc; # IBC level currently (to be) used by this vcpu __u8 pad[6]; __u64 fac_list[256]; # set of cpu facilities currently (to be) used - # by this vcpu -} + # by this vcpu + } KVM does not enforce or limit the cpu model data in any form. Take the information retrieved by means of KVM_S390_VM_CPU_MACHINE as hint for reasonable configuration setups. Instruction interceptions triggered by additionally set facility bits that are not handled by KVM need to by imlemented in the VM driver code. -Parameters: address of buffer to store/set the processor related cpu - data of type struct kvm_s390_vm_cpu_processor*. -Returns: -EBUSY in case 1 or more vcpus are already activated (only in write case) - -EFAULT if the given address is not accessible from kernel space - -ENOMEM if not enough memory is available to process the ioctl - 0 in case of success +:Parameters: address of buffer to store/set the processor related cpu + data of type struct kvm_s390_vm_cpu_processor*. +:Returns: -EBUSY in case 1 or more vcpus are already activated (only in write case); + -EFAULT if the given address is not accessible from kernel space; + -ENOMEM if not enough memory is available to process the ioctl; + 0 in case of success. + +.. _KVM_S390_VM_CPU_MACHINE_FEAT: 2.3. ATTRIBUTE: KVM_S390_VM_CPU_MACHINE_FEAT (r/o) +-------------------------------------------------- Allows user space to retrieve available cpu features. A feature is available if provided by the hardware and supported by kvm. In theory, cpu features could even be completely emulated by kvm. -struct kvm_s390_vm_cpu_feat { - __u64 feat[16]; # Bitmap (1 = feature available), MSB 0 bit numbering -}; +:: -Parameters: address of a buffer to load the feature list from. -Returns: -EFAULT if the given address is not accessible from kernel space. - 0 in case of success. + struct kvm_s390_vm_cpu_feat { + __u64 feat[16]; # Bitmap (1 = feature available), MSB 0 bit numbering + }; + +:Parameters: address of a buffer to load the feature list from. +:Returns: -EFAULT if the given address is not accessible from kernel space; + 0 in case of success. 2.4. ATTRIBUTE: KVM_S390_VM_CPU_PROCESSOR_FEAT (r/w) +---------------------------------------------------- Allows user space to retrieve or change enabled cpu features for all VCPUs of a VM. Features that are not available cannot be enabled. -See 2.3. for a description of the parameter struct. +See :ref:`KVM_S390_VM_CPU_MACHINE_FEAT` for +a description of the parameter struct. -Parameters: address of a buffer to store/load the feature list from. -Returns: -EFAULT if the given address is not accessible from kernel space. - -EINVAL if a cpu feature that is not available is to be enabled. - -EBUSY if at least one VCPU has already been defined. +:Parameters: address of a buffer to store/load the feature list from. +:Returns: -EFAULT if the given address is not accessible from kernel space; + -EINVAL if a cpu feature that is not available is to be enabled; + -EBUSY if at least one VCPU has already been defined; 0 in case of success. +.. _KVM_S390_VM_CPU_MACHINE_SUBFUNC: + 2.5. ATTRIBUTE: KVM_S390_VM_CPU_MACHINE_SUBFUNC (r/o) +----------------------------------------------------- Allows user space to retrieve available cpu subfunctions without any filtering done by a set IBC. These subfunctions are indicated to the guest VCPU via @@ -126,7 +151,9 @@ contained in the returned struct. If the affected instruction indicates subfunctions via a "test bit" mechanism, the subfunction codes are contained in the returned struct in MSB 0 bit numbering. -struct kvm_s390_vm_cpu_subfunc { +:: + + struct kvm_s390_vm_cpu_subfunc { u8 plo[32]; # always valid (ESA/390 feature) u8 ptff[16]; # valid with TOD-clock steering u8 kmac[16]; # valid with Message-Security-Assist @@ -143,13 +170,14 @@ struct kvm_s390_vm_cpu_subfunc { u8 kma[16]; # valid with Message-Security-Assist-Extension 8 u8 kdsa[16]; # valid with Message-Security-Assist-Extension 9 u8 reserved[1792]; # reserved for future instructions -}; + }; -Parameters: address of a buffer to load the subfunction blocks from. -Returns: -EFAULT if the given address is not accessible from kernel space. +:Parameters: address of a buffer to load the subfunction blocks from. +:Returns: -EFAULT if the given address is not accessible from kernel space; 0 in case of success. 2.6. ATTRIBUTE: KVM_S390_VM_CPU_PROCESSOR_SUBFUNC (r/w) +------------------------------------------------------- Allows user space to retrieve or change cpu subfunctions to be indicated for all VCPUs of a VM. This attribute will only be available if kernel and @@ -164,107 +192,125 @@ As long as no data has been written, a read will fail. The IBC will be used to determine available subfunctions in this case, this will guarantee backward compatibility. -See 2.5. for a description of the parameter struct. +See :ref:`KVM_S390_VM_CPU_MACHINE_SUBFUNC` for a +description of the parameter struct. -Parameters: address of a buffer to store/load the subfunction blocks from. -Returns: -EFAULT if the given address is not accessible from kernel space. - -EINVAL when reading, if there was no write yet. - -EBUSY if at least one VCPU has already been defined. +:Parameters: address of a buffer to store/load the subfunction blocks from. +:Returns: -EFAULT if the given address is not accessible from kernel space; + -EINVAL when reading, if there was no write yet; + -EBUSY if at least one VCPU has already been defined; 0 in case of success. 3. GROUP: KVM_S390_VM_TOD -Architectures: s390 +========================= + +:Architectures: s390 3.1. ATTRIBUTE: KVM_S390_VM_TOD_HIGH +------------------------------------ Allows user space to set/get the TOD clock extension (u8) (superseded by KVM_S390_VM_TOD_EXT). -Parameters: address of a buffer in user space to store the data (u8) to -Returns: -EFAULT if the given address is not accessible from kernel space +:Parameters: address of a buffer in user space to store the data (u8) to +:Returns: -EFAULT if the given address is not accessible from kernel space; -EINVAL if setting the TOD clock extension to != 0 is not supported 3.2. ATTRIBUTE: KVM_S390_VM_TOD_LOW +----------------------------------- Allows user space to set/get bits 0-63 of the TOD clock register as defined in the POP (u64). -Parameters: address of a buffer in user space to store the data (u64) to -Returns: -EFAULT if the given address is not accessible from kernel space +:Parameters: address of a buffer in user space to store the data (u64) to +:Returns: -EFAULT if the given address is not accessible from kernel space 3.3. ATTRIBUTE: KVM_S390_VM_TOD_EXT +----------------------------------- + Allows user space to set/get bits 0-63 of the TOD clock register as defined in the POP (u64). If the guest CPU model supports the TOD clock extension (u8), it also allows user space to get/set it. If the guest CPU model does not support it, it is stored as 0 and not allowed to be set to a value != 0. -Parameters: address of a buffer in user space to store the data - (kvm_s390_vm_tod_clock) to -Returns: -EFAULT if the given address is not accessible from kernel space +:Parameters: address of a buffer in user space to store the data + (kvm_s390_vm_tod_clock) to +:Returns: -EFAULT if the given address is not accessible from kernel space; -EINVAL if setting the TOD clock extension to != 0 is not supported 4. GROUP: KVM_S390_VM_CRYPTO -Architectures: s390 +============================ + +:Architectures: s390 4.1. ATTRIBUTE: KVM_S390_VM_CRYPTO_ENABLE_AES_KW (w/o) +------------------------------------------------------ Allows user space to enable aes key wrapping, including generating a new wrapping key. -Parameters: none -Returns: 0 +:Parameters: none +:Returns: 0 4.2. ATTRIBUTE: KVM_S390_VM_CRYPTO_ENABLE_DEA_KW (w/o) +------------------------------------------------------ Allows user space to enable dea key wrapping, including generating a new wrapping key. -Parameters: none -Returns: 0 +:Parameters: none +:Returns: 0 4.3. ATTRIBUTE: KVM_S390_VM_CRYPTO_DISABLE_AES_KW (w/o) +------------------------------------------------------- Allows user space to disable aes key wrapping, clearing the wrapping key. -Parameters: none -Returns: 0 +:Parameters: none +:Returns: 0 4.4. ATTRIBUTE: KVM_S390_VM_CRYPTO_DISABLE_DEA_KW (w/o) +------------------------------------------------------- Allows user space to disable dea key wrapping, clearing the wrapping key. -Parameters: none -Returns: 0 +:Parameters: none +:Returns: 0 5. GROUP: KVM_S390_VM_MIGRATION -Architectures: s390 +=============================== + +:Architectures: s390 5.1. ATTRIBUTE: KVM_S390_VM_MIGRATION_STOP (w/o) +------------------------------------------------ Allows userspace to stop migration mode, needed for PGSTE migration. Setting this attribute when migration mode is not active will have no effects. -Parameters: none -Returns: 0 +:Parameters: none +:Returns: 0 5.2. ATTRIBUTE: KVM_S390_VM_MIGRATION_START (w/o) +------------------------------------------------- Allows userspace to start migration mode, needed for PGSTE migration. Setting this attribute when migration mode is already active will have no effects. -Parameters: none -Returns: -ENOMEM if there is not enough free memory to start migration mode - -EINVAL if the state of the VM is invalid (e.g. no memory defined) +:Parameters: none +:Returns: -ENOMEM if there is not enough free memory to start migration mode; + -EINVAL if the state of the VM is invalid (e.g. no memory defined); 0 in case of success. 5.3. ATTRIBUTE: KVM_S390_VM_MIGRATION_STATUS (r/o) +-------------------------------------------------- Allows userspace to query the status of migration mode. -Parameters: address of a buffer in user space to store the data (u64) to; - the data itself is either 0 if migration mode is disabled or 1 - if it is enabled -Returns: -EFAULT if the given address is not accessible from kernel space +:Parameters: address of a buffer in user space to store the data (u64) to; + the data itself is either 0 if migration mode is disabled or 1 + if it is enabled +:Returns: -EFAULT if the given address is not accessible from kernel space; 0 in case of success. diff --git a/Documentation/virt/kvm/devices/xics.txt b/Documentation/virt/kvm/devices/xics.rst index 423332dda7bc..2d6927e0b776 100644 --- a/Documentation/virt/kvm/devices/xics.txt +++ b/Documentation/virt/kvm/devices/xics.rst @@ -1,20 +1,31 @@ +.. SPDX-License-Identifier: GPL-2.0 + +========================= XICS interrupt controller +========================= Device type supported: KVM_DEV_TYPE_XICS Groups: 1. KVM_DEV_XICS_GRP_SOURCES - Attributes: One per interrupt source, indexed by the source number. + Attributes: + One per interrupt source, indexed by the source number. 2. KVM_DEV_XICS_GRP_CTRL - Attributes: - 2.1 KVM_DEV_XICS_NR_SERVERS (write only) + Attributes: + + 2.1 KVM_DEV_XICS_NR_SERVERS (write only) + The kvm_device_attr.addr points to a __u32 value which is the number of interrupt server numbers (ie, highest possible vcpu id plus one). + Errors: - -EINVAL: Value greater than KVM_MAX_VCPU_ID. - -EFAULT: Invalid user pointer for attr->addr. - -EBUSY: A vcpu is already connected to the device. + + ======= ========================================== + -EINVAL Value greater than KVM_MAX_VCPU_ID. + -EFAULT Invalid user pointer for attr->addr. + -EBUSY A vcpu is already connected to the device. + ======= ========================================== This device emulates the XICS (eXternal Interrupt Controller Specification) defined in PAPR. The XICS has a set of interrupt @@ -53,24 +64,29 @@ the interrupt source number. The 64 bit state word has the following bitfields, starting from the least-significant end of the word: * Destination (server number), 32 bits + This specifies where the interrupt should be sent, and is the interrupt server number specified for the destination vcpu. * Priority, 8 bits + This is the priority specified for this interrupt source, where 0 is the highest priority and 255 is the lowest. An interrupt with a priority of 255 will never be delivered. * Level sensitive flag, 1 bit + This bit is 1 for a level-sensitive interrupt source, or 0 for edge-sensitive (or MSI). * Masked flag, 1 bit + This bit is set to 1 if the interrupt is masked (cannot be delivered regardless of its priority), for example by the ibm,int-off RTAS call, or 0 if it is not masked. * Pending flag, 1 bit + This bit is 1 if the source has a pending interrupt, otherwise 0. Only one XICS instance may be created per VM. diff --git a/Documentation/virt/kvm/devices/xive.txt b/Documentation/virt/kvm/devices/xive.rst index f5d1d6b5af61..8bdf3dc38f01 100644 --- a/Documentation/virt/kvm/devices/xive.txt +++ b/Documentation/virt/kvm/devices/xive.rst @@ -1,8 +1,11 @@ +.. SPDX-License-Identifier: GPL-2.0 + +=========================================================== POWER9 eXternal Interrupt Virtualization Engine (XIVE Gen1) -========================================================== +=========================================================== Device types supported: - KVM_DEV_TYPE_XIVE POWER9 XIVE Interrupt Controller generation 1 + - KVM_DEV_TYPE_XIVE POWER9 XIVE Interrupt Controller generation 1 This device acts as a VM interrupt controller. It provides the KVM interface to configure the interrupt sources of a VM in the underlying @@ -64,72 +67,100 @@ the legacy interrupt mode, referred as XICS (POWER7/8). * Groups: - 1. KVM_DEV_XIVE_GRP_CTRL - Provides global controls on the device +1. KVM_DEV_XIVE_GRP_CTRL + Provides global controls on the device + Attributes: 1.1 KVM_DEV_XIVE_RESET (write only) Resets the interrupt controller configuration for sources and event queues. To be used by kexec and kdump. + Errors: none 1.2 KVM_DEV_XIVE_EQ_SYNC (write only) Sync all the sources and queues and mark the EQ pages dirty. This to make sure that a consistent memory state is captured when migrating the VM. + Errors: none 1.3 KVM_DEV_XIVE_NR_SERVERS (write only) The kvm_device_attr.addr points to a __u32 value which is the number of interrupt server numbers (ie, highest possible vcpu id plus one). + Errors: - -EINVAL: Value greater than KVM_MAX_VCPU_ID. - -EFAULT: Invalid user pointer for attr->addr. - -EBUSY: A vCPU is already connected to the device. - 2. KVM_DEV_XIVE_GRP_SOURCE (write only) - Initializes a new source in the XIVE device and mask it. + ======= ========================================== + -EINVAL Value greater than KVM_MAX_VCPU_ID. + -EFAULT Invalid user pointer for attr->addr. + -EBUSY A vCPU is already connected to the device. + ======= ========================================== + +2. KVM_DEV_XIVE_GRP_SOURCE (write only) + Initializes a new source in the XIVE device and mask it. + Attributes: Interrupt source number (64-bit) - The kvm_device_attr.addr points to a __u64 value: - bits: | 63 .... 2 | 1 | 0 - values: | unused | level | type + + The kvm_device_attr.addr points to a __u64 value:: + + bits: | 63 .... 2 | 1 | 0 + values: | unused | level | type + - type: 0:MSI 1:LSI - level: assertion level in case of an LSI. + Errors: - -E2BIG: Interrupt source number is out of range - -ENOMEM: Could not create a new source block - -EFAULT: Invalid user pointer for attr->addr. - -ENXIO: Could not allocate underlying HW interrupt - 3. KVM_DEV_XIVE_GRP_SOURCE_CONFIG (write only) - Configures source targeting + ======= ========================================== + -E2BIG Interrupt source number is out of range + -ENOMEM Could not create a new source block + -EFAULT Invalid user pointer for attr->addr. + -ENXIO Could not allocate underlying HW interrupt + ======= ========================================== + +3. KVM_DEV_XIVE_GRP_SOURCE_CONFIG (write only) + Configures source targeting + Attributes: Interrupt source number (64-bit) - The kvm_device_attr.addr points to a __u64 value: - bits: | 63 .... 33 | 32 | 31 .. 3 | 2 .. 0 - values: | eisn | mask | server | priority + + The kvm_device_attr.addr points to a __u64 value:: + + bits: | 63 .... 33 | 32 | 31 .. 3 | 2 .. 0 + values: | eisn | mask | server | priority + - priority: 0-7 interrupt priority level - server: CPU number chosen to handle the interrupt - mask: mask flag (unused) - eisn: Effective Interrupt Source Number + Errors: - -ENOENT: Unknown source number - -EINVAL: Not initialized source number - -EINVAL: Invalid priority - -EINVAL: Invalid CPU number. - -EFAULT: Invalid user pointer for attr->addr. - -ENXIO: CPU event queues not configured or configuration of the - underlying HW interrupt failed - -EBUSY: No CPU available to serve interrupt - - 4. KVM_DEV_XIVE_GRP_EQ_CONFIG (read-write) - Configures an event queue of a CPU + + ======= ======================================================= + -ENOENT Unknown source number + -EINVAL Not initialized source number + -EINVAL Invalid priority + -EINVAL Invalid CPU number. + -EFAULT Invalid user pointer for attr->addr. + -ENXIO CPU event queues not configured or configuration of the + underlying HW interrupt failed + -EBUSY No CPU available to serve interrupt + ======= ======================================================= + +4. KVM_DEV_XIVE_GRP_EQ_CONFIG (read-write) + Configures an event queue of a CPU + Attributes: EQ descriptor identifier (64-bit) - The EQ descriptor identifier is a tuple (server, priority) : - bits: | 63 .... 32 | 31 .. 3 | 2 .. 0 - values: | unused | server | priority - The kvm_device_attr.addr points to : + + The EQ descriptor identifier is a tuple (server, priority):: + + bits: | 63 .... 32 | 31 .. 3 | 2 .. 0 + values: | unused | server | priority + + The kvm_device_attr.addr points to:: + struct kvm_ppc_xive_eq { __u32 flags; __u32 qshift; @@ -138,8 +169,9 @@ the legacy interrupt mode, referred as XICS (POWER7/8). __u32 qindex; __u8 pad[40]; }; + - flags: queue flags - KVM_XIVE_EQ_ALWAYS_NOTIFY (required) + KVM_XIVE_EQ_ALWAYS_NOTIFY (required) forces notification without using the coalescing mechanism provided by the XIVE END ESBs. - qshift: queue size (power of 2) @@ -147,22 +179,31 @@ the legacy interrupt mode, referred as XICS (POWER7/8). - qtoggle: current queue toggle bit - qindex: current queue index - pad: reserved for future use + Errors: - -ENOENT: Invalid CPU number - -EINVAL: Invalid priority - -EINVAL: Invalid flags - -EINVAL: Invalid queue size - -EINVAL: Invalid queue address - -EFAULT: Invalid user pointer for attr->addr. - -EIO: Configuration of the underlying HW failed - - 5. KVM_DEV_XIVE_GRP_SOURCE_SYNC (write only) - Synchronize the source to flush event notifications + + ======= ========================================= + -ENOENT Invalid CPU number + -EINVAL Invalid priority + -EINVAL Invalid flags + -EINVAL Invalid queue size + -EINVAL Invalid queue address + -EFAULT Invalid user pointer for attr->addr. + -EIO Configuration of the underlying HW failed + ======= ========================================= + +5. KVM_DEV_XIVE_GRP_SOURCE_SYNC (write only) + Synchronize the source to flush event notifications + Attributes: Interrupt source number (64-bit) + Errors: - -ENOENT: Unknown source number - -EINVAL: Not initialized source number + + ======= ============================= + -ENOENT Unknown source number + -EINVAL Not initialized source number + ======= ============================= * VCPU state @@ -175,11 +216,12 @@ the legacy interrupt mode, referred as XICS (POWER7/8). as it synthesizes the priorities of the pending interrupts. We capture a bit more to report debug information. - KVM_REG_PPC_VP_STATE (2 * 64bits) - bits: | 63 .... 32 | 31 .... 0 | - values: | TIMA word0 | TIMA word1 | - bits: | 127 .......... 64 | - values: | unused | + KVM_REG_PPC_VP_STATE (2 * 64bits):: + + bits: | 63 .... 32 | 31 .... 0 | + values: | TIMA word0 | TIMA word1 | + bits: | 127 .......... 64 | + values: | unused | * Migration: @@ -196,7 +238,7 @@ the legacy interrupt mode, referred as XICS (POWER7/8). 3. Capture the state of the source targeting, the EQs configuration and the state of thread interrupt context registers. - Restore is similar : + Restore is similar: 1. Restore the EQ configuration. As targeting depends on it. 2. Restore targeting diff --git a/Documentation/virt/kvm/halt-polling.txt b/Documentation/virt/kvm/halt-polling.rst index 4f791b128dd2..4922e4a15f18 100644 --- a/Documentation/virt/kvm/halt-polling.txt +++ b/Documentation/virt/kvm/halt-polling.rst @@ -1,3 +1,6 @@ +.. SPDX-License-Identifier: GPL-2.0 + +=========================== The KVM halt polling system =========================== @@ -68,7 +71,8 @@ steady state polling interval but will only really do a good job for wakeups which come at an approximately constant rate, otherwise there will be constant adjustment of the polling interval. -[0] total block time: the time between when the halt polling function is +[0] total block time: + the time between when the halt polling function is invoked and a wakeup source received (irrespective of whether the scheduler is invoked within that function). @@ -81,31 +85,32 @@ shrunk. These variables are defined in include/linux/kvm_host.h and as module parameters in virt/kvm/kvm_main.c, or arch/powerpc/kvm/book3s_hv.c in the powerpc kvm-hv case. -Module Parameter | Description | Default Value --------------------------------------------------------------------------------- -halt_poll_ns | The global max polling | KVM_HALT_POLL_NS_DEFAULT - | interval which defines | - | the ceiling value of the | - | polling interval for | (per arch value) - | each vcpu. | --------------------------------------------------------------------------------- -halt_poll_ns_grow | The value by which the | 2 - | halt polling interval is | - | multiplied in the | - | grow_halt_poll_ns() | - | function. | --------------------------------------------------------------------------------- -halt_poll_ns_grow_start | The initial value to grow | 10000 - | to from zero in the | - | grow_halt_poll_ns() | - | function. | --------------------------------------------------------------------------------- -halt_poll_ns_shrink | The value by which the | 0 - | halt polling interval is | - | divided in the | - | shrink_halt_poll_ns() | - | function. | --------------------------------------------------------------------------------- ++-----------------------+---------------------------+-------------------------+ +|Module Parameter | Description | Default Value | ++-----------------------+---------------------------+-------------------------+ +|halt_poll_ns | The global max polling | KVM_HALT_POLL_NS_DEFAULT| +| | interval which defines | | +| | the ceiling value of the | | +| | polling interval for | (per arch value) | +| | each vcpu. | | ++-----------------------+---------------------------+-------------------------+ +|halt_poll_ns_grow | The value by which the | 2 | +| | halt polling interval is | | +| | multiplied in the | | +| | grow_halt_poll_ns() | | +| | function. | | ++-----------------------+---------------------------+-------------------------+ +|halt_poll_ns_grow_start| The initial value to grow | 10000 | +| | to from zero in the | | +| | grow_halt_poll_ns() | | +| | function. | | ++-----------------------+---------------------------+-------------------------+ +|halt_poll_ns_shrink | The value by which the | 0 | +| | halt polling interval is | | +| | divided in the | | +| | shrink_halt_poll_ns() | | +| | function. | | ++-----------------------+---------------------------+-------------------------+ These module parameters can be set from the debugfs files in: @@ -117,20 +122,19 @@ Note: that these module parameters are system wide values and are not able to Further Notes ============= -- Care should be taken when setting the halt_poll_ns module parameter as a -large value has the potential to drive the cpu usage to 100% on a machine which -would be almost entirely idle otherwise. This is because even if a guest has -wakeups during which very little work is done and which are quite far apart, if -the period is shorter than the global max polling interval (halt_poll_ns) then -the host will always poll for the entire block time and thus cpu utilisation -will go to 100%. - -- Halt polling essentially presents a trade off between power usage and latency -and the module parameters should be used to tune the affinity for this. Idle -cpu time is essentially converted to host kernel time with the aim of decreasing -latency when entering the guest. - -- Halt polling will only be conducted by the host when no other tasks are -runnable on that cpu, otherwise the polling will cease immediately and -schedule will be invoked to allow that other task to run. Thus this doesn't -allow a guest to denial of service the cpu. +- Care should be taken when setting the halt_poll_ns module parameter as a large value + has the potential to drive the cpu usage to 100% on a machine which would be almost + entirely idle otherwise. This is because even if a guest has wakeups during which very + little work is done and which are quite far apart, if the period is shorter than the + global max polling interval (halt_poll_ns) then the host will always poll for the + entire block time and thus cpu utilisation will go to 100%. + +- Halt polling essentially presents a trade off between power usage and latency and + the module parameters should be used to tune the affinity for this. Idle cpu time is + essentially converted to host kernel time with the aim of decreasing latency when + entering the guest. + +- Halt polling will only be conducted by the host when no other tasks are runnable on + that cpu, otherwise the polling will cease immediately and schedule will be invoked to + allow that other task to run. Thus this doesn't allow a guest to denial of service the + cpu. diff --git a/Documentation/virt/kvm/hypercalls.txt b/Documentation/virt/kvm/hypercalls.rst index 5f6d291bd004..dbaf207e560d 100644 --- a/Documentation/virt/kvm/hypercalls.txt +++ b/Documentation/virt/kvm/hypercalls.rst @@ -1,5 +1,9 @@ -Linux KVM Hypercall: +.. SPDX-License-Identifier: GPL-2.0 + +=================== +Linux KVM Hypercall =================== + X86: KVM Hypercalls have a three-byte sequence of either the vmcall or the vmmcall instruction. The hypervisor can replace it with instructions that are @@ -20,7 +24,7 @@ S390: For further information on the S390 diagnose call as supported by KVM, refer to Documentation/virt/kvm/s390-diag.txt. - PowerPC: +PowerPC: It uses R3-R10 and hypercall number in R11. R4-R11 are used as output registers. Return value is placed in R3. @@ -34,7 +38,8 @@ MIPS: the return value is placed in $2 (v0). KVM Hypercalls Documentation -=========================== +============================ + The template for each hypercall is: 1. Hypercall name. 2. Architecture(s) @@ -43,56 +48,64 @@ The template for each hypercall is: 1. KVM_HC_VAPIC_POLL_IRQ ------------------------ -Architecture: x86 -Status: active -Purpose: Trigger guest exit so that the host can check for pending -interrupts on reentry. + +:Architecture: x86 +:Status: active +:Purpose: Trigger guest exit so that the host can check for pending + interrupts on reentry. 2. KVM_HC_MMU_OP ------------------------- -Architecture: x86 -Status: deprecated. -Purpose: Support MMU operations such as writing to PTE, -flushing TLB, release PT. +---------------- + +:Architecture: x86 +:Status: deprecated. +:Purpose: Support MMU operations such as writing to PTE, + flushing TLB, release PT. 3. KVM_HC_FEATURES ------------------------- -Architecture: PPC -Status: active -Purpose: Expose hypercall availability to the guest. On x86 platforms, cpuid -used to enumerate which hypercalls are available. On PPC, either device tree -based lookup ( which is also what EPAPR dictates) OR KVM specific enumeration -mechanism (which is this hypercall) can be used. +------------------ + +:Architecture: PPC +:Status: active +:Purpose: Expose hypercall availability to the guest. On x86 platforms, cpuid + used to enumerate which hypercalls are available. On PPC, either + device tree based lookup ( which is also what EPAPR dictates) + OR KVM specific enumeration mechanism (which is this hypercall) + can be used. 4. KVM_HC_PPC_MAP_MAGIC_PAGE ------------------------- -Architecture: PPC -Status: active -Purpose: To enable communication between the hypervisor and guest there is a -shared page that contains parts of supervisor visible register state. -The guest can map this shared page to access its supervisor register through -memory using this hypercall. +---------------------------- + +:Architecture: PPC +:Status: active +:Purpose: To enable communication between the hypervisor and guest there is a + shared page that contains parts of supervisor visible register state. + The guest can map this shared page to access its supervisor register + through memory using this hypercall. 5. KVM_HC_KICK_CPU ------------------------- -Architecture: x86 -Status: active -Purpose: Hypercall used to wakeup a vcpu from HLT state -Usage example : A vcpu of a paravirtualized guest that is busywaiting in guest -kernel mode for an event to occur (ex: a spinlock to become available) can -execute HLT instruction once it has busy-waited for more than a threshold -time-interval. Execution of HLT instruction would cause the hypervisor to put -the vcpu to sleep until occurrence of an appropriate event. Another vcpu of the -same guest can wakeup the sleeping vcpu by issuing KVM_HC_KICK_CPU hypercall, -specifying APIC ID (a1) of the vcpu to be woken up. An additional argument (a0) -is used in the hypercall for future use. +------------------ + +:Architecture: x86 +:Status: active +:Purpose: Hypercall used to wakeup a vcpu from HLT state +:Usage example: + A vcpu of a paravirtualized guest that is busywaiting in guest + kernel mode for an event to occur (ex: a spinlock to become available) can + execute HLT instruction once it has busy-waited for more than a threshold + time-interval. Execution of HLT instruction would cause the hypervisor to put + the vcpu to sleep until occurrence of an appropriate event. Another vcpu of the + same guest can wakeup the sleeping vcpu by issuing KVM_HC_KICK_CPU hypercall, + specifying APIC ID (a1) of the vcpu to be woken up. An additional argument (a0) + is used in the hypercall for future use. 6. KVM_HC_CLOCK_PAIRING ------------------------- -Architecture: x86 -Status: active -Purpose: Hypercall used to synchronize host and guest clocks. +----------------------- +:Architecture: x86 +:Status: active +:Purpose: Hypercall used to synchronize host and guest clocks. + Usage: a0: guest physical address where host copies @@ -101,6 +114,8 @@ a0: guest physical address where host copies a1: clock_type, ATM only KVM_CLOCK_PAIRING_WALLCLOCK (0) is supported (corresponding to the host's CLOCK_REALTIME clock). + :: + struct kvm_clock_pairing { __s64 sec; __s64 nsec; @@ -123,15 +138,16 @@ Returns KVM_EOPNOTSUPP if the host does not use TSC clocksource, or if clock type is different than KVM_CLOCK_PAIRING_WALLCLOCK. 6. KVM_HC_SEND_IPI ------------------------- -Architecture: x86 -Status: active -Purpose: Send IPIs to multiple vCPUs. +------------------ + +:Architecture: x86 +:Status: active +:Purpose: Send IPIs to multiple vCPUs. -a0: lower part of the bitmap of destination APIC IDs -a1: higher part of the bitmap of destination APIC IDs -a2: the lowest APIC ID in bitmap -a3: APIC ICR +- a0: lower part of the bitmap of destination APIC IDs +- a1: higher part of the bitmap of destination APIC IDs +- a2: the lowest APIC ID in bitmap +- a3: APIC ICR The hypercall lets a guest send multicast IPIs, with at most 128 128 destinations per hypercall in 64-bit mode and 64 vCPUs per @@ -143,12 +159,13 @@ corresponds to the APIC ID a2+1, and so on. Returns the number of CPUs to which the IPIs were delivered successfully. 7. KVM_HC_SCHED_YIELD ------------------------- -Architecture: x86 -Status: active -Purpose: Hypercall used to yield if the IPI target vCPU is preempted +--------------------- + +:Architecture: x86 +:Status: active +:Purpose: Hypercall used to yield if the IPI target vCPU is preempted a0: destination APIC ID -Usage example: When sending a call-function IPI-many to vCPUs, yield if -any of the IPI target vCPUs was preempted. +:Usage example: When sending a call-function IPI-many to vCPUs, yield if + any of the IPI target vCPUs was preempted. diff --git a/Documentation/virt/kvm/index.rst b/Documentation/virt/kvm/index.rst index ada224a511fe..774deaebf7fa 100644 --- a/Documentation/virt/kvm/index.rst +++ b/Documentation/virt/kvm/index.rst @@ -7,6 +7,22 @@ KVM .. toctree:: :maxdepth: 2 + api amd-memory-encryption cpuid + halt-polling + hypercalls + locking + mmu + msr + nested-vmx + ppc-pv + s390-diag + timekeeping vcpu-requests + + review-checklist + + arm/index + + devices/index diff --git a/Documentation/virt/kvm/locking.rst b/Documentation/virt/kvm/locking.rst new file mode 100644 index 000000000000..c02291beac3f --- /dev/null +++ b/Documentation/virt/kvm/locking.rst @@ -0,0 +1,243 @@ +.. SPDX-License-Identifier: GPL-2.0 + +================= +KVM Lock Overview +================= + +1. Acquisition Orders +--------------------- + +The acquisition orders for mutexes are as follows: + +- kvm->lock is taken outside vcpu->mutex + +- kvm->lock is taken outside kvm->slots_lock and kvm->irq_lock + +- kvm->slots_lock is taken outside kvm->irq_lock, though acquiring + them together is quite rare. + +On x86, vcpu->mutex is taken outside kvm->arch.hyperv.hv_lock. + +Everything else is a leaf: no other lock is taken inside the critical +sections. + +2. Exception +------------ + +Fast page fault: + +Fast page fault is the fast path which fixes the guest page fault out of +the mmu-lock on x86. Currently, the page fault can be fast in one of the +following two cases: + +1. Access Tracking: The SPTE is not present, but it is marked for access + tracking i.e. the SPTE_SPECIAL_MASK is set. That means we need to + restore the saved R/X bits. This is described in more detail later below. + +2. Write-Protection: The SPTE is present and the fault is + caused by write-protect. That means we just need to change the W bit of + the spte. + +What we use to avoid all the race is the SPTE_HOST_WRITEABLE bit and +SPTE_MMU_WRITEABLE bit on the spte: + +- SPTE_HOST_WRITEABLE means the gfn is writable on host. +- SPTE_MMU_WRITEABLE means the gfn is writable on mmu. The bit is set when + the gfn is writable on guest mmu and it is not write-protected by shadow + page write-protection. + +On fast page fault path, we will use cmpxchg to atomically set the spte W +bit if spte.SPTE_HOST_WRITEABLE = 1 and spte.SPTE_WRITE_PROTECT = 1, or +restore the saved R/X bits if VMX_EPT_TRACK_ACCESS mask is set, or both. This +is safe because whenever changing these bits can be detected by cmpxchg. + +But we need carefully check these cases: + +1) The mapping from gfn to pfn + +The mapping from gfn to pfn may be changed since we can only ensure the pfn +is not changed during cmpxchg. This is a ABA problem, for example, below case +will happen: + ++------------------------------------------------------------------------+ +| At the beginning:: | +| | +| gpte = gfn1 | +| gfn1 is mapped to pfn1 on host | +| spte is the shadow page table entry corresponding with gpte and | +| spte = pfn1 | ++------------------------------------------------------------------------+ +| On fast page fault path: | ++------------------------------------+-----------------------------------+ +| CPU 0: | CPU 1: | ++------------------------------------+-----------------------------------+ +| :: | | +| | | +| old_spte = *spte; | | ++------------------------------------+-----------------------------------+ +| | pfn1 is swapped out:: | +| | | +| | spte = 0; | +| | | +| | pfn1 is re-alloced for gfn2. | +| | | +| | gpte is changed to point to | +| | gfn2 by the guest:: | +| | | +| | spte = pfn1; | ++------------------------------------+-----------------------------------+ +| :: | +| | +| if (cmpxchg(spte, old_spte, old_spte+W) | +| mark_page_dirty(vcpu->kvm, gfn1) | +| OOPS!!! | ++------------------------------------------------------------------------+ + +We dirty-log for gfn1, that means gfn2 is lost in dirty-bitmap. + +For direct sp, we can easily avoid it since the spte of direct sp is fixed +to gfn. For indirect sp, before we do cmpxchg, we call gfn_to_pfn_atomic() +to pin gfn to pfn, because after gfn_to_pfn_atomic(): + +- We have held the refcount of pfn that means the pfn can not be freed and + be reused for another gfn. +- The pfn is writable that means it can not be shared between different gfns + by KSM. + +Then, we can ensure the dirty bitmaps is correctly set for a gfn. + +Currently, to simplify the whole things, we disable fast page fault for +indirect shadow page. + +2) Dirty bit tracking + +In the origin code, the spte can be fast updated (non-atomically) if the +spte is read-only and the Accessed bit has already been set since the +Accessed bit and Dirty bit can not be lost. + +But it is not true after fast page fault since the spte can be marked +writable between reading spte and updating spte. Like below case: + ++------------------------------------------------------------------------+ +| At the beginning:: | +| | +| spte.W = 0 | +| spte.Accessed = 1 | ++------------------------------------+-----------------------------------+ +| CPU 0: | CPU 1: | ++------------------------------------+-----------------------------------+ +| In mmu_spte_clear_track_bits():: | | +| | | +| old_spte = *spte; | | +| | | +| | | +| /* 'if' condition is satisfied. */| | +| if (old_spte.Accessed == 1 && | | +| old_spte.W == 0) | | +| spte = 0ull; | | ++------------------------------------+-----------------------------------+ +| | on fast page fault path:: | +| | | +| | spte.W = 1 | +| | | +| | memory write on the spte:: | +| | | +| | spte.Dirty = 1 | ++------------------------------------+-----------------------------------+ +| :: | | +| | | +| else | | +| old_spte = xchg(spte, 0ull) | | +| if (old_spte.Accessed == 1) | | +| kvm_set_pfn_accessed(spte.pfn);| | +| if (old_spte.Dirty == 1) | | +| kvm_set_pfn_dirty(spte.pfn); | | +| OOPS!!! | | ++------------------------------------+-----------------------------------+ + +The Dirty bit is lost in this case. + +In order to avoid this kind of issue, we always treat the spte as "volatile" +if it can be updated out of mmu-lock, see spte_has_volatile_bits(), it means, +the spte is always atomically updated in this case. + +3) flush tlbs due to spte updated + +If the spte is updated from writable to readonly, we should flush all TLBs, +otherwise rmap_write_protect will find a read-only spte, even though the +writable spte might be cached on a CPU's TLB. + +As mentioned before, the spte can be updated to writable out of mmu-lock on +fast page fault path, in order to easily audit the path, we see if TLBs need +be flushed caused by this reason in mmu_spte_update() since this is a common +function to update spte (present -> present). + +Since the spte is "volatile" if it can be updated out of mmu-lock, we always +atomically update the spte, the race caused by fast page fault can be avoided, +See the comments in spte_has_volatile_bits() and mmu_spte_update(). + +Lockless Access Tracking: + +This is used for Intel CPUs that are using EPT but do not support the EPT A/D +bits. In this case, when the KVM MMU notifier is called to track accesses to a +page (via kvm_mmu_notifier_clear_flush_young), it marks the PTE as not-present +by clearing the RWX bits in the PTE and storing the original R & X bits in +some unused/ignored bits. In addition, the SPTE_SPECIAL_MASK is also set on the +PTE (using the ignored bit 62). When the VM tries to access the page later on, +a fault is generated and the fast page fault mechanism described above is used +to atomically restore the PTE to a Present state. The W bit is not saved when +the PTE is marked for access tracking and during restoration to the Present +state, the W bit is set depending on whether or not it was a write access. If +it wasn't, then the W bit will remain clear until a write access happens, at +which time it will be set using the Dirty tracking mechanism described above. + +3. Reference +------------ + +:Name: kvm_lock +:Type: mutex +:Arch: any +:Protects: - vm_list + +:Name: kvm_count_lock +:Type: raw_spinlock_t +:Arch: any +:Protects: - hardware virtualization enable/disable +:Comment: 'raw' because hardware enabling/disabling must be atomic /wrt + migration. + +:Name: kvm_arch::tsc_write_lock +:Type: raw_spinlock +:Arch: x86 +:Protects: - kvm_arch::{last_tsc_write,last_tsc_nsec,last_tsc_offset} + - tsc offset in vmcb +:Comment: 'raw' because updating the tsc offsets must not be preempted. + +:Name: kvm->mmu_lock +:Type: spinlock_t +:Arch: any +:Protects: -shadow page/shadow tlb entry +:Comment: it is a spinlock since it is used in mmu notifier. + +:Name: kvm->srcu +:Type: srcu lock +:Arch: any +:Protects: - kvm->memslots + - kvm->buses +:Comment: The srcu read lock must be held while accessing memslots (e.g. + when using gfn_to_* functions) and while accessing in-kernel + MMIO/PIO address->device structure mapping (kvm->buses). + The srcu index can be stored in kvm_vcpu->srcu_idx per vcpu + if it is needed by multiple functions. + +:Name: blocked_vcpu_on_cpu_lock +:Type: spinlock_t +:Arch: x86 +:Protects: blocked_vcpu_on_cpu +:Comment: This is a per-CPU lock and it is used for VT-d posted-interrupts. + When VT-d posted-interrupts is supported and the VM has assigned + devices, we put the blocked vCPU on the list blocked_vcpu_on_cpu + protected by blocked_vcpu_on_cpu_lock, when VT-d hardware issues + wakeup notification event since external interrupts from the + assigned devices happens, we will find the vCPU on the list to + wakeup. diff --git a/Documentation/virt/kvm/locking.txt b/Documentation/virt/kvm/locking.txt deleted file mode 100644 index 635cd6eaf714..000000000000 --- a/Documentation/virt/kvm/locking.txt +++ /dev/null @@ -1,215 +0,0 @@ -KVM Lock Overview -================= - -1. Acquisition Orders ---------------------- - -The acquisition orders for mutexes are as follows: - -- kvm->lock is taken outside vcpu->mutex - -- kvm->lock is taken outside kvm->slots_lock and kvm->irq_lock - -- kvm->slots_lock is taken outside kvm->irq_lock, though acquiring - them together is quite rare. - -On x86, vcpu->mutex is taken outside kvm->arch.hyperv.hv_lock. - -Everything else is a leaf: no other lock is taken inside the critical -sections. - -2: Exception ------------- - -Fast page fault: - -Fast page fault is the fast path which fixes the guest page fault out of -the mmu-lock on x86. Currently, the page fault can be fast in one of the -following two cases: - -1. Access Tracking: The SPTE is not present, but it is marked for access -tracking i.e. the SPTE_SPECIAL_MASK is set. That means we need to -restore the saved R/X bits. This is described in more detail later below. - -2. Write-Protection: The SPTE is present and the fault is -caused by write-protect. That means we just need to change the W bit of the -spte. - -What we use to avoid all the race is the SPTE_HOST_WRITEABLE bit and -SPTE_MMU_WRITEABLE bit on the spte: -- SPTE_HOST_WRITEABLE means the gfn is writable on host. -- SPTE_MMU_WRITEABLE means the gfn is writable on mmu. The bit is set when - the gfn is writable on guest mmu and it is not write-protected by shadow - page write-protection. - -On fast page fault path, we will use cmpxchg to atomically set the spte W -bit if spte.SPTE_HOST_WRITEABLE = 1 and spte.SPTE_WRITE_PROTECT = 1, or -restore the saved R/X bits if VMX_EPT_TRACK_ACCESS mask is set, or both. This -is safe because whenever changing these bits can be detected by cmpxchg. - -But we need carefully check these cases: -1): The mapping from gfn to pfn -The mapping from gfn to pfn may be changed since we can only ensure the pfn -is not changed during cmpxchg. This is a ABA problem, for example, below case -will happen: - -At the beginning: -gpte = gfn1 -gfn1 is mapped to pfn1 on host -spte is the shadow page table entry corresponding with gpte and -spte = pfn1 - - VCPU 0 VCPU0 -on fast page fault path: - - old_spte = *spte; - pfn1 is swapped out: - spte = 0; - - pfn1 is re-alloced for gfn2. - - gpte is changed to point to - gfn2 by the guest: - spte = pfn1; - - if (cmpxchg(spte, old_spte, old_spte+W) - mark_page_dirty(vcpu->kvm, gfn1) - OOPS!!! - -We dirty-log for gfn1, that means gfn2 is lost in dirty-bitmap. - -For direct sp, we can easily avoid it since the spte of direct sp is fixed -to gfn. For indirect sp, before we do cmpxchg, we call gfn_to_pfn_atomic() -to pin gfn to pfn, because after gfn_to_pfn_atomic(): -- We have held the refcount of pfn that means the pfn can not be freed and - be reused for another gfn. -- The pfn is writable that means it can not be shared between different gfns - by KSM. - -Then, we can ensure the dirty bitmaps is correctly set for a gfn. - -Currently, to simplify the whole things, we disable fast page fault for -indirect shadow page. - -2): Dirty bit tracking -In the origin code, the spte can be fast updated (non-atomically) if the -spte is read-only and the Accessed bit has already been set since the -Accessed bit and Dirty bit can not be lost. - -But it is not true after fast page fault since the spte can be marked -writable between reading spte and updating spte. Like below case: - -At the beginning: -spte.W = 0 -spte.Accessed = 1 - - VCPU 0 VCPU0 -In mmu_spte_clear_track_bits(): - - old_spte = *spte; - - /* 'if' condition is satisfied. */ - if (old_spte.Accessed == 1 && - old_spte.W == 0) - spte = 0ull; - on fast page fault path: - spte.W = 1 - memory write on the spte: - spte.Dirty = 1 - - - else - old_spte = xchg(spte, 0ull) - - - if (old_spte.Accessed == 1) - kvm_set_pfn_accessed(spte.pfn); - if (old_spte.Dirty == 1) - kvm_set_pfn_dirty(spte.pfn); - OOPS!!! - -The Dirty bit is lost in this case. - -In order to avoid this kind of issue, we always treat the spte as "volatile" -if it can be updated out of mmu-lock, see spte_has_volatile_bits(), it means, -the spte is always atomically updated in this case. - -3): flush tlbs due to spte updated -If the spte is updated from writable to readonly, we should flush all TLBs, -otherwise rmap_write_protect will find a read-only spte, even though the -writable spte might be cached on a CPU's TLB. - -As mentioned before, the spte can be updated to writable out of mmu-lock on -fast page fault path, in order to easily audit the path, we see if TLBs need -be flushed caused by this reason in mmu_spte_update() since this is a common -function to update spte (present -> present). - -Since the spte is "volatile" if it can be updated out of mmu-lock, we always -atomically update the spte, the race caused by fast page fault can be avoided, -See the comments in spte_has_volatile_bits() and mmu_spte_update(). - -Lockless Access Tracking: - -This is used for Intel CPUs that are using EPT but do not support the EPT A/D -bits. In this case, when the KVM MMU notifier is called to track accesses to a -page (via kvm_mmu_notifier_clear_flush_young), it marks the PTE as not-present -by clearing the RWX bits in the PTE and storing the original R & X bits in -some unused/ignored bits. In addition, the SPTE_SPECIAL_MASK is also set on the -PTE (using the ignored bit 62). When the VM tries to access the page later on, -a fault is generated and the fast page fault mechanism described above is used -to atomically restore the PTE to a Present state. The W bit is not saved when -the PTE is marked for access tracking and during restoration to the Present -state, the W bit is set depending on whether or not it was a write access. If -it wasn't, then the W bit will remain clear until a write access happens, at -which time it will be set using the Dirty tracking mechanism described above. - -3. Reference ------------- - -Name: kvm_lock -Type: mutex -Arch: any -Protects: - vm_list - -Name: kvm_count_lock -Type: raw_spinlock_t -Arch: any -Protects: - hardware virtualization enable/disable -Comment: 'raw' because hardware enabling/disabling must be atomic /wrt - migration. - -Name: kvm_arch::tsc_write_lock -Type: raw_spinlock -Arch: x86 -Protects: - kvm_arch::{last_tsc_write,last_tsc_nsec,last_tsc_offset} - - tsc offset in vmcb -Comment: 'raw' because updating the tsc offsets must not be preempted. - -Name: kvm->mmu_lock -Type: spinlock_t -Arch: any -Protects: -shadow page/shadow tlb entry -Comment: it is a spinlock since it is used in mmu notifier. - -Name: kvm->srcu -Type: srcu lock -Arch: any -Protects: - kvm->memslots - - kvm->buses -Comment: The srcu read lock must be held while accessing memslots (e.g. - when using gfn_to_* functions) and while accessing in-kernel - MMIO/PIO address->device structure mapping (kvm->buses). - The srcu index can be stored in kvm_vcpu->srcu_idx per vcpu - if it is needed by multiple functions. - -Name: blocked_vcpu_on_cpu_lock -Type: spinlock_t -Arch: x86 -Protects: blocked_vcpu_on_cpu -Comment: This is a per-CPU lock and it is used for VT-d posted-interrupts. - When VT-d posted-interrupts is supported and the VM has assigned - devices, we put the blocked vCPU on the list blocked_vcpu_on_cpu - protected by blocked_vcpu_on_cpu_lock, when VT-d hardware issues - wakeup notification event since external interrupts from the - assigned devices happens, we will find the vCPU on the list to - wakeup. diff --git a/Documentation/virt/kvm/mmu.txt b/Documentation/virt/kvm/mmu.rst index dadb29e8738f..60981887d20b 100644 --- a/Documentation/virt/kvm/mmu.txt +++ b/Documentation/virt/kvm/mmu.rst @@ -1,3 +1,6 @@ +.. SPDX-License-Identifier: GPL-2.0 + +====================== The x86 kvm shadow mmu ====================== @@ -7,27 +10,37 @@ physical addresses to host physical addresses. The mmu code attempts to satisfy the following requirements: -- correctness: the guest should not be able to determine that it is running +- correctness: + the guest should not be able to determine that it is running on an emulated mmu except for timing (we attempt to comply with the specification, not emulate the characteristics of a particular implementation such as tlb size) -- security: the guest must not be able to touch host memory not assigned +- security: + the guest must not be able to touch host memory not assigned to it -- performance: minimize the performance penalty imposed by the mmu -- scaling: need to scale to large memory and large vcpu guests -- hardware: support the full range of x86 virtualization hardware -- integration: Linux memory management code must be in control of guest memory +- performance: + minimize the performance penalty imposed by the mmu +- scaling: + need to scale to large memory and large vcpu guests +- hardware: + support the full range of x86 virtualization hardware +- integration: + Linux memory management code must be in control of guest memory so that swapping, page migration, page merging, transparent hugepages, and similar features work without change -- dirty tracking: report writes to guest memory to enable live migration +- dirty tracking: + report writes to guest memory to enable live migration and framebuffer-based displays -- footprint: keep the amount of pinned kernel memory low (most memory +- footprint: + keep the amount of pinned kernel memory low (most memory should be shrinkable) -- reliability: avoid multipage or GFP_ATOMIC allocations +- reliability: + avoid multipage or GFP_ATOMIC allocations Acronyms ======== +==== ==================================================================== pfn host page frame number hpa host physical address hva host virtual address @@ -41,6 +54,7 @@ pte page table entry (used also to refer generically to paging structure gpte guest pte (referring to gfns) spte shadow pte (referring to pfns) tdp two dimensional paging (vendor neutral term for NPT and EPT) +==== ==================================================================== Virtual and real hardware supported =================================== @@ -90,11 +104,13 @@ Events The mmu is driven by events, some from the guest, some from the host. Guest generated events: + - writes to control registers (especially cr3) - invlpg/invlpga instruction execution - access to missing or protected translations Host generated events: + - changes in the gpa->hpa translation (either through gpa->hva changes or through hva->hpa changes) - memory pressure (the shrinker) @@ -117,16 +133,19 @@ Leaf ptes point at guest pages. The following table shows translations encoded by leaf ptes, with higher-level translations in parentheses: - Non-nested guests: + Non-nested guests:: + nonpaging: gpa->hpa paging: gva->gpa->hpa paging, tdp: (gva->)gpa->hpa - Nested guests: + + Nested guests:: + non-tdp: ngva->gpa->hpa (*) tdp: (ngva->)ngpa->gpa->hpa -(*) the guest hypervisor will encode the ngva->gpa translation into its page - tables if npt is not present + (*) the guest hypervisor will encode the ngva->gpa translation into its page + tables if npt is not present Shadow pages contain the following information: role.level: @@ -291,28 +310,41 @@ Handling a page fault is performed as follows: - if the RSV bit of the error code is set, the page fault is caused by guest accessing MMIO and cached MMIO information is available. + - walk shadow page table - check for valid generation number in the spte (see "Fast invalidation of MMIO sptes" below) - cache the information to vcpu->arch.mmio_gva, vcpu->arch.mmio_access and vcpu->arch.mmio_gfn, and call the emulator + - If both P bit and R/W bit of error code are set, this could possibly be handled as a "fast page fault" (fixed without taking the MMU lock). See the description in Documentation/virt/kvm/locking.txt. + - if needed, walk the guest page tables to determine the guest translation (gva->gpa or ngpa->gpa) + - if permissions are insufficient, reflect the fault back to the guest + - determine the host page + - if this is an mmio request, there is no host page; cache the info to vcpu->arch.mmio_gva, vcpu->arch.mmio_access and vcpu->arch.mmio_gfn + - walk the shadow page table to find the spte for the translation, instantiating missing intermediate page tables as necessary + - If this is an mmio request, cache the mmio info to the spte and set some reserved bit on the spte (see callers of kvm_mmu_set_mmio_spte_mask) + - try to unsynchronize the page + - if successful, we can let the guest continue and modify the gpte + - emulate the instruction + - if failed, unshadow the page and let the guest continue + - update any translations that were modified by the instruction invlpg handling: @@ -324,10 +356,12 @@ invlpg handling: Guest control register updates: - mov to cr3 + - look up new shadow roots - synchronize newly reachable shadow pages - mov to cr0/cr4/efer + - set up mmu context for new paging mode - look up new shadow roots - synchronize newly reachable shadow pages @@ -358,6 +392,7 @@ on fault type: (user write faults generate a #PF) In the first case there are two additional complications: + - if CR4.SMEP is enabled: since we've turned the page into a kernel page, the kernel may now execute it. We handle this by also setting spte.nx. If we get a user fetch or read fault, we'll change spte.u=1 and @@ -446,4 +481,3 @@ Further reading - NPT presentation from KVM Forum 2008 http://www.linux-kvm.org/images/c/c8/KvmForum2008%24kdf2008_21.pdf - diff --git a/Documentation/virt/kvm/msr.txt b/Documentation/virt/kvm/msr.rst index df1f4338b3ca..33892036672d 100644 --- a/Documentation/virt/kvm/msr.txt +++ b/Documentation/virt/kvm/msr.rst @@ -1,6 +1,10 @@ -KVM-specific MSRs. -Glauber Costa <glommer@redhat.com>, Red Hat Inc, 2010 -===================================================== +.. SPDX-License-Identifier: GPL-2.0 + +================= +KVM-specific MSRs +================= + +:Author: Glauber Costa <glommer@redhat.com>, Red Hat Inc, 2010 KVM makes use of some custom MSRs to service some requests. @@ -9,34 +13,39 @@ Custom MSRs have a range reserved for them, that goes from but they are deprecated and their use is discouraged. Custom MSR list --------- +--------------- The current supported Custom MSR list is: -MSR_KVM_WALL_CLOCK_NEW: 0x4b564d00 +MSR_KVM_WALL_CLOCK_NEW: + 0x4b564d00 - data: 4-byte alignment physical address of a memory area which must be +data: + 4-byte alignment physical address of a memory area which must be in guest RAM. This memory is expected to hold a copy of the following - structure: + structure:: - struct pvclock_wall_clock { + struct pvclock_wall_clock { u32 version; u32 sec; u32 nsec; - } __attribute__((__packed__)); + } __attribute__((__packed__)); whose data will be filled in by the hypervisor. The hypervisor is only guaranteed to update this data at the moment of MSR write. Users that want to reliably query this information more than once have to write more than once to this MSR. Fields have the following meanings: - version: guest has to check version before and after grabbing + version: + guest has to check version before and after grabbing time information and check that they are both equal and even. An odd version indicates an in-progress update. - sec: number of seconds for wallclock at time of boot. + sec: + number of seconds for wallclock at time of boot. - nsec: number of nanoseconds for wallclock at time of boot. + nsec: + number of nanoseconds for wallclock at time of boot. In order to get the current wallclock time, the system_time from MSR_KVM_SYSTEM_TIME_NEW needs to be added. @@ -47,13 +56,15 @@ MSR_KVM_WALL_CLOCK_NEW: 0x4b564d00 Availability of this MSR must be checked via bit 3 in 0x4000001 cpuid leaf prior to usage. -MSR_KVM_SYSTEM_TIME_NEW: 0x4b564d01 +MSR_KVM_SYSTEM_TIME_NEW: + 0x4b564d01 - data: 4-byte aligned physical address of a memory area which must be in +data: + 4-byte aligned physical address of a memory area which must be in guest RAM, plus an enable bit in bit 0. This memory is expected to hold - a copy of the following structure: + a copy of the following structure:: - struct pvclock_vcpu_time_info { + struct pvclock_vcpu_time_info { u32 version; u32 pad0; u64 tsc_timestamp; @@ -62,7 +73,7 @@ MSR_KVM_SYSTEM_TIME_NEW: 0x4b564d01 s8 tsc_shift; u8 flags; u8 pad[2]; - } __attribute__((__packed__)); /* 32 bytes */ + } __attribute__((__packed__)); /* 32 bytes */ whose data will be filled in by the hypervisor periodically. Only one write, or registration, is needed for each VCPU. The interval between @@ -72,23 +83,28 @@ MSR_KVM_SYSTEM_TIME_NEW: 0x4b564d01 Fields have the following meanings: - version: guest has to check version before and after grabbing + version: + guest has to check version before and after grabbing time information and check that they are both equal and even. An odd version indicates an in-progress update. - tsc_timestamp: the tsc value at the current VCPU at the time + tsc_timestamp: + the tsc value at the current VCPU at the time of the update of this structure. Guests can subtract this value from current tsc to derive a notion of elapsed time since the structure update. - system_time: a host notion of monotonic time, including sleep + system_time: + a host notion of monotonic time, including sleep time at the time this structure was last updated. Unit is nanoseconds. - tsc_to_system_mul: multiplier to be used when converting + tsc_to_system_mul: + multiplier to be used when converting tsc-related quantity to nanoseconds - tsc_shift: shift to be used when converting tsc-related + tsc_shift: + shift to be used when converting tsc-related quantity to nanoseconds. This shift will ensure that multiplication with tsc_to_system_mul does not overflow. A positive value denotes a left shift, a negative value @@ -96,7 +112,7 @@ MSR_KVM_SYSTEM_TIME_NEW: 0x4b564d01 The conversion from tsc to nanoseconds involves an additional right shift by 32 bits. With this information, guests can - derive per-CPU time by doing: + derive per-CPU time by doing:: time = (current_tsc - tsc_timestamp) if (tsc_shift >= 0) @@ -106,29 +122,34 @@ MSR_KVM_SYSTEM_TIME_NEW: 0x4b564d01 time = (time * tsc_to_system_mul) >> 32 time = time + system_time - flags: bits in this field indicate extended capabilities + flags: + bits in this field indicate extended capabilities coordinated between the guest and the hypervisor. Availability of specific flags has to be checked in 0x40000001 cpuid leaf. Current flags are: - flag bit | cpuid bit | meaning - ------------------------------------------------------------- - | | time measures taken across - 0 | 24 | multiple cpus are guaranteed to - | | be monotonic - ------------------------------------------------------------- - | | guest vcpu has been paused by - 1 | N/A | the host - | | See 4.70 in api.txt - ------------------------------------------------------------- + + +-----------+--------------+----------------------------------+ + | flag bit | cpuid bit | meaning | + +-----------+--------------+----------------------------------+ + | | | time measures taken across | + | 0 | 24 | multiple cpus are guaranteed to | + | | | be monotonic | + +-----------+--------------+----------------------------------+ + | | | guest vcpu has been paused by | + | 1 | N/A | the host | + | | | See 4.70 in api.txt | + +-----------+--------------+----------------------------------+ Availability of this MSR must be checked via bit 3 in 0x4000001 cpuid leaf prior to usage. -MSR_KVM_WALL_CLOCK: 0x11 +MSR_KVM_WALL_CLOCK: + 0x11 - data and functioning: same as MSR_KVM_WALL_CLOCK_NEW. Use that instead. +data and functioning: + same as MSR_KVM_WALL_CLOCK_NEW. Use that instead. This MSR falls outside the reserved KVM range and may be removed in the future. Its usage is deprecated. @@ -136,9 +157,11 @@ MSR_KVM_WALL_CLOCK: 0x11 Availability of this MSR must be checked via bit 0 in 0x4000001 cpuid leaf prior to usage. -MSR_KVM_SYSTEM_TIME: 0x12 +MSR_KVM_SYSTEM_TIME: + 0x12 - data and functioning: same as MSR_KVM_SYSTEM_TIME_NEW. Use that instead. +data and functioning: + same as MSR_KVM_SYSTEM_TIME_NEW. Use that instead. This MSR falls outside the reserved KVM range and may be removed in the future. Its usage is deprecated. @@ -146,7 +169,7 @@ MSR_KVM_SYSTEM_TIME: 0x12 Availability of this MSR must be checked via bit 0 in 0x4000001 cpuid leaf prior to usage. - The suggested algorithm for detecting kvmclock presence is then: + The suggested algorithm for detecting kvmclock presence is then:: if (!kvm_para_available()) /* refer to cpuid.txt */ return NON_PRESENT; @@ -163,8 +186,11 @@ MSR_KVM_SYSTEM_TIME: 0x12 } else return NON_PRESENT; -MSR_KVM_ASYNC_PF_EN: 0x4b564d02 - data: Bits 63-6 hold 64-byte aligned physical address of a +MSR_KVM_ASYNC_PF_EN: + 0x4b564d02 + +data: + Bits 63-6 hold 64-byte aligned physical address of a 64 byte memory area which must be in guest RAM and must be zeroed. Bits 5-3 are reserved and should be zero. Bit 0 is 1 when asynchronous page faults are enabled on the vcpu 0 when @@ -200,20 +226,22 @@ MSR_KVM_ASYNC_PF_EN: 0x4b564d02 Currently type 2 APF will be always delivered on the same vcpu as type 1 was, but guest should not rely on that. -MSR_KVM_STEAL_TIME: 0x4b564d03 +MSR_KVM_STEAL_TIME: + 0x4b564d03 - data: 64-byte alignment physical address of a memory area which must be +data: + 64-byte alignment physical address of a memory area which must be in guest RAM, plus an enable bit in bit 0. This memory is expected to - hold a copy of the following structure: + hold a copy of the following structure:: - struct kvm_steal_time { + struct kvm_steal_time { __u64 steal; __u32 version; __u32 flags; __u8 preempted; __u8 u8_pad[3]; __u32 pad[11]; - } + } whose data will be filled in by the hypervisor periodically. Only one write, or registration, is needed for each VCPU. The interval between @@ -224,25 +252,32 @@ MSR_KVM_STEAL_TIME: 0x4b564d03 Fields have the following meanings: - version: a sequence counter. In other words, guest has to check + version: + a sequence counter. In other words, guest has to check this field before and after grabbing time information and make sure they are both equal and even. An odd version indicates an in-progress update. - flags: At this point, always zero. May be used to indicate + flags: + At this point, always zero. May be used to indicate changes in this structure in the future. - steal: the amount of time in which this vCPU did not run, in + steal: + the amount of time in which this vCPU did not run, in nanoseconds. Time during which the vcpu is idle, will not be reported as steal time. - preempted: indicate the vCPU who owns this struct is running or + preempted: + indicate the vCPU who owns this struct is running or not. Non-zero values mean the vCPU has been preempted. Zero means the vCPU is not preempted. NOTE, it is always zero if the the hypervisor doesn't support this field. -MSR_KVM_EOI_EN: 0x4b564d04 - data: Bit 0 is 1 when PV end of interrupt is enabled on the vcpu; 0 +MSR_KVM_EOI_EN: + 0x4b564d04 + +data: + Bit 0 is 1 when PV end of interrupt is enabled on the vcpu; 0 when disabled. Bit 1 is reserved and must be zero. When PV end of interrupt is enabled (bit 0 set), bits 63-2 hold a 4-byte aligned physical address of a 4 byte memory area which must be in guest RAM and @@ -274,11 +309,13 @@ MSR_KVM_EOI_EN: 0x4b564d04 clear it using a single CPU instruction, such as test and clear, or compare and exchange. -MSR_KVM_POLL_CONTROL: 0x4b564d05 +MSR_KVM_POLL_CONTROL: + 0x4b564d05 + Control host-side polling. - data: Bit 0 enables (1) or disables (0) host-side HLT polling logic. +data: + Bit 0 enables (1) or disables (0) host-side HLT polling logic. KVM guests can request the host not to poll on HLT, for example if they are performing polling themselves. - diff --git a/Documentation/virt/kvm/nested-vmx.txt b/Documentation/virt/kvm/nested-vmx.rst index 97eb1353e962..592b0ab6970b 100644 --- a/Documentation/virt/kvm/nested-vmx.txt +++ b/Documentation/virt/kvm/nested-vmx.rst @@ -1,3 +1,6 @@ +.. SPDX-License-Identifier: GPL-2.0 + +========== Nested VMX ========== @@ -41,9 +44,9 @@ No modifications are required to user space (qemu). However, qemu's default emulated CPU type (qemu64) does not list the "VMX" CPU feature, so it must be explicitly enabled, by giving qemu one of the following options: - -cpu host (emulated CPU has all features of the real CPU) + - cpu host (emulated CPU has all features of the real CPU) - -cpu qemu64,+vmx (add just the vmx feature to a named CPU type) + - cpu qemu64,+vmx (add just the vmx feature to a named CPU type) ABIs @@ -75,6 +78,8 @@ of this structure changes, this can break live migration across KVM versions. VMCS12_REVISION (from vmx.c) should be changed if struct vmcs12 or its inner struct shadow_vmcs is ever changed. +:: + typedef u64 natural_width; struct __packed vmcs12 { /* According to the Intel spec, a VMCS region must start with @@ -220,21 +225,21 @@ Authors ------- These patches were written by: - Abel Gordon, abelg <at> il.ibm.com - Nadav Har'El, nyh <at> il.ibm.com - Orit Wasserman, oritw <at> il.ibm.com - Ben-Ami Yassor, benami <at> il.ibm.com - Muli Ben-Yehuda, muli <at> il.ibm.com + - Abel Gordon, abelg <at> il.ibm.com + - Nadav Har'El, nyh <at> il.ibm.com + - Orit Wasserman, oritw <at> il.ibm.com + - Ben-Ami Yassor, benami <at> il.ibm.com + - Muli Ben-Yehuda, muli <at> il.ibm.com With contributions by: - Anthony Liguori, aliguori <at> us.ibm.com - Mike Day, mdday <at> us.ibm.com - Michael Factor, factor <at> il.ibm.com - Zvi Dubitzky, dubi <at> il.ibm.com + - Anthony Liguori, aliguori <at> us.ibm.com + - Mike Day, mdday <at> us.ibm.com + - Michael Factor, factor <at> il.ibm.com + - Zvi Dubitzky, dubi <at> il.ibm.com And valuable reviews by: - Avi Kivity, avi <at> redhat.com - Gleb Natapov, gleb <at> redhat.com - Marcelo Tosatti, mtosatti <at> redhat.com - Kevin Tian, kevin.tian <at> intel.com - and others. + - Avi Kivity, avi <at> redhat.com + - Gleb Natapov, gleb <at> redhat.com + - Marcelo Tosatti, mtosatti <at> redhat.com + - Kevin Tian, kevin.tian <at> intel.com + - and others. diff --git a/Documentation/virt/kvm/ppc-pv.txt b/Documentation/virt/kvm/ppc-pv.rst index e26115ce4258..5fdb907670be 100644 --- a/Documentation/virt/kvm/ppc-pv.txt +++ b/Documentation/virt/kvm/ppc-pv.rst @@ -1,3 +1,6 @@ +.. SPDX-License-Identifier: GPL-2.0 + +================================= The PPC KVM paravirtual interface ================================= @@ -34,8 +37,9 @@ up the hypercall. To call a hypercall, just call these instructions. The parameters are as follows: + ======== ================ ================ Register IN OUT - + ======== ================ ================ r0 - volatile r3 1st parameter Return code r4 2nd parameter 1st output value @@ -47,6 +51,7 @@ The parameters are as follows: r10 8th parameter 7th output value r11 hypercall number 8th output value r12 - volatile + ======== ================ ================ Hypercall definitions are shared in generic code, so the same hypercall numbers apply for x86 and powerpc alike with the exception that each KVM hypercall @@ -54,11 +59,13 @@ also needs to be ORed with the KVM vendor code which is (42 << 16). Return codes can be as follows: + ==== ========================= Code Meaning - + ==== ========================= 0 Success 12 Hypercall not implemented <0 Error + ==== ========================= The magic page ============== @@ -72,7 +79,7 @@ desired location. The first parameter indicates the effective address when the MMU is enabled. The second parameter indicates the address in real mode, if applicable to the target. For now, we always map the page to -4096. This way we can access it using absolute load and store functions. The following -instruction reads the first field of the magic page: +instruction reads the first field of the magic page:: ld rX, -4096(0) @@ -93,8 +100,10 @@ a bitmap of available features inside the magic page. The following enhancements to the magic page are currently available: + ============================ ======================================= KVM_MAGIC_FEAT_SR Maps SR registers r/w in the magic page KVM_MAGIC_FEAT_MAS0_TO_SPRG7 Maps MASn, ESR, PIR and high SPRGs + ============================ ======================================= For enhanced features in the magic page, please check for the existence of the feature before using them! @@ -121,8 +130,8 @@ when entering the guest or don't have any impact on the hypervisor's behavior. The following bits are safe to be set inside the guest: - MSR_EE - MSR_RI + - MSR_EE + - MSR_RI If any other bit changes in the MSR, please still use mtmsr(d). @@ -138,9 +147,9 @@ guest. Implementing any of those mappings is optional, as the instruction traps also act on the shared page. So calling privileged instructions still works as before. +======================= ================================ From To -==== == - +======================= ================================ mfmsr rX ld rX, magic_page->msr mfsprg rX, 0 ld rX, magic_page->sprg0 mfsprg rX, 1 ld rX, magic_page->sprg1 @@ -173,7 +182,7 @@ mtsrin rX, rY b <special mtsrin section> [BookE only] wrteei [0|1] b <special wrteei section> - +======================= ================================ Some instructions require more logic to determine what's going on than a load or store instruction can deliver. To enable patching of those, we keep some @@ -191,6 +200,7 @@ for example. Hypercall ABIs in KVM on PowerPC ================================= + 1) KVM hypercalls (ePAPR) These are ePAPR compliant hypercall implementation (mentioned above). Even diff --git a/Documentation/virt/kvm/review-checklist.txt b/Documentation/virt/kvm/review-checklist.rst index 499af499e296..1f86a9d3f705 100644 --- a/Documentation/virt/kvm/review-checklist.txt +++ b/Documentation/virt/kvm/review-checklist.rst @@ -1,3 +1,6 @@ +.. SPDX-License-Identifier: GPL-2.0 + +================================ Review checklist for kvm patches ================================ diff --git a/Documentation/virt/kvm/s390-diag.txt b/Documentation/virt/kvm/s390-diag.rst index 7c52e5f8b210..eaac4864d3d6 100644 --- a/Documentation/virt/kvm/s390-diag.txt +++ b/Documentation/virt/kvm/s390-diag.rst @@ -1,3 +1,6 @@ +.. SPDX-License-Identifier: GPL-2.0 + +============================= The s390 DIAGNOSE call on KVM ============================= @@ -16,12 +19,12 @@ DIAGNOSE calls by the guest cause a mandatory intercept. This implies all supported DIAGNOSE calls need to be handled by either KVM or its userspace. -All DIAGNOSE calls supported by KVM use the RS-a format: +All DIAGNOSE calls supported by KVM use the RS-a format:: --------------------------------------- -| '83' | R1 | R3 | B2 | D2 | --------------------------------------- -0 8 12 16 20 31 + -------------------------------------- + | '83' | R1 | R3 | B2 | D2 | + -------------------------------------- + 0 8 12 16 20 31 The second-operand address (obtained by the base/displacement calculation) is not used to address data. Instead, bits 48-63 of this address specify diff --git a/Documentation/virt/kvm/timekeeping.txt b/Documentation/virt/kvm/timekeeping.rst index 76808a17ad84..21ae7efa29ba 100644 --- a/Documentation/virt/kvm/timekeeping.txt +++ b/Documentation/virt/kvm/timekeeping.rst @@ -1,17 +1,21 @@ +.. SPDX-License-Identifier: GPL-2.0 - Timekeeping Virtualization for X86-Based Architectures +====================================================== +Timekeeping Virtualization for X86-Based Architectures +====================================================== - Zachary Amsden <zamsden@redhat.com> - Copyright (c) 2010, Red Hat. All rights reserved. +:Author: Zachary Amsden <zamsden@redhat.com> +:Copyright: (c) 2010, Red Hat. All rights reserved. -1) Overview -2) Timing Devices -3) TSC Hardware -4) Virtualization Problems +.. Contents -========================================================================= + 1) Overview + 2) Timing Devices + 3) TSC Hardware + 4) Virtualization Problems -1) Overview +1. Overview +=========== One of the most complicated parts of the X86 platform, and specifically, the virtualization of this platform is the plethora of timing devices available @@ -27,15 +31,15 @@ The purpose of this document is to collect data and information relevant to timekeeping which may be difficult to find elsewhere, specifically, information relevant to KVM and hardware-based virtualization. -========================================================================= - -2) Timing Devices +2. Timing Devices +================= First we discuss the basic hardware devices available. TSC and the related KVM clock are special enough to warrant a full exposition and are described in the following section. -2.1) i8254 - PIT +2.1. i8254 - PIT +---------------- One of the first timer devices available is the programmable interrupt timer, or PIT. The PIT has a fixed frequency 1.193182 MHz base clock and three @@ -50,13 +54,13 @@ The PIT uses I/O ports 0x40 - 0x43. Access to the 16-bit counters is done using single or multiple byte access to the I/O ports. There are 6 modes available, but not all modes are available to all timers, as only timer 2 has a connected gate input, required for modes 1 and 5. The gate line is -controlled by port 61h, bit 0, as illustrated in the following diagram. +controlled by port 61h, bit 0, as illustrated in the following diagram:: - -------------- ---------------- -| | | | -| 1.1932 MHz |---------->| CLOCK OUT | ---------> IRQ 0 -| Clock | | | | - -------------- | +->| GATE TIMER 0 | + -------------- ---------------- + | | | | + | 1.1932 MHz|---------->| CLOCK OUT | ---------> IRQ 0 + | Clock | | | | + -------------- | +->| GATE TIMER 0 | | ---------------- | | ---------------- @@ -70,29 +74,33 @@ controlled by port 61h, bit 0, as illustrated in the following diagram. | | | |------>| CLOCK OUT | ---------> Port 61h, bit 5 | | | -Port 61h, bit 0 ---------->| GATE TIMER 2 | \_.---- ____ + Port 61h, bit 0 -------->| GATE TIMER 2 | \_.---- ____ ---------------- _| )--|LPF|---Speaker / *---- \___/ -Port 61h, bit 1 -----------------------------------/ + Port 61h, bit 1 ---------------------------------/ The timer modes are now described. -Mode 0: Single Timeout. This is a one-shot software timeout that counts down +Mode 0: Single Timeout. + This is a one-shot software timeout that counts down when the gate is high (always true for timers 0 and 1). When the count reaches zero, the output goes high. -Mode 1: Triggered One-shot. The output is initially set high. When the gate +Mode 1: Triggered One-shot. + The output is initially set high. When the gate line is set high, a countdown is initiated (which does not stop if the gate is lowered), during which the output is set low. When the count reaches zero, the output goes high. -Mode 2: Rate Generator. The output is initially set high. When the countdown +Mode 2: Rate Generator. + The output is initially set high. When the countdown reaches 1, the output goes low for one count and then returns high. The value is reloaded and the countdown automatically resumes. If the gate line goes low, the count is halted. If the output is low when the gate is lowered, the output automatically goes high (this only affects timer 2). -Mode 3: Square Wave. This generates a high / low square wave. The count +Mode 3: Square Wave. + This generates a high / low square wave. The count determines the length of the pulse, which alternates between high and low when zero is reached. The count only proceeds when gate is high and is automatically reloaded on reaching zero. The count is decremented twice at @@ -103,12 +111,14 @@ Mode 3: Square Wave. This generates a high / low square wave. The count values are not observed when reading. This is the intended mode for timer 2, which generates sine-like tones by low-pass filtering the square wave output. -Mode 4: Software Strobe. After programming this mode and loading the counter, +Mode 4: Software Strobe. + After programming this mode and loading the counter, the output remains high until the counter reaches zero. Then the output goes low for 1 clock cycle and returns high. The counter is not reloaded. Counting only occurs when gate is high. -Mode 5: Hardware Strobe. After programming and loading the counter, the +Mode 5: Hardware Strobe. + After programming and loading the counter, the output remains high. When the gate is raised, a countdown is initiated (which does not stop if the gate is lowered). When the counter reaches zero, the output goes low for 1 clock cycle and then returns high. The counter is @@ -118,49 +128,49 @@ In addition to normal binary counting, the PIT supports BCD counting. The command port, 0x43 is used to set the counter and mode for each of the three timers. -PIT commands, issued to port 0x43, using the following bit encoding: +PIT commands, issued to port 0x43, using the following bit encoding:: -Bit 7-4: Command (See table below) -Bit 3-1: Mode (000 = Mode 0, 101 = Mode 5, 11X = undefined) -Bit 0 : Binary (0) / BCD (1) + Bit 7-4: Command (See table below) + Bit 3-1: Mode (000 = Mode 0, 101 = Mode 5, 11X = undefined) + Bit 0 : Binary (0) / BCD (1) -Command table: +Command table:: -0000 - Latch Timer 0 count for port 0x40 + 0000 - Latch Timer 0 count for port 0x40 sample and hold the count to be read in port 0x40; additional commands ignored until counter is read; mode bits ignored. -0001 - Set Timer 0 LSB mode for port 0x40 + 0001 - Set Timer 0 LSB mode for port 0x40 set timer to read LSB only and force MSB to zero; mode bits set timer mode -0010 - Set Timer 0 MSB mode for port 0x40 + 0010 - Set Timer 0 MSB mode for port 0x40 set timer to read MSB only and force LSB to zero; mode bits set timer mode -0011 - Set Timer 0 16-bit mode for port 0x40 + 0011 - Set Timer 0 16-bit mode for port 0x40 set timer to read / write LSB first, then MSB; mode bits set timer mode -0100 - Latch Timer 1 count for port 0x41 - as described above -0101 - Set Timer 1 LSB mode for port 0x41 - as described above -0110 - Set Timer 1 MSB mode for port 0x41 - as described above -0111 - Set Timer 1 16-bit mode for port 0x41 - as described above + 0100 - Latch Timer 1 count for port 0x41 - as described above + 0101 - Set Timer 1 LSB mode for port 0x41 - as described above + 0110 - Set Timer 1 MSB mode for port 0x41 - as described above + 0111 - Set Timer 1 16-bit mode for port 0x41 - as described above -1000 - Latch Timer 2 count for port 0x42 - as described above -1001 - Set Timer 2 LSB mode for port 0x42 - as described above -1010 - Set Timer 2 MSB mode for port 0x42 - as described above -1011 - Set Timer 2 16-bit mode for port 0x42 as described above + 1000 - Latch Timer 2 count for port 0x42 - as described above + 1001 - Set Timer 2 LSB mode for port 0x42 - as described above + 1010 - Set Timer 2 MSB mode for port 0x42 - as described above + 1011 - Set Timer 2 16-bit mode for port 0x42 as described above -1101 - General counter latch + 1101 - General counter latch Latch combination of counters into corresponding ports Bit 3 = Counter 2 Bit 2 = Counter 1 Bit 1 = Counter 0 Bit 0 = Unused -1110 - Latch timer status + 1110 - Latch timer status Latch combination of counter mode into corresponding ports Bit 3 = Counter 2 Bit 2 = Counter 1 @@ -177,7 +187,8 @@ Command table: Bit 3-1 = Mode Bit 0 = Binary (0) / BCD mode (1) -2.2) RTC +2.2. RTC +-------- The second device which was available in the original PC was the MC146818 real time clock. The original device is now obsolete, and usually emulated by the @@ -201,21 +212,21 @@ in progress, as indicated in the status register. The clock uses a 32.768kHz crystal, so bits 6-4 of register A should be programmed to a 32kHz divider if the RTC is to count seconds. -This is the RAM map originally used for the RTC/CMOS: - -Location Size Description ------------------------------------------- -00h byte Current second (BCD) -01h byte Seconds alarm (BCD) -02h byte Current minute (BCD) -03h byte Minutes alarm (BCD) -04h byte Current hour (BCD) -05h byte Hours alarm (BCD) -06h byte Current day of week (BCD) -07h byte Current day of month (BCD) -08h byte Current month (BCD) -09h byte Current year (BCD) -0Ah byte Register A +This is the RAM map originally used for the RTC/CMOS:: + + Location Size Description + ------------------------------------------ + 00h byte Current second (BCD) + 01h byte Seconds alarm (BCD) + 02h byte Current minute (BCD) + 03h byte Minutes alarm (BCD) + 04h byte Current hour (BCD) + 05h byte Hours alarm (BCD) + 06h byte Current day of week (BCD) + 07h byte Current day of month (BCD) + 08h byte Current month (BCD) + 09h byte Current year (BCD) + 0Ah byte Register A bit 7 = Update in progress bit 6-4 = Divider for clock 000 = 4.194 MHz @@ -234,7 +245,7 @@ Location Size Description 1101 = 125 mS 1110 = 250 mS 1111 = 500 mS -0Bh byte Register B + 0Bh byte Register B bit 7 = Run (0) / Halt (1) bit 6 = Periodic interrupt enable bit 5 = Alarm interrupt enable @@ -243,19 +254,20 @@ Location Size Description bit 2 = BCD calendar (0) / Binary (1) bit 1 = 12-hour mode (0) / 24-hour mode (1) bit 0 = 0 (DST off) / 1 (DST enabled) -OCh byte Register C (read only) + OCh byte Register C (read only) bit 7 = interrupt request flag (IRQF) bit 6 = periodic interrupt flag (PF) bit 5 = alarm interrupt flag (AF) bit 4 = update interrupt flag (UF) bit 3-0 = reserved -ODh byte Register D (read only) + ODh byte Register D (read only) bit 7 = RTC has power bit 6-0 = reserved -32h byte Current century BCD (*) + 32h byte Current century BCD (*) (*) location vendor specific and now determined from ACPI global tables -2.3) APIC +2.3. APIC +--------- On Pentium and later processors, an on-board timer is available to each CPU as part of the Advanced Programmable Interrupt Controller. The APIC is @@ -276,7 +288,8 @@ timer is programmed through the LVT (local vector timer) register, is capable of one-shot or periodic operation, and is based on the bus clock divided down by the programmable divider register. -2.4) HPET +2.4. HPET +--------- HPET is quite complex, and was originally intended to replace the PIT / RTC support of the X86 PC. It remains to be seen whether that will be the case, as @@ -297,7 +310,8 @@ indicated through ACPI tables by the BIOS. Detailed specification of the HPET is beyond the current scope of this document, as it is also very well documented elsewhere. -2.5) Offboard Timers +2.5. Offboard Timers +-------------------- Several cards, both proprietary (watchdog boards) and commonplace (e1000) have timing chips built into the cards which may have registers which are accessible @@ -307,9 +321,8 @@ general frowned upon as not playing by the agreed rules of the game. Such a timer device would require additional support to be virtualized properly and is not considered important at this time as no known operating system does this. -========================================================================= - -3) TSC Hardware +3. TSC Hardware +=============== The TSC or time stamp counter is relatively simple in theory; it counts instruction cycles issued by the processor, which can be used as a measure of @@ -340,7 +353,8 @@ allows the guest visible TSC to be offset by a constant. Newer implementations promise to allow the TSC to additionally be scaled, but this hardware is not yet widely available. -3.1) TSC synchronization +3.1. TSC synchronization +------------------------ The TSC is a CPU-local clock in most implementations. This means, on SMP platforms, the TSCs of different CPUs may start at different times depending @@ -357,7 +371,8 @@ practice, getting a perfectly synchronized TSC will not be possible unless all values are read from the same clock, which generally only is possible on single socket systems or those with special hardware support. -3.2) TSC and CPU hotplug +3.2. TSC and CPU hotplug +------------------------ As touched on already, CPUs which arrive later than the boot time of the system may not have a TSC value that is synchronized with the rest of the system. @@ -367,7 +382,8 @@ a guarantee. This can have the effect of bringing a system from a state where TSC is synchronized back to a state where TSC synchronization flaws, however small, may be exposed to the OS and any virtualization environment. -3.3) TSC and multi-socket / NUMA +3.3. TSC and multi-socket / NUMA +-------------------------------- Multi-socket systems, especially large multi-socket systems are likely to have individual clocksources rather than a single, universally distributed clock. @@ -385,7 +401,8 @@ standards for telecommunications and computer equipment. It is recommended not to trust the TSCs to remain synchronized on NUMA or multiple socket systems for these reasons. -3.4) TSC and C-states +3.4. TSC and C-states +--------------------- C-states, or idling states of the processor, especially C1E and deeper sleep states may be problematic for TSC as well. The TSC may stop advancing in such @@ -396,7 +413,8 @@ based on CPU and chipset identifications. The TSC in such a case may be corrected by catching it up to a known external clocksource. -3.5) TSC frequency change / P-states +3.5. TSC frequency change / P-states +------------------------------------ To make things slightly more interesting, some CPUs may change frequency. They may or may not run the TSC at the same rate, and because the frequency change @@ -416,14 +434,16 @@ other processors. In such cases, the TSC on halted CPUs could advance faster than that of non-halted processors. AMD Turion processors are known to have this problem. -3.6) TSC and STPCLK / T-states +3.6. TSC and STPCLK / T-states +------------------------------ External signals given to the processor may also have the effect of stopping the TSC. This is typically done for thermal emergency power control to prevent an overheating condition, and typically, there is no way to detect that this condition has happened. -3.7) TSC virtualization - VMX +3.7. TSC virtualization - VMX +----------------------------- VMX provides conditional trapping of RDTSC, RDMSR, WRMSR and RDTSCP instructions, which is enough for full virtualization of TSC in any manner. In @@ -431,14 +451,16 @@ addition, VMX allows passing through the host TSC plus an additional TSC_OFFSET field specified in the VMCS. Special instructions must be used to read and write the VMCS field. -3.8) TSC virtualization - SVM +3.8. TSC virtualization - SVM +----------------------------- SVM provides conditional trapping of RDTSC, RDMSR, WRMSR and RDTSCP instructions, which is enough for full virtualization of TSC in any manner. In addition, SVM allows passing through the host TSC plus an additional offset field specified in the SVM control block. -3.9) TSC feature bits in Linux +3.9. TSC feature bits in Linux +------------------------------ In summary, there is no way to guarantee the TSC remains in perfect synchronization unless it is explicitly guaranteed by the architecture. Even @@ -448,13 +470,16 @@ despite being locally consistent. The following feature bits are used by Linux to signal various TSC attributes, but they can only be taken to be meaningful for UP or single node systems. -X86_FEATURE_TSC : The TSC is available in hardware -X86_FEATURE_RDTSCP : The RDTSCP instruction is available -X86_FEATURE_CONSTANT_TSC : The TSC rate is unchanged with P-states -X86_FEATURE_NONSTOP_TSC : The TSC does not stop in C-states -X86_FEATURE_TSC_RELIABLE : TSC sync checks are skipped (VMware) +========================= ======================================= +X86_FEATURE_TSC The TSC is available in hardware +X86_FEATURE_RDTSCP The RDTSCP instruction is available +X86_FEATURE_CONSTANT_TSC The TSC rate is unchanged with P-states +X86_FEATURE_NONSTOP_TSC The TSC does not stop in C-states +X86_FEATURE_TSC_RELIABLE TSC sync checks are skipped (VMware) +========================= ======================================= -4) Virtualization Problems +4. Virtualization Problems +========================== Timekeeping is especially problematic for virtualization because a number of challenges arise. The most obvious problem is that time is now shared between @@ -473,7 +498,8 @@ BIOS, but not in such an extreme fashion. However, the fact that SMM mode may cause similar problems to virtualization makes it a good justification for solving many of these problems on bare metal. -4.1) Interrupt clocking +4.1. Interrupt clocking +----------------------- One of the most immediate problems that occurs with legacy operating systems is that the system timekeeping routines are often designed to keep track of @@ -502,7 +528,8 @@ thus requires interrupt slewing to keep proper time. It does use a low enough rate (ed: is it 18.2 Hz?) however that it has not yet been a problem in practice. -4.2) TSC sampling and serialization +4.2. TSC sampling and serialization +----------------------------------- As the highest precision time source available, the cycle counter of the CPU has aroused much interest from developers. As explained above, this timer has @@ -524,7 +551,8 @@ it may be necessary for an implementation to guard against "backwards" reads of the TSC as seen from other CPUs, even in an otherwise perfectly synchronized system. -4.3) Timespec aliasing +4.3. Timespec aliasing +---------------------- Additionally, this lack of serialization from the TSC poses another challenge when using results of the TSC when measured against another time source. As @@ -548,7 +576,8 @@ This aliasing requires care in the computation and recalibration of kvmclock and any other values derived from TSC computation (such as TSC virtualization itself). -4.4) Migration +4.4. Migration +-------------- Migration of a virtual machine raises problems for timekeeping in two ways. First, the migration itself may take time, during which interrupts cannot be @@ -566,7 +595,8 @@ always be caught up to the original rate. KVM clock avoids these problems by simply storing multipliers and offsets against the TSC for the guest to convert back into nanosecond resolution values. -4.5) Scheduling +4.5. Scheduling +--------------- Since scheduling may be based on precise timing and firing of interrupts, the scheduling algorithms of an operating system may be adversely affected by @@ -579,7 +609,8 @@ In an attempt to work around this, several implementations have provided a paravirtualized scheduler clock, which reveals the true amount of CPU time for which a virtual machine has been running. -4.6) Watchdogs +4.6. Watchdogs +-------------- Watchdog timers, such as the lock detector in Linux may fire accidentally when running under hardware virtualization due to timer interrupts being delayed or @@ -587,7 +618,8 @@ misinterpretation of the passage of real time. Usually, these warnings are spurious and can be ignored, but in some circumstances it may be necessary to disable such detection. -4.7) Delays and precision timing +4.7. Delays and precision timing +-------------------------------- Precise timing and delays may not be possible in a virtualized system. This can happen if the system is controlling physical hardware, or issues delays to @@ -600,7 +632,8 @@ The second issue may cause performance problems, but this is unlikely to be a significant issue. In many cases these delays may be eliminated through configuration or paravirtualization. -4.8) Covert channels and leaks +4.8. Covert channels and leaks +------------------------------ In addition to the above problems, time information will inevitably leak to the guest about the host in anything but a perfect implementation of virtualized diff --git a/Documentation/virt/uml/UserModeLinux-HOWTO.txt b/Documentation/virt/uml/user_mode_linux.rst index 87b80f589e1c..de0f0b2c9d5b 100644 --- a/Documentation/virt/uml/UserModeLinux-HOWTO.txt +++ b/Documentation/virt/uml/user_mode_linux.rst @@ -1,12 +1,17 @@ - User Mode Linux HOWTO - User Mode Linux Core Team - Mon Nov 18 14:16:16 EST 2002 +.. SPDX-License-Identifier: GPL-2.0 - This document describes the use and abuse of Jeff Dike's User Mode - Linux: a port of the Linux kernel as a normal Intel Linux process. - ______________________________________________________________________ +===================== +User Mode Linux HOWTO +===================== - Table of Contents +:Author: User Mode Linux Core Team +:Last-updated: Sat Jan 25 16:07:55 CET 2020 + +This document describes the use and abuse of Jeff Dike's User Mode +Linux: a port of the Linux kernel as a normal Intel Linux process. + + +.. Table of Contents 1. Introduction @@ -132,19 +137,19 @@ 15.5 Other contributions - ______________________________________________________________________ - - 1. Introduction +1. Introduction +================ Welcome to User Mode Linux. It's going to be fun. - 1.1. How is User Mode Linux Different? +1.1. How is User Mode Linux Different? +--------------------------------------- Normally, the Linux Kernel talks straight to your hardware (video card, keyboard, hard drives, etc), and any programs which run ask the - kernel to operate the hardware, like so: + kernel to operate the hardware, like so:: @@ -160,10 +165,10 @@ The User Mode Linux Kernel is different; instead of talking to the - hardware, it talks to a `real' Linux kernel (called the `host kernel' + hardware, it talks to a `real` Linux kernel (called the `host kernel` from now on), like any other program. Programs can then run inside User-Mode Linux as if they were running under a normal kernel, like - so: + so:: @@ -181,7 +186,8 @@ - 1.2. Why Would I Want User Mode Linux? +1.2. Why Would I Want User Mode Linux? +--------------------------------------- 1. If User Mode Linux crashes, your host kernel is still fine. @@ -204,83 +210,41 @@ +.. _Compiling_the_kernel_and_modules: - - 2. Compiling the kernel and modules +2. Compiling the kernel and modules +==================================== - 2.1. Compiling the kernel +2.1. Compiling the kernel +-------------------------- Compiling the user mode kernel is just like compiling any other - kernel. Let's go through the steps, using 2.4.0-prerelease (current - as of this writing) as an example: - - - 1. Download the latest UML patch from - - the download page <http://user-mode-linux.sourceforge.net/ - - In this example, the file is uml-patch-2.4.0-prerelease.bz2. + kernel. - 2. Download the matching kernel from your favourite kernel mirror, + 1. Download the latest kernel from your favourite kernel mirror, such as: - ftp://ftp.ca.kernel.org/pub/kernel/v2.4/linux-2.4.0-prerelease.tar.bz2 - <ftp://ftp.ca.kernel.org/pub/kernel/v2.4/linux-2.4.0-prerelease.tar.bz2> - . - - - 3. Make a directory and unpack the kernel into it. - + https://mirrors.edge.kernel.org/pub/linux/kernel/v5.x/linux-5.4.14.tar.xz + 2. Make a directory and unpack the kernel into it:: host% mkdir ~/uml - - - - - host% cd ~/uml - - - - - - host% - tar -xzvf linux-2.4.0-prerelease.tar.bz2 - - - - - - - 4. Apply the patch using - - - - host% - cd ~/uml/linux - - - host% - bzcat uml-patch-2.4.0-prerelease.bz2 | patch -p1 + tar xvf linux-5.4.14.tar.xz - - - - - 5. Run your favorite config; `make xconfig ARCH=um' is the most - convenient. `make config ARCH=um' and 'make menuconfig ARCH=um' + 3. Run your favorite config; ``make xconfig ARCH=um`` is the most + convenient. ``make config ARCH=um`` and ``make menuconfig ARCH=um`` will work as well. The defaults will give you a useful kernel. If you want to change something, go ahead, it probably won't hurt anything. @@ -288,44 +252,20 @@ Note: If the host is configured with a 2G/2G address space split rather than the usual 3G/1G split, then the packaged UML binaries - will not run. They will immediately segfault. See ``UML on 2G/2G - hosts'' for the scoop on running UML on your system. - - - - 6. Finish with `make linux ARCH=um': the result is a file called - `linux' in the top directory of your source tree. - - Make sure that you don't build this kernel in /usr/src/linux. On some - distributions, /usr/include/asm is a link into this pool. The user- - mode build changes the other end of that link, and things that include - <asm/anything.h> stop compiling. - - The sources are also available from cvs at the project's cvs page, - which has directions on getting the sources. You can also browse the - CVS pool from there. + will not run. They will immediately segfault. See + :ref:`UML_on_2G/2G_hosts` for the scoop on running UML on your system. - If you get the CVS sources, you will have to check them out into an - empty directory. You will then have to copy each file into the - corresponding directory in the appropriate kernel pool. - If you don't have the latest kernel pool, you can get the - corresponding user-mode sources with + 4. Finish with ``make linux ARCH=um``: the result is a file called + ``linux`` in the top directory of your source tree. - host% cvs co -r v_2_3_x linux - - - - where 'x' is the version in your pool. Note that you will not get the - bug fixes and enhancements that have gone into subsequent releases. - - - 2.2. Compiling and installing kernel modules +2.2. Compiling and installing kernel modules +--------------------------------------------- UML modules are built in the same way as the native kernel (with the - exception of the 'ARCH=um' that you always need for UML): + exception of the 'ARCH=um' that you always need for UML):: host% make modules ARCH=um @@ -337,12 +277,12 @@ the user-mode pool. Modules from the native kernel won't work. You can install them by using ftp or something to copy them into the - virtual machine and dropping them into /lib/modules/`uname -r`. + virtual machine and dropping them into ``/lib/modules/$(uname -r)``. You can also get the kernel build process to install them as follows: 1. with the kernel not booted, mount the root filesystem in the top - level of the kernel pool: + level of the kernel pool:: host% mount root_fs mnt -o loop @@ -352,7 +292,7 @@ - 2. run + 2. run:: host% @@ -363,7 +303,7 @@ - 3. unmount the filesystem + 3. unmount the filesystem:: host% umount mnt @@ -381,27 +321,28 @@ as modules, especially filesystems and network protocols and filters, so most symbols which need to be exported probably already are. However, if you do find symbols that need exporting, let us - <http://user-mode-linux.sourceforge.net/> know, and + know at http://user-mode-linux.sourceforge.net/, and they'll be "taken care of". - 2.3. Compiling and installing uml_utilities +2.3. Compiling and installing uml_utilities +-------------------------------------------- Many features of the UML kernel require a user-space helper program, so a uml_utilities package is distributed separately from the kernel patch which provides these helpers. Included within this is: - o port-helper - Used by consoles which connect to xterms or ports + - port-helper - Used by consoles which connect to xterms or ports - o tunctl - Configuration tool to create and delete tap devices + - tunctl - Configuration tool to create and delete tap devices - o uml_net - Setuid binary for automatic tap device configuration + - uml_net - Setuid binary for automatic tap device configuration - o uml_switch - User-space virtual switch required for daemon + - uml_switch - User-space virtual switch required for daemon transport - The uml_utilities tree is compiled with: + The uml_utilities tree is compiled with:: host# @@ -423,38 +364,42 @@ - 3. Running UML and logging in +3. Running UML and logging in +============================== - 3.1. Running UML +3.1. Running UML +----------------- - It runs on 2.2.15 or later, and all 2.4 kernels. + It runs on 2.2.15 or later, and all kernel versions since 2.4. Booting UML is straightforward. Simply run 'linux': it will try to - mount the file `root_fs' in the current directory. You do not need to - run it as root. If your root filesystem is not named `root_fs', then - you need to put a `ubd0=root_fs_whatever' switch on the linux command + mount the file ``root_fs`` in the current directory. You do not need to + run it as root. If your root filesystem is not named ``root_fs``, then + you need to put a ``ubd0=root_fs_whatever`` switch on the linux command line. You will need a filesystem to boot UML from. There are a number - available for download from here <http://user-mode- - linux.sourceforge.net/> . There are also several tools - <http://user-mode-linux.sourceforge.net/> which can be + available for download from http://user-mode-linux.sourceforge.net. + There are also several tools at + http://user-mode-linux.sourceforge.net/ which can be used to generate UML-compatible filesystem images from media. The kernel will boot up and present you with a login prompt. - Note: If the host is configured with a 2G/2G address space split +Note: + If the host is configured with a 2G/2G address space split rather than the usual 3G/1G split, then the packaged UML binaries will - not run. They will immediately segfault. See ``UML on 2G/2G hosts'' + not run. They will immediately segfault. See :ref:`UML_on_2G/2G_hosts` for the scoop on running UML on your system. - 3.2. Logging in +3.2. Logging in +---------------- @@ -468,22 +413,22 @@ There are a couple of other ways to log in: - o On a virtual console + - On a virtual console Each virtual console that is configured (i.e. the device exists in /dev and /etc/inittab runs a getty on it) will come up in its own - xterm. If you get tired of the xterms, read ``Setting up serial - lines and consoles'' to see how to attach the consoles to - something else, like host ptys. + xterm. If you get tired of the xterms, read + :ref:`setting_up_serial_lines_and_consoles` to see how to attach + the consoles to something else, like host ptys. - o Over the serial line + - Over the serial line - In the boot output, find a line that looks like: + In the boot output, find a line that looks like:: @@ -493,7 +438,7 @@ Attach your favorite terminal program to the corresponding tty. I.e. - for minicom, the command would be + for minicom, the command would be:: host% minicom -o -p /dev/ttyp1 @@ -503,37 +448,40 @@ - o Over the net + - Over the net If the network is running, then you can telnet to the virtual - machine and log in to it. See ``Setting up the network'' to learn + machine and log in to it. See :ref:`Setting_up_the_network` to learn about setting up a virtual network. When you're done using it, run halt, and the kernel will bring itself down and the process will exit. - 3.3. Examples +3.3. Examples +-------------- Here are some examples of UML in action: - o A login session <http://user-mode-linux.sourceforge.net/login.html> + - A login session http://user-mode-linux.sourceforge.net/old/login.html - o A virtual network <http://user-mode-linux.sourceforge.net/net.html> + - A virtual network http://user-mode-linux.sourceforge.net/old/net.html +.. _UML_on_2G/2G_hosts: +4. UML on 2G/2G hosts +====================== - 4. UML on 2G/2G hosts - - 4.1. Introduction +4.1. Introduction +------------------ Most Linux machines are configured so that the kernel occupies the @@ -546,7 +494,8 @@ - 4.2. The problem +4.2. The problem +----------------- The prebuilt UML binaries on this site will not run on 2G/2G hosts @@ -558,13 +507,14 @@ - 4.3. The solution +4.3. The solution +------------------ The fix for this is to rebuild UML from source after enabling CONFIG_HOST_2G_2G (under 'General Setup'). This will cause UML to load itself in the top .5G of that smaller process address space, - where it will run fine. See ``Compiling the kernel and modules'' if + where it will run fine. See :ref:`Compiling_the_kernel_and_modules` if you need help building UML from source. @@ -573,10 +523,11 @@ +.. _setting_up_serial_lines_and_consoles: - - 5. Setting up serial lines and consoles +5. Setting up serial lines and consoles +======================================== It is possible to attach UML serial lines and consoles to many types @@ -584,22 +535,23 @@ You can attach them to host ptys, ttys, file descriptors, and ports. - This allows you to do things like + This allows you to do things like: - o have a UML console appear on an unused host console, + - have a UML console appear on an unused host console, - o hook two virtual machines together by having one attach to a pty + - hook two virtual machines together by having one attach to a pty and having the other attach to the corresponding tty - o make a virtual machine accessible from the net by attaching a + - make a virtual machine accessible from the net by attaching a console to a port on the host. - The general format of the command line option is device=channel. + The general format of the command line option is ``device=channel``. - 5.1. Specifying the device +5.1. Specifying the device +--------------------------- Devices are specified with "con" or "ssl" (console or serial line, respectively), optionally with a device number if you are talking @@ -613,7 +565,7 @@ A specific device name will override a less general "con=" or "ssl=". So, for example, you can assign a pty to each of the serial lines - except for the first two like this: + except for the first two like this:: ssl=pty ssl0=tty:/dev/tty0 ssl1=tty:/dev/tty1 @@ -626,13 +578,14 @@ - 5.2. Specifying the channel +5.2. Specifying the channel +---------------------------- There are a number of different types of channels to attach a UML device to, each with a different way of specifying exactly what to attach to. - o pseudo-terminals - device=pty pts terminals - device=pts + - pseudo-terminals - device=pty pts terminals - device=pts This will cause UML to allocate a free host pseudo-terminal for the @@ -640,23 +593,23 @@ log. You access it by attaching a terminal program to the corresponding tty: - o screen /dev/pts/n + - screen /dev/pts/n - o screen /dev/ttyxx + - screen /dev/ttyxx - o minicom -o -p /dev/ttyxx - minicom seems not able to handle pts + - minicom -o -p /dev/ttyxx - minicom seems not able to handle pts devices - o kermit - start it up, 'open' the device, then 'connect' + - kermit - start it up, 'open' the device, then 'connect' - o terminals - device=tty:tty device file + - terminals - device=tty:tty device file - This will make UML attach the device to the specified tty (i.e + This will make UML attach the device to the specified tty (i.e:: con1=tty:/dev/tty3 @@ -672,7 +625,7 @@ - o xterms - device=xterm + - xterms - device=xterm UML will run an xterm and the device will be attached to it. @@ -681,12 +634,12 @@ - o Port - device=port:port number + - Port - device=port:port number This will attach the UML devices to the specified host port. Attaching console 1 to the host's port 9000 would be done like - this: + this:: con1=port:9000 @@ -694,7 +647,7 @@ - Attaching all the serial lines to that port would be done similarly: + Attaching all the serial lines to that port would be done similarly:: ssl=port:9000 @@ -702,8 +655,8 @@ - You access these devices by telnetting to that port. Each active tel- - net session gets a different device. If there are more telnets to a + You access these devices by telnetting to that port. Each active + telnet session gets a different device. If there are more telnets to a port than UML devices attached to it, then the extra telnet sessions will block until an existing telnet detaches, or until another device becomes active (i.e. by being activated in /etc/inittab). @@ -725,13 +678,13 @@ - o already-existing file descriptors - device=file descriptor + - already-existing file descriptors - device=file descriptor If you set up a file descriptor on the UML command line, you can attach a UML device to it. This is most commonly used to put the main console back on stdin and stdout after assigning all the other - consoles to something else: + consoles to something else:: con0=fd:0,fd:1 con=pts @@ -743,7 +696,7 @@ - o Nothing - device=null + - Nothing - device=null This allows the device to be opened, in contrast to 'none', but @@ -754,7 +707,7 @@ - o None - device=none + - None - device=none This causes the device to disappear. @@ -762,7 +715,7 @@ You can also specify different input and output channels for a device - by putting a comma between them: + by putting a comma between them:: ssl3=tty:/dev/tty2,xterm @@ -785,14 +738,15 @@ - 5.3. Examples +5.3. Examples +-------------- There are a number of interesting things you can do with this capability. First, this is how you get rid of those bleeding console xterms by - attaching them to host ptys: + attaching them to host ptys:: con=pty con0=fd:0,fd:1 @@ -802,7 +756,7 @@ This will make a UML console take over an unused host virtual console, so that when you switch to it, you will see the UML login prompt - rather than the host login prompt: + rather than the host login prompt:: con1=tty:/dev/tty6 @@ -813,7 +767,7 @@ You can attach two virtual machines together with what amounts to a serial line as follows: - Run one UML with a serial line attached to a pty - + Run one UML with a serial line attached to a pty:: ssl1=pty @@ -825,7 +779,7 @@ that it got /dev/ptyp1). Boot the other UML with a serial line attached to the corresponding - tty - + tty:: ssl1=tty:/dev/ttyp1 @@ -838,7 +792,10 @@ prompt of the other virtual machine. - 6. Setting up the network +.. _setting_up_the_network: + +6. Setting up the network +========================== @@ -858,19 +815,19 @@ There are currently five transport types available for a UML virtual machine to exchange packets with other hosts: - o ethertap + - ethertap - o TUN/TAP + - TUN/TAP - o Multicast + - Multicast - o a switch daemon + - a switch daemon - o slip + - slip - o slirp + - slirp - o pcap + - pcap The TUN/TAP, ethertap, slip, and slirp transports allow a UML instance to exchange packets with the host. They may be directed @@ -893,28 +850,28 @@ With so many host transports, which one should you use? Here's when you should use each one: - o ethertap - if you want access to the host networking and it is + - ethertap - if you want access to the host networking and it is running 2.2 - o TUN/TAP - if you want access to the host networking and it is + - TUN/TAP - if you want access to the host networking and it is running 2.4. Also, the TUN/TAP transport is able to use a preconfigured device, allowing it to avoid using the setuid uml_net helper, which is a security advantage. - o Multicast - if you want a purely virtual network and you don't want + - Multicast - if you want a purely virtual network and you don't want to set up anything but the UML - o a switch daemon - if you want a purely virtual network and you + - a switch daemon - if you want a purely virtual network and you don't mind running the daemon in order to get somewhat better performance - o slip - there is no particular reason to run the slip backend unless + - slip - there is no particular reason to run the slip backend unless ethertap and TUN/TAP are just not available for some reason - o slirp - if you don't have root access on the host to setup + - slirp - if you don't have root access on the host to setup networking, or if you don't want to allocate an IP to your UML - o pcap - not much use for actual network connectivity, but great for + - pcap - not much use for actual network connectivity, but great for monitoring traffic on the host Ethertap is available on 2.4 and works fine. TUN/TAP is preferred @@ -926,7 +883,8 @@ exploit the helper's root privileges. - 6.1. General setup +6.1. General setup +------------------- First, you must have the virtual network enabled in your UML. If are running a prebuilt kernel from this site, everything is already @@ -938,7 +896,7 @@ The next step is to provide a network device to the virtual machine. This is done by describing it on the kernel command line. - The general format is + The general format is:: eth <n> = <transport> , <transport args> @@ -947,7 +905,7 @@ For example, a virtual ethernet device may be attached to a host - ethertap device as follows: + ethertap device as follows:: eth0=ethertap,tap0,fe:fd:0:0:0:1,192.168.0.254 @@ -978,7 +936,7 @@ You can also add devices to a UML and remove them at runtime. See the - ``The Management Console'' page for details. + :ref:`The_Management_Console` page for details. The sections below describe this in more detail. @@ -995,7 +953,8 @@ - 6.2. Userspace daemons +6.2. Userspace daemons +----------------------- You will likely need the setuid helper, or the switch daemon, or both. They are both installed with the RPM and deb, so if you've installed @@ -1011,7 +970,8 @@ - 6.3. Specifying ethernet addresses +6.3. Specifying ethernet addresses +----------------------------------- Below, you will see that the TUN/TAP, ethertap, and daemon interfaces allow you to specify hardware addresses for the virtual ethernet @@ -1023,21 +983,21 @@ sufficient to guarantee a unique hardware address for the device. A couple of exceptions are: - o Another set of virtual ethernet devices are on the same network and + - Another set of virtual ethernet devices are on the same network and they are assigned hardware addresses using a different scheme which may conflict with the UML IP address-based scheme - o You aren't going to use the device for IP networking, so you don't + - You aren't going to use the device for IP networking, so you don't assign the device an IP address If you let the driver provide the hardware address, you should make sure that the device IP address is known before the interface is - brought up. So, inside UML, this will guarantee that: + brought up. So, inside UML, this will guarantee that:: - UML# - ifconfig eth0 192.168.0.250 up + UML# + ifconfig eth0 192.168.0.250 up @@ -1049,13 +1009,14 @@ - 6.4. UML interface setup +6.4. UML interface setup +------------------------- Once the network devices have been described on the command line, you should boot UML and log in. - The first thing to do is bring the interface up: + The first thing to do is bring the interface up:: UML# ifconfig ethn ip-address up @@ -1067,7 +1028,7 @@ To reach the rest of the world, you should set a default route to the - host: + host:: UML# route add default gw host ip @@ -1075,7 +1036,7 @@ - Again, with host ip of 192.168.0.4: + Again, with host ip of 192.168.0.4:: UML# route add default gw 192.168.0.4 @@ -1097,29 +1058,25 @@ Note: If you can't communicate with other hosts on your physical ethernet, it's probably because of a network route that's automatically set up. If you run 'route -n' and see a route that - looks like this: + looks like this:: - Destination Gateway Genmask Flags Metric Ref Use Iface - 192.168.0.0 0.0.0.0 255.255.255.0 U 0 0 0 eth0 + Destination Gateway Genmask Flags Metric Ref Use Iface + 192.168.0.0 0.0.0.0 255.255.255.0 U 0 0 0 eth0 with a mask that's not 255.255.255.255, then replace it with a route - to your host: + to your host:: UML# route del -net 192.168.0.0 dev eth0 netmask 255.255.255.0 - - - - UML# route add -host 192.168.0.4 dev eth0 @@ -1131,7 +1088,8 @@ - 6.5. Multicast +6.5. Multicast +--------------- The simplest way to set up a virtual network between multiple UMLs is to use the mcast transport. This was written by Harald Welte and is @@ -1142,7 +1100,7 @@ messages when you bring the device up inside UML. - To use it, run two UMLs with + To use it, run two UMLs with:: eth0=mcast @@ -1151,16 +1109,12 @@ on their command lines. Log in, configure the ethernet device in each - machine with different IP addresses: + machine with different IP addresses:: UML1# ifconfig eth0 192.168.0.254 - - - - UML2# ifconfig eth0 192.168.0.253 @@ -1168,7 +1122,7 @@ and they should be able to talk to each other. - The full set of command line options for this transport are + The full set of command line options for this transport are:: @@ -1177,16 +1131,11 @@ - - Harald's original README is here <http://user-mode-linux.source- - forge.net/> and explains these in detail, as well as - some other issues. - There is also a related point-to-point only "ucast" transport. This is useful when your network does not support multicast, and all network connections are simple point to point links. - The full set of command line options for this transport are + The full set of command line options for this transport are:: ethn=ucast,ethernet address,remote address,listen port,remote port @@ -1194,7 +1143,8 @@ - 6.6. TUN/TAP with the uml_net helper +6.6. TUN/TAP with the uml_net helper +------------------------------------- TUN/TAP is the preferred mechanism on 2.4 to exchange packets with the host. The TUN/TAP backend has been in UML since 2.4.9-3um. @@ -1216,7 +1166,7 @@ kernel or as the tun.o module. The format of the command line switch to attach a device to a TUN/TAP - device is + device is:: eth <n> =tuntap,,, <IP address> @@ -1226,7 +1176,7 @@ For example, this argument will attach the UML's eth0 to the next available tap device and assign an ethernet address to it based on its - IP address + IP address:: eth0=tuntap,,,192.168.0.254 @@ -1247,10 +1197,10 @@ There are a couple potential problems with running the TUN/TAP transport on a 2.4 host kernel - o TUN/TAP seems not to work on 2.4.3 and earlier. Upgrade the host + - TUN/TAP seems not to work on 2.4.3 and earlier. Upgrade the host kernel or use the ethertap transport. - o With an upgraded kernel, TUN/TAP may fail with + - With an upgraded kernel, TUN/TAP may fail with:: File descriptor in bad state @@ -1263,13 +1213,12 @@ make sure that /usr/src/linux points to the headers for the running kernel. - These were pointed out by Tim Robinson <timro at trkr dot net> in - <http://www.geocrawler.com/> name="this uml- - user post"> . + These were pointed out by Tim Robinson <timro at trkr dot net> in the past. - 6.7. TUN/TAP with a preconfigured tap device +6.7. TUN/TAP with a preconfigured tap device +--------------------------------------------- If you prefer not to have UML use uml_net (which is somewhat insecure), with UML 2.4.17-11, you can set up a TUN/TAP device @@ -1277,8 +1226,8 @@ there is no need for root assistance. Setting up the device is done as follows: - o Create the device with tunctl (available from the UML utilities - tarball) + - Create the device with tunctl (available from the UML utilities + tarball):: @@ -1291,8 +1240,8 @@ where uid is the user id or username that UML will be run as. This will tell you what device was created. - o Configure the device IP (change IP addresses and device name to - suit) + - Configure the device IP (change IP addresses and device name to + suit):: @@ -1303,8 +1252,8 @@ - o Set up routing and arping if desired - this is my recipe, there are - other ways of doing the same thing + - Set up routing and arping if desired - this is my recipe, there are + other ways of doing the same thing:: host# @@ -1313,19 +1262,9 @@ host# route add -host 192.168.0.253 dev tap0 - - - - - host# bash -c 'echo 1 > /proc/sys/net/ipv4/conf/tap0/proxy_arp' - - - - - host# arp -Ds 192.168.0.253 eth0 pub @@ -1338,76 +1277,43 @@ utility which reads the information from a config file and sets up devices at boot time. - o Rather than using up two IPs and ARPing for one of them, you can + - Rather than using up two IPs and ARPing for one of them, you can also provide direct access to your LAN by the UML by using a - bridge. + bridge:: host# brctl addbr br0 - - - - host# ifconfig eth0 0.0.0.0 promisc up - - - - host# ifconfig tap0 0.0.0.0 promisc up - - - - host# ifconfig br0 192.168.0.1 netmask 255.255.255.0 up - - - - - - host# - brctl stp br0 off - - - - + host# + brctl stp br0 off host# brctl setfd br0 1 - - - - host# brctl sethello br0 1 - - - - host# brctl addif br0 eth0 - - - - host# brctl addif br0 tap0 @@ -1417,12 +1323,12 @@ Note that 'br0' should be setup using ifconfig with the existing IP address of eth0, as eth0 no longer has its own IP. - o + - Also, the /dev/net/tun device must be writable by the user running UML in order for the UML to use the device that's been configured - for it. The simplest thing to do is + for it. The simplest thing to do is:: host# chmod 666 /dev/net/tun @@ -1438,14 +1344,14 @@ devices and chgrp /dev/net/tun to that group with mode 664 or 660. - o Once the device is set up, run UML with 'eth0=tuntap,device name' + - Once the device is set up, run UML with 'eth0=tuntap,device name' (i.e. 'eth0=tuntap,tap0') on the command line (or do it with the mconsole config command). - o Bring the eth device up in UML and you're in business. + - Bring the eth device up in UML and you're in business. If you don't want that tap device any more, you can make it non- - persistent with + persistent with:: host# tunctl -d tap device @@ -1455,7 +1361,7 @@ Finally, tunctl has a -b (for brief mode) switch which causes it to output only the name of the tap device it created. This makes it - suitable for capture by a script: + suitable for capture by a script:: host# TAP=`tunctl -u 1000 -b` @@ -1465,7 +1371,8 @@ - 6.8. Ethertap +6.8. Ethertap +-------------- Ethertap is the general mechanism on 2.2 for userspace processes to exchange packets with the kernel. @@ -1473,7 +1380,7 @@ To use this transport, you need to describe the virtual network device - on the UML command line. The general format for this is + on the UML command line. The general format for this is:: eth <n> =ethertap, <device> , <ethernet address> , <tap IP address> @@ -1481,7 +1388,7 @@ - So, the previous example + So, the previous example:: eth0=ethertap,tap0,fe:fd:0:0:0:1,192.168.0.254 @@ -1521,7 +1428,7 @@ If you want to set things up yourself, you need to make sure that the appropriate /dev entry exists. If it doesn't, become root and create - it as follows: + it as follows:: mknod /dev/tap <minor> c 36 <minor> + 16 @@ -1529,7 +1436,7 @@ - For example, this is how to create /dev/tap0: + For example, this is how to create /dev/tap0:: mknod /dev/tap0 c 36 0 + 16 @@ -1539,7 +1446,7 @@ You also need to make sure that the host kernel has ethertap support. If ethertap is enabled as a module, you apparently need to insmod - ethertap once for each ethertap device you want to enable. So, + ethertap once for each ethertap device you want to enable. So,:: host# @@ -1549,7 +1456,7 @@ will give you the tap0 interface. To get the tap1 interface, you need - to run + to run:: host# @@ -1561,7 +1468,8 @@ - 6.9. The switch daemon +6.9. The switch daemon +----------------------- Note: This is the daemon formerly known as uml_router, but which was renamed so the network weenies of the world would stop growling at me. @@ -1577,7 +1485,7 @@ sockets. - If you want it to listen on a different pair of sockets, use + If you want it to listen on a different pair of sockets, use:: -unix control socket data socket @@ -1586,7 +1494,7 @@ - If you want it to act as a hub rather than a switch, use + If you want it to act as a hub rather than a switch, use:: -hub @@ -1596,7 +1504,7 @@ If you want the switch to be connected to host networking (allowing - the umls to get access to the outside world through the host), use + the umls to get access to the outside world through the host), use:: -tap tap0 @@ -1610,7 +1518,7 @@ device than tap0, specify that instead of tap0. - uml_switch can be backgrounded as follows + uml_switch can be backgrounded as follows:: host% @@ -1623,7 +1531,7 @@ stdin for EOF. When it sees that, it exits. - The general format of the kernel command line switch is + The general format of the kernel command line switch is:: @@ -1639,7 +1547,8 @@ how to communicate with the daemon. You should only specify them if you told the daemon to use different sockets than the default. So, if you ran the daemon with no arguments, running the UML on the same - machine with + machine with:: + eth0=daemon @@ -1649,7 +1558,8 @@ - 6.10. Slip +6.10. Slip +----------- Slip is another, less general, mechanism for a process to communicate with the host networking. In contrast to the ethertap interface, @@ -1658,7 +1568,7 @@ IP. - The general format of the command line switch is + The general format of the command line switch is:: @@ -1681,7 +1591,8 @@ - 6.11. Slirp +6.11. Slirp +------------ slirp uses an external program, usually /usr/bin/slirp, to provide IP only networking connectivity through the host. This is similar to IP @@ -1691,7 +1602,7 @@ root access or setuid binaries on the host. - The general format of the command line switch for slirp is: + The general format of the command line switch for slirp is:: @@ -1716,7 +1627,7 @@ The eth0 interface on UML should be set up with the IP 10.2.0.15, although you can use anything as long as it is not used by a network you will be connecting to. The default route on UML should be set to - use + use:: UML# @@ -1737,10 +1648,11 @@ - 6.12. pcap +6.12. pcap +----------- The pcap transport is attached to a UML ethernet device on the command - line or with uml_mconsole with the following syntax: + line or with uml_mconsole with the following syntax:: @@ -1762,7 +1674,7 @@ expression optimizer is used. - Example: + Example:: @@ -1777,7 +1689,8 @@ - 6.13. Setting up the host yourself +6.13. Setting up the host yourself +----------------------------------- If you don't specify an address for the host side of the ethertap or slip device, UML won't do any setup on the host. So this is what is @@ -1785,19 +1698,15 @@ 192.168.0.251 and a UML-side IP of 192.168.0.250 - adjust to suit your own network): - o The device needs to be configured with its IP address. Tap devices + - The device needs to be configured with its IP address. Tap devices are also configured with an mtu of 1484. Slip devices are configured with a point-to-point address pointing at the UML ip - address. + address:: host# ifconfig tap0 arp mtu 1484 192.168.0.251 up - - - - host# ifconfig sl0 192.168.0.251 pointopoint 192.168.0.250 up @@ -1805,7 +1714,7 @@ - o If a tap device is being set up, a route is set to the UML IP. + - If a tap device is being set up, a route is set to the UML IP:: UML# route add -host 192.168.0.250 gw 192.168.0.251 @@ -1814,8 +1723,8 @@ - o To allow other hosts on your network to see the virtual machine, - proxy arp is set up for it. + - To allow other hosts on your network to see the virtual machine, + proxy arp is set up for it:: host# arp -Ds 192.168.0.250 eth0 pub @@ -1824,7 +1733,7 @@ - o Finally, the host is set up to route packets. + - Finally, the host is set up to route packets:: host# echo 1 > /proc/sys/net/ipv4/ip_forward @@ -1838,12 +1747,14 @@ - 7. Sharing Filesystems between Virtual Machines +7. Sharing Filesystems between Virtual Machines +================================================ - 7.1. A warning +7.1. A warning +--------------- Don't attempt to share filesystems simply by booting two UMLs from the same file. That's the same thing as booting two physical machines @@ -1851,7 +1762,8 @@ - 7.2. Using layered block devices +7.2. Using layered block devices +--------------------------------- The way to share a filesystem between two virtual machines is to use the copy-on-write (COW) layering capability of the ubd block driver. @@ -1872,7 +1784,7 @@ To add a copy-on-write layer to an existing block device file, simply - add the name of the COW file to the appropriate ubd switch: + add the name of the COW file to the appropriate ubd switch:: ubd0=root_fs_cow,root_fs_debian_22 @@ -1883,7 +1795,7 @@ where 'root_fs_cow' is the private COW file and 'root_fs_debian_22' is the existing shared filesystem. The COW file need not exist. If it doesn't, the driver will create and initialize it. Once the COW file - has been initialized, it can be used on its own on the command line: + has been initialized, it can be used on its own on the command line:: ubd0=root_fs_cow @@ -1896,14 +1808,16 @@ - 7.3. Note! +7.3. Note! +----------- When checking the size of the COW file in order to see the gobs of space that you're saving, make sure you use 'ls -ls' to see the actual disk consumption rather than the length of the file. The COW file is sparse, so the length will be very different from the disk usage. Here is a 'ls -l' of a COW file and backing file from one boot and - shutdown: + shutdown:: + host% ls -l cow.debian debian2.2 -rw-r--r-- 1 jdike jdike 492504064 Aug 6 21:16 cow.debian -rwxrw-rw- 1 jdike jdike 537919488 Aug 6 20:42 debian2.2 @@ -1911,7 +1825,7 @@ - Doesn't look like much saved space, does it? Well, here's 'ls -ls': + Doesn't look like much saved space, does it? Well, here's 'ls -ls':: host% ls -ls cow.debian debian2.2 @@ -1926,7 +1840,8 @@ - 7.4. Another warning +7.4. Another warning +--------------------- Once a filesystem is being used as a readonly backing file for a COW file, do not boot directly from it or modify it in any way. Doing so @@ -1952,7 +1867,8 @@ - 7.5. uml_moo : Merging a COW file with its backing file +7.5. uml_moo : Merging a COW file with its backing file +-------------------------------------------------------- Depending on how you use UML and COW devices, it may be advisable to merge the changes in the COW file into the backing file every once in @@ -1961,7 +1877,7 @@ - The utility that does this is uml_moo. Its usage is + The utility that does this is uml_moo. Its usage is:: host% uml_moo COW file new backing file @@ -1991,8 +1907,8 @@ uml_moo is installed with the UML deb and RPM. If you didn't install UML from one of those packages, you can also get it from the UML - utilities <http://user-mode-linux.sourceforge.net/ - utilities> tar file in tools/moo. + utilities http://user-mode-linux.sourceforge.net/utilities tar file + in tools/moo. @@ -2001,7 +1917,8 @@ - 8. Creating filesystems +8. Creating filesystems +======================== You may want to create and mount new UML filesystems, either because @@ -2015,13 +1932,14 @@ should be easy to translate to the filesystem of your choice. - 8.1. Create the filesystem file +8.1. Create the filesystem file +================================ dd is your friend. All you need to do is tell dd to create an empty file of the appropriate size. I usually make it sparse to save time and to avoid allocating disk space until it's actually used. For example, the following command will create a sparse 100 meg file full - of zeroes. + of zeroes:: host% @@ -2034,9 +1952,9 @@ 8.2. Assign the file to a UML device - Add an argument like the following to the UML command line: + Add an argument like the following to the UML command line:: - ubd4=new_filesystem + ubd4=new_filesystem @@ -2053,7 +1971,7 @@ etc), then get them into UML by way of the net or hostfs. - Make the new filesystem on the device assigned to the new file: + Make the new filesystem on the device assigned to the new file:: host# mkreiserfs /dev/ubd/4 @@ -2077,7 +1995,7 @@ - Now, mount it: + Now, mount it:: UML# @@ -2096,7 +2014,8 @@ - 9. Host file access +9. Host file access +==================== If you want to access files on the host machine from inside UML, you @@ -2112,10 +2031,11 @@ files contained in it just as you would on the host. - 9.1. Using hostfs +9.1. Using hostfs +------------------ To begin with, make sure that hostfs is available inside the virtual - machine with + machine with:: UML# cat /proc/filesystems @@ -2127,7 +2047,7 @@ module and available inside the virtual machine, and insmod it. - Now all you need to do is run mount: + Now all you need to do is run mount:: UML# mount none /mnt/host -t hostfs @@ -2139,7 +2059,7 @@ If you don't want to mount the host root directory, then you can - specify a subdirectory to mount with the -o switch to mount: + specify a subdirectory to mount with the -o switch to mount:: UML# mount none /mnt/home -t hostfs -o /home @@ -2151,13 +2071,14 @@ - 9.2. hostfs as the root filesystem +9.2. hostfs as the root filesystem +----------------------------------- It's possible to boot from a directory hierarchy on the host using hostfs rather than using the standard filesystem in a file. To start, you need that hierarchy. The easiest way is to loop mount - an existing root_fs file: + an existing root_fs file:: host# mount root_fs uml_root_dir -o loop @@ -2166,15 +2087,15 @@ You need to change the filesystem type of / in etc/fstab to be - 'hostfs', so that line looks like this: + 'hostfs', so that line looks like this:: - /dev/ubd/0 / hostfs defaults 1 1 + /dev/ubd/0 / hostfs defaults 1 1 Then you need to chown to yourself all the files in that directory - that are owned by root. This worked for me: + that are owned by root. This worked for me:: host# find . -uid 0 -exec chown jdike {} \; @@ -2183,7 +2104,7 @@ Next, make sure that your UML kernel has hostfs compiled in, not as a - module. Then run UML with the boot device pointing at that directory: + module. Then run UML with the boot device pointing at that directory:: ubd0=/path/to/uml/root/directory @@ -2194,41 +2115,35 @@ UML should then boot as it does normally. - 9.3. Building hostfs +9.3. Building hostfs +--------------------- If you need to build hostfs because it's not in your kernel, you have two choices: - o Compiling hostfs into the kernel: + - Compiling hostfs into the kernel: Reconfigure the kernel and set the 'Host filesystem' option under - o Compiling hostfs as a module: + - Compiling hostfs as a module: Reconfigure the kernel and set the 'Host filesystem' option under be in arch/um/fs/hostfs/hostfs.o. Install that in - /lib/modules/`uname -r`/fs in the virtual machine, boot it up, and + ``/lib/modules/$(uname -r)/fs`` in the virtual machine, boot it up, and:: UML# insmod hostfs +.. _The_Management_Console: - - - - - - - - - - 10. The Management Console +10. The Management Console +=========================== @@ -2240,15 +2155,15 @@ There are a number of things you can do with the mconsole interface: - o get the kernel version + - get the kernel version - o add and remove devices + - add and remove devices - o halt or reboot the machine + - halt or reboot the machine - o Send SysRq commands + - Send SysRq commands - o Pause and resume the UML + - Pause and resume the UML You need the mconsole client (uml_mconsole) which is present in CVS @@ -2257,7 +2172,7 @@ You also need CONFIG_MCONSOLE (under 'General Setup') enabled in UML. - When you boot UML, you'll see a line like: + When you boot UML, you'll see a line like:: mconsole initialized on /home/jdike/.uml/umlNJ32yL/mconsole @@ -2265,7 +2180,7 @@ - If you specify a unique machine id one the UML command line, i.e. + If you specify a unique machine id one the UML command line, i.e.:: umid=debian @@ -2273,7 +2188,7 @@ - you'll see this + you'll see this:: mconsole initialized on /home/jdike/.uml/debian/mconsole @@ -2282,7 +2197,7 @@ That file is the socket that uml_mconsole will use to communicate with - UML. Run it with either the umid or the full path as its argument: + UML. Run it with either the umid or the full path as its argument:: host% uml_mconsole debian @@ -2290,7 +2205,7 @@ - or + or:: host% uml_mconsole /home/jdike/.uml/debian/mconsole @@ -2300,30 +2215,31 @@ You'll get a prompt, at which you can run one of these commands: - o version + - version - o halt + - halt - o reboot + - reboot - o config + - config - o remove + - remove - o sysrq + - sysrq - o help + - help - o cad + - cad - o stop + - stop - o go + - go - 10.1. version +10.1. version +-------------- - This takes no arguments. It prints the UML version. + This takes no arguments. It prints the UML version:: (mconsole) version @@ -2342,11 +2258,12 @@ - 10.2. halt and reboot +10.2. halt and reboot +---------------------- These take no arguments. They shut the machine down immediately, with no syncing of disks and no clean shutdown of userspace. So, they are - pretty close to crashing the machine. + pretty close to crashing the machine:: (mconsole) halt @@ -2357,34 +2274,36 @@ - 10.3. config +10.3. config +------------- "config" adds a new device to the virtual machine. Currently the ubd and network drivers support this. It takes one argument, which is the - device to add, with the same syntax as the kernel command line. + device to add, with the same syntax as the kernel command line:: - (mconsole) - config ubd3=/home/jdike/incoming/roots/root_fs_debian22 + (mconsole) + config ubd3=/home/jdike/incoming/roots/root_fs_debian22 - OK - (mconsole) config eth1=mcast - OK + OK + (mconsole) config eth1=mcast + OK - 10.4. remove +10.4. remove +------------- "remove" deletes a device from the system. Its argument is just the name of the device to be removed. The device must be idle in whatever sense the driver considers necessary. In the case of the ubd driver, the removed block device must not be mounted, swapped on, or otherwise - open, and in the case of the network driver, the device must be down. + open, and in the case of the network driver, the device must be down:: (mconsole) remove ubd3 @@ -2397,7 +2316,8 @@ - 10.5. sysrq +10.5. sysrq +------------ This takes one argument, which is a single letter. It calls the generic kernel's SysRq driver, which does whatever is called for by @@ -2407,19 +2327,21 @@ - 10.6. help +10.6. help +----------- "help" returns a string listing the valid commands and what each one does. - 10.7. cad +10.7. cad +---------- This invokes the Ctl-Alt-Del action on init. What exactly this ends up doing is up to /etc/inittab. Normally, it reboots the machine. With UML, this is usually not desired, so if a halt would be better, - then find the section of inittab that looks like this + then find the section of inittab that looks like this:: # What to do when CTRL-ALT-DEL is pressed. @@ -2432,7 +2354,8 @@ - 10.8. stop +10.8. stop +----------- This puts the UML in a loop reading mconsole requests until a 'go' mconsole command is received. This is very useful for making backups @@ -2448,7 +2371,8 @@ - 10.9. go +10.9. go +--------- This resumes a UML after being paused by a 'stop' command. Note that when the UML has resumed, TCP connections may have timed out and if @@ -2460,9 +2384,10 @@ +.. _Kernel_debugging: - - 11. Kernel debugging +11. Kernel debugging +===================== Note: The interface that makes debugging, as described here, possible @@ -2477,15 +2402,16 @@ In order to debug the kernel, you need build it from source. See - ``Compiling the kernel and modules'' for information on doing that. + :ref:`Compiling_the_kernel_and_modules` for information on doing that. Make sure that you enable CONFIG_DEBUGSYM and CONFIG_PT_PROXY during - the config. These will compile the kernel with -g, and enable the + the config. These will compile the kernel with ``-g``, and enable the ptrace proxy so that gdb works with UML, respectively. - 11.1. Starting the kernel under gdb +11.1. Starting the kernel under gdb +------------------------------------ You can have the kernel running under the control of gdb from the beginning by putting 'debug' on the command line. You will get an @@ -2498,7 +2424,11 @@ There is a transcript of a debugging session here <debug- session.html> , with breakpoints being set in the scheduler and in an interrupt handler. - 11.2. Examining sleeping processes + + +11.2. Examining sleeping processes +----------------------------------- + Not every bug is evident in the currently running process. Sometimes, processes hang in the kernel when they shouldn't because they've @@ -2516,7 +2446,7 @@ Now what you do is this: - o detach from the current thread + - detach from the current thread:: (UML gdb) det @@ -2525,7 +2455,7 @@ - o attach to the thread you are interested in + - attach to the thread you are interested in:: (UML gdb) att <host pid> @@ -2534,7 +2464,7 @@ - o look at its stack and anything else of interest + - look at its stack and anything else of interest:: (UML gdb) bt @@ -2545,18 +2475,14 @@ Note that you can't do anything at this point that requires that a process execute, e.g. calling a function - o when you're done looking at that process, reattach to the current - thread and continue it + - when you're done looking at that process, reattach to the current + thread and continue it:: (UML gdb) att 1 - - - - (UML gdb) c @@ -2569,12 +2495,13 @@ - 11.3. Running ddd on UML +11.3. Running ddd on UML +------------------------- ddd works on UML, but requires a special kludge. The process goes like this: - o Start ddd + - Start ddd:: host% ddd linux @@ -2583,14 +2510,14 @@ - o With ps, get the pid of the gdb that ddd started. You can ask the + - With ps, get the pid of the gdb that ddd started. You can ask the gdb to tell you, but for some reason that confuses things and causes a hang. - o run UML with 'debug=parent gdb-pid=<pid>' added to the command line + - run UML with 'debug=parent gdb-pid=<pid>' added to the command line - it will just sit there after you hit return - o type 'att 1' to the ddd gdb and you will see something like + - type 'att 1' to the ddd gdb and you will see something like:: 0xa013dc51 in __kill () @@ -2602,12 +2529,14 @@ - o At this point, type 'c', UML will boot up, and you can use ddd just + - At this point, type 'c', UML will boot up, and you can use ddd just as you do on any other process. - 11.4. Debugging modules +11.4. Debugging modules +------------------------ + gdb has support for debugging code which is dynamically loaded into the process. This support is what is needed to debug kernel modules @@ -2629,7 +2558,8 @@ First, you must tell it where your modules are. There is a list in - the script that looks like this: + the script that looks like this:: + set MODULE_PATHS { "fat" "/usr/src/uml/linux-2.4.18/fs/fat/fat.o" "isofs" "/usr/src/uml/linux-2.4.18/fs/isofs/isofs.o" @@ -2641,9 +2571,7 @@ You change that to list the names and paths of the modules that you are going to debug. Then you run it from the toplevel directory of - your UML pool and it basically tells you what to do: - - + your UML pool and it basically tells you what to do:: ******** GDB pid is 21903 ******** @@ -2666,7 +2594,7 @@ After you run UML and it sits there doing nothing, you hit return at - the 'att 1' and continue it: + the 'att 1' and continue it:: Attaching to program: /home/jdike/linux/2.4/um/./linux, process 1 @@ -2678,63 +2606,48 @@ At this point, you debug normally. When you insmod something, the - expect magic will kick in and you'll see something like: - - - - - - - - - - - - - - - - - - *** Module hostfs loaded *** - Breakpoint 1, sys_init_module (name_user=0x805abb0 "hostfs", - mod_user=0x8070e00) at module.c:349 - 349 char *name, *n_name, *name_tmp = NULL; - (UML gdb) finish - Run till exit from #0 sys_init_module (name_user=0x805abb0 "hostfs", - mod_user=0x8070e00) at module.c:349 - 0xa00e2e23 in execute_syscall (r=0xa8140284) at syscall_kern.c:411 - 411 else res = EXECUTE_SYSCALL(syscall, regs); - Value returned is $1 = 0 - (UML gdb) - p/x (int)module_list + module_list->size_of_struct - - $2 = 0xa9021054 - (UML gdb) symbol-file ./linux - Load new symbol table from "./linux"? (y or n) y - Reading symbols from ./linux... - done. - (UML gdb) - add-symbol-file /home/jdike/linux/2.4/um/arch/um/fs/hostfs/hostfs.o 0xa9021054 - - add symbol table from file "/home/jdike/linux/2.4/um/arch/um/fs/hostfs/hostfs.o" at - .text_addr = 0xa9021054 - (y or n) y - - Reading symbols from /home/jdike/linux/2.4/um/arch/um/fs/hostfs/hostfs.o... - done. - (UML gdb) p *module_list - $1 = {size_of_struct = 84, next = 0xa0178720, name = 0xa9022de0 "hostfs", - size = 9016, uc = {usecount = {counter = 0}, pad = 0}, flags = 1, - nsyms = 57, ndeps = 0, syms = 0xa9023170, deps = 0x0, refs = 0x0, - init = 0xa90221f0 <init_hostfs>, cleanup = 0xa902222c <exit_hostfs>, - ex_table_start = 0x0, ex_table_end = 0x0, persist_start = 0x0, - persist_end = 0x0, can_unload = 0, runsize = 0, kallsyms_start = 0x0, - kallsyms_end = 0x0, - archdata_start = 0x1b855 <Address 0x1b855 out of bounds>, - archdata_end = 0xe5890000 <Address 0xe5890000 out of bounds>, - kernel_data = 0xf689c35d <Address 0xf689c35d out of bounds>} - >> Finished loading symbols for hostfs ... + expect magic will kick in and you'll see something like:: + + + *** Module hostfs loaded *** + Breakpoint 1, sys_init_module (name_user=0x805abb0 "hostfs", + mod_user=0x8070e00) at module.c:349 + 349 char *name, *n_name, *name_tmp = NULL; + (UML gdb) finish + Run till exit from #0 sys_init_module (name_user=0x805abb0 "hostfs", + mod_user=0x8070e00) at module.c:349 + 0xa00e2e23 in execute_syscall (r=0xa8140284) at syscall_kern.c:411 + 411 else res = EXECUTE_SYSCALL(syscall, regs); + Value returned is $1 = 0 + (UML gdb) + p/x (int)module_list + module_list->size_of_struct + + $2 = 0xa9021054 + (UML gdb) symbol-file ./linux + Load new symbol table from "./linux"? (y or n) y + Reading symbols from ./linux... + done. + (UML gdb) + add-symbol-file /home/jdike/linux/2.4/um/arch/um/fs/hostfs/hostfs.o 0xa9021054 + + add symbol table from file "/home/jdike/linux/2.4/um/arch/um/fs/hostfs/hostfs.o" at + .text_addr = 0xa9021054 + (y or n) y + + Reading symbols from /home/jdike/linux/2.4/um/arch/um/fs/hostfs/hostfs.o... + done. + (UML gdb) p *module_list + $1 = {size_of_struct = 84, next = 0xa0178720, name = 0xa9022de0 "hostfs", + size = 9016, uc = {usecount = {counter = 0}, pad = 0}, flags = 1, + nsyms = 57, ndeps = 0, syms = 0xa9023170, deps = 0x0, refs = 0x0, + init = 0xa90221f0 <init_hostfs>, cleanup = 0xa902222c <exit_hostfs>, + ex_table_start = 0x0, ex_table_end = 0x0, persist_start = 0x0, + persist_end = 0x0, can_unload = 0, runsize = 0, kallsyms_start = 0x0, + kallsyms_end = 0x0, + archdata_start = 0x1b855 <Address 0x1b855 out of bounds>, + archdata_end = 0xe5890000 <Address 0xe5890000 out of bounds>, + kernel_data = 0xf689c35d <Address 0xf689c35d out of bounds>} + >> Finished loading symbols for hostfs ... @@ -2744,7 +2657,7 @@ Boot the kernel under the debugger and load the module with insmod or - modprobe. With gdb, do: + modprobe. With gdb, do:: (UML gdb) p module_list @@ -2758,12 +2671,12 @@ the name fields until find the module you want to debug. Take the address of that structure, and add module.size_of_struct (which in 2.4.10 kernels is 96 (0x60)) to it. Gdb can make this hard addition - for you :-): + for you :-):: - (UML gdb) - printf "%#x\n", (int)module_list module_list->size_of_struct + (UML gdb) + printf "%#x\n", (int)module_list module_list->size_of_struct @@ -2771,7 +2684,7 @@ The offset from the module start occasionally changes (before 2.4.0, it was module.size_of_struct + 4), so it's a good idea to check the init and cleanup addresses once in a while, as describe below. Now - do: + do:: (UML gdb) @@ -2786,7 +2699,7 @@ If there's any doubt that you got the offset right, like breakpoints appear not to work, or they're appearing in the wrong place, you can check it by looking at the module structure. The init and cleanup - fields should look like: + fields should look like:: init = 0x588066b0 <init_hostfs>, cleanup = 0x588066c0 <exit_hostfs> @@ -2801,7 +2714,7 @@ When you want to load in a new version of the module, you need to get gdb to forget about the old one. The only way I've found to do that - is to tell gdb to forget about all symbols that it knows about: + is to tell gdb to forget about all symbols that it knows about:: (UML gdb) symbol-file @@ -2809,7 +2722,7 @@ - Then reload the symbols from the kernel binary: + Then reload the symbols from the kernel binary:: (UML gdb) symbol-file /path/to/kernel @@ -2823,17 +2736,19 @@ - 11.5. Attaching gdb to the kernel +11.5. Attaching gdb to the kernel +---------------------------------- If you don't have the kernel running under gdb, you can attach gdb to it later by sending the tracing thread a SIGUSR1. The first line of - the console output identifies its pid: + the console output identifies its pid:: + tracing thread pid = 20093 - When you send it the signal: + When you send it the signal:: host% kill -USR1 20093 @@ -2845,7 +2760,7 @@ If you have the mconsole compiled into UML, then the mconsole client - can be used to start gdb: + can be used to start gdb:: (mconsole) (mconsole) config gdb=xterm @@ -2857,7 +2772,8 @@ - 11.6. Using alternate debuggers +11.6. Using alternate debuggers +-------------------------------- UML has support for attaching to an already running debugger rather than starting gdb itself. This is present in CVS as of 17 Apr 2001. @@ -2886,7 +2802,7 @@ An example of an alternate debugger is strace. You can strace the actual kernel as follows: - o Run the following in a shell + - Run the following in a shell:: host% @@ -2894,13 +2810,13 @@ - o Run UML with 'debug' and 'gdb-pid=<pid>' with the pid printed out + - Run UML with 'debug' and 'gdb-pid=<pid>' with the pid printed out by the previous command - o Hit return in the shell, and UML will start running, and strace + - Hit return in the shell, and UML will start running, and strace output will start accumulating in the output file. - Note that this is different from running + Note that this is different from running:: host% strace ./linux @@ -2917,95 +2833,57 @@ - 12. Kernel debugging examples +12. Kernel debugging examples +============================== - 12.1. The case of the hung fsck +12.1. The case of the hung fsck +-------------------------------- When booting up the kernel, fsck failed, and dropped me into a shell - to fix things up. I ran fsck -y, which hung: - - - - - - - - - - - - - - - - - - - - - - - - - + to fix things up. I ran fsck -y, which hung:: + Setting hostname uml [ OK ] + Checking root filesystem + /dev/fhd0 was not cleanly unmounted, check forced. + Error reading block 86894 (Attempt to read block from filesystem resulted in short read) while reading indirect blocks of inode 19780. + /dev/fhd0: UNEXPECTED INCONSISTENCY; RUN fsck MANUALLY. + (i.e., without -a or -p options) + [ FAILED ] + *** An error occurred during the file system check. + *** Dropping you to a shell; the system will reboot + *** when you leave the shell. + Give root password for maintenance + (or type Control-D for normal startup): + [root@uml /root]# fsck -y /dev/fhd0 + fsck -y /dev/fhd0 + Parallelizing fsck version 1.14 (9-Jan-1999) + e2fsck 1.14, 9-Jan-1999 for EXT2 FS 0.5b, 95/08/09 + /dev/fhd0 contains a file system with errors, check forced. + Pass 1: Checking inodes, blocks, and sizes + Error reading block 86894 (Attempt to read block from filesystem resulted in short read) while reading indirect blocks of inode 19780. Ignore error? yes + Inode 19780, i_blocks is 1548, should be 540. Fix? yes + Pass 2: Checking directory structure + Error reading block 49405 (Attempt to read block from filesystem resulted in short read). Ignore error? yes + Directory inode 11858, block 0, offset 0: directory corrupted + Salvage? yes + Missing '.' in directory inode 11858. + Fix? yes - - - Setting hostname uml [ OK ] - Checking root filesystem - /dev/fhd0 was not cleanly unmounted, check forced. - Error reading block 86894 (Attempt to read block from filesystem resulted in short read) while reading indirect blocks of inode 19780. - - /dev/fhd0: UNEXPECTED INCONSISTENCY; RUN fsck MANUALLY. - (i.e., without -a or -p options) - [ FAILED ] - - *** An error occurred during the file system check. - *** Dropping you to a shell; the system will reboot - *** when you leave the shell. - Give root password for maintenance - (or type Control-D for normal startup): - - [root@uml /root]# fsck -y /dev/fhd0 - fsck -y /dev/fhd0 - Parallelizing fsck version 1.14 (9-Jan-1999) - e2fsck 1.14, 9-Jan-1999 for EXT2 FS 0.5b, 95/08/09 - /dev/fhd0 contains a file system with errors, check forced. - Pass 1: Checking inodes, blocks, and sizes - Error reading block 86894 (Attempt to read block from filesystem resulted in short read) while reading indirect blocks of inode 19780. Ignore error? yes - - Inode 19780, i_blocks is 1548, should be 540. Fix? yes - - Pass 2: Checking directory structure - Error reading block 49405 (Attempt to read block from filesystem resulted in short read). Ignore error? yes - - Directory inode 11858, block 0, offset 0: directory corrupted - Salvage? yes - - Missing '.' in directory inode 11858. - Fix? yes - - Missing '..' in directory inode 11858. - Fix? yes - - - + Missing '..' in directory inode 11858. + Fix? yes The standard drill in this sort of situation is to fire up gdb on the signal thread, which, in this case, was pid 1935. In another window, - I run gdb and attach pid 1935. - - + I run gdb and attach pid 1935:: ~/linux/2.3.26/um 1016: gdb linux @@ -3022,11 +2900,7 @@ 0x100756d9 in __wait4 () - - - - - Let's see what's currently running: + Let's see what's currently running:: @@ -3041,7 +2915,7 @@ reason and never woke up. - Let's guess that the last process in the process list is fsck: + Let's guess that the last process in the process list is fsck:: @@ -3052,7 +2926,7 @@ - It is, so let's see what it thinks it's up to: + It is, so let's see what it thinks it's up to:: @@ -3068,8 +2942,6 @@ - - The interesting things here are the fact that its .thread.syscall.id is __NR_write (see the big switch in arch/um/kernel/syscall_kern.c or the defines in include/asm-um/arch/unistd.h), and that it never @@ -3081,30 +2953,20 @@ The fact that it never returned from write means that its stack should be fairly interesting. Its pid is 1980 (.thread.extern_pid). That process is being ptraced by the signal thread, so it must be detached - before gdb can attach it: - - - - - - + before gdb can attach it:: + (gdb) call detach(1980) - (gdb) call detach(1980) - - Program received signal SIGSEGV, Segmentation fault. - <function called from gdb> - The program being debugged stopped while in a function called from GDB. - When the function (detach) is done executing, GDB will silently - stop (instead of continuing to evaluate the expression containing - the function call). - (gdb) call detach(1980) - $15 = 0 - - - + Program received signal SIGSEGV, Segmentation fault. + <function called from gdb> + The program being debugged stopped while in a function called from GDB. + When the function (detach) is done executing, GDB will silently + stop (instead of continuing to evaluate the expression containing + the function call). + (gdb) call detach(1980) + $15 = 0 The first detach segfaults for some reason, and the second one @@ -3112,7 +2974,7 @@ Now I detach from the signal thread, attach to the fsck thread, and - look at its stack: + look at its stack:: (gdb) det @@ -3152,14 +3014,14 @@ - The interesting things here are : + The interesting things here are: - o There are two segfaults on this stack (frames 9 and 14) + - There are two segfaults on this stack (frames 9 and 14) - o The first faulting address (frame 11) is 0x50000800 + - The first faulting address (frame 11) is 0x50000800:: - (gdb) p (void *)1342179328 - $16 = (void *) 0x50000800 + (gdb) p (void *)1342179328 + $16 = (void *) 0x50000800 @@ -3175,7 +3037,7 @@ However, the more immediate problem is that second segfault and I'm going to concentrate on that. First, I want to see where the fault - happened, so I have to go look at the sigcontent struct in frame 8: + happened, so I have to go look at the sigcontent struct in frame 8:: @@ -3211,7 +3073,7 @@ - That's not very useful, so I'll try a more manual method: + That's not very useful, so I'll try a more manual method:: (gdb) p *((struct sigcontext *) (&sig + 1)) @@ -3224,7 +3086,7 @@ - The ip is in handle_mm_fault: + The ip is in handle_mm_fault:: (gdb) p (void *)268480945 @@ -3236,7 +3098,7 @@ - Specifically, it's in pte_alloc: + Specifically, it's in pte_alloc:: (gdb) i line *$20 @@ -3249,7 +3111,7 @@ To find where in handle_mm_fault this is, I'll jump forward in the - code until I see an address in that procedure: + code until I see an address in that procedure:: @@ -3286,21 +3148,21 @@ Something is apparently wrong with the page tables or vma_structs, so - lets go back to frame 11 and have a look at them: + lets go back to frame 11 and have a look at them:: - #11 0x1006c0aa in segv (address=1342179328, is_write=2) at trap_kern.c:50 - 50 handle_mm_fault(current, vma, address, is_write); - (gdb) call pgd_offset_proc(vma->vm_mm, address) - $22 = (pgd_t *) 0x80a548c + #11 0x1006c0aa in segv (address=1342179328, is_write=2) at trap_kern.c:50 + 50 handle_mm_fault(current, vma, address, is_write); + (gdb) call pgd_offset_proc(vma->vm_mm, address) + $22 = (pgd_t *) 0x80a548c That's pretty bogus. Page tables aren't supposed to be in process - text or data areas. Let's see what's in the vma: + text or data areas. Let's see what's in the vma:: (gdb) p *vma @@ -3325,12 +3187,9 @@ - - This also pretty bogus. With all of the 0x80xxxxx and 0xaffffxxx addresses, this is looking like a stack was plonked down on top of - these structures. Maybe it's a stack overflow from the next page: - + these structures. Maybe it's a stack overflow from the next page:: (gdb) p vma @@ -3338,52 +3197,36 @@ - - That's towards the lower quarter of the page, so that would have to - have been pretty heavy stack overflow: - - - - - - - - - - - - - - - (gdb) x/100x $25 - 0x507d2434: 0x507d2434 0x00000000 0x08048000 0x080a4f8c - 0x507d2444: 0x00000000 0x080a79e0 0x080a8c94 0x080d1000 - 0x507d2454: 0xaffffdb0 0xaffffe63 0xaffffe7a 0xaffffe7a - 0x507d2464: 0xafffffec 0x00000062 0x0000008a 0x00000000 - 0x507d2474: 0x00000000 0x00000000 0x00000000 0x00000000 - 0x507d2484: 0x00000000 0x00000000 0x00000000 0x00000000 - 0x507d2494: 0x00000000 0x00000000 0x507d2fe0 0x00000000 - 0x507d24a4: 0x00000000 0x00000000 0x00000000 0x00000000 - 0x507d24b4: 0x00000000 0x00000000 0x00000000 0x00000000 - 0x507d24c4: 0x00000000 0x00000000 0x00000000 0x00000000 - 0x507d24d4: 0x00000000 0x00000000 0x00000000 0x00000000 - 0x507d24e4: 0x00000000 0x00000000 0x00000000 0x00000000 - 0x507d24f4: 0x00000000 0x00000000 0x00000000 0x00000000 - 0x507d2504: 0x00000000 0x00000000 0x00000000 0x00000000 - 0x507d2514: 0x00000000 0x00000000 0x00000000 0x00000000 - 0x507d2524: 0x00000000 0x00000000 0x00000000 0x00000000 - 0x507d2534: 0x00000000 0x00000000 0x507d25dc 0x00000000 - 0x507d2544: 0x00000000 0x00000000 0x00000000 0x00000000 - 0x507d2554: 0x00000000 0x00000000 0x00000000 0x00000000 - 0x507d2564: 0x00000000 0x00000000 0x00000000 0x00000000 - 0x507d2574: 0x00000000 0x00000000 0x00000000 0x00000000 - 0x507d2584: 0x00000000 0x00000000 0x00000000 0x00000000 - 0x507d2594: 0x00000000 0x00000000 0x00000000 0x00000000 - 0x507d25a4: 0x00000000 0x00000000 0x00000000 0x00000000 - 0x507d25b4: 0x00000000 0x00000000 0x00000000 0x00000000 - - + have been pretty heavy stack overflow:: + + + (gdb) x/100x $25 + 0x507d2434: 0x507d2434 0x00000000 0x08048000 0x080a4f8c + 0x507d2444: 0x00000000 0x080a79e0 0x080a8c94 0x080d1000 + 0x507d2454: 0xaffffdb0 0xaffffe63 0xaffffe7a 0xaffffe7a + 0x507d2464: 0xafffffec 0x00000062 0x0000008a 0x00000000 + 0x507d2474: 0x00000000 0x00000000 0x00000000 0x00000000 + 0x507d2484: 0x00000000 0x00000000 0x00000000 0x00000000 + 0x507d2494: 0x00000000 0x00000000 0x507d2fe0 0x00000000 + 0x507d24a4: 0x00000000 0x00000000 0x00000000 0x00000000 + 0x507d24b4: 0x00000000 0x00000000 0x00000000 0x00000000 + 0x507d24c4: 0x00000000 0x00000000 0x00000000 0x00000000 + 0x507d24d4: 0x00000000 0x00000000 0x00000000 0x00000000 + 0x507d24e4: 0x00000000 0x00000000 0x00000000 0x00000000 + 0x507d24f4: 0x00000000 0x00000000 0x00000000 0x00000000 + 0x507d2504: 0x00000000 0x00000000 0x00000000 0x00000000 + 0x507d2514: 0x00000000 0x00000000 0x00000000 0x00000000 + 0x507d2524: 0x00000000 0x00000000 0x00000000 0x00000000 + 0x507d2534: 0x00000000 0x00000000 0x507d25dc 0x00000000 + 0x507d2544: 0x00000000 0x00000000 0x00000000 0x00000000 + 0x507d2554: 0x00000000 0x00000000 0x00000000 0x00000000 + 0x507d2564: 0x00000000 0x00000000 0x00000000 0x00000000 + 0x507d2574: 0x00000000 0x00000000 0x00000000 0x00000000 + 0x507d2584: 0x00000000 0x00000000 0x00000000 0x00000000 + 0x507d2594: 0x00000000 0x00000000 0x00000000 0x00000000 + 0x507d25a4: 0x00000000 0x00000000 0x00000000 0x00000000 + 0x507d25b4: 0x00000000 0x00000000 0x00000000 0x00000000 @@ -3399,65 +3242,53 @@ on will be somewhat clearer. - 12.2. Episode 2: The case of the hung fsck +12.2. Episode 2: The case of the hung fsck +------------------------------------------- After setting a trap in the SEGV handler for accesses to the signal thread's stack, I reran the kernel. - fsck hung again, this time by hitting the trap: - - + fsck hung again, this time by hitting the trap:: + Setting hostname uml [ OK ] + Checking root filesystem + /dev/fhd0 contains a file system with errors, check forced. + Error reading block 86894 (Attempt to read block from filesystem resulted in short read) while reading indirect blocks of inode 19780. + /dev/fhd0: UNEXPECTED INCONSISTENCY; RUN fsck MANUALLY. + (i.e., without -a or -p options) + [ FAILED ] + *** An error occurred during the file system check. + *** Dropping you to a shell; the system will reboot + *** when you leave the shell. + Give root password for maintenance + (or type Control-D for normal startup): + [root@uml /root]# fsck -y /dev/fhd0 + fsck -y /dev/fhd0 + Parallelizing fsck version 1.14 (9-Jan-1999) + e2fsck 1.14, 9-Jan-1999 for EXT2 FS 0.5b, 95/08/09 + /dev/fhd0 contains a file system with errors, check forced. + Pass 1: Checking inodes, blocks, and sizes + Error reading block 86894 (Attempt to read block from filesystem resulted in short read) while reading indirect blocks of inode 19780. Ignore error? yes + Pass 2: Checking directory structure + Error reading block 49405 (Attempt to read block from filesystem resulted in short read). Ignore error? yes + Directory inode 11858, block 0, offset 0: directory corrupted + Salvage? yes + Missing '.' in directory inode 11858. + Fix? yes + Missing '..' in directory inode 11858. + Fix? yes - - - - Setting hostname uml [ OK ] - Checking root filesystem - /dev/fhd0 contains a file system with errors, check forced. - Error reading block 86894 (Attempt to read block from filesystem resulted in short read) while reading indirect blocks of inode 19780. - - /dev/fhd0: UNEXPECTED INCONSISTENCY; RUN fsck MANUALLY. - (i.e., without -a or -p options) - [ FAILED ] - - *** An error occurred during the file system check. - *** Dropping you to a shell; the system will reboot - *** when you leave the shell. - Give root password for maintenance - (or type Control-D for normal startup): - - [root@uml /root]# fsck -y /dev/fhd0 - fsck -y /dev/fhd0 - Parallelizing fsck version 1.14 (9-Jan-1999) - e2fsck 1.14, 9-Jan-1999 for EXT2 FS 0.5b, 95/08/09 - /dev/fhd0 contains a file system with errors, check forced. - Pass 1: Checking inodes, blocks, and sizes - Error reading block 86894 (Attempt to read block from filesystem resulted in short read) while reading indirect blocks of inode 19780. Ignore error? yes - - Pass 2: Checking directory structure - Error reading block 49405 (Attempt to read block from filesystem resulted in short read). Ignore error? yes - - Directory inode 11858, block 0, offset 0: directory corrupted - Salvage? yes - - Missing '.' in directory inode 11858. - Fix? yes - - Missing '..' in directory inode 11858. - Fix? yes - - Untested (4127) [100fe44c]: trap_kern.c line 31 + Untested (4127) [100fe44c]: trap_kern.c line 31 @@ -3465,7 +3296,7 @@ I need to get the signal thread to detach from pid 4127 so that I can attach to it with gdb. This is done by sending it a SIGUSR1, which is - caught by the signal thread, which detaches the process: + caught by the signal thread, which detaches the process:: kill -USR1 4127 @@ -3474,31 +3305,20 @@ - Now I can run gdb on it: - - - - - - - + Now I can run gdb on it:: - - - - - ~/linux/2.3.26/um 1034: gdb linux - GNU gdb 4.17.0.11 with Linux support - Copyright 1998 Free Software Foundation, Inc. - GDB is free software, covered by the GNU General Public License, and you are - welcome to change it and/or distribute copies of it under certain conditions. - Type "show copying" to see the conditions. - There is absolutely no warranty for GDB. Type "show warranty" for details. - This GDB was configured as "i386-redhat-linux"... - (gdb) att 4127 - Attaching to program `/home/dike/linux/2.3.26/um/linux', Pid 4127 - 0x10075891 in __libc_nanosleep () + ~/linux/2.3.26/um 1034: gdb linux + GNU gdb 4.17.0.11 with Linux support + Copyright 1998 Free Software Foundation, Inc. + GDB is free software, covered by the GNU General Public License, and you are + welcome to change it and/or distribute copies of it under certain conditions. + Type "show copying" to see the conditions. + There is absolutely no warranty for GDB. Type "show warranty" for details. + This GDB was configured as "i386-redhat-linux"... + (gdb) att 4127 + Attaching to program `/home/dike/linux/2.3.26/um/linux', Pid 4127 + 0x10075891 in __libc_nanosleep () @@ -3506,7 +3326,7 @@ The backtrace shows that it was in a write and that the fault address (address in frame 3) is 0x50000800, which is right in the middle of - the signal thread's stack page: + the signal thread's stack page:: (gdb) bt @@ -3540,58 +3360,48 @@ - - Going up the stack to the segv_handler frame and looking at where in the code the access happened shows that it happened near line 110 of - block_dev.c: - - - - - - - - - - (gdb) up - #1 0x1007584d in __sleep (seconds=1000000) - at ../sysdeps/unix/sysv/linux/sleep.c:78 - ../sysdeps/unix/sysv/linux/sleep.c:78: No such file or directory. - (gdb) - #2 0x1006ce9a in stop () at user_util.c:191 - 191 while(1) sleep(1000000); - (gdb) - #3 0x1006bf88 in segv (address=1342179328, is_write=2) at trap_kern.c:31 - 31 KERN_UNTESTED(); - (gdb) - #4 0x1006c628 in segv_handler (sc=0x5006eaf8) at trap_user.c:174 - 174 segv(sc->cr2, sc->err & 2); - (gdb) p *sc - $1 = {gs = 0, __gsh = 0, fs = 0, __fsh = 0, es = 43, __esh = 0, ds = 43, - __dsh = 0, edi = 1342179328, esi = 134973440, ebp = 1342631484, - esp = 1342630864, ebx = 256, edx = 0, ecx = 256, eax = 1024, trapno = 14, - err = 6, eip = 268550834, cs = 35, __csh = 0, eflags = 66070, - esp_at_signal = 1342630864, ss = 43, __ssh = 0, fpstate = 0x0, oldmask = 0, - cr2 = 1342179328} - (gdb) p (void *)268550834 - $2 = (void *) 0x1001c2b2 - (gdb) i sym $2 - block_write + 1090 in section .text - (gdb) i line *$2 - Line 209 of "/home/dike/linux/2.3.26/um/include/asm/arch/string.h" - starts at address 0x1001c2a1 <block_write+1073> - and ends at 0x1001c2bf <block_write+1103>. - (gdb) i line *0x1001c2c0 - Line 110 of "block_dev.c" starts at address 0x1001c2bf <block_write+1103> - and ends at 0x1001c2e3 <block_write+1139>. - - + block_dev.c:: + + + + (gdb) up + #1 0x1007584d in __sleep (seconds=1000000) + at ../sysdeps/unix/sysv/linux/sleep.c:78 + ../sysdeps/unix/sysv/linux/sleep.c:78: No such file or directory. + (gdb) + #2 0x1006ce9a in stop () at user_util.c:191 + 191 while(1) sleep(1000000); + (gdb) + #3 0x1006bf88 in segv (address=1342179328, is_write=2) at trap_kern.c:31 + 31 KERN_UNTESTED(); + (gdb) + #4 0x1006c628 in segv_handler (sc=0x5006eaf8) at trap_user.c:174 + 174 segv(sc->cr2, sc->err & 2); + (gdb) p *sc + $1 = {gs = 0, __gsh = 0, fs = 0, __fsh = 0, es = 43, __esh = 0, ds = 43, + __dsh = 0, edi = 1342179328, esi = 134973440, ebp = 1342631484, + esp = 1342630864, ebx = 256, edx = 0, ecx = 256, eax = 1024, trapno = 14, + err = 6, eip = 268550834, cs = 35, __csh = 0, eflags = 66070, + esp_at_signal = 1342630864, ss = 43, __ssh = 0, fpstate = 0x0, oldmask = 0, + cr2 = 1342179328} + (gdb) p (void *)268550834 + $2 = (void *) 0x1001c2b2 + (gdb) i sym $2 + block_write + 1090 in section .text + (gdb) i line *$2 + Line 209 of "/home/dike/linux/2.3.26/um/include/asm/arch/string.h" + starts at address 0x1001c2a1 <block_write+1073> + and ends at 0x1001c2bf <block_write+1103>. + (gdb) i line *0x1001c2c0 + Line 110 of "block_dev.c" starts at address 0x1001c2bf <block_write+1103> + and ends at 0x1001c2e3 <block_write+1139>. Looking at the source shows that the fault happened during a call to - copy_from_user to copy the data into the kernel: + copy_from_user to copy the data into the kernel:: 107 count -= chars; @@ -3601,10 +3411,8 @@ - - p is the pointer which must contain 0x50000800, since buf contains - 0x80b8800 (frame 8 above). It is defined as: + 0x80b8800 (frame 8 above). It is defined as:: p = offset + bh->b_data; @@ -3615,24 +3423,22 @@ I need to figure out what bh is, and it just so happens that bh is passed as an argument to mark_buffer_uptodate and mark_buffer_dirty a - few lines later, so I do a little disassembly: - - + few lines later, so I do a little disassembly:: - (gdb) disas 0x1001c2bf 0x1001c2e0 - Dump of assembler code from 0x1001c2bf to 0x1001c2d0: - 0x1001c2bf <block_write+1103>: addl %eax,0xc(%ebp) - 0x1001c2c2 <block_write+1106>: movl 0xfffffdd4(%ebp),%edx - 0x1001c2c8 <block_write+1112>: btsl $0x0,0x18(%edx) - 0x1001c2cd <block_write+1117>: btsl $0x1,0x18(%edx) - 0x1001c2d2 <block_write+1122>: sbbl %ecx,%ecx - 0x1001c2d4 <block_write+1124>: testl %ecx,%ecx - 0x1001c2d6 <block_write+1126>: jne 0x1001c2e3 <block_write+1139> - 0x1001c2d8 <block_write+1128>: pushl $0x0 - 0x1001c2da <block_write+1130>: pushl %edx - 0x1001c2db <block_write+1131>: call 0x1001819c <__mark_buffer_dirty> - End of assembler dump. + (gdb) disas 0x1001c2bf 0x1001c2e0 + Dump of assembler code from 0x1001c2bf to 0x1001c2d0: + 0x1001c2bf <block_write+1103>: addl %eax,0xc(%ebp) + 0x1001c2c2 <block_write+1106>: movl 0xfffffdd4(%ebp),%edx + 0x1001c2c8 <block_write+1112>: btsl $0x0,0x18(%edx) + 0x1001c2cd <block_write+1117>: btsl $0x1,0x18(%edx) + 0x1001c2d2 <block_write+1122>: sbbl %ecx,%ecx + 0x1001c2d4 <block_write+1124>: testl %ecx,%ecx + 0x1001c2d6 <block_write+1126>: jne 0x1001c2e3 <block_write+1139> + 0x1001c2d8 <block_write+1128>: pushl $0x0 + 0x1001c2da <block_write+1130>: pushl %edx + 0x1001c2db <block_write+1131>: call 0x1001819c <__mark_buffer_dirty> + End of assembler dump. @@ -3640,7 +3446,7 @@ At that point, bh is in %edx (address 0x1001c2da), which is calculated at 0x1001c2c2 as %ebp + 0xfffffdd4, so I figure exactly what that is, - taking %ebp from the sigcontext_struct above: + taking %ebp from the sigcontext_struct above:: (gdb) p (void *)1342631484 @@ -3657,7 +3463,7 @@ Now, I look at the structure to see what's in it, and particularly, - what its b_data field contains: + what its b_data field contains:: (gdb) p *((struct buffer_head *)0x50100200) @@ -3682,18 +3488,18 @@ The b_page field is a pointer to the page_struct representing the 0x50000000 page. Looking at it shows the kernel's idea of the state - of that page: + of that page:: - (gdb) p *$13.b_page - $17 = {list = {next = 0x50004a5c, prev = 0x100c5174}, mapping = 0x0, - index = 0, next_hash = 0x0, count = {counter = 1}, flags = 132, lru = { - next = 0x50008460, prev = 0x50019350}, wait = { - lock = <optimized out or zero length>, task_list = {next = 0x50004024, - prev = 0x50004024}, __magic = 1342193708, __creator = 0}, - pprev_hash = 0x0, buffers = 0x501002c0, virtual = 1342177280, - zone = 0x100c5160} + (gdb) p *$13.b_page + $17 = {list = {next = 0x50004a5c, prev = 0x100c5174}, mapping = 0x0, + index = 0, next_hash = 0x0, count = {counter = 1}, flags = 132, lru = { + next = 0x50008460, prev = 0x50019350}, wait = { + lock = <optimized out or zero length>, task_list = {next = 0x50004024, + prev = 0x50004024}, __magic = 1342193708, __creator = 0}, + pprev_hash = 0x0, buffers = 0x501002c0, virtual = 1342177280, + zone = 0x100c5160} @@ -3702,7 +3508,7 @@ Some sanity-checking: the virtual field shows the "virtual" address of this page, which in this kernel is the same as its "physical" address, and the page_struct itself should be mem_map[0], since it represents - the first page of memory: + the first page of memory:: @@ -3719,7 +3525,7 @@ Now to check out the page_struct itself. In particular, the flags - field shows whether the page is considered free or not: + field shows whether the page is considered free or not:: (gdb) p (void *)132 @@ -3739,7 +3545,7 @@ In my setup_arch procedure, I have the following code which looks just - fine: + fine:: @@ -3762,7 +3568,7 @@ Stepping into init_bootmem, and looking at bootmem_map before looking - at what it contains shows the following: + at what it contains shows the following:: @@ -3788,18 +3594,20 @@ - 13. What to do when UML doesn't work +13. What to do when UML doesn't work +===================================== - 13.1. Strange compilation errors when you build from source +13.1. Strange compilation errors when you build from source +------------------------------------------------------------ As of test11, it is necessary to have "ARCH=um" in the environment or on the make command line for all steps in building UML, including clean, distclean, or mrproper, config, menuconfig, or xconfig, dep, and linux. If you forget for any of them, the i386 build seems to - contaminate the UML build. If this happens, start from scratch with + contaminate the UML build. If this happens, start from scratch with:: host% @@ -3811,7 +3619,7 @@ and repeat the build process with ARCH=um on all the steps. - See ``Compiling the kernel and modules'' for more details. + See :ref:`Compiling_the_kernel_and_modules` for more details. Another cause of strange compilation errors is building UML in @@ -3824,11 +3632,11 @@ - 13.3. A variety of panics and hangs with /tmp on a reiserfs filesys- - tem +13.3. A variety of panics and hangs with /tmp on a reiserfs filesystem +----------------------------------------------------------------------- I saw this on reiserfs 3.5.21 and it seems to be fixed in 3.5.27. - Panics preceded by + Panics preceded by:: Detaching pid nnnn @@ -3854,17 +3662,19 @@ - 13.5. UML doesn't work when /tmp is an NFS filesystem +13.5. UML doesn't work when /tmp is an NFS filesystem +------------------------------------------------------ This seems to be a similar situation with the ReiserFS problem above. Some versions of NFS seems not to handle mmap correctly, which UML depends on. The workaround is have /tmp be a non-NFS directory. - 13.6. UML hangs on boot when compiled with gprof support +13.6. UML hangs on boot when compiled with gprof support +--------------------------------------------------------- If you build UML with gprof support and, early in the boot, it does - this + this:: kernel BUG at page_alloc.c:100! @@ -3878,10 +3688,11 @@ - 13.7. syslogd dies with a SIGTERM on startup +13.7. syslogd dies with a SIGTERM on startup +--------------------------------------------- The exact boot error depends on the distribution that you're booting, - but Debian produces this: + but Debian produces this:: /etc/rc2.d/S10sysklogd: line 49: 93 Terminated @@ -3891,23 +3702,21 @@ This is a syslogd bug. There's a race between a parent process - installing a signal handler and its child sending the signal. See - this uml-devel post <http://www.geocrawler.com/lists/3/Source- - Forge/709/0/6612801> for the details. + installing a signal handler and its child sending the signal. - 13.8. TUN/TAP networking doesn't work on a 2.4 host +13.8. TUN/TAP networking doesn't work on a 2.4 host +---------------------------------------------------- - There are a couple of problems which were - <http://www.geocrawler.com/lists/3/SourceForge/597/0/> name="pointed - out"> by Tim Robinson <timro at trkr dot net> + There are a couple of problems which were reported by + Tim Robinson <timro at trkr dot net> - o It doesn't work on hosts running 2.4.7 (or thereabouts) or earlier. + - It doesn't work on hosts running 2.4.7 (or thereabouts) or earlier. The fix is to upgrade to something more recent and then read the next item. - o If you see + - If you see:: File descriptor in bad state @@ -3921,8 +3730,8 @@ - 13.9. You can network to the host but not to other machines on the - net +13.9. You can network to the host but not to other machines on the net +======================================================================= If you can connect to the host, and the host can connect to UML, but you cannot connect to any other machines, then you may need to enable @@ -3930,7 +3739,7 @@ using private IP addresses (192.168.x.x or 10.x.x.x) for host/UML networking, rather than the public address space that your host is connected to. UML does not enable IP Masquerading, so you will need - to create a static rule to enable it: + to create a static rule to enable it:: host% @@ -3944,11 +3753,11 @@ Documentation on IP Masquerading, and SNAT, can be found at - www.netfilter.org <http://www.netfilter.org> . + http://www.netfilter.org. If you can reach the local net, but not the outside Internet, then - that is usually a routing problem. The UML needs a default route: + that is usually a routing problem. The UML needs a default route:: UML# @@ -3972,7 +3781,8 @@ - 13.10. I have no root and I want to scream +13.10. I have no root and I want to scream +=========================================== Thanks to Birgit Wahlich for telling me about this strange one. It turns out that there's a limit of six environment variables on the @@ -3987,14 +3797,16 @@ - 13.11. UML build conflict between ptrace.h and ucontext.h +13.11. UML build conflict between ptrace.h and ucontext.h +========================================================== On some older systems, /usr/include/asm/ptrace.h and /usr/include/sys/ucontext.h define the same names. So, when they're included together, the defines from one completely mess up the parsing - of the other, producing errors like: + of the other, producing errors like:: + /usr/include/sys/ucontext.h:47: parse error before - `10' + `10` @@ -4007,7 +3819,8 @@ - 13.12. The UML BogoMips is exactly half the host's BogoMips +13.12. The UML BogoMips is exactly half the host's BogoMips +------------------------------------------------------------ On i386 kernels, there are two ways of running the loop that is used to calculate the BogoMips rating, using the TSC if it's there or using @@ -4019,15 +3832,17 @@ - 13.13. When you run UML, it immediately segfaults +13.13. When you run UML, it immediately segfaults +-------------------------------------------------- If the host is configured with the 2G/2G address space split, that's - why. See ``UML on 2G/2G hosts'' for the details on getting UML to + why. See ref:`UML_on_2G/2G_hosts` for the details on getting UML to run on your host. - 13.14. xterms appear, then immediately disappear +13.14. xterms appear, then immediately disappear +------------------------------------------------- If you're running an up to date kernel with an old release of uml_utilities, the port-helper program will not work properly, so @@ -4039,7 +3854,8 @@ - 13.15. Any other panic, hang, or strange behavior +13.15. Any other panic, hang, or strange behavior +-------------------------------------------------- If you're seeing truly strange behavior, such as hangs or panics that happen in random places, or you try running the debugger to see what's @@ -4057,9 +3873,13 @@ it and that a fix is imminent. - If you want to be super-helpful, read ``Diagnosing Problems'' and + If you want to be super-helpful, read :ref:`Diagnosing_Problems` and follow the instructions contained therein. - 14. Diagnosing Problems + +.. _Diagnosing_Problems: + +14. Diagnosing Problems +======================== If you get UML to crash, hang, or otherwise misbehave, you should @@ -4074,21 +3894,22 @@ For any diagnosis, you're going to need to build a debugging kernel. The binaries from this site aren't debuggable. If you haven't done - this before, read about ``Compiling the kernel and modules'' and - ``Kernel debugging'' UML first. + this before, read about :ref:`Compiling_the_kernel_and_modules` and + :ref:`Kernel_debugging` UML first. - 14.1. Case 1 : Normal kernel panics +14.1. Case 1 : Normal kernel panics +------------------------------------ The most common case is for a normal thread to panic. To debug this, you will need to run it under the debugger (add 'debug' to the command line). An xterm will start up with gdb running inside it. Continue - it when it stops in start_kernel and make it crash. Now ^C gdb and + it when it stops in start_kernel and make it crash. Now ``^C gdb`` and If the panic was a "Kernel mode fault", then there will be a segv frame on the stack and I'm going to want some more information. The - stack might look something like this: + stack might look something like this:: (UML gdb) backtrace @@ -4107,7 +3928,7 @@ I'm going to want to see the symbol and line information for the value - of ip in the segv frame. In this case, you would do the following: + of ip in the segv frame. In this case, you would do the following:: (UML gdb) i sym 268849158 @@ -4115,7 +3936,7 @@ - and + and:: (UML gdb) i line *268849158 @@ -4128,7 +3949,8 @@ to get that information from the faulting ip. - 14.2. Case 2 : Tracing thread panics +14.2. Case 2 : Tracing thread panics +------------------------------------- The less common and more painful case is when the tracing thread panics. In this case, the kernel debugger will be useless because it @@ -4136,7 +3958,7 @@ do is get a backtrace from the tracing thread. This is done by figuring out what its pid is, firing up gdb, and attaching it to that pid. You can figure out the tracing thread pid by looking at the - first line of the console output, which will look like this: + first line of the console output, which will look like this:: tracing thread pid = 15851 @@ -4145,7 +3967,7 @@ or by running ps on the host and finding the line that looks like - this: + this:: jdike 15851 4.5 0.4 132568 1104 pts/0 S 21:34 0:05 ./linux [(tracing thread)] @@ -4164,7 +3986,7 @@ 14.3. Case 3 : Tracing thread panics caused by other threads However, there are cases where the misbehavior of another thread - caused the problem. The most common panic of this type is: + caused the problem. The most common panic of this type is:: wait_for_stop failed to wait for <pid> to stop with <signal number> @@ -4177,7 +3999,7 @@ debugger is defunct and without some fancy footwork, another gdb can't attach to it. So, this is how the fancy footwork goes: - In a shell: + In a shell:: host% kill -STOP pid @@ -4185,7 +4007,7 @@ - Run gdb on the tracing thread as described in case 2 and do: + Run gdb on the tracing thread as described in case 2 and do:: (host gdb) call detach(pid) @@ -4193,7 +4015,7 @@ If you get a segfault, do it again. It always works the second time. - Detach from the tracing thread and attach to that other thread: + Detach from the tracing thread and attach to that other thread:: (host gdb) detach @@ -4209,7 +4031,7 @@ If gdb hangs when attaching to that process, go back to a shell and - do: + do:: host% @@ -4218,7 +4040,7 @@ - And then get the backtrace: + And then get the backtrace:: (host gdb) backtrace @@ -4227,13 +4049,14 @@ - 14.4. Case 4 : Hangs +14.4. Case 4 : Hangs +--------------------- Hangs seem to be fairly rare, but they sometimes happen. When a hang happens, we need a backtrace from the offending process. Run the kernel debugger as described in case 1 and get a backtrace. If the current process is not the idle thread, then send in the backtrace. - You can tell that it's the idle thread if the stack looks like this: + You can tell that it's the idle thread if the stack looks like this:: #0 0x100b1401 in __libc_nanosleep () @@ -4257,7 +4080,8 @@ - 15. Thanks +15. Thanks +=========== A number of people have helped this project in various ways, and this @@ -4274,20 +4098,21 @@ bookkeeping lapses and I forget about contributions. - 15.1. Code and Documentation +15.1. Code and Documentation +----------------------------- Rusty Russell <rusty at linuxcare.com.au> - - o wrote the HOWTO <http://user-mode- - linux.sourceforge.net/UserModeLinux-HOWTO.html> + - wrote the HOWTO + http://user-mode-linux.sourceforge.net/old/UserModeLinux-HOWTO.html - o prodded me into making this project official and putting it on + - prodded me into making this project official and putting it on SourceForge - o came up with the way cool UML logo <http://user-mode- - linux.sourceforge.net/uml-small.png> + - came up with the way cool UML logo + http://user-mode-linux.sourceforge.net/uml-small.png - o redid the config process + - redid the config process Peter Moulder <reiter at netspace.net.au> - Fixed my config and build @@ -4296,34 +4121,32 @@ Bill Stearns <wstearns at pobox.com> - - o HOWTO updates + - HOWTO updates - o lots of bug reports + - lots of bug reports - o lots of testing + - lots of testing - o dedicated a box (uml.ists.dartmouth.edu) to support UML development + - dedicated a box (uml.ists.dartmouth.edu) to support UML development - o wrote the mkrootfs script, which allows bootable filesystems of + - wrote the mkrootfs script, which allows bootable filesystems of RPM-based distributions to be cranked out - o cranked out a large number of filesystems with said script + - cranked out a large number of filesystems with said script Jim Leu <jleu at mindspring.com> - Wrote the virtual ethernet driver and associated usermode tools - Lars Brinkhoff <http://lars.nocrew.org/> - Contributed the ptrace - proxy from his own project <http://a386.nocrew.org/> to allow easier - kernel debugging + Lars Brinkhoff http://lars.nocrew.org/ - Contributed the ptrace + proxy from his own project to allow easier kernel debugging Andrea Arcangeli <andrea at suse.de> - Redid some of the early boot code so that it would work on machines with Large File Support - Chris Emerson <http://www.chiark.greenend.org.uk/~cemerson/> - Did - the first UML port to Linux/ppc + Chris Emerson - Did the first UML port to Linux/ppc Harald Welte <laforge at gnumonks.org> - Wrote the multicast @@ -4338,7 +4161,7 @@ wrote the iomem emulation support - Henrik Nordstrom <http://hem.passagen.se/hno/> - Provided a variety + Henrik Nordstrom http://hem.passagen.se/hno/ - Provided a variety of patches, fixes, and clues @@ -4373,190 +4196,193 @@ submitted patches for the slip transport and lots of other things. - David Coulson <http://davidcoulson.net> - + David Coulson http://davidcoulson.net - - o Set up the usermodelinux.org <http://usermodelinux.org> site, + - Set up the http://usermodelinux.org site, which is a great way of keeping the UML user community on top of UML goings-on. - o Site documentation and updates + - Site documentation and updates - o Nifty little UML management daemon UMLd - <http://uml.openconsultancy.com/umld/> + - Nifty little UML management daemon UMLd - o Lots of testing and bug reports + - Lots of testing and bug reports - 15.2. Flushing out bugs +15.2. Flushing out bugs +------------------------ - o Yuri Pudgorodsky + - Yuri Pudgorodsky - o Gerald Britton + - Gerald Britton - o Ian Wehrman + - Ian Wehrman - o Gord Lamb + - Gord Lamb - o Eugene Koontz + - Eugene Koontz - o John H. Hartman + - John H. Hartman - o Anders Karlsson + - Anders Karlsson - o Daniel Phillips + - Daniel Phillips - o John Fremlin + - John Fremlin - o Rainer Burgstaller + - Rainer Burgstaller - o James Stevenson + - James Stevenson - o Matt Clay + - Matt Clay - o Cliff Jefferies + - Cliff Jefferies - o Geoff Hoff + - Geoff Hoff - o Lennert Buytenhek + - Lennert Buytenhek - o Al Viro + - Al Viro - o Frank Klingenhoefer + - Frank Klingenhoefer - o Livio Baldini Soares + - Livio Baldini Soares - o Jon Burgess + - Jon Burgess - o Petru Paler + - Petru Paler - o Paul + - Paul - o Chris Reahard + - Chris Reahard - o Sverker Nilsson + - Sverker Nilsson - o Gong Su + - Gong Su - o johan verrept + - johan verrept - o Bjorn Eriksson + - Bjorn Eriksson - o Lorenzo Allegrucci + - Lorenzo Allegrucci - o Muli Ben-Yehuda + - Muli Ben-Yehuda - o David Mansfield + - David Mansfield - o Howard Goff + - Howard Goff - o Mike Anderson + - Mike Anderson - o John Byrne + - John Byrne - o Sapan J. Batia + - Sapan J. Batia - o Iris Huang + - Iris Huang - o Jan Hudec + - Jan Hudec - o Voluspa + - Voluspa - 15.3. Buglets and clean-ups +15.3. Buglets and clean-ups +---------------------------- - o Dave Zarzycki + - Dave Zarzycki - o Adam Lazur + - Adam Lazur - o Boria Feigin + - Boria Feigin - o Brian J. Murrell + - Brian J. Murrell - o JS + - JS - o Roman Zippel + - Roman Zippel - o Wil Cooley + - Wil Cooley - o Ayelet Shemesh + - Ayelet Shemesh - o Will Dyson + - Will Dyson - o Sverker Nilsson + - Sverker Nilsson - o dvorak + - dvorak - o v.naga srinivas + - v.naga srinivas - o Shlomi Fish + - Shlomi Fish - o Roger Binns + - Roger Binns - o johan verrept + - johan verrept - o MrChuoi + - MrChuoi - o Peter Cleve + - Peter Cleve - o Vincent Guffens + - Vincent Guffens - o Nathan Scott + - Nathan Scott - o Patrick Caulfield + - Patrick Caulfield - o jbearce + - jbearce - o Catalin Marinas + - Catalin Marinas - o Shane Spencer + - Shane Spencer - o Zou Min + - Zou Min - o Ryan Boder + - Ryan Boder - o Lorenzo Colitti + - Lorenzo Colitti - o Gwendal Grignou + - Gwendal Grignou - o Andre' Breiler + - Andre' Breiler - o Tsutomu Yasuda + - Tsutomu Yasuda - 15.4. Case Studies +15.4. Case Studies +------------------- - o Jon Wright + - Jon Wright - o William McEwan + - William McEwan - o Michael Richardson + - Michael Richardson - 15.5. Other contributions +15.5. Other contributions +-------------------------- Bill Carr <Bill.Carr at compaq.com> made the Red Hat mkrootfs script work with RH 6.2. Michael Jennings <mikejen at hevanet.com> sent in some material which - is now gracing the top of the index page <http://user-mode- - linux.sourceforge.net/> of this site. + is now gracing the top of the index page + http://user-mode-linux.sourceforge.net/ of this site. - SGI <http://www.sgi.com> (and more specifically Ralf Baechle <ralf at - uni-koblenz.de> ) gave me an account on oss.sgi.com - <http://www.oss.sgi.com> . The bandwidth there made it possible to + SGI (and more specifically Ralf Baechle <ralf at + uni-koblenz.de> ) gave me an account on oss.sgi.com. + The bandwidth there made it possible to produce most of the filesystems available on the project download page. @@ -4573,17 +4399,5 @@ Chris Reahard built a specialized root filesystem for running a DNS server jailed inside UML. It's available from the download - <http://user-mode-linux.sourceforge.net/dl-sf.html> page in the Jail + http://user-mode-linux.sourceforge.net/old/dl-sf.html page in the Jail Filesystems section. - - - - - - - - - - - - diff --git a/Documentation/vm/hmm.rst b/Documentation/vm/hmm.rst index 893a8ba0e9fe..95fec5968362 100644 --- a/Documentation/vm/hmm.rst +++ b/Documentation/vm/hmm.rst @@ -149,14 +149,14 @@ CPU page table into a device page table; HMM helps keep both synchronized. A device driver that wants to mirror a process address space must start with the registration of a mmu_interval_notifier:: - mni->ops = &driver_ops; - int mmu_interval_notifier_insert(struct mmu_interval_notifier *mni, - unsigned long start, unsigned long length, - struct mm_struct *mm); + int mmu_interval_notifier_insert(struct mmu_interval_notifier *interval_sub, + struct mm_struct *mm, unsigned long start, + unsigned long length, + const struct mmu_interval_notifier_ops *ops); -During the driver_ops->invalidate() callback the device driver must perform -the update action to the range (mark range read only, or fully unmap, -etc.). The device must complete the update before the driver callback returns. +During the ops->invalidate() callback the device driver must perform the +update action to the range (mark range read only, or fully unmap, etc.). The +device must complete the update before the driver callback returns. When the device driver wants to populate a range of virtual addresses, it can use:: @@ -183,7 +183,7 @@ The usage pattern is:: struct hmm_range range; ... - range.notifier = &mni; + range.notifier = &interval_sub; range.start = ...; range.end = ...; range.pfns = ...; @@ -191,11 +191,11 @@ The usage pattern is:: range.values = ...; range.pfn_shift = ...; - if (!mmget_not_zero(mni->notifier.mm)) + if (!mmget_not_zero(interval_sub->notifier.mm)) return -EFAULT; again: - range.notifier_seq = mmu_interval_read_begin(&mni); + range.notifier_seq = mmu_interval_read_begin(&interval_sub); down_read(&mm->mmap_sem); ret = hmm_range_fault(&range, HMM_RANGE_SNAPSHOT); if (ret) { diff --git a/Documentation/vm/zswap.rst b/Documentation/vm/zswap.rst index 1444ecd40911..61f6185188cd 100644 --- a/Documentation/vm/zswap.rst +++ b/Documentation/vm/zswap.rst @@ -130,6 +130,19 @@ checking for the same-value filled pages during store operation. However, the existing pages which are marked as same-value filled pages remain stored unchanged in zswap until they are either loaded or invalidated. +To prevent zswap from shrinking pool when zswap is full and there's a high +pressure on swap (this will result in flipping pages in and out zswap pool +without any real benefit but with a performance drop for the system), a +special parameter has been introduced to implement a sort of hysteresis to +refuse taking pages into zswap pool until it has sufficient space if the limit +has been hit. To set the threshold at which zswap would start accepting pages +again after it became full, use the sysfs ``accept_threhsold_percent`` +attribute, e. g.:: + + echo 80 > /sys/module/zswap/parameters/accept_threhsold_percent + +Setting this parameter to 100 will disable the hysteresis. + A debugfs interface is provided for various statistic about pool size, number of pages stored, same-value filled pages and various counters for the reasons pages are rejected. diff --git a/Documentation/w1/masters/omap-hdq.rst b/Documentation/w1/masters/omap-hdq.rst index 345298a59e50..5347b5d9e90a 100644 --- a/Documentation/w1/masters/omap-hdq.rst +++ b/Documentation/w1/masters/omap-hdq.rst @@ -44,7 +44,7 @@ that the ID used should be same for both master and slave driver loading. e.g:: insmod omap_hdq.ko W1_ID=2 - inamod w1_bq27000.ko F_ID=2 + insmod w1_bq27000.ko F_ID=2 The driver also supports 1-wire mode. In this mode, there is no need to pass slave ID as parameter. The driver will auto-detect slaves connected diff --git a/Documentation/x86/boot.rst b/Documentation/x86/boot.rst index 90bb8f5ab384..c9c201596c3e 100644 --- a/Documentation/x86/boot.rst +++ b/Documentation/x86/boot.rst @@ -69,11 +69,12 @@ Protocol 2.13 (Kernel 3.14) Support 32- and 64-bit flags being set in xloadflags to support booting a 64-bit kernel from 32-bit EFI -Protocol 2.14: BURNT BY INCORRECT COMMIT ae7e1238e68f2a472a125673ab506d49158c1889 +Protocol 2.14 BURNT BY INCORRECT COMMIT + ae7e1238e68f2a472a125673ab506d49158c1889 (x86/boot: Add ACPI RSDP address to setup_header) DO NOT USE!!! ASSUME SAME AS 2.13. -Protocol 2.15: (Kernel 5.5) Added the kernel_info and kernel_info.setup_type_max. +Protocol 2.15 (Kernel 5.5) Added the kernel_info and kernel_info.setup_type_max. ============= ============================================================ .. note:: @@ -251,7 +252,7 @@ setting fields in the header, you must make sure only to set fields supported by the protocol version in use. -Details of Harder Fileds +Details of Header Fields ======================== For each field, some are information from the kernel to the bootloader @@ -834,14 +835,14 @@ Protocol: 2.09+ chunks of memory are occupied by kernel data. Thus setup_indirect struct and SETUP_INDIRECT type were introduced in - protocol 2.15. + protocol 2.15:: - struct setup_indirect { - __u32 type; - __u32 reserved; /* Reserved, must be set to zero. */ - __u64 len; - __u64 addr; - }; + struct setup_indirect { + __u32 type; + __u32 reserved; /* Reserved, must be set to zero. */ + __u64 len; + __u64 addr; + }; The type member is a SETUP_INDIRECT | SETUP_* type. However, it cannot be SETUP_INDIRECT itself since making the setup_indirect a tree structure @@ -849,19 +850,19 @@ Protocol: 2.09+ and stack space can be limited in boot contexts. Let's give an example how to point to SETUP_E820_EXT data using setup_indirect. - In this case setup_data and setup_indirect will look like this: - - struct setup_data { - __u64 next = 0 or <addr_of_next_setup_data_struct>; - __u32 type = SETUP_INDIRECT; - __u32 len = sizeof(setup_data); - __u8 data[sizeof(setup_indirect)] = struct setup_indirect { - __u32 type = SETUP_INDIRECT | SETUP_E820_EXT; - __u32 reserved = 0; - __u64 len = <len_of_SETUP_E820_EXT_data>; - __u64 addr = <addr_of_SETUP_E820_EXT_data>; + In this case setup_data and setup_indirect will look like this:: + + struct setup_data { + __u64 next = 0 or <addr_of_next_setup_data_struct>; + __u32 type = SETUP_INDIRECT; + __u32 len = sizeof(setup_data); + __u8 data[sizeof(setup_indirect)] = struct setup_indirect { + __u32 type = SETUP_INDIRECT | SETUP_E820_EXT; + __u32 reserved = 0; + __u64 len = <len_of_SETUP_E820_EXT_data>; + __u64 addr = <addr_of_SETUP_E820_EXT_data>; + } } - } .. note:: SETUP_INDIRECT | SETUP_NONE objects cannot be properly distinguished @@ -964,7 +965,7 @@ expected to copy into a setup_data chunk. All kernel_info data should be part of this structure. Fixed size data have to be put before kernel_info_var_len_data label. Variable size data have to be put after kernel_info_var_len_data label. Each chunk of variable size data has to -be prefixed with header/magic and its size, e.g.: +be prefixed with header/magic and its size, e.g.:: kernel_info: .ascii "LToP" /* Header, Linux top (structure). */ diff --git a/Documentation/x86/intel_mpx.rst b/Documentation/x86/intel_mpx.rst deleted file mode 100644 index 387a640941a6..000000000000 --- a/Documentation/x86/intel_mpx.rst +++ /dev/null @@ -1,252 +0,0 @@ -.. SPDX-License-Identifier: GPL-2.0 - -=========================================== -Intel(R) Memory Protection Extensions (MPX) -=========================================== - -Intel(R) MPX Overview -===================== - -Intel(R) Memory Protection Extensions (Intel(R) MPX) is a new capability -introduced into Intel Architecture. Intel MPX provides hardware features -that can be used in conjunction with compiler changes to check memory -references, for those references whose compile-time normal intentions are -usurped at runtime due to buffer overflow or underflow. - -You can tell if your CPU supports MPX by looking in /proc/cpuinfo:: - - cat /proc/cpuinfo | grep ' mpx ' - -For more information, please refer to Intel(R) Architecture Instruction -Set Extensions Programming Reference, Chapter 9: Intel(R) Memory Protection -Extensions. - -Note: As of December 2014, no hardware with MPX is available but it is -possible to use SDE (Intel(R) Software Development Emulator) instead, which -can be downloaded from -http://software.intel.com/en-us/articles/intel-software-development-emulator - - -How to get the advantage of MPX -=============================== - -For MPX to work, changes are required in the kernel, binutils and compiler. -No source changes are required for applications, just a recompile. - -There are a lot of moving parts of this to all work right. The following -is how we expect the compiler, application and kernel to work together. - -1) Application developer compiles with -fmpx. The compiler will add the - instrumentation as well as some setup code called early after the app - starts. New instruction prefixes are noops for old CPUs. -2) That setup code allocates (virtual) space for the "bounds directory", - points the "bndcfgu" register to the directory (must also set the valid - bit) and notifies the kernel (via the new prctl(PR_MPX_ENABLE_MANAGEMENT)) - that the app will be using MPX. The app must be careful not to access - the bounds tables between the time when it populates "bndcfgu" and - when it calls the prctl(). This might be hard to guarantee if the app - is compiled with MPX. You can add "__attribute__((bnd_legacy))" to - the function to disable MPX instrumentation to help guarantee this. - Also be careful not to call out to any other code which might be - MPX-instrumented. -3) The kernel detects that the CPU has MPX, allows the new prctl() to - succeed, and notes the location of the bounds directory. Userspace is - expected to keep the bounds directory at that location. We note it - instead of reading it each time because the 'xsave' operation needed - to access the bounds directory register is an expensive operation. -4) If the application needs to spill bounds out of the 4 registers, it - issues a bndstx instruction. Since the bounds directory is empty at - this point, a bounds fault (#BR) is raised, the kernel allocates a - bounds table (in the user address space) and makes the relevant entry - in the bounds directory point to the new table. -5) If the application violates the bounds specified in the bounds registers, - a separate kind of #BR is raised which will deliver a signal with - information about the violation in the 'struct siginfo'. -6) Whenever memory is freed, we know that it can no longer contain valid - pointers, and we attempt to free the associated space in the bounds - tables. If an entire table becomes unused, we will attempt to free - the table and remove the entry in the directory. - -To summarize, there are essentially three things interacting here: - -GCC with -fmpx: - * enables annotation of code with MPX instructions and prefixes - * inserts code early in the application to call in to the "gcc runtime" -GCC MPX Runtime: - * Checks for hardware MPX support in cpuid leaf - * allocates virtual space for the bounds directory (malloc() essentially) - * points the hardware BNDCFGU register at the directory - * calls a new prctl(PR_MPX_ENABLE_MANAGEMENT) to notify the kernel to - start managing the bounds directories -Kernel MPX Code: - * Checks for hardware MPX support in cpuid leaf - * Handles #BR exceptions and sends SIGSEGV to the app when it violates - bounds, like during a buffer overflow. - * When bounds are spilled in to an unallocated bounds table, the kernel - notices in the #BR exception, allocates the virtual space, then - updates the bounds directory to point to the new table. It keeps - special track of the memory with a VM_MPX flag. - * Frees unused bounds tables at the time that the memory they described - is unmapped. - - -How does MPX kernel code work -============================= - -Handling #BR faults caused by MPX ---------------------------------- - -When MPX is enabled, there are 2 new situations that can generate -#BR faults. - - * new bounds tables (BT) need to be allocated to save bounds. - * bounds violation caused by MPX instructions. - -We hook #BR handler to handle these two new situations. - -On-demand kernel allocation of bounds tables --------------------------------------------- - -MPX only has 4 hardware registers for storing bounds information. If -MPX-enabled code needs more than these 4 registers, it needs to spill -them somewhere. It has two special instructions for this which allow -the bounds to be moved between the bounds registers and some new "bounds -tables". - -#BR exceptions are a new class of exceptions just for MPX. They are -similar conceptually to a page fault and will be raised by the MPX -hardware during both bounds violations or when the tables are not -present. The kernel handles those #BR exceptions for not-present tables -by carving the space out of the normal processes address space and then -pointing the bounds-directory over to it. - -The tables need to be accessed and controlled by userspace because -the instructions for moving bounds in and out of them are extremely -frequent. They potentially happen every time a register points to -memory. Any direct kernel involvement (like a syscall) to access the -tables would obviously destroy performance. - -Why not do this in userspace? MPX does not strictly require anything in -the kernel. It can theoretically be done completely from userspace. Here -are a few ways this could be done. We don't think any of them are practical -in the real-world, but here they are. - -:Q: Can virtual space simply be reserved for the bounds tables so that we - never have to allocate them? -:A: MPX-enabled application will possibly create a lot of bounds tables in - process address space to save bounds information. These tables can take - up huge swaths of memory (as much as 80% of the memory on the system) - even if we clean them up aggressively. In the worst-case scenario, the - tables can be 4x the size of the data structure being tracked. IOW, a - 1-page structure can require 4 bounds-table pages. An X-GB virtual - area needs 4*X GB of virtual space, plus 2GB for the bounds directory. - If we were to preallocate them for the 128TB of user virtual address - space, we would need to reserve 512TB+2GB, which is larger than the - entire virtual address space today. This means they can not be reserved - ahead of time. Also, a single process's pre-populated bounds directory - consumes 2GB of virtual *AND* physical memory. IOW, it's completely - infeasible to prepopulate bounds directories. - -:Q: Can we preallocate bounds table space at the same time memory is - allocated which might contain pointers that might eventually need - bounds tables? -:A: This would work if we could hook the site of each and every memory - allocation syscall. This can be done for small, constrained applications. - But, it isn't practical at a larger scale since a given app has no - way of controlling how all the parts of the app might allocate memory - (think libraries). The kernel is really the only place to intercept - these calls. - -:Q: Could a bounds fault be handed to userspace and the tables allocated - there in a signal handler instead of in the kernel? -:A: mmap() is not on the list of safe async handler functions and even - if mmap() would work it still requires locking or nasty tricks to - keep track of the allocation state there. - -Having ruled out all of the userspace-only approaches for managing -bounds tables that we could think of, we create them on demand in -the kernel. - -Decoding MPX instructions -------------------------- - -If a #BR is generated due to a bounds violation caused by MPX. -We need to decode MPX instructions to get violation address and -set this address into extended struct siginfo. - -The _sigfault field of struct siginfo is extended as follow:: - - 87 /* SIGILL, SIGFPE, SIGSEGV, SIGBUS */ - 88 struct { - 89 void __user *_addr; /* faulting insn/memory ref. */ - 90 #ifdef __ARCH_SI_TRAPNO - 91 int _trapno; /* TRAP # which caused the signal */ - 92 #endif - 93 short _addr_lsb; /* LSB of the reported address */ - 94 struct { - 95 void __user *_lower; - 96 void __user *_upper; - 97 } _addr_bnd; - 98 } _sigfault; - -The '_addr' field refers to violation address, and new '_addr_and' -field refers to the upper/lower bounds when a #BR is caused. - -Glibc will be also updated to support this new siginfo. So user -can get violation address and bounds when bounds violations occur. - -Cleanup unused bounds tables ----------------------------- - -When a BNDSTX instruction attempts to save bounds to a bounds directory -entry marked as invalid, a #BR is generated. This is an indication that -no bounds table exists for this entry. In this case the fault handler -will allocate a new bounds table on demand. - -Since the kernel allocated those tables on-demand without userspace -knowledge, it is also responsible for freeing them when the associated -mappings go away. - -Here, the solution for this issue is to hook do_munmap() to check -whether one process is MPX enabled. If yes, those bounds tables covered -in the virtual address region which is being unmapped will be freed also. - -Adding new prctl commands -------------------------- - -Two new prctl commands are added to enable and disable MPX bounds tables -management in kernel. -:: - - 155 #define PR_MPX_ENABLE_MANAGEMENT 43 - 156 #define PR_MPX_DISABLE_MANAGEMENT 44 - -Runtime library in userspace is responsible for allocation of bounds -directory. So kernel have to use XSAVE instruction to get the base -of bounds directory from BNDCFG register. - -But XSAVE is expected to be very expensive. In order to do performance -optimization, we have to get the base of bounds directory and save it -into struct mm_struct to be used in future during PR_MPX_ENABLE_MANAGEMENT -command execution. - - -Special rules -============= - -1) If userspace is requesting help from the kernel to do the management -of bounds tables, it may not create or modify entries in the bounds directory. - -Certainly users can allocate bounds tables and forcibly point the bounds -directory at them through XSAVE instruction, and then set valid bit -of bounds entry to have this entry valid. But, the kernel will decline -to assist in managing these tables. - -2) Userspace may not take multiple bounds directory entries and point -them at the same bounds table. - -This is allowed architecturally. See more information "Intel(R) Architecture -Instruction Set Extensions Programming Reference" (9.3.4). - -However, if users did this, the kernel might be fooled in to unmapping an -in-use bounds table since it does not recognize sharing. diff --git a/Documentation/x86/pat.rst b/Documentation/x86/pat.rst index 9a298fd97d74..5d901771016d 100644 --- a/Documentation/x86/pat.rst +++ b/Documentation/x86/pat.rst @@ -44,8 +44,6 @@ address range to avoid any aliasing. +------------------------+----------+--------------+------------------+ | ioremap_uc | -- | UC | UC | +------------------------+----------+--------------+------------------+ -| ioremap_nocache | -- | UC- | UC- | -+------------------------+----------+--------------+------------------+ | ioremap_wc | -- | -- | WC | +------------------------+----------+--------------+------------------+ | ioremap_wt | -- | -- | WT | diff --git a/Documentation/x86/x86_64/mm.rst b/Documentation/x86/x86_64/mm.rst index 267fc4808945..e5053404a1ae 100644 --- a/Documentation/x86/x86_64/mm.rst +++ b/Documentation/x86/x86_64/mm.rst @@ -1,8 +1,8 @@ .. SPDX-License-Identifier: GPL-2.0 -================ -Memory Managment -================ +================= +Memory Management +================= Complete virtual memory map with 4-level page tables ==================================================== |
