diff options
Diffstat (limited to 'Documentation')
597 files changed, 31302 insertions, 5988 deletions
diff --git a/Documentation/ABI/testing/configfs-usb-gadget-uac1 b/Documentation/ABI/testing/configfs-usb-gadget-uac1 index dc23fd776943..dd647d44d975 100644 --- a/Documentation/ABI/testing/configfs-usb-gadget-uac1 +++ b/Documentation/ABI/testing/configfs-usb-gadget-uac1 @@ -8,9 +8,19 @@ Description: c_chmask capture channel mask c_srate capture sampling rate c_ssize capture sample size (bytes) + c_mute_present capture mute control enable + c_volume_present capture volume control enable + c_volume_min capture volume control min value (in 1/256 dB) + c_volume_max capture volume control max value (in 1/256 dB) + c_volume_res capture volume control resolution (in 1/256 dB) p_chmask playback channel mask p_srate playback sampling rate p_ssize playback sample size (bytes) + p_mute_present playback mute control enable + p_volume_present playback volume control enable + p_volume_min playback volume control min value (in 1/256 dB) + p_volume_max playback volume control max value (in 1/256 dB) + p_volume_res playback volume control resolution (in 1/256 dB) req_number the number of pre-allocated request for both capture and playback ========== =================================== diff --git a/Documentation/ABI/testing/configfs-usb-gadget-uac2 b/Documentation/ABI/testing/configfs-usb-gadget-uac2 index 26fb8e9b4e61..cfd160ff8b56 100644 --- a/Documentation/ABI/testing/configfs-usb-gadget-uac2 +++ b/Documentation/ABI/testing/configfs-usb-gadget-uac2 @@ -9,8 +9,18 @@ Description: c_srate capture sampling rate c_ssize capture sample size (bytes) c_sync capture synchronization type (async/adaptive) + c_mute_present capture mute control enable + c_volume_present capture volume control enable + c_volume_min capture volume control min value (in 1/256 dB) + c_volume_max capture volume control max value (in 1/256 dB) + c_volume_res capture volume control resolution (in 1/256 dB) fb_max maximum extra bandwidth in async mode p_chmask playback channel mask p_srate playback sampling rate p_ssize playback sample size (bytes) + p_mute_present playback mute control enable + p_volume_present playback volume control enable + p_volume_min playback volume control min value (in 1/256 dB) + p_volume_max playback volume control max value (in 1/256 dB) + p_volume_res playback volume control resolution (in 1/256 dB) ========= ============================ diff --git a/Documentation/ABI/testing/dell-smbios-wmi b/Documentation/ABI/testing/dell-smbios-wmi index 5f3a0dc67050..f58229084469 100644 --- a/Documentation/ABI/testing/dell-smbios-wmi +++ b/Documentation/ABI/testing/dell-smbios-wmi @@ -1,7 +1,7 @@ What: /dev/wmi/dell-smbios Date: November 2017 KernelVersion: 4.15 -Contact: "Mario Limonciello" <mario.limonciello@dell.com> +Contact: Dell.Client.Kernel@dell.com Description: Perform SMBIOS calls on supported Dell machines. through the Dell ACPI-WMI interface. diff --git a/Documentation/ABI/testing/ima_policy b/Documentation/ABI/testing/ima_policy index 070779e8d836..5c2798534950 100644 --- a/Documentation/ABI/testing/ima_policy +++ b/Documentation/ABI/testing/ima_policy @@ -27,12 +27,13 @@ Description: lsm: [[subj_user=] [subj_role=] [subj_type=] [obj_user=] [obj_role=] [obj_type=]] option: [[appraise_type=]] [template=] [permit_directio] - [appraise_flag=] [keyrings=] + [appraise_flag=] [appraise_algos=] [keyrings=] base: func:= [BPRM_CHECK][MMAP_CHECK][CREDS_CHECK][FILE_CHECK][MODULE_CHECK] - [FIRMWARE_CHECK] + [FIRMWARE_CHECK] [KEXEC_KERNEL_CHECK] [KEXEC_INITRAMFS_CHECK] [KEXEC_CMDLINE] [KEY_CHECK] [CRITICAL_DATA] + [SETXATTR_CHECK] mask:= [[^]MAY_READ] [[^]MAY_WRITE] [[^]MAY_APPEND] [[^]MAY_EXEC] fsmagic:= hex value @@ -55,6 +56,10 @@ Description: label:= [selinux]|[kernel_info]|[data_label] data_label:= a unique string used for grouping and limiting critical data. For example, "selinux" to measure critical data for SELinux. + appraise_algos:= comma-separated list of hash algorithms + For example, "sha256,sha512" to only accept to appraise + files where the security.ima xattr was hashed with one + of these two algorithms. default policy: # PROC_SUPER_MAGIC @@ -134,3 +139,9 @@ Description: keys added to .builtin_trusted_keys or .ima keyring: measure func=KEY_CHECK keyrings=.builtin_trusted_keys|.ima + + Example of the special SETXATTR_CHECK appraise rule, that + restricts the hash algorithms allowed when writing to the + security.ima xattr of a file: + + appraise func=SETXATTR_CHECK appraise_algos=sha256,sha384,sha512 diff --git a/Documentation/ABI/testing/sysfs-block b/Documentation/ABI/testing/sysfs-block index e34cdeeeb9d4..a0ed87386639 100644 --- a/Documentation/ABI/testing/sysfs-block +++ b/Documentation/ABI/testing/sysfs-block @@ -28,6 +28,18 @@ Description: For more details refer Documentation/admin-guide/iostats.rst +What: /sys/block/<disk>/diskseq +Date: February 2021 +Contact: Matteo Croce <mcroce@microsoft.com> +Description: + The /sys/block/<disk>/diskseq files reports the disk + sequence number, which is a monotonically increasing + number assigned to every drive. + Some devices, like the loop device, refresh such number + every time the backing file is changed. + The value type is 64 bit unsigned. + + What: /sys/block/<disk>/<part>/stat Date: February 2008 Contact: Jerome Marchand <jmarchan@redhat.com> diff --git a/Documentation/ABI/testing/sysfs-block-device b/Documentation/ABI/testing/sysfs-block-device index aa0fb500e3c9..7ac7b19b2f72 100644 --- a/Documentation/ABI/testing/sysfs-block-device +++ b/Documentation/ABI/testing/sysfs-block-device @@ -55,6 +55,43 @@ Date: Oct, 2016 KernelVersion: v4.10 Contact: linux-ide@vger.kernel.org Description: - (RW) Write to the file to turn on or off the SATA ncq (native - command queueing) support. By default this feature is turned - off. + (RW) Write to the file to turn on or off the SATA NCQ (native + command queueing) priority support. By default this feature is + turned off. If the device does not support the SATA NCQ + priority feature, writing "1" to this file results in an error + (see ncq_prio_supported). + + +What: /sys/block/*/device/sas_ncq_prio_enable +Date: Oct, 2016 +KernelVersion: v4.10 +Contact: linux-ide@vger.kernel.org +Description: + (RW) This is the equivalent of the ncq_prio_enable attribute + file for SATA devices connected to a SAS host-bus-adapter + (HBA) implementing support for the SATA NCQ priority feature. + This file does not exist if the HBA driver does not implement + support for the SATA NCQ priority feature, regardless of the + device support for this feature (see sas_ncq_prio_supported). + + +What: /sys/block/*/device/ncq_prio_supported +Date: Aug, 2021 +KernelVersion: v5.15 +Contact: linux-ide@vger.kernel.org +Description: + (RO) Indicates if the device supports the SATA NCQ (native + command queueing) priority feature. + + +What: /sys/block/*/device/sas_ncq_prio_supported +Date: Aug, 2021 +KernelVersion: v5.15 +Contact: linux-ide@vger.kernel.org +Description: + (RO) This is the equivalent of the ncq_prio_supported attribute + file for SATA devices connected to a SAS host-bus-adapter + (HBA) implementing support for the SATA NCQ priority feature. + This file does not exist if the HBA driver does not implement + support for the SATA NCQ priority feature, regardless of the + device support for this feature. diff --git a/Documentation/ABI/testing/sysfs-bus-event_source-devices-uncore b/Documentation/ABI/testing/sysfs-bus-event_source-devices-uncore new file mode 100644 index 000000000000..b56e8f019fd4 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-bus-event_source-devices-uncore @@ -0,0 +1,13 @@ +What: /sys/bus/event_source/devices/uncore_*/alias +Date: June 2021 +KernelVersion: 5.15 +Contact: Linux kernel mailing list <linux-kernel@vger.kernel.org> +Description: Read-only. An attribute to describe the alias name of + the uncore PMU if an alias exists on some platforms. + The 'perf(1)' tool should treat both names the same. + They both can be used to access the uncore PMU. + + Example: + + $ cat /sys/devices/uncore_cha_2/alias + uncore_type_0_2 diff --git a/Documentation/ABI/testing/sysfs-bus-iio-chemical-sgp40 b/Documentation/ABI/testing/sysfs-bus-iio-chemical-sgp40 new file mode 100644 index 000000000000..469a7c00fad4 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-bus-iio-chemical-sgp40 @@ -0,0 +1,31 @@ +What: /sys/bus/iio/devices/iio:deviceX/out_temp_raw +Date: August 2021 +KernelVersion: 5.15 +Contact: Andreas Klinger <ak@it-klinger.de> +Description: + Set the temperature. This value is sent to the sensor for + temperature compensation. + Default value: 25000 (25 °C) + +What: /sys/bus/iio/devices/iio:deviceX/out_humidityrelative_raw +Date: August 2021 +KernelVersion: 5.15 +Contact: Andreas Klinger <ak@it-klinger.de> +Description: + Set the relative humidity. This value is sent to the sensor for + humidity compensation. + Default value: 50000 (50 % relative humidity) + +What: /sys/bus/iio/devices/iio:deviceX/in_resistance_calibbias +Date: August 2021 +KernelVersion: 5.15 +Contact: Andreas Klinger <ak@it-klinger.de> +Description: + Set the bias value for the resistance which is used for + calculation of in_concentration_input as follows: + + x = (in_resistance_raw - in_resistance_calibbias) * 0.65 + + in_concentration_input = 500 / (1 + e^x) + + Default value: 30000 diff --git a/Documentation/ABI/testing/sysfs-bus-platform b/Documentation/ABI/testing/sysfs-bus-platform index 194ca700e962..ff30728595ef 100644 --- a/Documentation/ABI/testing/sysfs-bus-platform +++ b/Documentation/ABI/testing/sysfs-bus-platform @@ -28,3 +28,17 @@ Description: value comes from an ACPI _PXM method or a similar firmware source. Initial users for this file would be devices like arm smmu which are populated by arm64 acpi_iort. + +What: /sys/bus/platform/devices/.../msi_irqs/ +Date: August 2021 +Contact: Barry Song <song.bao.hua@hisilicon.com> +Description: + The /sys/devices/.../msi_irqs directory contains a variable set + of files, with each file being named after a corresponding msi + irq vector allocated to that device. + +What: /sys/bus/platform/devices/.../msi_irqs/<N> +Date: August 2021 +Contact: Barry Song <song.bao.hua@hisilicon.com> +Description: + This attribute will show "msi" if <N> is a valid msi irq diff --git a/Documentation/ABI/testing/sysfs-bus-thunderbolt b/Documentation/ABI/testing/sysfs-bus-thunderbolt index 95c21d6c9a84..b7e87f6c7d47 100644 --- a/Documentation/ABI/testing/sysfs-bus-thunderbolt +++ b/Documentation/ABI/testing/sysfs-bus-thunderbolt @@ -232,7 +232,7 @@ Description: When new NVM image is written to the non-active NVM What: /sys/bus/thunderbolt/devices/.../nvm_authenticate_on_disconnect Date: Oct 2020 KernelVersion: v5.9 -Contact: Mario Limonciello <mario.limonciello@dell.com> +Contact: Mario Limonciello <mario.limonciello@outlook.com> Description: For supported devices, automatically authenticate the new Thunderbolt image when the device is disconnected from the host system. diff --git a/Documentation/ABI/testing/sysfs-class-firmware-attributes b/Documentation/ABI/testing/sysfs-class-firmware-attributes index 3348bf80a37c..90fdf935aa5e 100644 --- a/Documentation/ABI/testing/sysfs-class-firmware-attributes +++ b/Documentation/ABI/testing/sysfs-class-firmware-attributes @@ -2,8 +2,8 @@ What: /sys/class/firmware-attributes/*/attributes/*/ Date: February 2021 KernelVersion: 5.11 Contact: Divya Bharathi <Divya.Bharathi@Dell.com>, - Mario Limonciello <mario.limonciello@dell.com>, Prasanth KSR <prasanth.ksr@dell.com> + Dell.Client.Kernel@dell.com Description: A sysfs interface for systems management software to enable configuration capability on supported systems. This directory @@ -130,8 +130,8 @@ What: /sys/class/firmware-attributes/*/authentication/ Date: February 2021 KernelVersion: 5.11 Contact: Divya Bharathi <Divya.Bharathi@Dell.com>, - Mario Limonciello <mario.limonciello@dell.com>, Prasanth KSR <prasanth.ksr@dell.com> + Dell.Client.Kernel@dell.com Description: Devices support various authentication mechanisms which can be exposed as a separate configuration object. @@ -220,8 +220,8 @@ What: /sys/class/firmware-attributes/*/attributes/pending_reboot Date: February 2021 KernelVersion: 5.11 Contact: Divya Bharathi <Divya.Bharathi@Dell.com>, - Mario Limonciello <mario.limonciello@dell.com>, Prasanth KSR <prasanth.ksr@dell.com> + Dell.Client.Kernel@dell.com Description: A read-only attribute reads 1 if a reboot is necessary to apply pending BIOS attribute changes. Also, an uevent_KOBJ_CHANGE is @@ -249,8 +249,8 @@ What: /sys/class/firmware-attributes/*/attributes/reset_bios Date: February 2021 KernelVersion: 5.11 Contact: Divya Bharathi <Divya.Bharathi@Dell.com>, - Mario Limonciello <mario.limonciello@dell.com>, Prasanth KSR <prasanth.ksr@dell.com> + Dell.Client.Kernel@dell.com Description: This attribute can be used to reset the BIOS Configuration. Specifically, it tells which type of reset BIOS configuration is being @@ -272,3 +272,14 @@ Description: Note that any changes to this attribute requires a reboot for changes to take effect. + +What: /sys/class/firmware-attributes/*/attributes/debug_cmd +Date: July 2021 +KernelVersion: 5.14 +Contact: Mark Pearson <markpearson@lenovo.com> +Description: + This write only attribute can be used to send debug commands to the BIOS. + This should only be used when recommended by the BIOS vendor. Vendors may + use it to enable extra debug attributes or BIOS features for testing purposes. + + Note that any changes to this attribute requires a reboot for changes to take effect. diff --git a/Documentation/ABI/testing/sysfs-devices-system-cpu b/Documentation/ABI/testing/sysfs-devices-system-cpu index 160b10c029c0..b46ef147616a 100644 --- a/Documentation/ABI/testing/sysfs-devices-system-cpu +++ b/Documentation/ABI/testing/sysfs-devices-system-cpu @@ -494,6 +494,15 @@ Description: AArch64 CPU registers 'identification' directory exposes the CPU ID registers for identifying model and revision of the CPU. +What: /sys/devices/system/cpu/aarch32_el0 +Date: May 2021 +Contact: Linux ARM Kernel Mailing list <linux-arm-kernel@lists.infradead.org> +Description: Identifies the subset of CPUs in the system that can execute + AArch32 (32-bit ARM) applications. If present, the same format as + /sys/devices/system/cpu/{offline,online,possible,present} is used. + If absent, then all or none of the CPUs can execute AArch32 + applications and execve() will behave accordingly. + What: /sys/devices/system/cpu/cpu#/cpu_capacity Date: December 2016 Contact: Linux kernel mailing list <linux-kernel@vger.kernel.org> @@ -640,3 +649,20 @@ Description: SPURR ticks for cpuX when it was idle. This sysfs interface exposes the number of SPURR ticks for cpuX when it was idle. + +What: /sys/devices/system/cpu/cpuX/mte_tcf_preferred +Date: July 2021 +Contact: Linux ARM Kernel Mailing list <linux-arm-kernel@lists.infradead.org> +Description: Preferred MTE tag checking mode + + When a user program specifies more than one MTE tag checking + mode, this sysfs node is used to specify which mode should + be preferred when scheduling a task on that CPU. Possible + values: + + ================ ============================================== + "sync" Prefer synchronous mode + "async" Prefer asynchronous mode + ================ ============================================== + + See also: Documentation/arm64/memory-tagging-extension.rst diff --git a/Documentation/ABI/testing/sysfs-driver-ge-achc b/Documentation/ABI/testing/sysfs-driver-ge-achc new file mode 100644 index 000000000000..a9e7a079190c --- /dev/null +++ b/Documentation/ABI/testing/sysfs-driver-ge-achc @@ -0,0 +1,15 @@ +What: /sys/bus/spi/<dev>/update_firmware +Date: Jul 2021 +Contact: sebastian.reichel@collabora.com +Description: Write 1 to this file to update the ACHC microcontroller + firmware via the EzPort interface. For this the kernel + will load "achc.bin" via the firmware API (so usually + from /lib/firmware). The write will block until the FW + has either been flashed successfully or an error occured. + +What: /sys/bus/spi/<dev>/reset +Date: Jul 2021 +Contact: sebastian.reichel@collabora.com +Description: This file represents the microcontroller's reset line. + 1 means the reset line is asserted, 0 means it's not + asserted. The file is read and writable. diff --git a/Documentation/ABI/testing/sysfs-driver-intc_sar b/Documentation/ABI/testing/sysfs-driver-intc_sar new file mode 100644 index 000000000000..ec334b0e5ed9 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-driver-intc_sar @@ -0,0 +1,54 @@ +What: /sys/bus/platform/devices/INTC1092:00/intc_reg +Date: August 2021 +KernelVersion: 5.15 +Contact: Shravan S <s.shravan@intel.com>, + An Sudhakar <sudhakar.an@intel.com> +Description: + Specific Absorption Rate (SAR) regulatory mode is typically + derived based on information like mcc (Mobile Country Code) and + mnc (Mobile Network Code) that is available for the currently + attached LTE network. A userspace application is required to set + the current SAR regulatory mode on the Dynamic SAR driver using + this sysfs node. Such an application can also read back using + this sysfs node, the currently configured regulatory mode value + from the Dynamic SAR driver. + + Acceptable regulatory modes are: + == ==== + 0 FCC + 1 CE + 2 ISED + == ==== + + - The regulatory mode value has one of the above values. + - The default regulatory mode used in the driver is 0. + +What: /sys/bus/platform/devices/INTC1092:00/intc_data +Date: August 2021 +KernelVersion: 5.15 +Contact: Shravan S <s.shravan@intel.com>, + An Sudhakar <sudhakar.an@intel.com> +Description: + This sysfs entry is used to retrieve Dynamic SAR information + emitted/maintained by a BIOS that supports Dynamic SAR. + + The retrieved information is in the order given below: + - device_mode + - bandtable_index + - antennatable_index + - sartable_index + + The above information is sent as integer values separated + by a single space. This information can then be pushed to a + WWAN modem that uses this to control the transmit signal + level using the Band/Antenna/SAR table index information. + These parameters are derived/decided by aggregating + device-mode like laptop/tablet/clamshell etc. and the + proximity-sensor data available to the embedded controller on + given host. The regulatory mode configured on Dynamic SAR + driver also influences these values. + + The userspace applications can poll for changes to this file + using POLLPRI event on file-descriptor (fd) obtained by opening + this sysfs entry. Application can then read this information from + the sysfs node and consume the given information. diff --git a/Documentation/ABI/testing/sysfs-driver-ufs b/Documentation/ABI/testing/sysfs-driver-ufs index b4a5d55fa19f..ec3a7149ced5 100644 --- a/Documentation/ABI/testing/sysfs-driver-ufs +++ b/Documentation/ABI/testing/sysfs-driver-ufs @@ -1298,3 +1298,239 @@ Description: This node is used to set or display whether UFS WriteBooster is (if the platform supports UFSHCD_CAP_CLK_SCALING). For a platform that doesn't support UFSHCD_CAP_CLK_SCALING, we can disable/enable WriteBooster through this sysfs node. + +What: /sys/bus/platform/drivers/ufshcd/*/device_descriptor/hpb_version +Date: June 2021 +Contact: Daejun Park <daejun7.park@samsung.com> +Description: This entry shows the HPB specification version. + The full information about the descriptor can be found in the UFS + HPB (Host Performance Booster) Extension specifications. + Example: version 1.2.3 = 0123h + + The file is read only. + +What: /sys/bus/platform/drivers/ufshcd/*/device_descriptor/hpb_control +Date: June 2021 +Contact: Daejun Park <daejun7.park@samsung.com> +Description: This entry shows an indication of the HPB control mode. + 00h: Host control mode + 01h: Device control mode + + The file is read only. + +What: /sys/bus/platform/drivers/ufshcd/*/geometry_descriptor/hpb_region_size +Date: June 2021 +Contact: Daejun Park <daejun7.park@samsung.com> +Description: This entry shows the bHPBRegionSize which can be calculated + as in the following (in bytes): + HPB Region size = 512B * 2^bHPBRegionSize + + The file is read only. + +What: /sys/bus/platform/drivers/ufshcd/*/geometry_descriptor/hpb_number_lu +Date: June 2021 +Contact: Daejun Park <daejun7.park@samsung.com> +Description: This entry shows the maximum number of HPB LU supported by + the device. + 00h: HPB is not supported by the device. + 01h ~ 20h: Maximum number of HPB LU supported by the device + + The file is read only. + +What: /sys/bus/platform/drivers/ufshcd/*/geometry_descriptor/hpb_subregion_size +Date: June 2021 +Contact: Daejun Park <daejun7.park@samsung.com> +Description: This entry shows the bHPBSubRegionSize, which can be + calculated as in the following (in bytes) and shall be a multiple of + logical block size: + HPB Sub-Region size = 512B x 2^bHPBSubRegionSize + bHPBSubRegionSize shall not exceed bHPBRegionSize. + + The file is read only. + +What: /sys/bus/platform/drivers/ufshcd/*/geometry_descriptor/hpb_max_active_regions +Date: June 2021 +Contact: Daejun Park <daejun7.park@samsung.com> +Description: This entry shows the maximum number of active HPB regions that + is supported by the device. + + The file is read only. + +What: /sys/class/scsi_device/*/device/unit_descriptor/hpb_lu_max_active_regions +Date: June 2021 +Contact: Daejun Park <daejun7.park@samsung.com> +Description: This entry shows the maximum number of HPB regions assigned to + the HPB logical unit. + + The file is read only. + +What: /sys/class/scsi_device/*/device/unit_descriptor/hpb_pinned_region_start_offset +Date: June 2021 +Contact: Daejun Park <daejun7.park@samsung.com> +Description: This entry shows the start offset of HPB pinned region. + + The file is read only. + +What: /sys/class/scsi_device/*/device/unit_descriptor/hpb_number_pinned_regions +Date: June 2021 +Contact: Daejun Park <daejun7.park@samsung.com> +Description: This entry shows the number of HPB pinned regions assigned to + the HPB logical unit. + + The file is read only. + +What: /sys/class/scsi_device/*/device/hpb_stats/hit_cnt +Date: June 2021 +Contact: Daejun Park <daejun7.park@samsung.com> +Description: This entry shows the number of reads that changed to HPB read. + + The file is read only. + +What: /sys/class/scsi_device/*/device/hpb_stats/miss_cnt +Date: June 2021 +Contact: Daejun Park <daejun7.park@samsung.com> +Description: This entry shows the number of reads that cannot be changed to + HPB read. + + The file is read only. + +What: /sys/class/scsi_device/*/device/hpb_stats/rb_noti_cnt +Date: June 2021 +Contact: Daejun Park <daejun7.park@samsung.com> +Description: This entry shows the number of response UPIUs that has + recommendations for activating sub-regions and/or inactivating region. + + The file is read only. + +What: /sys/class/scsi_device/*/device/hpb_stats/rb_active_cnt +Date: June 2021 +Contact: Daejun Park <daejun7.park@samsung.com> +Description: This entry shows the number of active sub-regions recommended by + response UPIUs. + + The file is read only. + +What: /sys/class/scsi_device/*/device/hpb_stats/rb_inactive_cnt +Date: June 2021 +Contact: Daejun Park <daejun7.park@samsung.com> +Description: This entry shows the number of inactive regions recommended by + response UPIUs. + + The file is read only. + +What: /sys/class/scsi_device/*/device/hpb_stats/map_req_cnt +Date: June 2021 +Contact: Daejun Park <daejun7.park@samsung.com> +Description: This entry shows the number of read buffer commands for + activating sub-regions recommended by response UPIUs. + + The file is read only. + +What: /sys/class/scsi_device/*/device/hpb_params/requeue_timeout_ms +Date: June 2021 +Contact: Daejun Park <daejun7.park@samsung.com> +Description: This entry shows the requeue timeout threshold for write buffer + command in ms. The value can be changed by writing an integer to + this entry. + +What: /sys/bus/platform/drivers/ufshcd/*/attributes/max_data_size_hpb_single_cmd +Date: June 2021 +Contact: Daejun Park <daejun7.park@samsung.com> +Description: This entry shows the maximum HPB data size for using a single HPB + command. + + === ======== + 00h 4KB + 01h 8KB + 02h 12KB + ... + FFh 1024KB + === ======== + + The file is read only. + +What: /sys/bus/platform/drivers/ufshcd/*/flags/hpb_enable +Date: June 2021 +Contact: Daejun Park <daejun7.park@samsung.com> +Description: This entry shows the status of HPB. + + == ============================ + 0 HPB is not enabled. + 1 HPB is enabled + == ============================ + + The file is read only. + +What: /sys/class/scsi_device/*/device/hpb_param_sysfs/activation_thld +Date: February 2021 +Contact: Avri Altman <avri.altman@wdc.com> +Description: In host control mode, reads are the major source of activation + trials. Once this threshold hs met, the region is added to the + "to-be-activated" list. Since we reset the read counter upon + write, this include sending a rb command updating the region + ppn as well. + +What: /sys/class/scsi_device/*/device/hpb_param_sysfs/normalization_factor +Date: February 2021 +Contact: Avri Altman <avri.altman@wdc.com> +Description: In host control mode, we think of the regions as "buckets". + Those buckets are being filled with reads, and emptied on write. + We use entries_per_srgn - the amount of blocks in a subregion as + our bucket size. This applies because HPB1.0 only handles + single-block reads. Once the bucket size is crossed, we trigger + a normalization work - not only to avoid overflow, but mainly + because we want to keep those counters normalized, as we are + using those reads as a comparative score, to make various decisions. + The normalization is dividing (shift right) the read counter by + the normalization_factor. If during consecutive normalizations + an active region has exhausted its reads - inactivate it. + +What: /sys/class/scsi_device/*/device/hpb_param_sysfs/eviction_thld_enter +Date: February 2021 +Contact: Avri Altman <avri.altman@wdc.com> +Description: Region deactivation is often due to the fact that eviction took + place: A region becomes active at the expense of another. This is + happening when the max-active-regions limit has been crossed. + In host mode, eviction is considered an extreme measure. We + want to verify that the entering region has enough reads, and + the exiting region has much fewer reads. eviction_thld_enter is + the min reads that a region must have in order to be considered + a candidate for evicting another region. + +What: /sys/class/scsi_device/*/device/hpb_param_sysfs/eviction_thld_exit +Date: February 2021 +Contact: Avri Altman <avri.altman@wdc.com> +Description: Same as above for the exiting region. A region is considered to + be a candidate for eviction only if it has fewer reads than + eviction_thld_exit. + +What: /sys/class/scsi_device/*/device/hpb_param_sysfs/read_timeout_ms +Date: February 2021 +Contact: Avri Altman <avri.altman@wdc.com> +Description: In order not to hang on to "cold" regions, we inactivate + a region that has no READ access for a predefined amount of + time - read_timeout_ms. If read_timeout_ms has expired, and the + region is dirty, it is less likely that we can make any use of + HPB reading it so we inactivate it. Still, deactivation has + its overhead, and we may still benefit from HPB reading this + region if it is clean - see read_timeout_expiries. + +What: /sys/class/scsi_device/*/device/hpb_param_sysfs/read_timeout_expiries +Date: February 2021 +Contact: Avri Altman <avri.altman@wdc.com> +Description: If the region read timeout has expired, but the region is clean, + just re-wind its timer for another spin. Do that as long as it + is clean and did not exhaust its read_timeout_expiries threshold. + +What: /sys/class/scsi_device/*/device/hpb_param_sysfs/timeout_polling_interval_ms +Date: February 2021 +Contact: Avri Altman <avri.altman@wdc.com> +Description: The frequency with which the delayed worker that checks the + read_timeouts is awakened. + +What: /sys/class/scsi_device/*/device/hpb_param_sysfs/inflight_map_req +Date: February 2021 +Contact: Avri Altman <avri.altman@wdc.com> +Description: In host control mode the host is the originator of map requests. + To avoid flooding the device with map requests, use a simple throttling + mechanism that limits the number of inflight map requests. diff --git a/Documentation/ABI/testing/sysfs-fs-f2fs b/Documentation/ABI/testing/sysfs-fs-f2fs index ef4b9218ae1e..f627e705e663 100644 --- a/Documentation/ABI/testing/sysfs-fs-f2fs +++ b/Documentation/ABI/testing/sysfs-fs-f2fs @@ -41,8 +41,7 @@ Description: This parameter controls the number of prefree segments to be What: /sys/fs/f2fs/<disk>/main_blkaddr Date: November 2019 Contact: "Ramon Pantin" <pantin@google.com> -Description: - Shows first block address of MAIN area. +Description: Shows first block address of MAIN area. What: /sys/fs/f2fs/<disk>/ipu_policy Date: November 2013 @@ -493,3 +492,23 @@ Contact: "Chao Yu" <yuchao0@huawei.com> Description: When ATGC is on, it controls age threshold to bypass GCing young candidates whose age is not beyond the threshold, by default it was initialized as 604800 seconds (equals to 7 days). + +What: /sys/fs/f2fs/<disk>/gc_reclaimed_segments +Date: July 2021 +Contact: "Daeho Jeong" <daehojeong@google.com> +Description: Show how many segments have been reclaimed by GC during a specific + GC mode (0: GC normal, 1: GC idle CB, 2: GC idle greedy, + 3: GC idle AT, 4: GC urgent high, 5: GC urgent low) + You can re-initialize this value to "0". + +What: /sys/fs/f2fs/<disk>/gc_segment_mode +Date: July 2021 +Contact: "Daeho Jeong" <daehojeong@google.com> +Description: You can control for which gc mode the "gc_reclaimed_segments" node shows. + Refer to the description of the modes in "gc_reclaimed_segments". + +What: /sys/fs/f2fs/<disk>/seq_file_ra_mul +Date: July 2021 +Contact: "Daeho Jeong" <daehojeong@google.com> +Description: You can control the multiplier value of bdi device readahead window size + between 2 (default) and 256 for POSIX_FADV_SEQUENTIAL advise option. diff --git a/Documentation/ABI/testing/sysfs-kernel-dmabuf-buffers b/Documentation/ABI/testing/sysfs-kernel-dmabuf-buffers new file mode 100644 index 000000000000..5d3bc997dc64 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-kernel-dmabuf-buffers @@ -0,0 +1,24 @@ +What: /sys/kernel/dmabuf/buffers +Date: May 2021 +KernelVersion: v5.13 +Contact: Hridya Valsaraju <hridya@google.com> +Description: The /sys/kernel/dmabuf/buffers directory contains a + snapshot of the internal state of every DMA-BUF. + /sys/kernel/dmabuf/buffers/<inode_number> will contain the + statistics for the DMA-BUF with the unique inode number + <inode_number> +Users: kernel memory tuning/debugging tools + +What: /sys/kernel/dmabuf/buffers/<inode_number>/exporter_name +Date: May 2021 +KernelVersion: v5.13 +Contact: Hridya Valsaraju <hridya@google.com> +Description: This file is read-only and contains the name of the exporter of + the DMA-BUF. + +What: /sys/kernel/dmabuf/buffers/<inode_number>/size +Date: May 2021 +KernelVersion: v5.13 +Contact: Hridya Valsaraju <hridya@google.com> +Description: This file is read-only and specifies the size of the DMA-BUF in + bytes. diff --git a/Documentation/ABI/testing/sysfs-kernel-iommu_groups b/Documentation/ABI/testing/sysfs-kernel-iommu_groups index eae2f1c1e11e..b15af6a5bc08 100644 --- a/Documentation/ABI/testing/sysfs-kernel-iommu_groups +++ b/Documentation/ABI/testing/sysfs-kernel-iommu_groups @@ -42,8 +42,12 @@ Description: /sys/kernel/iommu_groups/<grp_id>/type shows the type of default ======== ====================================================== DMA All the DMA transactions from the device in this group are translated by the iommu. + DMA-FQ As above, but using batched invalidation to lazily + remove translations after use. This may offer reduced + overhead at the cost of reduced memory protection. identity All the DMA transactions from the device in this group - are not translated by the iommu. + are not translated by the iommu. Maximum performance + but zero protection. auto Change to the type the device was booted with. ======== ====================================================== diff --git a/Documentation/ABI/testing/sysfs-kernel-mm-numa b/Documentation/ABI/testing/sysfs-kernel-mm-numa new file mode 100644 index 000000000000..77e559d4ed80 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-kernel-mm-numa @@ -0,0 +1,24 @@ +What: /sys/kernel/mm/numa/ +Date: June 2021 +Contact: Linux memory management mailing list <linux-mm@kvack.org> +Description: Interface for NUMA + +What: /sys/kernel/mm/numa/demotion_enabled +Date: June 2021 +Contact: Linux memory management mailing list <linux-mm@kvack.org> +Description: Enable/disable demoting pages during reclaim + + Page migration during reclaim is intended for systems + with tiered memory configurations. These systems have + multiple types of memory with varied performance + characteristics instead of plain NUMA systems where + the same kind of memory is found at varied distances. + Allowing page migration during reclaim enables these + systems to migrate pages from fast tiers to slow tiers + when the fast tier is under pressure. This migration + is performed before swap. It may move data to a NUMA + node that does not fall into the cpuset of the + allocating process which might be construed to violate + the guarantees of cpusets. This should not be enabled + on systems which need strict cpuset location + guarantees. diff --git a/Documentation/ABI/testing/sysfs-platform-dell-smbios b/Documentation/ABI/testing/sysfs-platform-dell-smbios index e6e0f7f834a7..5583da581025 100644 --- a/Documentation/ABI/testing/sysfs-platform-dell-smbios +++ b/Documentation/ABI/testing/sysfs-platform-dell-smbios @@ -1,7 +1,7 @@ What: /sys/devices/platform/<platform>/tokens/* Date: November 2017 KernelVersion: 4.15 -Contact: "Mario Limonciello" <mario.limonciello@dell.com> +Contact: Dell.Client.Kernel@dell.com Description: A read-only description of Dell platform tokens available on the machine. diff --git a/Documentation/ABI/testing/sysfs-platform-dptf b/Documentation/ABI/testing/sysfs-platform-dptf index 141834342a4d..53c6b1000320 100644 --- a/Documentation/ABI/testing/sysfs-platform-dptf +++ b/Documentation/ABI/testing/sysfs-platform-dptf @@ -111,3 +111,43 @@ Contact: linux-acpi@vger.kernel.org Description: (RW) The PCH FIVR (Fully Integrated Voltage Regulator) switching frequency in MHz, when FIVR clock is 38.4MHz. + +What: /sys/bus/platform/devices/INTC1045:00/pch_fivr_switch_frequency/fivr_switching_freq_mhz +Date: September, 2021 +KernelVersion: v5.15 +Contact: linux-acpi@vger.kernel.org +Description: + (RO) Get the FIVR switching control frequency in MHz. + +What: /sys/bus/platform/devices/INTC1045:00/pch_fivr_switch_frequency/fivr_switching_fault_status +Date: September, 2021 +KernelVersion: v5.15 +Contact: linux-acpi@vger.kernel.org +Description: + (RO) Read the FIVR switching frequency control fault status. + +What: /sys/bus/platform/devices/INTC1045:00/pch_fivr_switch_frequency/ssc_clock_info +Date: September, 2021 +KernelVersion: v5.15 +Contact: linux-acpi@vger.kernel.org +Description: + (RO) Presents SSC (spread spectrum clock) information for EMI + (Electro magnetic interference) control. This is a bit mask. + Bits Description + [7:0] Sets clock spectrum spread percentage: + 0x00=0.2% , 0x3F=10% + 1 LSB = 0.1% increase in spread (for + settings 0x01 thru 0x1C) + 1 LSB = 0.2% increase in spread (for + settings 0x1E thru 0x3F) + [8] When set to 1, enables spread + spectrum clock + [9] 0: Triangle mode. FFC frequency + walks around the Fcenter in a linear + fashion + 1: Random walk mode. FFC frequency + changes randomly within the SSC + (Spread spectrum clock) range + [10] 0: No white noise. 1: Add white noise + to spread waveform + [11] When 1, future writes are ignored. diff --git a/Documentation/ABI/testing/sysfs-platform-intel-wmi-thunderbolt b/Documentation/ABI/testing/sysfs-platform-intel-wmi-thunderbolt index e19144fd5d86..fd3a7ec79760 100644 --- a/Documentation/ABI/testing/sysfs-platform-intel-wmi-thunderbolt +++ b/Documentation/ABI/testing/sysfs-platform-intel-wmi-thunderbolt @@ -1,7 +1,7 @@ What: /sys/devices/platform/<platform>/force_power Date: September 2017 KernelVersion: 4.15 -Contact: "Mario Limonciello" <mario.limonciello@dell.com> +Contact: "Mario Limonciello" <mario.limonciello@outlook.com> Description: Modify the platform force power state, influencing Thunderbolt controllers to turn on or off when no diff --git a/Documentation/ABI/testing/sysfs-platform_profile b/Documentation/ABI/testing/sysfs-platform_profile index dae9c8941905..baf1d125f9f8 100644 --- a/Documentation/ABI/testing/sysfs-platform_profile +++ b/Documentation/ABI/testing/sysfs-platform_profile @@ -26,3 +26,10 @@ Contact: Hans de Goede <hdegoede@redhat.com> Description: Reading this file gives the current selected profile for this device. Writing this file with one of the strings from platform_profile_choices changes the profile to the new value. + + This file can be monitored for changes by polling for POLLPRI, + POLLPRI will be signalled on any changes, independent of those + changes coming from a userspace write; or coming from another + source such as e.g. a hotkey triggered profile change handled + either directly by the embedded-controller or fully handled + inside the kernel. diff --git a/Documentation/ABI/testing/sysfs-power b/Documentation/ABI/testing/sysfs-power index 51c0f578bfce..90ec4987074b 100644 --- a/Documentation/ABI/testing/sysfs-power +++ b/Documentation/ABI/testing/sysfs-power @@ -295,7 +295,7 @@ Description: What: /sys/power/resume_offset Date: April 2018 -Contact: Mario Limonciello <mario.limonciello@dell.com> +Contact: Mario Limonciello <mario.limonciello@outlook.com> Description: This file is used for telling the kernel an offset into a disk to use when hibernating the system such as with a swap file. diff --git a/Documentation/PCI/pci.rst b/Documentation/PCI/pci.rst index fa651e25d98c..87c6f4a6ca32 100644 --- a/Documentation/PCI/pci.rst +++ b/Documentation/PCI/pci.rst @@ -103,6 +103,7 @@ need pass only as many optional fields as necessary: - subvendor and subdevice fields default to PCI_ANY_ID (FFFFFFFF) - class and classmask fields default to 0 - driver_data defaults to 0UL. + - override_only field defaults to 0. Note that driver_data must match the value used by any of the pci_device_id entries defined in the driver. This makes the driver_data field mandatory diff --git a/Documentation/RCU/Design/Memory-Ordering/Tree-RCU-Memory-Ordering.rst b/Documentation/RCU/Design/Memory-Ordering/Tree-RCU-Memory-Ordering.rst index 11cdab037bff..eeb351296df1 100644 --- a/Documentation/RCU/Design/Memory-Ordering/Tree-RCU-Memory-Ordering.rst +++ b/Documentation/RCU/Design/Memory-Ordering/Tree-RCU-Memory-Ordering.rst @@ -112,6 +112,35 @@ on PowerPC. The ``smp_mb__after_unlock_lock()`` invocations prevent this ``WARN_ON()`` from triggering. ++-----------------------------------------------------------------------+ +| **Quick Quiz**: | ++-----------------------------------------------------------------------+ +| But the chain of rcu_node-structure lock acquisitions guarantees | +| that new readers will see all of the updater's pre-grace-period | +| accesses and also guarantees that the updater's post-grace-period | +| accesses will see all of the old reader's accesses. So why do we | +| need all of those calls to smp_mb__after_unlock_lock()? | ++-----------------------------------------------------------------------+ +| **Answer**: | ++-----------------------------------------------------------------------+ +| Because we must provide ordering for RCU's polling grace-period | +| primitives, for example, get_state_synchronize_rcu() and | +| poll_state_synchronize_rcu(). Consider this code:: | +| | +| CPU 0 CPU 1 | +| ---- ---- | +| WRITE_ONCE(X, 1) WRITE_ONCE(Y, 1) | +| g = get_state_synchronize_rcu() smp_mb() | +| while (!poll_state_synchronize_rcu(g)) r1 = READ_ONCE(X) | +| continue; | +| r0 = READ_ONCE(Y) | +| | +| RCU guarantees that the outcome r0 == 0 && r1 == 0 will not | +| happen, even if CPU 1 is in an RCU extended quiescent state | +| (idle or offline) and thus won't interact directly with the RCU | +| core processing at all. | ++-----------------------------------------------------------------------+ + This approach must be extended to include idle CPUs, which need RCU's grace-period memory ordering guarantee to extend to any RCU read-side critical sections preceding and following the current diff --git a/Documentation/RCU/Design/Requirements/Requirements.rst b/Documentation/RCU/Design/Requirements/Requirements.rst index 38a39476fc24..45278e2974c0 100644 --- a/Documentation/RCU/Design/Requirements/Requirements.rst +++ b/Documentation/RCU/Design/Requirements/Requirements.rst @@ -362,9 +362,8 @@ do_something_gp() uses rcu_dereference() to fetch from ``gp``: 12 } The rcu_dereference() uses volatile casts and (for DEC Alpha) memory -barriers in the Linux kernel. Should a `high-quality implementation of -C11 ``memory_order_consume`` -[PDF] <http://www.rdrop.com/users/paulmck/RCU/consume.2015.07.13a.pdf>`__ +barriers in the Linux kernel. Should a |high-quality implementation of +C11 memory_order_consume [PDF]|_ ever appear, then rcu_dereference() could be implemented as a ``memory_order_consume`` load. Regardless of the exact implementation, a pointer fetched by rcu_dereference() may not be used outside of the @@ -374,6 +373,9 @@ element has been passed from RCU to some other synchronization mechanism, most commonly locking or `reference counting <https://www.kernel.org/doc/Documentation/RCU/rcuref.txt>`__. +.. |high-quality implementation of C11 memory_order_consume [PDF]| replace:: high-quality implementation of C11 ``memory_order_consume`` [PDF] +.. _high-quality implementation of C11 memory_order_consume [PDF]: http://www.rdrop.com/users/paulmck/RCU/consume.2015.07.13a.pdf + In short, updaters use rcu_assign_pointer() and readers use rcu_dereference(), and these two RCU API elements work together to ensure that readers have a consistent view of newly added data elements. diff --git a/Documentation/RCU/checklist.rst b/Documentation/RCU/checklist.rst index 01cc21f17f7b..f4545b7c9a63 100644 --- a/Documentation/RCU/checklist.rst +++ b/Documentation/RCU/checklist.rst @@ -37,7 +37,7 @@ over a rather long period of time, but improvements are always welcome! 1. Does the update code have proper mutual exclusion? - RCU does allow -readers- to run (almost) naked, but -writers- must + RCU does allow *readers* to run (almost) naked, but *writers* must still use some sort of mutual exclusion, such as: a. locking, @@ -73,7 +73,7 @@ over a rather long period of time, but improvements are always welcome! critical section is every bit as bad as letting them leak out from under a lock. Unless, of course, you have arranged some other means of protection, such as a lock or a reference count - -before- letting them out of the RCU read-side critical section. + *before* letting them out of the RCU read-side critical section. 3. Does the update code tolerate concurrent accesses? @@ -101,7 +101,7 @@ over a rather long period of time, but improvements are always welcome! c. Make updates appear atomic to readers. For example, pointer updates to properly aligned fields will appear atomic, as will individual atomic primitives. - Sequences of operations performed under a lock will -not- + Sequences of operations performed under a lock will *not* appear to be atomic to RCU readers, nor will sequences of multiple atomic primitives. @@ -333,7 +333,7 @@ over a rather long period of time, but improvements are always welcome! for example) may be omitted. 10. Conversely, if you are in an RCU read-side critical section, - and you don't hold the appropriate update-side lock, you -must- + and you don't hold the appropriate update-side lock, you *must* use the "_rcu()" variants of the list macros. Failing to do so will break Alpha, cause aggressive compilers to generate bad code, and confuse people trying to read your code. @@ -359,12 +359,12 @@ over a rather long period of time, but improvements are always welcome! callback pending, then that RCU callback will execute on some surviving CPU. (If this was not the case, a self-spawning RCU callback would prevent the victim CPU from ever going offline.) - Furthermore, CPUs designated by rcu_nocbs= might well -always- + Furthermore, CPUs designated by rcu_nocbs= might well *always* have their RCU callbacks executed on some other CPUs, in fact, for some real-time workloads, this is the whole point of using the rcu_nocbs= kernel boot parameter. -13. Unlike other forms of RCU, it -is- permissible to block in an +13. Unlike other forms of RCU, it *is* permissible to block in an SRCU read-side critical section (demarked by srcu_read_lock() and srcu_read_unlock()), hence the "SRCU": "sleepable RCU". Please note that if you don't need to sleep in read-side critical @@ -411,16 +411,16 @@ over a rather long period of time, but improvements are always welcome! 14. The whole point of call_rcu(), synchronize_rcu(), and friends is to wait until all pre-existing readers have finished before carrying out some otherwise-destructive operation. It is - therefore critically important to -first- remove any path + therefore critically important to *first* remove any path that readers can follow that could be affected by the - destructive operation, and -only- -then- invoke call_rcu(), + destructive operation, and *only then* invoke call_rcu(), synchronize_rcu(), or friends. Because these primitives only wait for pre-existing readers, it is the caller's responsibility to guarantee that any subsequent readers will execute safely. -15. The various RCU read-side primitives do -not- necessarily contain +15. The various RCU read-side primitives do *not* necessarily contain memory barriers. You should therefore plan for the CPU and the compiler to freely reorder code into and out of RCU read-side critical sections. It is the responsibility of the @@ -459,8 +459,8 @@ over a rather long period of time, but improvements are always welcome! pass in a function defined within a loadable module, then it in necessary to wait for all pending callbacks to be invoked after the last invocation and before unloading that module. Note that - it is absolutely -not- sufficient to wait for a grace period! - The current (say) synchronize_rcu() implementation is -not- + it is absolutely *not* sufficient to wait for a grace period! + The current (say) synchronize_rcu() implementation is *not* guaranteed to wait for callbacks registered on other CPUs. Or even on the current CPU if that CPU recently went offline and came back online. @@ -470,7 +470,7 @@ over a rather long period of time, but improvements are always welcome! - call_rcu() -> rcu_barrier() - call_srcu() -> srcu_barrier() - However, these barrier functions are absolutely -not- guaranteed + However, these barrier functions are absolutely *not* guaranteed to wait for a grace period. In fact, if there are no call_rcu() callbacks waiting anywhere in the system, rcu_barrier() is within its rights to return immediately. diff --git a/Documentation/RCU/rcu_dereference.rst b/Documentation/RCU/rcu_dereference.rst index f3e587acb4de..0b418a5b243c 100644 --- a/Documentation/RCU/rcu_dereference.rst +++ b/Documentation/RCU/rcu_dereference.rst @@ -43,7 +43,7 @@ Follow these rules to keep your RCU code working properly: - 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. + *not* work in general for char* pointers. - XOR bits to translate pointers, as is done in some classic buddy-allocator algorithms. @@ -174,7 +174,7 @@ Follow these rules to keep your RCU code working properly: Please see the "CONTROL DEPENDENCIES" section of Documentation/memory-barriers.txt for more details. - - 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. @@ -360,7 +360,7 @@ in turn destroying the ordering between this load and the loads of the return values. This can result in "p->b" returning pre-initialization garbage values. -In short, rcu_dereference() is -not- optional when you are going to +In short, rcu_dereference() is *not* optional when you are going to dereference the resulting pointer. diff --git a/Documentation/RCU/stallwarn.rst b/Documentation/RCU/stallwarn.rst index 7148e9be08c3..5036df24ae61 100644 --- a/Documentation/RCU/stallwarn.rst +++ b/Documentation/RCU/stallwarn.rst @@ -32,7 +32,7 @@ warnings: - Booting Linux using a console connection that is too slow to keep up with the boot-time console-message rate. For example, - a 115Kbaud serial console can be -way- too slow to keep up + a 115Kbaud serial console can be *way* too slow to keep up with boot-time message rates, and will frequently result in RCU CPU stall warning messages. Especially if you have added debug printk()s. @@ -105,7 +105,7 @@ warnings: leading the realization that the CPU had failed. The RCU, RCU-sched, and RCU-tasks implementations have CPU stall warning. -Note that SRCU does -not- have CPU stall warnings. Please note that +Note that SRCU does *not* have CPU stall warnings. Please note that RCU only detects CPU stalls when there is a grace period in progress. No grace period, no CPU stall warnings. @@ -145,7 +145,7 @@ CONFIG_RCU_CPU_STALL_TIMEOUT this parameter is checked only at the beginning of a cycle. So if you are 10 seconds into a 40-second stall, setting this sysfs parameter to (say) five will shorten the timeout for the - -next- stall, or the following warning for the current stall + *next* stall, or the following warning for the current stall (assuming the stall lasts long enough). It will not affect the timing of the next warning for the current stall. @@ -189,8 +189,8 @@ rcupdate.rcu_task_stall_timeout Interpreting RCU's CPU Stall-Detector "Splats" ============================================== -For non-RCU-tasks flavors of RCU, when a CPU detects that it is stalling, -it will print a message similar to the following:: +For non-RCU-tasks flavors of RCU, when a CPU detects that some other +CPU is stalling, it will print a message similar to the following:: INFO: rcu_sched detected stalls on CPUs/tasks: 2-...: (3 GPs behind) idle=06c/0/0 softirq=1453/1455 fqs=0 @@ -202,8 +202,10 @@ causing stalls, and that the stall was affecting RCU-sched. This message will normally be followed by stack dumps for each CPU. Please note that PREEMPT_RCU builds can be stalled by tasks as well as by CPUs, and that the tasks will be indicated by PID, for example, "P3421". It is even -possible for an rcu_state stall to be caused by both CPUs -and- tasks, +possible for an rcu_state stall to be caused by both CPUs *and* tasks, in which case the offending CPUs and tasks will all be called out in the list. +In some cases, CPUs will detect themselves stalling, which will result +in a self-detected stall. CPU 2's "(3 GPs behind)" indicates that this CPU has not interacted with the RCU core for the past three grace periods. In contrast, CPU 16's "(0 @@ -224,7 +226,7 @@ is the number that had executed since boot at the time that this CPU last noted the beginning of a grace period, which might be the current (stalled) grace period, or it might be some earlier grace period (for example, if the CPU might have been in dyntick-idle mode for an extended -time period. The number after the "/" is the number that have executed +time period). The number after the "/" is the number that have executed since boot until the current time. If this latter number stays constant across repeated stall-warning messages, it is possible that RCU's softirq handlers are no longer able to execute on this CPU. This can happen if @@ -283,7 +285,8 @@ If the relevant grace-period kthread has been unable to run prior to the stall warning, as was the case in the "All QSes seen" line above, the following additional line is printed:: - kthread starved for 23807 jiffies! g7075 f0x0 RCU_GP_WAIT_FQS(3) ->state=0x1 ->cpu=5 + rcu_sched kthread starved for 23807 jiffies! g7075 f0x0 RCU_GP_WAIT_FQS(3) ->state=0x1 ->cpu=5 + Unless rcu_sched kthread gets sufficient CPU time, OOM is now expected behavior. Starving the grace-period kthreads of CPU time can of course result in RCU CPU stall warnings even when all CPUs and tasks have passed @@ -313,15 +316,21 @@ is the current ``TIMER_SOFTIRQ`` count on cpu 4. If this value does not change on successive RCU CPU stall warnings, there is further reason to suspect a timer problem. +These messages are usually followed by stack dumps of the CPUs and tasks +involved in the stall. These stack traces can help you locate the cause +of the stall, keeping in mind that the CPU detecting the stall will have +an interrupt frame that is mainly devoted to detecting the stall. + Multiple Warnings From One Stall ================================ -If a stall lasts long enough, multiple stall-warning messages will be -printed for it. The second and subsequent messages are printed at +If a stall lasts long enough, multiple stall-warning messages will +be printed for it. The second and subsequent messages are printed at longer intervals, so that the time between (say) the first and second message will be about three times the interval between the beginning -of the stall and the first message. +of the stall and the first message. It can be helpful to compare the +stack dumps for the different messages for the same stalled grace period. Stall Warnings for Expedited Grace Periods diff --git a/Documentation/admin-guide/binderfs.rst b/Documentation/admin-guide/binderfs.rst index 199d84314a14..41a4db00df8d 100644 --- a/Documentation/admin-guide/binderfs.rst +++ b/Documentation/admin-guide/binderfs.rst @@ -72,3 +72,16 @@ that the `rm() <rm_>`_ tool can be used to delete them. Note that the ``binder-control`` device cannot be deleted since this would make the binderfs instance unusable. The ``binder-control`` device will be deleted when the binderfs instance is unmounted and all references to it have been dropped. + +Binder features +--------------- + +Assuming an instance of binderfs has been mounted at ``/dev/binderfs``, the +features supported by the binder driver can be located under +``/dev/binderfs/features/``. The presence of individual files can be tested +to determine whether a particular feature is supported by the driver. + +Example:: + + cat /dev/binderfs/features/oneway_spam_detection + 1 diff --git a/Documentation/admin-guide/cgroup-v2.rst b/Documentation/admin-guide/cgroup-v2.rst index 5c7377b5bd3e..babbe04c8d37 100644 --- a/Documentation/admin-guide/cgroup-v2.rst +++ b/Documentation/admin-guide/cgroup-v2.rst @@ -2056,6 +2056,17 @@ Cpuset Interface Files The value of "cpuset.mems" stays constant until the next update and won't be affected by any memory nodes hotplug events. + Setting a non-empty value to "cpuset.mems" causes memory of + tasks within the cgroup to be migrated to the designated nodes if + they are currently using memory outside of the designated nodes. + + There is a cost for this memory migration. The migration + may not be complete and some memory pages may be left behind. + So it is recommended that "cpuset.mems" should be set properly + before spawning new tasks into the cpuset. Even if there is + a need to change "cpuset.mems" with active tasks, it shouldn't + be done frequently. + cpuset.mems.effective A read-only multiple values file which exists on all cpuset-enabled cgroups. diff --git a/Documentation/admin-guide/cputopology.rst b/Documentation/admin-guide/cputopology.rst index 8632a1db36e4..b085dbac60a5 100644 --- a/Documentation/admin-guide/cputopology.rst +++ b/Documentation/admin-guide/cputopology.rst @@ -58,9 +58,9 @@ source for the output is in brackets ("[]"). [NR_CPUS-1] offline: CPUs that are not online because they have been - HOTPLUGGED off (see cpu-hotplug.txt) or exceed the limit - of CPUs allowed by the kernel configuration (kernel_max - above). [~cpu_online_mask + cpus >= NR_CPUS] + HOTPLUGGED off or exceed the limit of CPUs allowed by the + kernel configuration (kernel_max above). + [~cpu_online_mask + cpus >= NR_CPUS] online: CPUs that are online and being scheduled [cpu_online_mask] @@ -96,5 +96,5 @@ online.):: possible: 0-127 present: 0-3 -See cpu-hotplug.txt for the possible_cpus=NUM kernel start parameter -as well as more information on the various cpumasks. +See Documentation/core-api/cpu_hotplug.rst for the possible_cpus=NUM +kernel start parameter as well as more information on the various cpumasks. diff --git a/Documentation/admin-guide/device-mapper/dm-ima.rst b/Documentation/admin-guide/device-mapper/dm-ima.rst new file mode 100644 index 000000000000..a4aa50a828e0 --- /dev/null +++ b/Documentation/admin-guide/device-mapper/dm-ima.rst @@ -0,0 +1,715 @@ +====== +dm-ima +====== + +For a given system, various external services/infrastructure tools +(including the attestation service) interact with it - both during the +setup and during rest of the system run-time. They share sensitive data +and/or execute critical workload on that system. The external services +may want to verify the current run-time state of the relevant kernel +subsystems before fully trusting the system with business-critical +data/workload. + +Device mapper plays a critical role on a given system by providing +various important functionalities to the block devices using various +target types like crypt, verity, integrity etc. Each of these target +types’ functionalities can be configured with various attributes. +The attributes chosen to configure these target types can significantly +impact the security profile of the block device, and in-turn, of the +system itself. For instance, the type of encryption algorithm and the +key size determines the strength of encryption for a given block device. + +Therefore, verifying the current state of various block devices as well +as their various target attributes is crucial for external services before +fully trusting the system with business-critical data/workload. + +IMA kernel subsystem provides the necessary functionality for +device mapper to measure the state and configuration of +various block devices - + +- by device mapper itself, from within the kernel, +- in a tamper resistant way, +- and re-measured - triggered on state/configuration change. + +Setting the IMA Policy: +======================= +For IMA to measure the data on a given system, the IMA policy on the +system needs to be updated to have following line, and the system needs +to be restarted for the measurements to take effect. + +:: + + /etc/ima/ima-policy + measure func=CRITICAL_DATA label=device-mapper template=ima-buf + +The measurements will be reflected in the IMA logs, which are located at: + +:: + + /sys/kernel/security/integrity/ima/ascii_runtime_measurements + /sys/kernel/security/integrity/ima/binary_runtime_measurements + +Then IMA ASCII measurement log has the following format: + +:: + + <PCR> <TEMPLATE_DATA_DIGEST> <TEMPLATE_NAME> <TEMPLATE_DATA> + + PCR := Platform Configuration Register, in which the values are registered. + This is applicable if TPM chip is in use. + + TEMPLATE_DATA_DIGEST := Template data digest of the IMA record. + TEMPLATE_NAME := Template name that registered the integrity value (e.g. ima-buf). + + TEMPLATE_DATA := <ALG> ":" <EVENT_DIGEST> <EVENT_NAME> <EVENT_DATA> + It contains data for the specific event to be measured, + in a given template data format. + + ALG := Algorithm to compute event digest + EVENT_DIGEST := Digest of the event data + EVENT_NAME := Description of the event (e.g. 'dm_table_load'). + EVENT_DATA := The event data to be measured. + +| + +| *NOTE #1:* +| The DM target data measured by IMA subsystem can alternatively + be queried from userspace by setting DM_IMA_MEASUREMENT_FLAG with + DM_TABLE_STATUS_CMD. + +| + +| *NOTE #2:* +| The Kernel configuration CONFIG_IMA_DISABLE_HTABLE allows measurement of duplicate records. +| To support recording duplicate IMA events in the IMA log, the Kernel needs to be configured with + CONFIG_IMA_DISABLE_HTABLE=y. + +Supported Device States: +======================== +Following device state changes will trigger IMA measurements: + + 1. Table load + #. Device resume + #. Device remove + #. Table clear + #. Device rename + +1. Table load: +--------------- +When a new table is loaded in a device's inactive table slot, +the device information and target specific details from the +targets in the table are measured. + +The IMA measurement log has the following format for 'dm_table_load': + +:: + + EVENT_NAME := "dm_table_load" + EVENT_DATA := <dm_version_str> ";" <device_metadata> ";" <table_load_data> + + dm_version_str := "dm_version=" <N> "." <N> "." <N> + Same as Device Mapper driver version. + device_metadata := <device_name> "," <device_uuid> "," <device_major> "," <device_minor> "," + <minor_count> "," <num_device_targets> ";" + + device_name := "name=" <dm-device-name> + device_uuid := "uuid=" <dm-device-uuid> + device_major := "major=" <N> + device_minor := "minor=" <N> + minor_count := "minor_count=" <N> + num_device_targets := "num_targets=" <N> + dm-device-name := Name of the device. If it contains special characters like '\', ',', ';', + they are prefixed with '\'. + dm-device-uuid := UUID of the device. If it contains special characters like '\', ',', ';', + they are prefixed with '\'. + + table_load_data := <target_data> + Represents the data (as name=value pairs) from various targets in the table, + which is being loaded into the DM device's inactive table slot. + target_data := <target_data_row> | <target_data><target_data_row> + + target_data_row := <target_index> "," <target_begin> "," <target_len> "," <target_name> "," + <target_version> "," <target_attributes> ";" + target_index := "target_index=" <N> + Represents nth target in the table (from 0 to N-1 targets specified in <num_device_targets>) + If all the data for N targets doesn't fit in the given buffer - then the data that fits + in the buffer (say from target 0 to x) is measured in a given IMA event. + The remaining data from targets x+1 to N-1 is measured in the subsequent IMA events, + with the same format as that of 'dm_table_load' + i.e. <dm_version_str> ";" <device_metadata> ";" <table_load_data>. + + target_begin := "target_begin=" <N> + target_len := "target_len=" <N> + target_name := Name of the target. 'linear', 'crypt', 'integrity' etc. + The targets that are supported for IMA measurements are documented below in the + 'Supported targets' section. + target_version := "target_version=" <N> "." <N> "." <N> + target_attributes := Data containing comma separated list of name=value pairs of target specific attributes. + + For instance, if a linear device is created with the following table entries, + # dmsetup create linear1 + 0 2 linear /dev/loop0 512 + 2 2 linear /dev/loop0 512 + 4 2 linear /dev/loop0 512 + 6 2 linear /dev/loop0 512 + + Then IMA ASCII measurement log will have the following entry: + (converted from ASCII to text for readability) + + 10 a8c5ff755561c7a28146389d1514c318592af49a ima-buf sha256:4d73481ecce5eadba8ab084640d85bb9ca899af4d0a122989252a76efadc5b72 + dm_table_load + dm_version=4.45.0; + name=linear1,uuid=,major=253,minor=0,minor_count=1,num_targets=4; + target_index=0,target_begin=0,target_len=2,target_name=linear,target_version=1.4.0,device_name=7:0,start=512; + target_index=1,target_begin=2,target_len=2,target_name=linear,target_version=1.4.0,device_name=7:0,start=512; + target_index=2,target_begin=4,target_len=2,target_name=linear,target_version=1.4.0,device_name=7:0,start=512; + target_index=3,target_begin=6,target_len=2,target_name=linear,target_version=1.4.0,device_name=7:0,start=512; + +2. Device resume: +------------------ +When a suspended device is resumed, the device information and the hash of the +data from previous load of an active table are measured. + +The IMA measurement log has the following format for 'dm_device_resume': + +:: + + EVENT_NAME := "dm_device_resume" + EVENT_DATA := <dm_version_str> ";" <device_metadata> ";" <active_table_hash> ";" <current_device_capacity> ";" + + dm_version_str := As described in the 'Table load' section above. + device_metadata := As described in the 'Table load' section above. + active_table_hash := "active_table_hash=" <table_hash_alg> ":" <table_hash> + Rerpresents the hash of the IMA data being measured for the + active table for the device. + table_hash_alg := Algorithm used to compute the hash. + table_hash := Hash of the (<dm_version_str> ";" <device_metadata> ";" <table_load_data> ";") + as described in the 'dm_table_load' above. + Note: If the table_load data spans across multiple IMA 'dm_table_load' + events for a given device, the hash is computed combining all the event data + i.e. (<dm_version_str> ";" <device_metadata> ";" <table_load_data> ";") + across all those events. + current_device_capacity := "current_device_capacity=" <N> + + For instance, if a linear device is resumed with the following command, + #dmsetup resume linear1 + + then IMA ASCII measurement log will have an entry with: + (converted from ASCII to text for readability) + + 10 56c00cc062ffc24ccd9ac2d67d194af3282b934e ima-buf sha256:e7d12c03b958b4e0e53e7363a06376be88d98a1ac191fdbd3baf5e4b77f329b6 + dm_device_resume + dm_version=4.45.0; + name=linear1,uuid=,major=253,minor=0,minor_count=1,num_targets=4; + active_table_hash=sha256:4d73481ecce5eadba8ab084640d85bb9ca899af4d0a122989252a76efadc5b72;current_device_capacity=8; + +3. Device remove: +------------------ +When a device is removed, the device information and a sha256 hash of the +data from an active and inactive table are measured. + +The IMA measurement log has the following format for 'dm_device_remove': + +:: + + EVENT_NAME := "dm_device_remove" + EVENT_DATA := <dm_version_str> ";" <device_active_metadata> ";" <device_inactive_metadata> ";" + <active_table_hash> "," <inactive_table_hash> "," <remove_all> ";" <current_device_capacity> ";" + + dm_version_str := As described in the 'Table load' section above. + device_active_metadata := Device metadata that reflects the currently loaded active table. + The format is same as 'device_metadata' described in the 'Table load' section above. + device_inactive_metadata := Device metadata that reflects the inactive table. + The format is same as 'device_metadata' described in the 'Table load' section above. + active_table_hash := Hash of the currently loaded active table. + The format is same as 'active_table_hash' described in the 'Device resume' section above. + inactive_table_hash := Hash of the inactive table. + The format is same as 'active_table_hash' described in the 'Device resume' section above. + remove_all := "remove_all=" <yes_no> + yes_no := "y" | "n" + current_device_capacity := "current_device_capacity=" <N> + + For instance, if a linear device is removed with the following command, + #dmsetup remove l1 + + then IMA ASCII measurement log will have the following entry: + (converted from ASCII to text for readability) + + 10 790e830a3a7a31590824ac0642b3b31c2d0e8b38 ima-buf sha256:ab9f3c959367a8f5d4403d6ce9c3627dadfa8f9f0e7ec7899299782388de3840 + dm_device_remove + dm_version=4.45.0; + device_active_metadata=name=l1,uuid=,major=253,minor=2,minor_count=1,num_targets=2; + device_inactive_metadata=name=l1,uuid=,major=253,minor=2,minor_count=1,num_targets=1; + active_table_hash=sha256:4a7e62efaebfc86af755831998b7db6f59b60d23c9534fb16a4455907957953a, + inactive_table_hash=sha256:9d79c175bc2302d55a183e8f50ad4bafd60f7692fd6249e5fd213e2464384b86,remove_all=n; + current_device_capacity=2048; + +4. Table clear: +---------------- +When an inactive table is cleared from the device, the device information and a sha256 hash of the +data from an inactive table are measured. + +The IMA measurement log has the following format for 'dm_table_clear': + +:: + + EVENT_NAME := "dm_table_clear" + EVENT_DATA := <dm_version_str> ";" <device_inactive_metadata> ";" <inactive_table_hash> ";" <current_device_capacity> ";" + + dm_version_str := As described in the 'Table load' section above. + device_inactive_metadata := Device metadata that was captured during the load time inactive table being cleared. + The format is same as 'device_metadata' described in the 'Table load' section above. + inactive_table_hash := Hash of the inactive table being cleared from the device. + The format is same as 'active_table_hash' described in the 'Device resume' section above. + current_device_capacity := "current_device_capacity=" <N> + + For instance, if a linear device's inactive table is cleared, + #dmsetup clear l1 + + then IMA ASCII measurement log will have an entry with: + (converted from ASCII to text for readability) + + 10 77d347408f557f68f0041acb0072946bb2367fe5 ima-buf sha256:42f9ca22163fdfa548e6229dece2959bc5ce295c681644240035827ada0e1db5 + dm_table_clear + dm_version=4.45.0; + name=l1,uuid=,major=253,minor=2,minor_count=1,num_targets=1; + inactive_table_hash=sha256:75c0dc347063bf474d28a9907037eba060bfe39d8847fc0646d75e149045d545;current_device_capacity=1024; + +5. Device rename: +------------------ +When an device's NAME or UUID is changed, the device information and the new NAME and UUID +are measured. + +The IMA measurement log has the following format for 'dm_device_rename': + +:: + + EVENT_NAME := "dm_device_rename" + EVENT_DATA := <dm_version_str> ";" <device_active_metadata> ";" <new_device_name> "," <new_device_uuid> ";" <current_device_capacity> ";" + + dm_version_str := As described in the 'Table load' section above. + device_active_metadata := Device metadata that reflects the currently loaded active table. + The format is same as 'device_metadata' described in the 'Table load' section above. + new_device_name := "new_name=" <dm-device-name> + dm-device-name := Same as <dm-device-name> described in 'Table load' section above + new_device_uuid := "new_uuid=" <dm-device-uuid> + dm-device-uuid := Same as <dm-device-uuid> described in 'Table load' section above + current_device_capacity := "current_device_capacity=" <N> + + E.g 1: if a linear device's name is changed with the following command, + #dmsetup rename linear1 --setuuid 1234-5678 + + then IMA ASCII measurement log will have an entry with: + (converted from ASCII to text for readability) + + 10 8b0423209b4c66ac1523f4c9848c9b51ee332f48 ima-buf sha256:6847b7258134189531db593e9230b257c84f04038b5a18fd2e1473860e0569ac + dm_device_rename + dm_version=4.45.0; + name=linear1,uuid=,major=253,minor=2,minor_count=1,num_targets=1;new_name=linear1,new_uuid=1234-5678; + current_device_capacity=1024; + + E.g 2: if a linear device's name is changed with the following command, + # dmsetup rename linear1 linear=2 + + then IMA ASCII measurement log will have an entry with: + (converted from ASCII to text for readability) + + 10 bef70476b99c2bdf7136fae033aa8627da1bf76f ima-buf sha256:8c6f9f53b9ef9dc8f92a2f2cca8910e622543d0f0d37d484870cb16b95111402 + dm_device_rename + dm_version=4.45.0; + name=linear1,uuid=1234-5678,major=253,minor=2,minor_count=1,num_targets=1; + new_name=linear\=2,new_uuid=1234-5678; + current_device_capacity=1024; + +Supported targets: +================== + +Following targets are supported to measure their data using IMA: + + 1. cache + #. crypt + #. integrity + #. linear + #. mirror + #. multipath + #. raid + #. snapshot + #. striped + #. verity + +1. cache +--------- +The 'target_attributes' (described as part of EVENT_DATA in 'Table load' +section above) has the following data format for 'cache' target. + +:: + + target_attributes := <target_name> "," <target_version> "," <metadata_mode> "," <cache_metadata_device> "," + <cache_device> "," <cache_origin_device> "," <writethrough> "," <writeback> "," + <passthrough> "," <no_discard_passdown> ";" + + target_name := "target_name=cache" + target_version := "target_version=" <N> "." <N> "." <N> + metadata_mode := "metadata_mode=" <cache_metadata_mode> + cache_metadata_mode := "fail" | "ro" | "rw" + cache_device := "cache_device=" <cache_device_name_string> + cache_origin_device := "cache_origin_device=" <cache_origin_device_string> + writethrough := "writethrough=" <yes_no> + writeback := "writeback=" <yes_no> + passthrough := "passthrough=" <yes_no> + no_discard_passdown := "no_discard_passdown=" <yes_no> + yes_no := "y" | "n" + + E.g. + When a 'cache' target is loaded, then IMA ASCII measurement log will have an entry + similar to the following, depicting what 'cache' attributes are measured in EVENT_DATA + for 'dm_table_load' event. + (converted from ASCII to text for readability) + + dm_version=4.45.0;name=cache1,uuid=cache_uuid,major=253,minor=2,minor_count=1,num_targets=1; + target_index=0,target_begin=0,target_len=28672,target_name=cache,target_version=2.2.0,metadata_mode=rw, + cache_metadata_device=253:4,cache_device=253:3,cache_origin_device=253:5,writethrough=y,writeback=n, + passthrough=n,metadata2=y,no_discard_passdown=n; + + +2. crypt +--------- +The 'target_attributes' (described as part of EVENT_DATA in 'Table load' +section above) has the following data format for 'crypt' target. + +:: + + target_attributes := <target_name> "," <target_version> "," <allow_discards> "," <same_cpu_crypt> "," + <submit_from_crypt_cpus> "," <no_read_workqueue> "," <no_write_workqueue> "," + <iv_large_sectors> "," <iv_large_sectors> "," [<integrity_tag_size> ","] [<cipher_auth> ","] + [<sector_size> ","] [<cipher_string> ","] <key_size> "," <key_parts> "," + <key_extra_size> "," <key_mac_size> ";" + + target_name := "target_name=crypt" + target_version := "target_version=" <N> "." <N> "." <N> + allow_discards := "allow_discards=" <yes_no> + same_cpu_crypt := "same_cpu_crypt=" <yes_no> + submit_from_crypt_cpus := "submit_from_crypt_cpus=" <yes_no> + no_read_workqueue := "no_read_workqueue=" <yes_no> + no_write_workqueue := "no_write_workqueue=" <yes_no> + iv_large_sectors := "iv_large_sectors=" <yes_no> + integrity_tag_size := "integrity_tag_size=" <N> + cipher_auth := "cipher_auth=" <string> + sector_size := "sector_size=" <N> + cipher_string := "cipher_string=" + key_size := "key_size=" <N> + key_parts := "key_parts=" <N> + key_extra_size := "key_extra_size=" <N> + key_mac_size := "key_mac_size=" <N> + yes_no := "y" | "n" + + E.g. + When a 'crypt' target is loaded, then IMA ASCII measurement log will have an entry + similar to the following, depicting what 'crypt' attributes are measured in EVENT_DATA + for 'dm_table_load' event. + (converted from ASCII to text for readability) + + dm_version=4.45.0; + name=crypt1,uuid=crypt_uuid1,major=253,minor=0,minor_count=1,num_targets=1; + target_index=0,target_begin=0,target_len=1953125,target_name=crypt,target_version=1.23.0, + allow_discards=y,same_cpu=n,submit_from_crypt_cpus=n,no_read_workqueue=n,no_write_workqueue=n, + iv_large_sectors=n,cipher_string=aes-xts-plain64,key_size=32,key_parts=1,key_extra_size=0,key_mac_size=0; + +3. integrity +------------- +The 'target_attributes' (described as part of EVENT_DATA in 'Table load' +section above) has the following data format for 'integrity' target. + +:: + + target_attributes := <target_name> "," <target_version> "," <dev_name> "," <start> + <tag_size> "," <mode> "," [<meta_device> ","] [<block_size> ","] <recalculate> "," + <allow_discards> "," <fix_padding> "," <fix_hmac> "," <legacy_recalculate> "," + <journal_sectors> "," <interleave_sectors> "," <buffer_sectors> ";" + + target_name := "target_name=integrity" + target_version := "target_version=" <N> "." <N> "." <N> + dev_name := "dev_name=" <device_name_str> + start := "start=" <N> + tag_size := "tag_size=" <N> + mode := "mode=" <integrity_mode_str> + integrity_mode_str := "J" | "B" | "D" | "R" + meta_device := "meta_device=" <meta_device_str> + block_size := "block_size=" <N> + recalculate := "recalculate=" <yes_no> + allow_discards := "allow_discards=" <yes_no> + fix_padding := "fix_padding=" <yes_no> + fix_hmac := "fix_hmac=" <yes_no> + legacy_recalculate := "legacy_recalculate=" <yes_no> + journal_sectors := "journal_sectors=" <N> + interleave_sectors := "interleave_sectors=" <N> + buffer_sectors := "buffer_sectors=" <N> + yes_no := "y" | "n" + + E.g. + When a 'integrity' target is loaded, then IMA ASCII measurement log will have an entry + similar to the following, depicting what 'integrity' attributes are measured in EVENT_DATA + for 'dm_table_load' event. + (converted from ASCII to text for readability) + + dm_version=4.45.0; + name=integrity1,uuid=,major=253,minor=1,minor_count=1,num_targets=1; + target_index=0,target_begin=0,target_len=7856,target_name=integrity,target_version=1.10.0, + dev_name=253:0,start=0,tag_size=32,mode=J,recalculate=n,allow_discards=n,fix_padding=n, + fix_hmac=n,legacy_recalculate=n,journal_sectors=88,interleave_sectors=32768,buffer_sectors=128; + + +4. linear +---------- +The 'target_attributes' (described as part of EVENT_DATA in 'Table load' +section above) has the following data format for 'linear' target. + +:: + + target_attributes := <target_name> "," <target_version> "," <device_name> <,> <start> ";" + + target_name := "target_name=linear" + target_version := "target_version=" <N> "." <N> "." <N> + device_name := "device_name=" <linear_device_name_str> + start := "start=" <N> + + E.g. + When a 'linear' target is loaded, then IMA ASCII measurement log will have an entry + similar to the following, depicting what 'linear' attributes are measured in EVENT_DATA + for 'dm_table_load' event. + (converted from ASCII to text for readability) + + dm_version=4.45.0; + name=linear1,uuid=linear_uuid1,major=253,minor=2,minor_count=1,num_targets=1; + target_index=0,target_begin=0,target_len=28672,target_name=linear,target_version=1.4.0, + device_name=253:1,start=2048; + +5. mirror +---------- +The 'target_attributes' (described as part of EVENT_DATA in 'Table load' +section above) has the following data format for 'mirror' target. + +:: + + target_attributes := <target_name> "," <target_version> "," <nr_mirrors> "," + <mirror_device_data> "," <handle_errors> "," <keep_log> "," <log_type_status> ";" + + target_name := "target_name=mirror" + target_version := "target_version=" <N> "." <N> "." <N> + nr_mirrors := "nr_mirrors=" <NR> + mirror_device_data := <mirror_device_row> | <mirror_device_data><mirror_device_row> + mirror_device_row is repeated <NR> times - for <NR> described in <nr_mirrors>. + mirror_device_row := <mirror_device_name> "," <mirror_device_status> + mirror_device_name := "mirror_device_" <X> "=" <mirror_device_name_str> + where <X> ranges from 0 to (<NR> -1) - for <NR> described in <nr_mirrors>. + mirror_device_status := "mirror_device_" <X> "_status=" <mirror_device_status_char> + where <X> ranges from 0 to (<NR> -1) - for <NR> described in <nr_mirrors>. + mirror_device_status_char := "A" | "F" | "D" | "S" | "R" | "U" + handle_errors := "handle_errors=" <yes_no> + keep_log := "keep_log=" <yes_no> + log_type_status := "log_type_status=" <log_type_status_str> + yes_no := "y" | "n" + + E.g. + When a 'mirror' target is loaded, then IMA ASCII measurement log will have an entry + similar to the following, depicting what 'mirror' attributes are measured in EVENT_DATA + for 'dm_table_load' event. + (converted from ASCII to text for readability) + + dm_version=4.45.0; + name=mirror1,uuid=mirror_uuid1,major=253,minor=6,minor_count=1,num_targets=1; + target_index=0,target_begin=0,target_len=2048,target_name=mirror,target_version=1.14.0,nr_mirrors=2, + mirror_device_0=253:4,mirror_device_0_status=A, + mirror_device_1=253:5,mirror_device_1_status=A, + handle_errors=y,keep_log=n,log_type_status=; + +6. multipath +------------- +The 'target_attributes' (described as part of EVENT_DATA in 'Table load' +section above) has the following data format for 'multipath' target. + +:: + + target_attributes := <target_name> "," <target_version> "," <nr_priority_groups> + ["," <pg_state> "," <priority_groups> "," <priority_group_paths>] ";" + + target_name := "target_name=multipath" + target_version := "target_version=" <N> "." <N> "." <N> + nr_priority_groups := "nr_priority_groups=" <NPG> + priority_groups := <priority_groups_row>|<priority_groups_row><priority_groups> + priority_groups_row := "pg_state_" <X> "=" <pg_state_str> "," "nr_pgpaths_" <X> "=" <NPGP> "," + "path_selector_name_" <X> "=" <string> "," <priority_group_paths> + where <X> ranges from 0 to (<NPG> -1) - for <NPG> described in <nr_priority_groups>. + pg_state_str := "E" | "A" | "D" + <priority_group_paths> := <priority_group_paths_row> | <priority_group_paths_row><priority_group_paths> + priority_group_paths_row := "path_name_" <X> "_" <Y> "=" <string> "," "is_active_" <X> "_" <Y> "=" <is_active_str> + "fail_count_" <X> "_" <Y> "=" <N> "," "path_selector_status_" <X> "_" <Y> "=" <path_selector_status_str> + where <X> ranges from 0 to (<NPG> -1) - for <NPG> described in <nr_priority_groups>, + and <Y> ranges from 0 to (<NPGP> -1) - for <NPGP> described in <priority_groups_row>. + is_active_str := "A" | "F" + + E.g. + When a 'multipath' target is loaded, then IMA ASCII measurement log will have an entry + similar to the following, depicting what 'multipath' attributes are measured in EVENT_DATA + for 'dm_table_load' event. + (converted from ASCII to text for readability) + + dm_version=4.45.0; + name=mp,uuid=,major=253,minor=0,minor_count=1,num_targets=1; + target_index=0,target_begin=0,target_len=2097152,target_name=multipath,target_version=1.14.0,nr_priority_groups=2, + pg_state_0=E,nr_pgpaths_0=2,path_selector_name_0=queue-length, + path_name_0_0=8:16,is_active_0_0=A,fail_count_0_0=0,path_selector_status_0_0=, + path_name_0_1=8:32,is_active_0_1=A,fail_count_0_1=0,path_selector_status_0_1=, + pg_state_1=E,nr_pgpaths_1=2,path_selector_name_1=queue-length, + path_name_1_0=8:48,is_active_1_0=A,fail_count_1_0=0,path_selector_status_1_0=, + path_name_1_1=8:64,is_active_1_1=A,fail_count_1_1=0,path_selector_status_1_1=; + +7. raid +-------- +The 'target_attributes' (described as part of EVENT_DATA in 'Table load' +section above) has the following data format for 'raid' target. + +:: + + target_attributes := <target_name> "," <target_version> "," <raid_type> "," <raid_disks> "," <raid_state> + <raid_device_status> ["," journal_dev_mode] ";" + + target_name := "target_name=raid" + target_version := "target_version=" <N> "." <N> "." <N> + raid_type := "raid_type=" <raid_type_str> + raid_disks := "raid_disks=" <NRD> + raid_state := "raid_state=" <raid_state_str> + raid_state_str := "frozen" | "reshape" |"resync" | "check" | "repair" | "recover" | "idle" |"undef" + raid_device_status := <raid_device_status_row> | <raid_device_status_row><raid_device_status> + <raid_device_status_row> is repeated <NRD> times - for <NRD> described in <raid_disks>. + raid_device_status_row := "raid_device_" <X> "_status=" <raid_device_status_str> + where <X> ranges from 0 to (<NRD> -1) - for <NRD> described in <raid_disks>. + raid_device_status_str := "A" | "D" | "a" | "-" + journal_dev_mode := "journal_dev_mode=" <journal_dev_mode_str> + journal_dev_mode_str := "writethrough" | "writeback" | "invalid" + + E.g. + When a 'raid' target is loaded, then IMA ASCII measurement log will have an entry + similar to the following, depicting what 'raid' attributes are measured in EVENT_DATA + for 'dm_table_load' event. + (converted from ASCII to text for readability) + + dm_version=4.45.0; + name=raid_LV1,uuid=uuid_raid_LV1,major=253,minor=12,minor_count=1,num_targets=1; + target_index=0,target_begin=0,target_len=2048,target_name=raid,target_version=1.15.1, + raid_type=raid10,raid_disks=4,raid_state=idle, + raid_device_0_status=A, + raid_device_1_status=A, + raid_device_2_status=A, + raid_device_3_status=A; + + +8. snapshot +------------ +The 'target_attributes' (described as part of EVENT_DATA in 'Table load' +section above) has the following data format for 'snapshot' target. + +:: + + target_attributes := <target_name> "," <target_version> "," <snap_origin_name> "," + <snap_cow_name> "," <snap_valid> "," <snap_merge_failed> "," <snapshot_overflowed> ";" + + target_name := "target_name=snapshot" + target_version := "target_version=" <N> "." <N> "." <N> + snap_origin_name := "snap_origin_name=" <string> + snap_cow_name := "snap_cow_name=" <string> + snap_valid := "snap_valid=" <yes_no> + snap_merge_failed := "snap_merge_failed=" <yes_no> + snapshot_overflowed := "snapshot_overflowed=" <yes_no> + yes_no := "y" | "n" + + E.g. + When a 'snapshot' target is loaded, then IMA ASCII measurement log will have an entry + similar to the following, depicting what 'snapshot' attributes are measured in EVENT_DATA + for 'dm_table_load' event. + (converted from ASCII to text for readability) + + dm_version=4.45.0; + name=snap1,uuid=snap_uuid1,major=253,minor=13,minor_count=1,num_targets=1; + target_index=0,target_begin=0,target_len=4096,target_name=snapshot,target_version=1.16.0, + snap_origin_name=253:11,snap_cow_name=253:12,snap_valid=y,snap_merge_failed=n,snapshot_overflowed=n; + +9. striped +----------- +The 'target_attributes' (described as part of EVENT_DATA in 'Table load' +section above) has the following data format for 'striped' target. + +:: + + target_attributes := <target_name> "," <target_version> "," <stripes> "," <chunk_size> "," + <stripe_data> ";" + + target_name := "target_name=striped" + target_version := "target_version=" <N> "." <N> "." <N> + stripes := "stripes=" <NS> + chunk_size := "chunk_size=" <N> + stripe_data := <stripe_data_row>|<stripe_data><stripe_data_row> + stripe_data_row := <stripe_device_name> "," <stripe_physical_start> "," <stripe_status> + stripe_device_name := "stripe_" <X> "_device_name=" <stripe_device_name_str> + where <X> ranges from 0 to (<NS> -1) - for <NS> described in <stripes>. + stripe_physical_start := "stripe_" <X> "_physical_start=" <N> + where <X> ranges from 0 to (<NS> -1) - for <NS> described in <stripes>. + stripe_status := "stripe_" <X> "_status=" <stripe_status_str> + where <X> ranges from 0 to (<NS> -1) - for <NS> described in <stripes>. + stripe_status_str := "D" | "A" + + E.g. + When a 'striped' target is loaded, then IMA ASCII measurement log will have an entry + similar to the following, depicting what 'striped' attributes are measured in EVENT_DATA + for 'dm_table_load' event. + (converted from ASCII to text for readability) + + dm_version=4.45.0; + name=striped1,uuid=striped_uuid1,major=253,minor=5,minor_count=1,num_targets=1; + target_index=0,target_begin=0,target_len=640,target_name=striped,target_version=1.6.0,stripes=2,chunk_size=64, + stripe_0_device_name=253:0,stripe_0_physical_start=2048,stripe_0_status=A, + stripe_1_device_name=253:3,stripe_1_physical_start=2048,stripe_1_status=A; + +10. verity +---------- +The 'target_attributes' (described as part of EVENT_DATA in 'Table load' +section above) has the following data format for 'verity' target. + +:: + + target_attributes := <target_name> "," <target_version> "," <hash_failed> "," <verity_version> "," + <data_device_name> "," <hash_device_name> "," <verity_algorithm> "," <root_digest> "," + <salt> "," <ignore_zero_blocks> "," <check_at_most_once> ["," <root_hash_sig_key_desc>] + ["," <verity_mode>] ";" + + target_name := "target_name=verity" + target_version := "target_version=" <N> "." <N> "." <N> + hash_failed := "hash_failed=" <hash_failed_str> + hash_failed_str := "C" | "V" + verity_version := "verity_version=" <verity_version_str> + data_device_name := "data_device_name=" <data_device_name_str> + hash_device_name := "hash_device_name=" <hash_device_name_str> + verity_algorithm := "verity_algorithm=" <verity_algorithm_str> + root_digest := "root_digest=" <root_digest_str> + salt := "salt=" <salt_str> + salt_str := "-" <verity_salt_str> + ignore_zero_blocks := "ignore_zero_blocks=" <yes_no> + check_at_most_once := "check_at_most_once=" <yes_no> + root_hash_sig_key_desc := "root_hash_sig_key_desc=" + verity_mode := "verity_mode=" <verity_mode_str> + verity_mode_str := "ignore_corruption" | "restart_on_corruption" | "panic_on_corruption" | "invalid" + yes_no := "y" | "n" + + E.g. + When a 'verity' target is loaded, then IMA ASCII measurement log will have an entry + similar to the following, depicting what 'verity' attributes are measured in EVENT_DATA + for 'dm_table_load' event. + (converted from ASCII to text for readability) + + dm_version=4.45.0; + name=test-verity,uuid=,major=253,minor=2,minor_count=1,num_targets=1; + target_index=0,target_begin=0,target_len=1953120,target_name=verity,target_version=1.8.0,hash_failed=V, + verity_version=1,data_device_name=253:1,hash_device_name=253:0,verity_algorithm=sha256, + root_digest=29cb87e60ce7b12b443ba6008266f3e41e93e403d7f298f8e3f316b29ff89c5e, + salt=e48da609055204e89ae53b655ca2216dd983cf3cb829f34f63a297d106d53e2d, + ignore_zero_blocks=n,check_at_most_once=n; diff --git a/Documentation/admin-guide/device-mapper/index.rst b/Documentation/admin-guide/device-mapper/index.rst index 6cf8adc86fa8..cde52cc09645 100644 --- a/Documentation/admin-guide/device-mapper/index.rst +++ b/Documentation/admin-guide/device-mapper/index.rst @@ -13,6 +13,7 @@ Device Mapper dm-dust dm-ebs dm-flakey + dm-ima dm-init dm-integrity dm-io diff --git a/Documentation/admin-guide/device-mapper/writecache.rst b/Documentation/admin-guide/device-mapper/writecache.rst index 65427d8dfca6..10429779a91a 100644 --- a/Documentation/admin-guide/device-mapper/writecache.rst +++ b/Documentation/admin-guide/device-mapper/writecache.rst @@ -78,13 +78,23 @@ Status: 2. the number of blocks 3. the number of free blocks 4. the number of blocks under writeback +5. the number of read requests +6. the number of read requests that hit the cache +7. the number of write requests +8. the number of write requests that hit uncommitted block +9. the number of write requests that hit committed block +10. the number of write requests that bypass the cache +11. the number of write requests that are allocated in the cache +12. the number of write requests that are blocked on the freelist +13. the number of flush requests +14. the number of discard requests Messages: flush - flush the cache device. The message returns successfully + Flush the cache device. The message returns successfully if the cache device was flushed without an error flush_on_suspend - flush the cache device on next suspend. Use this message + Flush the cache device on next suspend. Use this message when you are going to remove the cache device. The proper sequence for removing the cache device is: @@ -98,3 +108,5 @@ Messages: 6. the cache device is now inactive and it can be deleted cleaner See above "cleaner" constructor documentation. + clear_stats + Clear the statistics that are reported on the status line diff --git a/Documentation/admin-guide/devices.txt b/Documentation/admin-guide/devices.txt index 9c2be821c225..922c23bb4372 100644 --- a/Documentation/admin-guide/devices.txt +++ b/Documentation/admin-guide/devices.txt @@ -2993,10 +2993,10 @@ 65 = /dev/infiniband/issm1 Second InfiniBand IsSM device ... 127 = /dev/infiniband/issm63 63rd InfiniBand IsSM device - 128 = /dev/infiniband/uverbs0 First InfiniBand verbs device - 129 = /dev/infiniband/uverbs1 Second InfiniBand verbs device + 192 = /dev/infiniband/uverbs0 First InfiniBand verbs device + 193 = /dev/infiniband/uverbs1 Second InfiniBand verbs device ... - 159 = /dev/infiniband/uverbs31 31st InfiniBand verbs device + 223 = /dev/infiniband/uverbs31 31st InfiniBand verbs device 232 char Biometric Devices 0 = /dev/biometric/sensor0/fingerprint first fingerprint sensor on first device diff --git a/Documentation/admin-guide/hw-vuln/core-scheduling.rst b/Documentation/admin-guide/hw-vuln/core-scheduling.rst index 7b410aef9c5c..0febe458597c 100644 --- a/Documentation/admin-guide/hw-vuln/core-scheduling.rst +++ b/Documentation/admin-guide/hw-vuln/core-scheduling.rst @@ -181,10 +181,12 @@ Open cross-HT issues that core scheduling does not solve -------------------------------------------------------- 1. For MDS ~~~~~~~~~~ -Core scheduling cannot protect against MDS attacks between an HT running in -user mode and another running in kernel mode. Even though both HTs run tasks -which trust each other, kernel memory is still considered untrusted. Such -attacks are possible for any combination of sibling CPU modes (host or guest mode). +Core scheduling cannot protect against MDS attacks between the siblings +running in user mode and the others running in kernel mode. Even though all +siblings run tasks which trust each other, when the kernel is executing +code on behalf of a task, it cannot trust the code running in the +sibling. Such attacks are possible for any combination of sibling CPU modes +(host or guest mode). 2. For L1TF ~~~~~~~~~~~ diff --git a/Documentation/admin-guide/hw-vuln/index.rst b/Documentation/admin-guide/hw-vuln/index.rst index f12cda55538b..8cbc711cda93 100644 --- a/Documentation/admin-guide/hw-vuln/index.rst +++ b/Documentation/admin-guide/hw-vuln/index.rst @@ -16,3 +16,4 @@ are configurable at compile, boot or run time. multihit.rst special-register-buffer-data-sampling.rst core-scheduling.rst + l1d_flush.rst diff --git a/Documentation/admin-guide/hw-vuln/l1d_flush.rst b/Documentation/admin-guide/hw-vuln/l1d_flush.rst new file mode 100644 index 000000000000..210020bc3f56 --- /dev/null +++ b/Documentation/admin-guide/hw-vuln/l1d_flush.rst @@ -0,0 +1,69 @@ +L1D Flushing +============ + +With an increasing number of vulnerabilities being reported around data +leaks from the Level 1 Data cache (L1D) the kernel provides an opt-in +mechanism to flush the L1D cache on context switch. + +This mechanism can be used to address e.g. CVE-2020-0550. For applications +the mechanism keeps them safe from vulnerabilities, related to leaks +(snooping of) from the L1D cache. + + +Related CVEs +------------ +The following CVEs can be addressed by this +mechanism + + ============= ======================== ================== + CVE-2020-0550 Improper Data Forwarding OS related aspects + ============= ======================== ================== + +Usage Guidelines +---------------- + +Please see document: :ref:`Documentation/userspace-api/spec_ctrl.rst +<set_spec_ctrl>` for details. + +**NOTE**: The feature is disabled by default, applications need to +specifically opt into the feature to enable it. + +Mitigation +---------- + +When PR_SET_L1D_FLUSH is enabled for a task a flush of the L1D cache is +performed when the task is scheduled out and the incoming task belongs to a +different process and therefore to a different address space. + +If the underlying CPU supports L1D flushing in hardware, the hardware +mechanism is used, software fallback for the mitigation, is not supported. + +Mitigation control on the kernel command line +--------------------------------------------- + +The kernel command line allows to control the L1D flush mitigations at boot +time with the option "l1d_flush=". The valid arguments for this option are: + + ============ ============================================================= + on Enables the prctl interface, applications trying to use + the prctl() will fail with an error if l1d_flush is not + enabled + ============ ============================================================= + +By default the mechanism is disabled. + +Limitations +----------- + +The mechanism does not mitigate L1D data leaks between tasks belonging to +different processes which are concurrently executing on sibling threads of +a physical CPU core when SMT is enabled on the system. + +This can be addressed by controlled placement of processes on physical CPU +cores or by disabling SMT. See the relevant chapter in the L1TF mitigation +document: :ref:`Documentation/admin-guide/hw-vuln/l1tf.rst <smt_control>`. + +**NOTE** : The opt-in of a task for L1D flushing works only when the task's +affinity is limited to cores running in non-SMT mode. If a task which +requested L1D flushing is scheduled on a SMT-enabled core the kernel sends +a SIGBUS to the task. diff --git a/Documentation/admin-guide/kernel-parameters.txt b/Documentation/admin-guide/kernel-parameters.txt index bdb22006f713..828d11441ebf 100644 --- a/Documentation/admin-guide/kernel-parameters.txt +++ b/Documentation/admin-guide/kernel-parameters.txt @@ -287,13 +287,21 @@ do not want to use tracing_snapshot_alloc() as it needs to be done where GFP_KERNEL allocations are allowed. + allow_mismatched_32bit_el0 [ARM64] + Allow execve() of 32-bit applications and setting of the + PER_LINUX32 personality on systems where only a strict + subset of the CPUs support 32-bit EL0. When this + parameter is present, the set of CPUs supporting 32-bit + EL0 is indicated by /sys/devices/system/cpu/aarch32_el0 + and hot-unplug operations may be restricted. + + See Documentation/arm64/asymmetric-32bit.rst for more + information. + amd_iommu= [HW,X86-64] Pass parameters to the AMD IOMMU driver in the system. Possible values are: - fullflush - enable flushing of IO/TLB entries when - they are unmapped. Otherwise they are - flushed before they will be reused, which - is a lot of faster + fullflush - Deprecated, equivalent to iommu.strict=1 off - do not initialize any AMD IOMMU found in the system force_isolation - Force device isolation for all @@ -380,6 +388,9 @@ arm64.nopauth [ARM64] Unconditionally disable Pointer Authentication support + arm64.nomte [ARM64] Unconditionally disable Memory Tagging Extension + support + ataflop= [HW,M68k] atarimouse= [HW,MOUSE] Atari Mouse @@ -1944,18 +1955,17 @@ this case, gfx device will use physical address for DMA. strict [Default Off] - With this option on every unmap_single operation will - result in a hardware IOTLB flush operation as opposed - to batching them for performance. + Deprecated, equivalent to iommu.strict=1. sp_off [Default Off] By default, super page will be supported if Intel IOMMU has the capability. With this option, super page will not be supported. - sm_on [Default Off] - By default, scalable mode will be disabled even if the - hardware advertises that it has support for the scalable - mode translation. With this option set, scalable mode - will be used on hardware which claims to support it. + sm_on + Enable the Intel IOMMU scalable mode if the hardware + advertises that it has support for the scalable mode + translation. + sm_off + Disallow use of the Intel IOMMU scalable mode. tboot_noforce [Default Off] Do not force the Intel IOMMU enabled under tboot. By default, tboot will force Intel IOMMU on, which @@ -2047,13 +2057,12 @@ throughput at the cost of reduced device isolation. Will fall back to strict mode if not supported by the relevant IOMMU driver. - 1 - Strict mode (default). + 1 - Strict mode. DMA unmap operations invalidate IOMMU hardware TLBs synchronously. - Note: on x86, the default behaviour depends on the - equivalent driver-specific parameters, but a strict - mode explicitly specified by either method takes - precedence. + unset - Use value of CONFIG_IOMMU_DEFAULT_DMA_{LAZY,STRICT}. + Note: on x86, strict mode specified via one of the + legacy driver-specific options takes precedence. iommu.passthrough= [ARM64, X86] Configure DMA to bypass the IOMMU by default. @@ -2421,6 +2430,23 @@ feature (tagged TLBs) on capable Intel chips. Default is 1 (enabled) + l1d_flush= [X86,INTEL] + Control mitigation for L1D based snooping vulnerability. + + Certain CPUs are vulnerable to an exploit against CPU + internal buffers which can forward information to a + disclosure gadget under certain conditions. + + In vulnerable processors, the speculatively + forwarded data can be used in a cache side channel + attack, to access data to which the attacker does + not have direct access. + + This parameter controls the mitigation. The + options are: + + on - enable the interface for the mitigation + l1tf= [X86] Control mitigation of the L1TF vulnerability on affected CPUs @@ -4167,6 +4193,15 @@ Format: <bool> (1/Y/y=enable, 0/N/n=disable) default: disabled + printk.console_no_auto_verbose= + Disable console loglevel raise on oops, panic + or lockdep-detected issues (only if lock debug is on). + With an exception to setups with low baudrate on + serial console, keeping this 0 is a good choice + in order to provide more debug information. + Format: <bool> + default: 0 (auto_verbose is enabled) + printk.devkmsg={on,off,ratelimit} Control writing to /dev/kmsg. on - unlimited logging to /dev/kmsg from userspace @@ -4777,7 +4812,7 @@ reboot= [KNL] Format (x86 or x86_64): - [w[arm] | c[old] | h[ard] | s[oft] | g[pio]] \ + [w[arm] | c[old] | h[ard] | s[oft] | g[pio]] | d[efault] \ [[,]s[mp]#### \ [[,]b[ios] | a[cpi] | k[bd] | t[riple] | e[fi] | p[ci]] \ [[,]f[orce] @@ -4945,8 +4980,6 @@ sa1100ir [NET] See drivers/net/irda/sa1100_ir.c. - sbni= [NET] Granch SBNI12 leased line adapter - sched_verbose [KNL] Enables verbose scheduler debug messages. schedstats= [KNL,X86] Enable or disable scheduled statistics. diff --git a/Documentation/admin-guide/laptops/lg-laptop.rst b/Documentation/admin-guide/laptops/lg-laptop.rst index ce9b14671cb9..6fbe165dcd27 100644 --- a/Documentation/admin-guide/laptops/lg-laptop.rst +++ b/Documentation/admin-guide/laptops/lg-laptop.rst @@ -13,10 +13,8 @@ Hotkeys The following FN keys are ignored by the kernel without this driver: - FN-F1 (LG control panel) - Generates F15 -- FN-F5 (Touchpad toggle) - Generates F13 +- FN-F5 (Touchpad toggle) - Generates F21 - FN-F6 (Airplane mode) - Generates RFKILL -- FN-F8 (Keyboard backlight) - Generates F16. - This key also changes keyboard backlight mode. - FN-F9 (Reader mode) - Generates F14 The rest of the FN keys work without a need for a special driver. diff --git a/Documentation/admin-guide/mm/numa_memory_policy.rst b/Documentation/admin-guide/mm/numa_memory_policy.rst index 067a90a1499c..64fd0ba0d057 100644 --- a/Documentation/admin-guide/mm/numa_memory_policy.rst +++ b/Documentation/admin-guide/mm/numa_memory_policy.rst @@ -245,6 +245,13 @@ MPOL_INTERLEAVED address range or file. During system boot up, the temporary interleaved system default policy works in this mode. +MPOL_PREFERRED_MANY + This mode specifices that the allocation should be preferrably + satisfied from the nodemask specified in the policy. If there is + a memory pressure on all nodes in the nodemask, the allocation + can fall back to all existing numa nodes. This is effectively + MPOL_PREFERRED allowed for a mask rather than a single node. + NUMA memory policy supports the following optional mode flags: MPOL_F_STATIC_NODES @@ -253,10 +260,10 @@ MPOL_F_STATIC_NODES nodes changes after the memory policy has been defined. Without this flag, any time a mempolicy is rebound because of a - change in the set of allowed nodes, the node (Preferred) or - nodemask (Bind, Interleave) is remapped to the new set of - allowed nodes. This may result in nodes being used that were - previously undesired. + change in the set of allowed nodes, the preferred nodemask (Preferred + Many), preferred node (Preferred) or nodemask (Bind, Interleave) is + remapped to the new set of allowed nodes. This may result in nodes + being used that were previously undesired. With this flag, if the user-specified nodes overlap with the nodes allowed by the task's cpuset, then the memory policy is diff --git a/Documentation/admin-guide/sysctl/vm.rst b/Documentation/admin-guide/sysctl/vm.rst index 003d5cc3751b..5e795202111f 100644 --- a/Documentation/admin-guide/sysctl/vm.rst +++ b/Documentation/admin-guide/sysctl/vm.rst @@ -118,7 +118,8 @@ compaction_proactiveness This tunable takes a value in the range [0, 100] with a default value of 20. This tunable determines how aggressively compaction is done in the -background. Setting it to 0 disables proactive compaction. +background. Write of a non zero value to this tunable will immediately +trigger the proactive compaction. Setting it to 0 disables proactive compaction. Note that compaction has a non-trivial system-wide impact as pages belonging to different processes are moved around, which could also lead diff --git a/Documentation/admin-guide/sysrq.rst b/Documentation/admin-guide/sysrq.rst index 60ce5f5ebab6..0a178ef0111d 100644 --- a/Documentation/admin-guide/sysrq.rst +++ b/Documentation/admin-guide/sysrq.rst @@ -72,7 +72,7 @@ On PowerPC On other If you know of the key combos for other architectures, please - let me know so I can add them to this section. + submit a patch to be included in this section. On all Write a character to /proc/sysrq-trigger. e.g.:: @@ -205,10 +205,12 @@ frozen (probably root) filesystem via the FIFREEZE ioctl. Sometimes SysRq seems to get 'stuck' after using it, what can I do? ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -That happens to me, also. I've found that tapping shift, alt, and control -on both sides of the keyboard, and hitting an invalid sysrq sequence again -will fix the problem. (i.e., something like :kbd:`alt-sysrq-z`). Switching to -another virtual console (:kbd:`ALT+Fn`) and then back again should also help. +When this happens, try tapping shift, alt and control on both sides of the +keyboard, and hitting an invalid sysrq sequence again. (i.e., something like +:kbd:`alt-sysrq-z`). + +Switching to another virtual console (:kbd:`ALT+Fn`) and then back again +should also help. I hit SysRq, but nothing seems to happen, what's wrong? ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/Documentation/arm/marvell.rst b/Documentation/arm/marvell.rst index db2246493d18..85169bc3f538 100644 --- a/Documentation/arm/marvell.rst +++ b/Documentation/arm/marvell.rst @@ -58,11 +58,19 @@ Kirkwood family - Product Brief : https://web.archive.org/web/20120616201621/http://www.marvell.com/embedded-processors/kirkwood/assets/88F6180-003_ver1.pdf - Hardware Spec : https://web.archive.org/web/20130730091654/http://www.marvell.com/embedded-processors/kirkwood/assets/HW_88F6180_OpenSource.pdf - Functional Spec: https://web.archive.org/web/20130730091033/http://www.marvell.com/embedded-processors/kirkwood/assets/FS_88F6180_9x_6281_OpenSource.pdf + - 88F6280 + + - Product Brief : https://web.archive.org/web/20130730091058/http://www.marvell.com/embedded-processors/kirkwood/assets/88F6280_SoC_PB-001.pdf - 88F6281 - Product Brief : https://web.archive.org/web/20120131133709/http://www.marvell.com/embedded-processors/kirkwood/assets/88F6281-004_ver1.pdf - Hardware Spec : https://web.archive.org/web/20120620073511/http://www.marvell.com/embedded-processors/kirkwood/assets/HW_88F6281_OpenSource.pdf - Functional Spec: https://web.archive.org/web/20130730091033/http://www.marvell.com/embedded-processors/kirkwood/assets/FS_88F6180_9x_6281_OpenSource.pdf + - 88F6321 + - 88F6322 + - 88F6323 + + - Product Brief : https://web.archive.org/web/20120616201639/http://www.marvell.com/embedded-processors/kirkwood/assets/88f632x_pb.pdf Homepage: https://web.archive.org/web/20160513194943/http://www.marvell.com/embedded-processors/kirkwood/ Core: @@ -89,6 +97,10 @@ Discovery family - MV76100 + - Product Brief : https://web.archive.org/web/20140722064429/http://www.marvell.com/embedded-processors/discovery-innovation/assets/MV76100-002_WEB.pdf + - Hardware Spec : https://web.archive.org/web/20140722064425/http://www.marvell.com/embedded-processors/discovery-innovation/assets/HW_MV76100_OpenSource.pdf + - Functional Spec: https://web.archive.org/web/20111110081125/http://www.marvell.com/embedded-processors/discovery-innovation/assets/FS_MV76100_78100_78200_OpenSource.pdf + Not supported by the Linux kernel. Core: @@ -124,17 +136,23 @@ EBU Armada family Armada 38x Flavors: - 88F6810 Armada 380 + - 88F6811 Armada 381 + - 88F6821 Armada 382 + - 88F6W21 Armada 383 - 88F6820 Armada 385 - 88F6828 Armada 388 - Product infos: https://web.archive.org/web/20181006144616/http://www.marvell.com/embedded-processors/armada-38x/ - Functional Spec: https://web.archive.org/web/20200420191927/https://www.marvell.com/content/dam/marvell/en/public-collateral/embedded-processors/marvell-embedded-processors-armada-38x-functional-specifications-2015-11.pdf + - Hardware Spec: https://web.archive.org/web/20180713105318/https://www.marvell.com/docs/embedded-processors/assets/marvell-embedded-processors-armada-38x-hardware-specifications-2017-03.pdf + - Design guide: https://web.archive.org/web/20180712231737/https://www.marvell.com/docs/embedded-processors/assets/marvell-embedded-processors-armada-38x-hardware-design-guide-2017-08.pdf Core: ARM Cortex-A9 Armada 39x Flavors: - 88F6920 Armada 390 + - 88F6925 Armada 395 - 88F6928 Armada 398 - Product infos: https://web.archive.org/web/20181020222559/http://www.marvell.com/embedded-processors/armada-39x/ diff --git a/Documentation/arm64/asymmetric-32bit.rst b/Documentation/arm64/asymmetric-32bit.rst new file mode 100644 index 000000000000..64a0b505da7d --- /dev/null +++ b/Documentation/arm64/asymmetric-32bit.rst @@ -0,0 +1,155 @@ +====================== +Asymmetric 32-bit SoCs +====================== + +Author: Will Deacon <will@kernel.org> + +This document describes the impact of asymmetric 32-bit SoCs on the +execution of 32-bit (``AArch32``) applications. + +Date: 2021-05-17 + +Introduction +============ + +Some Armv9 SoCs suffer from a big.LITTLE misfeature where only a subset +of the CPUs are capable of executing 32-bit user applications. On such +a system, Linux by default treats the asymmetry as a "mismatch" and +disables support for both the ``PER_LINUX32`` personality and +``execve(2)`` of 32-bit ELF binaries, with the latter returning +``-ENOEXEC``. If the mismatch is detected during late onlining of a +64-bit-only CPU, then the onlining operation fails and the new CPU is +unavailable for scheduling. + +Surprisingly, these SoCs have been produced with the intention of +running legacy 32-bit binaries. Unsurprisingly, that doesn't work very +well with the default behaviour of Linux. + +It seems inevitable that future SoCs will drop 32-bit support +altogether, so if you're stuck in the unenviable position of needing to +run 32-bit code on one of these transitionary platforms then you would +be wise to consider alternatives such as recompilation, emulation or +retirement. If neither of those options are practical, then read on. + +Enabling kernel support +======================= + +Since the kernel support is not completely transparent to userspace, +allowing 32-bit tasks to run on an asymmetric 32-bit system requires an +explicit "opt-in" and can be enabled by passing the +``allow_mismatched_32bit_el0`` parameter on the kernel command-line. + +For the remainder of this document we will refer to an *asymmetric +system* to mean an asymmetric 32-bit SoC running Linux with this kernel +command-line option enabled. + +Userspace impact +================ + +32-bit tasks running on an asymmetric system behave in mostly the same +way as on a homogeneous system, with a few key differences relating to +CPU affinity. + +sysfs +----- + +The subset of CPUs capable of running 32-bit tasks is described in +``/sys/devices/system/cpu/aarch32_el0`` and is documented further in +``Documentation/ABI/testing/sysfs-devices-system-cpu``. + +**Note:** CPUs are advertised by this file as they are detected and so +late-onlining of 32-bit-capable CPUs can result in the file contents +being modified by the kernel at runtime. Once advertised, CPUs are never +removed from the file. + +``execve(2)`` +------------- + +On a homogeneous system, the CPU affinity of a task is preserved across +``execve(2)``. This is not always possible on an asymmetric system, +specifically when the new program being executed is 32-bit yet the +affinity mask contains 64-bit-only CPUs. In this situation, the kernel +determines the new affinity mask as follows: + + 1. If the 32-bit-capable subset of the affinity mask is not empty, + then the affinity is restricted to that subset and the old affinity + mask is saved. This saved mask is inherited over ``fork(2)`` and + preserved across ``execve(2)`` of 32-bit programs. + + **Note:** This step does not apply to ``SCHED_DEADLINE`` tasks. + See `SCHED_DEADLINE`_. + + 2. Otherwise, the cpuset hierarchy of the task is walked until an + ancestor is found containing at least one 32-bit-capable CPU. The + affinity of the task is then changed to match the 32-bit-capable + subset of the cpuset determined by the walk. + + 3. On failure (i.e. out of memory), the affinity is changed to the set + of all 32-bit-capable CPUs of which the kernel is aware. + +A subsequent ``execve(2)`` of a 64-bit program by the 32-bit task will +invalidate the affinity mask saved in (1) and attempt to restore the CPU +affinity of the task using the saved mask if it was previously valid. +This restoration may fail due to intervening changes to the deadline +policy or cpuset hierarchy, in which case the ``execve(2)`` continues +with the affinity unchanged. + +Calls to ``sched_setaffinity(2)`` for a 32-bit task will consider only +the 32-bit-capable CPUs of the requested affinity mask. On success, the +affinity for the task is updated and any saved mask from a prior +``execve(2)`` is invalidated. + +``SCHED_DEADLINE`` +------------------ + +Explicit admission of a 32-bit deadline task to the default root domain +(e.g. by calling ``sched_setattr(2)``) is rejected on an asymmetric +32-bit system unless admission control is disabled by writing -1 to +``/proc/sys/kernel/sched_rt_runtime_us``. + +``execve(2)`` of a 32-bit program from a 64-bit deadline task will +return ``-ENOEXEC`` if the root domain for the task contains any +64-bit-only CPUs and admission control is enabled. Concurrent offlining +of 32-bit-capable CPUs may still necessitate the procedure described in +`execve(2)`_, in which case step (1) is skipped and a warning is +emitted on the console. + +**Note:** It is recommended that a set of 32-bit-capable CPUs are placed +into a separate root domain if ``SCHED_DEADLINE`` is to be used with +32-bit tasks on an asymmetric system. Failure to do so is likely to +result in missed deadlines. + +Cpusets +------- + +The affinity of a 32-bit task on an asymmetric system may include CPUs +that are not explicitly allowed by the cpuset to which it is attached. +This can occur as a result of the following two situations: + + - A 64-bit task attached to a cpuset which allows only 64-bit CPUs + executes a 32-bit program. + + - All of the 32-bit-capable CPUs allowed by a cpuset containing a + 32-bit task are offlined. + +In both of these cases, the new affinity is calculated according to step +(2) of the process described in `execve(2)`_ and the cpuset hierarchy is +unchanged irrespective of the cgroup version. + +CPU hotplug +----------- + +On an asymmetric system, the first detected 32-bit-capable CPU is +prevented from being offlined by userspace and any such attempt will +return ``-EPERM``. Note that suspend is still permitted even if the +primary CPU (i.e. CPU 0) is 64-bit-only. + +KVM +--- + +Although KVM will not advertise 32-bit EL0 support to any vCPUs on an +asymmetric system, a broken guest at EL1 could still attempt to execute +32-bit code at EL0. In this case, an exit from a vCPU thread in 32-bit +mode will return to host userspace with an ``exit_reason`` of +``KVM_EXIT_FAIL_ENTRY`` and will remain non-runnable until successfully +re-initialised by a subsequent ``KVM_ARM_VCPU_INIT`` operation. diff --git a/Documentation/arm64/booting.rst b/Documentation/arm64/booting.rst index a9192e7a231b..3f9d86557c5e 100644 --- a/Documentation/arm64/booting.rst +++ b/Documentation/arm64/booting.rst @@ -207,10 +207,17 @@ Before jumping into the kernel, the following conditions must be met: software at a higher exception level to prevent execution in an UNKNOWN state. - - SCR_EL3.FIQ must have the same value across all CPUs the kernel is - executing on. - - The value of SCR_EL3.FIQ must be the same as the one present at boot - time whenever the kernel is executing. + For all systems: + - If EL3 is present: + + - SCR_EL3.FIQ must have the same value across all CPUs the kernel is + executing on. + - The value of SCR_EL3.FIQ must be the same as the one present at boot + time whenever the kernel is executing. + + - If EL3 is present and the kernel is entered at EL2: + + - SCR_EL3.HCE (bit 8) must be initialised to 0b1. For systems with a GICv3 interrupt controller to be used in v3 mode: - If EL3 is present: @@ -311,6 +318,28 @@ Before jumping into the kernel, the following conditions must be met: - ZCR_EL2.LEN must be initialised to the same value for all CPUs the kernel will execute on. + For CPUs with the Scalable Matrix Extension (FEAT_SME): + + - If EL3 is present: + + - CPTR_EL3.ESM (bit 12) must be initialised to 0b1. + + - SCR_EL3.EnTP2 (bit 41) must be initialised to 0b1. + + - SMCR_EL3.LEN must be initialised to the same value for all CPUs the + kernel will execute on. + + - If the kernel is entered at EL1 and EL2 is present: + + - CPTR_EL2.TSM (bit 12) must be initialised to 0b0. + + - CPTR_EL2.SMEN (bits 25:24) must be initialised to 0b11. + + - SCTLR_EL2.EnTP2 (bit 60) must be initialised to 0b1. + + - SMCR_EL2.LEN must be initialised to the same value for all CPUs the + kernel will execute on. + The requirements described above for CPU mode, caches, MMUs, architected timers, coherency and system registers apply to all CPUs. All CPUs must enter the kernel in the same exception level. Where the values documented diff --git a/Documentation/arm64/index.rst b/Documentation/arm64/index.rst index 97d65ba12a35..4f840bac083e 100644 --- a/Documentation/arm64/index.rst +++ b/Documentation/arm64/index.rst @@ -10,6 +10,7 @@ ARM64 Architecture acpi_object_usage amu arm-acpi + asymmetric-32bit booting cpu-feature-registers elf_hwcaps diff --git a/Documentation/arm64/memory-tagging-extension.rst b/Documentation/arm64/memory-tagging-extension.rst index b540178a93f8..7b99c8f428eb 100644 --- a/Documentation/arm64/memory-tagging-extension.rst +++ b/Documentation/arm64/memory-tagging-extension.rst @@ -77,14 +77,20 @@ configurable behaviours: address is unknown). The user can select the above modes, per thread, using the -``prctl(PR_SET_TAGGED_ADDR_CTRL, flags, 0, 0, 0)`` system call where -``flags`` contain one of the following values in the ``PR_MTE_TCF_MASK`` +``prctl(PR_SET_TAGGED_ADDR_CTRL, flags, 0, 0, 0)`` system call where ``flags`` +contains any number of the following values in the ``PR_MTE_TCF_MASK`` bit-field: -- ``PR_MTE_TCF_NONE`` - *Ignore* tag check faults +- ``PR_MTE_TCF_NONE`` - *Ignore* tag check faults + (ignored if combined with other options) - ``PR_MTE_TCF_SYNC`` - *Synchronous* tag check fault mode - ``PR_MTE_TCF_ASYNC`` - *Asynchronous* tag check fault mode +If no modes are specified, tag check faults are ignored. If a single +mode is specified, the program will run in that mode. If multiple +modes are specified, the mode is selected as described in the "Per-CPU +preferred tag checking modes" section below. + The current tag check fault mode can be read using the ``prctl(PR_GET_TAGGED_ADDR_CTRL, 0, 0, 0, 0)`` system call. @@ -120,13 +126,39 @@ in the ``PR_MTE_TAG_MASK`` bit-field. interface provides an include mask. An include mask of ``0`` (exclusion mask ``0xffff``) results in the CPU always generating tag ``0``. +Per-CPU preferred tag checking mode +----------------------------------- + +On some CPUs the performance of MTE in stricter tag checking modes +is similar to that of less strict tag checking modes. This makes it +worthwhile to enable stricter checks on those CPUs when a less strict +checking mode is requested, in order to gain the error detection +benefits of the stricter checks without the performance downsides. To +support this scenario, a privileged user may configure a stricter +tag checking mode as the CPU's preferred tag checking mode. + +The preferred tag checking mode for each CPU is controlled by +``/sys/devices/system/cpu/cpu<N>/mte_tcf_preferred``, to which a +privileged user may write the value ``async`` or ``sync``. The default +preferred mode for each CPU is ``async``. + +To allow a program to potentially run in the CPU's preferred tag +checking mode, the user program may set multiple tag check fault mode +bits in the ``flags`` argument to the ``prctl(PR_SET_TAGGED_ADDR_CTRL, +flags, 0, 0, 0)`` system call. If the CPU's preferred tag checking +mode is in the task's set of provided tag checking modes (this will +always be the case at present because the kernel only supports two +tag checking modes, but future kernels may support more modes), that +mode will be selected. Otherwise, one of the modes in the task's mode +set will be selected in a currently unspecified manner. + Initial process state --------------------- On ``execve()``, the new process has the following configuration: - ``PR_TAGGED_ADDR_ENABLE`` set to 0 (disabled) -- Tag checking mode set to ``PR_MTE_TCF_NONE`` +- No tag checking modes are selected (tag check faults ignored) - ``PR_MTE_TAG_MASK`` set to 0 (all tags excluded) - ``PSTATE.TCO`` set to 0 - ``PROT_MTE`` not set on any of the initial memory maps @@ -251,11 +283,13 @@ Example of correct usage return EXIT_FAILURE; /* - * Enable the tagged address ABI, synchronous MTE tag check faults and - * allow all non-zero tags in the randomly generated set. + * Enable the tagged address ABI, synchronous or asynchronous MTE + * tag check faults (based on per-CPU preference) and allow all + * non-zero tags in the randomly generated set. */ if (prctl(PR_SET_TAGGED_ADDR_CTRL, - PR_TAGGED_ADDR_ENABLE | PR_MTE_TCF_SYNC | (0xfffe << PR_MTE_TAG_SHIFT), + PR_TAGGED_ADDR_ENABLE | PR_MTE_TCF_SYNC | PR_MTE_TCF_ASYNC | + (0xfffe << PR_MTE_TAG_SHIFT), 0, 0, 0)) { perror("prctl() failed"); return EXIT_FAILURE; diff --git a/Documentation/arm64/tagged-address-abi.rst b/Documentation/arm64/tagged-address-abi.rst index 459e6b66ff68..0c9120ec58ae 100644 --- a/Documentation/arm64/tagged-address-abi.rst +++ b/Documentation/arm64/tagged-address-abi.rst @@ -45,14 +45,24 @@ 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. ``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. + tagged pointers in this context is allowed with these exceptions: + + - ``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. + + - The ``range.start``, ``start`` and ``dst`` arguments to the + ``UFFDIO_*`` ``ioctl()``s used on a file descriptor obtained from + ``userfaultfd()``, as fault addresses subsequently obtained by reading + the file descriptor will be untagged, which may otherwise confuse + tag-unaware programs. + + NOTE: This behaviour changed in v5.14 and so some earlier kernels may + incorrectly accept valid tagged pointers for this system call. 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/atomic_t.txt b/Documentation/atomic_t.txt index 0f1fdedf36bb..0f1ffa03db09 100644 --- a/Documentation/atomic_t.txt +++ b/Documentation/atomic_t.txt @@ -271,3 +271,97 @@ WRITE_ONCE. Thus: SC *y, t; is allowed. + + +CMPXCHG vs TRY_CMPXCHG +---------------------- + + int atomic_cmpxchg(atomic_t *ptr, int old, int new); + bool atomic_try_cmpxchg(atomic_t *ptr, int *oldp, int new); + +Both provide the same functionality, but try_cmpxchg() can lead to more +compact code. The functions relate like: + + bool atomic_try_cmpxchg(atomic_t *ptr, int *oldp, int new) + { + int ret, old = *oldp; + ret = atomic_cmpxchg(ptr, old, new); + if (ret != old) + *oldp = ret; + return ret == old; + } + +and: + + int atomic_cmpxchg(atomic_t *ptr, int old, int new) + { + (void)atomic_try_cmpxchg(ptr, &old, new); + return old; + } + +Usage: + + old = atomic_read(&v); old = atomic_read(&v); + for (;;) { do { + new = func(old); new = func(old); + tmp = atomic_cmpxchg(&v, old, new); } while (!atomic_try_cmpxchg(&v, &old, new)); + if (tmp == old) + break; + old = tmp; + } + +NB. try_cmpxchg() also generates better code on some platforms (notably x86) +where the function more closely matches the hardware instruction. + + +FORWARD PROGRESS +---------------- + +In general strong forward progress is expected of all unconditional atomic +operations -- those in the Arithmetic and Bitwise classes and xchg(). However +a fair amount of code also requires forward progress from the conditional +atomic operations. + +Specifically 'simple' cmpxchg() loops are expected to not starve one another +indefinitely. However, this is not evident on LL/SC architectures, because +while an LL/SC architecure 'can/should/must' provide forward progress +guarantees between competing LL/SC sections, such a guarantee does not +transfer to cmpxchg() implemented using LL/SC. Consider: + + old = atomic_read(&v); + do { + new = func(old); + } while (!atomic_try_cmpxchg(&v, &old, new)); + +which on LL/SC becomes something like: + + old = atomic_read(&v); + do { + new = func(old); + } while (!({ + volatile asm ("1: LL %[oldval], %[v]\n" + " CMP %[oldval], %[old]\n" + " BNE 2f\n" + " SC %[new], %[v]\n" + " BNE 1b\n" + "2:\n" + : [oldval] "=&r" (oldval), [v] "m" (v) + : [old] "r" (old), [new] "r" (new) + : "memory"); + success = (oldval == old); + if (!success) + old = oldval; + success; })); + +However, even the forward branch from the failed compare can cause the LL/SC +to fail on some architectures, let alone whatever the compiler makes of the C +loop body. As a result there is no guarantee what so ever the cacheline +containing @v will stay on the local CPU and progress is made. + +Even native CAS architectures can fail to provide forward progress for their +primitive (See Sparc64 for an example). + +Such implementations are strongly encouraged to add exponential backoff loops +to a failed CAS in order to ensure some progress. Affected architectures are +also strongly encouraged to inspect/audit the atomic fallbacks, refcount_t and +their locking primitives. diff --git a/Documentation/bpf/index.rst b/Documentation/bpf/index.rst index baea6c2abba5..1ceb5d704a97 100644 --- a/Documentation/bpf/index.rst +++ b/Documentation/bpf/index.rst @@ -15,15 +15,7 @@ that goes into great technical depth about the BPF Architecture. libbpf ====== -Libbpf is a userspace library for loading and interacting with bpf programs. - -.. toctree:: - :maxdepth: 1 - - libbpf/libbpf - libbpf/libbpf_api - libbpf/libbpf_build - libbpf/libbpf_naming_convention +Documentation/bpf/libbpf/libbpf.rst is a userspace library for loading and interacting with bpf programs. BPF Type Format (BTF) ===================== diff --git a/Documentation/bpf/libbpf/libbpf.rst b/Documentation/bpf/libbpf/index.rst index 1b1e61d5ead1..4f8adfc3ab83 100644 --- a/Documentation/bpf/libbpf/libbpf.rst +++ b/Documentation/bpf/libbpf/index.rst @@ -3,6 +3,14 @@ libbpf ====== +For API documentation see the `versioned API documentation site <https://libbpf.readthedocs.io/en/latest/api.html>`_. + +.. toctree:: + :maxdepth: 1 + + libbpf_naming_convention + libbpf_build + This is documentation for libbpf, a userspace library for loading and interacting with bpf programs. diff --git a/Documentation/bpf/libbpf/libbpf_api.rst b/Documentation/bpf/libbpf/libbpf_api.rst deleted file mode 100644 index f07eecd054da..000000000000 --- a/Documentation/bpf/libbpf/libbpf_api.rst +++ /dev/null @@ -1,27 +0,0 @@ -.. SPDX-License-Identifier: (LGPL-2.1 OR BSD-2-Clause) - -API -=== - -This documentation is autogenerated from header files in libbpf, tools/lib/bpf - -.. kernel-doc:: tools/lib/bpf/libbpf.h - :internal: - -.. kernel-doc:: tools/lib/bpf/bpf.h - :internal: - -.. kernel-doc:: tools/lib/bpf/btf.h - :internal: - -.. kernel-doc:: tools/lib/bpf/xsk.h - :internal: - -.. kernel-doc:: tools/lib/bpf/bpf_tracing.h - :internal: - -.. kernel-doc:: tools/lib/bpf/bpf_core_read.h - :internal: - -.. kernel-doc:: tools/lib/bpf/bpf_endian.h - :internal:
\ No newline at end of file diff --git a/Documentation/bpf/libbpf/libbpf_naming_convention.rst b/Documentation/bpf/libbpf/libbpf_naming_convention.rst index 3de1d51e41da..9c68d5014ff1 100644 --- a/Documentation/bpf/libbpf/libbpf_naming_convention.rst +++ b/Documentation/bpf/libbpf/libbpf_naming_convention.rst @@ -69,7 +69,7 @@ functions. These can be mixed and matched. Note that these functions are not reentrant for performance reasons. ABI -========== +--- libbpf can be both linked statically or used as DSO. To avoid possible conflicts with other libraries an application is linked with, all @@ -108,7 +108,7 @@ This bump in ABI version is at most once per kernel development cycle. For example, if current state of ``libbpf.map`` is: -.. code-block:: c +.. code-block:: none LIBBPF_0.0.1 { global: @@ -121,7 +121,7 @@ For example, if current state of ``libbpf.map`` is: , and a new symbol ``bpf_func_c`` is being introduced, then ``libbpf.map`` should be changed like this: -.. code-block:: c +.. code-block:: none LIBBPF_0.0.1 { global: diff --git a/Documentation/conf.py b/Documentation/conf.py index 7d92ec3e5b6e..75650f6443af 100644 --- a/Documentation/conf.py +++ b/Documentation/conf.py @@ -16,8 +16,6 @@ import sys import os import sphinx -from subprocess import check_output - # Get Sphinx version major, minor, patch = sphinx.version_info[:3] @@ -343,6 +341,9 @@ latex_elements = { verbatimhintsturnover=false, ''', + # For CJK One-half spacing, need to be in front of hyperref + 'extrapackages': r'\usepackage{setspace}', + # Additional stuff for the LaTeX preamble. 'preamble': ''' % Prevent column squeezing of tabulary. @@ -355,29 +356,117 @@ latex_elements = { ''', } -# At least one book (translations) may have Asian characters -# with are only displayed if xeCJK is used +# Translations have Asian (CJK) characters which are only displayed if +# xeCJK is used -cjk_cmd = check_output(['fc-list', '--format="%{family[0]}\n"']).decode('utf-8', 'ignore') -if cjk_cmd.find("Noto Sans CJK SC") >= 0: - latex_elements['preamble'] += ''' +latex_elements['preamble'] += ''' + \\IfFontExistsTF{Noto Sans CJK SC}{ % This is needed for translations - \\usepackage{xeCJK} - \\setCJKmainfont{Noto Sans CJK SC} + \\usepackage{xeCJK} + \\IfFontExistsTF{Noto Serif CJK SC}{ + \\setCJKmainfont{Noto Serif CJK SC}[AutoFakeSlant] + }{ + \\setCJKmainfont{Noto Sans CJK SC}[AutoFakeSlant] + } + \\setCJKsansfont{Noto Sans CJK SC}[AutoFakeSlant] + \\setCJKmonofont{Noto Sans Mono CJK SC}[AutoFakeSlant] + % CJK Language-specific font choices + \\IfFontExistsTF{Noto Serif CJK SC}{ + \\newCJKfontfamily[SCmain]\\scmain{Noto Serif CJK SC}[AutoFakeSlant] + \\newCJKfontfamily[SCserif]\\scserif{Noto Serif CJK SC}[AutoFakeSlant] + }{ + \\newCJKfontfamily[SCmain]\\scmain{Noto Sans CJK SC}[AutoFakeSlant] + \\newCJKfontfamily[SCserif]\\scserif{Noto Sans CJK SC}[AutoFakeSlant] + } + \\newCJKfontfamily[SCsans]\\scsans{Noto Sans CJK SC}[AutoFakeSlant] + \\newCJKfontfamily[SCmono]\\scmono{Noto Sans Mono CJK SC}[AutoFakeSlant] + \\IfFontExistsTF{Noto Serif CJK TC}{ + \\newCJKfontfamily[TCmain]\\tcmain{Noto Serif CJK TC}[AutoFakeSlant] + \\newCJKfontfamily[TCserif]\\tcserif{Noto Serif CJK TC}[AutoFakeSlant] + }{ + \\newCJKfontfamily[TCmain]\\tcmain{Noto Sans CJK TC}[AutoFakeSlant] + \\newCJKfontfamily[TCserif]\\tcserif{Noto Sans CJK TC}[AutoFakeSlant] + } + \\newCJKfontfamily[TCsans]\\tcsans{Noto Sans CJK TC}[AutoFakeSlant] + \\newCJKfontfamily[TCmono]\\tcmono{Noto Sans Mono CJK TC}[AutoFakeSlant] + \\IfFontExistsTF{Noto Serif CJK KR}{ + \\newCJKfontfamily[KRmain]\\krmain{Noto Serif CJK KR}[AutoFakeSlant] + \\newCJKfontfamily[KRserif]\\krserif{Noto Serif CJK KR}[AutoFakeSlant] + }{ + \\newCJKfontfamily[KRmain]\\krmain{Noto Sans CJK KR}[AutoFakeSlant] + \\newCJKfontfamily[KRserif]\\krserif{Noto Sans CJK KR}[AutoFakeSlant] + } + \\newCJKfontfamily[KRsans]\\krsans{Noto Sans CJK KR}[AutoFakeSlant] + \\newCJKfontfamily[KRmono]\\krmono{Noto Sans Mono CJK KR}[AutoFakeSlant] + \\IfFontExistsTF{Noto Serif CJK JP}{ + \\newCJKfontfamily[JPmain]\\jpmain{Noto Serif CJK JP}[AutoFakeSlant] + \\newCJKfontfamily[JPserif]\\jpserif{Noto Serif CJK JP}[AutoFakeSlant] + }{ + \\newCJKfontfamily[JPmain]\\jpmain{Noto Sans CJK JP}[AutoFakeSlant] + \\newCJKfontfamily[JPserif]\\jpserif{Noto Sans CJK JP}[AutoFakeSlant] + } + \\newCJKfontfamily[JPsans]\\jpsans{Noto Sans CJK JP}[AutoFakeSlant] + \\newCJKfontfamily[JPmono]\\jpmono{Noto Sans Mono CJK JP}[AutoFakeSlant] + % Dummy commands for Sphinx < 2.3 (no 'extrapackages' support) + \\providecommand{\\onehalfspacing}{} + \\providecommand{\\singlespacing}{} % Define custom macros to on/off CJK - \\newcommand{\\kerneldocCJKon}{\\makexeCJKactive} - \\newcommand{\\kerneldocCJKoff}{\\makexeCJKinactive} - % To customize \sphinxtableofcontents + \\newcommand{\\kerneldocCJKon}{\\makexeCJKactive\\onehalfspacing} + \\newcommand{\\kerneldocCJKoff}{\\makexeCJKinactive\\singlespacing} + \\newcommand{\\kerneldocBeginSC}{% + \\begingroup% + \\scmain% + } + \\newcommand{\\kerneldocEndSC}{\\endgroup} + \\newcommand{\\kerneldocBeginTC}{% + \\begingroup% + \\tcmain% + \\renewcommand{\\CJKrmdefault}{TCserif}% + \\renewcommand{\\CJKsfdefault}{TCsans}% + \\renewcommand{\\CJKttdefault}{TCmono}% + } + \\newcommand{\\kerneldocEndTC}{\\endgroup} + \\newcommand{\\kerneldocBeginKR}{% + \\begingroup% + \\xeCJKDeclareCharClass{HalfLeft}{`“,`‘}% + \\xeCJKDeclareCharClass{HalfRight}{`”,`’}% + \\krmain% + \\renewcommand{\\CJKrmdefault}{KRserif}% + \\renewcommand{\\CJKsfdefault}{KRsans}% + \\renewcommand{\\CJKttdefault}{KRmono}% + \\xeCJKsetup{CJKspace = true} % For inter-phrase space + } + \\newcommand{\\kerneldocEndKR}{\\endgroup} + \\newcommand{\\kerneldocBeginJP}{% + \\begingroup% + \\xeCJKDeclareCharClass{HalfLeft}{`“,`‘}% + \\xeCJKDeclareCharClass{HalfRight}{`”,`’}% + \\jpmain% + \\renewcommand{\\CJKrmdefault}{JPserif}% + \\renewcommand{\\CJKsfdefault}{JPsans}% + \\renewcommand{\\CJKttdefault}{JPmono}% + } + \\newcommand{\\kerneldocEndJP}{\\endgroup} + % Single spacing in literal blocks + \\fvset{baselinestretch=1} + % To customize \\sphinxtableofcontents \\usepackage{etoolbox} % Inactivate CJK after tableofcontents \\apptocmd{\\sphinxtableofcontents}{\\kerneldocCJKoff}{}{} - ''' -else: - latex_elements['preamble'] += ''' + }{ % No CJK font found % Custom macros to on/off CJK (Dummy) \\newcommand{\\kerneldocCJKon}{} \\newcommand{\\kerneldocCJKoff}{} - ''' + \\newcommand{\\kerneldocBeginSC}{} + \\newcommand{\\kerneldocEndSC}{} + \\newcommand{\\kerneldocBeginTC}{} + \\newcommand{\\kerneldocEndTC}{} + \\newcommand{\\kerneldocBeginKR}{} + \\newcommand{\\kerneldocEndKR}{} + \\newcommand{\\kerneldocBeginSC}{} + \\newcommand{\\kerneldocEndKR}{} + } +''' # Fix reference escape troubles with Sphinx 1.4.x if major == 1: diff --git a/Documentation/core-api/cachetlb.rst b/Documentation/core-api/cachetlb.rst index fe4290e26729..8aed9103e48a 100644 --- a/Documentation/core-api/cachetlb.rst +++ b/Documentation/core-api/cachetlb.rst @@ -271,10 +271,15 @@ maps this page at its virtual address. ``void flush_dcache_page(struct page *page)`` - Any time the kernel writes to a page cache page, _OR_ - the kernel is about to read from a page cache page and - user space shared/writable mappings of this page potentially - exist, this routine is called. + This routines must be called when: + + a) the kernel did write to a page that is in the page cache page + and / or in high memory + b) the kernel is about to read from a page cache page and user space + shared/writable mappings of this page potentially exist. Note + that {get,pin}_user_pages{_fast} already call flush_dcache_page + on any page found in the user address space and thus driver + code rarely needs to take this into account. .. note:: @@ -284,38 +289,34 @@ maps this page at its virtual address. handling vfs symlinks in the page cache need not call this interface at all. - The phrase "kernel writes to a page cache page" means, - specifically, that the kernel executes store instructions - that dirty data in that page at the page->virtual mapping - of that page. It is important to flush here to handle - D-cache aliasing, to make sure these kernel stores are - visible to user space mappings of that page. - - The corollary case is just as important, if there are users - which have shared+writable mappings of this file, we must make - sure that kernel reads of these pages will see the most recent - stores done by the user. - - If D-cache aliasing is not an issue, this routine may - simply be defined as a nop on that architecture. - - There is a bit set aside in page->flags (PG_arch_1) as - "architecture private". The kernel guarantees that, - for pagecache pages, it will clear this bit when such - a page first enters the pagecache. - - This allows these interfaces to be implemented much more - efficiently. It allows one to "defer" (perhaps indefinitely) - the actual flush if there are currently no user processes - mapping this page. See sparc64's flush_dcache_page and - update_mmu_cache implementations for an example of how to go - about doing this. - - The idea is, first at flush_dcache_page() time, if - page->mapping->i_mmap is an empty tree, just mark the architecture - private page flag bit. Later, in update_mmu_cache(), a check is - made of this flag bit, and if set the flush is done and the flag - bit is cleared. + The phrase "kernel writes to a page cache page" means, specifically, + that the kernel executes store instructions that dirty data in that + page at the page->virtual mapping of that page. It is important to + flush here to handle D-cache aliasing, to make sure these kernel stores + are visible to user space mappings of that page. + + The corollary case is just as important, if there are users which have + shared+writable mappings of this file, we must make sure that kernel + reads of these pages will see the most recent stores done by the user. + + If D-cache aliasing is not an issue, this routine may simply be defined + as a nop on that architecture. + + There is a bit set aside in page->flags (PG_arch_1) as "architecture + private". The kernel guarantees that, for pagecache pages, it will + clear this bit when such a page first enters the pagecache. + + This allows these interfaces to be implemented much more efficiently. + It allows one to "defer" (perhaps indefinitely) the actual flush if + there are currently no user processes mapping this page. See sparc64's + flush_dcache_page and update_mmu_cache implementations for an example + of how to go about doing this. + + The idea is, first at flush_dcache_page() time, if page_file_mapping() + returns a mapping, and mapping_mapped on that mapping returns %false, + just mark the architecture private page flag bit. Later, in + update_mmu_cache(), a check is made of this flag bit, and if set the + flush is done and the flag bit is cleared. .. important:: @@ -351,19 +352,6 @@ maps this page at its virtual address. architectures). For incoherent architectures, it should flush the cache of the page at vmaddr. - ``void flush_kernel_dcache_page(struct page *page)`` - - When the kernel needs to modify a user page is has obtained - with kmap, it calls this function after all modifications are - complete (but before kunmapping it) to bring the underlying - page up to date. It is assumed here that the user has no - incoherent cached copies (i.e. the original page was obtained - from a mechanism like get_user_pages()). The default - implementation is a nop and should remain so on all coherent - architectures. On incoherent architectures, this should flush - the kernel cache for page (using page_address(page)). - - ``void flush_icache_range(unsigned long start, unsigned long end)`` When the kernel stores into addresses that it will execute diff --git a/Documentation/core-api/cpu_hotplug.rst b/Documentation/core-api/cpu_hotplug.rst index a2c96bec5ee8..b66e3cae1472 100644 --- a/Documentation/core-api/cpu_hotplug.rst +++ b/Documentation/core-api/cpu_hotplug.rst @@ -91,9 +91,10 @@ Never use anything other than ``cpumask_t`` to represent bitmap of CPUs. Using CPU hotplug ================= + The kernel option *CONFIG_HOTPLUG_CPU* needs to be enabled. It is currently available on multiple architectures including ARM, MIPS, PowerPC and X86. The -configuration is done via the sysfs interface: :: +configuration is done via the sysfs interface:: $ ls -lh /sys/devices/system/cpu total 0 @@ -113,14 +114,14 @@ configuration is done via the sysfs interface: :: The files *offline*, *online*, *possible*, *present* represent the CPU masks. Each CPU folder contains an *online* file which controls the logical on (1) and -off (0) state. To logically shutdown CPU4: :: +off (0) state. To logically shutdown CPU4:: $ echo 0 > /sys/devices/system/cpu/cpu4/online smpboot: CPU 4 is now offline Once the CPU is shutdown, it will be removed from */proc/interrupts*, */proc/cpuinfo* and should also not be shown visible by the *top* command. To -bring CPU4 back online: :: +bring CPU4 back online:: $ echo 1 > /sys/devices/system/cpu/cpu4/online smpboot: Booting Node 0 Processor 4 APIC 0x1 @@ -142,6 +143,7 @@ The CPU hotplug coordination The offline case ---------------- + Once a CPU has been logically shutdown the teardown callbacks of registered hotplug states will be invoked, starting with ``CPUHP_ONLINE`` and terminating at state ``CPUHP_OFFLINE``. This includes: @@ -158,9 +160,10 @@ at state ``CPUHP_OFFLINE``. This includes: Using the hotplug API --------------------- + It is possible to receive notifications once a CPU is offline or onlined. This might be important to certain drivers which need to perform some kind of setup -or clean up functions based on the number of available CPUs: :: +or clean up functions based on the number of available CPUs:: #include <linux/cpuhotplug.h> @@ -186,9 +189,10 @@ During the removal of a hotplug state the teardown callback will be invoked. Multiple instances ~~~~~~~~~~~~~~~~~~ + If a driver has multiple instances and each instance needs to perform the callback independently then it is likely that a ''multi-state'' should be used. -First a multi-state state needs to be registered: :: +First a multi-state state needs to be registered:: ret = cpuhp_setup_state_multi(CPUHP_AP_ONLINE_DYN, "X/Y:online, Y_online, Y_prepare_down); @@ -197,7 +201,7 @@ First a multi-state state needs to be registered: :: The ``cpuhp_setup_state_multi()`` behaves similar to ``cpuhp_setup_state()`` except it prepares the callbacks for a multi state and does not invoke the callbacks. This is a one time setup. -Once a new instance is allocated, you need to register this new instance: :: +Once a new instance is allocated, you need to register this new instance:: ret = cpuhp_state_add_instance(Y_hp_online, &d->node); @@ -206,7 +210,8 @@ This function will add this instance to your previously allocated (*Y_online*) on all online CPUs. The *node* element is a ``struct hlist_node`` member of your per-instance data structure. -On removal of the instance: :: +On removal of the instance:: + cpuhp_state_remove_instance(Y_hp_online, &d->node) should be invoked which will invoke the teardown callback on all online @@ -214,18 +219,20 @@ CPUs. Manual setup ~~~~~~~~~~~~ + Usually it is handy to invoke setup and teardown callbacks on registration or removal of a state because usually the operation needs to performed once a CPU goes online (offline) and during initial setup (shutdown) of the driver. However each registration and removal function is also available with a ``_nocalls`` suffix which does not invoke the provided callbacks if the invocation of the callbacks is not desired. During the manual setup (or teardown) the functions -``get_online_cpus()`` and ``put_online_cpus()`` should be used to inhibit CPU +``cpus_read_lock()`` and ``cpus_read_unlock()`` should be used to inhibit CPU hotplug operations. The ordering of the events -------------------------- + The hotplug states are defined in ``include/linux/cpuhotplug.h``: * The states *CPUHP_OFFLINE* … *CPUHP_AP_OFFLINE* are invoked before the @@ -248,13 +255,14 @@ another hotplug event. Testing of hotplug states ========================= + One way to verify whether a custom state is working as expected or not is to shutdown a CPU and then put it online again. It is also possible to put the CPU to certain state (for instance *CPUHP_AP_ONLINE*) and then go back to *CPUHP_ONLINE*. This would simulate an error one state after *CPUHP_AP_ONLINE* which would lead to rollback to the online state. -All registered states are enumerated in ``/sys/devices/system/cpu/hotplug/states``: :: +All registered states are enumerated in ``/sys/devices/system/cpu/hotplug/states`` :: $ tail /sys/devices/system/cpu/hotplug/states 138: mm/vmscan:online @@ -268,7 +276,7 @@ All registered states are enumerated in ``/sys/devices/system/cpu/hotplug/states 168: sched:active 169: online -To rollback CPU4 to ``lib/percpu_cnt:online`` and back online just issue: :: +To rollback CPU4 to ``lib/percpu_cnt:online`` and back online just issue:: $ cat /sys/devices/system/cpu/cpu4/hotplug/state 169 @@ -276,14 +284,14 @@ To rollback CPU4 to ``lib/percpu_cnt:online`` and back online just issue: :: $ cat /sys/devices/system/cpu/cpu4/hotplug/state 140 -It is important to note that the teardown callbac of state 140 have been -invoked. And now get back online: :: +It is important to note that the teardown callback of state 140 have been +invoked. And now get back online:: $ echo 169 > /sys/devices/system/cpu/cpu4/hotplug/target $ cat /sys/devices/system/cpu/cpu4/hotplug/state 169 -With trace events enabled, the individual steps are visible, too: :: +With trace events enabled, the individual steps are visible, too:: # TASK-PID CPU# TIMESTAMP FUNCTION # | | | | | @@ -318,6 +326,7 @@ trace. Architecture's requirements =========================== + The following functions and configurations are required: ``CONFIG_HOTPLUG_CPU`` @@ -339,11 +348,12 @@ The following functions and configurations are required: User Space Notification ======================= -After CPU successfully onlined or offline udev events are sent. A udev rule like: :: + +After CPU successfully onlined or offline udev events are sent. A udev rule like:: SUBSYSTEM=="cpu", DRIVERS=="processor", DEVPATH=="/devices/system/cpu/*", RUN+="the_hotplug_receiver.sh" -will receive all events. A script like: :: +will receive all events. A script like:: #!/bin/sh diff --git a/Documentation/core-api/irq/irq-domain.rst b/Documentation/core-api/irq/irq-domain.rst index 53283b3729a1..6979b4af2c1f 100644 --- a/Documentation/core-api/irq/irq-domain.rst +++ b/Documentation/core-api/irq/irq-domain.rst @@ -55,8 +55,24 @@ exist then it will allocate a new Linux irq_desc, associate it with the hwirq, and call the .map() callback so the driver can perform any required hardware setup. -When an interrupt is received, irq_find_mapping() function should -be used to find the Linux IRQ number from the hwirq number. +Once a mapping has been established, it can be retrieved or used via a +variety of methods: + +- irq_resolve_mapping() returns a pointer to the irq_desc structure + for a given domain and hwirq number, and NULL if there was no + mapping. +- irq_find_mapping() returns a Linux IRQ number for a given domain and + hwirq number, and 0 if there was no mapping +- irq_linear_revmap() is now identical to irq_find_mapping(), and is + deprecated +- generic_handle_domain_irq() handles an interrupt described by a + domain and a hwirq number +- handle_domain_irq() does the same thing for root interrupt + controllers and deals with the set_irq_reg()/irq_enter() sequences + that most architecture requires + +Note that irq domain lookups must happen in contexts that are +compatible with a RCU read-side critical section. The irq_create_mapping() function must be called *atleast once* before any call to irq_find_mapping(), lest the descriptor will not @@ -137,7 +153,9 @@ required. Calling irq_create_direct_mapping() will allocate a Linux IRQ number and call the .map() callback so that driver can program the Linux IRQ number into the hardware. -Most drivers cannot use this mapping. +Most drivers cannot use this mapping, and it is now gated on the +CONFIG_IRQ_DOMAIN_NOMAP option. Please refrain from introducing new +users of this API. Legacy ------ @@ -157,6 +175,10 @@ for IRQ numbers that are passed to struct device registrations. In that case the Linux IRQ numbers cannot be dynamically assigned and the legacy mapping should be used. +As the name implies, the *_legacy() functions are deprecated and only +exist to ease the support of ancient platforms. No new users should be +added. + The legacy map assumes a contiguous range of IRQ numbers has already been allocated for the controller and that the IRQ number can be calculated by adding a fixed offset to the hwirq number, and diff --git a/Documentation/core-api/printk-basics.rst b/Documentation/core-api/printk-basics.rst index 965e4281eddd..2dde24ca7d9f 100644 --- a/Documentation/core-api/printk-basics.rst +++ b/Documentation/core-api/printk-basics.rst @@ -107,9 +107,6 @@ also ``CONFIG_DYNAMIC_DEBUG`` in the case of pr_debug()) is defined. Function reference ================== -.. kernel-doc:: kernel/printk/printk.c - :functions: printk - .. kernel-doc:: include/linux/printk.h - :functions: pr_emerg pr_alert pr_crit pr_err pr_warn pr_notice pr_info + :functions: printk pr_emerg pr_alert pr_crit pr_err pr_warn pr_notice pr_info pr_fmt pr_debug pr_devel pr_cont diff --git a/Documentation/core-api/printk-formats.rst b/Documentation/core-api/printk-formats.rst index d941717a191b..e08bbe9b0cbf 100644 --- a/Documentation/core-api/printk-formats.rst +++ b/Documentation/core-api/printk-formats.rst @@ -130,6 +130,7 @@ printed after the symbol name with an extra ``b`` appended to the end of the specifier. :: + %pS versatile_init+0x0/0x110 [module_name] %pSb versatile_init+0x0/0x110 [module_name ed5019fdf5e53be37cb1ba7899292d7e143b259e] %pSRb versatile_init+0x9/0x110 [module_name ed5019fdf5e53be37cb1ba7899292d7e143b259e] diff --git a/Documentation/dev-tools/kasan.rst b/Documentation/dev-tools/kasan.rst index 83ec4a556c19..21dc03bc10a4 100644 --- a/Documentation/dev-tools/kasan.rst +++ b/Documentation/dev-tools/kasan.rst @@ -181,9 +181,16 @@ By default, KASAN prints a bug report only for the first invalid memory access. With ``kasan_multi_shot``, KASAN prints a report on every invalid access. This effectively disables ``panic_on_warn`` for KASAN reports. +Alternatively, independent of ``panic_on_warn`` the ``kasan.fault=`` boot +parameter can be used to control panic and reporting behaviour: + +- ``kasan.fault=report`` or ``=panic`` controls whether to only print a KASAN + report or also panic the kernel (default: ``report``). The panic happens even + if ``kasan_multi_shot`` is enabled. + Hardware tag-based KASAN mode (see the section about various modes below) is intended for use in production as a security mitigation. Therefore, it supports -boot parameters that allow disabling KASAN or controlling its features. +additional boot parameters that allow disabling KASAN or controlling features: - ``kasan=off`` or ``=on`` controls whether KASAN is enabled (default: ``on``). @@ -199,10 +206,6 @@ boot parameters that allow disabling KASAN or controlling its features. - ``kasan.stacktrace=off`` or ``=on`` disables or enables alloc and free stack traces collection (default: ``on``). -- ``kasan.fault=report`` or ``=panic`` controls whether to only print a KASAN - report or also panic the kernel (default: ``report``). The panic happens even - if ``kasan_multi_shot`` is enabled. - Implementation details ---------------------- diff --git a/Documentation/dev-tools/kcsan.rst b/Documentation/dev-tools/kcsan.rst index 6a600cf8430b..7db43c7c09b8 100644 --- a/Documentation/dev-tools/kcsan.rst +++ b/Documentation/dev-tools/kcsan.rst @@ -127,6 +127,18 @@ Kconfig options: causes KCSAN to not report data races due to conflicts where the only plain accesses are aligned writes up to word size. +* ``CONFIG_KCSAN_PERMISSIVE``: Enable additional permissive rules to ignore + certain classes of common data races. Unlike the above, the rules are more + complex involving value-change patterns, access type, and address. This + option depends on ``CONFIG_KCSAN_REPORT_VALUE_CHANGE_ONLY=y``. For details + please see the ``kernel/kcsan/permissive.h``. Testers and maintainers that + only focus on reports from specific subsystems and not the whole kernel are + recommended to disable this option. + +To use the strictest possible rules, select ``CONFIG_KCSAN_STRICT=y``, which +configures KCSAN to follow the Linux-kernel memory consistency model (LKMM) as +closely as possible. + DebugFS interface ~~~~~~~~~~~~~~~~~ diff --git a/Documentation/dev-tools/kunit/kunit-tool.rst b/Documentation/dev-tools/kunit/kunit-tool.rst index c7ff9afe407a..ae52e0f489f9 100644 --- a/Documentation/dev-tools/kunit/kunit-tool.rst +++ b/Documentation/dev-tools/kunit/kunit-tool.rst @@ -114,9 +114,12 @@ results in TAP format, you can pass the ``--raw_output`` argument. ./tools/testing/kunit/kunit.py run --raw_output -.. note:: - The raw output from test runs may contain other, non-KUnit kernel log - lines. +The raw output from test runs may contain other, non-KUnit kernel log +lines. You can see just KUnit output with ``--raw_output=kunit``: + +.. code-block:: bash + + ./tools/testing/kunit/kunit.py run --raw_output=kunit If you have KUnit results in their raw TAP format, you can parse them and print the human-readable summary with the ``parse`` command for kunit_tool. This diff --git a/Documentation/dev-tools/kunit/running_tips.rst b/Documentation/dev-tools/kunit/running_tips.rst index d1626d548fa5..30d2147eb5b5 100644 --- a/Documentation/dev-tools/kunit/running_tips.rst +++ b/Documentation/dev-tools/kunit/running_tips.rst @@ -80,6 +80,16 @@ file ``.kunitconfig``, you can just pass in the dir, e.g. automagically, but tests could theoretically depend on incompatible options, so handling that would be tricky. +Setting kernel commandline parameters +------------------------------------- + +You can use ``--kernel_args`` to pass arbitrary kernel arguments, e.g. + +.. code-block:: bash + + $ ./tools/testing/kunit/kunit.py run --kernel_args=param=42 --kernel_args=param2=false + + Generating code coverage reports under UML ------------------------------------------ diff --git a/Documentation/devicetree/bindings/Makefile b/Documentation/devicetree/bindings/Makefile index 5ccfed90cc70..a072e95de626 100644 --- a/Documentation/devicetree/bindings/Makefile +++ b/Documentation/devicetree/bindings/Makefile @@ -28,7 +28,7 @@ find_cmd = find $(srctree)/$(src) \( -name '*.yaml' ! \ quiet_cmd_yamllint = LINT $(src) cmd_yamllint = ($(find_cmd) | \ - xargs $(DT_SCHEMA_LINT) -f parsable -c $(srctree)/$(src)/.yamllint) || true + xargs $(DT_SCHEMA_LINT) -f parsable -c $(srctree)/$(src)/.yamllint >&2) || true quiet_cmd_chk_bindings = CHKDT $@ cmd_chk_bindings = ($(find_cmd) | \ diff --git a/Documentation/devicetree/bindings/arm/atmel-at91.yaml b/Documentation/devicetree/bindings/arm/atmel-at91.yaml index 6fc5a22ad962..fba071b9af1d 100644 --- a/Documentation/devicetree/bindings/arm/atmel-at91.yaml +++ b/Documentation/devicetree/bindings/arm/atmel-at91.yaml @@ -146,6 +146,11 @@ properties: - const: atmel,sama5 - items: + - const: microchip,sama7g5ek # SAMA7G5 Evaluation Kit + - const: microchip,sama7g5 + - const: microchip,sama7 + + - items: - enum: - atmel,sams70j19 - atmel,sams70j20 diff --git a/Documentation/devicetree/bindings/arm/atmel-sysregs.txt b/Documentation/devicetree/bindings/arm/atmel-sysregs.txt index 807264a78edc..16eef600d599 100644 --- a/Documentation/devicetree/bindings/arm/atmel-sysregs.txt +++ b/Documentation/devicetree/bindings/arm/atmel-sysregs.txt @@ -45,7 +45,8 @@ RAMC SDRAM/DDR Controller required properties: "atmel,at91sam9260-sdramc", "atmel,at91sam9g45-ddramc", "atmel,sama5d3-ddramc", - "microchip,sam9x60-ddramc" + "microchip,sam9x60-ddramc", + "microchip,sama7g5-uddrc" - reg: Should contain registers location and length Examples: @@ -55,6 +56,17 @@ Examples: reg = <0xffffe800 0x200>; }; +RAMC PHY Controller required properties: +- compatible: Should be "microchip,sama7g5-ddr3phy", "syscon" +- reg: Should contain registers location and length + +Example: + + ddr3phy: ddr3phy@e3804000 { + compatible = "microchip,sama7g5-ddr3phy", "syscon"; + reg = <0xe3804000 0x1000>; +}; + SHDWC Shutdown Controller required properties: diff --git a/Documentation/devicetree/bindings/arm/fsl.yaml b/Documentation/devicetree/bindings/arm/fsl.yaml index 1c827c1954dc..60f4862ba15e 100644 --- a/Documentation/devicetree/bindings/arm/fsl.yaml +++ b/Documentation/devicetree/bindings/arm/fsl.yaml @@ -221,9 +221,13 @@ properties: - prt,prti6q # Protonic PRTI6Q board - prt,prtwd2 # Protonic WD2 board - rex,imx6q-rex-pro # Rex Pro i.MX6 Quad Board + - skov,imx6q-skov-revc-lt2 # SKOV IMX6 CPU QuadCore lt2 + - skov,imx6q-skov-revc-lt6 # SKOV IMX6 CPU QuadCore lt6 + - skov,imx6q-skov-reve-mi1010ait-1cp1 # SKOV IMX6 CPU QuadCore mi1010ait-1cp1 - solidrun,cubox-i/q # SolidRun Cubox-i Dual/Quad - solidrun,hummingboard/q - solidrun,hummingboard2/q + - solidrun,solidsense/q # SolidRun SolidSense Dual/Quad - tbs,imx6q-tbs2910 # TBS2910 Matrix ARM mini PC - technexion,imx6q-pico-dwarf # TechNexion i.MX6Q Pico-Dwarf - technexion,imx6q-pico-hobbit # TechNexion i.MX6Q Pico-Hobbit @@ -377,9 +381,12 @@ properties: - prt,prtvt7 # Protonic VT7 board - rex,imx6dl-rex-basic # Rex Basic i.MX6 Dual Lite Board - riot,imx6s-riotboard # RIoTboard i.MX6S + - skov,imx6dl-skov-revc-lt2 # SKOV IMX6 CPU SoloCore lt2 + - skov,imx6dl-skov-revc-lt6 # SKOV IMX6 CPU SoloCore lt6 - solidrun,cubox-i/dl # SolidRun Cubox-i Solo/DualLite - solidrun,hummingboard/dl - solidrun,hummingboard2/dl # SolidRun HummingBoard2 Solo/DualLite + - solidrun,solidsense/dl # SolidRun SolidSense Solo/DualLite - technexion,imx6dl-pico-dwarf # TechNexion i.MX6DL Pico-Dwarf - technexion,imx6dl-pico-hobbit # TechNexion i.MX6DL Pico-Hobbit - technexion,imx6dl-pico-nymph # TechNexion i.MX6DL Pico-Nymph @@ -418,6 +425,12 @@ properties: - const: dfi,fs700e-m60 - const: fsl,imx6dl + - description: i.MX6DL DHCOM PicoITX Board + items: + - const: dh,imx6dl-dhcom-picoitx + - const: dh,imx6dl-dhcom-som + - const: fsl,imx6dl + - description: i.MX6DL Gateworks Ventana Boards items: - enum: @@ -469,6 +482,12 @@ properties: - const: toradex,colibri_imx6dl # Colibri iMX6 Module - const: fsl,imx6dl + - description: i.MX6S DHCOM DRC02 Board + items: + - const: dh,imx6s-dhcom-drc02 + - const: dh,imx6s-dhcom-som + - const: fsl,imx6dl + - description: i.MX6SL based Boards items: - enum: @@ -698,6 +717,7 @@ properties: - gw,imx8mm-gw72xx-0x # i.MX8MM Gateworks Development Kit - gw,imx8mm-gw73xx-0x # i.MX8MM Gateworks Development Kit - gw,imx8mm-gw7901 # i.MX8MM Gateworks Board + - gw,imx8mm-gw7902 # i.MX8MM Gateworks Board - kontron,imx8mm-n801x-som # i.MX8MM Kontron SL (N801X) SOM - variscite,var-som-mx8mm # i.MX8MM Variscite VAR-SOM-MX8MM module - const: fsl,imx8mm @@ -728,6 +748,7 @@ properties: - beacon,imx8mn-beacon-kit # i.MX8MN Beacon Development Kit - fsl,imx8mn-ddr4-evk # i.MX8MN DDR4 EVK Board - fsl,imx8mn-evk # i.MX8MN LPDDR4 EVK Board + - gw,imx8mn-gw7902 # i.MX8MM Gateworks Board - const: fsl,imx8mn - description: Variscite VAR-SOM-MX8MN based boards @@ -752,10 +773,12 @@ properties: items: - enum: - boundary,imx8mq-nitrogen8m # i.MX8MQ NITROGEN Board + - boundary,imx8mq-nitrogen8m-som # i.MX8MQ NITROGEN SoM - einfochips,imx8mq-thor96 # i.MX8MQ Thor96 Board - fsl,imx8mq-evk # i.MX8MQ EVK Board - google,imx8mq-phanbell # Google Coral Edge TPU - kontron,pitx-imx8m # Kontron pITX-imx8m Board + - mntre,reform2 # MNT Reform2 Laptop - purism,librem5-devkit # Purism Librem5 devkit - solidrun,hummingboard-pulse # SolidRun Hummingboard Pulse - technexion,pico-pi-imx8m # TechNexion PICO-PI-8M evk @@ -973,6 +996,12 @@ properties: - fsl,s32v234-evb # S32V234-EVB2 Customer Evaluation Board - const: fsl,s32v234 + - description: Traverse LS1088A based Boards + items: + - enum: + - traverse,ten64 # Ten64 Networking Appliance / Board + - const: fsl,ls1088a + additionalProperties: true ... diff --git a/Documentation/devicetree/bindings/arm/gemini.txt b/Documentation/devicetree/bindings/arm/gemini.txt deleted file mode 100644 index 55bf7ce96c44..000000000000 --- a/Documentation/devicetree/bindings/arm/gemini.txt +++ /dev/null @@ -1,108 +0,0 @@ -Cortina systems Gemini platforms - -The Gemini SoC is the project name for an ARMv4 FA525-based SoC originally -produced by Storlink Semiconductor around 2005. The company was renamed -later renamed Storm Semiconductor. The chip product name is Storlink SL3516. -It was derived from earlier products from Storm named SL3316 (Centroid) and -SL3512 (Bulverde). - -Storm Semiconductor was acquired by Cortina Systems in 2008 and the SoC was -produced and used for NAS and similar usecases. In 2014 Cortina Systems was -in turn acquired by Inphi, who seem to have discontinued this product family. - -Many of the IP blocks used in the SoC comes from Faraday Technology. - -Required properties (in root node): - compatible = "cortina,gemini"; - -Required nodes: - -- soc: the SoC should be represented by a simple bus encompassing all the - onchip devices, this is referred to as the soc bus node. - -- syscon: the soc bus node must have a system controller node pointing to the - global control registers, with the compatible string - "cortina,gemini-syscon", "syscon"; - - Required properties on the syscon: - - reg: syscon register location and size. - - #clock-cells: should be set to <1> - the system controller is also a - clock provider. - - #reset-cells: should be set to <1> - the system controller is also a - reset line provider. - - The clock sources have shorthand defines in the include file: - <dt-bindings/clock/cortina,gemini-clock.h> - - The reset lines have shorthand defines in the include file: - <dt-bindings/reset/cortina,gemini-reset.h> - -- timer: the soc bus node must have a timer node pointing to the SoC timer - block, with the compatible string "cortina,gemini-timer" - See: clocksource/cortina,gemini-timer.txt - -- interrupt-controller: the sob bus node must have an interrupt controller - node pointing to the SoC interrupt controller block, with the compatible - string "cortina,gemini-interrupt-controller" - See interrupt-controller/cortina,gemini-interrupt-controller.txt - -Example: - -/ { - model = "Foo Gemini Machine"; - compatible = "cortina,gemini"; - #address-cells = <1>; - #size-cells = <1>; - - memory { - device_type = "memory"; - reg = <0x00000000 0x8000000>; - }; - - soc { - #address-cells = <1>; - #size-cells = <1>; - ranges; - compatible = "simple-bus"; - interrupt-parent = <&intcon>; - - syscon: syscon@40000000 { - compatible = "cortina,gemini-syscon", "syscon"; - reg = <0x40000000 0x1000>; - #clock-cells = <1>; - #reset-cells = <1>; - }; - - uart0: serial@42000000 { - compatible = "ns16550a"; - reg = <0x42000000 0x100>; - resets = <&syscon GEMINI_RESET_UART>; - clocks = <&syscon GEMINI_CLK_UART>; - interrupts = <18 IRQ_TYPE_LEVEL_HIGH>; - reg-shift = <2>; - }; - - timer@43000000 { - compatible = "cortina,gemini-timer"; - reg = <0x43000000 0x1000>; - interrupt-parent = <&intcon>; - interrupts = <14 IRQ_TYPE_EDGE_FALLING>, /* Timer 1 */ - <15 IRQ_TYPE_EDGE_FALLING>, /* Timer 2 */ - <16 IRQ_TYPE_EDGE_FALLING>; /* Timer 3 */ - resets = <&syscon GEMINI_RESET_TIMER>; - /* APB clock or RTC clock */ - clocks = <&syscon GEMINI_CLK_APB>, - <&syscon GEMINI_CLK_RTC>; - clock-names = "PCLK", "EXTCLK"; - syscon = <&syscon>; - }; - - intcon: interrupt-controller@48000000 { - compatible = "cortina,gemini-interrupt-controller"; - reg = <0x48000000 0x1000>; - resets = <&syscon GEMINI_RESET_INTCON0>; - interrupt-controller; - #interrupt-cells = <2>; - }; - }; -}; diff --git a/Documentation/devicetree/bindings/arm/gemini.yaml b/Documentation/devicetree/bindings/arm/gemini.yaml new file mode 100644 index 000000000000..f6a0b675830f --- /dev/null +++ b/Documentation/devicetree/bindings/arm/gemini.yaml @@ -0,0 +1,95 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/arm/gemini.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Cortina systems Gemini platforms + +description: | + The Gemini SoC is the project name for an ARMv4 FA525-based SoC originally + produced by Storlink Semiconductor around 2005. The company was renamed + later renamed Storm Semiconductor. The chip product name is Storlink SL3516. + It was derived from earlier products from Storm named SL3316 (Centroid) and + SL3512 (Bulverde). + + Storm Semiconductor was acquired by Cortina Systems in 2008 and the SoC was + produced and used for NAS and similar usecases. In 2014 Cortina Systems was + in turn acquired by Inphi, who seem to have discontinued this product family. + + Many of the IP blocks used in the SoC comes from Faraday Technology. + +maintainers: + - Linus Walleij <linus.walleij@linaro.org> + +properties: + $nodename: + const: '/' + compatible: + oneOf: + + - description: Storlink Semiconductor Gemini324 EV-Board also known + as Storm Semiconductor SL93512R_BRD + items: + - const: storlink,gemini324 + - const: storm,sl93512r + - const: cortina,gemini + + - description: D-Link DIR-685 Xtreme N Storage Router + items: + - const: dlink,dir-685 + - const: cortina,gemini + + - description: D-Link DNS-313 1-Bay Network Storage Enclosure + items: + - const: dlink,dns-313 + - const: cortina,gemini + + - description: Edimax NS-2502 + items: + - const: edimax,ns-2502 + - const: cortina,gemini + + - description: ITian Square One SQ201 + items: + - const: itian,sq201 + - const: cortina,gemini + + - description: Raidsonic NAS IB-4220-B + items: + - const: raidsonic,ib-4220-b + - const: cortina,gemini + + - description: SSI 1328 + items: + - const: ssi,1328 + - const: cortina,gemini + + - description: Teltonika RUT1xx Mobile Router + items: + - const: teltonika,rut1xx + - const: cortina,gemini + + - description: Wiligear Wiliboard WBD-111 + items: + - const: wiligear,wiliboard-wbd111 + - const: cortina,gemini + + - description: Wiligear Wiliboard WBD-222 + items: + - const: wiligear,wiliboard-wbd222 + - const: cortina,gemini + + - description: Wiligear Wiliboard WBD-111 - old incorrect binding + items: + - const: wiliboard,wbd111 + - const: cortina,gemini + deprecated: true + + - description: Wiligear Wiliboard WBD-222 - old incorrect binding + items: + - const: wiliboard,wbd222 + - const: cortina,gemini + deprecated: true + +additionalProperties: true diff --git a/Documentation/devicetree/bindings/arm/mediatek/mediatek,audsys.txt b/Documentation/devicetree/bindings/arm/mediatek/mediatek,audsys.txt index b32d374193c7..699776be1dd3 100644 --- a/Documentation/devicetree/bindings/arm/mediatek/mediatek,audsys.txt +++ b/Documentation/devicetree/bindings/arm/mediatek/mediatek,audsys.txt @@ -13,6 +13,7 @@ Required Properties: - "mediatek,mt7623-audsys", "mediatek,mt2701-audsys", "syscon" - "mediatek,mt8167-audiosys", "syscon" - "mediatek,mt8183-audiosys", "syscon" + - "mediatek,mt8192-audsys", "syscon" - "mediatek,mt8516-audsys", "syscon" - #clock-cells: Must be 1 diff --git a/Documentation/devicetree/bindings/arm/mediatek/mediatek,mmsys.txt b/Documentation/devicetree/bindings/arm/mediatek/mediatek,mmsys.txt deleted file mode 100644 index 78c50733985c..000000000000 --- a/Documentation/devicetree/bindings/arm/mediatek/mediatek,mmsys.txt +++ /dev/null @@ -1,31 +0,0 @@ -Mediatek mmsys controller -============================ - -The Mediatek mmsys system controller provides clock control, routing control, -and miscellaneous control in mmsys partition. - -Required Properties: - -- compatible: Should be one of: - - "mediatek,mt2701-mmsys", "syscon" - - "mediatek,mt2712-mmsys", "syscon" - - "mediatek,mt6765-mmsys", "syscon" - - "mediatek,mt6779-mmsys", "syscon" - - "mediatek,mt6797-mmsys", "syscon" - - "mediatek,mt7623-mmsys", "mediatek,mt2701-mmsys", "syscon" - - "mediatek,mt8167-mmsys", "syscon" - - "mediatek,mt8173-mmsys", "syscon" - - "mediatek,mt8183-mmsys", "syscon" -- #clock-cells: Must be 1 - -For the clock control, the mmsys controller uses the common clk binding from -Documentation/devicetree/bindings/clock/clock-bindings.txt -The available clocks are defined in dt-bindings/clock/mt*-clk.h. - -Example: - -mmsys: syscon@14000000 { - compatible = "mediatek,mt8173-mmsys", "syscon"; - reg = <0 0x14000000 0 0x1000>; - #clock-cells = <1>; -}; diff --git a/Documentation/devicetree/bindings/arm/mediatek/mediatek,mmsys.yaml b/Documentation/devicetree/bindings/arm/mediatek/mediatek,mmsys.yaml new file mode 100644 index 000000000000..f9ffa5b703a5 --- /dev/null +++ b/Documentation/devicetree/bindings/arm/mediatek/mediatek,mmsys.yaml @@ -0,0 +1,59 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: "http://devicetree.org/schemas/arm/mediatek/mediatek,mmsys.yaml#" +$schema: "http://devicetree.org/meta-schemas/core.yaml#" + +title: MediaTek mmsys controller + +maintainers: + - Matthias Brugger <matthias.bgg@gmail.com> + +description: + The MediaTek mmsys system controller provides clock control, routing control, + and miscellaneous control in mmsys partition. + +properties: + $nodename: + pattern: "^syscon@[0-9a-f]+$" + + compatible: + oneOf: + - items: + - enum: + - mediatek,mt2701-mmsys + - mediatek,mt2712-mmsys + - mediatek,mt6765-mmsys + - mediatek,mt6779-mmsys + - mediatek,mt6797-mmsys + - mediatek,mt8167-mmsys + - mediatek,mt8173-mmsys + - mediatek,mt8183-mmsys + - mediatek,mt8192-mmsys + - mediatek,mt8365-mmsys + - const: syscon + - items: + - const: mediatek,mt7623-mmsys + - const: mediatek,mt2701-mmsys + - const: syscon + + reg: + maxItems: 1 + + "#clock-cells": + const: 1 + +required: + - compatible + - reg + - "#clock-cells" + +additionalProperties: false + +examples: + - | + mmsys: syscon@14000000 { + compatible = "mediatek,mt8173-mmsys", "syscon"; + reg = <0x14000000 0x1000>; + #clock-cells = <1>; + }; diff --git a/Documentation/devicetree/bindings/arm/mediatek/mediatek,mt8192-clock.yaml b/Documentation/devicetree/bindings/arm/mediatek/mediatek,mt8192-clock.yaml new file mode 100644 index 000000000000..c8c67c033f8c --- /dev/null +++ b/Documentation/devicetree/bindings/arm/mediatek/mediatek,mt8192-clock.yaml @@ -0,0 +1,199 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: "http://devicetree.org/schemas/arm/mediatek/mediatek,mt8192-clock.yaml#" +$schema: "http://devicetree.org/meta-schemas/core.yaml#" + +title: MediaTek Functional Clock Controller for MT8192 + +maintainers: + - Chun-Jie Chen <chun-jie.chen@mediatek.com> + +description: + The Mediatek functional clock controller provides various clocks on MT8192. + +properties: + compatible: + items: + - enum: + - mediatek,mt8192-scp_adsp + - mediatek,mt8192-imp_iic_wrap_c + - mediatek,mt8192-imp_iic_wrap_e + - mediatek,mt8192-imp_iic_wrap_s + - mediatek,mt8192-imp_iic_wrap_ws + - mediatek,mt8192-imp_iic_wrap_w + - mediatek,mt8192-imp_iic_wrap_n + - mediatek,mt8192-msdc_top + - mediatek,mt8192-msdc + - mediatek,mt8192-mfgcfg + - mediatek,mt8192-imgsys + - mediatek,mt8192-imgsys2 + - mediatek,mt8192-vdecsys_soc + - mediatek,mt8192-vdecsys + - mediatek,mt8192-vencsys + - mediatek,mt8192-camsys + - mediatek,mt8192-camsys_rawa + - mediatek,mt8192-camsys_rawb + - mediatek,mt8192-camsys_rawc + - mediatek,mt8192-ipesys + - mediatek,mt8192-mdpsys + + reg: + maxItems: 1 + + '#clock-cells': + const: 1 + +required: + - compatible + - reg + +additionalProperties: false + +examples: + - | + scp_adsp: clock-controller@10720000 { + compatible = "mediatek,mt8192-scp_adsp"; + reg = <0x10720000 0x1000>; + #clock-cells = <1>; + }; + + - | + imp_iic_wrap_c: clock-controller@11007000 { + compatible = "mediatek,mt8192-imp_iic_wrap_c"; + reg = <0x11007000 0x1000>; + #clock-cells = <1>; + }; + + - | + imp_iic_wrap_e: clock-controller@11cb1000 { + compatible = "mediatek,mt8192-imp_iic_wrap_e"; + reg = <0x11cb1000 0x1000>; + #clock-cells = <1>; + }; + + - | + imp_iic_wrap_s: clock-controller@11d03000 { + compatible = "mediatek,mt8192-imp_iic_wrap_s"; + reg = <0x11d03000 0x1000>; + #clock-cells = <1>; + }; + + - | + imp_iic_wrap_ws: clock-controller@11d23000 { + compatible = "mediatek,mt8192-imp_iic_wrap_ws"; + reg = <0x11d23000 0x1000>; + #clock-cells = <1>; + }; + + - | + imp_iic_wrap_w: clock-controller@11e01000 { + compatible = "mediatek,mt8192-imp_iic_wrap_w"; + reg = <0x11e01000 0x1000>; + #clock-cells = <1>; + }; + + - | + imp_iic_wrap_n: clock-controller@11f02000 { + compatible = "mediatek,mt8192-imp_iic_wrap_n"; + reg = <0x11f02000 0x1000>; + #clock-cells = <1>; + }; + + - | + msdc_top: clock-controller@11f10000 { + compatible = "mediatek,mt8192-msdc_top"; + reg = <0x11f10000 0x1000>; + #clock-cells = <1>; + }; + + - | + msdc: clock-controller@11f60000 { + compatible = "mediatek,mt8192-msdc"; + reg = <0x11f60000 0x1000>; + #clock-cells = <1>; + }; + + - | + mfgcfg: clock-controller@13fbf000 { + compatible = "mediatek,mt8192-mfgcfg"; + reg = <0x13fbf000 0x1000>; + #clock-cells = <1>; + }; + + - | + imgsys: clock-controller@15020000 { + compatible = "mediatek,mt8192-imgsys"; + reg = <0x15020000 0x1000>; + #clock-cells = <1>; + }; + + - | + imgsys2: clock-controller@15820000 { + compatible = "mediatek,mt8192-imgsys2"; + reg = <0x15820000 0x1000>; + #clock-cells = <1>; + }; + + - | + vdecsys_soc: clock-controller@1600f000 { + compatible = "mediatek,mt8192-vdecsys_soc"; + reg = <0x1600f000 0x1000>; + #clock-cells = <1>; + }; + + - | + vdecsys: clock-controller@1602f000 { + compatible = "mediatek,mt8192-vdecsys"; + reg = <0x1602f000 0x1000>; + #clock-cells = <1>; + }; + + - | + vencsys: clock-controller@17000000 { + compatible = "mediatek,mt8192-vencsys"; + reg = <0x17000000 0x1000>; + #clock-cells = <1>; + }; + + - | + camsys: clock-controller@1a000000 { + compatible = "mediatek,mt8192-camsys"; + reg = <0x1a000000 0x1000>; + #clock-cells = <1>; + }; + + - | + camsys_rawa: clock-controller@1a04f000 { + compatible = "mediatek,mt8192-camsys_rawa"; + reg = <0x1a04f000 0x1000>; + #clock-cells = <1>; + }; + + - | + camsys_rawb: clock-controller@1a06f000 { + compatible = "mediatek,mt8192-camsys_rawb"; + reg = <0x1a06f000 0x1000>; + #clock-cells = <1>; + }; + + - | + camsys_rawc: clock-controller@1a08f000 { + compatible = "mediatek,mt8192-camsys_rawc"; + reg = <0x1a08f000 0x1000>; + #clock-cells = <1>; + }; + + - | + ipesys: clock-controller@1b000000 { + compatible = "mediatek,mt8192-ipesys"; + reg = <0x1b000000 0x1000>; + #clock-cells = <1>; + }; + + - | + mdpsys: clock-controller@1f000000 { + compatible = "mediatek,mt8192-mdpsys"; + reg = <0x1f000000 0x1000>; + #clock-cells = <1>; + }; diff --git a/Documentation/devicetree/bindings/arm/mediatek/mediatek,mt8192-sys-clock.yaml b/Documentation/devicetree/bindings/arm/mediatek/mediatek,mt8192-sys-clock.yaml new file mode 100644 index 000000000000..5705bcf1fe47 --- /dev/null +++ b/Documentation/devicetree/bindings/arm/mediatek/mediatek,mt8192-sys-clock.yaml @@ -0,0 +1,65 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: "http://devicetree.org/schemas/arm/mediatek/mediatek,mt8192-sys-clock.yaml#" +$schema: "http://devicetree.org/meta-schemas/core.yaml#" + +title: MediaTek System Clock Controller for MT8192 + +maintainers: + - Chun-Jie Chen <chun-jie.chen@mediatek.com> + +description: + The Mediatek system clock controller provides various clocks and system configuration + like reset and bus protection on MT8192. + +properties: + compatible: + items: + - enum: + - mediatek,mt8192-topckgen + - mediatek,mt8192-infracfg + - mediatek,mt8192-pericfg + - mediatek,mt8192-apmixedsys + - const: syscon + + reg: + maxItems: 1 + + '#clock-cells': + const: 1 + +required: + - compatible + - reg + +additionalProperties: false + +examples: + - | + topckgen: syscon@10000000 { + compatible = "mediatek,mt8192-topckgen", "syscon"; + reg = <0x10000000 0x1000>; + #clock-cells = <1>; + }; + + - | + infracfg: syscon@10001000 { + compatible = "mediatek,mt8192-infracfg", "syscon"; + reg = <0x10001000 0x1000>; + #clock-cells = <1>; + }; + + - | + pericfg: syscon@10003000 { + compatible = "mediatek,mt8192-pericfg", "syscon"; + reg = <0x10003000 0x1000>; + #clock-cells = <1>; + }; + + - | + apmixedsys: syscon@1000c000 { + compatible = "mediatek,mt8192-apmixedsys", "syscon"; + reg = <0x1000c000 0x1000>; + #clock-cells = <1>; + }; diff --git a/Documentation/devicetree/bindings/arm/qcom.yaml b/Documentation/devicetree/bindings/arm/qcom.yaml index 9720b00c41d2..880ddafc634e 100644 --- a/Documentation/devicetree/bindings/arm/qcom.yaml +++ b/Documentation/devicetree/bindings/arm/qcom.yaml @@ -31,6 +31,7 @@ description: | ipq6018 ipq8074 mdm9615 + msm8226 msm8916 msm8974 msm8992 @@ -116,6 +117,11 @@ properties: - items: - enum: + - samsung,s3ve3g + - const: qcom,msm8226 + + - items: + - enum: - qcom,msm8960-cdp - const: qcom,msm8960 @@ -129,6 +135,8 @@ properties: - const: qcom,msm8974 - items: + - enum: + - alcatel,idol347 - const: qcom,msm8916-mtp/1 - const: qcom,msm8916-mtp - const: qcom,msm8916 @@ -181,6 +189,8 @@ properties: - items: - enum: - qcom,sc7280-idp + - qcom,sc7280-idp2 + - google,piglin - google,senor - const: qcom,sc7280 diff --git a/Documentation/devicetree/bindings/arm/renesas.yaml b/Documentation/devicetree/bindings/arm/renesas.yaml index a0cce4e25039..8a11918866b8 100644 --- a/Documentation/devicetree/bindings/arm/renesas.yaml +++ b/Documentation/devicetree/bindings/arm/renesas.yaml @@ -238,17 +238,29 @@ properties: - const: renesas,r8a77961 - description: Kingfisher (SBEV-RCAR-KF-M03) - items: - - const: shimafuji,kingfisher - - enum: - - renesas,h3ulcb - - renesas,m3ulcb - - renesas,m3nulcb - - enum: - - renesas,r8a7795 - - renesas,r8a7796 - - renesas,r8a77961 - - renesas,r8a77965 + oneOf: + - items: + - const: shimafuji,kingfisher + - enum: + - renesas,h3ulcb + - renesas,m3ulcb + - renesas,m3nulcb + - enum: + - renesas,r8a7795 + - renesas,r8a7796 + - renesas,r8a77961 + - renesas,r8a77965 + - items: + - const: shimafuji,kingfisher + - enum: + - renesas,h3ulcb + - renesas,m3ulcb + - enum: + - renesas,r8a779m1 + - renesas,r8a779m3 + - enum: + - renesas,r8a7795 + - renesas,r8a77961 - description: R-Car M3-N (R8A77965) items: @@ -296,6 +308,22 @@ properties: - const: renesas,falcon-cpu - const: renesas,r8a779a0 + - description: R-Car H3e-2G (R8A779M1) + items: + - enum: + - renesas,h3ulcb # H3ULCB (R-Car Starter Kit Premier) + - renesas,salvator-xs # Salvator-XS (Salvator-X 2nd version) + - const: renesas,r8a779m1 + - const: renesas,r8a7795 + + - description: R-Car M3e-2G (R8A779M3) + items: + - enum: + - renesas,m3ulcb # M3ULCB (R-Car Starter Kit Pro) + - renesas,salvator-xs # Salvator-XS (Salvator-X 2nd version) + - const: renesas,r8a779m3 + - const: renesas,r8a77961 + - description: RZ/N1D (R9A06G032) items: - enum: diff --git a/Documentation/devicetree/bindings/arm/tegra.yaml b/Documentation/devicetree/bindings/arm/tegra.yaml index b9f75e20fef5..b962fa6d649c 100644 --- a/Documentation/devicetree/bindings/arm/tegra.yaml +++ b/Documentation/devicetree/bindings/arm/tegra.yaml @@ -111,6 +111,7 @@ properties: - items: - enum: - nvidia,p2771-0000 + - nvidia,p3509-0000+p3636-0001 - const: nvidia,tegra186 - items: - enum: diff --git a/Documentation/devicetree/bindings/ata/exynos-sata.txt b/Documentation/devicetree/bindings/ata/exynos-sata.txt deleted file mode 100644 index cb48448247ea..000000000000 --- a/Documentation/devicetree/bindings/ata/exynos-sata.txt +++ /dev/null @@ -1,30 +0,0 @@ -* Samsung AHCI SATA Controller - -SATA nodes are defined to describe on-chip Serial ATA controllers. -Each SATA controller should have its own node. - -Required properties: -- compatible : compatible list, contains "samsung,exynos5-sata" -- interrupts : <interrupt mapping for SATA IRQ> -- reg : <registers mapping> -- samsung,sata-freq : <frequency in MHz> -- phys : Must contain exactly one entry as specified - in phy-bindings.txt -- phy-names : Must be "sata-phy" - -Optional properties: -- clocks : Must contain an entry for each entry in clock-names. -- clock-names : Shall be "sata" for the external SATA bus clock, - and "sclk_sata" for the internal controller clock. - -Example: - sata@122f0000 { - compatible = "snps,dwc-ahci"; - samsung,sata-freq = <66>; - reg = <0x122f0000 0x1ff>; - interrupts = <0 115 0>; - clocks = <&clock 277>, <&clock 143>; - clock-names = "sata", "sclk_sata"; - phys = <&sata_phy>; - phy-names = "sata-phy"; - }; diff --git a/Documentation/devicetree/bindings/ata/intel,ixp4xx-compact-flash.yaml b/Documentation/devicetree/bindings/ata/intel,ixp4xx-compact-flash.yaml new file mode 100644 index 000000000000..52e18600ecff --- /dev/null +++ b/Documentation/devicetree/bindings/ata/intel,ixp4xx-compact-flash.yaml @@ -0,0 +1,61 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/ata/intel,ixp4xx-compact-flash.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Intel IXP4xx CompactFlash Card Controller + +maintainers: + - Linus Walleij <linus.walleij@linaro.org> + +description: | + The IXP4xx network processors have a CompactFlash interface that presents + a CompactFlash card to the system as a true IDE (parallel ATA) device. The + device is always connected to the expansion bus of the IXP4xx SoCs using one + or two chip select areas and address translating logic on the board. The + node must be placed inside a chip select node on the IXP4xx expansion bus. + +properties: + compatible: + const: intel,ixp4xx-compact-flash + + reg: + items: + - description: Command interface registers + - description: Control interface registers + + interrupts: + maxItems: 1 + +required: + - compatible + - reg + - interrupts + +allOf: + - $ref: pata-common.yaml# + +unevaluatedProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/irq.h> + + bus@c4000000 { + compatible = "intel,ixp43x-expansion-bus-controller", "syscon"; + reg = <0xc4000000 0x1000>; + native-endian; + #address-cells = <2>; + #size-cells = <1>; + ranges = <0 0x0 0x50000000 0x01000000>, <1 0x0 0x51000000 0x01000000>; + dma-ranges = <0 0x0 0x50000000 0x01000000>, <1 0x0 0x51000000 0x01000000>; + ide@1,0 { + compatible = "intel,ixp4xx-compact-flash"; + reg = <1 0x00000000 0x1000>, <1 0x00040000 0x1000>; + interrupt-parent = <&gpio0>; + interrupts = <12 IRQ_TYPE_EDGE_RISING>; + }; + }; + +... diff --git a/Documentation/devicetree/bindings/auxdisplay/arm,versatile-lcd.yaml b/Documentation/devicetree/bindings/auxdisplay/arm,versatile-lcd.yaml new file mode 100644 index 000000000000..5d02bd032a85 --- /dev/null +++ b/Documentation/devicetree/bindings/auxdisplay/arm,versatile-lcd.yaml @@ -0,0 +1,44 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/auxdisplay/arm,versatile-lcd.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: ARM Versatile Character LCD + +maintainers: + - Linus Walleij <linus.walleij@linaro.org> + - Rob Herring <robh@kernel.org> + +description: + This binding defines the character LCD interface found on ARM Versatile AB + and PB reference platforms. + +properties: + compatible: + const: arm,versatile-lcd + + reg: + maxItems: 1 + + clocks: + maxItems: 1 + + clock-names: + maxItems: 1 + + interrupts: + maxItems: 1 + +required: + - compatible + - reg + +additionalProperties: false + +examples: + - | + lcd@10008000 { + compatible = "arm,versatile-lcd"; + reg = <0x10008000 0x1000>; + }; diff --git a/Documentation/devicetree/bindings/auxdisplay/arm-charlcd.txt b/Documentation/devicetree/bindings/auxdisplay/arm-charlcd.txt deleted file mode 100644 index e28e2aac47f1..000000000000 --- a/Documentation/devicetree/bindings/auxdisplay/arm-charlcd.txt +++ /dev/null @@ -1,18 +0,0 @@ -ARM Versatile Character LCD ------------------------------------------------------ -This binding defines the character LCD interface found on ARM Versatile AB -and PB reference platforms. - -Required properties: -- compatible : "arm,versatile-clcd" -- reg : Location and size of character LCD registers - -Optional properties: -- interrupts - single interrupt for character LCD. The character LCD can - operate in polled mode without an interrupt. - -Example: - lcd@10008000 { - compatible = "arm,versatile-lcd"; - reg = <0x10008000 0x1000>; - }; diff --git a/Documentation/devicetree/bindings/auxdisplay/img,ascii-lcd.yaml b/Documentation/devicetree/bindings/auxdisplay/img,ascii-lcd.yaml new file mode 100644 index 000000000000..1899b23de7d1 --- /dev/null +++ b/Documentation/devicetree/bindings/auxdisplay/img,ascii-lcd.yaml @@ -0,0 +1,55 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/auxdisplay/img,ascii-lcd.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: ASCII LCD displays on Imagination Technologies boards + +maintainers: + - Paul Burton <paulburton@kernel.org> + +properties: + compatible: + enum: + - img,boston-lcd + - mti,malta-lcd + - mti,sead3-lcd + + reg: + maxItems: 1 + + offset: + $ref: /schemas/types.yaml#/definitions/uint32 + description: + Offset in bytes to the LCD registers within the system controller + +required: + - compatible + +oneOf: + - required: + - reg + - required: + - offset + +if: + properties: + compatible: + contains: + const: img,boston-lcd +then: + required: + - reg +else: + required: + - offset + +additionalProperties: false + +examples: + - | + lcd: lcd@17fff000 { + compatible = "img,boston-lcd"; + reg = <0x17fff000 0x8>; + }; diff --git a/Documentation/devicetree/bindings/auxdisplay/img-ascii-lcd.txt b/Documentation/devicetree/bindings/auxdisplay/img-ascii-lcd.txt deleted file mode 100644 index b69bb68992fd..000000000000 --- a/Documentation/devicetree/bindings/auxdisplay/img-ascii-lcd.txt +++ /dev/null @@ -1,17 +0,0 @@ -Binding for ASCII LCD displays on Imagination Technologies boards - -Required properties: -- compatible : should be one of: - "img,boston-lcd" - "mti,malta-lcd" - "mti,sead3-lcd" - -Required properties for "img,boston-lcd": -- reg : memory region locating the device registers - -Required properties for "mti,malta-lcd" or "mti,sead3-lcd": -- regmap: phandle of the system controller containing the LCD registers -- offset: offset in bytes to the LCD registers within the system controller - -The layout of the registers & properties of the display are determined -from the compatible string, making this binding somewhat trivial. diff --git a/Documentation/devicetree/bindings/bus/intel,ixp4xx-expansion-bus-controller.yaml b/Documentation/devicetree/bindings/bus/intel,ixp4xx-expansion-bus-controller.yaml new file mode 100644 index 000000000000..5fb4e7bfa4da --- /dev/null +++ b/Documentation/devicetree/bindings/bus/intel,ixp4xx-expansion-bus-controller.yaml @@ -0,0 +1,168 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/bus/intel,ixp4xx-expansion-bus-controller.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Intel IXP4xx Expansion Bus Controller + +description: | + The IXP4xx expansion bus controller handles access to devices on the + memory-mapped expansion bus on the Intel IXP4xx family of system on chips, + including IXP42x, IXP43x, IXP45x and IXP46x. + +maintainers: + - Linus Walleij <linus.walleij@linaro.org> + +properties: + $nodename: + pattern: '^bus@[0-9a-f]+$' + + compatible: + items: + - enum: + - intel,ixp42x-expansion-bus-controller + - intel,ixp43x-expansion-bus-controller + - intel,ixp45x-expansion-bus-controller + - intel,ixp46x-expansion-bus-controller + - const: syscon + + reg: + description: Control registers for the expansion bus, these are not + inside the memory range handled by the expansion bus. + maxItems: 1 + + native-endian: + $ref: /schemas/types.yaml#/definitions/flag + description: The IXP4xx has a peculiar MMIO access scheme, as it changes + the access pattern for words (swizzling) on the bus depending on whether + the SoC is running in big-endian or little-endian mode. Thus the + registers must always be accessed using native endianness. + + "#address-cells": + description: | + The first cell is the chip select number. + The second cell is the address offset within the bank. + const: 2 + + "#size-cells": + const: 1 + + ranges: true + dma-ranges: true + +patternProperties: + "^.*@[0-7],[0-9a-f]+$": + description: Devices attached to chip selects are represented as + subnodes. + type: object + + properties: + intel,ixp4xx-eb-t1: + description: Address timing, extend address phase with n cycles. + $ref: /schemas/types.yaml#/definitions/uint32 + maximum: 3 + + intel,ixp4xx-eb-t2: + description: Setup chip select timing, extend setup phase with n cycles. + $ref: /schemas/types.yaml#/definitions/uint32 + maximum: 3 + + intel,ixp4xx-eb-t3: + description: Strobe timing, extend strobe phase with n cycles. + $ref: /schemas/types.yaml#/definitions/uint32 + maximum: 15 + + intel,ixp4xx-eb-t4: + description: Hold timing, extend hold phase with n cycles. + $ref: /schemas/types.yaml#/definitions/uint32 + maximum: 3 + + intel,ixp4xx-eb-t5: + description: Recovery timing, extend recovery phase with n cycles. + $ref: /schemas/types.yaml#/definitions/uint32 + maximum: 15 + + intel,ixp4xx-eb-cycle-type: + description: The type of cycles to use on the expansion bus for this + chip select. 0 = Intel cycles, 1 = Motorola cycles, 2 = HPI cycles. + $ref: /schemas/types.yaml#/definitions/uint32 + enum: [0, 1, 2] + + intel,ixp4xx-eb-byte-access-on-halfword: + description: Allow byte read access on half word devices. + $ref: /schemas/types.yaml#/definitions/uint32 + enum: [0, 1] + + intel,ixp4xx-eb-hpi-hrdy-pol-high: + description: Set HPI HRDY polarity to active high when using HPI. + $ref: /schemas/types.yaml#/definitions/uint32 + enum: [0, 1] + + intel,ixp4xx-eb-mux-address-and-data: + description: Multiplex address and data on the data bus. + $ref: /schemas/types.yaml#/definitions/uint32 + enum: [0, 1] + + intel,ixp4xx-eb-ahb-split-transfers: + description: Enable AHB split transfers. + $ref: /schemas/types.yaml#/definitions/uint32 + enum: [0, 1] + + intel,ixp4xx-eb-write-enable: + description: Enable write cycles. + $ref: /schemas/types.yaml#/definitions/uint32 + enum: [0, 1] + + intel,ixp4xx-eb-byte-access: + description: Expansion bus uses only 8 bits. The default is to use + 16 bits. + $ref: /schemas/types.yaml#/definitions/uint32 + enum: [0, 1] + +required: + - compatible + - reg + - native-endian + - "#address-cells" + - "#size-cells" + - ranges + - dma-ranges + +additionalProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/irq.h> + bus@50000000 { + compatible = "intel,ixp42x-expansion-bus-controller", "syscon"; + reg = <0xc4000000 0x28>; + native-endian; + #address-cells = <2>; + #size-cells = <1>; + ranges = <0 0x0 0x50000000 0x01000000>, + <1 0x0 0x51000000 0x01000000>; + dma-ranges = <0 0x0 0x50000000 0x01000000>, + <1 0x0 0x51000000 0x01000000>; + flash@0,0 { + compatible = "intel,ixp4xx-flash", "cfi-flash"; + bank-width = <2>; + reg = <0 0x00000000 0x1000000>; + intel,ixp4xx-eb-t3 = <3>; + intel,ixp4xx-eb-cycle-type = <0>; + intel,ixp4xx-eb-byte-access-on-halfword = <1>; + intel,ixp4xx-eb-write-enable = <1>; + intel,ixp4xx-eb-byte-access = <0>; + }; + serial@1,0 { + compatible = "exar,xr16l2551", "ns8250"; + reg = <1 0x00000000 0x10>; + interrupt-parent = <&gpio0>; + interrupts = <4 IRQ_TYPE_LEVEL_LOW>; + clock-frequency = <1843200>; + intel,ixp4xx-eb-t3 = <3>; + intel,ixp4xx-eb-cycle-type = <1>; + intel,ixp4xx-eb-write-enable = <1>; + intel,ixp4xx-eb-byte-access = <1>; + }; + }; diff --git a/Documentation/devicetree/bindings/chosen.txt b/Documentation/devicetree/bindings/chosen.txt index 45e79172a646..1cc3aa10dcb1 100644 --- a/Documentation/devicetree/bindings/chosen.txt +++ b/Documentation/devicetree/bindings/chosen.txt @@ -79,9 +79,9 @@ a different secondary CPU release mechanism) linux,usable-memory-range ------------------------- -This property (arm64 only) holds a base address and size, describing a -limited region in which memory may be considered available for use by -the kernel. Memory outside of this range is not available for use. +This property holds a base address and size, describing a limited region in +which memory may be considered available for use by the kernel. Memory outside +of this range is not available for use. This property describes a limitation: memory within this range is only valid when also described through another mechanism that the kernel @@ -106,9 +106,9 @@ respectively, of the root node. linux,elfcorehdr ---------------- -This property (currently used only on arm64) holds the memory range, -the address and the size, of the elf core header which mainly describes -the panicked kernel's memory layout as PT_LOAD segments of elf format. +This property holds the memory range, the address and the size, of the elf +core header which mainly describes the panicked kernel's memory layout as +PT_LOAD segments of elf format. e.g. / { diff --git a/Documentation/devicetree/bindings/clock/brcm,iproc-clocks.yaml b/Documentation/devicetree/bindings/clock/brcm,iproc-clocks.yaml index 1174c9aa9934..5ad147d265e6 100644 --- a/Documentation/devicetree/bindings/clock/brcm,iproc-clocks.yaml +++ b/Documentation/devicetree/bindings/clock/brcm,iproc-clocks.yaml @@ -61,7 +61,7 @@ properties: maxItems: 1 '#clock-cells': - const: 1 + true clock-output-names: minItems: 1 @@ -74,6 +74,23 @@ allOf: contains: enum: - brcm,cygnus-armpll + - brcm,nsp-armpll + then: + properties: + '#clock-cells': + const: 0 + else: + properties: + '#clock-cells': + const: 1 + required: + - clock-output-names + - if: + properties: + compatible: + contains: + enum: + - brcm,cygnus-armpll - brcm,cygnus-genpll - brcm,cygnus-lcpll0 - brcm,cygnus-mipipll @@ -358,7 +375,6 @@ required: - reg - clocks - '#clock-cells' - - clock-output-names additionalProperties: false @@ -392,3 +408,10 @@ examples: clocks = <&osc2>; clock-output-names = "keypad", "adc/touch", "pwm"; }; + - | + arm_clk@0 { + #clock-cells = <0>; + compatible = "brcm,nsp-armpll"; + clocks = <&osc>; + reg = <0x0 0x1000>; + }; diff --git a/Documentation/devicetree/bindings/clock/clk-exynos-audss.txt b/Documentation/devicetree/bindings/clock/clk-exynos-audss.txt deleted file mode 100644 index 6030afb10b5c..000000000000 --- a/Documentation/devicetree/bindings/clock/clk-exynos-audss.txt +++ /dev/null @@ -1,103 +0,0 @@ -* Samsung Audio Subsystem Clock Controller - -The Samsung Audio Subsystem clock controller generates and supplies clocks -to Audio Subsystem block available in the S5PV210 and Exynos SoCs. The clock -binding described here is applicable to all SoCs in Exynos family. - -Required Properties: - -- compatible: should be one of the following: - - "samsung,exynos4210-audss-clock" - controller compatible with all Exynos4 SoCs. - - "samsung,exynos5250-audss-clock" - controller compatible with Exynos5250 - SoCs. - - "samsung,exynos5410-audss-clock" - controller compatible with Exynos5410 - SoCs. - - "samsung,exynos5420-audss-clock" - controller compatible with Exynos5420 - SoCs. -- reg: physical base address and length of the controller's register set. - -- #clock-cells: should be 1. - -- clocks: - - pll_ref: Fixed rate PLL reference clock, parent of mout_audss. "fin_pll" - is used if not specified. - - pll_in: Input PLL to the AudioSS block, parent of mout_audss. "fout_epll" - is used if not specified. - - cdclk: External i2s clock, parent of mout_i2s. "cdclk0" is used if not - specified. - - sclk_audio: Audio bus clock, parent of mout_i2s. "sclk_audio0" is used if - not specified. - - sclk_pcm_in: PCM clock, parent of sclk_pcm. "sclk_pcm0" is used if not - specified. - -- clock-names: Aliases for the above clocks. They should be "pll_ref", - "pll_in", "cdclk", "sclk_audio", and "sclk_pcm_in" respectively. - -Optional Properties: - - - power-domains: a phandle to respective power domain node as described by - generic PM domain bindings (see power/power_domain.txt for more - information). - -The following is the list of clocks generated by the controller. Each clock is -assigned an identifier and client nodes use this identifier to specify the -clock which they consume. Some of the clocks are available only on a particular -Exynos4 SoC and this is specified where applicable. - -Provided clocks: - -Clock ID SoC (if specific) ------------------------------------------------ - -mout_audss 0 -mout_i2s 1 -dout_srp 2 -dout_aud_bus 3 -dout_i2s 4 -srp_clk 5 -i2s_bus 6 -sclk_i2s 7 -pcm_bus 8 -sclk_pcm 9 -adma 10 Exynos5420 - -Example 1: An example of a clock controller node using the default input - clock names is listed below. - -clock_audss: audss-clock-controller@3810000 { - compatible = "samsung,exynos5250-audss-clock"; - reg = <0x03810000 0x0C>; - #clock-cells = <1>; -}; - -Example 2: An example of a clock controller node with the input clocks - specified. - -clock_audss: audss-clock-controller@3810000 { - compatible = "samsung,exynos5250-audss-clock"; - reg = <0x03810000 0x0C>; - #clock-cells = <1>; - clocks = <&clock 1>, <&clock 7>, <&clock 138>, <&clock 160>, - <&ext_i2s_clk>; - clock-names = "pll_ref", "pll_in", "sclk_audio", "sclk_pcm_in", "cdclk"; -}; - -Example 3: I2S controller node that consumes the clock generated by the clock - controller. Refer to the standard clock bindings for information - about 'clocks' and 'clock-names' property. - -i2s0: i2s@3830000 { - compatible = "samsung,i2s-v5"; - reg = <0x03830000 0x100>; - dmas = <&pdma0 10 - &pdma0 9 - &pdma0 8>; - dma-names = "tx", "rx", "tx-sec"; - clocks = <&clock_audss EXYNOS_I2S_BUS>, - <&clock_audss EXYNOS_I2S_BUS>, - <&clock_audss EXYNOS_SCLK_I2S>, - <&clock_audss EXYNOS_MOUT_AUDSS>, - <&clock_audss EXYNOS_MOUT_I2S>; - clock-names = "iis", "i2s_opclk0", "i2s_opclk1", - "mout_audss", "mout_i2s"; -}; diff --git a/Documentation/devicetree/bindings/clock/clk-s5pv210-audss.txt b/Documentation/devicetree/bindings/clock/clk-s5pv210-audss.txt deleted file mode 100644 index f6272dcd96f4..000000000000 --- a/Documentation/devicetree/bindings/clock/clk-s5pv210-audss.txt +++ /dev/null @@ -1,53 +0,0 @@ -* Samsung Audio Subsystem Clock Controller - -The Samsung Audio Subsystem clock controller generates and supplies clocks -to Audio Subsystem block available in the S5PV210 and compatible SoCs. - -Required Properties: - -- compatible: should be "samsung,s5pv210-audss-clock". -- reg: physical base address and length of the controller's register set. - -- #clock-cells: should be 1. - -- clocks: - - hclk: AHB bus clock of the Audio Subsystem. - - xxti: Optional fixed rate PLL reference clock, parent of mout_audss. If - not specified (i.e. xusbxti is used for PLL reference), it is fixed to - a clock named "xxti". - - fout_epll: Input PLL to the AudioSS block, parent of mout_audss. - - iiscdclk0: Optional external i2s clock, parent of mout_i2s. If not - specified, it is fixed to a clock named "iiscdclk0". - - sclk_audio0: Audio bus clock, parent of mout_i2s. - -- clock-names: Aliases for the above clocks. They should be "hclk", - "xxti", "fout_epll", "iiscdclk0", and "sclk_audio0" respectively. - -All available clocks are defined as preprocessor macros in -dt-bindings/clock/s5pv210-audss-clk.h header and can be used in device -tree sources. - -Example: Clock controller node. - - clk_audss: clock-controller@c0900000 { - compatible = "samsung,s5pv210-audss-clock"; - reg = <0xc0900000 0x1000>; - #clock-cells = <1>; - clock-names = "hclk", "xxti", - "fout_epll", "sclk_audio0"; - clocks = <&clocks DOUT_HCLKP>, <&xxti>, - <&clocks FOUT_EPLL>, <&clocks SCLK_AUDIO0>; - }; - -Example: I2S controller node that consumes the clock generated by the clock - controller. Refer to the standard clock bindings for information - about 'clocks' and 'clock-names' property. - - i2s0: i2s@3830000 { - /* ... */ - clock-names = "iis", "i2s_opclk0", - "i2s_opclk1"; - clocks = <&clk_audss CLK_I2S>, <&clk_audss CLK_I2S>, - <&clk_audss CLK_DOUT_AUD_BUS>; - /* ... */ - }; diff --git a/Documentation/devicetree/bindings/clock/exynos3250-clock.txt b/Documentation/devicetree/bindings/clock/exynos3250-clock.txt deleted file mode 100644 index 7441ed519f02..000000000000 --- a/Documentation/devicetree/bindings/clock/exynos3250-clock.txt +++ /dev/null @@ -1,57 +0,0 @@ -* Samsung Exynos3250 Clock Controller - -The Exynos3250 clock controller generates and supplies clock to various -controllers within the Exynos3250 SoC. - -Required Properties: - -- compatible: should be one of the following. - - "samsung,exynos3250-cmu" - controller compatible with Exynos3250 SoC. - - "samsung,exynos3250-cmu-dmc" - controller compatible with - Exynos3250 SoC for Dynamic Memory Controller domain. - - "samsung,exynos3250-cmu-isp" - ISP block clock controller compatible - with Exynos3250 SOC - -- reg: physical base address of the controller and length of memory mapped - region. - -- #clock-cells: should be 1. - -Each clock is assigned an identifier and client nodes can use this identifier -to specify the clock which they consume. - -All available clocks are defined as preprocessor macros in -dt-bindings/clock/exynos3250.h header and can be used in device -tree sources. - -Example 1: Examples of clock controller nodes are listed below. - - cmu: clock-controller@10030000 { - compatible = "samsung,exynos3250-cmu"; - reg = <0x10030000 0x20000>; - #clock-cells = <1>; - }; - - cmu_dmc: clock-controller@105c0000 { - compatible = "samsung,exynos3250-cmu-dmc"; - reg = <0x105C0000 0x2000>; - #clock-cells = <1>; - }; - - cmu_isp: clock-controller@10048000 { - compatible = "samsung,exynos3250-cmu-isp"; - reg = <0x10048000 0x1000>; - #clock-cells = <1>; - }; - -Example 2: UART controller node that consumes the clock generated by the clock - controller. Refer to the standard clock bindings for information - about 'clocks' and 'clock-names' property. - - serial@13800000 { - compatible = "samsung,exynos4210-uart"; - reg = <0x13800000 0x100>; - interrupts = <0 109 0>; - clocks = <&cmu CLK_UART0>, <&cmu CLK_SCLK_UART0>; - clock-names = "uart", "clk_uart_baud0"; - }; diff --git a/Documentation/devicetree/bindings/clock/exynos4-clock.txt b/Documentation/devicetree/bindings/clock/exynos4-clock.txt deleted file mode 100644 index 17bb11365354..000000000000 --- a/Documentation/devicetree/bindings/clock/exynos4-clock.txt +++ /dev/null @@ -1,86 +0,0 @@ -* Samsung Exynos4 Clock Controller - -The Exynos4 clock controller generates and supplies clock to various controllers -within the Exynos4 SoC. The clock binding described here is applicable to all -SoC's in the Exynos4 family. - -Required Properties: - -- compatible: should be one of the following. - - "samsung,exynos4210-clock" - controller compatible with Exynos4210 SoC. - - "samsung,exynos4412-clock" - controller compatible with Exynos4412 SoC. - -- reg: physical base address of the controller and length of memory mapped - region. - -- #clock-cells: should be 1. - -Each clock is assigned an identifier and client nodes can use this identifier -to specify the clock which they consume. - -All available clocks are defined as preprocessor macros in -dt-bindings/clock/exynos4.h header and can be used in device -tree sources. - -Example 1: An example of a clock controller node is listed below. - - clock: clock-controller@10030000 { - compatible = "samsung,exynos4210-clock"; - reg = <0x10030000 0x20000>; - #clock-cells = <1>; - }; - -Example 2: UART controller node that consumes the clock generated by the clock - controller. Refer to the standard clock bindings for information - about 'clocks' and 'clock-names' property. - - serial@13820000 { - compatible = "samsung,exynos4210-uart"; - reg = <0x13820000 0x100>; - interrupts = <0 54 0>; - clocks = <&clock CLK_UART2>, <&clock CLK_SCLK_UART2>; - clock-names = "uart", "clk_uart_baud0"; - }; - -Exynos4412 SoC contains some additional clocks for FIMC-ISP (Camera ISP) -subsystem. Registers for those clocks are located in the ISP power domain. -Because those registers are also located in a different memory region than -the main clock controller, a separate clock controller has to be defined for -handling them. - -Required Properties: - -- compatible: should be "samsung,exynos4412-isp-clock". - -- reg: physical base address of the ISP clock controller and length of memory - mapped region. - -- #clock-cells: should be 1. - -- clocks: list of the clock controller input clock identifiers, - from common clock bindings, should point to CLK_ACLK200 and - CLK_ACLK400_MCUISP clocks from the main clock controller. - -- clock-names: list of the clock controller input clock names, - as described in clock-bindings.txt, should be "aclk200" and - "aclk400_mcuisp". - -- power-domains: a phandle to ISP power domain node as described by - generic PM domain bindings. - -Example 3: The clock controllers bindings for Exynos4412 SoCs. - - clock: clock-controller@10030000 { - compatible = "samsung,exynos4412-clock"; - reg = <0x10030000 0x18000>; - #clock-cells = <1>; - }; - - isp_clock: clock-controller@10048000 { - compatible = "samsung,exynos4412-isp-clock"; - reg = <0x10048000 0x1000>; - #clock-cells = <1>; - power-domains = <&pd_isp>; - clocks = <&clock CLK_ACLK200>, <&clock CLK_ACLK400_MCUISP>; - clock-names = "aclk200", "aclk400_mcuisp"; - }; diff --git a/Documentation/devicetree/bindings/clock/exynos5250-clock.txt b/Documentation/devicetree/bindings/clock/exynos5250-clock.txt deleted file mode 100644 index aff266a12eeb..000000000000 --- a/Documentation/devicetree/bindings/clock/exynos5250-clock.txt +++ /dev/null @@ -1,41 +0,0 @@ -* Samsung Exynos5250 Clock Controller - -The Exynos5250 clock controller generates and supplies clock to various -controllers within the Exynos5250 SoC. - -Required Properties: - -- compatible: should be one of the following. - - "samsung,exynos5250-clock" - controller compatible with Exynos5250 SoC. - -- reg: physical base address of the controller and length of memory mapped - region. - -- #clock-cells: should be 1. - -Each clock is assigned an identifier and client nodes can use this identifier -to specify the clock which they consume. - -All available clocks are defined as preprocessor macros in -dt-bindings/clock/exynos5250.h header and can be used in device -tree sources. - -Example 1: An example of a clock controller node is listed below. - - clock: clock-controller@10010000 { - compatible = "samsung,exynos5250-clock"; - reg = <0x10010000 0x30000>; - #clock-cells = <1>; - }; - -Example 2: UART controller node that consumes the clock generated by the clock - controller. Refer to the standard clock bindings for information - about 'clocks' and 'clock-names' property. - - serial@13820000 { - compatible = "samsung,exynos4210-uart"; - reg = <0x13820000 0x100>; - interrupts = <0 54 0>; - clocks = <&clock CLK_UART2>, <&clock CLK_SCLK_UART2>; - clock-names = "uart", "clk_uart_baud0"; - }; diff --git a/Documentation/devicetree/bindings/clock/exynos5420-clock.txt b/Documentation/devicetree/bindings/clock/exynos5420-clock.txt deleted file mode 100644 index 717a7b1531c7..000000000000 --- a/Documentation/devicetree/bindings/clock/exynos5420-clock.txt +++ /dev/null @@ -1,42 +0,0 @@ -* Samsung Exynos5420 Clock Controller - -The Exynos5420 clock controller generates and supplies clock to various -controllers within the Exynos5420 SoC and for the Exynos5800 SoC. - -Required Properties: - -- compatible: should be one of the following. - - "samsung,exynos5420-clock" - controller compatible with Exynos5420 SoC. - - "samsung,exynos5800-clock" - controller compatible with Exynos5800 SoC. - -- reg: physical base address of the controller and length of memory mapped - region. - -- #clock-cells: should be 1. - -Each clock is assigned an identifier and client nodes can use this identifier -to specify the clock which they consume. - -All available clocks are defined as preprocessor macros in -dt-bindings/clock/exynos5420.h header and can be used in device -tree sources. - -Example 1: An example of a clock controller node is listed below. - - clock: clock-controller@10010000 { - compatible = "samsung,exynos5420-clock"; - reg = <0x10010000 0x30000>; - #clock-cells = <1>; - }; - -Example 2: UART controller node that consumes the clock generated by the clock - controller. Refer to the standard clock bindings for information - about 'clocks' and 'clock-names' property. - - serial@13820000 { - compatible = "samsung,exynos4210-uart"; - reg = <0x13820000 0x100>; - interrupts = <0 54 0>; - clocks = <&clock CLK_UART2>, <&clock CLK_SCLK_UART2>; - clock-names = "uart", "clk_uart_baud0"; - }; diff --git a/Documentation/devicetree/bindings/clock/idt,versaclock5.yaml b/Documentation/devicetree/bindings/clock/idt,versaclock5.yaml index 26ed040bc717..ffd6ae0eed64 100644 --- a/Documentation/devicetree/bindings/clock/idt,versaclock5.yaml +++ b/Documentation/devicetree/bindings/clock/idt,versaclock5.yaml @@ -30,6 +30,20 @@ description: | 3 -- OUT3 4 -- OUT4 + The idt,shutdown and idt,output-enable-active properties control the + SH (en_global_shutdown) and SP bits of the Primary Source and Shutdown + Register, respectively. Their behavior is summarized by the following + table: + + SH SP Output when the SD/OE pin is Low/High + == == ===================================== + 0 0 Active/Inactive + 0 1 Inactive/Active + 1 0 Active/Shutdown + 1 1 Inactive/Shutdown + + The case where SH and SP are both 1 is likely not very interesting. + maintainers: - Luca Ceresoli <luca@lucaceresoli.net> @@ -64,6 +78,26 @@ properties: maximum: 22760 description: Optional load capacitor for XTAL1 and XTAL2 + idt,shutdown: + $ref: /schemas/types.yaml#/definitions/uint32 + enum: [0, 1] + description: | + If 1, this enables the shutdown functionality: the chip will be + shut down if the SD/OE pin is driven high. If 0, this disables the + shutdown functionality: the chip will never be shut down based on + the value of the SD/OE pin. This property corresponds to the SH + bit of the Primary Source and Shutdown Register. + + idt,output-enable-active: + $ref: /schemas/types.yaml#/definitions/uint32 + enum: [0, 1] + description: | + If 1, this enables output when the SD/OE pin is high, and disables + output when the SD/OE pin is low. If 0, this disables output when + the SD/OE pin is high, and enables output when the SD/OE pin is + low. This corresponds to the SP bit of the Primary Source and + Shutdown Register. + patternProperties: "^OUT[1-4]$": type: object @@ -90,6 +124,8 @@ required: - compatible - reg - '#clock-cells' + - idt,shutdown + - idt,output-enable-active allOf: - if: @@ -139,6 +175,10 @@ examples: clocks = <&ref25m>; clock-names = "xin"; + /* Set the SD/OE pin's settings */ + idt,shutdown = <0>; + idt,output-enable-active = <0>; + OUT1 { idt,mode = <VC5_CMOSD>; idt,voltage-microvolt = <1800000>; diff --git a/Documentation/devicetree/bindings/clock/qcom,a53pll.yaml b/Documentation/devicetree/bindings/clock/qcom,a53pll.yaml index db3d0ea6bc7a..fbd758470b88 100644 --- a/Documentation/devicetree/bindings/clock/qcom,a53pll.yaml +++ b/Documentation/devicetree/bindings/clock/qcom,a53pll.yaml @@ -18,6 +18,7 @@ properties: enum: - qcom,ipq6018-a53pll - qcom,msm8916-a53pll + - qcom,msm8939-a53pll reg: maxItems: 1 @@ -33,6 +34,8 @@ properties: items: - const: xo + operating-points-v2: true + required: - compatible - reg diff --git a/Documentation/devicetree/bindings/clock/qcom,gcc-sm6115.yaml b/Documentation/devicetree/bindings/clock/qcom,gcc-sm6115.yaml new file mode 100644 index 000000000000..26050da844d5 --- /dev/null +++ b/Documentation/devicetree/bindings/clock/qcom,gcc-sm6115.yaml @@ -0,0 +1,72 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/clock/qcom,gcc-sm6115.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Qualcomm Global Clock & Reset Controller Binding for SM6115 and SM4250 + +maintainers: + - Iskren Chernev <iskren.chernev@gmail.com> + +description: | + Qualcomm global clock control module which supports the clocks, resets and + power domains on SM4250/6115. + + See also: + - dt-bindings/clock/qcom,gcc-sm6115.h + +properties: + compatible: + const: qcom,gcc-sm6115 + + 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' + +additionalProperties: false + +examples: + - | + #include <dt-bindings/clock/qcom,rpmcc.h> + clock-controller@1400000 { + compatible = "qcom,gcc-sm6115"; + reg = <0x01400000 0x1f0000>; + #clock-cells = <1>; + #reset-cells = <1>; + #power-domain-cells = <1>; + clock-names = "bi_tcxo", "sleep_clk"; + clocks = <&rpmcc RPM_SMD_XO_CLK_SRC>, <&sleep_clk>; + }; +... diff --git a/Documentation/devicetree/bindings/clock/qcom,gcc-sm6350.yaml b/Documentation/devicetree/bindings/clock/qcom,gcc-sm6350.yaml new file mode 100644 index 000000000000..20926cd8293e --- /dev/null +++ b/Documentation/devicetree/bindings/clock/qcom,gcc-sm6350.yaml @@ -0,0 +1,76 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/clock/qcom,gcc-sm6350.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Qualcomm Global Clock & Reset Controller Binding for SM6350 + +maintainers: + - Konrad Dybcio <konrad.dybcio@somainline.org> + +description: | + Qualcomm global clock control module which supports the clocks, resets and + power domains on SM6350. + + See also: + - dt-bindings/clock/qcom,gcc-sm6350.h + +properties: + compatible: + const: qcom,gcc-sm6350 + + 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' + +additionalProperties: false + +examples: + - | + #include <dt-bindings/clock/qcom,rpmh.h> + clock-controller@100000 { + compatible = "qcom,gcc-sm6350"; + reg = <0x00100000 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.yaml b/Documentation/devicetree/bindings/clock/qcom,gcc.yaml index 8453eeddf30e..2f20f8aa932a 100644 --- a/Documentation/devicetree/bindings/clock/qcom,gcc.yaml +++ b/Documentation/devicetree/bindings/clock/qcom,gcc.yaml @@ -23,6 +23,7 @@ description: | - 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-msm8939.h + - dt-bindings/clock/qcom,gcc-msm8953.h - dt-bindings/reset/qcom,gcc-msm8939.h - dt-bindings/clock/qcom,gcc-msm8660.h - dt-bindings/reset/qcom,gcc-msm8660.h @@ -46,6 +47,7 @@ properties: - qcom,gcc-msm8660 - qcom,gcc-msm8916 - qcom,gcc-msm8939 + - qcom,gcc-msm8953 - qcom,gcc-msm8960 - qcom,gcc-msm8974 - qcom,gcc-msm8974pro diff --git a/Documentation/devicetree/bindings/clock/qcom,gpucc.yaml b/Documentation/devicetree/bindings/clock/qcom,gpucc.yaml index df943c4c3234..46dff46d5760 100644 --- a/Documentation/devicetree/bindings/clock/qcom,gpucc.yaml +++ b/Documentation/devicetree/bindings/clock/qcom,gpucc.yaml @@ -1,4 +1,4 @@ -# SPDX-License-Identifier: GPL-2.0-only +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) %YAML 1.2 --- $id: http://devicetree.org/schemas/clock/qcom,gpucc.yaml# @@ -11,11 +11,12 @@ maintainers: description: | Qualcomm graphics clock control module which supports the clocks, resets and - power domains on SDM845/SC7180/SM8150/SM8250. + power domains on Qualcomm SoCs. See also: dt-bindings/clock/qcom,gpucc-sdm845.h dt-bindings/clock/qcom,gpucc-sc7180.h + dt-bindings/clock/qcom,gpucc-sc7280.h dt-bindings/clock/qcom,gpucc-sm8150.h dt-bindings/clock/qcom,gpucc-sm8250.h @@ -24,6 +25,8 @@ properties: enum: - qcom,sdm845-gpucc - qcom,sc7180-gpucc + - qcom,sc7280-gpucc + - qcom,sc8180x-gpucc - qcom,sm8150-gpucc - qcom,sm8250-gpucc diff --git a/Documentation/devicetree/bindings/clock/qcom,mmcc.yaml b/Documentation/devicetree/bindings/clock/qcom,mmcc.yaml index 8b0b1c56f354..68fdc3d4982a 100644 --- a/Documentation/devicetree/bindings/clock/qcom,mmcc.yaml +++ b/Documentation/devicetree/bindings/clock/qcom,mmcc.yaml @@ -22,6 +22,8 @@ properties: - qcom,mmcc-msm8660 - qcom,mmcc-msm8960 - qcom,mmcc-msm8974 + - qcom,mmcc-msm8992 + - qcom,mmcc-msm8994 - qcom,mmcc-msm8996 - qcom,mmcc-msm8998 - qcom,mmcc-sdm630 diff --git a/Documentation/devicetree/bindings/clock/qcom,rpmcc.txt b/Documentation/devicetree/bindings/clock/qcom,rpmcc.txt index 6cf5a7ec2b4c..a4877881f1d8 100644 --- a/Documentation/devicetree/bindings/clock/qcom,rpmcc.txt +++ b/Documentation/devicetree/bindings/clock/qcom,rpmcc.txt @@ -10,11 +10,13 @@ Required properties : - compatible : shall contain only one of the following. The generic compatible "qcom,rpmcc" should be also included. + "qcom,rpmcc-mdm9607", "qcom,rpmcc" "qcom,rpmcc-msm8660", "qcom,rpmcc" "qcom,rpmcc-apq8060", "qcom,rpmcc" "qcom,rpmcc-msm8226", "qcom,rpmcc" "qcom,rpmcc-msm8916", "qcom,rpmcc" "qcom,rpmcc-msm8936", "qcom,rpmcc" + "qcom,rpmcc-msm8953", "qcom,rpmcc" "qcom,rpmcc-msm8974", "qcom,rpmcc" "qcom,rpmcc-msm8976", "qcom,rpmcc" "qcom,rpmcc-apq8064", "qcom,rpmcc" @@ -25,6 +27,8 @@ Required properties : "qcom,rpmcc-msm8998", "qcom,rpmcc" "qcom,rpmcc-qcs404", "qcom,rpmcc" "qcom,rpmcc-sdm660", "qcom,rpmcc" + "qcom,rpmcc-sm6115", "qcom,rpmcc" + "qcom,rpmcc-sm6125", "qcom,rpmcc" - #clock-cells : shall contain 1 diff --git a/Documentation/devicetree/bindings/clock/qcom,rpmhcc.yaml b/Documentation/devicetree/bindings/clock/qcom,rpmhcc.yaml index 9ea0b3f5a4f2..72212970e6f5 100644 --- a/Documentation/devicetree/bindings/clock/qcom,rpmhcc.yaml +++ b/Documentation/devicetree/bindings/clock/qcom,rpmhcc.yaml @@ -22,6 +22,7 @@ properties: - qcom,sc8180x-rpmh-clk - qcom,sdm845-rpmh-clk - qcom,sdx55-rpmh-clk + - qcom,sm6350-rpmh-clk - qcom,sm8150-rpmh-clk - qcom,sm8250-rpmh-clk - qcom,sm8350-rpmh-clk diff --git a/Documentation/devicetree/bindings/clock/qcom,sc7280-dispcc.yaml b/Documentation/devicetree/bindings/clock/qcom,sc7280-dispcc.yaml new file mode 100644 index 000000000000..2178666fb697 --- /dev/null +++ b/Documentation/devicetree/bindings/clock/qcom,sc7280-dispcc.yaml @@ -0,0 +1,94 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/clock/qcom,sc7280-dispcc.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Qualcomm Display Clock & Reset Controller Binding for SC7280 + +maintainers: + - Taniya Das <tdas@codeaurora.org> + +description: | + Qualcomm display clock control module which supports the clocks, resets and + power domains on SC7280. + + See also dt-bindings/clock/qcom,dispcc-sc7280.h. + +properties: + compatible: + const: qcom,sc7280-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 + - description: Link clock from EDP PHY + - description: VCO DIV clock from EDP PHY + + clock-names: + items: + - const: bi_tcxo + - const: gcc_disp_gpll0_clk + - 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 + - const: edp_phy_pll_link_clk + - const: edp_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' + +additionalProperties: false + +examples: + - | + #include <dt-bindings/clock/qcom,gcc-sc7280.h> + #include <dt-bindings/clock/qcom,rpmh.h> + clock-controller@af00000 { + compatible = "qcom,sc7280-dispcc"; + reg = <0x0af00000 0x200000>; + clocks = <&rpmhcc RPMH_CXO_CLK>, + <&gcc GCC_DISP_GPLL0_CLK_SRC>, + <&dsi_phy 0>, + <&dsi_phy 1>, + <&dp_phy 0>, + <&dp_phy 1>, + <&edp_phy 0>, + <&edp_phy 1>; + clock-names = "bi_tcxo", + "gcc_disp_gpll0_clk", + "dsi0_phy_pll_out_byteclk", + "dsi0_phy_pll_out_dsiclk", + "dp_phy_pll_link_clk", + "dp_phy_pll_vco_div_clk", + "edp_phy_pll_link_clk", + "edp_phy_pll_vco_div_clk"; + #clock-cells = <1>; + #reset-cells = <1>; + #power-domain-cells = <1>; + }; +... diff --git a/Documentation/devicetree/bindings/clock/qcom,videocc.yaml b/Documentation/devicetree/bindings/clock/qcom,videocc.yaml index 567202942b88..0d224f114b5b 100644 --- a/Documentation/devicetree/bindings/clock/qcom,videocc.yaml +++ b/Documentation/devicetree/bindings/clock/qcom,videocc.yaml @@ -1,4 +1,4 @@ -# SPDX-License-Identifier: GPL-2.0-only +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) %YAML 1.2 --- $id: http://devicetree.org/schemas/clock/qcom,videocc.yaml# @@ -11,10 +11,11 @@ maintainers: description: | Qualcomm video clock control module which supports the clocks, resets and - power domains on SDM845/SC7180/SM8150/SM8250. + power domains on Qualcomm SoCs. See also: dt-bindings/clock/qcom,videocc-sc7180.h + dt-bindings/clock/qcom,videocc-sc7280.h dt-bindings/clock/qcom,videocc-sdm845.h dt-bindings/clock/qcom,videocc-sm8150.h dt-bindings/clock/qcom,videocc-sm8250.h @@ -23,6 +24,7 @@ properties: compatible: enum: - qcom,sc7180-videocc + - qcom,sc7280-videocc - qcom,sdm845-videocc - qcom,sm8150-videocc - qcom,sm8250-videocc diff --git a/Documentation/devicetree/bindings/clock/rockchip,rk3399-cru.txt b/Documentation/devicetree/bindings/clock/rockchip,rk3399-cru.txt deleted file mode 100644 index 3bc56fae90ac..000000000000 --- a/Documentation/devicetree/bindings/clock/rockchip,rk3399-cru.txt +++ /dev/null @@ -1,68 +0,0 @@ -* Rockchip RK3399 Clock and Reset Unit - -The RK3399 clock controller generates and supplies clock to various -controllers within the SoC and also implements a reset controller for SoC -peripherals. - -Required Properties: - -- compatible: PMU for CRU should be "rockchip,rk3399-pmucru" -- compatible: CRU should be "rockchip,rk3399-cru" -- reg: physical base address of the controller and length of memory mapped - region. -- #clock-cells: should be 1. -- #reset-cells: should be 1. - -Optional Properties: - -- rockchip,grf: phandle to the syscon managing the "general register files". - It is used for GRF muxes, if missing any muxes present in the GRF will not - be available. - -Each clock is assigned an identifier and client nodes can use this identifier -to specify the clock which they consume. All available clocks are defined as -preprocessor macros in the dt-bindings/clock/rk3399-cru.h headers and can be -used in device tree sources. Similar macros exist for the reset sources in -these files. - -External clocks: - -There are several clocks that are generated outside the SoC. It is expected -that they are defined using standard clock bindings with following -clock-output-names: - - "xin24m" - crystal input - required, - - "xin32k" - rtc clock - optional, - - "clkin_gmac" - external GMAC clock - optional, - - "clkin_i2s" - external I2S clock - optional, - - "pclkin_cif" - external ISP clock - optional, - - "clk_usbphy0_480m" - output clock of the pll in the usbphy0 - - "clk_usbphy1_480m" - output clock of the pll in the usbphy1 - -Example: Clock controller node: - - pmucru: pmu-clock-controller@ff750000 { - compatible = "rockchip,rk3399-pmucru"; - reg = <0x0 0xff750000 0x0 0x1000>; - #clock-cells = <1>; - #reset-cells = <1>; - }; - - cru: clock-controller@ff760000 { - compatible = "rockchip,rk3399-cru"; - reg = <0x0 0xff760000 0x0 0x1000>; - #clock-cells = <1>; - #reset-cells = <1>; - }; - -Example: UART controller node that consumes the clock generated by the clock - controller: - - uart0: serial@ff1a0000 { - compatible = "rockchip,rk3399-uart", "snps,dw-apb-uart"; - reg = <0x0 0xff180000 0x0 0x100>; - clocks = <&cru SCLK_UART0>, <&cru PCLK_UART0>; - clock-names = "baudclk", "apb_pclk"; - interrupts = <GIC_SPI 99 IRQ_TYPE_LEVEL_HIGH>; - reg-shift = <2>; - reg-io-width = <4>; - }; diff --git a/Documentation/devicetree/bindings/clock/rockchip,rk3399-cru.yaml b/Documentation/devicetree/bindings/clock/rockchip,rk3399-cru.yaml new file mode 100644 index 000000000000..72b286a1beba --- /dev/null +++ b/Documentation/devicetree/bindings/clock/rockchip,rk3399-cru.yaml @@ -0,0 +1,92 @@ +# SPDX-License-Identifier: GPL-2.0-only +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/clock/rockchip,rk3399-cru.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Rockchip RK3399 Clock and Reset Unit + +maintainers: + - Xing Zheng <zhengxing@rock-chips.com> + - Heiko Stuebner <heiko@sntech.de> + +description: | + The RK3399 clock controller generates and supplies clock to various + controllers within the SoC and also implements a reset controller for SoC + peripherals. + Each clock is assigned an identifier and client nodes can use this identifier + to specify the clock which they consume. All available clocks are defined as + preprocessor macros in the dt-bindings/clock/rk3399-cru.h headers and can be + used in device tree sources. Similar macros exist for the reset sources in + these files. + There are several clocks that are generated outside the SoC. It is expected + that they are defined using standard clock bindings with following + clock-output-names: + - "xin24m" - crystal input - required, + - "xin32k" - rtc clock - optional, + - "clkin_gmac" - external GMAC clock - optional, + - "clkin_i2s" - external I2S clock - optional, + - "pclkin_cif" - external ISP clock - optional, + - "clk_usbphy0_480m" - output clock of the pll in the usbphy0 + - "clk_usbphy1_480m" - output clock of the pll in the usbphy1 + +properties: + compatible: + enum: + - rockchip,rk3399-pmucru + - rockchip,rk3399-cru + + reg: + maxItems: 1 + + "#clock-cells": + const: 1 + + "#reset-cells": + const: 1 + + clocks: + minItems: 1 + + assigned-clocks: + minItems: 1 + maxItems: 64 + + assigned-clock-parents: + minItems: 1 + maxItems: 64 + + assigned-clock-rates: + minItems: 1 + maxItems: 64 + + rockchip,grf: + $ref: /schemas/types.yaml#/definitions/phandle + description: > + phandle to the syscon managing the "general register files". It is used + for GRF muxes, if missing any muxes present in the GRF will not be + available. + +required: + - compatible + - reg + - "#clock-cells" + - "#reset-cells" + +additionalProperties: false + +examples: + - | + pmucru: pmu-clock-controller@ff750000 { + compatible = "rockchip,rk3399-pmucru"; + reg = <0xff750000 0x1000>; + #clock-cells = <1>; + #reset-cells = <1>; + }; + - | + cru: clock-controller@ff760000 { + compatible = "rockchip,rk3399-cru"; + reg = <0xff760000 0x1000>; + #clock-cells = <1>; + #reset-cells = <1>; + }; diff --git a/Documentation/devicetree/bindings/clock/samsung,exynos-audss-clock.yaml b/Documentation/devicetree/bindings/clock/samsung,exynos-audss-clock.yaml new file mode 100644 index 000000000000..f14f1d39da36 --- /dev/null +++ b/Documentation/devicetree/bindings/clock/samsung,exynos-audss-clock.yaml @@ -0,0 +1,80 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/clock/samsung,exynos-audss-clock.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Samsung Exynos SoC Audio SubSystem clock controller + +maintainers: + - Chanwoo Choi <cw00.choi@samsung.com> + - Krzysztof Kozlowski <krzysztof.kozlowski@canonical.com> + - Sylwester Nawrocki <s.nawrocki@samsung.com> + - Tomasz Figa <tomasz.figa@gmail.com> + +description: | + All available clocks are defined as preprocessor macros in + include/dt-bindings/clock/exynos-audss-clk.h header. + +properties: + compatible: + enum: + - samsung,exynos4210-audss-clock + - samsung,exynos5250-audss-clock + - samsung,exynos5410-audss-clock + - samsung,exynos5420-audss-clock + + clocks: + minItems: 2 + items: + - description: + Fixed rate PLL reference clock, parent of mout_audss. "fin_pll" is + used if not specified. + - description: + Input PLL to the AudioSS block, parent of mout_audss. "fout_epll" is + used if not specified. + - description: + Audio bus clock, parent of mout_i2s. "sclk_audio0" is used if not + specified. + - description: + PCM clock, parent of sclk_pcm. "sclk_pcm0" is used if not specified. + - description: + External i2s clock, parent of mout_i2s. "cdclk0" is used if not + specified. + + clock-names: + minItems: 2 + items: + - const: pll_ref + - const: pll_in + - const: sclk_audio + - const: sclk_pcm_in + - const: cdclk + + "#clock-cells": + const: 1 + + power-domains: + maxItems: 1 + + reg: + maxItems: 1 + +required: + - compatible + - clocks + - clock-names + - "#clock-cells" + - reg + +additionalProperties: false + +examples: + - | + clock-controller@3810000 { + compatible = "samsung,exynos5250-audss-clock"; + reg = <0x03810000 0x0c>; + #clock-cells = <1>; + clocks = <&clock 1>, <&clock 7>, <&clock 138>, <&clock 160>, <&ext_i2s_clk>; + clock-names = "pll_ref", "pll_in", "sclk_audio", "sclk_pcm_in", "cdclk"; + }; diff --git a/Documentation/devicetree/bindings/clock/samsung,exynos-clock.yaml b/Documentation/devicetree/bindings/clock/samsung,exynos-clock.yaml new file mode 100644 index 000000000000..4e8062860986 --- /dev/null +++ b/Documentation/devicetree/bindings/clock/samsung,exynos-clock.yaml @@ -0,0 +1,59 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/clock/samsung,exynos-clock.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Samsung Exynos SoC clock controller + +maintainers: + - Chanwoo Choi <cw00.choi@samsung.com> + - Krzysztof Kozlowski <krzysztof.kozlowski@canonical.com> + - Sylwester Nawrocki <s.nawrocki@samsung.com> + - Tomasz Figa <tomasz.figa@gmail.com> + +description: | + All available clocks are defined as preprocessor macros in + dt-bindings/clock/ headers. + +properties: + compatible: + oneOf: + - enum: + - samsung,exynos3250-cmu + - samsung,exynos3250-cmu-dmc + - samsung,exynos3250-cmu-isp + - samsung,exynos4210-clock + - samsung,exynos4412-clock + - samsung,exynos5250-clock + - items: + - enum: + - samsung,exynos5420-clock + - samsung,exynos5800-clock + - const: syscon + + clocks: + minItems: 1 + maxItems: 4 + + "#clock-cells": + const: 1 + + reg: + maxItems: 1 + +required: + - compatible + - "#clock-cells" + - reg + +additionalProperties: false + +examples: + - | + #include <dt-bindings/clock/exynos5250.h> + clock: clock-controller@10010000 { + compatible = "samsung,exynos5250-clock"; + reg = <0x10010000 0x30000>; + #clock-cells = <1>; + }; diff --git a/Documentation/devicetree/bindings/clock/samsung,exynos-ext-clock.yaml b/Documentation/devicetree/bindings/clock/samsung,exynos-ext-clock.yaml new file mode 100644 index 000000000000..64d027dbe3b2 --- /dev/null +++ b/Documentation/devicetree/bindings/clock/samsung,exynos-ext-clock.yaml @@ -0,0 +1,46 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/clock/samsung,exynos-ext-clock.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Samsung SoC external/osc/XXTI/XusbXTI clock + +maintainers: + - Chanwoo Choi <cw00.choi@samsung.com> + - Krzysztof Kozlowski <krzysztof.kozlowski@canonical.com> + - Sylwester Nawrocki <s.nawrocki@samsung.com> + - Tomasz Figa <tomasz.figa@gmail.com> + +description: | + Samsung SoCs require an external clock supplied through XXTI or XusbXTI pins. + +properties: + compatible: + enum: + - samsung,clock-xxti + - samsung,clock-xusbxti + - samsung,exynos5420-oscclk + + "#clock-cells": + const: 0 + + clock-frequency: true + + clock-output-names: + maxItems: 1 + +required: + - compatible + - clock-frequency + +additionalProperties: false + +examples: + - | + fixed-rate-clocks { + clock { + compatible = "samsung,clock-xxti"; + clock-frequency = <24000000>; + }; + }; diff --git a/Documentation/devicetree/bindings/clock/samsung,exynos4412-isp-clock.yaml b/Documentation/devicetree/bindings/clock/samsung,exynos4412-isp-clock.yaml new file mode 100644 index 000000000000..1ed64add4355 --- /dev/null +++ b/Documentation/devicetree/bindings/clock/samsung,exynos4412-isp-clock.yaml @@ -0,0 +1,64 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/clock/samsung,exynos4412-isp-clock.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Samsung Exynos4412 SoC ISP clock controller + +maintainers: + - Chanwoo Choi <cw00.choi@samsung.com> + - Krzysztof Kozlowski <krzysztof.kozlowski@canonical.com> + - Sylwester Nawrocki <s.nawrocki@samsung.com> + - Tomasz Figa <tomasz.figa@gmail.com> + +description: | + Clock controller for Samsung Exynos4412 SoC FIMC-ISP (Camera ISP) + All available clocks are defined as preprocessor macros in + dt-bindings/clock/ headers. + +properties: + compatible: + const: samsung,exynos4412-isp-clock + + clocks: + items: + - description: CLK_ACLK200 from the main clock controller + - description: CLK_ACLK400_MCUISP from the main clock controller + + clock-names: + items: + - const: aclk200 + - const: aclk400_mcuisp + + "#clock-cells": + const: 1 + + power-domains: + maxItems: 1 + + reg: + maxItems: 1 + +required: + - compatible + - "#clock-cells" + - clocks + - clock-names + - power-domains + - reg + +additionalProperties: false + +examples: + - | + #include <dt-bindings/clock/exynos4.h> + clock-controller@10048000 { + compatible = "samsung,exynos4412-isp-clock"; + reg = <0x10048000 0x1000>; + #clock-cells = <1>; + power-domains = <&pd_isp>; + clocks = <&clock CLK_ACLK200>, <&clock CLK_ACLK400_MCUISP>; + clock-names = "aclk200", "aclk400_mcuisp"; + }; + diff --git a/Documentation/devicetree/bindings/clock/samsung,s5pv210-audss-clock.yaml b/Documentation/devicetree/bindings/clock/samsung,s5pv210-audss-clock.yaml new file mode 100644 index 000000000000..ae8f8fc93233 --- /dev/null +++ b/Documentation/devicetree/bindings/clock/samsung,s5pv210-audss-clock.yaml @@ -0,0 +1,78 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/clock/samsung,s5pv210-audss-clock.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Samsung S5Pv210 SoC Audio SubSystem clock controller + +maintainers: + - Chanwoo Choi <cw00.choi@samsung.com> + - Krzysztof Kozlowski <krzysztof.kozlowski@canonical.com> + - Sylwester Nawrocki <s.nawrocki@samsung.com> + - Tomasz Figa <tomasz.figa@gmail.com> + +description: | + All available clocks are defined as preprocessor macros in + include/dt-bindings/clock/s5pv210-audss.h header. + +properties: + compatible: + const: samsung,s5pv210-audss-clock + + clocks: + minItems: 4 + items: + - description: + AHB bus clock of the Audio Subsystem. + - description: + Optional fixed rate PLL reference clock, parent of mout_audss. If not + specified (i.e. xusbxti is used for PLL reference), it is fixed to a + clock named "xxti". + - description: + Input PLL to the AudioSS block, parent of mout_audss. + - description: + Audio bus clock, parent of mout_i2s. + - description: + Optional external i2s clock, parent of mout_i2s. If not specified, it + is fixed to a clock named "iiscdclk0". + + clock-names: + minItems: 4 + items: + - const: hclk + - const: xxti + - const: fout_epll + - const: sclk_audio0 + - const: iiscdclk0 + + "#clock-cells": + const: 1 + + power-domains: + maxItems: 1 + + reg: + maxItems: 1 + +required: + - compatible + - clocks + - clock-names + - "#clock-cells" + - reg + +additionalProperties: false + +examples: + - | + #include <dt-bindings/clock/s5pv210.h> + + clock-controller@c0900000 { + compatible = "samsung,s5pv210-audss-clock"; + reg = <0xc0900000 0x1000>; + #clock-cells = <1>; + clock-names = "hclk", "xxti", "fout_epll", "sclk_audio0"; + clocks = <&clocks DOUT_HCLKP>, <&xxti>, <&clocks FOUT_EPLL>, + <&clocks SCLK_AUDIO0>; + }; diff --git a/Documentation/devicetree/bindings/connector/usb-connector.yaml b/Documentation/devicetree/bindings/connector/usb-connector.yaml index 92b49bc37939..7eb8659fa610 100644 --- a/Documentation/devicetree/bindings/connector/usb-connector.yaml +++ b/Documentation/devicetree/bindings/connector/usb-connector.yaml @@ -111,6 +111,10 @@ properties: - 1.5A - 3.0A + pd-disable: + description: Set this property if the Type-C connector has no power delivery support. + type: boolean + # The following are optional properties for "usb-c-connector" with power # delivery support. source-pdos: diff --git a/Documentation/devicetree/bindings/devfreq/event/exynos-nocp.txt b/Documentation/devicetree/bindings/devfreq/event/exynos-nocp.txt deleted file mode 100644 index aeaebd425d1f..000000000000 --- a/Documentation/devicetree/bindings/devfreq/event/exynos-nocp.txt +++ /dev/null @@ -1,26 +0,0 @@ - -* Samsung Exynos NoC (Network on Chip) Probe device - -The Samsung Exynos542x SoC has NoC (Network on Chip) Probe for NoC bus. -NoC provides the primitive values to get the performance data. The packets -that the Network on Chip (NoC) probes detects are transported over -the network infrastructure to observer units. You can configure probes to -capture packets with header or data on the data request response network, -or as traffic debug or statistic collectors. Exynos542x bus has multiple -NoC probes to provide bandwidth information about behavior of the SoC -that you can use while analyzing system performance. - -Required properties: -- compatible: Should be "samsung,exynos5420-nocp" -- reg: physical base address of each NoC Probe and length of memory mapped region. - -Optional properties: -- clock-names : the name of clock used by the NoC Probe, "nocp" -- clocks : phandles for clock specified in "clock-names" property - -Example : NoC Probe nodes in Device Tree are listed below. - - nocp_mem0_0: nocp@10ca1000 { - compatible = "samsung,exynos5420-nocp"; - reg = <0x10CA1000 0x200>; - }; diff --git a/Documentation/devicetree/bindings/devfreq/event/exynos-ppmu.txt b/Documentation/devicetree/bindings/devfreq/event/exynos-ppmu.txt deleted file mode 100644 index fb46b491791c..000000000000 --- a/Documentation/devicetree/bindings/devfreq/event/exynos-ppmu.txt +++ /dev/null @@ -1,169 +0,0 @@ - -* Samsung Exynos PPMU (Platform Performance Monitoring Unit) device - -The Samsung Exynos SoC has PPMU (Platform Performance Monitoring Unit) for -each IP. PPMU provides the primitive values to get performance data. These -PPMU events provide information of the SoC's behaviors so that you may -use to analyze system performance, to make behaviors visible and to count -usages of each IP (DMC, CPU, RIGHTBUS, LEFTBUS, CAM interface, LCD, G3D, MFC). -The Exynos PPMU driver uses the devfreq-event class to provide event data -to various devfreq devices. The devfreq devices would use the event data when -derterming the current state of each IP. - -Required properties for PPMU device: -- compatible: Should be "samsung,exynos-ppmu" or "samsung,exynos-ppmu-v2. -- reg: physical base address of each PPMU and length of memory mapped region. - -Optional properties for PPMU device: -- clock-names : the name of clock used by the PPMU, "ppmu" -- clocks : phandles for clock specified in "clock-names" property - -Required properties for 'events' child node of PPMU device: -- event-name : the unique event name among PPMU device -Optional properties for 'events' child node of PPMU device: -- event-data-type : Define the type of data which shell be counted -by the counter. You can check include/dt-bindings/pmu/exynos_ppmu.h for -all possible type, i.e. count read requests, count write data in bytes, -etc. This field is optional and when it is missing, the driver code -will use default data type. - -Example1 : PPMUv1 nodes in exynos3250.dtsi are listed below. - - ppmu_dmc0: ppmu_dmc0@106a0000 { - compatible = "samsung,exynos-ppmu"; - reg = <0x106a0000 0x2000>; - status = "disabled"; - }; - - ppmu_dmc1: ppmu_dmc1@106b0000 { - compatible = "samsung,exynos-ppmu"; - reg = <0x106b0000 0x2000>; - status = "disabled"; - }; - - ppmu_cpu: ppmu_cpu@106c0000 { - compatible = "samsung,exynos-ppmu"; - reg = <0x106c0000 0x2000>; - status = "disabled"; - }; - - ppmu_rightbus: ppmu_rightbus@112a0000 { - compatible = "samsung,exynos-ppmu"; - reg = <0x112a0000 0x2000>; - clocks = <&cmu CLK_PPMURIGHT>; - clock-names = "ppmu"; - status = "disabled"; - }; - - ppmu_leftbus: ppmu_leftbus0@116a0000 { - compatible = "samsung,exynos-ppmu"; - reg = <0x116a0000 0x2000>; - clocks = <&cmu CLK_PPMULEFT>; - clock-names = "ppmu"; - status = "disabled"; - }; - -Example2 : Events of each PPMU node in exynos3250-rinato.dts are listed below. - - &ppmu_dmc0 { - status = "okay"; - - events { - ppmu_dmc0_3: ppmu-event3-dmc0 { - event-name = "ppmu-event3-dmc0"; - }; - - ppmu_dmc0_2: ppmu-event2-dmc0 { - event-name = "ppmu-event2-dmc0"; - }; - - ppmu_dmc0_1: ppmu-event1-dmc0 { - event-name = "ppmu-event1-dmc0"; - }; - - ppmu_dmc0_0: ppmu-event0-dmc0 { - event-name = "ppmu-event0-dmc0"; - }; - }; - }; - - &ppmu_dmc1 { - status = "okay"; - - events { - ppmu_dmc1_3: ppmu-event3-dmc1 { - event-name = "ppmu-event3-dmc1"; - }; - }; - }; - - &ppmu_leftbus { - status = "okay"; - - events { - ppmu_leftbus_3: ppmu-event3-leftbus { - event-name = "ppmu-event3-leftbus"; - }; - }; - }; - - &ppmu_rightbus { - status = "okay"; - - events { - ppmu_rightbus_3: ppmu-event3-rightbus { - event-name = "ppmu-event3-rightbus"; - }; - }; - }; - -Example3 : PPMUv2 nodes in exynos5433.dtsi are listed below. - - ppmu_d0_cpu: ppmu_d0_cpu@10480000 { - compatible = "samsung,exynos-ppmu-v2"; - reg = <0x10480000 0x2000>; - status = "disabled"; - }; - - ppmu_d0_general: ppmu_d0_general@10490000 { - compatible = "samsung,exynos-ppmu-v2"; - reg = <0x10490000 0x2000>; - status = "disabled"; - }; - - ppmu_d0_rt: ppmu_d0_rt@104a0000 { - compatible = "samsung,exynos-ppmu-v2"; - reg = <0x104a0000 0x2000>; - status = "disabled"; - }; - - ppmu_d1_cpu: ppmu_d1_cpu@104b0000 { - compatible = "samsung,exynos-ppmu-v2"; - reg = <0x104b0000 0x2000>; - status = "disabled"; - }; - - ppmu_d1_general: ppmu_d1_general@104c0000 { - compatible = "samsung,exynos-ppmu-v2"; - reg = <0x104c0000 0x2000>; - status = "disabled"; - }; - - ppmu_d1_rt: ppmu_d1_rt@104d0000 { - compatible = "samsung,exynos-ppmu-v2"; - reg = <0x104d0000 0x2000>; - status = "disabled"; - }; - -Example4 : 'event-data-type' in exynos4412-ppmu-common.dtsi are listed below. - - &ppmu_dmc0 { - status = "okay"; - events { - ppmu_dmc0_3: ppmu-event3-dmc0 { - event-name = "ppmu-event3-dmc0"; - event-data-type = <(PPMU_RO_DATA_CNT | - PPMU_WO_DATA_CNT)>; - }; - }; - }; diff --git a/Documentation/devicetree/bindings/devfreq/event/samsung,exynos-nocp.yaml b/Documentation/devicetree/bindings/devfreq/event/samsung,exynos-nocp.yaml new file mode 100644 index 000000000000..d318fccf78f1 --- /dev/null +++ b/Documentation/devicetree/bindings/devfreq/event/samsung,exynos-nocp.yaml @@ -0,0 +1,48 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/devfreq/event/samsung,exynos-nocp.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Samsung Exynos NoC (Network on Chip) Probe + +maintainers: + - Chanwoo Choi <cw00.choi@samsung.com> + - Krzysztof Kozlowski <krzysztof.kozlowski@canonical.com> + +description: | + The Samsung Exynos542x SoC has a NoC (Network on Chip) Probe for NoC bus. + NoC provides the primitive values to get the performance data. The packets + that the Network on Chip (NoC) probes detects are transported over the + network infrastructure to observer units. You can configure probes to capture + packets with header or data on the data request response network, or as + traffic debug or statistic collectors. Exynos542x bus has multiple NoC probes + to provide bandwidth information about behavior of the SoC that you can use + while analyzing system performance. + +properties: + compatible: + const: samsung,exynos5420-nocp + + clock-names: + items: + - const: nocp + + clocks: + maxItems: 1 + + reg: + maxItems: 1 + +required: + - compatible + - reg + +additionalProperties: false + +examples: + - | + nocp_mem0_0: nocp@10ca1000 { + compatible = "samsung,exynos5420-nocp"; + reg = <0x10ca1000 0x200>; + }; diff --git a/Documentation/devicetree/bindings/devfreq/event/samsung,exynos-ppmu.yaml b/Documentation/devicetree/bindings/devfreq/event/samsung,exynos-ppmu.yaml new file mode 100644 index 000000000000..c9a8cb5fd555 --- /dev/null +++ b/Documentation/devicetree/bindings/devfreq/event/samsung,exynos-ppmu.yaml @@ -0,0 +1,169 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/devfreq/event/samsung,exynos-ppmu.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Samsung Exynos SoC PPMU (Platform Performance Monitoring Unit) + +maintainers: + - Chanwoo Choi <cw00.choi@samsung.com> + - Krzysztof Kozlowski <krzysztof.kozlowski@canonical.com> + +description: | + The Samsung Exynos SoC has PPMU (Platform Performance Monitoring Unit) for + each IP. PPMU provides the primitive values to get performance data. These + PPMU events provide information of the SoC's behaviors so that you may use to + analyze system performance, to make behaviors visible and to count usages of + each IP (DMC, CPU, RIGHTBUS, LEFTBUS, CAM interface, LCD, G3D, MFC). The + Exynos PPMU driver uses the devfreq-event class to provide event data to + various devfreq devices. The devfreq devices would use the event data when + derterming the current state of each IP. + +properties: + compatible: + enum: + - samsung,exynos-ppmu + - samsung,exynos-ppmu-v2 + + clock-names: + items: + - const: ppmu + + clocks: + maxItems: 1 + + reg: + maxItems: 1 + + events: + type: object + + patternProperties: + '^ppmu-event[0-9]+(-[a-z0-9]+){,2}$': + type: object + properties: + event-name: + description: | + The unique event name among PPMU device + $ref: /schemas/types.yaml#/definitions/string + + event-data-type: + description: | + Define the type of data which shell be counted by the counter. + You can check include/dt-bindings/pmu/exynos_ppmu.h for all + possible type, i.e. count read requests, count write data in + bytes, etc. This field is optional and when it is missing, the + driver code will use default data type. + $ref: /schemas/types.yaml#/definitions/uint32 + + required: + - event-name + + additionalProperties: false + + additionalProperties: false + +required: + - compatible + - reg + +additionalProperties: false + +examples: + - | + // PPMUv1 nodes for Exynos3250 (although the board DTS defines events) + #include <dt-bindings/clock/exynos3250.h> + + ppmu_dmc0: ppmu@106a0000 { + compatible = "samsung,exynos-ppmu"; + reg = <0x106a0000 0x2000>; + + events { + ppmu_dmc0_3: ppmu-event3-dmc0 { + event-name = "ppmu-event3-dmc0"; + }; + + ppmu_dmc0_2: ppmu-event2-dmc0 { + event-name = "ppmu-event2-dmc0"; + }; + + ppmu_dmc0_1: ppmu-event1-dmc0 { + event-name = "ppmu-event1-dmc0"; + }; + + ppmu_dmc0_0: ppmu-event0-dmc0 { + event-name = "ppmu-event0-dmc0"; + }; + }; + }; + + ppmu_rightbus: ppmu@112a0000 { + compatible = "samsung,exynos-ppmu"; + reg = <0x112a0000 0x2000>; + clocks = <&cmu CLK_PPMURIGHT>; + clock-names = "ppmu"; + + events { + ppmu_rightbus_3: ppmu-event3-rightbus { + event-name = "ppmu-event3-rightbus"; + }; + }; + }; + + - | + // PPMUv2 nodes in Exynos5433 + ppmu_d0_cpu: ppmu@10480000 { + compatible = "samsung,exynos-ppmu-v2"; + reg = <0x10480000 0x2000>; + }; + + ppmu_d0_general: ppmu@10490000 { + compatible = "samsung,exynos-ppmu-v2"; + reg = <0x10490000 0x2000>; + + events { + ppmu_event0_d0_general: ppmu-event0-d0-general { + event-name = "ppmu-event0-d0-general"; + }; + }; + }; + + ppmu_d0_rt: ppmu@104a0000 { + compatible = "samsung,exynos-ppmu-v2"; + reg = <0x104a0000 0x2000>; + }; + + ppmu_d1_cpu: ppmu@104b0000 { + compatible = "samsung,exynos-ppmu-v2"; + reg = <0x104b0000 0x2000>; + }; + + ppmu_d1_general: ppmu@104c0000 { + compatible = "samsung,exynos-ppmu-v2"; + reg = <0x104c0000 0x2000>; + }; + + ppmu_d1_rt: ppmu@104d0000 { + compatible = "samsung,exynos-ppmu-v2"; + reg = <0x104d0000 0x2000>; + }; + + - | + // PPMUv1 nodes with event-data-type for Exynos4412 + #include <dt-bindings/pmu/exynos_ppmu.h> + + ppmu@106a0000 { + compatible = "samsung,exynos-ppmu"; + reg = <0x106a0000 0x2000>; + clocks = <&clock 400>; + clock-names = "ppmu"; + + events { + ppmu-event3-dmc0 { + event-name = "ppmu-event3-dmc0"; + event-data-type = <(PPMU_RO_DATA_CNT | + PPMU_WO_DATA_CNT)>; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/display/allwinner,sun8i-a83t-dw-hdmi.yaml b/Documentation/devicetree/bindings/display/allwinner,sun8i-a83t-dw-hdmi.yaml index 5d42d36608d9..4951b5ef5c6a 100644 --- a/Documentation/devicetree/bindings/display/allwinner,sun8i-a83t-dw-hdmi.yaml +++ b/Documentation/devicetree/bindings/display/allwinner,sun8i-a83t-dw-hdmi.yaml @@ -174,7 +174,6 @@ examples: phy-names = "phy"; pinctrl-names = "default"; pinctrl-0 = <&hdmi_pins>; - status = "disabled"; ports { #address-cells = <1>; @@ -233,7 +232,6 @@ examples: phy-names = "phy"; pinctrl-names = "default"; pinctrl-0 = <&hdmi_pins>; - status = "disabled"; ports { #address-cells = <1>; diff --git a/Documentation/devicetree/bindings/display/bridge/simple-bridge.yaml b/Documentation/devicetree/bindings/display/bridge/simple-bridge.yaml index 6c7b577fd471..43cf4df9811a 100644 --- a/Documentation/devicetree/bindings/display/bridge/simple-bridge.yaml +++ b/Documentation/devicetree/bindings/display/bridge/simple-bridge.yaml @@ -22,6 +22,9 @@ properties: - ti,ths8134a - ti,ths8134b - const: ti,ths8134 + - items: + - const: corpro,gm7123 + - const: adi,adv7123 - enum: - adi,adv7123 - dumb-vga-dac diff --git a/Documentation/devicetree/bindings/display/bridge/ti,sn65dsi83.yaml b/Documentation/devicetree/bindings/display/bridge/ti,sn65dsi83.yaml index d101233ae17f..07b20383cbca 100644 --- a/Documentation/devicetree/bindings/display/bridge/ti,sn65dsi83.yaml +++ b/Documentation/devicetree/bindings/display/bridge/ti,sn65dsi83.yaml @@ -37,7 +37,8 @@ properties: properties: port@0: - $ref: /schemas/graph.yaml#/properties/port + $ref: /schemas/graph.yaml#/$defs/port-base + unevaluatedProperties: false description: Video port for MIPI DSI Channel-A input properties: @@ -57,7 +58,8 @@ properties: - const: 4 port@1: - $ref: /schemas/graph.yaml#/properties/port + $ref: /schemas/graph.yaml#/$defs/port-base + unevaluatedProperties: false description: Video port for MIPI DSI Channel-B input properties: diff --git a/Documentation/devicetree/bindings/display/bridge/ti,sn65dsi86.yaml b/Documentation/devicetree/bindings/display/bridge/ti,sn65dsi86.yaml index 26932d2e86ab..1c2daf7c24cc 100644 --- a/Documentation/devicetree/bindings/display/bridge/ti,sn65dsi86.yaml +++ b/Documentation/devicetree/bindings/display/bridge/ti,sn65dsi86.yaml @@ -70,6 +70,9 @@ properties: const: 1 description: See ../../pwm/pwm.yaml for description of the cell formats. + aux-bus: + $ref: /schemas/display/dp-aux-bus.yaml# + ports: $ref: /schemas/graph.yaml#/properties/ports @@ -150,7 +153,6 @@ properties: required: - compatible - reg - - enable-gpios - vccio-supply - vpll-supply - vcca-supply @@ -201,11 +203,26 @@ examples: port@1 { reg = <1>; - endpoint { + sn65dsi86_out: endpoint { remote-endpoint = <&panel_in_edp>; }; }; }; + + aux-bus { + panel { + compatible = "boe,nv133fhm-n62"; + power-supply = <&pp3300_dx_edp>; + backlight = <&backlight>; + hpd-gpios = <&sn65dsi86_bridge 2 GPIO_ACTIVE_HIGH>; + + port { + panel_in_edp: endpoint { + remote-endpoint = <&sn65dsi86_out>; + }; + }; + }; + }; }; }; - | diff --git a/Documentation/devicetree/bindings/display/dp-aux-bus.yaml b/Documentation/devicetree/bindings/display/dp-aux-bus.yaml new file mode 100644 index 000000000000..5e4afe9f98fb --- /dev/null +++ b/Documentation/devicetree/bindings/display/dp-aux-bus.yaml @@ -0,0 +1,37 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/display/dp-aux-bus.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: DisplayPort AUX bus + +maintainers: + - Douglas Anderson <dianders@chromium.org> + +description: + DisplayPort controllers provide a control channel to the sinks that + are hooked up to them. This is the DP AUX bus. Over the DP AUX bus + we can query properties about a sink and also configure it. In + particular, DP sinks support DDC over DP AUX which allows tunneling + a standard I2C DDC connection over the AUX channel. + + To model this relationship, DP sinks should be placed as children + of the DP controller under the "aux-bus" node. + + At the moment, this binding only handles the eDP case. It is + possible it will be extended in the future to handle the DP case. + For DP, presumably a connector would be listed under the DP AUX + bus instead of a panel. + +properties: + $nodename: + const: "aux-bus" + + panel: + $ref: panel/panel-common.yaml# + +additionalProperties: false + +required: + - panel diff --git a/Documentation/devicetree/bindings/display/fsl,lcdif.yaml b/Documentation/devicetree/bindings/display/fsl,lcdif.yaml index a4c3064c778c..900a56cae80e 100644 --- a/Documentation/devicetree/bindings/display/fsl,lcdif.yaml +++ b/Documentation/devicetree/bindings/display/fsl,lcdif.yaml @@ -27,6 +27,7 @@ properties: - fsl,imx6ul-lcdif - fsl,imx7d-lcdif - fsl,imx8mm-lcdif + - fsl,imx8mn-lcdif - fsl,imx8mq-lcdif - const: fsl,imx6sx-lcdif diff --git a/Documentation/devicetree/bindings/display/mediatek/mediatek,dsi.txt b/Documentation/devicetree/bindings/display/mediatek/mediatek,dsi.txt index 8238a86686be..d30428b9fb33 100644 --- a/Documentation/devicetree/bindings/display/mediatek/mediatek,dsi.txt +++ b/Documentation/devicetree/bindings/display/mediatek/mediatek,dsi.txt @@ -7,7 +7,7 @@ channel output. Required properties: - compatible: "mediatek,<chip>-dsi" -- the supported chips are mt2701, mt7623, mt8173 and mt8183. +- the supported chips are mt2701, mt7623, mt8167, mt8173 and mt8183. - reg: Physical base address and length of the controller's registers - interrupts: The interrupt signal from the function block. - clocks: device clocks diff --git a/Documentation/devicetree/bindings/display/msm/dsi-controller-main.yaml b/Documentation/devicetree/bindings/display/msm/dsi-controller-main.yaml index 76348b71f736..35426fde8610 100644 --- a/Documentation/devicetree/bindings/display/msm/dsi-controller-main.yaml +++ b/Documentation/devicetree/bindings/display/msm/dsi-controller-main.yaml @@ -64,6 +64,18 @@ properties: Indicates if the DSI controller is driving a panel which needs 2 DSI links. + assigned-clocks: + minItems: 2 + maxItems: 2 + description: | + Parents of "byte" and "pixel" for the given platform. + + assigned-clock-parents: + minItems: 2 + maxItems: 2 + description: | + The Byte clock and Pixel clock PLL outputs provided by a DSI PHY block. + power-domains: maxItems: 1 @@ -77,7 +89,8 @@ properties: properties: port@0: - $ref: "/schemas/graph.yaml#/properties/port" + $ref: "/schemas/graph.yaml#/$defs/port-base" + unevaluatedProperties: false description: | Input endpoints of the controller. properties: @@ -92,7 +105,8 @@ properties: enum: [ 0, 1, 2, 3 ] port@1: - $ref: "/schemas/graph.yaml#/properties/port" + $ref: "/schemas/graph.yaml#/$defs/port-base" + unevaluatedProperties: false description: | Output endpoints of the controller. properties: @@ -119,6 +133,8 @@ required: - clock-names - phys - phy-names + - assigned-clocks + - assigned-clock-parents - power-domains - operating-points-v2 - ports @@ -159,6 +175,9 @@ examples: phys = <&dsi0_phy>; phy-names = "dsi"; + assigned-clocks = <&dispcc DISP_CC_MDSS_BYTE0_CLK_SRC>, <&dispcc DISP_CC_MDSS_PCLK0_CLK_SRC>; + assigned-clock-parents = <&dsi_phy 0>, <&dsi_phy 1>; + power-domains = <&rpmhpd SC7180_CX>; operating-points-v2 = <&dsi_opp_table>; diff --git a/Documentation/devicetree/bindings/display/msm/dsi-phy-10nm.yaml b/Documentation/devicetree/bindings/display/msm/dsi-phy-10nm.yaml index 4a26bef19360..4399715953e1 100644 --- a/Documentation/devicetree/bindings/display/msm/dsi-phy-10nm.yaml +++ b/Documentation/devicetree/bindings/display/msm/dsi-phy-10nm.yaml @@ -14,9 +14,9 @@ allOf: properties: compatible: - oneOf: - - const: qcom,dsi-phy-10nm - - const: qcom,dsi-phy-10nm-8998 + enum: + - qcom,dsi-phy-10nm + - qcom,dsi-phy-10nm-8998 reg: items: diff --git a/Documentation/devicetree/bindings/display/msm/dsi-phy-14nm.yaml b/Documentation/devicetree/bindings/display/msm/dsi-phy-14nm.yaml index 72a00cce0147..064df50e21a5 100644 --- a/Documentation/devicetree/bindings/display/msm/dsi-phy-14nm.yaml +++ b/Documentation/devicetree/bindings/display/msm/dsi-phy-14nm.yaml @@ -14,9 +14,9 @@ allOf: properties: compatible: - oneOf: - - const: qcom,dsi-phy-14nm - - const: qcom,dsi-phy-14nm-660 + enum: + - qcom,dsi-phy-14nm + - qcom,dsi-phy-14nm-660 reg: items: diff --git a/Documentation/devicetree/bindings/display/msm/dsi-phy-20nm.yaml b/Documentation/devicetree/bindings/display/msm/dsi-phy-20nm.yaml index 743806d61afe..b8de785ce815 100644 --- a/Documentation/devicetree/bindings/display/msm/dsi-phy-20nm.yaml +++ b/Documentation/devicetree/bindings/display/msm/dsi-phy-20nm.yaml @@ -14,8 +14,7 @@ allOf: properties: compatible: - oneOf: - - const: qcom,dsi-phy-20nm + const: qcom,dsi-phy-20nm reg: items: diff --git a/Documentation/devicetree/bindings/display/msm/dsi-phy-28nm.yaml b/Documentation/devicetree/bindings/display/msm/dsi-phy-28nm.yaml index b106007116b4..69eecaa64b18 100644 --- a/Documentation/devicetree/bindings/display/msm/dsi-phy-28nm.yaml +++ b/Documentation/devicetree/bindings/display/msm/dsi-phy-28nm.yaml @@ -14,10 +14,10 @@ allOf: properties: compatible: - oneOf: - - const: qcom,dsi-phy-28nm-hpm - - const: qcom,dsi-phy-28nm-lp - - const: qcom,dsi-phy-28nm-8960 + enum: + - qcom,dsi-phy-28nm-hpm + - qcom,dsi-phy-28nm-lp + - qcom,dsi-phy-28nm-8960 reg: items: diff --git a/Documentation/devicetree/bindings/display/msm/dsi-phy-7nm.yaml b/Documentation/devicetree/bindings/display/msm/dsi-phy-7nm.yaml new file mode 100644 index 000000000000..4265399bb154 --- /dev/null +++ b/Documentation/devicetree/bindings/display/msm/dsi-phy-7nm.yaml @@ -0,0 +1,72 @@ +# SPDX-License-Identifier: GPL-2.0-only or BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/display/msm/dsi-phy-7nm.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Qualcomm Display DSI 7nm PHY + +maintainers: + - Jonathan Marek <jonathan@marek.ca> + +allOf: + - $ref: dsi-phy-common.yaml# + +properties: + compatible: + oneOf: + - const: qcom,dsi-phy-7nm + - const: qcom,dsi-phy-7nm-8150 + - const: qcom,sc7280-dsi-phy-7nm + + reg: + items: + - description: dsi phy register set + - description: dsi phy lane register set + - description: dsi pll register set + + reg-names: + items: + - const: dsi_phy + - const: dsi_phy_lane + - const: dsi_pll + + vdds-supply: + description: | + Connected to VDD_A_DSI_PLL_0P9 pin (or VDDA_DSI{0,1}_PLL_0P9 for sm8150) + + phy-type: + description: D-PHY (default) or C-PHY mode + enum: [ 10, 11 ] + default: 10 + +required: + - compatible + - reg + - reg-names + - vdds-supply + +unevaluatedProperties: false + +examples: + - | + #include <dt-bindings/clock/qcom,dispcc-sm8250.h> + #include <dt-bindings/clock/qcom,rpmh.h> + + dsi-phy@ae94400 { + compatible = "qcom,dsi-phy-7nm"; + reg = <0x0ae94400 0x200>, + <0x0ae94600 0x280>, + <0x0ae94900 0x260>; + reg-names = "dsi_phy", + "dsi_phy_lane", + "dsi_pll"; + + #clock-cells = <1>; + #phy-cells = <0>; + + vdds-supply = <&vreg_l5a_0p88>; + clocks = <&dispcc DISP_CC_MDSS_AHB_CLK>, + <&rpmhcc RPMH_CXO_CLK>; + clock-names = "iface", "ref"; + }; diff --git a/Documentation/devicetree/bindings/display/panel/boe,tv101wum-nl6.yaml b/Documentation/devicetree/bindings/display/panel/boe,tv101wum-nl6.yaml index 38bc1d1b511e..b87a2e28c866 100644 --- a/Documentation/devicetree/bindings/display/panel/boe,tv101wum-nl6.yaml +++ b/Documentation/devicetree/bindings/display/panel/boe,tv101wum-nl6.yaml @@ -70,7 +70,6 @@ examples: avee-supply = <&ppvarp_lcd>; pp1800-supply = <&pp1800_lcd>; backlight = <&backlight_lcd0>; - status = "okay"; port { panel_in: endpoint { remote-endpoint = <&dsi_out>; diff --git a/Documentation/devicetree/bindings/display/panel/ilitek,ili9341.yaml b/Documentation/devicetree/bindings/display/panel/ilitek,ili9341.yaml new file mode 100644 index 000000000000..2ed010f91e2d --- /dev/null +++ b/Documentation/devicetree/bindings/display/panel/ilitek,ili9341.yaml @@ -0,0 +1,78 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/display/panel/ilitek,ili9341.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Ilitek-9341 Display Panel + +maintainers: + - Dillon Min <dillon.minfei@gmail.com> + +description: | + Ilitek ILI9341 TFT panel driver with SPI control bus + This is a driver for 320x240 TFT panels, accepting a rgb input + streams with 16 bits or 18 bits. + +allOf: + - $ref: panel-common.yaml# + +properties: + compatible: + items: + - enum: + # ili9341 240*320 Color on stm32f429-disco board + - st,sf-tc240t-9370-t + - const: ilitek,ili9341 + + reg: true + + dc-gpios: + maxItems: 1 + description: Display data/command selection (D/CX) of this DBI panel + + spi-3wire: true + + spi-max-frequency: + const: 10000000 + + port: true + + vci-supply: + description: Analog voltage supply (2.5 .. 3.3V) + + vddi-supply: + description: Voltage supply for interface logic (1.65 .. 3.3 V) + + vddi-led-supply: + description: Voltage supply for the LED driver (1.65 .. 3.3 V) + +additionalProperties: false + +required: + - compatible + - reg + - dc-gpios + - port + +examples: + - |+ + spi { + #address-cells = <1>; + #size-cells = <0>; + panel: display@0 { + compatible = "st,sf-tc240t-9370-t", + "ilitek,ili9341"; + reg = <0>; + spi-3wire; + spi-max-frequency = <10000000>; + dc-gpios = <&gpiod 13 0>; + port { + panel_in: endpoint { + remote-endpoint = <&display_out>; + }; + }; + }; + }; +... + diff --git a/Documentation/devicetree/bindings/display/panel/innolux,ej030na.yaml b/Documentation/devicetree/bindings/display/panel/innolux,ej030na.yaml new file mode 100644 index 000000000000..cda36c04e85c --- /dev/null +++ b/Documentation/devicetree/bindings/display/panel/innolux,ej030na.yaml @@ -0,0 +1,62 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/display/panel/innolux,ej030na.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Innolux EJ030NA 3.0" (320x480 pixels) 24-bit TFT LCD panel + +description: | + The panel must obey the rules for a SPI slave device as specified in + spi/spi-controller.yaml + +maintainers: + - Paul Cercueil <paul@crapouillou.net> + +allOf: + - $ref: panel-common.yaml# + +properties: + compatible: + const: innolux,ej030na + + backlight: true + port: true + power-supply: true + reg: true + reset-gpios: true + +required: + - compatible + - reg + - power-supply + - reset-gpios + +unevaluatedProperties: false + +examples: + - | + #include <dt-bindings/gpio/gpio.h> + + spi { + #address-cells = <1>; + #size-cells = <0>; + + panel@0 { + compatible = "innolux,ej030na"; + reg = <0>; + + spi-max-frequency = <10000000>; + + reset-gpios = <&gpe 4 GPIO_ACTIVE_LOW>; + power-supply = <&lcd_power>; + + backlight = <&backlight>; + + port { + panel_input: endpoint { + remote-endpoint = <&panel_output>; + }; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/display/panel/panel-simple.yaml b/Documentation/devicetree/bindings/display/panel/panel-simple.yaml index b3797ba2698b..335776c45474 100644 --- a/Documentation/devicetree/bindings/display/panel/panel-simple.yaml +++ b/Documentation/devicetree/bindings/display/panel/panel-simple.yaml @@ -46,9 +46,13 @@ properties: # AU Optronics Corporation 11.6" HD (1366x768) color TFT-LCD panel - auo,b116xw03 # AU Optronics Corporation 13.3" FHD (1920x1080) color TFT-LCD panel + - auo,b133han05 + # AU Optronics Corporation 13.3" FHD (1920x1080) color TFT-LCD panel - auo,b133htn01 # AU Optronics Corporation 13.3" WXGA (1366x768) TFT LCD panel - auo,b133xtn01 + # AU Optronics Corporation 14.0" FHD (1920x1080) color TFT-LCD panel + - auo,b140han06 # AU Optronics Corporation 7.0" FHD (800 x 480) TFT LCD panel - auo,g070vvn01 # AU Optronics Corporation 10.1" (1280x800) color TFT LCD panel @@ -110,6 +114,9 @@ properties: # Emerging Display Technology Corp. 5.7" VGA TFT LCD panel - edt,et057090dhu - edt,et070080dh6 + # Emerging Display Technology Corp. 3.5" WVGA TFT LCD panel with + # capacitive multitouch + - edt,etm0350g0dh6 # Emerging Display Technology Corp. 480x272 TFT Display with capacitive touch - edt,etm043080dh6gp # Emerging Display Technology Corp. 480x272 TFT Display @@ -128,6 +135,11 @@ properties: # Emerging Display Technology Corp. WVGA TFT Display with capacitive touch - edt,etm0700g0dh6 - edt,etm0700g0edh6 + # Emerging Display Technology Corp. 5.7" VGA TFT LCD panel with + # capacitive touch + - edt,etmv570g2dhu + # E Ink VB3300-KCA + - eink,vb3300-kca # Evervision Electronics Co. Ltd. VGG804821 5.0" WVGA TFT LCD Panel - evervision,vgg804821 # Foxlink Group 5" WVGA TFT LCD panel @@ -202,8 +214,14 @@ properties: - logictechno,lt161010-2nhr # Logic Technologies LT170410-2WHC 10.1" 1280x800 IPS TFT Cap Touch Mod. - logictechno,lt170410-2whc + # Logic Technologies LTTD800x480 L2RT 7" 800x480 TFT Resistive Touch Module + - logictechno,lttd800480070-l2rt + # Logic Technologies LTTD800480070-L6WH-RT 7” 800x480 TFT Resistive Touch Module + - logictechno,lttd800480070-l6wh-rt # Mitsubishi "AA070MC01 7.0" WVGA TFT LCD panel - mitsubishi,aa070mc01-ca1 + # Multi-Inno Technology Co.,Ltd MI1010AIT-1CP 10.1" 1280x800 LVDS IPS Cap Touch Mod. + - multi-inno,mi1010ait-1cp # NEC LCD Technologies, Ltd. 12.1" WXGA (1280x800) LVDS TFT LCD panel - nec,nl12880bc20-05 # NEC LCD Technologies,Ltd. WQVGA TFT LCD panel @@ -238,10 +256,14 @@ properties: - powertip,ph800480t013-idf02 # QiaoDian XianShi Corporation 4"3 TFT LCD panel - qiaodian,qd43003c0-40 + # Shenzhen QiShenglong Industrialist Co., Ltd. Gopher 2b 4.3" 480(RGB)x272 TFT LCD panel + - qishenglong,gopher2b-lcd # Rocktech Displays Ltd. RK101II01D-CT 10.1" TFT 1280x800 - rocktech,rk101ii01d-ct # Rocktech Display Ltd. RK070ER9427 800(RGB)x480 TFT LCD panel - rocktech,rk070er9427 + # Samsung 13.3" FHD (1920x1080 pixels) eDP AMOLED panel + - samsung,atna33xc20 # Samsung 12.2" (2560x1600 pixels) TFT LCD panel - samsung,lsn122dl01-c01 # Samsung Electronics 10.1" WSVGA TFT LCD panel @@ -298,6 +320,8 @@ properties: enable-gpios: true port: true power-supply: true + no-hpd: true + hpd-gpios: true additionalProperties: false diff --git a/Documentation/devicetree/bindings/display/panel/samsung,lms380kf01.yaml b/Documentation/devicetree/bindings/display/panel/samsung,lms380kf01.yaml new file mode 100644 index 000000000000..251f0c7115aa --- /dev/null +++ b/Documentation/devicetree/bindings/display/panel/samsung,lms380kf01.yaml @@ -0,0 +1,99 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/display/panel/samsung,lms380kf01.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Samsung LMS380KF01 display panel + +description: The LMS380KF01 is a 480x800 DPI display panel from Samsung Mobile + Displays (SMD) utilizing the WideChips WS2401 display controller. It can be + used with internal or external backlight control. + The panel must obey the rules for a SPI slave device as specified in + spi/spi-controller.yaml + +maintainers: + - Linus Walleij <linus.walleij@linaro.org> + +allOf: + - $ref: panel-common.yaml# + +properties: + compatible: + const: samsung,lms380kf01 + + reg: true + + interrupts: + description: provides an optional ESD (electrostatic discharge) + interrupt that signals abnormalities in the display hardware. + This can also be raised for other reasons like erroneous + configuration. + maxItems: 1 + + reset-gpios: true + + vci-supply: + description: regulator that supplies the VCI analog voltage + usually around 3.0 V + + vccio-supply: + description: regulator that supplies the VCCIO voltage usually + around 1.8 V + + backlight: true + + spi-cpha: true + + spi-cpol: true + + spi-max-frequency: + maximum: 1200000 + + port: true + +required: + - compatible + - reg + - spi-cpha + - spi-cpol + - port + +additionalProperties: false + +examples: + - | + #include <dt-bindings/gpio/gpio.h> + #include <dt-bindings/interrupt-controller/irq.h> + + spi { + compatible = "spi-gpio"; + sck-gpios = <&gpio 0 GPIO_ACTIVE_HIGH>; + miso-gpios = <&gpio 1 GPIO_ACTIVE_HIGH>; + mosi-gpios = <&gpio 2 GPIO_ACTIVE_HIGH>; + cs-gpios = <&gpio 3 GPIO_ACTIVE_HIGH>; + num-chipselects = <1>; + #address-cells = <1>; + #size-cells = <0>; + + panel@0 { + compatible = "samsung,lms380kf01"; + spi-max-frequency = <1200000>; + spi-cpha; + spi-cpol; + reg = <0>; + vci-supply = <&lcd_3v0_reg>; + vccio-supply = <&lcd_1v8_reg>; + reset-gpios = <&gpio 4 GPIO_ACTIVE_LOW>; + interrupt-parent = <&gpio>; + interrupts = <5 IRQ_TYPE_EDGE_RISING>; + + port { + panel_in: endpoint { + remote-endpoint = <&display_out>; + }; + }; + }; + }; + +... diff --git a/Documentation/devicetree/bindings/display/panel/samsung,lms397kf04.yaml b/Documentation/devicetree/bindings/display/panel/samsung,lms397kf04.yaml index 4cb75a5f2e3a..cd62968426fb 100644 --- a/Documentation/devicetree/bindings/display/panel/samsung,lms397kf04.yaml +++ b/Documentation/devicetree/bindings/display/panel/samsung,lms397kf04.yaml @@ -33,8 +33,11 @@ properties: backlight: true + spi-cpha: true + + spi-cpol: true + spi-max-frequency: - $ref: /schemas/types.yaml#/definitions/uint32 description: inherited as a SPI client node, the datasheet specifies maximum 300 ns minimum cycle which gives around 3 MHz max frequency maximum: 3000000 @@ -44,6 +47,9 @@ properties: required: - compatible - reg + - spi-cpha + - spi-cpol + - port additionalProperties: false @@ -52,15 +58,23 @@ examples: #include <dt-bindings/gpio/gpio.h> spi { + compatible = "spi-gpio"; + sck-gpios = <&gpio 0 GPIO_ACTIVE_HIGH>; + miso-gpios = <&gpio 1 GPIO_ACTIVE_HIGH>; + mosi-gpios = <&gpio 2 GPIO_ACTIVE_HIGH>; + cs-gpios = <&gpio 3 GPIO_ACTIVE_HIGH>; + num-chipselects = <1>; #address-cells = <1>; #size-cells = <0>; panel@0 { compatible = "samsung,lms397kf04"; spi-max-frequency = <3000000>; + spi-cpha; + spi-cpol; reg = <0>; vci-supply = <&lcd_3v0_reg>; vccio-supply = <&lcd_1v8_reg>; - reset-gpios = <&gpio 1 GPIO_ACTIVE_LOW>; + reset-gpios = <&gpio 4 GPIO_ACTIVE_LOW>; backlight = <&ktd259>; port { 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 151be3bba06f..39792f051d2d 100644 --- a/Documentation/devicetree/bindings/display/rockchip/dw_mipi_dsi_rockchip.txt +++ b/Documentation/devicetree/bindings/display/rockchip/dw_mipi_dsi_rockchip.txt @@ -23,6 +23,7 @@ Required properties: Optional properties: - phys: from general PHY binding: the phandle for the PHY device. - phy-names: Should be "dphy" if phys references an external phy. +- #phy-cells: Defined when used as ISP phy, should be 0. - 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/solomon,ssd1307fb.yaml b/Documentation/devicetree/bindings/display/solomon,ssd1307fb.yaml new file mode 100644 index 000000000000..2ed2a7d0ca2f --- /dev/null +++ b/Documentation/devicetree/bindings/display/solomon,ssd1307fb.yaml @@ -0,0 +1,208 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/display/solomon,ssd1307fb.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Solomon SSD1307 OLED Controller Framebuffer + +maintainers: + - Maxime Ripard <mripard@kernel.org> + +properties: + compatible: + enum: + - solomon,ssd1305fb-i2c + - solomon,ssd1306fb-i2c + - solomon,ssd1307fb-i2c + - solomon,ssd1309fb-i2c + + reg: + maxItems: 1 + + pwms: + maxItems: 1 + + reset-gpios: + maxItems: 1 + + vbat-supply: + description: The supply for VBAT + + solomon,height: + $ref: /schemas/types.yaml#/definitions/uint32 + default: 16 + description: + Height in pixel of the screen driven by the controller + + solomon,width: + $ref: /schemas/types.yaml#/definitions/uint32 + default: 96 + description: + Width in pixel of the screen driven by the controller + + solomon,page-offset: + $ref: /schemas/types.yaml#/definitions/uint32 + default: 1 + description: + Offset of pages (band of 8 pixels) that the screen is mapped to + + solomon,segment-no-remap: + type: boolean + description: + Display needs normal (non-inverted) data column to segment mapping + + solomon,col-offset: + $ref: /schemas/types.yaml#/definitions/uint32 + default: 0 + description: + Offset of columns (COL/SEG) that the screen is mapped to + + solomon,com-seq: + type: boolean + description: + Display uses sequential COM pin configuration + + solomon,com-lrremap: + type: boolean + description: + Display uses left-right COM pin remap + + solomon,com-invdir: + type: boolean + description: + Display uses inverted COM pin scan direction + + solomon,com-offset: + $ref: /schemas/types.yaml#/definitions/uint32 + default: 0 + description: + Number of the COM pin wired to the first display line + + solomon,prechargep1: + $ref: /schemas/types.yaml#/definitions/uint32 + default: 2 + description: + Length of deselect period (phase 1) in clock cycles + + solomon,prechargep2: + $ref: /schemas/types.yaml#/definitions/uint32 + default: 2 + description: + Length of precharge period (phase 2) in clock cycles. This needs to be + the higher, the higher the capacitance of the OLED's pixels is. + + solomon,dclk-div: + $ref: /schemas/types.yaml#/definitions/uint32 + minimum: 1 + maximum: 16 + description: + Clock divisor. The default value is controller-dependent. + + solomon,dclk-frq: + $ref: /schemas/types.yaml#/definitions/uint32 + minimum: 0 + maximum: 15 + description: + Clock frequency, higher value means higher frequency. + The default value is controller-dependent. + + solomon,lookup-table: + $ref: /schemas/types.yaml#/definitions/uint8-array + maxItems: 4 + description: + 8 bit value array of current drive pulse widths for BANK0, and colors A, + B, and C. Each value in range of 31 to 63 for pulse widths of 32 to 64. + Color D is always width 64. + + solomon,area-color-enable: + type: boolean + description: + Display uses color mode + + solomon,low-power: + type: boolean + description: + Display runs in low power mode + +required: + - compatible + - reg + +allOf: + - if: + properties: + compatible: + contains: + const: solomon,ssd1305fb-i2c + then: + properties: + solomon,dclk-div: + default: 1 + solomon,dclk-frq: + default: 7 + + - if: + properties: + compatible: + contains: + const: solomon,ssd1306fb-i2c + then: + properties: + solomon,dclk-div: + default: 1 + solomon,dclk-frq: + default: 8 + + - if: + properties: + compatible: + contains: + const: solomon,ssd1307fb-i2c + then: + properties: + solomon,dclk-div: + default: 2 + solomon,dclk-frq: + default: 12 + required: + - pwms + + - if: + properties: + compatible: + contains: + const: solomon,ssd1309fb-i2c + then: + properties: + solomon,dclk-div: + default: 1 + solomon,dclk-frq: + default: 10 + +additionalProperties: false + +examples: + - | + i2c1 { + #address-cells = <1>; + #size-cells = <0>; + + ssd1307: oled@3c { + compatible = "solomon,ssd1307fb-i2c"; + reg = <0x3c>; + pwms = <&pwm 4 3000>; + reset-gpios = <&gpio2 7>; + }; + + ssd1306: oled@3d { + compatible = "solomon,ssd1306fb-i2c"; + reg = <0x3c>; + pwms = <&pwm 4 3000>; + reset-gpios = <&gpio2 7>; + solomon,com-lrremap; + solomon,com-invdir; + solomon,com-offset = <32>; + solomon,lookup-table = /bits/ 8 <0x3f 0x3f 0x3f 0x3f>; + }; + }; diff --git a/Documentation/devicetree/bindings/display/ssd1307fb.txt b/Documentation/devicetree/bindings/display/ssd1307fb.txt deleted file mode 100644 index 2dcb6d12d137..000000000000 --- a/Documentation/devicetree/bindings/display/ssd1307fb.txt +++ /dev/null @@ -1,60 +0,0 @@ -* Solomon SSD1307 Framebuffer Driver - -Required properties: - - compatible: Should be "solomon,<chip>fb-<bus>". The only supported bus for - now is i2c, and the supported chips are ssd1305, ssd1306, ssd1307 and - ssd1309. - - reg: Should contain address of the controller on the I2C bus. Most likely - 0x3c or 0x3d - - pwm: Should contain the pwm to use according to the OF device tree PWM - specification [0]. Only required for the ssd1307. - - solomon,height: Height in pixel of the screen driven by the controller - - solomon,width: Width in pixel of the screen driven by the controller - - solomon,page-offset: Offset of pages (band of 8 pixels) that the screen is - mapped to. - -Optional properties: - - reset-gpios: The GPIO used to reset the OLED display, if available. See - Documentation/devicetree/bindings/gpio/gpio.txt for details. - - vbat-supply: The supply for VBAT - - solomon,segment-no-remap: Display needs normal (non-inverted) data column - to segment mapping - - solomon,col-offset: Offset of columns (COL/SEG) that the screen is mapped to. - - solomon,com-seq: Display uses sequential COM pin configuration - - solomon,com-lrremap: Display uses left-right COM pin remap - - solomon,com-invdir: Display uses inverted COM pin scan direction - - solomon,com-offset: Number of the COM pin wired to the first display line - - solomon,prechargep1: Length of deselect period (phase 1) in clock cycles. - - solomon,prechargep2: Length of precharge period (phase 2) in clock cycles. - This needs to be the higher, the higher the capacitance - of the OLED's pixels is - - solomon,dclk-div: Clock divisor 1 to 16 - - solomon,dclk-frq: Clock frequency 0 to 15, higher value means higher - frequency - - solomon,lookup-table: 8 bit value array of current drive pulse widths for - BANK0, and colors A, B, and C. Each value in range - of 31 to 63 for pulse widths of 32 to 64. Color D - is always width 64. - - solomon,area-color-enable: Display uses color mode - - solomon,low-power. Display runs in low power mode - -[0]: Documentation/devicetree/bindings/pwm/pwm.txt - -Examples: -ssd1307: oled@3c { - compatible = "solomon,ssd1307fb-i2c"; - reg = <0x3c>; - pwms = <&pwm 4 3000>; - reset-gpios = <&gpio2 7>; -}; - -ssd1306: oled@3c { - compatible = "solomon,ssd1306fb-i2c"; - reg = <0x3c>; - pwms = <&pwm 4 3000>; - reset-gpios = <&gpio2 7>; - solomon,com-lrremap; - solomon,com-invdir; - solomon,com-offset = <32>; - solomon,lookup-table = /bits/ 8 <0x3f 0x3f 0x3f 0x3f>; -}; diff --git a/Documentation/devicetree/bindings/display/zte,vou.txt b/Documentation/devicetree/bindings/display/zte,vou.txt deleted file mode 100644 index 38476475fd60..000000000000 --- a/Documentation/devicetree/bindings/display/zte,vou.txt +++ /dev/null @@ -1,120 +0,0 @@ -ZTE VOU Display Controller - -This is a display controller found on ZTE ZX296718 SoC. It includes multiple -Graphic Layer (GL) and Video Layer (VL), two Mixers/Channels, and a few blocks -handling scaling, color space conversion etc. VOU also integrates the support -for typical output devices, like HDMI, TV Encoder, VGA, and RGB LCD. - -* Master VOU node - -It must be the parent node of all the sub-device nodes. - -Required properties: - - compatible: should be "zte,zx296718-vou" - - #address-cells: should be <1> - - #size-cells: should be <1> - - ranges: list of address translations between VOU and sub-devices - -* VOU DPC device - -Required properties: - - compatible: should be "zte,zx296718-dpc" - - reg: Physical base address and length of DPC register regions, one for each - entry in 'reg-names' - - reg-names: The names of register regions. The following regions are required: - "osd" - "timing_ctrl" - "dtrc" - "vou_ctrl" - "otfppu" - - interrupts: VOU DPC interrupt number to CPU - - clocks: A list of phandle + clock-specifier pairs, one for each entry - in 'clock-names' - - clock-names: A list of clock names. The following clocks are required: - "aclk" - "ppu_wclk" - "main_wclk" - "aux_wclk" - -* HDMI output device - -Required properties: - - compatible: should be "zte,zx296718-hdmi" - - reg: Physical base address and length of the HDMI device IO region - - interrupts : HDMI interrupt number to CPU - - clocks: A list of phandle + clock-specifier pairs, one for each entry - in 'clock-names' - - clock-names: A list of clock names. The following clocks are required: - "osc_cec" - "osc_clk" - "xclk" - -* TV Encoder output device - -Required properties: - - compatible: should be "zte,zx296718-tvenc" - - reg: Physical base address and length of the TVENC device IO region - - zte,tvenc-power-control: the phandle to SYSCTRL block followed by two - integer cells. The first cell is the offset of SYSCTRL register used - to control TV Encoder DAC power, and the second cell is the bit mask. - -* VGA output device - -Required properties: - - compatible: should be "zte,zx296718-vga" - - reg: Physical base address and length of the VGA device IO region - - interrupts : VGA interrupt number to CPU - - clocks: Phandle with clock-specifier pointing to VGA I2C clock. - - clock-names: Must be "i2c_wclk". - - zte,vga-power-control: the phandle to SYSCTRL block followed by two - integer cells. The first cell is the offset of SYSCTRL register used - to control VGA DAC power, and the second cell is the bit mask. - -Example: - -vou: vou@1440000 { - compatible = "zte,zx296718-vou"; - #address-cells = <1>; - #size-cells = <1>; - ranges = <0 0x1440000 0x10000>; - - dpc: dpc@0 { - compatible = "zte,zx296718-dpc"; - reg = <0x0000 0x1000>, <0x1000 0x1000>, - <0x5000 0x1000>, <0x6000 0x1000>, - <0xa000 0x1000>; - reg-names = "osd", "timing_ctrl", - "dtrc", "vou_ctrl", - "otfppu"; - interrupts = <GIC_SPI 81 IRQ_TYPE_LEVEL_HIGH>; - clocks = <&topcrm VOU_ACLK>, <&topcrm VOU_PPU_WCLK>, - <&topcrm VOU_MAIN_WCLK>, <&topcrm VOU_AUX_WCLK>; - clock-names = "aclk", "ppu_wclk", - "main_wclk", "aux_wclk"; - }; - - vga: vga@8000 { - compatible = "zte,zx296718-vga"; - reg = <0x8000 0x1000>; - interrupts = <GIC_SPI 86 IRQ_TYPE_LEVEL_HIGH>; - clocks = <&topcrm VGA_I2C_WCLK>; - clock-names = "i2c_wclk"; - zte,vga-power-control = <&sysctrl 0x170 0xe0>; - }; - - hdmi: hdmi@c000 { - compatible = "zte,zx296718-hdmi"; - reg = <0xc000 0x4000>; - interrupts = <GIC_SPI 82 IRQ_TYPE_EDGE_RISING>; - clocks = <&topcrm HDMI_OSC_CEC>, - <&topcrm HDMI_OSC_CLK>, - <&topcrm HDMI_XCLK>; - clock-names = "osc_cec", "osc_clk", "xclk"; - }; - - tvenc: tvenc@2000 { - compatible = "zte,zx296718-tvenc"; - reg = <0x2000 0x1000>; - zte,tvenc-power-control = <&sysctrl 0x170 0x10>; - }; -}; diff --git a/Documentation/devicetree/bindings/dma/allwinner,sun6i-a31-dma.yaml b/Documentation/devicetree/bindings/dma/allwinner,sun6i-a31-dma.yaml index c1676b96daac..a6df6f8b54db 100644 --- a/Documentation/devicetree/bindings/dma/allwinner,sun6i-a31-dma.yaml +++ b/Documentation/devicetree/bindings/dma/allwinner,sun6i-a31-dma.yaml @@ -19,12 +19,12 @@ properties: description: The cell is the request line number. compatible: - oneOf: - - const: allwinner,sun6i-a31-dma - - const: allwinner,sun8i-a23-dma - - const: allwinner,sun8i-a83t-dma - - const: allwinner,sun8i-h3-dma - - const: allwinner,sun8i-v3s-dma + enum: + - allwinner,sun6i-a31-dma + - allwinner,sun8i-a23-dma + - allwinner,sun8i-a83t-dma + - allwinner,sun8i-h3-dma + - allwinner,sun8i-v3s-dma reg: maxItems: 1 diff --git a/Documentation/devicetree/bindings/dma/fsl-imx-sdma.txt b/Documentation/devicetree/bindings/dma/fsl-imx-sdma.txt index c9e97409e853..12c316ff4834 100644 --- a/Documentation/devicetree/bindings/dma/fsl-imx-sdma.txt +++ b/Documentation/devicetree/bindings/dma/fsl-imx-sdma.txt @@ -9,6 +9,7 @@ Required properties: "fsl,imx53-sdma" "fsl,imx6q-sdma" "fsl,imx7d-sdma" + "fsl,imx6ul-sdma" "fsl,imx8mq-sdma" "fsl,imx8mm-sdma" "fsl,imx8mn-sdma" diff --git a/Documentation/devicetree/bindings/firmware/arm,scmi.yaml b/Documentation/devicetree/bindings/firmware/arm,scmi.yaml index cebf6ffe70d5..5c4c6782e052 100644 --- a/Documentation/devicetree/bindings/firmware/arm,scmi.yaml +++ b/Documentation/devicetree/bindings/firmware/arm,scmi.yaml @@ -34,6 +34,10 @@ properties: - description: SCMI compliant firmware with ARM SMC/HVC transport items: - const: arm,scmi-smc + - description: SCMI compliant firmware with SCMI Virtio transport. + The virtio transport only supports a single device. + items: + - const: arm,scmi-virtio interrupts: description: @@ -172,6 +176,7 @@ patternProperties: Each sub-node represents a protocol supported. If the platform supports a dedicated communication channel for a particular protocol, then the corresponding transport properties must be present. + The virtio transport does not support a dedicated communication channel. properties: reg: @@ -195,7 +200,6 @@ patternProperties: required: - compatible - - shmem if: properties: @@ -209,6 +213,7 @@ then: required: - mboxes + - shmem else: if: @@ -219,6 +224,7 @@ else: then: required: - arm,smc-id + - shmem examples: - | diff --git a/Documentation/devicetree/bindings/firmware/arm,scpi.yaml b/Documentation/devicetree/bindings/firmware/arm,scpi.yaml index d7113b06454b..23b346bd1252 100644 --- a/Documentation/devicetree/bindings/firmware/arm,scpi.yaml +++ b/Documentation/devicetree/bindings/firmware/arm,scpi.yaml @@ -131,9 +131,9 @@ properties: properties: compatible: - oneOf: - - const: arm,scpi-dvfs-clocks - - const: arm,scpi-variable-clocks + enum: + - arm,scpi-dvfs-clocks + - arm,scpi-variable-clocks '#clock-cells': const: 1 diff --git a/Documentation/devicetree/bindings/firmware/xilinx/xlnx,zynqmp-firmware.txt b/Documentation/devicetree/bindings/firmware/xilinx/xlnx,zynqmp-firmware.txt deleted file mode 100644 index 18c3aea90df2..000000000000 --- a/Documentation/devicetree/bindings/firmware/xilinx/xlnx,zynqmp-firmware.txt +++ /dev/null @@ -1,44 +0,0 @@ ------------------------------------------------------------------ -Device Tree Bindings for the Xilinx Zynq MPSoC Firmware Interface ------------------------------------------------------------------ - -The zynqmp-firmware node describes the interface to platform firmware. -ZynqMP has an interface to communicate with secure firmware. Firmware -driver provides an interface to firmware APIs. Interface APIs can be -used by any driver to communicate to PMUFW(Platform Management Unit). -These requests include clock management, pin control, device control, -power management service, FPGA service and other platform management -services. - -Required properties: - - compatible: Must contain any of below: - "xlnx,zynqmp-firmware" for Zynq Ultrascale+ MPSoC - "xlnx,versal-firmware" for Versal - - method: The method of calling the PM-API firmware layer. - Permitted values are: - - "smc" : SMC #0, following the SMCCC - - "hvc" : HVC #0, following the SMCCC - -------- -Example -------- - -Zynq Ultrascale+ MPSoC ----------------------- -firmware { - zynqmp_firmware: zynqmp-firmware { - compatible = "xlnx,zynqmp-firmware"; - method = "smc"; - ... - }; -}; - -Versal ------- -firmware { - versal_firmware: versal-firmware { - compatible = "xlnx,versal-firmware"; - method = "smc"; - ... - }; -}; diff --git a/Documentation/devicetree/bindings/firmware/xilinx/xlnx,zynqmp-firmware.yaml b/Documentation/devicetree/bindings/firmware/xilinx/xlnx,zynqmp-firmware.yaml new file mode 100644 index 000000000000..f14f7b454f07 --- /dev/null +++ b/Documentation/devicetree/bindings/firmware/xilinx/xlnx,zynqmp-firmware.yaml @@ -0,0 +1,89 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/firmware/xilinx/xlnx,zynqmp-firmware.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Xilinx firmware driver + +maintainers: + - Nava kishore Manne <nava.manne@xilinx.com> + +description: The zynqmp-firmware node describes the interface to platform + firmware. ZynqMP has an interface to communicate with secure firmware. + Firmware driver provides an interface to firmware APIs. Interface APIs + can be used by any driver to communicate to PMUFW(Platform Management Unit). + These requests include clock management, pin control, device control, + power management service, FPGA service and other platform management + services. + +properties: + compatible: + oneOf: + - description: For implementations complying for Zynq Ultrascale+ MPSoC. + const: xlnx,zynqmp-firmware + + - description: For implementations complying for Versal. + const: xlnx,versal-firmware + + method: + description: | + The method of calling the PM-API firmware layer. + Permitted values are. + - "smc" : SMC #0, following the SMCCC + - "hvc" : HVC #0, following the SMCCC + + $ref: /schemas/types.yaml#/definitions/string-array + enum: + - smc + - hvc + + versal_fpga: + $ref: /schemas/fpga/xlnx,versal-fpga.yaml# + description: Compatible of the FPGA device. + type: object + + zynqmp-aes: + $ref: /schemas/crypto/xlnx,zynqmp-aes.yaml# + description: The ZynqMP AES-GCM hardened cryptographic accelerator is + used to encrypt or decrypt the data with provided key and initialization + vector. + type: object + + clock-controller: + $ref: /schemas/clock/xlnx,versal-clk.yaml# + description: The clock controller is a hardware block of Xilinx versal + clock tree. It reads required input clock frequencies from the devicetree + and acts as clock provider for all clock consumers of PS clocks.list of + clock specifiers which are external input clocks to the given clock + controller. + type: object + +required: + - compatible + +additionalProperties: false + +examples: + - | + versal-firmware { + compatible = "xlnx,versal-firmware"; + method = "smc"; + + versal_fpga: versal_fpga { + compatible = "xlnx,versal-fpga"; + }; + + xlnx_aes: zynqmp-aes { + compatible = "xlnx,zynqmp-aes"; + }; + + versal_clk: clock-controller { + #clock-cells = <1>; + compatible = "xlnx,versal-clk"; + clocks = <&ref>, <&alt_ref>, <&pl_alt_ref>; + clock-names = "ref", "alt_ref", "pl_alt_ref"; + }; + }; + +... diff --git a/Documentation/devicetree/bindings/fpga/xlnx,versal-fpga.yaml b/Documentation/devicetree/bindings/fpga/xlnx,versal-fpga.yaml new file mode 100644 index 000000000000..ac6a207278d5 --- /dev/null +++ b/Documentation/devicetree/bindings/fpga/xlnx,versal-fpga.yaml @@ -0,0 +1,33 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/fpga/xlnx,versal-fpga.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Xilinx Versal FPGA driver. + +maintainers: + - Nava kishore Manne <nava.manne@xilinx.com> + +description: | + Device Tree Versal FPGA bindings for the Versal SoC, controlled + using firmware interface. + +properties: + compatible: + items: + - enum: + - xlnx,versal-fpga + +required: + - compatible + +additionalProperties: false + +examples: + - | + versal_fpga: versal_fpga { + compatible = "xlnx,versal-fpga"; + }; + +... diff --git a/Documentation/devicetree/bindings/fpga/xlnx,zynqmp-pcap-fpga.txt b/Documentation/devicetree/bindings/fpga/xlnx,zynqmp-pcap-fpga.txt deleted file mode 100644 index 3052bf619dd5..000000000000 --- a/Documentation/devicetree/bindings/fpga/xlnx,zynqmp-pcap-fpga.txt +++ /dev/null @@ -1,25 +0,0 @@ -Devicetree bindings for Zynq Ultrascale MPSoC FPGA Manager. -The ZynqMP SoC uses the PCAP (Processor configuration Port) to configure the -Programmable Logic (PL). The configuration uses the firmware interface. - -Required properties: -- compatible: should contain "xlnx,zynqmp-pcap-fpga" - -Example for full FPGA configuration: - - fpga-region0 { - compatible = "fpga-region"; - fpga-mgr = <&zynqmp_pcap>; - #address-cells = <0x1>; - #size-cells = <0x1>; - }; - - firmware { - zynqmp_firmware: zynqmp-firmware { - compatible = "xlnx,zynqmp-firmware"; - method = "smc"; - zynqmp_pcap: pcap { - compatible = "xlnx,zynqmp-pcap-fpga"; - }; - }; - }; diff --git a/Documentation/devicetree/bindings/fpga/xlnx,zynqmp-pcap-fpga.yaml b/Documentation/devicetree/bindings/fpga/xlnx,zynqmp-pcap-fpga.yaml new file mode 100644 index 000000000000..6cd2bdc06b5f --- /dev/null +++ b/Documentation/devicetree/bindings/fpga/xlnx,zynqmp-pcap-fpga.yaml @@ -0,0 +1,36 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/fpga/xlnx,zynqmp-pcap-fpga.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Xilinx Zynq Ultrascale MPSoC FPGA Manager Device Tree Bindings + +maintainers: + - Nava kishore Manne <navam@xilinx.com> + +description: | + Device Tree Bindings for Zynq Ultrascale MPSoC FPGA Manager. + The ZynqMP SoC uses the PCAP (Processor Configuration Port) to + configure the Programmable Logic (PL). The configuration uses the + firmware interface. + +properties: + compatible: + const: xlnx,zynqmp-pcap-fpga + +required: + - compatible + +additionalProperties: false + +examples: + - | + firmware { + zynqmp_firmware: zynqmp-firmware { + zynqmp_pcap: pcap { + compatible = "xlnx,zynqmp-pcap-fpga"; + }; + }; + }; +... diff --git a/Documentation/devicetree/bindings/fsi/ibm,fsi2spi.yaml b/Documentation/devicetree/bindings/fsi/ibm,fsi2spi.yaml index e425278653f5..e2ca0b000471 100644 --- a/Documentation/devicetree/bindings/fsi/ibm,fsi2spi.yaml +++ b/Documentation/devicetree/bindings/fsi/ibm,fsi2spi.yaml @@ -19,7 +19,6 @@ properties: compatible: enum: - ibm,fsi2spi - - ibm,fsi2spi-restricted reg: items: diff --git a/Documentation/devicetree/bindings/gpio/aspeed,sgpio.yaml b/Documentation/devicetree/bindings/gpio/aspeed,sgpio.yaml new file mode 100644 index 000000000000..46bb121360dc --- /dev/null +++ b/Documentation/devicetree/bindings/gpio/aspeed,sgpio.yaml @@ -0,0 +1,77 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/gpio/aspeed,sgpio.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Aspeed SGPIO controller + +maintainers: + - Andrew Jeffery <andrew@aj.id.au> + +description: + This SGPIO controller is for ASPEED AST2400, AST2500 and AST2600 SoC, + AST2600 have two sgpio master one with 128 pins another one with 80 pins, + AST2500/AST2400 have one sgpio master with 80 pins. Each of the Serial + GPIO pins can be programmed to support the following options + - Support interrupt option for each input port and various interrupt + sensitivity option (level-high, level-low, edge-high, edge-low) + - Support reset tolerance option for each output port + - Directly connected to APB bus and its shift clock is from APB bus clock + divided by a programmable value. + - Co-work with external signal-chained TTL components (74LV165/74LV595) + +properties: + compatible: + enum: + - aspeed,ast2400-sgpio + - aspeed,ast2500-sgpio + - aspeed,ast2600-sgpiom + + reg: + maxItems: 1 + + gpio-controller: true + + '#gpio-cells': + const: 2 + + interrupts: + maxItems: 1 + + interrupt-controller: true + + clocks: + maxItems: 1 + + ngpios: true + + bus-frequency: true + +required: + - compatible + - reg + - gpio-controller + - '#gpio-cells' + - interrupts + - interrupt-controller + - ngpios + - clocks + - bus-frequency + +additionalProperties: false + +examples: + - | + #include <dt-bindings/clock/aspeed-clock.h> + sgpio: sgpio@1e780200 { + #gpio-cells = <2>; + compatible = "aspeed,ast2500-sgpio"; + gpio-controller; + interrupts = <40>; + reg = <0x1e780200 0x0100>; + clocks = <&syscon ASPEED_CLK_APB>; + interrupt-controller; + ngpios = <80>; + bus-frequency = <12000000>; + }; diff --git a/Documentation/devicetree/bindings/gpio/rockchip,gpio-bank.yaml b/Documentation/devicetree/bindings/gpio/rockchip,gpio-bank.yaml index d993e002cebe..0d62c28fb58d 100644 --- a/Documentation/devicetree/bindings/gpio/rockchip,gpio-bank.yaml +++ b/Documentation/devicetree/bindings/gpio/rockchip,gpio-bank.yaml @@ -22,7 +22,10 @@ properties: maxItems: 1 clocks: - maxItems: 1 + minItems: 1 + items: + - description: APB interface clock source + - description: GPIO debounce reference clock source gpio-controller: true diff --git a/Documentation/devicetree/bindings/gpio/sgpio-aspeed.txt b/Documentation/devicetree/bindings/gpio/sgpio-aspeed.txt deleted file mode 100644 index be329ea4794f..000000000000 --- a/Documentation/devicetree/bindings/gpio/sgpio-aspeed.txt +++ /dev/null @@ -1,46 +0,0 @@ -Aspeed SGPIO controller Device Tree Bindings --------------------------------------------- - -This SGPIO controller is for ASPEED AST2500 SoC, it supports up to 80 full -featured Serial GPIOs. Each of the Serial GPIO pins can be programmed to -support the following options: -- Support interrupt option for each input port and various interrupt - sensitivity option (level-high, level-low, edge-high, edge-low) -- Support reset tolerance option for each output port -- Directly connected to APB bus and its shift clock is from APB bus clock - divided by a programmable value. -- Co-work with external signal-chained TTL components (74LV165/74LV595) - -Required properties: - -- compatible : Should be one of - "aspeed,ast2400-sgpio", "aspeed,ast2500-sgpio" -- #gpio-cells : Should be 2, see gpio.txt -- reg : Address and length of the register set for the device -- gpio-controller : Marks the device node as a GPIO controller -- interrupts : Interrupt specifier, see interrupt-controller/interrupts.txt -- interrupt-controller : Mark the GPIO controller as an interrupt-controller -- ngpios : number of *hardware* GPIO lines, see gpio.txt. This will expose - 2 software GPIOs per hardware GPIO: one for hardware input, one for hardware - output. Up to 80 pins, must be a multiple of 8. -- clocks : A phandle to the APB clock for SGPM clock division -- bus-frequency : SGPM CLK frequency - -The sgpio and interrupt properties are further described in their respective -bindings documentation: - -- Documentation/devicetree/bindings/gpio/gpio.txt -- Documentation/devicetree/bindings/interrupt-controller/interrupts.txt - - Example: - sgpio: sgpio@1e780200 { - #gpio-cells = <2>; - compatible = "aspeed,ast2500-sgpio"; - gpio-controller; - interrupts = <40>; - reg = <0x1e780200 0x0100>; - clocks = <&syscon ASPEED_CLK_APB>; - interrupt-controller; - ngpios = <8>; - bus-frequency = <12000000>; - }; diff --git a/Documentation/devicetree/bindings/gpu/arm,mali-bifrost.yaml b/Documentation/devicetree/bindings/gpu/arm,mali-bifrost.yaml index 0f73f436bea7..c5f6092a2855 100644 --- a/Documentation/devicetree/bindings/gpu/arm,mali-bifrost.yaml +++ b/Documentation/devicetree/bindings/gpu/arm,mali-bifrost.yaml @@ -20,6 +20,7 @@ properties: - mediatek,mt8183-mali - realtek,rtd1619-mali - rockchip,px30-mali + - rockchip,rk3568-mali - const: arm,mali-bifrost # Mali Bifrost GPU model/revision is fully discoverable reg: diff --git a/Documentation/devicetree/bindings/hwmon/amd,sbrmi.yaml b/Documentation/devicetree/bindings/hwmon/amd,sbrmi.yaml new file mode 100644 index 000000000000..7598b083979c --- /dev/null +++ b/Documentation/devicetree/bindings/hwmon/amd,sbrmi.yaml @@ -0,0 +1,53 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/hwmon/amd,sbrmi.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: > + Sideband Remote Management Interface (SB-RMI) compliant + AMD SoC power device. + +maintainers: + - Akshay Gupta <Akshay.Gupta@amd.com> + +description: | + SB Remote Management Interface (SB-RMI) is an SMBus compatible + interface that reports AMD SoC's Power (normalized Power) using, + Mailbox Service Request and resembles a typical 8-pin remote power + sensor's I2C interface to BMC. The power attributes in hwmon + reports power in microwatts. + +properties: + compatible: + enum: + - amd,sbrmi + + reg: + maxItems: 1 + description: | + I2C bus address of the device as specified in Section SBI SMBus Address + of the SoC register reference. The SB-RMI address is normally 78h for + socket 0 and 70h for socket 1, but it could vary based on hardware + address select pins. + \[open source SoC register reference\] + https://www.amd.com/en/support/tech-docs?keyword=55898 + +required: + - compatible + - reg + +additionalProperties: false + +examples: + - | + i2c0 { + #address-cells = <1>; + #size-cells = <0>; + + sbrmi@3c { + compatible = "amd,sbrmi"; + reg = <0x3c>; + }; + }; +... diff --git a/Documentation/devicetree/bindings/hwmon/max1619.txt b/Documentation/devicetree/bindings/hwmon/max1619.txt deleted file mode 100644 index c70dbbe1e56f..000000000000 --- a/Documentation/devicetree/bindings/hwmon/max1619.txt +++ /dev/null @@ -1,12 +0,0 @@ -Bindings for MAX1619 Temperature Sensor - -Required properties: -- compatible : "maxim,max1619" -- reg : I2C address, one of 0x18, 0x19, 0x1a, 0x29, 0x2a, 0x2b, 0x4c, or - 0x4d, 0x4e - -Example: - temp@4c { - compatible = "maxim,max1619"; - reg = <0x4c>; - }; diff --git a/Documentation/devicetree/bindings/hwmon/winbond,w83781d.yaml b/Documentation/devicetree/bindings/hwmon/winbond,w83781d.yaml new file mode 100644 index 000000000000..31ce77a4b087 --- /dev/null +++ b/Documentation/devicetree/bindings/hwmon/winbond,w83781d.yaml @@ -0,0 +1,41 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- + +$id: http://devicetree.org/schemas/hwmon/winbond,w83781d.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Winbond W83781 and compatible hardware monitor IC + +maintainers: + - Linus Walleij <linus.walleij@linaro.org> + +properties: + compatible: + enum: + - winbond,w83781d + - winbond,w83781g + - winbond,w83782d + - winbond,w83783s + - asus,as99127f + + reg: + maxItems: 1 + +required: + - compatible + - reg + +additionalProperties: false + +examples: + - | + i2c { + #address-cells = <1>; + #size-cells = <0>; + + temperature-sensor@28 { + compatible = "winbond,w83781d"; + reg = <0x28>; + }; + }; diff --git a/Documentation/devicetree/bindings/i2c/brcm,iproc-i2c.txt b/Documentation/devicetree/bindings/i2c/brcm,iproc-i2c.txt deleted file mode 100644 index d12cc33cca6c..000000000000 --- a/Documentation/devicetree/bindings/i2c/brcm,iproc-i2c.txt +++ /dev/null @@ -1,46 +0,0 @@ -Broadcom iProc I2C controller - -Required properties: - -- compatible: - Must be "brcm,iproc-i2c" or "brcm,iproc-nic-i2c" - -- reg: - Define the base and range of the I/O address space that contain the iProc - I2C controller registers - -- clock-frequency: - This is the I2C bus clock. Need to be either 100000 or 400000 - -- #address-cells: - Always 1 (for I2C addresses) - -- #size-cells: - Always 0 - -Optional properties: - -- interrupts: - Should contain the I2C interrupt. For certain revisions of the I2C - controller, I2C interrupt is unwired to the interrupt controller. In such - case, this property should be left unspecified, and driver will fall back - to polling mode - -- brcm,ape-hsls-addr-mask: - Required for "brcm,iproc-nic-i2c". Host view of address mask into the - 'APE' co-processor. Value must be unsigned, 32-bit - -Example: - i2c0: i2c@18008000 { - compatible = "brcm,iproc-i2c"; - reg = <0x18008000 0x100>; - #address-cells = <1>; - #size-cells = <0>; - interrupts = <GIC_SPI 85 IRQ_TYPE_NONE>; - clock-frequency = <100000>; - - codec: wm8750@1a { - compatible = "wlf,wm8750"; - reg = <0x1a>; - }; - }; diff --git a/Documentation/devicetree/bindings/i2c/brcm,iproc-i2c.yaml b/Documentation/devicetree/bindings/i2c/brcm,iproc-i2c.yaml new file mode 100644 index 000000000000..2aa75b7add7b --- /dev/null +++ b/Documentation/devicetree/bindings/i2c/brcm,iproc-i2c.yaml @@ -0,0 +1,71 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/i2c/brcm,iproc-i2c.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Broadcom iProc I2C controller + +maintainers: + - Rafał Miłecki <rafal@milecki.pl> + +properties: + compatible: + enum: + - brcm,iproc-i2c + - brcm,iproc-nic-i2c + + reg: + maxItems: 1 + + clock-frequency: + enum: [ 100000, 400000 ] + + interrupts: + description: | + Should contain the I2C interrupt. For certain revisions of the I2C + controller, I2C interrupt is unwired to the interrupt controller. In such + case, this property should be left unspecified, and driver will fall back + to polling mode + maxItems: 1 + + brcm,ape-hsls-addr-mask: + $ref: /schemas/types.yaml#/definitions/uint32 + description: Host view of address mask into the 'APE' co-processor + +allOf: + - $ref: /schemas/i2c/i2c-controller.yaml# + - if: + properties: + compatible: + contains: + const: brcm,iproc-nic-i2c + then: + required: + - brcm,ape-hsls-addr-mask + +unevaluatedProperties: false + +required: + - reg + - clock-frequency + - '#address-cells' + - '#size-cells' + +examples: + - | + #include <dt-bindings/interrupt-controller/arm-gic.h> + + i2c@18008000 { + compatible = "brcm,iproc-i2c"; + reg = <0x18008000 0x100>; + #address-cells = <1>; + #size-cells = <0>; + interrupts = <GIC_SPI 85 IRQ_TYPE_NONE>; + clock-frequency = <100000>; + + wm8750@1a { + compatible = "wlf,wm8750"; + reg = <0x1a>; + }; + }; diff --git a/Documentation/devicetree/bindings/i2c/renesas,riic.yaml b/Documentation/devicetree/bindings/i2c/renesas,riic.yaml index 52d92ec7ec0b..402fd125e010 100644 --- a/Documentation/devicetree/bindings/i2c/renesas,riic.yaml +++ b/Documentation/devicetree/bindings/i2c/renesas,riic.yaml @@ -27,14 +27,25 @@ properties: interrupts: items: - - description: Transmit End Interrupt (TEI) - - description: Receive Data Full Interrupt (RI) - - description: Transmit Data Empty Interrupt (TI) - - description: Stop Condition Detection Interrupt (SPI) - - description: Start Condition Detection Interrupt (STI) - - description: NACK Reception Interrupt (NAKI) - - description: Arbitration-Lost Interrupt (ALI) - - description: Timeout Interrupt (TMOI) + - description: Transmit End Interrupt + - description: Receive Data Full Interrupt + - description: Transmit Data Empty Interrupt + - description: Stop Condition Detection Interrupt + - description: Start Condition Detection Interrupt + - description: NACK Reception Interrupt + - description: Arbitration-Lost Interrupt + - description: Timeout Interrupt + + interrupt-names: + items: + - const: tei + - const: ri + - const: ti + - const: spi + - const: sti + - const: naki + - const: ali + - const: tmoi clock-frequency: description: @@ -51,6 +62,7 @@ required: - compatible - reg - interrupts + - interrupt-names - clocks - clock-frequency - power-domains @@ -85,6 +97,8 @@ examples: <GIC_SPI 162 IRQ_TYPE_LEVEL_HIGH>, <GIC_SPI 163 IRQ_TYPE_LEVEL_HIGH>, <GIC_SPI 164 IRQ_TYPE_LEVEL_HIGH>; + interrupt-names = "tei", "ri", "ti", "spi", "sti", "naki", "ali", + "tmoi"; clocks = <&mstp9_clks R7S72100_CLK_I2C0>; clock-frequency = <100000>; power-domains = <&cpg_clocks>; diff --git a/Documentation/devicetree/bindings/i2c/ti,omap4-i2c.yaml b/Documentation/devicetree/bindings/i2c/ti,omap4-i2c.yaml index ff165ad1bee8..db0843be91c5 100644 --- a/Documentation/devicetree/bindings/i2c/ti,omap4-i2c.yaml +++ b/Documentation/devicetree/bindings/i2c/ti,omap4-i2c.yaml @@ -72,11 +72,11 @@ additionalProperties: false if: properties: compatible: - oneOf: - - const: ti,omap2420-i2c - - const: ti,omap2430-i2c - - const: ti,omap3-i2c - - const: ti,omap4-i2c + enum: + - ti,omap2420-i2c + - ti,omap2430-i2c + - ti,omap3-i2c + - ti,omap4-i2c then: properties: diff --git a/Documentation/devicetree/bindings/iio/accel/bosch,bma180.yaml b/Documentation/devicetree/bindings/iio/accel/bosch,bma180.yaml deleted file mode 100644 index a7e84089cc3d..000000000000 --- a/Documentation/devicetree/bindings/iio/accel/bosch,bma180.yaml +++ /dev/null @@ -1,61 +0,0 @@ -# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) -%YAML 1.2 ---- -$id: http://devicetree.org/schemas/iio/accel/bosch,bma180.yaml# -$schema: http://devicetree.org/meta-schemas/core.yaml# - -title: Bosch BMA023 / BMA150/ BMA180 / BMA250 / SMB380 triaxial accelerometers - -maintainers: - - Jonathan Cameron <jic23@kernel.org> - -description: | - https://media.digikey.com/pdf/Data%20Sheets/Bosch/BMA150.pdf - http://omapworld.com/BMA180_111_1002839.pdf - http://ae-bst.resource.bosch.com/media/products/dokumente/bma250/bst-bma250-ds002-05.pdf - -properties: - compatible: - enum: - - bosch,bma023 - - bosch,bma150 - - bosch,bma180 - - bosch,bma250 - - bosch,smb380 - - reg: - maxItems: 1 - - vdd-supply: true - - vddio-supply: true - - interrupts: - minItems: 1 - maxItems: 2 - description: | - Type should be either IRQ_TYPE_LEVEL_HIGH or IRQ_TYPE_EDGE_RISING. - For the bma250 the first interrupt listed must be the one - connected to the INT1 pin, the second (optional) interrupt - listed must be the one connected to the INT2 pin. - -required: - - compatible - - reg - -additionalProperties: false - -examples: - - | - #include <dt-bindings/interrupt-controller/irq.h> - i2c { - #address-cells = <1>; - #size-cells = <0>; - accel@40 { - compatible = "bosch,bma180"; - reg = <0x40>; - interrupt-parent = <&gpio6>; - interrupts = <18 (IRQ_TYPE_LEVEL_HIGH | IRQ_TYPE_EDGE_RISING)>; - }; - }; -... diff --git a/Documentation/devicetree/bindings/iio/accel/bosch,bma255.yaml b/Documentation/devicetree/bindings/iio/accel/bosch,bma255.yaml index e830d5295b92..478e75ae0885 100644 --- a/Documentation/devicetree/bindings/iio/accel/bosch,bma255.yaml +++ b/Documentation/devicetree/bindings/iio/accel/bosch,bma255.yaml @@ -8,6 +8,7 @@ title: Bosch BMA255 and Similar Accelerometers maintainers: - Linus Walleij <linus.walleij@linaro.org> + - Stephan Gerhold <stephan@gerhold.net> description: 3 axis accelerometers with varying range and I2C or SPI @@ -16,15 +17,24 @@ description: properties: compatible: enum: - - bosch,bmc150_accel - - bosch,bmi055_accel + # bmc150-accel driver in Linux + - bosch,bma222 + - bosch,bma222e + - bosch,bma250e - bosch,bma253 - bosch,bma254 - bosch,bma255 - - bosch,bma250e - - bosch,bma222 - - bosch,bma222e - bosch,bma280 + - bosch,bmc150_accel + - bosch,bmc156_accel + - bosch,bmi055_accel + + # bma180 driver in Linux + - bosch,bma023 + - bosch,bma150 + - bosch,bma180 + - bosch,bma250 + - bosch,smb380 reg: maxItems: 1 @@ -36,9 +46,21 @@ properties: minItems: 1 maxItems: 2 description: | - The first interrupt listed must be the one connected to the INT1 pin, - the second (optional) interrupt listed must be the one connected to the - INT2 pin (if available). + Without interrupt-names, the first interrupt listed must be the one + connected to the INT1 pin, the second (optional) interrupt listed must be + the one connected to the INT2 pin (if available). The type should be + IRQ_TYPE_EDGE_RISING. + + BMC156 does not have an INT1 pin, therefore the first interrupt pin is + always treated as INT2. + + interrupt-names: + minItems: 1 + maxItems: 2 + items: + enum: + - INT1 + - INT2 mount-matrix: description: an optional 3x3 mounting rotation matrix. @@ -63,7 +85,22 @@ examples: reg = <0x08>; vddio-supply = <&vddio>; vdd-supply = <&vdd>; - interrupts = <57 IRQ_TYPE_EDGE_FALLING>; + interrupts = <57 IRQ_TYPE_EDGE_RISING>; + interrupt-names = "INT1"; + }; + }; + - | + #include <dt-bindings/interrupt-controller/irq.h> + i2c { + #address-cells = <1>; + #size-cells = <0>; + accelerometer@10 { + compatible = "bosch,bmc156_accel"; + reg = <0x10>; + vddio-supply = <&vddio>; + vdd-supply = <&vdd>; + interrupts = <116 IRQ_TYPE_EDGE_RISING>; + interrupt-names = "INT2"; }; }; - | diff --git a/Documentation/devicetree/bindings/iio/adc/ingenic,adc.yaml b/Documentation/devicetree/bindings/iio/adc/ingenic,adc.yaml index 433a3fb55a2e..3eb7aa8822c3 100644 --- a/Documentation/devicetree/bindings/iio/adc/ingenic,adc.yaml +++ b/Documentation/devicetree/bindings/iio/adc/ingenic,adc.yaml @@ -23,6 +23,8 @@ properties: enum: - ingenic,jz4725b-adc - ingenic,jz4740-adc + - ingenic,jz4760-adc + - ingenic,jz4760b-adc - ingenic,jz4770-adc '#io-channel-cells': @@ -43,6 +45,23 @@ properties: interrupts: maxItems: 1 + ingenic,use-internal-divider: + description: + If present, battery voltage is read from the VBAT_IR pin, which has an + internal 1/4 divider. If absent, it is read through the VBAT_ER pin, + which does not have such a divider. + type: boolean + +if: + not: + properties: + compatible: + contains: + const: ingenic,jz4760b-adc +then: + properties: + ingenic,use-internal-divider: false + required: - compatible - '#io-channel-cells' diff --git a/Documentation/devicetree/bindings/iio/adc/renesas,rzg2l-adc.yaml b/Documentation/devicetree/bindings/iio/adc/renesas,rzg2l-adc.yaml new file mode 100644 index 000000000000..c80201d6a716 --- /dev/null +++ b/Documentation/devicetree/bindings/iio/adc/renesas,rzg2l-adc.yaml @@ -0,0 +1,134 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/iio/adc/renesas,rzg2l-adc.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Renesas RZ/G2L ADC + +maintainers: + - Lad Prabhakar <prabhakar.mahadev-lad.rj@bp.renesas.com> + +description: | + A/D Converter block is a successive approximation analog-to-digital converter + with a 12-bit accuracy. Up to eight analog input channels can be selected. + Conversions can be performed in single or repeat mode. Result of the ADC is + stored in a 32-bit data register corresponding to each channel. + +properties: + compatible: + items: + - enum: + - renesas,r9a07g044-adc # RZ/G2{L,LC} + - const: renesas,rzg2l-adc + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + clocks: + items: + - description: converter clock + - description: peripheral clock + + clock-names: + items: + - const: adclk + - const: pclk + + power-domains: + maxItems: 1 + + resets: + maxItems: 2 + + reset-names: + items: + - const: presetn + - const: adrst-n + + '#address-cells': + const: 1 + + '#size-cells': + const: 0 + +required: + - compatible + - reg + - interrupts + - clocks + - clock-names + - power-domains + - resets + - reset-names + +patternProperties: + "^channel@[0-7]$": + $ref: "adc.yaml" + type: object + description: | + Represents the external channels which are connected to the ADC. + + properties: + reg: + description: | + The channel number. It can have up to 8 channels numbered from 0 to 7. + items: + - minimum: 0 + maximum: 7 + + required: + - reg + + additionalProperties: false + +additionalProperties: false + +examples: + - | + #include <dt-bindings/clock/r9a07g044-cpg.h> + #include <dt-bindings/interrupt-controller/arm-gic.h> + + adc: adc@10059000 { + compatible = "renesas,r9a07g044-adc", "renesas,rzg2l-adc"; + reg = <0x10059000 0x400>; + interrupts = <GIC_SPI 347 IRQ_TYPE_EDGE_RISING>; + clocks = <&cpg CPG_MOD R9A07G044_ADC_ADCLK>, + <&cpg CPG_MOD R9A07G044_ADC_PCLK>; + clock-names = "adclk", "pclk"; + power-domains = <&cpg>; + resets = <&cpg R9A07G044_ADC_PRESETN>, + <&cpg R9A07G044_ADC_ADRST_N>; + reset-names = "presetn", "adrst-n"; + + #address-cells = <1>; + #size-cells = <0>; + + channel@0 { + reg = <0>; + }; + channel@1 { + reg = <1>; + }; + channel@2 { + reg = <2>; + }; + channel@3 { + reg = <3>; + }; + channel@4 { + reg = <4>; + }; + channel@5 { + reg = <5>; + }; + channel@6 { + reg = <6>; + }; + channel@7 { + reg = <7>; + }; + }; diff --git a/Documentation/devicetree/bindings/iio/adc/rockchip-saradc.yaml b/Documentation/devicetree/bindings/iio/adc/rockchip-saradc.yaml index 1bb76197787b..e512a14e41b4 100644 --- a/Documentation/devicetree/bindings/iio/adc/rockchip-saradc.yaml +++ b/Documentation/devicetree/bindings/iio/adc/rockchip-saradc.yaml @@ -20,6 +20,7 @@ properties: - rockchip,px30-saradc - rockchip,rk3308-saradc - rockchip,rk3328-saradc + - rockchip,rk3568-saradc - rockchip,rv1108-saradc - const: rockchip,rk3399-saradc diff --git a/Documentation/devicetree/bindings/iio/dac/adi,ad5064.yaml b/Documentation/devicetree/bindings/iio/dac/adi,ad5064.yaml new file mode 100644 index 000000000000..05ed4e0ec364 --- /dev/null +++ b/Documentation/devicetree/bindings/iio/dac/adi,ad5064.yaml @@ -0,0 +1,268 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/iio/dac/adi,ad5064.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Analog Devices AD5064 and similar DACs + +maintainers: + - Lars-Peter Clausen <lars@metafoo.de> + - Jonathan Cameron <jic23@kernel.org> + +description: | + A range of similar DAC devices with between 1 and 12 channels. Some parts + have internal references, others require a single shared external reference + and the remainder have a separate reference pin for each DAC. + +properties: + compatible: + oneOf: + - description: I2C devics + enum: + - adi,ad5024 + - adi,ad5025 + - adi,ad5044 + - adi,ad5045 + - adi,ad5064 + - adi,ad5064-1 + - adi,ad5065 + - adi,ad5628-1 + - adi,ad5628-2 + - adi,ad5648-1 + - adi,ad5648-2 + - adi,ad5666-1 + - adi,ad5666-2 + - adi,ad5668-1 + - adi,ad5668-2 + - adi,ad5668-3 + - description: SPI devices + enum: + - adi,ad5625 + - adi,ad5625r-1v25 + - adi,ad5625r-2v5 + - adi,ad5627 + - adi,ad5627r-1v25 + - adi,ad5627r-2v5 + - adi,ad5629-1 + - adi,ad5629-2 + - adi,ad5629-3 + - adi,ad5645r-1v25 + - adi,ad5645r-2v5 + - adi,ad5665 + - adi,ad5665r-1v25 + - adi,ad5665r-2v5 + - adi,ad5667 + - adi,ad5667r-1v25 + - adi,ad5667r-2v5 + - adi,ad5669-1 + - adi,ad5669-2 + - adi,ad5669-3 + - lltc,ltc2606 + - lltc,ltc2607 + - lltc,ltc2609 + - lltc,ltc2616 + - lltc,ltc2617 + - lltc,ltc2619 + - lltc,ltc2626 + - lltc,ltc2627 + - lltc,ltc2629 + - lltc,ltc2631-l12 + - lltc,ltc2631-h12 + - lltc,ltc2631-l10 + - lltc,ltc2631-h10 + - lltc,ltc2631-l8 + - lltc,ltc2631-h8 + - lltc,ltc2633-l12 + - lltc,ltc2633-h12 + - lltc,ltc2633-l10 + - lltc,ltc2633-h10 + - lltc,ltc2633-l8 + - lltc,ltc2633-h8 + - lltc,ltc2635-l12 + - lltc,ltc2635-h12 + - lltc,ltc2635-l10 + - lltc,ltc2635-h10 + - lltc,ltc2635-l8 + - lltc,ltc2635-h8 + + reg: + maxItems: 1 + + vrefA-supply: true + vrefB-supply: true + vrefC-supply: true + vrefD-supply: true + vref-supply: true + + spi-max-frequency: true + +additionalProperties: false + +required: + - compatible + - reg + +allOf: + - # Shared external vref, no internal reference + if: + properties: + compatible: + contains: + enum: + - adi,ad5064-1 + - adi,ad5625 + - adi,ad5627 + - adi,ad5665 + - adi,ad5667 + - lltc,ltc2606 + - lltc,ltc2607 + - lltc,ltc2616 + - lltc,ltc2617 + - lltc,ltc2626 + - lltc,ltc2627 + then: + properties: + vref-supply: true + vrefA-supply: false + vrefB-supply: false + vrefC-supply: false + vrefD-supply: false + required: + - vref-supply + - # Shared external vref, internal reference available + if: + properties: + compatible: + contains: + enum: + - adi,ad5625r-1v25 + - adi,ad5625r-2v5 + - adi,ad5627r-1v25 + - adi,ad5627r-2v5 + - adi,ad5628-1 + - adi,ad5628-2 + - adi,ad5629-1 + - adi,ad5629-2 + - adi,ad5629-3 + - adi,ad5645r-1v25 + - adi,ad5645r-2v5 + - adi,ad5647r-1v25 + - adi,ad5647r-2v5 + - adi,ad5648-1 + - adi,ad5648-2 + - adi,ad5665r-1v25 + - adi,ad5665r-2v5 + - adi,ad5666-1 + - adi,ad5666-2 + - adi,ad5667r-1v25 + - adi,ad5667r-2v5 + - adi,ad5668-1 + - adi,ad5668-2 + - adi,ad5668-3 + - adi,ad5669-1 + - adi,ad5669-2 + - adi,ad5669-3 + - lltc,ltc2631-l12 + - lltc,ltc2631-h12 + - lltc,ltc2631-l10 + - lltc,ltc2631-h10 + - lltc,ltc2631-l8 + - lltc,ltc2631-h8 + - lltc,ltc2633-l12 + - lltc,ltc2633-h12 + - lltc,ltc2633-l10 + - lltc,ltc2633-h10 + - lltc,ltc2633-l8 + - lltc,ltc2633-h8 + - lltc,ltc2635-l12 + - lltc,ltc2635-h12 + - lltc,ltc2635-l10 + - lltc,ltc2635-h10 + - lltc,ltc2635-l8 + - lltc,ltc2635-h8 + then: + properties: + vref-supply: true + vrefA-supply: false + vrefB-supply: false + vrefC-supply: false + vrefD-supply: false + - # 4 input devices, separate vrefs, no internal reference + if: + properties: + compatible: + contains: + enum: + - adi,ad5024 + - adi,ad5044 + - adi,ad5064 + - lltc,ltc2609 + - lltc,ltc2619 + - lltc,ltc2629 + then: + properties: + vrefA-supply: true + vrefB-supply: true + vrefC-supply: true + vrefD-supply: true + vref-supply: false + required: + - vrefA-supply + - vrefB-supply + - vrefC-supply + - vrefD-supply + - # 2 input devices, separate vrefs, no internal reference + if: + properties: + compatible: + contains: + enum: + - adi,ad5025 + - adi,ad5045 + - adi,ad5065 + then: + properties: + vrefA-supply: true + vrefB-supply: true + vrefC-supply: false + vrefD-supply: false + vref-supply: false + required: + - vrefA-supply + - vrefB-supply + +examples: + - | + spi { + #address-cells = <1>; + #size-cells = <0>; + dac@0 { + reg = <0>; + compatible = "adi,ad5625"; + vref-supply = <&dac_vref>; + }; + }; + - | + spi { + #address-cells = <1>; + #size-cells = <0>; + dac@0 { + reg = <0>; + compatible = "adi,ad5625r-1v25"; + }; + }; + - | + i2c { + #address-cells = <1>; + #size-cells = <0>; + dac@42 { + reg = <0x42>; + compatible = "adi,ad5024"; + vrefA-supply = <&dac_vref>; + vrefB-supply = <&dac_vref>; + vrefC-supply = <&dac_vref2>; + vrefD-supply = <&dac_vref2>; + }; + }; +... diff --git a/Documentation/devicetree/bindings/iio/dac/adi,ad5360.yaml b/Documentation/devicetree/bindings/iio/dac/adi,ad5360.yaml new file mode 100644 index 000000000000..0d8fb56f4b09 --- /dev/null +++ b/Documentation/devicetree/bindings/iio/dac/adi,ad5360.yaml @@ -0,0 +1,79 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/iio/dac/adi,ad5360.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Analog Devices AD5360 and similar DACs + +maintainers: + - Lars-Peter Clausen <lars@metafoo.de> + - Jonathan Cameron <jic23@kernel.org> + +properties: + compatible: + enum: + - adi,ad5360 + - adi,ad5361 + - adi,ad5363 + - adi,ad5370 + - adi,ad5371 + - adi,ad5372 + - adi,ad5373 + + reg: + maxItems: 1 + + vref0-supply: true + vref1-supply: true + vref2-supply: true + + spi-max-frequency: true + +additionalProperties: false + +required: + - compatible + - reg + - vref0-supply + - vref1-supply + +allOf: + - if: + properties: + compatible: + contains: + enum: + - adi,ad5360 + - adi,ad5361 + - adi,ad5363 + - adi,ad5370 + - adi,ad5372 + - adi,ad5373 + then: + properties: + vref2-supply: false + - if: + properties: + compatible: + contains: + enum: + - adi,ad5371 + then: + required: + - vref2-supply + +examples: + - | + spi { + #address-cells = <1>; + #size-cells = <0>; + dac@0 { + reg = <0>; + compatible = "adi,ad5371"; + vref0-supply = <&dac_vref0>; + vref1-supply = <&dac_vref1>; + vref2-supply = <&dac_vref2>; + }; + }; +... diff --git a/Documentation/devicetree/bindings/iio/dac/adi,ad5380.yaml b/Documentation/devicetree/bindings/iio/dac/adi,ad5380.yaml new file mode 100644 index 000000000000..d599b418a020 --- /dev/null +++ b/Documentation/devicetree/bindings/iio/dac/adi,ad5380.yaml @@ -0,0 +1,70 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/iio/dac/adi,ad5380.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Analog Devices AD5380 and similar DACs + +maintainers: + - Lars-Peter Clausen <lars@metafoo.de> + - Jonathan Cameron <jic23@kernel.org> + +description: | + DAC devices supporting both SPI and I2C interfaces. +properties: + compatible: + enum: + - adi,ad5380-3 + - adi,ad5380-5 + - adi,ad5381-3 + - adi,ad5381-5 + - adi,ad5382-3 + - adi,ad5382-5 + - adi,ad5383-3 + - adi,ad5383-5 + - adi,ad5384-3 + - adi,ad5384-5 + - adi,ad5390-3 + - adi,ad5390-5 + - adi,ad5391-3 + - adi,ad5391-5 + - adi,ad5392-3 + - adi,ad5392-5 + + reg: + maxItems: 1 + + vref-supply: + description: + If not supplied devices will use internal regulators. + + spi-max-frequency: true + +additionalProperties: false + +required: + - compatible + - reg + +examples: + - | + spi { + #address-cells = <1>; + #size-cells = <0>; + dac@0 { + reg = <0>; + compatible = "adi,ad5390-5"; + vref-supply = <&dacvref>; + }; + }; + - | + i2c { + #address-cells = <1>; + #size-cells = <0>; + dac@42 { + reg = <0x42>; + compatible = "adi,ad5380-3"; + }; + }; +... diff --git a/Documentation/devicetree/bindings/iio/dac/adi,ad5421.yaml b/Documentation/devicetree/bindings/iio/dac/adi,ad5421.yaml new file mode 100644 index 000000000000..188f656617e3 --- /dev/null +++ b/Documentation/devicetree/bindings/iio/dac/adi,ad5421.yaml @@ -0,0 +1,51 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/iio/dac/adi,ad5421.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Analog Devices AD5421 DAC + +maintainers: + - Lars-Peter Clausen <lars@metafoo.de> + - Jonathan Cameron <jic23@kernel.org> + +description: | + AD5421 is designed for us in loop-powered, 4 mA to 20 mA smart transmitter + applications. It provides a 16-bit DAC, current amplifier, voltage regulator + to drive the loop and a voltage reference. + +properties: + compatible: + const: adi,ad5421 + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + description: Fault signal. + + spi-max-frequency: true + +required: + - compatible + - reg + +additionalProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/irq.h> + spi { + #address-cells = <1>; + #size-cells = <0>; + + dac@0 { + compatible = "adi,ad5421"; + reg = <0>; + spi-max-frequency = <30000000>; + interrupts = <55 IRQ_TYPE_LEVEL_HIGH>; + }; + }; +... diff --git a/Documentation/devicetree/bindings/iio/dac/adi,ad5449.yaml b/Documentation/devicetree/bindings/iio/dac/adi,ad5449.yaml new file mode 100644 index 000000000000..044332c97743 --- /dev/null +++ b/Documentation/devicetree/bindings/iio/dac/adi,ad5449.yaml @@ -0,0 +1,97 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/iio/dac/adi,ad5449.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Analog Devices AD5449 and similar DACs + +maintainers: + - Lars-Peter Clausen <lars@metafoo.de> + - Jonathan Cameron <jic23@kernel.org> + +description: + Family of multiplying DACs from Analog Devices + +properties: + compatible: + enum: + - adi,ad5415 + - adi,ad5426 + - adi,ad5429 + - adi,ad5432 + - adi,ad5439 + - adi,ad5443 + - adi,ad5449 + + reg: + maxItems: 1 + + spi-max-frequency: true + + VREF-supply: true + VREFA-supply: true + VREFB-supply: true + +additionalProperties: false + +required: + - compatible + - reg + +allOf: + - if: + properties: + compatible: + contains: + enum: + - adi,ad5415 + - adi,ad5426 + - adi,ad5432 + then: + properties: + VREF-supply: true + VREFA-supply: false + VREFB-supply: false + required: + - VREF-supply + - if: + properties: + compatible: + contains: + enum: + - adi,ad5429 + - adi,ad5439 + - adi,ad5449 + then: + properties: + VREF-supply: false + VREFA-supply: true + VREFB-supply: true + required: + - VREFA-supply + - VREFB-supply + +examples: + - | + spi { + #address-cells = <1>; + #size-cells = <0>; + dac@0 { + reg = <0>; + compatible = "adi,ad5415"; + VREF-supply = <&dac_ref>; + }; + }; + - | + spi { + #address-cells = <1>; + #size-cells = <0>; + dac@0 { + reg = <0>; + compatible = "adi,ad5429"; + VREFA-supply = <&dac_refA>; + VREFB-supply = <&dac_refB>; + }; + }; +... diff --git a/Documentation/devicetree/bindings/iio/dac/adi,ad5504.yaml b/Documentation/devicetree/bindings/iio/dac/adi,ad5504.yaml new file mode 100644 index 000000000000..9c2c038683b4 --- /dev/null +++ b/Documentation/devicetree/bindings/iio/dac/adi,ad5504.yaml @@ -0,0 +1,50 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/iio/dac/adi,ad5504.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Analog Devices AD5501 and AD5504 DACs + +maintainers: + - Lars-Peter Clausen <lars@metafoo.de> + - Jonathan Cameron <jic23@kernel.org> + +description: + High voltage (up to 60V) DACs with temperature sensor alarm function + +properties: + compatible: + enum: + - adi,ad5501 + - adi,ad5504 + + reg: + maxItems: 1 + + interrupts: + description: Used for temperature alarm. + maxItems: 1 + + vcc-supply: true + +additionalProperties: false + +required: + - compatible + - reg + +examples: + - | + #include <dt-bindings/interrupt-controller/irq.h> + spi { + #address-cells = <1>; + #size-cells = <0>; + dac@0 { + reg = <0>; + compatible = "adi,ad5504"; + vcc-supply = <&dac_vcc>; + interrupts = <55 IRQ_TYPE_EDGE_FALLING>; + }; + }; +... diff --git a/Documentation/devicetree/bindings/iio/dac/adi,ad5624r.yaml b/Documentation/devicetree/bindings/iio/dac/adi,ad5624r.yaml new file mode 100644 index 000000000000..330383b85eeb --- /dev/null +++ b/Documentation/devicetree/bindings/iio/dac/adi,ad5624r.yaml @@ -0,0 +1,47 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/iio/dac/adi,ad5624r.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Analog Devices AD5624r and similar DACs + +maintainers: + - Jonathan Cameron <jic23@kernel.org> + +properties: + compatible: + enum: + - adi,ad5624r3 + - adi,ad5644r3 + - adi,ad5664r3 + - adi,ad5624r5 + - adi,ad5644r5 + - adi,ad5664r5 + + reg: + maxItems: 1 + + spi-max-frequency: true + + vref-supply: + description: If not present, internal reference will be used. + +additionalProperties: false + +required: + - compatible + - reg + +examples: + - | + spi { + #address-cells = <1>; + #size-cells = <0>; + dac@0 { + reg = <0>; + compatible = "adi,ad5624r3"; + vref-supply = <&vref>; + }; + }; +... diff --git a/Documentation/devicetree/bindings/iio/dac/adi,ad5686.yaml b/Documentation/devicetree/bindings/iio/dac/adi,ad5686.yaml new file mode 100644 index 000000000000..5c26441eae9f --- /dev/null +++ b/Documentation/devicetree/bindings/iio/dac/adi,ad5686.yaml @@ -0,0 +1,75 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/iio/dac/adi,ad5686.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Analog Devices AD5360 and similar DACs + +maintainers: + - Michael Hennerich <michael.hennerich@analog.com> + - Jonathan Cameron <jic23@kernel.org> + +properties: + compatible: + oneOf: + - description: SPI devices + enum: + - adi,ad5310r + - adi,ad5672r + - adi,ad5674r + - adi,ad5676 + - adi,ad5676r + - adi,ad5679r + - adi,ad5681r + - adi,ad5682r + - adi,ad5683 + - adi,ad5683r + - adi,ad5684 + - adi,ad5684r + - adi,ad5685r + - adi,ad5686 + - adi,ad5686r + - description: I2C devices + enum: + - adi,ad5311r + - adi,ad5338r + - adi,ad5671r + - adi,ad5675r + - adi,ad5691r + - adi,ad5692r + - adi,ad5693 + - adi,ad5693r + - adi,ad5694 + - adi,ad5694r + - adi,ad5695r + - adi,ad5696 + - adi,ad5696r + + + reg: + maxItems: 1 + + vcc-supply: + description: If not supplied the internal reference is used. + + spi-max-frequency: true + +additionalProperties: false + +required: + - compatible + - reg + +examples: + - | + spi { + #address-cells = <1>; + #size-cells = <0>; + dac@0 { + reg = <0>; + compatible = "adi,ad5310r"; + vcc-supply = <&dac_vref0>; + }; + }; +... diff --git a/Documentation/devicetree/bindings/iio/dac/adi,ad5761.yaml b/Documentation/devicetree/bindings/iio/dac/adi,ad5761.yaml new file mode 100644 index 000000000000..7f95a9ed55fe --- /dev/null +++ b/Documentation/devicetree/bindings/iio/dac/adi,ad5761.yaml @@ -0,0 +1,60 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/iio/dac/adi,ad5761.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Analog Devices AD5761 and similar DACs + +maintainers: + - Ricardo Ribalda <ribalda@kernel.org> + - Jonathan Cameron <jic23@kernel.org> + +properties: + + compatible: + enum: + - adi,ad5721 + - adi,ad5721r + - adi,ad5761 + - adi,ad5761r + + reg: + maxItems: 1 + + spi-max-frequency: true + + vref-supply: + description: If not supplied, internal reference will be used. + +additionalProperties: false + +required: + - compatible + - reg + +allOf: + - if: + properties: + compatible: + contains: + enum: + - adi,ad5721 + - adi,ad5761 + then: + required: + - vref-supply + +examples: + - | + spi { + #address-cells = <1>; + #size-cells = <0>; + + dac@0 { + compatible = "adi,ad5721"; + reg = <0>; + vref-supply = <&dac_vref>; + }; + }; +... diff --git a/Documentation/devicetree/bindings/iio/dac/adi,ad5764.yaml b/Documentation/devicetree/bindings/iio/dac/adi,ad5764.yaml new file mode 100644 index 000000000000..8e893d52bfb1 --- /dev/null +++ b/Documentation/devicetree/bindings/iio/dac/adi,ad5764.yaml @@ -0,0 +1,62 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/iio/dac/adi,ad5764.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Analog Devices AD5744 and AD5764 DAC families + +maintainers: + - Lars-Peter Clausen <lars@metafoo.de> + - Jonathan Cameron <jic23@kernel.org> + +properties: + + compatible: + enum: + - adi,ad5744 + - adi,ad5744r + - adi,ad5764 + - adi,ad5764r + + reg: + maxItems: 1 + + spi-max-frequency: true + + vrefAB-supply: true + vrefCD-supply: true + +additionalProperties: false + +required: + - compatible + - reg + +allOf: + - if: + properties: + compatible: + contains: + enum: + - adi,ad5744 + - adi,ad5764 + then: + required: + - vrefAB-supply + - vrefCD-supply + +examples: + - | + spi { + #address-cells = <1>; + #size-cells = <0>; + + dac@0 { + compatible = "adi,ad5744"; + reg = <0>; + vrefAB-supply = <&dac_vref>; + vrefCD-supply = <&dac_vref>; + }; + }; +... diff --git a/Documentation/devicetree/bindings/iio/dac/adi,ad5791.yaml b/Documentation/devicetree/bindings/iio/dac/adi,ad5791.yaml new file mode 100644 index 000000000000..650d1ebdcec3 --- /dev/null +++ b/Documentation/devicetree/bindings/iio/dac/adi,ad5791.yaml @@ -0,0 +1,52 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/iio/dac/adi,ad5791.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Analog Devices AD5791 and similar DACs + +maintainers: + - Michael Hennerich <michael.hennerich@analog.com> + - Jonathan Cameron <jic23@kernel.org> + +properties: + + compatible: + enum: + - adi,ad5760 + - adi,ad5780 + - adi,ad5781 + - adi,ad5790 + - adi,ad5791 + + reg: + maxItems: 1 + + spi-max-frequency: true + + vdd-supply: true + vss-supply: true + +additionalProperties: false + +required: + - compatible + - reg + - vdd-supply + - vss-supply + +examples: + - | + spi { + #address-cells = <1>; + #size-cells = <0>; + + dac@0 { + compatible = "adi,ad5791"; + reg = <0>; + vss-supply = <&dac_vss>; + vdd-supply = <&dac_vdd>; + }; + }; +... diff --git a/Documentation/devicetree/bindings/iio/dac/adi,ad8801.yaml b/Documentation/devicetree/bindings/iio/dac/adi,ad8801.yaml new file mode 100644 index 000000000000..6a3990a8d0ad --- /dev/null +++ b/Documentation/devicetree/bindings/iio/dac/adi,ad8801.yaml @@ -0,0 +1,60 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/iio/dac/adi,ad8801.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Analog Devices AD8801 and AD8803 DACs + +maintainers: + - Jonathan Cameron <jic23@kernel.org> + +properties: + + compatible: + enum: + - adi,ad8801 + - adi,ad8803 + + reg: + maxItems: 1 + + spi-max-frequency: true + + vrefh-supply: true + vrefl-supply: true + +additionalProperties: false + +required: + - compatible + - reg + - vrefh-supply + +allOf: + - if: + properties: + compatible: + contains: + const: adi,ad8803 + then: + required: + - vrefl-supply + else: + properties: + vrefl-supply: false + +examples: + - | + spi { + #address-cells = <1>; + #size-cells = <0>; + + dac@0 { + compatible = "adi,ad8803"; + reg = <0>; + vrefl-supply = <&dac_vrefl>; + vrefh-supply = <&dac_vrefh>; + }; + }; +... diff --git a/Documentation/devicetree/bindings/iio/dac/microchip,mcp4922.yaml b/Documentation/devicetree/bindings/iio/dac/microchip,mcp4922.yaml new file mode 100644 index 000000000000..12a14b3f36cb --- /dev/null +++ b/Documentation/devicetree/bindings/iio/dac/microchip,mcp4922.yaml @@ -0,0 +1,46 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/iio/dac/microchip,mcp4922.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Microchip MCP4902, MCP4912 and MPC4922 dual output SPI DACs + +maintainers: + - Jonathan Cameron <jic23@kernel.org> + - Michael Welling <mwelling@ieee.org> + +properties: + compatible: + enum: + - microchip,mcp4902 + - microchip,mcp4912 + - microchip,mcp4922 + + reg: + maxItems: 1 + + spi-max-frequency: true + + vref-supply: true + +additionalProperties: false + +required: + - compatible + - reg + - vref-supply + +examples: + - | + spi { + #address-cells = <1>; + #size-cells = <0>; + + dac@0 { + compatible = "microchip,mcp4912"; + reg = <0>; + vref-supply = <&dac_vref>; + }; + }; +... diff --git a/Documentation/devicetree/bindings/iio/st,st-sensors.yaml b/Documentation/devicetree/bindings/iio/st,st-sensors.yaml index b2a1e42c56fa..71de5631ebae 100644 --- a/Documentation/devicetree/bindings/iio/st,st-sensors.yaml +++ b/Documentation/devicetree/bindings/iio/st,st-sensors.yaml @@ -152,47 +152,6 @@ allOf: maxItems: 1 st,drdy-int-pin: false - - if: - properties: - compatible: - enum: - # Two intertial interrupts i.e. accelerometer/gyro interrupts - - st,h3lis331dl-accel - - st,l3g4200d-gyro - - st,l3g4is-gyro - - st,l3gd20-gyro - - st,l3gd20h-gyro - - st,lis2de12 - - st,lis2dw12 - - st,lis2hh12 - - st,lis2dh12-accel - - st,lis331dl-accel - - st,lis331dlh-accel - - st,lis3de - - st,lis3dh-accel - - st,lis3dhh - - st,lis3mdl-magn - - st,lng2dm-accel - - st,lps331ap-press - - st,lsm303agr-accel - - st,lsm303dlh-accel - - st,lsm303dlhc-accel - - st,lsm303dlm-accel - - st,lsm330-accel - - st,lsm330-gyro - - st,lsm330d-accel - - st,lsm330d-gyro - - st,lsm330dl-accel - - st,lsm330dl-gyro - - st,lsm330dlc-accel - - st,lsm330dlc-gyro - - st,lsm9ds0-gyro - - st,lsm9ds1-magn - then: - properties: - interrupts: - maxItems: 2 - required: - compatible - reg diff --git a/Documentation/devicetree/bindings/interconnect/qcom,osm-l3.yaml b/Documentation/devicetree/bindings/interconnect/qcom,osm-l3.yaml index d6a95c3cb26f..e701524ee811 100644 --- a/Documentation/devicetree/bindings/interconnect/qcom,osm-l3.yaml +++ b/Documentation/devicetree/bindings/interconnect/qcom,osm-l3.yaml @@ -18,6 +18,7 @@ properties: compatible: enum: - qcom,sc7180-osm-l3 + - qcom,sc8180x-osm-l3 - qcom,sdm845-osm-l3 - qcom,sm8150-osm-l3 - qcom,sm8250-epss-l3 diff --git a/Documentation/devicetree/bindings/interconnect/qcom,rpmh.yaml b/Documentation/devicetree/bindings/interconnect/qcom,rpmh.yaml index 5accc0d113be..3fd1a134162d 100644 --- a/Documentation/devicetree/bindings/interconnect/qcom,rpmh.yaml +++ b/Documentation/devicetree/bindings/interconnect/qcom,rpmh.yaml @@ -49,6 +49,17 @@ properties: - qcom,sc7280-mmss-noc - qcom,sc7280-nsp-noc - qcom,sc7280-system-noc + - qcom,sc8180x-aggre1-noc + - qcom,sc8180x-aggre2-noc + - qcom,sc8180x-camnoc-virt + - qcom,sc8180x-compute-noc + - qcom,sc8180x-config-noc + - qcom,sc8180x-dc-noc + - qcom,sc8180x-gem-noc + - qcom,sc8180x-ipa-virt + - qcom,sc8180x-mc-virt + - qcom,sc8180x-mmss-noc + - qcom,sc8180x-system-noc - qcom,sdm845-aggre1-noc - qcom,sdm845-aggre2-noc - qcom,sdm845-config-noc diff --git a/Documentation/devicetree/bindings/interrupt-controller/loongson,liointc.yaml b/Documentation/devicetree/bindings/interrupt-controller/loongson,liointc.yaml index edf26452dc72..750cc44628e9 100644 --- a/Documentation/devicetree/bindings/interrupt-controller/loongson,liointc.yaml +++ b/Documentation/devicetree/bindings/interrupt-controller/loongson,liointc.yaml @@ -19,10 +19,10 @@ allOf: properties: compatible: - oneOf: - - const: loongson,liointc-1.0 - - const: loongson,liointc-1.0a - - const: loongson,liointc-2.0 + enum: + - loongson,liointc-1.0 + - loongson,liointc-1.0a + - loongson,liointc-2.0 reg: minItems: 1 diff --git a/Documentation/devicetree/bindings/interrupt-controller/samsung,exynos4210-combiner.txt b/Documentation/devicetree/bindings/interrupt-controller/samsung,exynos4210-combiner.txt deleted file mode 100644 index 19af687858a1..000000000000 --- a/Documentation/devicetree/bindings/interrupt-controller/samsung,exynos4210-combiner.txt +++ /dev/null @@ -1,50 +0,0 @@ -* Samsung Exynos Interrupt Combiner Controller - -Samsung's Exynos4 architecture includes a interrupt combiner controller which -can combine interrupt sources as a group and provide a single interrupt request -for the group. The interrupt request from each group are connected to a parent -interrupt controller, such as GIC in case of Exynos4210. - -The interrupt combiner controller consists of multiple combiners. Up to eight -interrupt sources can be connected to a combiner. The combiner outputs one -combined interrupt for its eight interrupt sources. The combined interrupt -is usually connected to a parent interrupt controller. - -A single node in the device tree is used to describe the interrupt combiner -controller module (which includes multiple combiners). A combiner in the -interrupt controller module shares config/control registers with other -combiners. For example, a 32-bit interrupt enable/disable config register -can accommodate up to 4 interrupt combiners (with each combiner supporting -up to 8 interrupt sources). - -Required properties: -- compatible: should be "samsung,exynos4210-combiner". -- interrupt-controller: Identifies the node as an interrupt controller. -- #interrupt-cells: should be <2>. The meaning of the cells are - * First Cell: Combiner Group Number. - * Second Cell: Interrupt number within the group. -- reg: Base address and size of interrupt combiner registers. -- interrupts: The list of interrupts generated by the combiners which are then - connected to a parent interrupt controller. The format of the interrupt - specifier depends in the interrupt parent controller. - -Optional properties: -- samsung,combiner-nr: The number of interrupt combiners supported. If this - property is not specified, the default number of combiners is assumed - to be 16. - - -Example: - - The following is a an example from the Exynos4210 SoC dtsi file. - - combiner:interrupt-controller@10440000 { - compatible = "samsung,exynos4210-combiner"; - interrupt-controller; - #interrupt-cells = <2>; - reg = <0x10440000 0x1000>; - interrupts = <0 0 0>, <0 1 0>, <0 2 0>, <0 3 0>, - <0 4 0>, <0 5 0>, <0 6 0>, <0 7 0>, - <0 8 0>, <0 9 0>, <0 10 0>, <0 11 0>, - <0 12 0>, <0 13 0>, <0 14 0>, <0 15 0>; - }; diff --git a/Documentation/devicetree/bindings/interrupt-controller/samsung,exynos4210-combiner.yaml b/Documentation/devicetree/bindings/interrupt-controller/samsung,exynos4210-combiner.yaml new file mode 100644 index 000000000000..d631b7589d50 --- /dev/null +++ b/Documentation/devicetree/bindings/interrupt-controller/samsung,exynos4210-combiner.yaml @@ -0,0 +1,96 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/interrupt-controller/samsung,exynos4210-combiner.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Samsung Exynos SoC Interrupt Combiner Controller + +maintainers: + - Krzysztof Kozlowski <krzysztof.kozlowski@canonical.com> + +description: | + Samsung's Exynos4 architecture includes a interrupt combiner controller which + can combine interrupt sources as a group and provide a single interrupt + request for the group. The interrupt request from each group are connected to + a parent interrupt controller, such as GIC in case of Exynos4210. + + The interrupt combiner controller consists of multiple combiners. Up to eight + interrupt sources can be connected to a combiner. The combiner outputs one + combined interrupt for its eight interrupt sources. The combined interrupt is + usually connected to a parent interrupt controller. + + A single node in the device tree is used to describe the interrupt combiner + controller module (which includes multiple combiners). A combiner in the + interrupt controller module shares config/control registers with other + combiners. For example, a 32-bit interrupt enable/disable config register can + accommodate up to 4 interrupt combiners (with each combiner supporting up to + 8 interrupt sources). + +allOf: + - $ref: /schemas/interrupt-controller.yaml# + +properties: + compatible: + const: samsung,exynos4210-combiner + + interrupt-controller: true + + interrupts: + minItems: 8 + maxItems: 32 + + "#interrupt-cells": + description: | + The meaning of the cells are: + * First Cell: Combiner Group Number. + * Second Cell: Interrupt number within the group. + const: 2 + + reg: + maxItems: 1 + + samsung,combiner-nr: + description: | + The number of interrupt combiners supported. Should match number + of interrupts set in "interrupts" property. + $ref: /schemas/types.yaml#/definitions/uint32 + minimum: 8 + maximum: 32 + default: 16 + +required: + - compatible + - interrupt-controller + - interrupts + - "#interrupt-cells" + - reg + +additionalProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/arm-gic.h> + + interrupt-controller@10440000 { + compatible = "samsung,exynos4210-combiner"; + interrupt-controller; + #interrupt-cells = <2>; + reg = <0x10440000 0x1000>; + interrupts = <GIC_SPI 0 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 1 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 2 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 3 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 4 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 5 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 6 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 7 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 8 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 9 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 10 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 11 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 12 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 13 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 14 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 15 IRQ_TYPE_LEVEL_HIGH>; + }; diff --git a/Documentation/devicetree/bindings/interrupt-controller/ti,pruss-intc.yaml b/Documentation/devicetree/bindings/interrupt-controller/ti,pruss-intc.yaml index 051beb45d998..65523d9459d8 100644 --- a/Documentation/devicetree/bindings/interrupt-controller/ti,pruss-intc.yaml +++ b/Documentation/devicetree/bindings/interrupt-controller/ti,pruss-intc.yaml @@ -46,7 +46,7 @@ properties: AM437x family of SoCs, AM57xx family of SoCs 66AK2G family of SoCs - Use "ti,icssg-intc" for K3 AM65x & J721E family of SoCs + Use "ti,icssg-intc" for K3 AM65x, J721E and AM64x family of SoCs reg: maxItems: 1 @@ -95,6 +95,8 @@ properties: - AM65x and J721E SoCs have "host_intr5", "host_intr6" and "host_intr7" interrupts connected to MPU, and other ICSSG instances. + - AM64x SoCs have all the 8 host interrupts connected to various + other SoC entities required: - compatible diff --git a/Documentation/devicetree/bindings/iommu/apple,dart.yaml b/Documentation/devicetree/bindings/iommu/apple,dart.yaml new file mode 100644 index 000000000000..94aa9e9afa59 --- /dev/null +++ b/Documentation/devicetree/bindings/iommu/apple,dart.yaml @@ -0,0 +1,81 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/iommu/apple,dart.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Apple DART IOMMU + +maintainers: + - Sven Peter <sven@svenpeter.dev> + +description: |+ + Apple SoCs may contain an implementation of their Device Address + Resolution Table which provides a mandatory layer of address + translations for various masters. + + Each DART instance is capable of handling up to 16 different streams + with individual pagetables and page-level read/write protection flags. + + This DART IOMMU also raises interrupts in response to various + fault conditions. + +properties: + compatible: + const: apple,t8103-dart + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + clocks: + description: + Reference to the gate clock phandle if required for this IOMMU. + Optional since not all IOMMUs are attached to a clock gate. + + '#iommu-cells': + const: 1 + description: + Has to be one. The single cell describes the stream id emitted by + a master to the IOMMU. + +required: + - compatible + - reg + - '#iommu-cells' + - interrupts + +additionalProperties: false + +examples: + - |+ + dart1: iommu@82f80000 { + compatible = "apple,t8103-dart"; + reg = <0x82f80000 0x4000>; + interrupts = <1 781 4>; + #iommu-cells = <1>; + }; + + master1 { + iommus = <&dart1 0>; + }; + + - |+ + dart2a: iommu@82f00000 { + compatible = "apple,t8103-dart"; + reg = <0x82f00000 0x4000>; + interrupts = <1 781 4>; + #iommu-cells = <1>; + }; + dart2b: iommu@82f80000 { + compatible = "apple,t8103-dart"; + reg = <0x82f80000 0x4000>; + interrupts = <1 781 4>; + #iommu-cells = <1>; + }; + + master2 { + iommus = <&dart2a 0>, <&dart2b 1>; + }; diff --git a/Documentation/devicetree/bindings/leds/common.yaml b/Documentation/devicetree/bindings/leds/common.yaml index b1f363747a62..697102707703 100644 --- a/Documentation/devicetree/bindings/leds/common.yaml +++ b/Documentation/devicetree/bindings/leds/common.yaml @@ -128,6 +128,12 @@ properties: as a panic indicator. type: boolean + retain-state-shutdown: + description: + This property specifies that the LED should not be turned off or changed + when the system shuts down. + type: boolean + trigger-sources: description: | List of devices which should be used as a source triggering this LED diff --git a/Documentation/devicetree/bindings/mailbox/mtk-gce.txt b/Documentation/devicetree/bindings/mailbox/mtk-gce.txt index 7771ecaac586..89a59b9c81f9 100644 --- a/Documentation/devicetree/bindings/mailbox/mtk-gce.txt +++ b/Documentation/devicetree/bindings/mailbox/mtk-gce.txt @@ -9,8 +9,8 @@ CMDQ driver uses mailbox framework for communication. Please refer to mailbox.txt for generic information about mailbox device-tree bindings. Required properties: -- compatible: can be "mediatek,mt8173-gce", "mediatek,mt8183-gce" or - "mediatek,mt6779-gce". +- compatible: can be "mediatek,mt8173-gce", "mediatek,mt8183-gce", + "mediatek,mt8192-gce", "mediatek,mt8195-gce" or "mediatek,mt6779-gce". - reg: Address range of the GCE unit - interrupts: The interrupt signal from the GCE block - clock: Clocks according to the common clock binding @@ -35,9 +35,14 @@ Optional properties for a client device: start_offset: the start offset of register address that GCE can access. size: the total size of register address that GCE can access. +Optional properties for a client mutex node: +- mediatek,gce-events: GCE events used by clients. The event numbers are + defined in 'dt-bindings/gce/<chip>-gce.h'. + Some vaules of properties are defined in 'dt-bindings/gce/mt8173-gce.h', -'dt-binding/gce/mt8183-gce.h' or 'dt-bindings/gce/mt6779-gce.h'. Such as -sub-system ids, thread priority, event ids. +'dt-binding/gce/mt8183-gce.h', 'dt-binding/gce/mt8192-gce.h', +'dt-binding/gce/mt8195-gce.h' or 'dt-bindings/gce/mt6779-gce.h'. +Such as sub-system ids, thread priority, event ids. Example: @@ -62,3 +67,14 @@ Example for a client device: <&gce SUBSYS_1401XXXX 0x2000 0x100>; ... }; + +Example for a client mutex node: + mutex: mutex@14020000 { + compatible = "mediatek,mt8173-disp-mutex"; + reg = <0 0x14020000 0 0x1000>; + interrupts = <GIC_SPI 169 IRQ_TYPE_LEVEL_LOW>; + power-domains = <&scpsys MT8173_POWER_DOMAIN_MM>; + clocks = <&mmsys CLK_MM_MUTEX_32K>; + mediatek,gce-events = <CMDQ_EVENT_MUTEX0_STREAM_EOF>, + <CMDQ_EVENT_MUTEX1_STREAM_EOF>; + }; diff --git a/Documentation/devicetree/bindings/mailbox/qcom,apcs-kpss-global.yaml b/Documentation/devicetree/bindings/mailbox/qcom,apcs-kpss-global.yaml index 8878ec00820e..6395281b0cec 100644 --- a/Documentation/devicetree/bindings/mailbox/qcom,apcs-kpss-global.yaml +++ b/Documentation/devicetree/bindings/mailbox/qcom,apcs-kpss-global.yaml @@ -20,6 +20,7 @@ properties: - qcom,ipq8074-apcs-apps-global - qcom,msm8916-apcs-kpss-global - qcom,msm8939-apcs-kpss-global + - qcom,msm8953-apcs-kpss-global - qcom,msm8994-apcs-kpss-global - qcom,msm8996-apcs-hmss-global - qcom,msm8998-apcs-hmss-global @@ -29,6 +30,7 @@ properties: - qcom,sdm660-apcs-hmss-global - qcom,sdm845-apss-shared - qcom,sm6125-apcs-hmss-global + - qcom,sm6115-apcs-hmss-global - qcom,sm8150-apss-shared reg: diff --git a/Documentation/devicetree/bindings/mailbox/qcom-ipcc.yaml b/Documentation/devicetree/bindings/mailbox/qcom-ipcc.yaml index b222f993b232..866efb278813 100644 --- a/Documentation/devicetree/bindings/mailbox/qcom-ipcc.yaml +++ b/Documentation/devicetree/bindings/mailbox/qcom-ipcc.yaml @@ -24,6 +24,7 @@ properties: compatible: items: - enum: + - qcom,sm6350-ipcc - qcom,sm8250-ipcc - qcom,sm8350-ipcc - qcom,sc7280-ipcc diff --git a/Documentation/devicetree/bindings/media/amlogic,meson-ir-tx.yaml b/Documentation/devicetree/bindings/media/amlogic,meson-ir-tx.yaml new file mode 100644 index 000000000000..4432fea32650 --- /dev/null +++ b/Documentation/devicetree/bindings/media/amlogic,meson-ir-tx.yaml @@ -0,0 +1,60 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) + +%YAML 1.2 +--- +$id: "http://devicetree.org/schemas/media/amlogic,meson-ir-tx.yaml#" +$schema: "http://devicetree.org/meta-schemas/core.yaml#" + +title: Amlogic Meson IR transmitter + +maintainers: + - Viktor Prutyanov <viktor.prutyanov@phystech.edu> + +description: | + Some Amlogic SoCs such as A311D and T950D4 have IR transmitter + (also called blaster) controller onboard. It is capable of + sending IR signals with arbitrary carrier frequency and duty cycle. + +properties: + compatible: + oneOf: + - const: amlogic,meson-ir-tx + - items: + - const: amlogic,meson-g12a-ir-tx + - const: amlogic,meson-ir-tx + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + clocks: + maxItems: 2 + + clock-names: + items: + - const: sysclk + - const: xtal + +required: + - compatible + - reg + - interrupts + - clocks + - clock-names + +additionalProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/irq.h> + #include <dt-bindings/clock/g12a-clkc.h> + + ir@ff80014c { + compatible = "amlogic,meson-g12a-ir-tx", "amlogic,meson-ir-tx"; + reg = <0xff80014c 0x10>; + interrupts = <0 198 IRQ_TYPE_EDGE_RISING>; + clocks = <&clkc CLKID_CLK81>, <&xtal>; + clock-names = "sysclk", "xtal"; + }; diff --git a/Documentation/devicetree/bindings/media/atmel,isc.yaml b/Documentation/devicetree/bindings/media/atmel,isc.yaml index 3e4bb8892d94..cd6d7af0c768 100644 --- a/Documentation/devicetree/bindings/media/atmel,isc.yaml +++ b/Documentation/devicetree/bindings/media/atmel,isc.yaml @@ -44,7 +44,8 @@ properties: const: isc-mck port: - $ref: /schemas/graph.yaml#/properties/port + $ref: /schemas/graph.yaml#/$defs/port-base + unevaluatedProperties: false description: Input port node, single endpoint describing the input pad. diff --git a/Documentation/devicetree/bindings/media/i2c/adv7180.yaml b/Documentation/devicetree/bindings/media/i2c/adv7180.yaml index 3ce4af143a3a..c8d887eee3bb 100644 --- a/Documentation/devicetree/bindings/media/i2c/adv7180.yaml +++ b/Documentation/devicetree/bindings/media/i2c/adv7180.yaml @@ -35,6 +35,14 @@ properties: powerdown-gpios: maxItems: 1 + reset-gpios: + maxItems: 1 + + adv,force-bt656-4: + description: + Indicates that the output is a BT.656-4 compatible stream. + type: boolean + port: $ref: /schemas/graph.yaml#/$defs/port-base unevaluatedProperties: false diff --git a/Documentation/devicetree/bindings/media/i2c/mipi-ccs.yaml b/Documentation/devicetree/bindings/media/i2c/mipi-ccs.yaml index 701f4e0d138f..39395ea8c318 100644 --- a/Documentation/devicetree/bindings/media/i2c/mipi-ccs.yaml +++ b/Documentation/devicetree/bindings/media/i2c/mipi-ccs.yaml @@ -83,10 +83,10 @@ properties: link-frequencies: true data-lanes: true bus-type: - oneOf: - - const: 1 # CSI-2 C-PHY - - const: 3 # CCP2 - - const: 4 # CSI-2 D-PHY + enum: + - 1 # CSI-2 C-PHY + - 3 # CCP2 + - 4 # CSI-2 D-PHY required: - link-frequencies diff --git a/Documentation/devicetree/bindings/media/i2c/ovti,ov9282.yaml b/Documentation/devicetree/bindings/media/i2c/ovti,ov9282.yaml new file mode 100644 index 000000000000..ad42992c6da3 --- /dev/null +++ b/Documentation/devicetree/bindings/media/i2c/ovti,ov9282.yaml @@ -0,0 +1,91 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +# Copyright (C) 2021 Intel Corporation +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/media/i2c/ovti,ov9282.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: OmniVision OV9282 Sensor + +maintainers: + - Paul J. Murphy <paul.j.murphy@intel.com> + - Daniele Alessandrelli <daniele.alessandrelli@intel.com> + +description: + OV9282 sensor is an OmniVision black & white CMOS active pixel digital image + sensor with an active array size of 1296H x 816V. It is programmable through + I2C interface. The I2C client address is fixed to 0x60/0x70 as per sensor data + sheet. Image data is sent through MIPI CSI-2. + +properties: + compatible: + const: ovti,ov9282 + reg: + description: I2C address + maxItems: 1 + + assigned-clocks: true + assigned-clock-parents: true + assigned-clock-rates: true + + clocks: + description: Clock frequency from 6 to 27MHz + maxItems: 1 + + reset-gpios: + description: Reference to the GPIO connected to the XCLR pin, if any. + maxItems: 1 + + port: + additionalProperties: false + $ref: /schemas/graph.yaml#/properties/port + + properties: + endpoint: + $ref: /schemas/media/video-interfaces.yaml# + unevaluatedProperties: false + + properties: + data-lanes: true + link-frequencies: true + + required: + - data-lanes + - link-frequencies + + required: + - endpoint + +required: + - compatible + - reg + - clocks + - port + +additionalProperties: false + +examples: + - | + i2c0 { + #address-cells = <1>; + #size-cells = <0>; + + camera@60 { + compatible = "ovti,ov9282"; + reg = <0x60>; + clocks = <&ov9282_clk>; + + assigned-clocks = <&ov9282_clk>; + assigned-clock-parents = <&ov9282_clk_parent>; + assigned-clock-rates = <24000000>; + + port { + ov9282: endpoint { + remote-endpoint = <&cam>; + data-lanes = <1 2>; + link-frequencies = /bits/ 64 <800000000>; + }; + }; + }; + }; +... diff --git a/Documentation/devicetree/bindings/media/i2c/sony,imx335.yaml b/Documentation/devicetree/bindings/media/i2c/sony,imx335.yaml new file mode 100644 index 000000000000..881f79532501 --- /dev/null +++ b/Documentation/devicetree/bindings/media/i2c/sony,imx335.yaml @@ -0,0 +1,91 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +# Copyright (C) 2021 Intel Corporation +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/media/i2c/sony,imx335.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Sony IMX335 Sensor + +maintainers: + - Paul J. Murphy <paul.j.murphy@intel.com> + - Daniele Alessandrelli <daniele.alessandrelli@intel.com> + +description: + IMX335 sensor is a Sony CMOS active pixel digital image sensor with an active + array size of 2592H x 1944V. It is programmable through I2C interface. The + I2C client address is fixed to 0x1a as per sensor data sheet. Image data is + sent through MIPI CSI-2. + +properties: + compatible: + const: sony,imx335 + reg: + description: I2C address + maxItems: 1 + + assigned-clocks: true + assigned-clock-parents: true + assigned-clock-rates: true + + clocks: + description: Clock frequency from 6 to 27 MHz, 37.125MHz, 74.25MHz + maxItems: 1 + + reset-gpios: + description: Reference to the GPIO connected to the XCLR pin, if any. + maxItems: 1 + + port: + additionalProperties: false + $ref: /schemas/graph.yaml#/properties/port + + properties: + endpoint: + $ref: /schemas/media/video-interfaces.yaml# + unevaluatedProperties: false + + properties: + data-lanes: true + link-frequencies: true + + required: + - data-lanes + - link-frequencies + + required: + - endpoint + +required: + - compatible + - reg + - clocks + - port + +additionalProperties: false + +examples: + - | + i2c0 { + #address-cells = <1>; + #size-cells = <0>; + + camera@1a { + compatible = "sony,imx335"; + reg = <0x1a>; + clocks = <&imx335_clk>; + + assigned-clocks = <&imx335_clk>; + assigned-clock-parents = <&imx335_clk_parent>; + assigned-clock-rates = <24000000>; + + port { + imx335: endpoint { + remote-endpoint = <&cam>; + data-lanes = <1 2 3 4>; + link-frequencies = /bits/ 64 <594000000>; + }; + }; + }; + }; +... diff --git a/Documentation/devicetree/bindings/media/i2c/sony,imx412.yaml b/Documentation/devicetree/bindings/media/i2c/sony,imx412.yaml new file mode 100644 index 000000000000..1edeabf39e6a --- /dev/null +++ b/Documentation/devicetree/bindings/media/i2c/sony,imx412.yaml @@ -0,0 +1,91 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +# Copyright (C) 2021 Intel Corporation +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/media/i2c/sony,imx412.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Sony IMX412 Sensor + +maintainers: + - Paul J. Murphy <paul.j.murphy@intel.com> + - Daniele Alessandrelli <daniele.alessandrelli@intel.com> + +description: + IMX412 sensor is a Sony CMOS active pixel digital image sensor with an active + array size of 4072H x 3176V. It is programmable through I2C interface. The + I2C client address is fixed to 0x1a as per sensor data sheet. Image data is + sent through MIPI CSI-2. + +properties: + compatible: + const: sony,imx412 + reg: + description: I2C address + maxItems: 1 + + assigned-clocks: true + assigned-clock-parents: true + assigned-clock-rates: true + + clocks: + description: Clock frequency 6MHz, 12MHz, 18MHz, 24MHz or 27MHz + maxItems: 1 + + reset-gpios: + description: Reference to the GPIO connected to the XCLR pin, if any. + maxItems: 1 + + port: + additionalProperties: false + $ref: /schemas/graph.yaml#/properties/port + + properties: + endpoint: + $ref: /schemas/media/video-interfaces.yaml# + unevaluatedProperties: false + + properties: + data-lanes: true + link-frequencies: true + + required: + - data-lanes + - link-frequencies + + required: + - endpoint + +required: + - compatible + - reg + - clocks + - port + +additionalProperties: false + +examples: + - | + i2c0 { + #address-cells = <1>; + #size-cells = <0>; + + camera@1a { + compatible = "sony,imx412"; + reg = <0x1a>; + clocks = <&imx412_clk>; + + assigned-clocks = <&imx412_clk>; + assigned-clock-parents = <&imx412_clk_parent>; + assigned-clock-rates = <24000000>; + + port { + imx412: endpoint { + remote-endpoint = <&cam>; + data-lanes = <1 2 3 4>; + link-frequencies = /bits/ 64 <600000000>; + }; + }; + }; + }; +... diff --git a/Documentation/devicetree/bindings/media/microchip,xisc.yaml b/Documentation/devicetree/bindings/media/microchip,xisc.yaml index 41afe2e5f133..086e1430af4f 100644 --- a/Documentation/devicetree/bindings/media/microchip,xisc.yaml +++ b/Documentation/devicetree/bindings/media/microchip,xisc.yaml @@ -52,7 +52,7 @@ properties: of the data and clock lines. port: - $ref: /schemas/graph.yaml#/properties/port + $ref: /schemas/graph.yaml#/$defs/port-base description: Input port node, single endpoint describing the input pad. diff --git a/Documentation/devicetree/bindings/media/nxp,imx7-csi.yaml b/Documentation/devicetree/bindings/media/nxp,imx7-csi.yaml index d91575b8ebb9..5922a2795167 100644 --- a/Documentation/devicetree/bindings/media/nxp,imx7-csi.yaml +++ b/Documentation/devicetree/bindings/media/nxp,imx7-csi.yaml @@ -4,7 +4,7 @@ $id: http://devicetree.org/schemas/media/nxp,imx7-csi.yaml# $schema: http://devicetree.org/meta-schemas/core.yaml# -title: i.MX7 CMOS Sensor Interface +title: i.MX7 and i.MX8 CSI bridge (CMOS Sensor Interface) maintainers: - Rui Miguel Silva <rmfrfs@gmail.com> @@ -15,9 +15,13 @@ description: | properties: compatible: - enum: - - fsl,imx7-csi - - fsl,imx6ul-csi + oneOf: + - enum: + - fsl,imx7-csi + - fsl,imx6ul-csi + - items: + - const: fsl,imx8mm-csi + - const: fsl,imx7-csi reg: maxItems: 1 diff --git a/Documentation/devicetree/bindings/media/nxp,imx7-mipi-csi2.yaml b/Documentation/devicetree/bindings/media/nxp,imx7-mipi-csi2.yaml index 7c09eec78ce5..877183cf4278 100644 --- a/Documentation/devicetree/bindings/media/nxp,imx7-mipi-csi2.yaml +++ b/Documentation/devicetree/bindings/media/nxp,imx7-mipi-csi2.yaml @@ -200,8 +200,6 @@ examples: clock-names = "pclk", "wrap", "phy", "axi"; power-domains = <&mipi_pd>; - status = "disabled"; - ports { #address-cells = <1>; #size-cells = <0>; diff --git a/Documentation/devicetree/bindings/media/nxp,imx8-jpeg.yaml b/Documentation/devicetree/bindings/media/nxp,imx8-jpeg.yaml index 5d13cbb5251b..3cc6f42aeb76 100644 --- a/Documentation/devicetree/bindings/media/nxp,imx8-jpeg.yaml +++ b/Documentation/devicetree/bindings/media/nxp,imx8-jpeg.yaml @@ -16,12 +16,17 @@ description: |- properties: compatible: - items: - - enum: - # JPEG decoder - - nxp,imx8qxp-jpgdec - # JPEG encoder - - nxp,imx8qxp-jpgenc + oneOf: + - items: + enum: + - nxp,imx8qxp-jpgdec + - nxp,imx8qxp-jpgenc + - items: + - const: nxp,imx8qm-jpgdec + - const: nxp,imx8qxp-jpgdec + - items: + - const: nxp,imx8qm-jpgenc + - const: nxp,imx8qxp-jpgenc reg: maxItems: 1 @@ -69,7 +74,7 @@ examples: }; jpegenc: jpegenc@58450000 { - compatible = "nxp,imx8qxp-jpgenc"; + compatible = "nxp,imx8qm-jpgenc", "nxp,imx8qxp-jpgenc"; reg = <0x58450000 0x00050000 >; interrupts = <GIC_SPI 305 IRQ_TYPE_LEVEL_HIGH>, <GIC_SPI 306 IRQ_TYPE_LEVEL_HIGH>, diff --git a/Documentation/devicetree/bindings/media/nxp,imx8mq-mipi-csi2.yaml b/Documentation/devicetree/bindings/media/nxp,imx8mq-mipi-csi2.yaml new file mode 100644 index 000000000000..9c04fa85ee5c --- /dev/null +++ b/Documentation/devicetree/bindings/media/nxp,imx8mq-mipi-csi2.yaml @@ -0,0 +1,174 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/media/nxp,imx8mq-mipi-csi2.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: NXP i.MX8MQ MIPI CSI-2 receiver + +maintainers: + - Martin Kepplinger <martin.kepplinger@puri.sm> + +description: |- + This binding covers the CSI-2 RX PHY and host controller included in the + NXP i.MX8MQ SoC. It handles the sensor/image input and process for all the + input imaging devices. + +properties: + compatible: + enum: + - fsl,imx8mq-mipi-csi2 + + reg: + maxItems: 1 + + clocks: + items: + - description: core is the RX Controller Core Clock input. This clock + must be exactly equal to or faster than the receive + byteclock from the RX DPHY. + - description: esc is the Rx Escape Clock. This must be the same escape + clock that the RX DPHY receives. + - description: ui is the pixel clock (phy_ref up to 333Mhz). + See the reference manual for details. + + clock-names: + items: + - const: core + - const: esc + - const: ui + + power-domains: + maxItems: 1 + + resets: + items: + - description: CORE_RESET reset register bit definition + - description: PHY_REF_RESET reset register bit definition + - description: ESC_RESET reset register bit definition + + fsl,mipi-phy-gpr: + description: | + The phandle to the imx8mq syscon iomux-gpr with the register + for setting RX_ENABLE for the mipi receiver. + + The format should be as follows: + <gpr req_gpr> + gpr is the phandle to general purpose register node. + req_gpr is the gpr register offset of RX_ENABLE for the mipi phy. + $ref: /schemas/types.yaml#/definitions/phandle-array + items: + items: + - description: The 'gpr' is the phandle to general purpose register node. + - description: The 'req_gpr' is the gpr register offset containing + CSI2_1_RX_ENABLE or CSI2_2_RX_ENABLE respectively. + maximum: 0xff + + interconnects: + maxItems: 1 + + interconnect-names: + const: dram + + ports: + $ref: /schemas/graph.yaml#/properties/ports + + properties: + port@0: + $ref: /schemas/graph.yaml#/$defs/port-base + unevaluatedProperties: false + description: + Input port node, single endpoint describing the CSI-2 transmitter. + + properties: + endpoint: + $ref: video-interfaces.yaml# + unevaluatedProperties: false + + properties: + data-lanes: + items: + minItems: 1 + maxItems: 4 + items: + - const: 1 + - const: 2 + - const: 3 + - const: 4 + + required: + - data-lanes + + port@1: + $ref: /schemas/graph.yaml#/properties/port + description: + Output port node + + required: + - port@0 + - port@1 + +required: + - compatible + - reg + - clocks + - clock-names + - power-domains + - resets + - fsl,mipi-phy-gpr + - ports + +additionalProperties: false + +examples: + - | + #include <dt-bindings/clock/imx8mq-clock.h> + #include <dt-bindings/interconnect/imx8mq.h> + #include <dt-bindings/reset/imx8mq-reset.h> + + csi@30a70000 { + compatible = "fsl,imx8mq-mipi-csi2"; + reg = <0x30a70000 0x1000>; + clocks = <&clk IMX8MQ_CLK_CSI1_CORE>, + <&clk IMX8MQ_CLK_CSI1_ESC>, + <&clk IMX8MQ_CLK_CSI1_PHY_REF>; + clock-names = "core", "esc", "ui"; + assigned-clocks = <&clk IMX8MQ_CLK_CSI1_CORE>, + <&clk IMX8MQ_CLK_CSI1_PHY_REF>, + <&clk IMX8MQ_CLK_CSI1_ESC>; + assigned-clock-rates = <266000000>, <200000000>, <66000000>; + assigned-clock-parents = <&clk IMX8MQ_SYS1_PLL_266M>, + <&clk IMX8MQ_SYS2_PLL_1000M>, + <&clk IMX8MQ_SYS1_PLL_800M>; + power-domains = <&pgc_mipi_csi1>; + resets = <&src IMX8MQ_RESET_MIPI_CSI1_CORE_RESET>, + <&src IMX8MQ_RESET_MIPI_CSI1_PHY_REF_RESET>, + <&src IMX8MQ_RESET_MIPI_CSI1_ESC_RESET>; + fsl,mipi-phy-gpr = <&iomuxc_gpr 0x88>; + interconnects = <&noc IMX8MQ_ICM_CSI1 &noc IMX8MQ_ICS_DRAM>; + interconnect-names = "dram"; + + ports { + #address-cells = <1>; + #size-cells = <0>; + + port@0 { + reg = <0>; + + imx8mm_mipi_csi_in: endpoint { + remote-endpoint = <&imx477_out>; + data-lanes = <1 2 3 4>; + }; + }; + + port@1 { + reg = <1>; + + imx8mm_mipi_csi_out: endpoint { + remote-endpoint = <&csi_in>; + }; + }; + }; + }; + +... diff --git a/Documentation/devicetree/bindings/media/renesas,drif.yaml b/Documentation/devicetree/bindings/media/renesas,drif.yaml index 817a6d566738..9403b235e976 100644 --- a/Documentation/devicetree/bindings/media/renesas,drif.yaml +++ b/Documentation/devicetree/bindings/media/renesas,drif.yaml @@ -96,7 +96,7 @@ properties: Indicates that the channel acts as primary among the bonded channels. port: - $ref: /schemas/graph.yaml#/properties/port + $ref: /schemas/graph.yaml#/$defs/port-base unevaluatedProperties: false description: Child port node corresponding to the data input. The port node must @@ -242,7 +242,6 @@ examples: power-domains = <&sysc R8A7795_PD_ALWAYS_ON>; resets = <&cpg 513>; renesas,bonding = <&drif11>; - status = "disabled"; }; drif11: rif@e6f70000 { diff --git a/Documentation/devicetree/bindings/media/rockchip-vpu.yaml b/Documentation/devicetree/bindings/media/rockchip-vpu.yaml index b88172a59de7..bacb60a34989 100644 --- a/Documentation/devicetree/bindings/media/rockchip-vpu.yaml +++ b/Documentation/devicetree/bindings/media/rockchip-vpu.yaml @@ -22,6 +22,7 @@ properties: - rockchip,rk3288-vpu - rockchip,rk3328-vpu - rockchip,rk3399-vpu + - rockchip,px30-vpu - items: - const: rockchip,rk3188-vpu - const: rockchip,rk3066-vpu diff --git a/Documentation/devicetree/bindings/memory-controllers/ath79-ddr-controller.txt b/Documentation/devicetree/bindings/memory-controllers/ath79-ddr-controller.txt deleted file mode 100644 index c81af75bcd88..000000000000 --- a/Documentation/devicetree/bindings/memory-controllers/ath79-ddr-controller.txt +++ /dev/null @@ -1,35 +0,0 @@ -Binding for Qualcomm Atheros AR7xxx/AR9xxx DDR controller - -The DDR controller of the AR7xxx and AR9xxx families provides an interface -to flush the FIFO between various devices and the DDR. This is mainly used -by the IRQ controller to flush the FIFO before running the interrupt handler -of such devices. - -Required properties: - -- compatible: has to be "qca,<soc-type>-ddr-controller", - "qca,[ar7100|ar7240]-ddr-controller" as fallback. - On SoC with PCI support "qca,ar7100-ddr-controller" should be used as - fallback, otherwise "qca,ar7240-ddr-controller" should be used. -- reg: Base address and size of the controller's memory area -- #qca,ddr-wb-channel-cells: Specifies the number of cells needed to encode - the write buffer channel index, should be 1. - -Example: - - ddr_ctrl: memory-controller@18000000 { - compatible = "qca,ar9132-ddr-controller", - "qca,ar7240-ddr-controller"; - reg = <0x18000000 0x100>; - - #qca,ddr-wb-channel-cells = <1>; - }; - - ... - - interrupt-controller { - ... - qca,ddr-wb-channel-interrupts = <2>, <3>, <4>, <5>; - qca,ddr-wb-channels = <&ddr_ctrl 3>, <&ddr_ctrl 2>, - <&ddr_ctrl 0>, <&ddr_ctrl 1>; - }; diff --git a/Documentation/devicetree/bindings/memory-controllers/brcm,dpfe-cpu.txt b/Documentation/devicetree/bindings/memory-controllers/brcm,dpfe-cpu.txt deleted file mode 100644 index 82d923ef413f..000000000000 --- a/Documentation/devicetree/bindings/memory-controllers/brcm,dpfe-cpu.txt +++ /dev/null @@ -1,27 +0,0 @@ -DDR PHY Front End (DPFE) for Broadcom STB -========================================= - -DPFE and the DPFE firmware provide an interface for the host CPU to -communicate with the DCPU, which resides inside the DDR PHY. - -There are three memory regions for interacting with the DCPU. These are -specified in a single reg property. - -Required properties: - - compatible: must be "brcm,bcm7271-dpfe-cpu", "brcm,bcm7268-dpfe-cpu" - or "brcm,dpfe-cpu" - - reg: must reference three register ranges - - start address and length of the DCPU register space - - start address and length of the DCPU data memory space - - start address and length of the DCPU instruction memory space - - reg-names: must contain "dpfe-cpu", "dpfe-dmem", and "dpfe-imem"; - they must be in the same order as the register declarations - -Example: - dpfe_cpu0: dpfe-cpu@f1132000 { - compatible = "brcm,bcm7271-dpfe-cpu", "brcm,dpfe-cpu"; - reg = <0xf1132000 0x180 - 0xf1134000 0x1000 - 0xf1138000 0x4000>; - reg-names = "dpfe-cpu", "dpfe-dmem", "dpfe-imem"; - }; diff --git a/Documentation/devicetree/bindings/memory-controllers/brcm,dpfe-cpu.yaml b/Documentation/devicetree/bindings/memory-controllers/brcm,dpfe-cpu.yaml new file mode 100644 index 000000000000..769f13250047 --- /dev/null +++ b/Documentation/devicetree/bindings/memory-controllers/brcm,dpfe-cpu.yaml @@ -0,0 +1,48 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/memory-controllers/brcm,dpfe-cpu.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: DDR PHY Front End (DPFE) for Broadcom STB + +maintainers: + - Krzysztof Kozlowski <krzysztof.kozlowski@canonical.com> + - Markus Mayer <mmayer@broadcom.com> + +properties: + compatible: + items: + - enum: + - brcm,bcm7271-dpfe-cpu + - brcm,bcm7268-dpfe-cpu + - const: brcm,dpfe-cpu + + reg: + items: + - description: DCPU register space + - description: DCPU data memory space + - description: DCPU instruction memory space + + reg-names: + items: + - const: dpfe-cpu + - const: dpfe-dmem + - const: dpfe-imem + +required: + - compatible + - reg + - reg-names + +additionalProperties: false + +examples: + - | + dpfe-cpu@f1132000 { + compatible = "brcm,bcm7271-dpfe-cpu", "brcm,dpfe-cpu"; + reg = <0xf1132000 0x180>, + <0xf1134000 0x1000>, + <0xf1138000 0x4000>; + reg-names = "dpfe-cpu", "dpfe-dmem", "dpfe-imem"; + }; diff --git a/Documentation/devicetree/bindings/memory-controllers/exynos5422-dmc.txt b/Documentation/devicetree/bindings/memory-controllers/exynos5422-dmc.txt deleted file mode 100644 index 02e4a1f862f1..000000000000 --- a/Documentation/devicetree/bindings/memory-controllers/exynos5422-dmc.txt +++ /dev/null @@ -1,84 +0,0 @@ -* Exynos5422 frequency and voltage scaling for Dynamic Memory Controller device - -The Samsung Exynos5422 SoC has DMC (Dynamic Memory Controller) to which the DRAM -memory chips are connected. The driver is to monitor the controller in runtime -and switch frequency and voltage. To monitor the usage of the controller in -runtime, the driver uses the PPMU (Platform Performance Monitoring Unit), which -is able to measure the current load of the memory. -When 'userspace' governor is used for the driver, an application is able to -switch the DMC and memory frequency. - -Required properties for DMC device for Exynos5422: -- compatible: Should be "samsung,exynos5422-dmc". -- clocks : list of clock specifiers, must contain an entry for each - required entry in clock-names for CLK_FOUT_SPLL, CLK_MOUT_SCLK_SPLL, - CLK_FF_DOUT_SPLL2, CLK_FOUT_BPLL, CLK_MOUT_BPLL, CLK_SCLK_BPLL, - CLK_MOUT_MX_MSPLL_CCORE, CLK_MOUT_MX_MSPLL_CCORE_PHY, CLK_MOUT_MCLK_CDREX, -- clock-names : should include "fout_spll", "mout_sclk_spll", "ff_dout_spll2", - "fout_bpll", "mout_bpll", "sclk_bpll", "mout_mx_mspll_ccore", - "mout_mclk_cdrex" entries -- devfreq-events : phandles for PPMU devices connected to this DMC. -- vdd-supply : phandle for voltage regulator which is connected. -- reg : registers of two CDREX controllers. -- operating-points-v2 : phandle for OPPs described in v2 definition. -- device-handle : phandle of the connected DRAM memory device. For more - information please refer to documentation file: - Documentation/devicetree/bindings/ddr/lpddr3.txt -- devfreq-events : phandles of the PPMU events used by the controller. -- samsung,syscon-clk : phandle of the clock register set used by the controller, - these registers are used for enabling a 'pause' feature and are not - exposed by clock framework but they must be used in a safe way. - The register offsets are in the driver code and specyfic for this SoC - type. - -Optional properties for DMC device for Exynos5422: -- interrupt-parent : The parent interrupt controller. -- interrupts : Contains the IRQ line numbers for the DMC internal performance - event counters in DREX0 and DREX1 channels. Align with specification of the - interrupt line(s) in the interrupt-parent controller. -- interrupt-names : IRQ names "drex_0" and "drex_1", the order should be the - same as in the 'interrupts' list above. - -Example: - - ppmu_dmc0_0: ppmu@10d00000 { - compatible = "samsung,exynos-ppmu"; - reg = <0x10d00000 0x2000>; - clocks = <&clock CLK_PCLK_PPMU_DREX0_0>; - clock-names = "ppmu"; - events { - ppmu_event_dmc0_0: ppmu-event3-dmc0_0 { - event-name = "ppmu-event3-dmc0_0"; - }; - }; - }; - - dmc: memory-controller@10c20000 { - compatible = "samsung,exynos5422-dmc"; - reg = <0x10c20000 0x10000>, <0x10c30000 0x10000>; - clocks = <&clock CLK_FOUT_SPLL>, - <&clock CLK_MOUT_SCLK_SPLL>, - <&clock CLK_FF_DOUT_SPLL2>, - <&clock CLK_FOUT_BPLL>, - <&clock CLK_MOUT_BPLL>, - <&clock CLK_SCLK_BPLL>, - <&clock CLK_MOUT_MX_MSPLL_CCORE>, - <&clock CLK_MOUT_MCLK_CDREX>; - clock-names = "fout_spll", - "mout_sclk_spll", - "ff_dout_spll2", - "fout_bpll", - "mout_bpll", - "sclk_bpll", - "mout_mx_mspll_ccore", - "mout_mclk_cdrex"; - operating-points-v2 = <&dmc_opp_table>; - devfreq-events = <&ppmu_event3_dmc0_0>, <&ppmu_event3_dmc0_1>, - <&ppmu_event3_dmc1_0>, <&ppmu_event3_dmc1_1>; - device-handle = <&samsung_K3QF2F20DB>; - vdd-supply = <&buck1_reg>; - samsung,syscon-clk = <&clock>; - interrupt-parent = <&combiner>; - interrupts = <16 0>, <16 1>; - interrupt-names = "drex_0", "drex_1"; - }; diff --git a/Documentation/devicetree/bindings/memory-controllers/marvell,mvebu-sdram-controller.yaml b/Documentation/devicetree/bindings/memory-controllers/marvell,mvebu-sdram-controller.yaml new file mode 100644 index 000000000000..14a6bc8f421f --- /dev/null +++ b/Documentation/devicetree/bindings/memory-controllers/marvell,mvebu-sdram-controller.yaml @@ -0,0 +1,31 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/memory-controllers/marvell,mvebu-sdram-controller.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Marvell MVEBU SDRAM controller + +maintainers: + - Jan Luebbe <jlu@pengutronix.de> + - Krzysztof Kozlowski <krzysztof.kozlowski@canonical.com> + +properties: + compatible: + const: marvell,armada-xp-sdram-controller + + reg: + maxItems: 1 + +required: + - compatible + - reg + +additionalProperties: false + +examples: + - | + memory-controller@1400 { + compatible = "marvell,armada-xp-sdram-controller"; + reg = <0x1400 0x500>; + }; diff --git a/Documentation/devicetree/bindings/memory-controllers/mvebu-sdram-controller.txt b/Documentation/devicetree/bindings/memory-controllers/mvebu-sdram-controller.txt deleted file mode 100644 index 89657d1d4cd4..000000000000 --- a/Documentation/devicetree/bindings/memory-controllers/mvebu-sdram-controller.txt +++ /dev/null @@ -1,21 +0,0 @@ -Device Tree bindings for MVEBU SDRAM controllers - -The Marvell EBU SoCs all have a SDRAM controller. The SDRAM controller -differs from one SoC variant to another, but they also share a number -of commonalities. - -For now, this Device Tree binding documentation only documents the -Armada XP SDRAM controller. - -Required properties: - - - compatible: for Armada XP, "marvell,armada-xp-sdram-controller" - - reg: a resource specifier for the register space, which should - include all SDRAM controller registers as per the datasheet. - -Example: - -sdramc@1400 { - compatible = "marvell,armada-xp-sdram-controller"; - reg = <0x1400 0x500>; -}; diff --git a/Documentation/devicetree/bindings/memory-controllers/qca,ath79-ddr-controller.yaml b/Documentation/devicetree/bindings/memory-controllers/qca,ath79-ddr-controller.yaml new file mode 100644 index 000000000000..9566b3421f03 --- /dev/null +++ b/Documentation/devicetree/bindings/memory-controllers/qca,ath79-ddr-controller.yaml @@ -0,0 +1,61 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/memory-controllers/qca,ath79-ddr-controller.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Qualcomm Atheros AR7xxx/AR9xxx DDR controller + +maintainers: + - Krzysztof Kozlowski <krzysztof.kozlowski@canonical.com> + +description: | + The DDR controller of the AR7xxx and AR9xxx families provides an interface to + flush the FIFO between various devices and the DDR. This is mainly used by + the IRQ controller to flush the FIFO before running the interrupt handler of + such devices. + +properties: + compatible: + oneOf: + - items: + - const: qca,ar9132-ddr-controller + - const: qca,ar7240-ddr-controller + - items: + - enum: + - qca,ar7100-ddr-controller + - qca,ar7240-ddr-controller + + "#qca,ddr-wb-channel-cells": + description: | + Specifies the number of cells needed to encode the write buffer channel + index. + $ref: /schemas/types.yaml#/definitions/uint32 + const: 1 + + reg: + maxItems: 1 + +required: + - compatible + - "#qca,ddr-wb-channel-cells" + - reg + +additionalProperties: false + +examples: + - | + ddr_ctrl: memory-controller@18000000 { + compatible = "qca,ar9132-ddr-controller", + "qca,ar7240-ddr-controller"; + reg = <0x18000000 0x100>; + + #qca,ddr-wb-channel-cells = <1>; + }; + + interrupt-controller { + // ... + qca,ddr-wb-channel-interrupts = <2>, <3>, <4>, <5>; + qca,ddr-wb-channels = <&ddr_ctrl 3>, <&ddr_ctrl 2>, + <&ddr_ctrl 0>, <&ddr_ctrl 1>; + }; diff --git a/Documentation/devicetree/bindings/memory-controllers/renesas,h8300-bsc.txt b/Documentation/devicetree/bindings/memory-controllers/renesas,h8300-bsc.txt deleted file mode 100644 index cdf406c902e2..000000000000 --- a/Documentation/devicetree/bindings/memory-controllers/renesas,h8300-bsc.txt +++ /dev/null @@ -1,12 +0,0 @@ -* H8/300 bus controller - -Required properties: - - compatible: Must be "renesas,h8300-bsc". - - reg: Base address and length of BSC registers. - -Example. - bsc: memory-controller@fee01e { - compatible = "renesas,h8300h-bsc", "renesas,h8300-bsc"; - reg = <0xfee01e 8>; - }; - diff --git a/Documentation/devicetree/bindings/memory-controllers/renesas,h8300-bsc.yaml b/Documentation/devicetree/bindings/memory-controllers/renesas,h8300-bsc.yaml new file mode 100644 index 000000000000..2b18cef99511 --- /dev/null +++ b/Documentation/devicetree/bindings/memory-controllers/renesas,h8300-bsc.yaml @@ -0,0 +1,35 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/memory-controllers/renesas,h8300-bsc.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: H8/300 bus controller + +maintainers: + - Krzysztof Kozlowski <krzysztof.kozlowski@canonical.com> + - Yoshinori Sato <ysato@users.sourceforge.jp> + +properties: + compatible: + items: + - enum: + - renesas,h8300h-bsc + - renesas,h8s-bsc + - const: renesas,h8300-bsc + + reg: + maxItems: 1 + +required: + - compatible + - reg + +additionalProperties: false + +examples: + - | + memory-controller@fee01e { + compatible = "renesas,h8300h-bsc", "renesas,h8300-bsc"; + reg = <0xfee01e 8>; + }; diff --git a/Documentation/devicetree/bindings/memory-controllers/renesas,rpc-if.yaml b/Documentation/devicetree/bindings/memory-controllers/renesas,rpc-if.yaml index 990489fdd2ac..d25072c414e4 100644 --- a/Documentation/devicetree/bindings/memory-controllers/renesas,rpc-if.yaml +++ b/Documentation/devicetree/bindings/memory-controllers/renesas,rpc-if.yaml @@ -61,12 +61,23 @@ patternProperties: type: object properties: compatible: - enum: - - cfi-flash - - jedec,spi-nor + contains: + enum: + - cfi-flash + - jedec,spi-nor unevaluatedProperties: false +required: + - compatible + - reg + - reg-names + - clocks + - power-domains + - resets + - '#address-cells' + - '#size-cells' + examples: - | #include <dt-bindings/clock/renesas-cpg-mssr.h> diff --git a/Documentation/devicetree/bindings/memory-controllers/samsung,exynos5422-dmc.yaml b/Documentation/devicetree/bindings/memory-controllers/samsung,exynos5422-dmc.yaml new file mode 100644 index 000000000000..6f4fd5814bf4 --- /dev/null +++ b/Documentation/devicetree/bindings/memory-controllers/samsung,exynos5422-dmc.yaml @@ -0,0 +1,137 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/memory-controllers/samsung,exynos5422-dmc.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: | + Samsung Exynos5422 SoC frequency and voltage scaling for Dynamic Memory + Controller device + +maintainers: + - Krzysztof Kozlowski <krzysztof.kozlowski@canonical.com> + - Lukasz Luba <lukasz.luba@arm.com> + +description: | + The Samsung Exynos5422 SoC has DMC (Dynamic Memory Controller) to which the + DRAM memory chips are connected. The driver is to monitor the controller in + runtime and switch frequency and voltage. To monitor the usage of the + controller in runtime, the driver uses the PPMU (Platform Performance + Monitoring Unit), which is able to measure the current load of the memory. + When 'userspace' governor is used for the driver, an application is able to + switch the DMC and memory frequency. + +properties: + compatible: + items: + - const: samsung,exynos5422-dmc + + clock-names: + items: + - const: fout_spll + - const: mout_sclk_spll + - const: ff_dout_spll2 + - const: fout_bpll + - const: mout_bpll + - const: sclk_bpll + - const: mout_mx_mspll_ccore + - const: mout_mclk_cdrex + + clocks: + minItems: 8 + maxItems: 8 + + devfreq-events: + $ref: '/schemas/types.yaml#/definitions/phandle-array' + minItems: 1 + maxItems: 16 + description: phandles of the PPMU events used by the controller. + + device-handle: + $ref: '/schemas/types.yaml#/definitions/phandle' + description: | + phandle of the connected DRAM memory device. For more information please + refer to documentation file: Documentation/devicetree/bindings/ddr/lpddr3.txt + + operating-points-v2: true + + interrupts: + items: + - description: DMC internal performance event counters in DREX0 + - description: DMC internal performance event counters in DREX1 + + interrupt-names: + items: + - const: drex_0 + - const: drex_1 + + reg: + items: + - description: registers of DREX0 + - description: registers of DREX1 + + samsung,syscon-clk: + $ref: '/schemas/types.yaml#/definitions/phandle' + description: | + Phandle of the clock register set used by the controller, these registers + are used for enabling a 'pause' feature and are not exposed by clock + framework but they must be used in a safe way. The register offsets are + in the driver code and specyfic for this SoC type. + + vdd-supply: true + +required: + - compatible + - clock-names + - clocks + - devfreq-events + - device-handle + - reg + - samsung,syscon-clk + +additionalProperties: false + +examples: + - | + #include <dt-bindings/clock/exynos5420.h> + ppmu_dmc0_0: ppmu@10d00000 { + compatible = "samsung,exynos-ppmu"; + reg = <0x10d00000 0x2000>; + clocks = <&clock CLK_PCLK_PPMU_DREX0_0>; + clock-names = "ppmu"; + events { + ppmu_event_dmc0_0: ppmu-event3-dmc0-0 { + event-name = "ppmu-event3-dmc0_0"; + }; + }; + }; + + memory-controller@10c20000 { + compatible = "samsung,exynos5422-dmc"; + reg = <0x10c20000 0x10000>, <0x10c30000 0x10000>; + clocks = <&clock CLK_FOUT_SPLL>, + <&clock CLK_MOUT_SCLK_SPLL>, + <&clock CLK_FF_DOUT_SPLL2>, + <&clock CLK_FOUT_BPLL>, + <&clock CLK_MOUT_BPLL>, + <&clock CLK_SCLK_BPLL>, + <&clock CLK_MOUT_MX_MSPLL_CCORE>, + <&clock CLK_MOUT_MCLK_CDREX>; + clock-names = "fout_spll", + "mout_sclk_spll", + "ff_dout_spll2", + "fout_bpll", + "mout_bpll", + "sclk_bpll", + "mout_mx_mspll_ccore", + "mout_mclk_cdrex"; + operating-points-v2 = <&dmc_opp_table>; + devfreq-events = <&ppmu_event3_dmc0_0>, <&ppmu_event3_dmc0_1>, + <&ppmu_event3_dmc1_0>, <&ppmu_event3_dmc1_1>; + device-handle = <&samsung_K3QF2F20DB>; + vdd-supply = <&buck1_reg>; + samsung,syscon-clk = <&clock>; + interrupt-parent = <&combiner>; + interrupts = <16 0>, <16 1>; + interrupt-names = "drex_0", "drex_1"; + }; diff --git a/Documentation/devicetree/bindings/memory-controllers/synopsys,ddrc-ecc.yaml b/Documentation/devicetree/bindings/memory-controllers/synopsys,ddrc-ecc.yaml new file mode 100644 index 000000000000..a24588474625 --- /dev/null +++ b/Documentation/devicetree/bindings/memory-controllers/synopsys,ddrc-ecc.yaml @@ -0,0 +1,73 @@ +# SPDX-License-Identifier: GPL-2.0-only +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/memory-controllers/synopsys,ddrc-ecc.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Synopsys IntelliDDR Multi Protocol memory controller + +maintainers: + - Krzysztof Kozlowski <krzysztof.kozlowski@canonical.com> + - Manish Narani <manish.narani@xilinx.com> + - Michal Simek <michal.simek@xilinx.com> + +description: | + The ZynqMP DDR ECC controller has an optional ECC support in 64-bit and + 32-bit bus width configurations. + + The Zynq DDR ECC controller has an optional ECC support in half-bus width + (16-bit) configuration. + + These both ECC controllers correct single bit ECC errors and detect double bit + ECC errors. + +properties: + compatible: + enum: + - xlnx,zynq-ddrc-a05 + - xlnx,zynqmp-ddrc-2.40a + + interrupts: + maxItems: 1 + + reg: + maxItems: 1 + +required: + - compatible + - reg + +allOf: + - if: + properties: + compatible: + contains: + const: xlnx,zynqmp-ddrc-2.40a + then: + required: + - interrupts + else: + properties: + interrupts: false + +additionalProperties: false + +examples: + - | + memory-controller@f8006000 { + compatible = "xlnx,zynq-ddrc-a05"; + reg = <0xf8006000 0x1000>; + }; + + - | + axi { + #address-cells = <2>; + #size-cells = <2>; + + memory-controller@fd070000 { + compatible = "xlnx,zynqmp-ddrc-2.40a"; + reg = <0x0 0xfd070000 0x0 0x30000>; + interrupt-parent = <&gic>; + interrupts = <0 112 4>; + }; + }; diff --git a/Documentation/devicetree/bindings/memory-controllers/synopsys.txt b/Documentation/devicetree/bindings/memory-controllers/synopsys.txt deleted file mode 100644 index 9d32762c47e1..000000000000 --- a/Documentation/devicetree/bindings/memory-controllers/synopsys.txt +++ /dev/null @@ -1,32 +0,0 @@ -Binding for Synopsys IntelliDDR Multi Protocol Memory Controller - -The ZynqMP DDR ECC controller has an optional ECC support in 64-bit and 32-bit -bus width configurations. - -The Zynq DDR ECC controller has an optional ECC support in half-bus width -(16-bit) configuration. - -These both ECC controllers correct single bit ECC errors and detect double bit -ECC errors. - -Required properties: - - compatible: One of: - - 'xlnx,zynq-ddrc-a05' : Zynq DDR ECC controller - - 'xlnx,zynqmp-ddrc-2.40a' : ZynqMP DDR ECC controller - - reg: Should contain DDR controller registers location and length. - -Required properties for "xlnx,zynqmp-ddrc-2.40a": - - interrupts: Property with a value describing the interrupt number. - -Example: - memory-controller@f8006000 { - compatible = "xlnx,zynq-ddrc-a05"; - reg = <0xf8006000 0x1000>; - }; - - mc: memory-controller@fd070000 { - compatible = "xlnx,zynqmp-ddrc-2.40a"; - reg = <0x0 0xfd070000 0x0 0x30000>; - interrupt-parent = <&gic>; - interrupts = <0 112 4>; - }; diff --git a/Documentation/devicetree/bindings/memory-controllers/ti,da8xx-ddrctl.yaml b/Documentation/devicetree/bindings/memory-controllers/ti,da8xx-ddrctl.yaml new file mode 100644 index 000000000000..9ed51185ff99 --- /dev/null +++ b/Documentation/devicetree/bindings/memory-controllers/ti,da8xx-ddrctl.yaml @@ -0,0 +1,35 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/memory-controllers/ti,da8xx-ddrctl.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Texas Instruments da8xx DDR2/mDDR memory controller + +maintainers: + - Bartosz Golaszewski <bgolaszewski@baylibre.com> + - Krzysztof Kozlowski <krzysztof.kozlowski@canonical.com> + +description: | + Documentation: + OMAP-L138 (DA850) - http://www.ti.com/lit/ug/spruh82c/spruh82c.pdf + +properties: + compatible: + const: ti,da850-ddr-controller + + reg: + maxItems: 1 + +required: + - compatible + - reg + +additionalProperties: false + +examples: + - | + memory-controller@b0000000 { + compatible = "ti,da850-ddr-controller"; + reg = <0xb0000000 0xe8>; + }; diff --git a/Documentation/devicetree/bindings/memory-controllers/ti-da8xx-ddrctl.txt b/Documentation/devicetree/bindings/memory-controllers/ti-da8xx-ddrctl.txt deleted file mode 100644 index ec1dd408d573..000000000000 --- a/Documentation/devicetree/bindings/memory-controllers/ti-da8xx-ddrctl.txt +++ /dev/null @@ -1,20 +0,0 @@ -* Device tree bindings for Texas Instruments da8xx DDR2/mDDR memory controller - -The DDR2/mDDR memory controller present on Texas Instruments da8xx SoCs features -a set of registers which allow to tweak the controller's behavior. - -Documentation: -OMAP-L138 (DA850) - http://www.ti.com/lit/ug/spruh82c/spruh82c.pdf - -Required properties: - -- compatible: "ti,da850-ddr-controller" - for da850 SoC based boards -- reg: a tuple containing the base address of the memory - controller and the size of the memory area to map - -Example for da850 shown below. - -ddrctl { - compatible = "ti,da850-ddr-controller"; - reg = <0xb0000000 0xe8>; -}; diff --git a/Documentation/devicetree/bindings/mfd/hisilicon,hi6421-spmi-pmic.yaml b/Documentation/devicetree/bindings/mfd/hisilicon,hi6421-spmi-pmic.yaml new file mode 100644 index 000000000000..22edcb4b212f --- /dev/null +++ b/Documentation/devicetree/bindings/mfd/hisilicon,hi6421-spmi-pmic.yaml @@ -0,0 +1,137 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/mfd/hisilicon,hi6421-spmi-pmic.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: HiSilicon 6421v600 SPMI PMIC + +maintainers: + - Mauro Carvalho Chehab <mchehab+huawei@kernel.org> + +description: | + HiSilicon 6421v600 should be connected inside a MIPI System Power Management + (SPMI) bus. It provides interrupts and power supply. + + The GPIO and interrupt settings are represented as part of the top-level PMIC + node. + + The SPMI controller part is provided by + Documentation/devicetree/bindings/mfd/hisilicon,hi6421-spmi-pmic.yaml + +properties: + $nodename: + pattern: "pmic@[0-9a-f]" + + compatible: + const: hisilicon,hi6421v600-spmi + + reg: + maxItems: 1 + + '#interrupt-cells': + const: 2 + + interrupt-controller: true + + interrupts: + maxItems: 1 + + regulators: + type: object + + additionalProperties: false + + properties: + '#address-cells': + const: 1 + + '#size-cells': + const: 0 + + patternProperties: + '^ldo[0-9]+$': + type: object + + $ref: "/schemas/regulator/regulator.yaml#" + + unevaluatedProperties: false + +required: + - compatible + - reg + - regulators + +additionalProperties: false + +examples: + - | + + pmic: pmic@0 { + compatible = "hisilicon,hi6421v600-spmi"; + reg = <0 0>; + + #interrupt-cells = <2>; + interrupt-controller; + interrupt-parent = <&gpio28>; + interrupts = <0 0>; + + regulators { + #address-cells = <1>; + #size-cells = <0>; + + ldo3: ldo3 { + regulator-name = "ldo3"; + regulator-min-microvolt = <1500000>; + regulator-max-microvolt = <2000000>; + regulator-boot-on; + }; + + ldo4: ldo4 { + regulator-name = "ldo4"; + regulator-min-microvolt = <1725000>; + regulator-max-microvolt = <1900000>; + regulator-boot-on; + }; + + ldo9: ldo9 { + regulator-name = "ldo9"; + regulator-min-microvolt = <1750000>; + regulator-max-microvolt = <3300000>; + regulator-boot-on; + }; + + ldo15: ldo15 { + regulator-name = "ldo15"; + regulator-min-microvolt = <1800000>; + regulator-max-microvolt = <3000000>; + regulator-always-on; + }; + + ldo16: ldo16 { + regulator-name = "ldo16"; + regulator-min-microvolt = <1800000>; + regulator-max-microvolt = <3000000>; + regulator-boot-on; + }; + + ldo17: ldo17 { + regulator-name = "ldo17"; + regulator-min-microvolt = <2500000>; + regulator-max-microvolt = <3300000>; + }; + + ldo33: ldo33 { + regulator-name = "ldo33"; + regulator-min-microvolt = <2500000>; + regulator-max-microvolt = <3300000>; + regulator-boot-on; + }; + + ldo34: ldo34 { + regulator-name = "ldo34"; + regulator-min-microvolt = <2600000>; + regulator-max-microvolt = <3300000>; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/mfd/ti,lp87565-q1.yaml b/Documentation/devicetree/bindings/mfd/ti,lp87565-q1.yaml index 48d4d53c25f9..012d25111054 100644 --- a/Documentation/devicetree/bindings/mfd/ti,lp87565-q1.yaml +++ b/Documentation/devicetree/bindings/mfd/ti,lp87565-q1.yaml @@ -11,9 +11,9 @@ maintainers: properties: compatible: - oneOf: - - const: ti,lp87565 - - const: ti,lp87565-q1 + enum: + - ti,lp87565 + - ti,lp87565-q1 reg: description: I2C slave address diff --git a/Documentation/devicetree/bindings/misc/eeprom-93xx46.txt b/Documentation/devicetree/bindings/misc/eeprom-93xx46.txt deleted file mode 100644 index 72ea0af368d4..000000000000 --- a/Documentation/devicetree/bindings/misc/eeprom-93xx46.txt +++ /dev/null @@ -1,29 +0,0 @@ -EEPROMs (SPI) compatible with Microchip Technology 93xx46 family. - -Required properties: -- compatible : shall be one of: - "atmel,at93c46" - "atmel,at93c46d" - "atmel,at93c56" - "atmel,at93c66" - "eeprom-93xx46" - "microchip,93lc46b" -- data-size : number of data bits per word (either 8 or 16) - -Optional properties: -- read-only : parameter-less property which disables writes to the EEPROM -- select-gpios : if present, specifies the GPIO that will be asserted prior to - each access to the EEPROM (e.g. for SPI bus multiplexing) - -Property rules described in Documentation/devicetree/bindings/spi/spi-bus.txt -apply. In particular, "reg" and "spi-max-frequency" properties must be given. - -Example: - eeprom@0 { - compatible = "eeprom-93xx46"; - reg = <0>; - spi-max-frequency = <1000000>; - spi-cs-high; - data-size = <8>; - select-gpios = <&gpio4 4 GPIO_ACTIVE_HIGH>; - }; diff --git a/Documentation/devicetree/bindings/misc/eeprom-93xx46.yaml b/Documentation/devicetree/bindings/misc/eeprom-93xx46.yaml new file mode 100644 index 000000000000..44fd2f6f0d8a --- /dev/null +++ b/Documentation/devicetree/bindings/misc/eeprom-93xx46.yaml @@ -0,0 +1,70 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/misc/eeprom-93xx46.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Microchip 93xx46 SPI compatible EEPROM family dt bindings + +maintainers: + - Cory Tusar <cory.tusar@pid1solutions.com> + +properties: + compatible: + enum: + - atmel,at93c46 + - atmel,at93c46d + - atmel,at93c56 + - atmel,at93c66 + - eeprom-93xx46 + - microchip,93lc46b + + data-size: + description: number of data bits per word + $ref: /schemas/types.yaml#/definitions/uint32 + enum: [8, 16] + + reg: + description: chip select of EEPROM + maxItems: 1 + + spi-max-frequency: true + spi-cs-high: true + + read-only: + description: + parameter-less property which disables writes to the EEPROM + type: boolean + + select-gpios: + description: + specifies the GPIO that needs to be asserted prior to each access + of EEPROM (e.g. for SPI bus multiplexing) + maxItems: 1 + + +required: + - compatible + - reg + - data-size + - spi-max-frequency + +additionalProperties: false + +examples: + - | + #include <dt-bindings/gpio/gpio.h> + + spi { + #address-cells = <1>; + #size-cells = <0>; + + eeprom@0 { + compatible = "eeprom-93xx46"; + reg = <0>; + spi-max-frequency = <1000000>; + spi-cs-high; + data-size = <8>; + select-gpios = <&gpio4 4 GPIO_ACTIVE_HIGH>; + }; + }; diff --git a/Documentation/devicetree/bindings/misc/ge-achc.txt b/Documentation/devicetree/bindings/misc/ge-achc.txt deleted file mode 100644 index 77df94d7a32f..000000000000 --- a/Documentation/devicetree/bindings/misc/ge-achc.txt +++ /dev/null @@ -1,26 +0,0 @@ -* GE Healthcare USB Management Controller - -A device which handles data aquisition from compatible USB based peripherals. -SPI is used for device management. - -Note: This device does not expose the peripherals as USB devices. - -Required properties: - -- compatible : Should be "ge,achc" - -Required SPI properties: - -- reg : Should be address of the device chip select within - the controller. - -- spi-max-frequency : Maximum SPI clocking speed of device in Hz, should be - 1MHz for the GE ACHC. - -Example: - -spidev0: spi@0 { - compatible = "ge,achc"; - reg = <0>; - spi-max-frequency = <1000000>; -}; diff --git a/Documentation/devicetree/bindings/misc/ge-achc.yaml b/Documentation/devicetree/bindings/misc/ge-achc.yaml new file mode 100644 index 000000000000..ff07aa62ed57 --- /dev/null +++ b/Documentation/devicetree/bindings/misc/ge-achc.yaml @@ -0,0 +1,65 @@ +# SPDX-License-Identifier: GPL-2.0 OR BSD-2-Clause +# Copyright (C) 2021 GE Inc. +# Copyright (C) 2021 Collabora Ltd. +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/misc/ge-achc.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: GE Healthcare USB Management Controller + +description: | + A device which handles data acquisition from compatible USB based peripherals. + SPI is used for device management. + + Note: This device does not expose the peripherals as USB devices. + +maintainers: + - Sebastian Reichel <sre@kernel.org> + +properties: + compatible: + items: + - const: ge,achc + - const: nxp,kinetis-k20 + + clocks: + maxItems: 1 + + vdd-supply: + description: Digital power supply regulator on VDD pin + + vdda-supply: + description: Analog power supply regulator on VDDA pin + + reg: + items: + - description: Control interface + - description: Firmware programming interface + + reset-gpios: + description: GPIO used for hardware reset. + maxItems: 1 + +required: + - compatible + - clocks + - reg + - reset-gpios + +additionalProperties: false + +examples: + - | + #include <dt-bindings/gpio/gpio.h> + spi { + #address-cells = <1>; + #size-cells = <0>; + + spi@1 { + compatible = "ge,achc", "nxp,kinetis-k20"; + reg = <1>, <0>; + clocks = <&achc_24M>; + reset-gpios = <&gpio3 6 GPIO_ACTIVE_LOW>; + }; + }; diff --git a/Documentation/devicetree/bindings/mmc/fsl-imx-esdhc.yaml b/Documentation/devicetree/bindings/mmc/fsl-imx-esdhc.yaml index b5baf439fbac..a3412f221104 100644 --- a/Documentation/devicetree/bindings/mmc/fsl-imx-esdhc.yaml +++ b/Documentation/devicetree/bindings/mmc/fsl-imx-esdhc.yaml @@ -29,6 +29,7 @@ properties: - fsl,imx53-esdhc - fsl,imx6q-usdhc - fsl,imx6sl-usdhc + - fsl,imx6sll-usdhc - fsl,imx6sx-usdhc - fsl,imx6ull-usdhc - fsl,imx7d-usdhc @@ -115,12 +116,17 @@ properties: - const: per pinctrl-names: - minItems: 1 - items: - - const: default - - const: state_100mhz - - const: state_200mhz - - const: sleep + oneOf: + - minItems: 3 + items: + - const: default + - const: state_100mhz + - const: state_200mhz + - const: sleep + - minItems: 1 + items: + - const: default + - const: sleep required: - compatible diff --git a/Documentation/devicetree/bindings/mmc/mmc-pwrseq-sd8787.yaml b/Documentation/devicetree/bindings/mmc/mmc-pwrseq-sd8787.yaml index e0169a285aa2..9e2396751030 100644 --- a/Documentation/devicetree/bindings/mmc/mmc-pwrseq-sd8787.yaml +++ b/Documentation/devicetree/bindings/mmc/mmc-pwrseq-sd8787.yaml @@ -11,7 +11,9 @@ maintainers: properties: compatible: - const: mmc-pwrseq-sd8787 + enum: + - mmc-pwrseq-sd8787 + - mmc-pwrseq-wilc1000 powerdown-gpios: minItems: 1 diff --git a/Documentation/devicetree/bindings/mmc/renesas,sdhi.yaml b/Documentation/devicetree/bindings/mmc/renesas,sdhi.yaml index 677989bc5924..9f1e7092cf44 100644 --- a/Documentation/devicetree/bindings/mmc/renesas,sdhi.yaml +++ b/Documentation/devicetree/bindings/mmc/renesas,sdhi.yaml @@ -9,9 +9,6 @@ title: Renesas SDHI SD/MMC controller maintainers: - Wolfram Sang <wsa+renesas@sang-engineering.com> -allOf: - - $ref: "mmc-controller.yaml" - properties: compatible: oneOf: @@ -47,19 +44,20 @@ properties: - const: renesas,sdhi-mmc-r8a77470 # RZ/G1C (SDHI/MMC IP) - items: - enum: - - renesas,sdhi-r8a774a1 # RZ/G2M - - renesas,sdhi-r8a774b1 # RZ/G2N - - renesas,sdhi-r8a774c0 # RZ/G2E - - renesas,sdhi-r8a774e1 # RZ/G2H - - renesas,sdhi-r8a7795 # R-Car H3 - - renesas,sdhi-r8a7796 # R-Car M3-W - - renesas,sdhi-r8a77961 # R-Car M3-W+ - - renesas,sdhi-r8a77965 # R-Car M3-N - - renesas,sdhi-r8a77970 # R-Car V3M - - renesas,sdhi-r8a77980 # R-Car V3H - - renesas,sdhi-r8a77990 # R-Car E3 - - renesas,sdhi-r8a77995 # R-Car D3 - - renesas,sdhi-r8a779a0 # R-Car V3U + - renesas,sdhi-r8a774a1 # RZ/G2M + - renesas,sdhi-r8a774b1 # RZ/G2N + - renesas,sdhi-r8a774c0 # RZ/G2E + - renesas,sdhi-r8a774e1 # RZ/G2H + - renesas,sdhi-r8a7795 # R-Car H3 + - renesas,sdhi-r8a7796 # R-Car M3-W + - renesas,sdhi-r8a77961 # R-Car M3-W+ + - renesas,sdhi-r8a77965 # R-Car M3-N + - renesas,sdhi-r8a77970 # R-Car V3M + - renesas,sdhi-r8a77980 # R-Car V3H + - renesas,sdhi-r8a77990 # R-Car E3 + - renesas,sdhi-r8a77995 # R-Car D3 + - renesas,sdhi-r8a779a0 # R-Car V3U + - renesas,sdhi-r9a07g044 # RZ/G2{L,LC} - const: renesas,rcar-gen3-sdhi # R-Car Gen3 or RZ/G2 reg: @@ -69,15 +67,9 @@ properties: minItems: 1 maxItems: 3 - clocks: - minItems: 1 - maxItems: 2 + clocks: true - clock-names: - minItems: 1 - items: - - const: core - - const: cd + clock-names: true dmas: minItems: 4 @@ -104,14 +96,82 @@ properties: pinctrl-1: maxItems: 1 - pinctrl-names: - minItems: 1 - items: - - const: default - - const: state_uhs + pinctrl-names: true max-frequency: true +allOf: + - $ref: "mmc-controller.yaml" + + - if: + properties: + compatible: + contains: + const: renesas,sdhi-r9a07g044 + then: + properties: + clocks: + items: + - description: IMCLK, SDHI channel main clock1. + - description: IMCLK2, SDHI channel main clock2. When this clock is + turned off, external SD card detection cannot be + detected. + - description: CLK_HS, SDHI channel High speed clock which operates + 4 times that of SDHI channel main clock1. + - description: ACLK, SDHI channel bus clock. + clock-names: + items: + - const: imclk + - const: imclk2 + - const: clk_hs + - const: aclk + required: + - clock-names + - resets + else: + properties: + clocks: + minItems: 1 + maxItems: 2 + clock-names: + minItems: 1 + items: + - const: core + - const: cd + + - if: + properties: + compatible: + contains: + const: renesas,sdhi-mmc-r8a77470 + then: + properties: + pinctrl-names: + items: + - const: state_uhs + else: + properties: + pinctrl-names: + minItems: 1 + items: + - const: default + - const: state_uhs + + - if: + properties: + compatible: + contains: + enum: + - renesas,sdhi-r7s72100 + - renesas,sdhi-r7s9210 + then: + required: + - clock-names + description: + The internal card detection logic that exists in these controllers is + sectioned off to be run by a separate second clock source to allow + the main core clock to be turned off to save power. + required: - compatible - reg @@ -119,21 +179,6 @@ required: - clocks - power-domains -if: - properties: - compatible: - contains: - enum: - - renesas,sdhi-r7s72100 - - renesas,sdhi-r7s9210 -then: - required: - - clock-names - description: - The internal card detection logic that exists in these controllers is - sectioned off to be run by a separate second clock source to allow - the main core clock to be turned off to save power. - unevaluatedProperties: false examples: diff --git a/Documentation/devicetree/bindings/mmc/sdhci-msm.txt b/Documentation/devicetree/bindings/mmc/sdhci-msm.txt index 4c7fa6a4ed15..365c3fc122ea 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,qcs404-sdhci", "qcom,sdhci-msm-v5" "qcom,sc7180-sdhci", "qcom,sdhci-msm-v5"; + "qcom,sc7280-sdhci", "qcom,sdhci-msm-v5"; "qcom,sdm845-sdhci", "qcom,sdhci-msm-v5" "qcom,sdx55-sdhci", "qcom,sdhci-msm-v5"; "qcom,sm8250-sdhci", "qcom,sdhci-msm-v5" diff --git a/Documentation/devicetree/bindings/mtd/gpmc-nand.txt b/Documentation/devicetree/bindings/mtd/gpmc-nand.txt index 44919d48d241..c459f169a904 100644 --- a/Documentation/devicetree/bindings/mtd/gpmc-nand.txt +++ b/Documentation/devicetree/bindings/mtd/gpmc-nand.txt @@ -122,7 +122,7 @@ on various other factors also like; so the device should have enough free bytes available its OOB/Spare area to accommodate ECC for entire page. In general following expression helps in determining if given device can accommodate ECC syndrome: - "2 + (PAGESIZE / 512) * ECC_BYTES" >= OOBSIZE" + "2 + (PAGESIZE / 512) * ECC_BYTES" <= OOBSIZE" where OOBSIZE number of bytes in OOB/spare area PAGESIZE number of bytes in main-area of device page diff --git a/Documentation/devicetree/bindings/mtd/gpmc-nor.txt b/Documentation/devicetree/bindings/mtd/gpmc-nor.txt index c8567b40fe13..2133be0d52f2 100644 --- a/Documentation/devicetree/bindings/mtd/gpmc-nor.txt +++ b/Documentation/devicetree/bindings/mtd/gpmc-nor.txt @@ -10,7 +10,7 @@ Documentation/devicetree/bindings/memory-controllers/omap-gpmc.txt Required properties: - bank-width: Width of NOR flash in bytes. GPMC supports 8-bit and 16-bit devices and so must be either 1 or 2 bytes. -- compatible: Documentation/devicetree/bindings/mtd/mtd-physmap.txt +- compatible: Documentation/devicetree/bindings/mtd/mtd-physmap.yaml - gpmc,cs-on-ns: Chip-select assertion time - gpmc,cs-rd-off-ns: Chip-select de-assertion time for reads - gpmc,cs-wr-off-ns: Chip-select de-assertion time for writes @@ -21,7 +21,7 @@ Required properties: - gpmc,access-ns: Start cycle to first data capture (read access) - gpmc,rd-cycle-ns: Total read cycle time - gpmc,wr-cycle-ns: Total write cycle time -- linux,mtd-name: Documentation/devicetree/bindings/mtd/mtd-physmap.txt +- linux,mtd-name: Documentation/devicetree/bindings/mtd/mtd-physmap.yaml - reg: Chip-select, base address (relative to chip-select) and size of NOR flash. Note that base address will be typically 0 as this is the start of the chip-select. diff --git a/Documentation/devicetree/bindings/mtd/mtd-physmap.yaml b/Documentation/devicetree/bindings/mtd/mtd-physmap.yaml index 13c29cc91b59..f827984936f6 100644 --- a/Documentation/devicetree/bindings/mtd/mtd-physmap.yaml +++ b/Documentation/devicetree/bindings/mtd/mtd-physmap.yaml @@ -23,6 +23,7 @@ properties: - amd,s29gl256n - amd,s29gl512n - arm,versatile-flash + - arm,vexpress-flash - cortina,gemini-flash - cypress,hyperflash - ge,imp3a-firmware-mirror diff --git a/Documentation/devicetree/bindings/mtd/partitions/redboot-fis.txt b/Documentation/devicetree/bindings/mtd/partitions/redboot-fis.txt deleted file mode 100644 index fd0ebe4e3415..000000000000 --- a/Documentation/devicetree/bindings/mtd/partitions/redboot-fis.txt +++ /dev/null @@ -1,27 +0,0 @@ -RedBoot FLASH Image System (FIS) Partitions -=========================================== - -The FLASH Image System (FIS) directory is a flash description -format closely associated with the RedBoot boot loader. - -It uses one single flash eraseblock in the flash to store an index of -all images in the flash. - -This block size will vary depending on flash but is typically -32 KB in size. - -Required properties: -- compatible : (required) must be "redboot-fis" -- fis-index-block : (required) a index to the eraseblock containing - the FIS directory on this device. On a flash memory with 32KB - eraseblocks, 0 means the first eraseblock at 0x00000000, 1 means the - second eraseblock at 0x00008000 and so on. - -Example: - -flash@0 { - partitions { - compatible = "redboot-fis"; - fis-index-block = <0>; - }; -}; diff --git a/Documentation/devicetree/bindings/mtd/partitions/redboot-fis.yaml b/Documentation/devicetree/bindings/mtd/partitions/redboot-fis.yaml new file mode 100644 index 000000000000..fee8d81b5276 --- /dev/null +++ b/Documentation/devicetree/bindings/mtd/partitions/redboot-fis.yaml @@ -0,0 +1,42 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/mtd/partitions/redboot-fis.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: RedBoot FLASH Image System (FIS) Partitions + +description: The FLASH Image System (FIS) directory is a flash description + format closely associated with the RedBoot boot loader. + It uses one single flash eraseblock in the flash to store an index of + all images in the flash. + This block size will vary depending on flash but is typically + 32 KB in size. + +maintainers: + - Linus Walleij <linus.walleij@linaro.org> + +properties: + compatible: + const: redboot-fis + + fis-index-block: + $ref: /schemas/types.yaml#/definitions/uint32 + description: a index to the eraseblock containing the FIS directory on this + device. On a flash memory with 32KB eraseblocks, 0 means the first + eraseblock at 0x00000000, 1 means the second eraseblock at 0x00008000 and so on. + +required: + - compatible + - fis-index-block + +additionalProperties: false + +examples: + - | + flash { + partitions { + compatible = "redboot-fis"; + fis-index-block = <0>; + }; + }; diff --git a/Documentation/devicetree/bindings/net/brcm,unimac-mdio.txt b/Documentation/devicetree/bindings/net/brcm,unimac-mdio.txt deleted file mode 100644 index e15589f47787..000000000000 --- a/Documentation/devicetree/bindings/net/brcm,unimac-mdio.txt +++ /dev/null @@ -1,43 +0,0 @@ -* Broadcom UniMAC MDIO bus controller - -Required properties: -- compatible: should one from "brcm,genet-mdio-v1", "brcm,genet-mdio-v2", - "brcm,genet-mdio-v3", "brcm,genet-mdio-v4", "brcm,genet-mdio-v5" or - "brcm,unimac-mdio" -- reg: address and length of the register set for the device, first one is the - base register, and the second one is optional and for indirect accesses to - larger than 16-bits MDIO transactions -- reg-names: name(s) of the register must be "mdio" and optional "mdio_indir_rw" -- #size-cells: must be 1 -- #address-cells: must be 0 - -Optional properties: -- interrupts: must be one if the interrupt is shared with the Ethernet MAC or - Ethernet switch this MDIO block is integrated from, or must be two, if there - are two separate interrupts, first one must be "mdio done" and second must be - for "mdio error" -- interrupt-names: must be "mdio_done_error" when there is a share interrupt fed - to this hardware block, or must be "mdio_done" for the first interrupt and - "mdio_error" for the second when there are separate interrupts -- clocks: A reference to the clock supplying the MDIO bus controller -- clock-frequency: the MDIO bus clock that must be output by the MDIO bus - hardware, if absent, the default hardware values are used - -Child nodes of this MDIO bus controller node are standard Ethernet PHY device -nodes as described in Documentation/devicetree/bindings/net/phy.txt - -Example: - -mdio@403c0 { - compatible = "brcm,unimac-mdio"; - reg = <0x403c0 0x8 0x40300 0x18>; - reg-names = "mdio", "mdio_indir_rw"; - #size-cells = <1>; - #address-cells = <0>; - - ... - phy@0 { - compatible = "ethernet-phy-ieee802.3-c22"; - reg = <0>; - }; -}; diff --git a/Documentation/devicetree/bindings/net/brcm,unimac-mdio.yaml b/Documentation/devicetree/bindings/net/brcm,unimac-mdio.yaml new file mode 100644 index 000000000000..f4f4c37f1d4e --- /dev/null +++ b/Documentation/devicetree/bindings/net/brcm,unimac-mdio.yaml @@ -0,0 +1,84 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/net/brcm,unimac-mdio.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Broadcom UniMAC MDIO bus controller + +maintainers: + - Rafał Miłecki <rafal@milecki.pl> + +allOf: + - $ref: mdio.yaml# + +properties: + compatible: + enum: + - brcm,genet-mdio-v1 + - brcm,genet-mdio-v2 + - brcm,genet-mdio-v3 + - brcm,genet-mdio-v4 + - brcm,genet-mdio-v5 + - brcm,unimac-mdio + + reg: + minItems: 1 + items: + - description: base register + - description: indirect accesses to larger than 16-bits MDIO transactions + + reg-names: + minItems: 1 + items: + - const: mdio + - const: mdio_indir_rw + + interrupts: + oneOf: + - description: > + Interrupt shared with the Ethernet MAC or Ethernet switch this MDIO + block is integrated from + - items: + - description: | + "mdio done" interrupt + - description: | + "mdio error" interrupt + + interrupt-names: + oneOf: + - const: mdio_done_error + - items: + - const: mdio_done + - const: mdio_error + + clocks: + description: A reference to the clock supplying the MDIO bus controller + + clock-frequency: + description: > + The MDIO bus clock that must be output by the MDIO bus hardware, if + absent, the default hardware values are used + +unevaluatedProperties: false + +required: + - reg + - reg-names + - '#address-cells' + - '#size-cells' + +examples: + - | + mdio@403c0 { + compatible = "brcm,unimac-mdio"; + reg = <0x403c0 0x8>, <0x40300 0x18>; + reg-names = "mdio", "mdio_indir_rw"; + #address-cells = <1>; + #size-cells = <0>; + + ethernet-phy@0 { + compatible = "ethernet-phy-ieee802.3-c22"; + reg = <0>; + }; + }; diff --git a/Documentation/devicetree/bindings/net/can/bosch,c_can.yaml b/Documentation/devicetree/bindings/net/can/bosch,c_can.yaml new file mode 100644 index 000000000000..2cd145a642f1 --- /dev/null +++ b/Documentation/devicetree/bindings/net/can/bosch,c_can.yaml @@ -0,0 +1,119 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/net/can/bosch,c_can.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Bosch C_CAN/D_CAN controller Device Tree Bindings + +description: Bosch C_CAN/D_CAN controller for CAN bus + +maintainers: + - Dario Binacchi <dariobin@libero.it> + +allOf: + - $ref: can-controller.yaml# + +properties: + compatible: + oneOf: + - enum: + - bosch,c_can + - bosch,d_can + - ti,dra7-d_can + - ti,am3352-d_can + - items: + - enum: + - ti,am4372-d_can + - const: ti,am3352-d_can + + reg: + maxItems: 1 + + interrupts: + minItems: 1 + maxItems: 4 + + power-domains: + description: | + Should contain a phandle to a PM domain provider node and an args + specifier containing the DCAN device id value. It's mandatory for + Keystone 2 66AK2G SoCs only. + maxItems: 1 + + clocks: + description: | + CAN functional clock phandle. + maxItems: 1 + + clock-names: + maxItems: 1 + + syscon-raminit: + description: | + Handle to system control region that contains the RAMINIT register, + register offset to the RAMINIT register and the CAN instance number (0 + offset). + $ref: /schemas/types.yaml#/definitions/phandle-array + items: + items: + - description: The phandle to the system control region. + - description: The register offset. + - description: The CAN instance number. + + resets: + maxItems: 1 + +required: + - compatible + - reg + - interrupts + - clocks + +if: + properties: + compatible: + contains: + enum: + - bosch,d_can + +then: + properties: + interrupts: + minItems: 4 + maxItems: 4 + items: + - description: Error and status IRQ + - description: Message object IRQ + - description: RAM ECC correctable error IRQ + - description: RAM ECC non-correctable error IRQ + +else: + properties: + interrupts: + maxItems: 1 + items: + - description: Error and status IRQ + +additionalProperties: false + +examples: + - | + #include <dt-bindings/reset/altr,rst-mgr.h> + + can@ffc00000 { + compatible = "bosch,d_can"; + reg = <0xffc00000 0x1000>; + interrupts = <0 131 4>, <0 132 4>, <0 133 4>, <0 134 4>; + clocks = <&can0_clk>; + resets = <&rst CAN0_RESET>; + }; + - | + can@0 { + compatible = "ti,am3352-d_can"; + reg = <0x0 0x2000>; + clocks = <&dcan1_fck>; + clock-names = "fck"; + syscon-raminit = <&scm_conf 0x644 1>; + interrupts = <55>; + }; diff --git a/Documentation/devicetree/bindings/net/can/bosch,m_can.yaml b/Documentation/devicetree/bindings/net/can/bosch,m_can.yaml index f84e31348d80..fb547e26c676 100644 --- a/Documentation/devicetree/bindings/net/can/bosch,m_can.yaml +++ b/Documentation/devicetree/bindings/net/can/bosch,m_can.yaml @@ -104,9 +104,18 @@ properties: maximum: 32 maxItems: 1 + power-domains: + description: + Power domain provider node and an args specifier containing + the can device id value. + maxItems: 1 + can-transceiver: $ref: can-transceiver.yaml# + phys: + maxItems: 1 + required: - compatible - reg diff --git a/Documentation/devicetree/bindings/net/can/c_can.txt b/Documentation/devicetree/bindings/net/can/c_can.txt deleted file mode 100644 index 366479806acb..000000000000 --- a/Documentation/devicetree/bindings/net/can/c_can.txt +++ /dev/null @@ -1,65 +0,0 @@ -Bosch C_CAN/D_CAN controller Device Tree Bindings -------------------------------------------------- - -Required properties: -- compatible : Should be "bosch,c_can" for C_CAN controllers and - "bosch,d_can" for D_CAN controllers. - Can be "ti,dra7-d_can", "ti,am3352-d_can" or - "ti,am4372-d_can". -- reg : physical base address and size of the C_CAN/D_CAN - registers map -- interrupts : property with a value describing the interrupt - number - -The following are mandatory properties for DRA7x, AM33xx and AM43xx SoCs only: -- ti,hwmods : Must be "d_can<n>" or "c_can<n>", n being the - instance number - -The following are mandatory properties for Keystone 2 66AK2G SoCs only: -- power-domains : Should contain a phandle to a PM domain provider node - and an args specifier containing the DCAN device id - value. This property is as per the binding, - Documentation/devicetree/bindings/soc/ti/sci-pm-domain.yaml -- clocks : CAN functional clock phandle. This property is as per the - binding, - Documentation/devicetree/bindings/clock/ti,sci-clk.yaml - -Optional properties: -- syscon-raminit : Handle to system control region that contains the - RAMINIT register, register offset to the RAMINIT - register and the CAN instance number (0 offset). - -Note: "ti,hwmods" field is used to fetch the base address and irq -resources from TI, omap hwmod data base during device registration. -Future plan is to migrate hwmod data base contents into device tree -blob so that, all the required data will be used from device tree dts -file. - -Example: - -Step1: SoC common .dtsi file - - dcan1: d_can@481d0000 { - compatible = "bosch,d_can"; - reg = <0x481d0000 0x2000>; - interrupts = <55>; - interrupt-parent = <&intc>; - status = "disabled"; - }; - -(or) - - dcan1: d_can@481d0000 { - compatible = "bosch,d_can"; - ti,hwmods = "d_can1"; - reg = <0x481d0000 0x2000>; - interrupts = <55>; - interrupt-parent = <&intc>; - status = "disabled"; - }; - -Step 2: board specific .dts file - - &dcan1 { - status = "okay"; - }; diff --git a/Documentation/devicetree/bindings/net/can/can-controller.yaml b/Documentation/devicetree/bindings/net/can/can-controller.yaml index 9cf2ae097156..1f0e98051074 100644 --- a/Documentation/devicetree/bindings/net/can/can-controller.yaml +++ b/Documentation/devicetree/bindings/net/can/can-controller.yaml @@ -13,6 +13,15 @@ properties: $nodename: pattern: "^can(@.*)?$" + termination-gpios: + description: GPIO pin to enable CAN bus termination. + maxItems: 1 + + termination-ohms: + description: The resistance value of the CAN bus termination resistor. + minimum: 1 + maximum: 65535 + additionalProperties: true ... diff --git a/Documentation/devicetree/bindings/net/can/fsl,flexcan.yaml b/Documentation/devicetree/bindings/net/can/fsl,flexcan.yaml index 55bff1586b6f..3f0ee17c1461 100644 --- a/Documentation/devicetree/bindings/net/can/fsl,flexcan.yaml +++ b/Documentation/devicetree/bindings/net/can/fsl,flexcan.yaml @@ -119,6 +119,9 @@ properties: minimum: 0 maximum: 2 + termination-gpios: true + termination-ohms: true + required: - compatible - reg @@ -148,3 +151,17 @@ examples: fsl,stop-mode = <&gpr 0x34 28>; fsl,scu-index = /bits/ 8 <1>; }; + - | + #include <dt-bindings/interrupt-controller/irq.h> + #include <dt-bindings/gpio/gpio.h> + + can@2090000 { + compatible = "fsl,imx6q-flexcan"; + reg = <0x02090000 0x4000>; + interrupts = <0 110 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&clks 1>, <&clks 2>; + clock-names = "ipg", "per"; + fsl,stop-mode = <&gpr 0x34 28>; + termination-gpios = <&gpio1 0 GPIO_ACTIVE_LOW>; + termination-ohms = <120>; + }; diff --git a/Documentation/devicetree/bindings/net/can/renesas,rcar-canfd.yaml b/Documentation/devicetree/bindings/net/can/renesas,rcar-canfd.yaml index 0b33ba9ccb47..546c6e6d2fb0 100644 --- a/Documentation/devicetree/bindings/net/can/renesas,rcar-canfd.yaml +++ b/Documentation/devicetree/bindings/net/can/renesas,rcar-canfd.yaml @@ -30,13 +30,15 @@ properties: - renesas,r8a77995-canfd # R-Car D3 - const: renesas,rcar-gen3-canfd # R-Car Gen3 and RZ/G2 + - items: + - enum: + - renesas,r9a07g044-canfd # RZ/G2{L,LC} + - const: renesas,rzg2l-canfd # RZ/G2L family + reg: maxItems: 1 - interrupts: - items: - - description: Channel interrupt - - description: Global interrupt + interrupts: true clocks: maxItems: 3 @@ -50,8 +52,7 @@ properties: power-domains: maxItems: 1 - resets: - maxItems: 1 + resets: true renesas,no-can-fd: $ref: /schemas/types.yaml#/definitions/flag @@ -91,6 +92,62 @@ required: - channel0 - channel1 +if: + properties: + compatible: + contains: + enum: + - renesas,rzg2l-canfd +then: + properties: + interrupts: + items: + - description: CAN global error interrupt + - description: CAN receive FIFO interrupt + - description: CAN0 error interrupt + - description: CAN0 transmit interrupt + - description: CAN0 transmit/receive FIFO receive completion interrupt + - description: CAN1 error interrupt + - description: CAN1 transmit interrupt + - description: CAN1 transmit/receive FIFO receive completion interrupt + + interrupt-names: + items: + - const: g_err + - const: g_recc + - const: ch0_err + - const: ch0_rec + - const: ch0_trx + - const: ch1_err + - const: ch1_rec + - const: ch1_trx + + resets: + maxItems: 2 + + reset-names: + items: + - const: rstp_n + - const: rstc_n + + required: + - interrupt-names + - reset-names +else: + properties: + interrupts: + items: + - description: Channel interrupt + - description: Global interrupt + + interrupt-names: + items: + - const: ch_int + - const: g_int + + resets: + maxItems: 1 + unevaluatedProperties: false examples: diff --git a/Documentation/devicetree/bindings/net/fsl,fec.yaml b/Documentation/devicetree/bindings/net/fsl,fec.yaml new file mode 100644 index 000000000000..eca41443fcce --- /dev/null +++ b/Documentation/devicetree/bindings/net/fsl,fec.yaml @@ -0,0 +1,244 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/net/fsl,fec.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Freescale Fast Ethernet Controller (FEC) + +maintainers: + - Joakim Zhang <qiangqing.zhang@nxp.com> + +allOf: + - $ref: ethernet-controller.yaml# + +properties: + compatible: + oneOf: + - enum: + - fsl,imx25-fec + - fsl,imx27-fec + - fsl,imx28-fec + - fsl,imx6q-fec + - fsl,mvf600-fec + - items: + - enum: + - fsl,imx53-fec + - fsl,imx6sl-fec + - const: fsl,imx25-fec + - items: + - enum: + - fsl,imx35-fec + - fsl,imx51-fec + - const: fsl,imx27-fec + - items: + - enum: + - fsl,imx6ul-fec + - fsl,imx6sx-fec + - const: fsl,imx6q-fec + - items: + - enum: + - fsl,imx7d-fec + - const: fsl,imx6sx-fec + - items: + - const: fsl,imx8mq-fec + - const: fsl,imx6sx-fec + - items: + - enum: + - fsl,imx8mm-fec + - fsl,imx8mn-fec + - fsl,imx8mp-fec + - const: fsl,imx8mq-fec + - const: fsl,imx6sx-fec + - items: + - const: fsl,imx8qm-fec + - const: fsl,imx6sx-fec + - items: + - enum: + - fsl,imx8qxp-fec + - const: fsl,imx8qm-fec + - const: fsl,imx6sx-fec + + reg: + maxItems: 1 + + interrupts: + minItems: 1 + maxItems: 4 + + interrupt-names: + oneOf: + - items: + - const: int0 + - items: + - const: int0 + - const: pps + - items: + - const: int0 + - const: int1 + - const: int2 + - items: + - const: int0 + - const: int1 + - const: int2 + - const: pps + + clocks: + minItems: 2 + maxItems: 5 + description: + The "ipg", for MAC ipg_clk_s, ipg_clk_mac_s that are for register accessing. + The "ahb", for MAC ipg_clk, ipg_clk_mac that are bus clock. + The "ptp"(option), for IEEE1588 timer clock that requires the clock. + The "enet_clk_ref"(option), for MAC transmit/receiver reference clock like + RGMII TXC clock or RMII reference clock. It depends on board design, + the clock is required if RGMII TXC and RMII reference clock source from + SOC internal PLL. + The "enet_out"(option), output clock for external device, like supply clock + for PHY. The clock is required if PHY clock source from SOC. + The "enet_2x_txclk"(option), for RGMII sampling clock which fixed at 250Mhz. + The clock is required if SoC RGMII enable clock delay. + + clock-names: + minItems: 2 + maxItems: 5 + items: + enum: + - ipg + - ahb + - ptp + - enet_clk_ref + - enet_out + - enet_2x_txclk + + phy-mode: true + + phy-handle: true + + fixed-link: true + + local-mac-address: true + + mac-address: true + + tx-internal-delay-ps: + enum: [0, 2000] + + rx-internal-delay-ps: + enum: [0, 2000] + + phy-supply: + description: + Regulator that powers the Ethernet PHY. + + fsl,num-tx-queues: + $ref: /schemas/types.yaml#/definitions/uint32 + description: + The property is valid for enet-avb IP, which supports hw multi queues. + Should specify the tx queue number, otherwise set tx queue number to 1. + enum: [1, 2, 3] + + fsl,num-rx-queues: + $ref: /schemas/types.yaml#/definitions/uint32 + description: + The property is valid for enet-avb IP, which supports hw multi queues. + Should specify the rx queue number, otherwise set rx queue number to 1. + enum: [1, 2, 3] + + fsl,magic-packet: + $ref: /schemas/types.yaml#/definitions/flag + description: + If present, indicates that the hardware supports waking up via magic packet. + + fsl,err006687-workaround-present: + $ref: /schemas/types.yaml#/definitions/flag + description: + If present indicates that the system has the hardware workaround for + ERR006687 applied and does not need a software workaround. + + fsl,stop-mode: + $ref: /schemas/types.yaml#/definitions/phandle-array + description: + Register bits of stop mode control, the format is <&gpr req_gpr req_bit>. + gpr is the phandle to general purpose register node. + req_gpr is the gpr register offset for ENET stop request. + req_bit is the gpr bit offset for ENET stop request. + + mdio: + type: object + description: + Specifies the mdio bus in the FEC, used as a container for phy nodes. + + # Deprecated optional properties: + # To avoid these, create a phy node according to ethernet-phy.yaml in the same + # directory, and point the FEC's "phy-handle" property to it. Then use + # the phy's reset binding, again described by ethernet-phy.yaml. + + phy-reset-gpios: + deprecated: true + description: + Should specify the gpio for phy reset. + + phy-reset-duration: + deprecated: true + description: + Reset duration in milliseconds. Should present only if property + "phy-reset-gpios" is available. Missing the property will have the + duration be 1 millisecond. Numbers greater than 1000 are invalid + and 1 millisecond will be used instead. + + phy-reset-active-high: + deprecated: true + description: + If present then the reset sequence using the GPIO specified in the + "phy-reset-gpios" property is reversed (H=reset state, L=operation state). + + phy-reset-post-delay: + deprecated: true + description: + Post reset delay in milliseconds. If present then a delay of phy-reset-post-delay + milliseconds will be observed after the phy-reset-gpios has been toggled. + Can be omitted thus no delay is observed. Delay is in range of 1ms to 1000ms. + Other delays are invalid. + +required: + - compatible + - reg + - interrupts + +# FIXME: We had better set additionalProperties to false to avoid invalid or at +# least undocumented properties. However, PHY may have a deprecated option to +# place PHY OF properties in the MAC node, such as Micrel PHY, and we can find +# these boards which is based on i.MX6QDL. +additionalProperties: false + +examples: + - | + ethernet@83fec000 { + compatible = "fsl,imx51-fec", "fsl,imx27-fec"; + reg = <0x83fec000 0x4000>; + interrupts = <87>; + phy-mode = "mii"; + phy-reset-gpios = <&gpio2 14 0>; + phy-supply = <®_fec_supply>; + }; + + ethernet@83fed000 { + compatible = "fsl,imx51-fec", "fsl,imx27-fec"; + reg = <0x83fed000 0x4000>; + interrupts = <87>; + phy-mode = "mii"; + phy-reset-gpios = <&gpio2 14 0>; + phy-supply = <®_fec_supply>; + phy-handle = <ðphy0>; + + mdio { + #address-cells = <1>; + #size-cells = <0>; + + ethphy0: ethernet-phy@0 { + compatible = "ethernet-phy-ieee802.3-c22"; + reg = <0>; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/net/fsl-fec.txt b/Documentation/devicetree/bindings/net/fsl-fec.txt deleted file mode 100644 index 9b543789cd52..000000000000 --- a/Documentation/devicetree/bindings/net/fsl-fec.txt +++ /dev/null @@ -1,95 +0,0 @@ -* Freescale Fast Ethernet Controller (FEC) - -Required properties: -- compatible : Should be "fsl,<soc>-fec" -- reg : Address and length of the register set for the device -- interrupts : Should contain fec interrupt -- phy-mode : See ethernet.txt file in the same directory - -Optional properties: -- phy-supply : regulator that powers the Ethernet PHY. -- phy-handle : phandle to the PHY device connected to this device. -- fixed-link : Assume a fixed link. See fixed-link.txt in the same directory. - Use instead of phy-handle. -- fsl,num-tx-queues : The property is valid for enet-avb IP, which supports - hw multi queues. Should specify the tx queue number, otherwise set tx queue - number to 1. -- fsl,num-rx-queues : The property is valid for enet-avb IP, which supports - hw multi queues. Should specify the rx queue number, otherwise set rx queue - number to 1. -- fsl,magic-packet : If present, indicates that the hardware supports waking - up via magic packet. -- fsl,err006687-workaround-present: If present indicates that the system has - the hardware workaround for ERR006687 applied and does not need a software - workaround. -- fsl,stop-mode: register bits of stop mode control, the format is - <&gpr req_gpr req_bit>. - gpr is the phandle to general purpose register node. - req_gpr is the gpr register offset for ENET stop request. - req_bit is the gpr bit offset for ENET stop request. - -interrupt-names: names of the interrupts listed in interrupts property in - the same order. The defaults if not specified are - __Number of interrupts__ __Default__ - 1 "int0" - 2 "int0", "pps" - 3 "int0", "int1", "int2" - 4 "int0", "int1", "int2", "pps" - The order may be changed as long as they correspond to the interrupts - property. Currently, only i.mx7 uses "int1" and "int2". They correspond to - tx/rx queues 1 and 2. "int0" will be used for queue 0 and ENET_MII interrupts. - For imx6sx, "int0" handles all 3 queues and ENET_MII. "pps" is for the pulse - per second interrupt associated with 1588 precision time protocol(PTP). - -Optional subnodes: -- mdio : specifies the mdio bus in the FEC, used as a container for phy nodes - according to phy.txt in the same directory - -Deprecated optional properties: - To avoid these, create a phy node according to phy.txt in the same - directory, and point the fec's "phy-handle" property to it. Then use - the phy's reset binding, again described by phy.txt. -- phy-reset-gpios : Should specify the gpio for phy reset -- phy-reset-duration : Reset duration in milliseconds. Should present - only if property "phy-reset-gpios" is available. Missing the property - will have the duration be 1 millisecond. Numbers greater than 1000 are - invalid and 1 millisecond will be used instead. -- phy-reset-active-high : If present then the reset sequence using the GPIO - specified in the "phy-reset-gpios" property is reversed (H=reset state, - L=operation state). -- phy-reset-post-delay : Post reset delay in milliseconds. If present then - a delay of phy-reset-post-delay milliseconds will be observed after the - phy-reset-gpios has been toggled. Can be omitted thus no delay is - observed. Delay is in range of 1ms to 1000ms. Other delays are invalid. - -Example: - -ethernet@83fec000 { - compatible = "fsl,imx51-fec", "fsl,imx27-fec"; - reg = <0x83fec000 0x4000>; - interrupts = <87>; - phy-mode = "mii"; - phy-reset-gpios = <&gpio2 14 GPIO_ACTIVE_LOW>; /* GPIO2_14 */ - local-mac-address = [00 04 9F 01 1B B9]; - phy-supply = <®_fec_supply>; -}; - -Example with phy specified: - -ethernet@83fec000 { - compatible = "fsl,imx51-fec", "fsl,imx27-fec"; - reg = <0x83fec000 0x4000>; - interrupts = <87>; - phy-mode = "mii"; - phy-reset-gpios = <&gpio2 14 GPIO_ACTIVE_LOW>; /* GPIO2_14 */ - local-mac-address = [00 04 9F 01 1B B9]; - phy-supply = <®_fec_supply>; - phy-handle = <ðphy>; - mdio { - clock-frequency = <5000000>; - ethphy: ethernet-phy@6 { - compatible = "ethernet-phy-ieee802.3-c22"; - reg = <6>; - max-speed = <100>; - }; - }; -}; diff --git a/Documentation/devicetree/bindings/net/imx-dwmac.txt b/Documentation/devicetree/bindings/net/imx-dwmac.txt deleted file mode 100644 index 921d522fe8d7..000000000000 --- a/Documentation/devicetree/bindings/net/imx-dwmac.txt +++ /dev/null @@ -1,56 +0,0 @@ -IMX8 glue layer controller, NXP imx8 families support Synopsys MAC 5.10a IP. - -This file documents platform glue layer for IMX. -Please see stmmac.txt for the other unchanged properties. - -The device node has following properties. - -Required properties: -- compatible: Should be "nxp,imx8mp-dwmac-eqos" to select glue layer - and "snps,dwmac-5.10a" to select IP version. -- clocks: Must contain a phandle for each entry in clock-names. -- clock-names: Should be "stmmaceth" for the host clock. - Should be "pclk" for the MAC apb clock. - Should be "ptp_ref" for the MAC timer clock. - Should be "tx" for the MAC RGMII TX clock: - Should be "mem" for EQOS MEM clock. - - "mem" clock is required for imx8dxl platform. - - "mem" clock is not required for imx8mp platform. -- interrupt-names: Should contain a list of interrupt names corresponding to - the interrupts in the interrupts property, if available. - Should be "macirq" for the main MAC IRQ - Should be "eth_wake_irq" for the IT which wake up system -- intf_mode: Should be phandle/offset pair. The phandle to the syscon node which - encompases the GPR register, and the offset of the GPR register. - - required for imx8mp platform. - - is optional for imx8dxl platform. - -Optional properties: -- intf_mode: is optional for imx8dxl platform. -- snps,rmii_refclk_ext: to select RMII reference clock from external. - -Example: - eqos: ethernet@30bf0000 { - compatible = "nxp,imx8mp-dwmac-eqos", "snps,dwmac-5.10a"; - reg = <0x30bf0000 0x10000>; - interrupts = <GIC_SPI 134 IRQ_TYPE_LEVEL_HIGH>, - <GIC_SPI 135 IRQ_TYPE_LEVEL_HIGH>; - interrupt-names = "eth_wake_irq", "macirq"; - clocks = <&clk IMX8MP_CLK_ENET_QOS_ROOT>, - <&clk IMX8MP_CLK_QOS_ENET_ROOT>, - <&clk IMX8MP_CLK_ENET_QOS_TIMER>, - <&clk IMX8MP_CLK_ENET_QOS>; - clock-names = "stmmaceth", "pclk", "ptp_ref", "tx"; - assigned-clocks = <&clk IMX8MP_CLK_ENET_AXI>, - <&clk IMX8MP_CLK_ENET_QOS_TIMER>, - <&clk IMX8MP_CLK_ENET_QOS>; - assigned-clock-parents = <&clk IMX8MP_SYS_PLL1_266M>, - <&clk IMX8MP_SYS_PLL2_100M>, - <&clk IMX8MP_SYS_PLL2_125M>; - assigned-clock-rates = <0>, <100000000>, <125000000>; - nvmem-cells = <ð_mac0>; - nvmem-cell-names = "mac-address"; - nvmem_macaddr_swap; - intf_mode = <&gpr 0x4>; - status = "disabled"; - }; diff --git a/Documentation/devicetree/bindings/net/intel,dwmac-plat.yaml b/Documentation/devicetree/bindings/net/intel,dwmac-plat.yaml index c1948ce00081..08a3f1f6aea2 100644 --- a/Documentation/devicetree/bindings/net/intel,dwmac-plat.yaml +++ b/Documentation/devicetree/bindings/net/intel,dwmac-plat.yaml @@ -116,7 +116,6 @@ examples: snps,mtl-rx-config = <&mtl_rx_setup>; snps,mtl-tx-config = <&mtl_tx_setup>; snps,tso; - status = "okay"; mdio0 { #address-cells = <1>; diff --git a/Documentation/devicetree/bindings/net/intel,ixp46x-ptp-timer.yaml b/Documentation/devicetree/bindings/net/intel,ixp46x-ptp-timer.yaml new file mode 100644 index 000000000000..8b9b3f915d92 --- /dev/null +++ b/Documentation/devicetree/bindings/net/intel,ixp46x-ptp-timer.yaml @@ -0,0 +1,54 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +# Copyright 2018 Linaro Ltd. +%YAML 1.2 +--- +$id: "http://devicetree.org/schemas/net/intel,ixp46x-ptp-timer.yaml#" +$schema: "http://devicetree.org/meta-schemas/core.yaml#" + +title: Intel IXP46x PTP Timer (TSYNC) + +maintainers: + - Linus Walleij <linus.walleij@linaro.org> + +description: | + The Intel IXP46x PTP timer is known in the manual as IEEE1588 Hardware + Assist and Time Synchronization Hardware Assist TSYNC provides a PTP + timer. It exists in the Intel IXP45x and IXP46x XScale SoCs. + +properties: + compatible: + const: intel,ixp46x-ptp-timer + + reg: + maxItems: 1 + + interrupts: + items: + - description: Interrupt to trigger master mode snapshot from the + PRP timer, usually a GPIO interrupt. + - description: Interrupt to trigger slave mode snapshot from the + PRP timer, usually a GPIO interrupt. + + interrupt-names: + items: + - const: master + - const: slave + +required: + - compatible + - reg + - interrupts + - interrupt-names + +additionalProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/irq.h> + ptp-timer@c8010000 { + compatible = "intel,ixp46x-ptp-timer"; + reg = <0xc8010000 0x1000>; + interrupt-parent = <&gpio0>; + interrupts = <8 IRQ_TYPE_EDGE_FALLING>, <7 IRQ_TYPE_EDGE_FALLING>; + interrupt-names = "master", "slave"; + }; diff --git a/Documentation/devicetree/bindings/net/intel,ixp4xx-ethernet.yaml b/Documentation/devicetree/bindings/net/intel,ixp4xx-ethernet.yaml index f2e91d1bf7d7..378ed2d3b003 100644 --- a/Documentation/devicetree/bindings/net/intel,ixp4xx-ethernet.yaml +++ b/Documentation/devicetree/bindings/net/intel,ixp4xx-ethernet.yaml @@ -71,7 +71,6 @@ examples: ethernet@c8009000 { compatible = "intel,ixp4xx-ethernet"; reg = <0xc8009000 0x1000>; - status = "disabled"; queue-rx = <&qmgr 4>; queue-txready = <&qmgr 21>; intel,npe-handle = <&npe 1>; @@ -82,7 +81,6 @@ examples: ethernet@c800c000 { compatible = "intel,ixp4xx-ethernet"; reg = <0xc800c000 0x1000>; - status = "disabled"; queue-rx = <&qmgr 3>; queue-txready = <&qmgr 20>; intel,npe-handle = <&npe 2>; diff --git a/Documentation/devicetree/bindings/net/litex,liteeth.yaml b/Documentation/devicetree/bindings/net/litex,liteeth.yaml new file mode 100644 index 000000000000..76c164a8199a --- /dev/null +++ b/Documentation/devicetree/bindings/net/litex,liteeth.yaml @@ -0,0 +1,98 @@ +# SPDX-License-Identifier: GPL-2.0-or-later OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/net/litex,liteeth.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: LiteX LiteETH ethernet device + +maintainers: + - Joel Stanley <joel@jms.id.au> + +description: | + LiteETH is a small footprint and configurable Ethernet core for FPGA based + system on chips. + + The hardware source is Open Source and can be found on at + https://github.com/enjoy-digital/liteeth/. + +allOf: + - $ref: ethernet-controller.yaml# + +properties: + compatible: + const: litex,liteeth + + reg: + items: + - description: MAC registers + - description: MDIO registers + - description: Packet buffer + + reg-names: + items: + - const: mac + - const: mdio + - const: buffer + + interrupts: + maxItems: 1 + + litex,rx-slots: + description: Number of slots in the receive buffer + $ref: /schemas/types.yaml#/definitions/uint32 + minimum: 1 + default: 2 + + litex,tx-slots: + description: Number of slots in the transmit buffer + $ref: /schemas/types.yaml#/definitions/uint32 + minimum: 1 + default: 2 + + litex,slot-size: + description: Size in bytes of a slot in the tx/rx buffer + $ref: /schemas/types.yaml#/definitions/uint32 + minimum: 0x800 + default: 0x800 + + mac-address: true + local-mac-address: true + phy-handle: true + + mdio: + $ref: mdio.yaml# + +required: + - compatible + - reg + - interrupts + +additionalProperties: false + +examples: + - | + mac: ethernet@8020000 { + compatible = "litex,liteeth"; + reg = <0x8021000 0x100>, + <0x8020800 0x100>, + <0x8030000 0x2000>; + reg-names = "mac", "mdio", "buffer"; + litex,rx-slots = <2>; + litex,tx-slots = <2>; + litex,slot-size = <0x800>; + interrupts = <0x11 0x1>; + phy-handle = <ð_phy>; + + mdio { + #address-cells = <1>; + #size-cells = <0>; + + eth_phy: ethernet-phy@0 { + reg = <0>; + }; + }; + }; +... + +# vim: set ts=2 sw=2 sts=2 tw=80 et cc=80 ft=yaml : diff --git a/Documentation/devicetree/bindings/net/macb.txt b/Documentation/devicetree/bindings/net/macb.txt index a4d547efc32a..af9df2f01a1c 100644 --- a/Documentation/devicetree/bindings/net/macb.txt +++ b/Documentation/devicetree/bindings/net/macb.txt @@ -8,6 +8,7 @@ Required properties: Use "cdns,np4-macb" for NP4 SoC devices. Use "cdns,at32ap7000-macb" for other 10/100 usage or use the generic form: "cdns,macb". Use "atmel,sama5d2-gem" for the GEM IP (10/100) available on Atmel sama5d2 SoCs. + Use "atmel,sama5d29-gem" for GEM XL IP (10/100) available on Atmel sama5d29 SoCs. Use "atmel,sama5d3-macb" for the 10/100Mbit IP available on Atmel sama5d3 SoCs. Use "atmel,sama5d3-gem" for the Gigabit IP available on Atmel sama5d3 SoCs. Use "atmel,sama5d4-gem" for the GEM IP (10/100) available on Atmel sama5d4 SoCs. diff --git a/Documentation/devicetree/bindings/net/micrel,ks8851.yaml b/Documentation/devicetree/bindings/net/micrel,ks8851.yaml new file mode 100644 index 000000000000..5aa7cf2eacb1 --- /dev/null +++ b/Documentation/devicetree/bindings/net/micrel,ks8851.yaml @@ -0,0 +1,96 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/net/micrel,ks8851.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Micrel KS8851 Ethernet MAC (SPI and Parallel bus options) + +maintainers: + - Marek Vasut <marex@denx.de> + +properties: + compatible: + enum: + - micrel,ks8851 # SPI bus option + - micrel,ks8851-mll # Parallel bus option + + interrupts: + maxItems: 1 + + reg: + minItems: 1 + items: + - description: SPI or Parallel bus hardware address + - description: Parallel bus command mode address + + reset-gpios: + maxItems: 1 + description: + The reset_n input pin + + vdd-supply: + description: | + Analog 3.3V supply for Ethernet MAC + + vdd-io-supply: + description: | + Digital 1.8V IO supply for Ethernet MAC + +required: + - compatible + - reg + - interrupts + +allOf: + - $ref: ethernet-controller.yaml# + - if: + properties: + compatible: + contains: + const: micrel,ks8851 + then: + properties: + reg: + maxItems: 1 + - if: + properties: + compatible: + contains: + const: micrel,ks8851-mll + then: + properties: + reg: + minItems: 2 + +unevaluatedProperties: false + +examples: + - | + /* SPI bus option */ + spi { + #address-cells = <1>; + #size-cells = <0>; + ethernet@0 { + compatible = "micrel,ks8851"; + reg = <0>; + interrupt-parent = <&msmgpio>; + interrupts = <90 8>; + vdd-supply = <&ext_l2>; + vdd-io-supply = <&pm8921_lvs6>; + reset-gpios = <&msmgpio 89 0>; + }; + }; + - | + #include <dt-bindings/interrupt-controller/irq.h> + /* Parallel bus option */ + memory-controller { + #address-cells = <2>; + #size-cells = <1>; + ethernet@1,0 { + compatible = "micrel,ks8851-mll"; + reg = <1 0x0 0x2>, <1 0x2 0x20000>; + interrupt-parent = <&gpioc>; + interrupts = <3 IRQ_TYPE_LEVEL_LOW>; + }; + }; diff --git a/Documentation/devicetree/bindings/net/micrel-ks8851.txt b/Documentation/devicetree/bindings/net/micrel-ks8851.txt deleted file mode 100644 index bbdf9a7359a2..000000000000 --- a/Documentation/devicetree/bindings/net/micrel-ks8851.txt +++ /dev/null @@ -1,18 +0,0 @@ -Micrel KS8851 Ethernet mac (MLL) - -Required properties: -- compatible = "micrel,ks8851-mll" of parallel interface -- reg : 2 physical address and size of registers for data and command -- interrupts : interrupt connection - -Micrel KS8851 Ethernet mac (SPI) - -Required properties: -- compatible = "micrel,ks8851" or the deprecated "ks8851" -- reg : chip select number -- interrupts : interrupt connection - -Optional properties: -- vdd-supply: analog 3.3V supply for Ethernet mac -- vdd-io-supply: digital 1.8V IO supply for Ethernet mac -- reset-gpios: reset_n input pin diff --git a/Documentation/devicetree/bindings/net/mscc-phy-vsc8531.txt b/Documentation/devicetree/bindings/net/mscc-phy-vsc8531.txt index 87a27d775d48..0a3647fe331b 100644 --- a/Documentation/devicetree/bindings/net/mscc-phy-vsc8531.txt +++ b/Documentation/devicetree/bindings/net/mscc-phy-vsc8531.txt @@ -67,7 +67,7 @@ Example: compatible = "ethernet-phy-id0007.0570"; vsc8531,vddmac = <3300>; vsc8531,edge-slowdown = <7>; - vsc8531,led-0-mode = <LINK_1000_ACTIVITY>; - vsc8531,led-1-mode = <LINK_100_ACTIVITY>; + vsc8531,led-0-mode = <VSC8531_LINK_1000_ACTIVITY>; + vsc8531,led-1-mode = <VSC8531_LINK_100_ACTIVITY>; load-save-gpios = <&gpio 10 GPIO_ACTIVE_HIGH>; }; diff --git a/Documentation/devicetree/bindings/net/nfc/samsung,s3fwrn5.yaml b/Documentation/devicetree/bindings/net/nfc/samsung,s3fwrn5.yaml index 081742c2b726..64995cbb0f97 100644 --- a/Documentation/devicetree/bindings/net/nfc/samsung,s3fwrn5.yaml +++ b/Documentation/devicetree/bindings/net/nfc/samsung,s3fwrn5.yaml @@ -90,14 +90,11 @@ examples: # UART example on Raspberry Pi - | uart0 { - status = "okay"; - nfc { compatible = "samsung,s3fwrn82"; en-gpios = <&gpio 20 GPIO_ACTIVE_HIGH>; wake-gpios = <&gpio 16 GPIO_ACTIVE_HIGH>; - status = "okay"; }; }; diff --git a/Documentation/devicetree/bindings/net/nxp,dwmac-imx.yaml b/Documentation/devicetree/bindings/net/nxp,dwmac-imx.yaml new file mode 100644 index 000000000000..5629b2e4ccf8 --- /dev/null +++ b/Documentation/devicetree/bindings/net/nxp,dwmac-imx.yaml @@ -0,0 +1,93 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/net/nxp,dwmac-imx.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: NXP i.MX8 DWMAC glue layer Device Tree Bindings + +maintainers: + - Joakim Zhang <qiangqing.zhang@nxp.com> + +# We need a select here so we don't match all nodes with 'snps,dwmac' +select: + properties: + compatible: + contains: + enum: + - nxp,imx8mp-dwmac-eqos + - nxp,imx8dxl-dwmac-eqos + required: + - compatible + +allOf: + - $ref: "snps,dwmac.yaml#" + +properties: + compatible: + oneOf: + - items: + - enum: + - nxp,imx8mp-dwmac-eqos + - nxp,imx8dxl-dwmac-eqos + - const: snps,dwmac-5.10a + + clocks: + minItems: 3 + maxItems: 5 + items: + - description: MAC host clock + - description: MAC apb clock + - description: MAC timer clock + - description: MAC RGMII TX clock + - description: EQOS MEM clock + + clock-names: + minItems: 3 + maxItems: 5 + contains: + enum: + - stmmaceth + - pclk + - ptp_ref + - tx + - mem + + intf_mode: + $ref: /schemas/types.yaml#/definitions/phandle-array + description: + Should be phandle/offset pair. The phandle to the syscon node which + encompases the GPR register, and the offset of the GPR register. + + snps,rmii_refclk_ext: + $ref: /schemas/types.yaml#/definitions/flag + description: + To select RMII reference clock from external. + +required: + - compatible + - clocks + - clock-names + +unevaluatedProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/arm-gic.h> + #include <dt-bindings/interrupt-controller/irq.h> + #include <dt-bindings/clock/imx8mp-clock.h> + + eqos: ethernet@30bf0000 { + compatible = "nxp,imx8mp-dwmac-eqos","snps,dwmac-5.10a"; + reg = <0x30bf0000 0x10000>; + interrupts = <GIC_SPI 135 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 134 IRQ_TYPE_LEVEL_HIGH>; + interrupt-names = "macirq", "eth_wake_irq"; + clocks = <&clk IMX8MP_CLK_ENET_QOS_ROOT>, + <&clk IMX8MP_CLK_QOS_ENET_ROOT>, + <&clk IMX8MP_CLK_ENET_QOS_TIMER>, + <&clk IMX8MP_CLK_ENET_QOS>; + clock-names = "stmmaceth", "pclk", "ptp_ref", "tx"; + phy-mode = "rgmii"; + status = "disabled"; + }; diff --git a/Documentation/devicetree/bindings/net/qca,ar71xx.yaml b/Documentation/devicetree/bindings/net/qca,ar71xx.yaml index f0db22645d73..cf4d35edaa1b 100644 --- a/Documentation/devicetree/bindings/net/qca,ar71xx.yaml +++ b/Documentation/devicetree/bindings/net/qca,ar71xx.yaml @@ -101,8 +101,6 @@ examples: phy-mode = "gmii"; - status = "disabled"; - fixed-link { speed = <1000>; full-duplex; @@ -148,32 +146,24 @@ examples: reg = <0x1>; phy-handle = <&phy_port0>; phy-mode = "internal"; - - status = "disabled"; }; switch_port2: port@2 { reg = <0x2>; phy-handle = <&phy_port1>; phy-mode = "internal"; - - status = "disabled"; }; switch_port3: port@3 { reg = <0x3>; phy-handle = <&phy_port2>; phy-mode = "internal"; - - status = "disabled"; }; switch_port4: port@4 { reg = <0x4>; phy-handle = <&phy_port3>; phy-mode = "internal"; - - status = "disabled"; }; }; @@ -183,34 +173,29 @@ examples: interrupt-parent = <&switch10>; - phy_port0: phy@0 { + phy_port0: ethernet-phy@0 { reg = <0x0>; interrupts = <0>; - status = "disabled"; }; - phy_port1: phy@1 { + phy_port1: ethernet-phy@1 { reg = <0x1>; interrupts = <0>; - status = "disabled"; }; - phy_port2: phy@2 { + phy_port2: ethernet-phy@2 { reg = <0x2>; interrupts = <0>; - status = "disabled"; }; - phy_port3: phy@3 { + phy_port3: ethernet-phy@3 { reg = <0x3>; interrupts = <0>; - status = "disabled"; }; - phy_port4: phy@4 { + phy_port4: ethernet-phy@4 { reg = <0x4>; interrupts = <0>; - status = "disabled"; }; }; }; diff --git a/Documentation/devicetree/bindings/net/qcom,ipa.yaml b/Documentation/devicetree/bindings/net/qcom,ipa.yaml index ed88ba4b94df..b8a0b392b24e 100644 --- a/Documentation/devicetree/bindings/net/qcom,ipa.yaml +++ b/Documentation/devicetree/bindings/net/qcom,ipa.yaml @@ -87,16 +87,24 @@ properties: - const: ipa-setup-ready interconnects: - items: - - description: Interconnect path between IPA and main memory - - description: Interconnect path between IPA and internal memory - - description: Interconnect path between IPA and the AP subsystem + oneOf: + - items: + - description: Path leading to system memory + - description: Path between the AP and IPA config space + - items: + - description: Path leading to system memory + - description: Path leading to internal memory + - description: Path between the AP and IPA config space interconnect-names: - items: - - const: memory - - const: imem - - const: config + oneOf: + - items: + - const: memory + - const: config + - items: + - const: memory + - const: imem + - const: config qcom,smem-states: $ref: /schemas/types.yaml#/definitions/phandle-array diff --git a/Documentation/devicetree/bindings/net/qcom,ipq4019-mdio.yaml b/Documentation/devicetree/bindings/net/qcom,ipq4019-mdio.yaml index 0c973310ada0..2af304341772 100644 --- a/Documentation/devicetree/bindings/net/qcom,ipq4019-mdio.yaml +++ b/Documentation/devicetree/bindings/net/qcom,ipq4019-mdio.yaml @@ -14,7 +14,9 @@ allOf: properties: compatible: - const: qcom,ipq4019-mdio + enum: + - qcom,ipq4019-mdio + - qcom,ipq5018-mdio "#address-cells": const: 1 @@ -23,7 +25,18 @@ properties: const: 0 reg: + minItems: 1 + maxItems: 2 + description: + the first Address and length of the register set for the MDIO controller. + the second Address and length of the register for ethernet LDO, this second + address range is only required by the platform IPQ50xx. + + clocks: maxItems: 1 + description: | + MDIO clock source frequency fixed to 100MHZ, this clock should be specified + by the platform IPQ807x, IPQ60xx and IPQ50xx. required: - compatible diff --git a/Documentation/devicetree/bindings/net/realtek-bluetooth.yaml b/Documentation/devicetree/bindings/net/realtek-bluetooth.yaml index 4f485df69ac3..0634e69dd9a6 100644 --- a/Documentation/devicetree/bindings/net/realtek-bluetooth.yaml +++ b/Documentation/devicetree/bindings/net/realtek-bluetooth.yaml @@ -17,10 +17,10 @@ description: properties: compatible: - oneOf: - - const: "realtek,rtl8723bs-bt" - - const: "realtek,rtl8723cs-bt" - - const: "realtek,rtl8822cs-bt" + enum: + - realtek,rtl8723bs-bt + - realtek,rtl8723cs-bt + - realtek,rtl8822cs-bt device-wake-gpios: maxItems: 1 diff --git a/Documentation/devicetree/bindings/net/renesas,etheravb.yaml b/Documentation/devicetree/bindings/net/renesas,etheravb.yaml index 005868f703a6..4c927d2c17d3 100644 --- a/Documentation/devicetree/bindings/net/renesas,etheravb.yaml +++ b/Documentation/devicetree/bindings/net/renesas,etheravb.yaml @@ -43,23 +43,20 @@ properties: - renesas,etheravb-r8a779a0 # R-Car V3U - const: renesas,etheravb-rcar-gen3 # R-Car Gen3 and RZ/G2 + - items: + - enum: + - renesas,r9a07g044-gbeth # RZ/G2{L,LC} + - const: renesas,rzg2l-gbeth # RZ/G2L + reg: true interrupts: true interrupt-names: true - clocks: - minItems: 1 - items: - - description: AVB functional clock - - description: Optional TXC reference clock + clocks: true - clock-names: - minItems: 1 - items: - - const: fck - - const: refclk + clock-names: true iommus: maxItems: 1 @@ -145,14 +142,20 @@ allOf: properties: compatible: contains: - const: renesas,etheravb-rcar-gen2 + enum: + - renesas,etheravb-rcar-gen2 + - renesas,rzg2l-gbeth then: properties: interrupts: - maxItems: 1 + minItems: 1 + maxItems: 3 interrupt-names: + minItems: 1 items: - const: mux + - const: fil + - const: arp_ns rx-internal-delay-ps: false else: properties: @@ -208,6 +211,36 @@ allOf: tx-internal-delay-ps: const: 2000 + - if: + properties: + compatible: + contains: + const: renesas,rzg2l-gbeth + then: + properties: + clocks: + items: + - description: Main clock + - description: Register access clock + - description: Reference clock for RGMII + clock-names: + items: + - const: axi + - const: chi + - const: refclk + else: + properties: + clocks: + minItems: 1 + items: + - description: AVB functional clock + - description: Optional TXC reference clock + clock-names: + minItems: 1 + items: + - const: fck + - const: refclk + additionalProperties: false examples: diff --git a/Documentation/devicetree/bindings/net/snps,dwmac.yaml b/Documentation/devicetree/bindings/net/snps,dwmac.yaml index d7652596a09b..42689b7d03a2 100644 --- a/Documentation/devicetree/bindings/net/snps,dwmac.yaml +++ b/Documentation/devicetree/bindings/net/snps,dwmac.yaml @@ -28,6 +28,7 @@ select: - snps,dwmac-4.00 - snps,dwmac-4.10a - snps,dwmac-4.20a + - snps,dwmac-5.10a - snps,dwxgmac - snps,dwxgmac-2.10 @@ -82,6 +83,7 @@ properties: - snps,dwmac-4.00 - snps,dwmac-4.10a - snps,dwmac-4.20a + - snps,dwmac-5.10a - snps,dwxgmac - snps,dwxgmac-2.10 @@ -375,6 +377,7 @@ allOf: - snps,dwmac-4.00 - snps,dwmac-4.10a - snps,dwmac-4.20a + - snps,dwmac-5.10a - snps,dwxgmac - snps,dwxgmac-2.10 - st,spear600-gmac diff --git a/Documentation/devicetree/bindings/net/ti,k3-am654-cpsw-nuss.yaml b/Documentation/devicetree/bindings/net/ti,k3-am654-cpsw-nuss.yaml index 783b9e32cf66..4b97a0f1175b 100644 --- a/Documentation/devicetree/bindings/net/ti,k3-am654-cpsw-nuss.yaml +++ b/Documentation/devicetree/bindings/net/ti,k3-am654-cpsw-nuss.yaml @@ -53,10 +53,10 @@ properties: "#size-cells": true compatible: - oneOf: - - const: ti,am654-cpsw-nuss - - const: ti,j721e-cpsw-nuss - - const: ti,am642-cpsw-nuss + enum: + - ti,am654-cpsw-nuss + - ti,j721e-cpsw-nuss + - ti,am642-cpsw-nuss reg: maxItems: 1 diff --git a/Documentation/devicetree/bindings/net/ti,k3-am654-cpts.yaml b/Documentation/devicetree/bindings/net/ti,k3-am654-cpts.yaml index 4317eba503ca..1a81bf70c88c 100644 --- a/Documentation/devicetree/bindings/net/ti,k3-am654-cpts.yaml +++ b/Documentation/devicetree/bindings/net/ti,k3-am654-cpts.yaml @@ -45,9 +45,9 @@ properties: pattern: "^cpts@[0-9a-f]+$" compatible: - oneOf: - - const: ti,am65-cpts - - const: ti,j721e-cpts + enum: + - ti,am65-cpts + - ti,j721e-cpts reg: maxItems: 1 diff --git a/Documentation/devicetree/bindings/nvmem/nintendo-otp.yaml b/Documentation/devicetree/bindings/nvmem/nintendo-otp.yaml new file mode 100644 index 000000000000..dbe4ffdd644c --- /dev/null +++ b/Documentation/devicetree/bindings/nvmem/nintendo-otp.yaml @@ -0,0 +1,44 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/nvmem/nintendo-otp.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Nintendo Wii and Wii U OTP Device Tree Bindings + +description: | + This binding represents the OTP memory as found on a Nintendo Wii or Wii U, + which contains common and per-console keys, signatures and related data + required to access peripherals. + + See https://wiiubrew.org/wiki/Hardware/OTP + +maintainers: + - Emmanuel Gil Peyrot <linkmauve@linkmauve.fr> + +allOf: + - $ref: "nvmem.yaml#" + +properties: + compatible: + enum: + - nintendo,hollywood-otp + - nintendo,latte-otp + + reg: + maxItems: 1 + +required: + - compatible + - reg + +unevaluatedProperties: false + +examples: + - | + otp@d8001ec { + compatible = "nintendo,latte-otp"; + reg = <0x0d8001ec 0x8>; + }; + +... diff --git a/Documentation/devicetree/bindings/nvmem/nvmem.yaml b/Documentation/devicetree/bindings/nvmem/nvmem.yaml index b8dc3d2b6e92..456fb808100a 100644 --- a/Documentation/devicetree/bindings/nvmem/nvmem.yaml +++ b/Documentation/devicetree/bindings/nvmem/nvmem.yaml @@ -40,7 +40,7 @@ properties: maxItems: 1 patternProperties: - "^.*@[0-9a-f]+$": + "@[0-9a-f]+(,[0-7])?$": type: object properties: diff --git a/Documentation/devicetree/bindings/nvmem/qcom,qfprom.yaml b/Documentation/devicetree/bindings/nvmem/qcom,qfprom.yaml index 861b205016b1..dede8892ee01 100644 --- a/Documentation/devicetree/bindings/nvmem/qcom,qfprom.yaml +++ b/Documentation/devicetree/bindings/nvmem/qcom,qfprom.yaml @@ -51,6 +51,9 @@ properties: vcc-supply: description: Our power supply. + power-domains: + maxItems: 1 + # Needed if any child nodes are present. "#address-cells": const: 1 diff --git a/Documentation/devicetree/bindings/nvmem/socionext,uniphier-efuse.yaml b/Documentation/devicetree/bindings/nvmem/socionext,uniphier-efuse.yaml new file mode 100644 index 000000000000..2578e39deda9 --- /dev/null +++ b/Documentation/devicetree/bindings/nvmem/socionext,uniphier-efuse.yaml @@ -0,0 +1,95 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/nvmem/socionext,uniphier-efuse.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Socionext UniPhier eFuse bindings + +maintainers: + - Keiji Hayashibara <hayashibara.keiji@socionext.com> + - Kunihiko Hayashi <hayashi.kunihiko@socionext.com> + +allOf: + - $ref: "nvmem.yaml#" + +properties: + "#address-cells": true + "#size-cells": true + + compatible: + const: socionext,uniphier-efuse + + reg: + maxItems: 1 + +required: + - compatible + - reg + +unevaluatedProperties: false + +examples: + - | + // The UniPhier eFuse should be a subnode of a "soc-glue" node. + + soc-glue@5f900000 { + compatible = "simple-mfd"; + #address-cells = <1>; + #size-cells = <1>; + ranges = <0x0 0x5f900000 0x2000>; + + efuse@100 { + compatible = "socionext,uniphier-efuse"; + reg = <0x100 0x28>; + }; + + efuse@200 { + compatible = "socionext,uniphier-efuse"; + reg = <0x200 0x68>; + #address-cells = <1>; + #size-cells = <1>; + + /* Data cells */ + usb_rterm0: trim@54,4 { + reg = <0x54 1>; + bits = <4 2>; + }; + usb_rterm1: trim@55,4 { + reg = <0x55 1>; + bits = <4 2>; + }; + usb_rterm2: trim@58,4 { + reg = <0x58 1>; + bits = <4 2>; + }; + usb_rterm3: trim@59,4 { + reg = <0x59 1>; + bits = <4 2>; + }; + usb_sel_t0: trim@54,0 { + reg = <0x54 1>; + bits = <0 4>; + }; + usb_sel_t1: trim@55,0 { + reg = <0x55 1>; + bits = <0 4>; + }; + usb_sel_t2: trim@58,0 { + reg = <0x58 1>; + bits = <0 4>; + }; + usb_sel_t3: trim@59,0 { + reg = <0x59 1>; + bits = <0 4>; + }; + usb_hs_i0: trim@56,0 { + reg = <0x56 1>; + bits = <0 4>; + }; + usb_hs_i2: trim@5a,0 { + reg = <0x5a 1>; + bits = <0 4>; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/nvmem/uniphier-efuse.txt b/Documentation/devicetree/bindings/nvmem/uniphier-efuse.txt deleted file mode 100644 index eccf490d5a6d..000000000000 --- a/Documentation/devicetree/bindings/nvmem/uniphier-efuse.txt +++ /dev/null @@ -1,49 +0,0 @@ -= UniPhier eFuse device tree bindings = - -This UniPhier eFuse must be under soc-glue. - -Required properties: -- compatible: should be "socionext,uniphier-efuse" -- reg: should contain the register location and length - -= Data cells = -Are child nodes of efuse, bindings of which as described in -bindings/nvmem/nvmem.txt - -Example: - - soc-glue@5f900000 { - compatible = "socionext,uniphier-ld20-soc-glue-debug", - "simple-mfd"; - #address-cells = <1>; - #size-cells = <1>; - ranges = <0x0 0x5f900000 0x2000>; - - efuse@100 { - compatible = "socionext,uniphier-efuse"; - reg = <0x100 0x28>; - }; - - efuse@200 { - compatible = "socionext,uniphier-efuse"; - reg = <0x200 0x68>; - #address-cells = <1>; - #size-cells = <1>; - - /* Data cells */ - usb_mon: usb-mon@54 { - reg = <0x54 0xc>; - }; - }; - }; - -= Data consumers = -Are device nodes which consume nvmem data cells. - -Example: - - usb { - ... - nvmem-cells = <&usb_mon>; - nvmem-cell-names = "usb_mon"; - } diff --git a/Documentation/devicetree/bindings/pci/amlogic,meson-pcie.txt b/Documentation/devicetree/bindings/pci/amlogic,meson-pcie.txt index b6acbe694ffb..c3a75ac6e59d 100644 --- a/Documentation/devicetree/bindings/pci/amlogic,meson-pcie.txt +++ b/Documentation/devicetree/bindings/pci/amlogic,meson-pcie.txt @@ -3,7 +3,7 @@ Amlogic Meson AXG DWC PCIE SoC controller Amlogic Meson PCIe host controller is based on the Synopsys DesignWare PCI core. It shares common functions with the PCIe DesignWare core driver and inherits common properties defined in -Documentation/devicetree/bindings/pci/designware-pcie.txt. +Documentation/devicetree/bindings/pci/snps,dw-pcie.yaml. Additional properties are described here: @@ -33,7 +33,7 @@ Required properties: - phy-names: must contain "pcie" - device_type: - should be "pci". As specified in designware-pcie.txt + should be "pci". As specified in snps,dw-pcie.yaml Example configuration: diff --git a/Documentation/devicetree/bindings/pci/axis,artpec6-pcie.txt b/Documentation/devicetree/bindings/pci/axis,artpec6-pcie.txt index 979dc7b6cfe8..cc6dcdb676b9 100644 --- a/Documentation/devicetree/bindings/pci/axis,artpec6-pcie.txt +++ b/Documentation/devicetree/bindings/pci/axis,artpec6-pcie.txt @@ -1,7 +1,7 @@ * Axis ARTPEC-6 PCIe interface This PCIe host controller is based on the Synopsys DesignWare PCIe IP -and thus inherits all the common properties defined in designware-pcie.txt. +and thus inherits all the common properties defined in snps,dw-pcie.yaml. Required properties: - compatible: "axis,artpec6-pcie", "snps,dw-pcie" for ARTPEC-6 in RC mode; diff --git a/Documentation/devicetree/bindings/pci/designware-pcie.txt b/Documentation/devicetree/bindings/pci/designware-pcie.txt deleted file mode 100644 index 78494c4050f7..000000000000 --- a/Documentation/devicetree/bindings/pci/designware-pcie.txt +++ /dev/null @@ -1,77 +0,0 @@ -* Synopsys DesignWare PCIe interface - -Required properties: -- compatible: - "snps,dw-pcie" for RC mode; - "snps,dw-pcie-ep" for EP mode; -- reg: For designware cores version < 4.80 contains the configuration - address space. For designware core version >= 4.80, contains - the configuration and ATU address space -- reg-names: Must be "config" for the PCIe configuration space and "atu" for - the ATU address space. - (The old way of getting the configuration address space from "ranges" - is deprecated and should be avoided.) -RC mode: -- #address-cells: set to <3> -- #size-cells: set to <2> -- device_type: set to "pci" -- 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 PCIe interface to interrupt - numbers. -EP mode: -- num-ib-windows: number of inbound address translation windows -- num-ob-windows: number of outbound address translation windows - -Optional properties: -- num-lanes: number of lanes to use (this property should be specified unless - the link is brought already up in BIOS) -- reset-gpio: GPIO pin number of power good signal -- clocks: Must contain an entry for each entry in clock-names. - See ../clocks/clock-bindings.txt for details. -- clock-names: Must include the following entries: - - "pcie" - - "pcie_bus" -- snps,enable-cdm-check: This is a boolean property and if present enables - automatic checking of CDM (Configuration Dependent Module) registers - for data corruption. CDM registers include standard PCIe configuration - space registers, Port Logic registers, DMA and iATU (internal Address - Translation Unit) registers. -RC mode: -- num-viewport: number of view ports configured in hardware. If a platform - does not specify it, the driver assumes 2. -- bus-range: PCI bus numbers covered (it is recommended for new devicetrees - to specify this property, to keep backwards compatibility a range of - 0x00-0xff is assumed if not present) - -EP mode: -- max-functions: maximum number of functions that can be configured - -Example configuration: - - pcie: pcie@dfc00000 { - compatible = "snps,dw-pcie"; - reg = <0xdfc00000 0x0001000>, /* IP registers */ - <0xd0000000 0x0002000>; /* Configuration space */ - reg-names = "dbi", "config"; - #address-cells = <3>; - #size-cells = <2>; - device_type = "pci"; - ranges = <0x81000000 0 0x00000000 0xde000000 0 0x00010000 - 0x82000000 0 0xd0400000 0xd0400000 0 0x0d000000>; - interrupts = <25>, <24>; - #interrupt-cells = <1>; - num-lanes = <1>; - }; -or - pcie: pcie@dfc00000 { - compatible = "snps,dw-pcie-ep"; - reg = <0xdfc00000 0x0001000>, /* IP registers 1 */ - <0xdfc01000 0x0001000>, /* IP registers 2 */ - <0xd0000000 0x2000000>; /* Configuration space */ - reg-names = "dbi", "dbi2", "addr_space"; - num-ib-windows = <6>; - num-ob-windows = <2>; - num-lanes = <1>; - }; diff --git a/Documentation/devicetree/bindings/pci/faraday,ftpci100.txt b/Documentation/devicetree/bindings/pci/faraday,ftpci100.txt deleted file mode 100644 index 5f8cb4962f8d..000000000000 --- a/Documentation/devicetree/bindings/pci/faraday,ftpci100.txt +++ /dev/null @@ -1,135 +0,0 @@ -Faraday Technology FTPCI100 PCI Host Bridge - -This PCI bridge is found inside that Cortina Systems Gemini SoC platform and -is a generic IP block from Faraday Technology. It exists in two variants: -plain and dual PCI. The plain version embeds a cascading interrupt controller -into the host bridge. The dual version routes the interrupts to the host -chips interrupt controller. - -The host controller appear on the PCI bus with vendor ID 0x159b (Faraday -Technology) and product ID 0x4321. - -Mandatory properties: - -- compatible: ranging from specific to generic, should be one of - "cortina,gemini-pci", "faraday,ftpci100" - "cortina,gemini-pci-dual", "faraday,ftpci100-dual" - "faraday,ftpci100" - "faraday,ftpci100-dual" -- reg: memory base and size for the host bridge -- #address-cells: set to <3> -- #size-cells: set to <2> -- #interrupt-cells: set to <1> -- bus-range: set to <0x00 0xff> -- device_type, set to "pci" -- ranges: see pci.txt -- interrupt-map-mask: see pci.txt -- interrupt-map: see pci.txt -- dma-ranges: three ranges for the inbound memory region. The ranges must - be aligned to a 1MB boundary, and may be 1MB, 2MB, 4MB, 8MB, 16MB, 32MB, 64MB, - 128MB, 256MB, 512MB, 1GB or 2GB in size. The memory should be marked as - pre-fetchable. - -Optional properties: -- clocks: when present, this should contain the peripheral clock (PCLK) and the - PCI clock (PCICLK). If these are not present, they are assumed to be - hard-wired enabled and always on. The PCI clock will be 33 or 66 MHz. -- clock-names: when present, this should contain "PCLK" for the peripheral - clock and "PCICLK" for the PCI-side clock. - -Mandatory subnodes: -- For "faraday,ftpci100" a node representing the interrupt-controller inside the - host bridge is mandatory. It has the following mandatory properties: - - interrupt: see interrupt-controller/interrupts.txt - - interrupt-controller: see interrupt-controller/interrupts.txt - - #address-cells: set to <0> - - #interrupt-cells: set to <1> - -I/O space considerations: - -The plain variant has 128MiB of non-prefetchable memory space, whereas the -"dual" variant has 64MiB. Take this into account when describing the ranges. - -Interrupt map considerations: - -The "dual" variant will get INT A, B, C, D from the system interrupt controller -and should point to respective interrupt in that controller in its -interrupt-map. - -The code which is the only documentation of how the Faraday PCI (the non-dual -variant) interrupts assigns the default interrupt mapping/swizzling has -typically been like this, doing the swizzling on the interrupt controller side -rather than in the interconnect: - -interrupt-map-mask = <0xf800 0 0 7>; -interrupt-map = - <0x4800 0 0 1 &pci_intc 0>, /* Slot 9 */ - <0x4800 0 0 2 &pci_intc 1>, - <0x4800 0 0 3 &pci_intc 2>, - <0x4800 0 0 4 &pci_intc 3>, - <0x5000 0 0 1 &pci_intc 1>, /* Slot 10 */ - <0x5000 0 0 2 &pci_intc 2>, - <0x5000 0 0 3 &pci_intc 3>, - <0x5000 0 0 4 &pci_intc 0>, - <0x5800 0 0 1 &pci_intc 2>, /* Slot 11 */ - <0x5800 0 0 2 &pci_intc 3>, - <0x5800 0 0 3 &pci_intc 0>, - <0x5800 0 0 4 &pci_intc 1>, - <0x6000 0 0 1 &pci_intc 3>, /* Slot 12 */ - <0x6000 0 0 2 &pci_intc 0>, - <0x6000 0 0 3 &pci_intc 1>, - <0x6000 0 0 4 &pci_intc 2>; - -Example: - -pci@50000000 { - compatible = "cortina,gemini-pci", "faraday,ftpci100"; - reg = <0x50000000 0x100>; - interrupts = <8 IRQ_TYPE_LEVEL_HIGH>, /* PCI A */ - <26 IRQ_TYPE_LEVEL_HIGH>, /* PCI B */ - <27 IRQ_TYPE_LEVEL_HIGH>, /* PCI C */ - <28 IRQ_TYPE_LEVEL_HIGH>; /* PCI D */ - #address-cells = <3>; - #size-cells = <2>; - #interrupt-cells = <1>; - - bus-range = <0x00 0xff>; - ranges = /* 1MiB I/O space 0x50000000-0x500fffff */ - <0x01000000 0 0 0x50000000 0 0x00100000>, - /* 128MiB non-prefetchable memory 0x58000000-0x5fffffff */ - <0x02000000 0 0x58000000 0x58000000 0 0x08000000>; - - /* DMA ranges */ - dma-ranges = - /* 128MiB at 0x00000000-0x07ffffff */ - <0x02000000 0 0x00000000 0x00000000 0 0x08000000>, - /* 64MiB at 0x00000000-0x03ffffff */ - <0x02000000 0 0x00000000 0x00000000 0 0x04000000>, - /* 64MiB at 0x00000000-0x03ffffff */ - <0x02000000 0 0x00000000 0x00000000 0 0x04000000>; - - interrupt-map-mask = <0xf800 0 0 7>; - interrupt-map = - <0x4800 0 0 1 &pci_intc 0>, /* Slot 9 */ - <0x4800 0 0 2 &pci_intc 1>, - <0x4800 0 0 3 &pci_intc 2>, - <0x4800 0 0 4 &pci_intc 3>, - <0x5000 0 0 1 &pci_intc 1>, /* Slot 10 */ - <0x5000 0 0 2 &pci_intc 2>, - <0x5000 0 0 3 &pci_intc 3>, - <0x5000 0 0 4 &pci_intc 0>, - <0x5800 0 0 1 &pci_intc 2>, /* Slot 11 */ - <0x5800 0 0 2 &pci_intc 3>, - <0x5800 0 0 3 &pci_intc 0>, - <0x5800 0 0 4 &pci_intc 1>, - <0x6000 0 0 1 &pci_intc 3>, /* Slot 12 */ - <0x6000 0 0 2 &pci_intc 0>, - <0x6000 0 0 3 &pci_intc 0>, - <0x6000 0 0 4 &pci_intc 0>; - pci_intc: interrupt-controller { - interrupt-parent = <&intcon>; - interrupt-controller; - #address-cells = <0>; - #interrupt-cells = <1>; - }; -}; diff --git a/Documentation/devicetree/bindings/pci/faraday,ftpci100.yaml b/Documentation/devicetree/bindings/pci/faraday,ftpci100.yaml new file mode 100644 index 000000000000..92efbf0f1297 --- /dev/null +++ b/Documentation/devicetree/bindings/pci/faraday,ftpci100.yaml @@ -0,0 +1,174 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/pci/faraday,ftpci100.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Faraday Technology FTPCI100 PCI Host Bridge + +maintainers: + - Linus Walleij <linus.walleij@linaro.org> + +description: | + This PCI bridge is found inside that Cortina Systems Gemini SoC platform and + is a generic IP block from Faraday Technology. It exists in two variants: + plain and dual PCI. The plain version embeds a cascading interrupt controller + into the host bridge. The dual version routes the interrupts to the host + chips interrupt controller. + The host controller appear on the PCI bus with vendor ID 0x159b (Faraday + Technology) and product ID 0x4321. + I/O space considerations: + The plain variant has 128MiB of non-prefetchable memory space, whereas the + "dual" variant has 64MiB. Take this into account when describing the ranges. + + Interrupt map considerations: + + The "dual" variant will get INT A, B, C, D from the system interrupt controller + and should point to respective interrupt in that controller in its interrupt-map. + + The code which is the only documentation of how the Faraday PCI (the non-dual + variant) interrupts assigns the default interrupt mapping/swizzling has + typically been like this, doing the swizzling on the interrupt controller side + rather than in the interconnect: + + interrupt-map-mask = <0xf800 0 0 7>; + interrupt-map = + <0x4800 0 0 1 &pci_intc 0>, /* Slot 9 */ + <0x4800 0 0 2 &pci_intc 1>, + <0x4800 0 0 3 &pci_intc 2>, + <0x4800 0 0 4 &pci_intc 3>, + <0x5000 0 0 1 &pci_intc 1>, /* Slot 10 */ + <0x5000 0 0 2 &pci_intc 2>, + <0x5000 0 0 3 &pci_intc 3>, + <0x5000 0 0 4 &pci_intc 0>, + <0x5800 0 0 1 &pci_intc 2>, /* Slot 11 */ + <0x5800 0 0 2 &pci_intc 3>, + <0x5800 0 0 3 &pci_intc 0>, + <0x5800 0 0 4 &pci_intc 1>, + <0x6000 0 0 1 &pci_intc 3>, /* Slot 12 */ + <0x6000 0 0 2 &pci_intc 0>, + <0x6000 0 0 3 &pci_intc 1>, + <0x6000 0 0 4 &pci_intc 2>; + +allOf: + - $ref: /schemas/pci/pci-bus.yaml# + +properties: + compatible: + oneOf: + - items: + - const: cortina,gemini-pci + - const: faraday,ftpci100 + - items: + - const: cortina,gemini-pci-dual + - const: faraday,ftpci100-dual + - const: faraday,ftpci100 + - const: faraday,ftpci100-dual + + reg: + maxItems: 1 + + "#address-cells": + const: 3 + + "#interrupt-cells": + const: 1 + + ranges: + minItems: 2 + + dma-ranges: + minItems: 3 + description: | + three ranges for the inbound memory region. The ranges must + be aligned to a 1MB boundary, and may be 1MB, 2MB, 4MB, 8MB, 16MB, 32MB, 64MB, + 128MB, 256MB, 512MB, 1GB or 2GB in size. The memory should be marked as + pre-fetchable. + + clocks: + items: + - description: peripheral clock (PCLK) + - description: PCI clock (PCICLK). + description: | + If these are not present, they are assumed to be + hard-wired enabled and always on. The PCI clock will be 33 or 66 MHz. + + clock-names: + items: + - const: PCLK + - const: PCICLK + + interrupt-controller: + type: object + +required: + - reg + - compatible + - "#interrupt-cells" + - interrupt-map-mask + - interrupt-map + - dma-ranges + +if: + properties: + compatible: + contains: + const: faraday,ftpci100 +then: + required: + - interrupt-controller + +unevaluatedProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/irq.h> + pci@50000000 { + compatible = "cortina,gemini-pci", "faraday,ftpci100"; + reg = <0x50000000 0x100>; + device_type = "pci"; + #address-cells = <3>; + #size-cells = <2>; + #interrupt-cells = <1>; + + bus-range = <0x00 0xff>; + ranges = /* 1MiB I/O space 0x50000000-0x500fffff */ + <0x01000000 0 0 0x50000000 0 0x00100000>, + /* 128MiB non-prefetchable memory 0x58000000-0x5fffffff */ + <0x02000000 0 0x58000000 0x58000000 0 0x08000000>; + + /* DMA ranges */ + dma-ranges = + /* 128MiB at 0x00000000-0x07ffffff */ + <0x02000000 0 0x00000000 0x00000000 0 0x08000000>, + /* 64MiB at 0x00000000-0x03ffffff */ + <0x02000000 0 0x00000000 0x00000000 0 0x04000000>, + /* 64MiB at 0x00000000-0x03ffffff */ + <0x02000000 0 0x00000000 0x00000000 0 0x04000000>; + + interrupt-map-mask = <0xf800 0 0 7>; + interrupt-map = + <0x4800 0 0 1 &pci_intc 0>, /* Slot 9 */ + <0x4800 0 0 2 &pci_intc 1>, + <0x4800 0 0 3 &pci_intc 2>, + <0x4800 0 0 4 &pci_intc 3>, + <0x5000 0 0 1 &pci_intc 1>, /* Slot 10 */ + <0x5000 0 0 2 &pci_intc 2>, + <0x5000 0 0 3 &pci_intc 3>, + <0x5000 0 0 4 &pci_intc 0>, + <0x5800 0 0 1 &pci_intc 2>, /* Slot 11 */ + <0x5800 0 0 2 &pci_intc 3>, + <0x5800 0 0 3 &pci_intc 0>, + <0x5800 0 0 4 &pci_intc 1>, + <0x6000 0 0 1 &pci_intc 3>, /* Slot 12 */ + <0x6000 0 0 2 &pci_intc 0>, + <0x6000 0 0 3 &pci_intc 0>, + <0x6000 0 0 4 &pci_intc 0>; + pci_intc: interrupt-controller { + interrupt-parent = <&intcon>; + interrupt-controller; + interrupts = <8 IRQ_TYPE_LEVEL_HIGH>; + #address-cells = <0>; + #interrupt-cells = <1>; + }; + }; diff --git a/Documentation/devicetree/bindings/pci/fsl,imx6q-pcie.txt b/Documentation/devicetree/bindings/pci/fsl,imx6q-pcie.txt deleted file mode 100644 index d8971ab99274..000000000000 --- a/Documentation/devicetree/bindings/pci/fsl,imx6q-pcie.txt +++ /dev/null @@ -1,100 +0,0 @@ -* Freescale i.MX6 PCIe interface - -This PCIe host controller is based on the Synopsys DesignWare PCIe IP -and thus inherits all the common properties defined in designware-pcie.txt. - -Required properties: -- compatible: - - "fsl,imx6q-pcie" - - "fsl,imx6sx-pcie", - - "fsl,imx6qp-pcie" - - "fsl,imx7d-pcie" - - "fsl,imx8mq-pcie" -- reg: base address and length of the PCIe controller -- interrupts: A list of interrupt outputs of the controller. Must contain an - entry for each entry in the interrupt-names property. -- interrupt-names: Must include the following entries: - - "msi": The interrupt that is asserted when an MSI is received -- clock-names: Must include the following additional entries: - - "pcie_phy" - -Optional properties: -- fsl,tx-deemph-gen1: Gen1 De-emphasis value. Default: 0 -- fsl,tx-deemph-gen2-3p5db: Gen2 (3.5db) De-emphasis value. Default: 0 -- fsl,tx-deemph-gen2-6db: Gen2 (6db) De-emphasis value. Default: 20 -- fsl,tx-swing-full: Gen2 TX SWING FULL value. Default: 127 -- fsl,tx-swing-low: TX launch amplitude swing_low value. Default: 127 -- fsl,max-link-speed: Specify PCI gen for link capability. Must be '2' for - gen2, otherwise will default to gen1. Note that the IMX6 LVDS clock outputs - do not meet gen2 jitter requirements and thus for gen2 capability a gen2 - compliant clock generator should be used and configured. -- reset-gpio: Should specify the GPIO for controlling the PCI bus device reset - signal. It's not polarity aware and defaults to active-low reset sequence - (L=reset state, H=operation state). -- reset-gpio-active-high: If present then the reset sequence using the GPIO - specified in the "reset-gpio" property is reversed (H=reset state, - L=operation state). -- vpcie-supply: Should specify the regulator in charge of PCIe port power. - The regulator will be enabled when initializing the PCIe host and - disabled either as part of the init process or when shutting down the - host. -- vph-supply: Should specify the regulator in charge of VPH one of the three - PCIe PHY powers. This regulator can be supplied by both 1.8v and 3.3v voltage - supplies. - -Additional required properties for imx6sx-pcie: -- clock names: Must include the following additional entries: - - "pcie_inbound_axi" -- power-domains: Must be set to phandles pointing to the DISPLAY and - PCIE_PHY power domains -- power-domain-names: Must be "pcie", "pcie_phy" - -Additional required properties for imx7d-pcie and imx8mq-pcie: -- power-domains: Must be set to a phandle pointing to PCIE_PHY power domain -- resets: Must contain phandles to PCIe-related reset lines exposed by SRC - IP block -- reset-names: Must contain the following entries: - - "pciephy" - - "apps" - - "turnoff" -- fsl,imx7d-pcie-phy: A phandle to an fsl,imx7d-pcie-phy node. - -Additional required properties for imx8mq-pcie: -- clock-names: Must include the following additional entries: - - "pcie_aux" - -Example: - - pcie@01000000 { - compatible = "fsl,imx6q-pcie", "snps,dw-pcie"; - reg = <0x01ffc000 0x04000>, - <0x01f00000 0x80000>; - reg-names = "dbi", "config"; - #address-cells = <3>; - #size-cells = <2>; - device_type = "pci"; - ranges = <0x00000800 0 0x01f00000 0x01f00000 0 0x00080000 - 0x81000000 0 0 0x01f80000 0 0x00010000 - 0x82000000 0 0x01000000 0x01000000 0 0x00f00000>; - num-lanes = <1>; - interrupts = <GIC_SPI 120 IRQ_TYPE_LEVEL_HIGH>; - interrupt-names = "msi"; - #interrupt-cells = <1>; - interrupt-map-mask = <0 0 0 0x7>; - interrupt-map = <0 0 0 1 &intc GIC_SPI 123 IRQ_TYPE_LEVEL_HIGH>, - <0 0 0 2 &intc GIC_SPI 122 IRQ_TYPE_LEVEL_HIGH>, - <0 0 0 3 &intc GIC_SPI 121 IRQ_TYPE_LEVEL_HIGH>, - <0 0 0 4 &intc GIC_SPI 120 IRQ_TYPE_LEVEL_HIGH>; - clocks = <&clks 144>, <&clks 206>, <&clks 189>; - clock-names = "pcie", "pcie_bus", "pcie_phy"; - }; - -* Freescale i.MX7d PCIe PHY - -This is the PHY associated with the IMX7d PCIe controller. It's used by the -PCI-e controller via the fsl,imx7d-pcie-phy phandle. - -Required properties: -- compatible: - - "fsl,imx7d-pcie-phy" -- reg: base address and length of the PCIe PHY controller diff --git a/Documentation/devicetree/bindings/pci/fsl,imx6q-pcie.yaml b/Documentation/devicetree/bindings/pci/fsl,imx6q-pcie.yaml new file mode 100644 index 000000000000..2911e565b260 --- /dev/null +++ b/Documentation/devicetree/bindings/pci/fsl,imx6q-pcie.yaml @@ -0,0 +1,202 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/pci/fsl,imx6q-pcie.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Freescale i.MX6 PCIe host controller + +maintainers: + - Lucas Stach <l.stach@pengutronix.de> + - Richard Zhu <hongxing.zhu@nxp.com> + +description: |+ + This PCIe host controller is based on the Synopsys DesignWare PCIe IP + and thus inherits all the common properties defined in snps,dw-pcie.yaml. + +allOf: + - $ref: /schemas/pci/snps,dw-pcie.yaml# + +properties: + compatible: + enum: + - fsl,imx6q-pcie + - fsl,imx6sx-pcie + - fsl,imx6qp-pcie + - fsl,imx7d-pcie + - fsl,imx8mq-pcie + + reg: + items: + - description: Data Bus Interface (DBI) registers. + - description: PCIe configuration space region. + + reg-names: + items: + - const: dbi + - const: config + + interrupts: + items: + - description: builtin MSI controller. + + interrupt-names: + minItems: 1 + items: + - const: msi + + clocks: + minItems: 3 + items: + - description: PCIe bridge clock. + - description: PCIe bus clock. + - description: PCIe PHY clock. + - description: Additional required clock entry for imx6sx-pcie, + imx8mq-pcie. + + clock-names: + minItems: 3 + items: + - const: pcie + - const: pcie_bus + - const: pcie_phy + - const: pcie_inbound_axi for imx6sx-pcie, pcie_aux for imx8mq-pcie + + num-lanes: + const: 1 + + fsl,imx7d-pcie-phy: + $ref: /schemas/types.yaml#/definitions/phandle + description: A phandle to an fsl,imx7d-pcie-phy node. Additional + required properties for imx7d-pcie and imx8mq-pcie. + + power-domains: + items: + - description: The phandle pointing to the DISPLAY domain for + imx6sx-pcie, to PCIE_PHY power domain for imx7d-pcie and + imx8mq-pcie. + - description: The phandle pointing to the PCIE_PHY power domains + for imx6sx-pcie. + + power-domain-names: + items: + - const: pcie + - const: pcie_phy + + resets: + maxItems: 3 + description: Phandles to PCIe-related reset lines exposed by SRC + IP block. Additional required by imx7d-pcie and imx8mq-pcie. + + reset-names: + items: + - const: pciephy + - const: apps + - const: turnoff + + fsl,tx-deemph-gen1: + description: Gen1 De-emphasis value (optional required). + $ref: /schemas/types.yaml#/definitions/uint32 + default: 0 + + fsl,tx-deemph-gen2-3p5db: + description: Gen2 (3.5db) De-emphasis value (optional required). + $ref: /schemas/types.yaml#/definitions/uint32 + default: 0 + + fsl,tx-deemph-gen2-6db: + description: Gen2 (6db) De-emphasis value (optional required). + $ref: /schemas/types.yaml#/definitions/uint32 + default: 20 + + fsl,tx-swing-full: + description: Gen2 TX SWING FULL value (optional required). + $ref: /schemas/types.yaml#/definitions/uint32 + default: 127 + + fsl,tx-swing-low: + description: TX launch amplitude swing_low value (optional required). + $ref: /schemas/types.yaml#/definitions/uint32 + default: 127 + + fsl,max-link-speed: + description: Specify PCI Gen for link capability (optional required). + Note that the IMX6 LVDS clock outputs do not meet gen2 jitter + requirements and thus for gen2 capability a gen2 compliant clock + generator should be used and configured. + $ref: /schemas/types.yaml#/definitions/uint32 + enum: [1, 2, 3, 4] + default: 1 + + reset-gpio: + description: Should specify the GPIO for controlling the PCI bus device + reset signal. It's not polarity aware and defaults to active-low reset + sequence (L=reset state, H=operation state) (optional required). + + reset-gpio-active-high: + description: If present then the reset sequence using the GPIO + specified in the "reset-gpio" property is reversed (H=reset state, + L=operation state) (optional required). + + vpcie-supply: + description: Should specify the regulator in charge of PCIe port power. + The regulator will be enabled when initializing the PCIe host and + disabled either as part of the init process or when shutting down + the host (optional required). + + vph-supply: + description: Should specify the regulator in charge of VPH one of + the three PCIe PHY powers. This regulator can be supplied by both + 1.8v and 3.3v voltage supplies (optional required). + +required: + - compatible + - reg + - reg-names + - "#address-cells" + - "#size-cells" + - device_type + - bus-range + - ranges + - num-lanes + - interrupts + - interrupt-names + - "#interrupt-cells" + - interrupt-map-mask + - interrupt-map + - clocks + - clock-names + +unevaluatedProperties: false + +examples: + - | + #include <dt-bindings/clock/imx6qdl-clock.h> + #include <dt-bindings/interrupt-controller/arm-gic.h> + + pcie: pcie@1ffc000 { + compatible = "fsl,imx6q-pcie"; + reg = <0x01ffc000 0x04000>, + <0x01f00000 0x80000>; + reg-names = "dbi", "config"; + #address-cells = <3>; + #size-cells = <2>; + device_type = "pci"; + bus-range = <0x00 0xff>; + ranges = <0x81000000 0 0 0x01f80000 0 0x00010000>, + <0x82000000 0 0x01000000 0x01000000 0 0x00f00000>; + num-lanes = <1>; + interrupts = <GIC_SPI 120 IRQ_TYPE_LEVEL_HIGH>; + interrupt-names = "msi"; + #interrupt-cells = <1>; + interrupt-map-mask = <0 0 0 0x7>; + interrupt-map = <0 0 0 1 &gpc GIC_SPI 123 IRQ_TYPE_LEVEL_HIGH>, + <0 0 0 2 &gpc GIC_SPI 122 IRQ_TYPE_LEVEL_HIGH>, + <0 0 0 3 &gpc GIC_SPI 121 IRQ_TYPE_LEVEL_HIGH>, + <0 0 0 4 &gpc GIC_SPI 120 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&clks IMX6QDL_CLK_PCIE_AXI>, + <&clks IMX6QDL_CLK_LVDS1_GATE>, + <&clks IMX6QDL_CLK_PCIE_REF_125M>; + clock-names = "pcie", "pcie_bus", "pcie_phy"; + }; +... diff --git a/Documentation/devicetree/bindings/pci/hisilicon,kirin-pcie.yaml b/Documentation/devicetree/bindings/pci/hisilicon,kirin-pcie.yaml new file mode 100644 index 000000000000..cbee87802559 --- /dev/null +++ b/Documentation/devicetree/bindings/pci/hisilicon,kirin-pcie.yaml @@ -0,0 +1,167 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/pci/hisilicon,kirin-pcie.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: HiSilicon Kirin SoCs PCIe host DT description + +maintainers: + - Xiaowei Song <songxiaowei@hisilicon.com> + - Binghui Wang <wangbinghui@hisilicon.com> + +description: | + Kirin PCIe host controller is based on the Synopsys DesignWare PCI core. + It shares common functions with the PCIe DesignWare core driver and + inherits common properties defined in + Documentation/devicetree/bindings/pci/snps,dw-pcie.yaml. + +allOf: + - $ref: /schemas/pci/snps,dw-pcie.yaml# + +properties: + compatible: + contains: + enum: + - hisilicon,kirin960-pcie + - hisilicon,kirin970-pcie + + reg: + description: | + Should contain dbi, apb, config registers location and length. + For hisilicon,kirin960-pcie, it should also contain phy. + minItems: 3 + maxItems: 4 + + reg-names: + minItems: 3 + maxItems: 4 + + hisilicon,clken-gpios: + description: | + Clock input enablement GPIOs from PCI devices like Ethernet, M.2 and + mini-PCIe slots. + +required: + - compatible + - reg + - reg-names + +unevaluatedProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/arm-gic.h> + #include <dt-bindings/clock/hi3660-clock.h> + #include <dt-bindings/clock/hi3670-clock.h> + + soc { + #address-cells = <2>; + #size-cells = <2>; + + pcie@f4000000 { + compatible = "hisilicon,kirin960-pcie"; + reg = <0x0 0xf4000000 0x0 0x1000>, + <0x0 0xff3fe000 0x0 0x1000>, + <0x0 0xf3f20000 0x0 0x40000>, + <0x0 0xf5000000 0x0 0x2000>; + reg-names = "dbi", "apb", "phy", "config"; + bus-range = <0x0 0xff>; + #address-cells = <3>; + #size-cells = <2>; + device_type = "pci"; + ranges = <0x02000000 0x0 0x00000000 + 0x0 0xf6000000 + 0x0 0x02000000>; + num-lanes = <1>; + #interrupt-cells = <1>; + interrupts = <0 283 4>; + interrupt-names = "msi"; + interrupt-map-mask = <0xf800 0 0 7>; + interrupt-map = <0x0 0 0 1 &gic GIC_SPI 282 IRQ_TYPE_LEVEL_HIGH>, + <0x0 0 0 2 &gic GIC_SPI 283 IRQ_TYPE_LEVEL_HIGH>, + <0x0 0 0 3 &gic GIC_SPI 284 IRQ_TYPE_LEVEL_HIGH>, + <0x0 0 0 4 &gic GIC_SPI 285 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&crg_ctrl HI3660_PCIEPHY_REF>, + <&crg_ctrl HI3660_CLK_GATE_PCIEAUX>, + <&crg_ctrl HI3660_PCLK_GATE_PCIE_PHY>, + <&crg_ctrl HI3660_PCLK_GATE_PCIE_SYS>, + <&crg_ctrl HI3660_ACLK_GATE_PCIE>; + clock-names = "pcie_phy_ref", "pcie_aux", "pcie_apb_phy", + "pcie_apb_sys", "pcie_aclk"; + }; + + pcie@f5000000 { + compatible = "hisilicon,kirin970-pcie"; + reg = <0x0 0xf4000000 0x0 0x1000000>, + <0x0 0xfc180000 0x0 0x1000>, + <0x0 0xf5000000 0x0 0x2000>; + reg-names = "dbi", "apb", "config"; + bus-range = <0x0 0xff>; + #address-cells = <3>; + #size-cells = <2>; + device_type = "pci"; + phys = <&pcie_phy>; + ranges = <0x02000000 0x0 0x00000000 + 0x0 0xf6000000 + 0x0 0x02000000>; + num-lanes = <1>; + #interrupt-cells = <1>; + interrupts = <GIC_SPI 283 IRQ_TYPE_LEVEL_HIGH>; + interrupt-names = "msi"; + interrupt-map-mask = <0 0 0 7>; + interrupt-map = <0x0 0 0 1 &gic GIC_SPI 282 IRQ_TYPE_LEVEL_HIGH>, + <0x0 0 0 2 &gic GIC_SPI 283 IRQ_TYPE_LEVEL_HIGH>, + <0x0 0 0 3 &gic GIC_SPI 284 IRQ_TYPE_LEVEL_HIGH>, + <0x0 0 0 4 &gic GIC_SPI 285 IRQ_TYPE_LEVEL_HIGH>; + reset-gpios = <&gpio7 0 0>; + hisilicon,clken-gpios = <&gpio27 3 0>, <&gpio17 0 0>, <&gpio20 6 0>; + pcie@0,0 { // Lane 0: PCIe switch: Bus 1, Device 0 + reg = <0 0 0 0 0>; + compatible = "pciclass,0604"; + device_type = "pci"; + #address-cells = <3>; + #size-cells = <2>; + ranges; + + pcie@0,0 { // Lane 0: upstream + reg = <0 0 0 0 0>; + compatible = "pciclass,0604"; + device_type = "pci"; + #address-cells = <3>; + #size-cells = <2>; + ranges; + + pcie@1,0 { // Lane 4: M.2 + reg = <0x0800 0 0 0 0>; + compatible = "pciclass,0604"; + device_type = "pci"; + reset-gpios = <&gpio3 1 0>; + #address-cells = <3>; + #size-cells = <2>; + ranges; + }; + + pcie@5,0 { // Lane 5: Mini PCIe + reg = <0x2800 0 0 0 0>; + compatible = "pciclass,0604"; + device_type = "pci"; + reset-gpios = <&gpio27 4 0 >; + #address-cells = <3>; + #size-cells = <2>; + ranges; + }; + + pcie@7,0 { // Lane 6: Ethernet + reg = <0x03800 0 0 0 0>; + compatible = "pciclass,0604"; + device_type = "pci"; + reset-gpios = <&gpio25 2 0 >; + #address-cells = <3>; + #size-cells = <2>; + ranges; + }; + }; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/pci/hisilicon-histb-pcie.txt b/Documentation/devicetree/bindings/pci/hisilicon-histb-pcie.txt index 760b4d740616..5f0cf6c2fef3 100644 --- a/Documentation/devicetree/bindings/pci/hisilicon-histb-pcie.txt +++ b/Documentation/devicetree/bindings/pci/hisilicon-histb-pcie.txt @@ -3,7 +3,7 @@ HiSilicon STB PCIe host bridge DT description The HiSilicon STB PCIe host controller is based on the DesignWare PCIe core. It shares common functions with the DesignWare PCIe core driver and inherits common properties defined in -Documentation/devicetree/bindings/pci/designware-pcie.txt. +Documentation/devicetree/bindings/pci/snps,dw-pcie.yaml. Additional properties are described here: diff --git a/Documentation/devicetree/bindings/pci/intel-gw-pcie.yaml b/Documentation/devicetree/bindings/pci/intel-gw-pcie.yaml index a1e2be737eec..54e2890ae631 100644 --- a/Documentation/devicetree/bindings/pci/intel-gw-pcie.yaml +++ b/Documentation/devicetree/bindings/pci/intel-gw-pcie.yaml @@ -7,7 +7,7 @@ $schema: http://devicetree.org/meta-schemas/core.yaml# title: PCIe RC controller on Intel Gateway SoCs maintainers: - - Dilip Kota <eswara.kota@linux.intel.com> + - Rahul Tanwar <rtanwar@maxlinear.com> select: properties: @@ -17,21 +17,15 @@ select: required: - compatible +allOf: + - $ref: /schemas/pci/snps,dw-pcie.yaml# + 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. @@ -62,30 +56,13 @@ properties: 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. - $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. @@ -94,9 +71,6 @@ properties: required: - compatible - - device_type - - "#address-cells" - - "#size-cells" - reg - reg-names - ranges @@ -109,7 +83,7 @@ required: - interrupt-map - interrupt-map-mask -additionalProperties: false +unevaluatedProperties: false examples: - | diff --git a/Documentation/devicetree/bindings/pci/kirin-pcie.txt b/Documentation/devicetree/bindings/pci/kirin-pcie.txt deleted file mode 100644 index 6bbe43818ad5..000000000000 --- a/Documentation/devicetree/bindings/pci/kirin-pcie.txt +++ /dev/null @@ -1,50 +0,0 @@ -HiSilicon Kirin SoCs PCIe host DT description - -Kirin PCIe host controller is based on the Synopsys DesignWare PCI core. -It shares common functions with the PCIe DesignWare core driver and -inherits common properties defined in -Documentation/devicetree/bindings/pci/designware-pcie.txt. - -Additional properties are described here: - -Required properties -- compatible: - "hisilicon,kirin960-pcie" for PCIe of Kirin960 SoC -- reg: Should contain rc_dbi, apb, phy, config registers location and length. -- reg-names: Must include the following entries: - "dbi": controller configuration registers; - "apb": apb Ctrl register defined by Kirin; - "phy": apb PHY register defined by Kirin; - "config": PCIe configuration space registers. -- reset-gpios: The GPIO to generate PCIe PERST# assert and deassert signal. - -Optional properties: - -Example based on kirin960: - - pcie@f4000000 { - compatible = "hisilicon,kirin-pcie"; - reg = <0x0 0xf4000000 0x0 0x1000>, <0x0 0xff3fe000 0x0 0x1000>, - <0x0 0xf3f20000 0x0 0x40000>, <0x0 0xF4000000 0 0x2000>; - reg-names = "dbi","apb","phy", "config"; - bus-range = <0x0 0x1>; - #address-cells = <3>; - #size-cells = <2>; - device_type = "pci"; - ranges = <0x02000000 0x0 0x00000000 0x0 0xf5000000 0x0 0x2000000>; - num-lanes = <1>; - #interrupt-cells = <1>; - interrupt-map-mask = <0xf800 0 0 7>; - interrupt-map = <0x0 0 0 1 &gic 0 0 0 282 4>, - <0x0 0 0 2 &gic 0 0 0 283 4>, - <0x0 0 0 3 &gic 0 0 0 284 4>, - <0x0 0 0 4 &gic 0 0 0 285 4>; - clocks = <&crg_ctrl HI3660_PCIEPHY_REF>, - <&crg_ctrl HI3660_CLK_GATE_PCIEAUX>, - <&crg_ctrl HI3660_PCLK_GATE_PCIE_PHY>, - <&crg_ctrl HI3660_PCLK_GATE_PCIE_SYS>, - <&crg_ctrl HI3660_ACLK_GATE_PCIE>; - clock-names = "pcie_phy_ref", "pcie_aux", - "pcie_apb_phy", "pcie_apb_sys", "pcie_aclk"; - reset-gpios = <&gpio11 1 0 >; - }; diff --git a/Documentation/devicetree/bindings/pci/layerscape-pci.txt b/Documentation/devicetree/bindings/pci/layerscape-pci.txt index 6d898dd4a8e2..f36efa73a470 100644 --- a/Documentation/devicetree/bindings/pci/layerscape-pci.txt +++ b/Documentation/devicetree/bindings/pci/layerscape-pci.txt @@ -1,7 +1,7 @@ Freescale Layerscape PCIe controller This PCIe host controller is based on the Synopsys DesignWare PCIe IP -and thus inherits all the common properties defined in designware-pcie.txt. +and thus inherits all the common properties defined in snps,dw-pcie.yaml. This controller derives its clocks from the Reset Configuration Word (RCW) which is used to describe the PLL settings at the time of chip-reset. diff --git a/Documentation/devicetree/bindings/pci/loongson.yaml b/Documentation/devicetree/bindings/pci/loongson.yaml index 82bc6c486ca3..a8324a9bd002 100644 --- a/Documentation/devicetree/bindings/pci/loongson.yaml +++ b/Documentation/devicetree/bindings/pci/loongson.yaml @@ -17,10 +17,10 @@ allOf: properties: compatible: - oneOf: - - const: loongson,ls2k-pci - - const: loongson,ls7a-pci - - const: loongson,rs780e-pci + enum: + - loongson,ls2k-pci + - loongson,ls7a-pci + - loongson,rs780e-pci reg: minItems: 1 diff --git a/Documentation/devicetree/bindings/pci/nvidia,tegra194-pcie.txt b/Documentation/devicetree/bindings/pci/nvidia,tegra194-pcie.txt index bd43f3c3ece4..6a99d2aa8075 100644 --- a/Documentation/devicetree/bindings/pci/nvidia,tegra194-pcie.txt +++ b/Documentation/devicetree/bindings/pci/nvidia,tegra194-pcie.txt @@ -1,7 +1,8 @@ NVIDIA Tegra PCIe controller (Synopsys DesignWare Core based) This PCIe controller is based on the Synopsis Designware PCIe IP -and thus inherits all the common properties defined in designware-pcie.txt. +and thus inherits all the common properties defined in snps,dw-pcie.yaml and +snps,dw-pcie-ep.yaml. Some of the controller instances are dual mode where in they can work either in root port mode or endpoint mode but one at a time. @@ -22,7 +23,7 @@ Required properties: property. - reg-names: Must include the following entries: "appl": Controller's application logic registers - "config": As per the definition in designware-pcie.txt + "config": As per the definition in snps,dw-pcie.yaml "atu_dma": iATU and DMA registers. This is where the iATU (internal Address Translation Unit) registers of the PCIe core are made available for SW access. diff --git a/Documentation/devicetree/bindings/pci/pci-armada8k.txt b/Documentation/devicetree/bindings/pci/pci-armada8k.txt index 7a813d0e6d63..ff25a134befa 100644 --- a/Documentation/devicetree/bindings/pci/pci-armada8k.txt +++ b/Documentation/devicetree/bindings/pci/pci-armada8k.txt @@ -1,7 +1,7 @@ * Marvell Armada 7K/8K PCIe interface This PCIe host controller is based on the Synopsys DesignWare PCIe IP -and thus inherits all the common properties defined in designware-pcie.txt. +and thus inherits all the common properties defined in snps,dw-pcie.yaml. Required properties: - compatible: "marvell,armada8k-pcie" diff --git a/Documentation/devicetree/bindings/pci/pcie-al.txt b/Documentation/devicetree/bindings/pci/pcie-al.txt index 557a5089229d..2ad1fe466eab 100644 --- a/Documentation/devicetree/bindings/pci/pcie-al.txt +++ b/Documentation/devicetree/bindings/pci/pcie-al.txt @@ -2,7 +2,7 @@ Amazon's Annapurna Labs PCIe Host Controller is based on the Synopsys DesignWare PCI core. It inherits common properties defined in -Documentation/devicetree/bindings/pci/designware-pcie.txt. +Documentation/devicetree/bindings/pci/snps,dw-pcie.yaml. Properties of the host controller node that differ from it are: diff --git a/Documentation/devicetree/bindings/pci/qcom,pcie.txt b/Documentation/devicetree/bindings/pci/qcom,pcie.txt index 25f4def468bf..3f646875f8c2 100644 --- a/Documentation/devicetree/bindings/pci/qcom,pcie.txt +++ b/Documentation/devicetree/bindings/pci/qcom,pcie.txt @@ -34,22 +34,22 @@ - device_type: Usage: required Value type: <string> - Definition: Should be "pci". As specified in designware-pcie.txt + Definition: Should be "pci". As specified in snps,dw-pcie.yaml - #address-cells: Usage: required Value type: <u32> - Definition: Should be 3. As specified in designware-pcie.txt + Definition: Should be 3. As specified in snps,dw-pcie.yaml - #size-cells: Usage: required Value type: <u32> - Definition: Should be 2. As specified in designware-pcie.txt + Definition: Should be 2. As specified in snps,dw-pcie.yaml - ranges: Usage: required Value type: <prop-encoded-array> - Definition: As specified in designware-pcie.txt + Definition: As specified in snps,dw-pcie.yaml - interrupts: Usage: required @@ -64,17 +64,17 @@ - #interrupt-cells: Usage: required Value type: <u32> - Definition: Should be 1. As specified in designware-pcie.txt + Definition: Should be 1. As specified in snps,dw-pcie.yaml - interrupt-map-mask: Usage: required Value type: <prop-encoded-array> - Definition: As specified in designware-pcie.txt + Definition: As specified in snps,dw-pcie.yaml - interrupt-map: Usage: required Value type: <prop-encoded-array> - Definition: As specified in designware-pcie.txt + Definition: As specified in snps,dw-pcie.yaml - clocks: Usage: required diff --git a/Documentation/devicetree/bindings/pci/samsung,exynos-pcie.yaml b/Documentation/devicetree/bindings/pci/samsung,exynos-pcie.yaml index 1810bf722350..445eed94b53f 100644 --- a/Documentation/devicetree/bindings/pci/samsung,exynos-pcie.yaml +++ b/Documentation/devicetree/bindings/pci/samsung,exynos-pcie.yaml @@ -13,10 +13,10 @@ maintainers: description: |+ Exynos5433 SoC PCIe host controller is based on the Synopsys DesignWare PCIe IP and thus inherits all the common properties defined in - designware-pcie.txt. + snps,dw-pcie.yaml. allOf: - - $ref: /schemas/pci/pci-bus.yaml# + - $ref: /schemas/pci/snps,dw-pcie.yaml# properties: compatible: diff --git a/Documentation/devicetree/bindings/pci/sifive,fu740-pcie.yaml b/Documentation/devicetree/bindings/pci/sifive,fu740-pcie.yaml index b03cbb9b6602..2b9d1d6fc661 100644 --- a/Documentation/devicetree/bindings/pci/sifive,fu740-pcie.yaml +++ b/Documentation/devicetree/bindings/pci/sifive,fu740-pcie.yaml @@ -10,14 +10,14 @@ description: |+ SiFive FU740 PCIe host controller is based on the Synopsys DesignWare PCI core. It shares common features with the PCIe DesignWare core and inherits common properties defined in - Documentation/devicetree/bindings/pci/designware-pcie.txt. + Documentation/devicetree/bindings/pci/snps,dw-pcie.yaml. maintainers: - Paul Walmsley <paul.walmsley@sifive.com> - Greentime Hu <greentime.hu@sifive.com> allOf: - - $ref: /schemas/pci/pci-bus.yaml# + - $ref: /schemas/pci/snps,dw-pcie.yaml# properties: compatible: diff --git a/Documentation/devicetree/bindings/pci/snps,dw-pcie-ep.yaml b/Documentation/devicetree/bindings/pci/snps,dw-pcie-ep.yaml new file mode 100644 index 000000000000..b5935b1b153f --- /dev/null +++ b/Documentation/devicetree/bindings/pci/snps,dw-pcie-ep.yaml @@ -0,0 +1,90 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/pci/snps,dw-pcie-ep.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Synopsys DesignWare PCIe endpoint interface + +maintainers: + - Jingoo Han <jingoohan1@gmail.com> + - Gustavo Pimentel <gustavo.pimentel@synopsys.com> + +description: | + Synopsys DesignWare PCIe host controller endpoint + +allOf: + - $ref: /schemas/pci/pci-ep.yaml# + +properties: + compatible: + anyOf: + - {} + - const: snps,dw-pcie-ep + + reg: + description: | + It should contain Data Bus Interface (dbi) and config registers for all + versions. + For designware core version >= 4.80, it may contain ATU address space. + minItems: 2 + maxItems: 4 + + reg-names: + minItems: 2 + maxItems: 4 + items: + enum: [dbi, dbi2, config, atu, addr_space, link, atu_dma, appl] + + reset-gpio: + description: GPIO pin number of PERST# signal + maxItems: 1 + deprecated: true + + reset-gpios: + description: GPIO controlled connection to PERST# signal + maxItems: 1 + + snps,enable-cdm-check: + type: boolean + description: | + This is a boolean property and if present enables + automatic checking of CDM (Configuration Dependent Module) registers + for data corruption. CDM registers include standard PCIe configuration + space registers, Port Logic registers, DMA and iATU (internal Address + Translation Unit) registers. + + num-ib-windows: + description: number of inbound address translation windows + maxItems: 1 + deprecated: true + + num-ob-windows: + description: number of outbound address translation windows + maxItems: 1 + deprecated: true + + max-functions: + $ref: /schemas/types.yaml#/definitions/uint32 + description: maximum number of functions that can be configured + +required: + - reg + - reg-names + - compatible + +unevaluatedProperties: false + +examples: + - | + bus { + #address-cells = <1>; + #size-cells = <1>; + pcie-ep@dfd00000 { + compatible = "snps,dw-pcie-ep"; + reg = <0xdfc00000 0x0001000>, /* IP registers 1 */ + <0xdfc01000 0x0001000>, /* IP registers 2 */ + <0xd0000000 0x2000000>; /* Configuration space */ + reg-names = "dbi", "dbi2", "addr_space"; + }; + }; diff --git a/Documentation/devicetree/bindings/pci/snps,dw-pcie.yaml b/Documentation/devicetree/bindings/pci/snps,dw-pcie.yaml new file mode 100644 index 000000000000..9ed0dfba7f89 --- /dev/null +++ b/Documentation/devicetree/bindings/pci/snps,dw-pcie.yaml @@ -0,0 +1,102 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/pci/snps,dw-pcie.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Synopsys DesignWare PCIe interface + +maintainers: + - Jingoo Han <jingoohan1@gmail.com> + - Gustavo Pimentel <gustavo.pimentel@synopsys.com> + +description: | + Synopsys DesignWare PCIe host controller + +allOf: + - $ref: /schemas/pci/pci-bus.yaml# + +properties: + compatible: + anyOf: + - {} + - const: snps,dw-pcie + + reg: + description: | + It should contain Data Bus Interface (dbi) and config registers for all + versions. + For designware core version >= 4.80, it may contain ATU address space. + minItems: 2 + maxItems: 5 + + reg-names: + minItems: 2 + maxItems: 5 + items: + enum: [ dbi, dbi2, config, atu, app, elbi, mgmt, ctrl, parf, cfg, link, + ulreg, smu, mpu, apb, phy ] + + num-lanes: + description: | + number of lanes to use (this property should be specified unless + the link is brought already up in firmware) + maximum: 16 + + reset-gpio: + description: GPIO pin number of PERST# signal + maxItems: 1 + deprecated: true + + reset-gpios: + description: GPIO controlled connection to PERST# signal + maxItems: 1 + + interrupts: true + + interrupt-names: true + + clocks: true + + snps,enable-cdm-check: + type: boolean + description: | + This is a boolean property and if present enables + automatic checking of CDM (Configuration Dependent Module) registers + for data corruption. CDM registers include standard PCIe configuration + space registers, Port Logic registers, DMA and iATU (internal Address + Translation Unit) registers. + + num-viewport: + description: | + number of view ports configured in hardware. If a platform + does not specify it, the driver autodetects it. + deprecated: true + +unevaluatedProperties: false + +required: + - reg + - reg-names + - compatible + +examples: + - | + bus { + #address-cells = <1>; + #size-cells = <1>; + pcie@dfc00000 { + device_type = "pci"; + compatible = "snps,dw-pcie"; + reg = <0xdfc00000 0x0001000>, /* IP registers */ + <0xd0000000 0x0002000>; /* Configuration space */ + reg-names = "dbi", "config"; + #address-cells = <3>; + #size-cells = <2>; + ranges = <0x81000000 0 0x00000000 0xde000000 0 0x00010000>, + <0x82000000 0 0xd0400000 0xd0400000 0 0x0d000000>; + interrupts = <25>, <24>; + #interrupt-cells = <1>; + num-lanes = <1>; + }; + }; diff --git a/Documentation/devicetree/bindings/pci/socionext,uniphier-pcie-ep.yaml b/Documentation/devicetree/bindings/pci/socionext,uniphier-pcie-ep.yaml index d6cf8a560ef0..144cbcd60a1c 100644 --- a/Documentation/devicetree/bindings/pci/socionext,uniphier-pcie-ep.yaml +++ b/Documentation/devicetree/bindings/pci/socionext,uniphier-pcie-ep.yaml @@ -10,13 +10,13 @@ description: | UniPhier PCIe endpoint controller is based on the Synopsys DesignWare PCI core. It shares common features with the PCIe DesignWare core and inherits common properties defined in - Documentation/devicetree/bindings/pci/designware-pcie.txt. + Documentation/devicetree/bindings/pci/snps,dw-pcie-ep.yaml. maintainers: - Kunihiko Hayashi <hayashi.kunihiko@socionext.com> allOf: - - $ref: "pci-ep.yaml#" + - $ref: /schemas/pci/snps,dw-pcie-ep.yaml# properties: compatible: diff --git a/Documentation/devicetree/bindings/pci/ti-pci.txt b/Documentation/devicetree/bindings/pci/ti-pci.txt index d5cbfe6b0d89..8147e3e3e29b 100644 --- a/Documentation/devicetree/bindings/pci/ti-pci.txt +++ b/Documentation/devicetree/bindings/pci/ti-pci.txt @@ -12,7 +12,7 @@ PCIe DesignWare Controller number of PHYs as specified in *phys* property. - ti,hwmods : Name of the hwmod associated to the pcie, "pcie<X>", where <X> is the instance number of the pcie from the HW spec. - - num-lanes as specified in ../designware-pcie.txt + - num-lanes as specified in ../snps,dw-pcie.yaml - ti,syscon-lane-sel : phandle/offset pair. Phandle to the system control module and the register offset to specify lane selection. @@ -32,7 +32,7 @@ HOST MODE device_type, ranges, interrupt-map-mask, - interrupt-map : as specified in ../designware-pcie.txt + interrupt-map : as specified in ../snps,dw-pcie.yaml - ti,syscon-unaligned-access: phandle to the syscon DT node. The 1st argument should contain the register offset within syscon and the 2nd argument should contain the bit field diff --git a/Documentation/devicetree/bindings/pci/toshiba,visconti-pcie.yaml b/Documentation/devicetree/bindings/pci/toshiba,visconti-pcie.yaml new file mode 100644 index 000000000000..30b6396d83c8 --- /dev/null +++ b/Documentation/devicetree/bindings/pci/toshiba,visconti-pcie.yaml @@ -0,0 +1,110 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/pci/toshiba,visconti-pcie.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Toshiba Visconti5 SoC PCIe Host Controller Device Tree Bindings + +maintainers: + - Nobuhiro Iwamatsu <nobuhiro1.iwamatsu@toshiba.co.jp> + +description: + Toshiba Visconti5 SoC PCIe host controller is based on the Synopsys DesignWare PCIe IP. + +allOf: + - $ref: /schemas/pci/snps,dw-pcie.yaml# + +properties: + compatible: + const: toshiba,visconti-pcie + + reg: + items: + - description: Data Bus Interface (DBI) registers. + - description: PCIe configuration space region. + - description: Visconti specific additional registers. + - description: Visconti specific SMU registers + - description: Visconti specific memory protection unit registers (MPU) + + reg-names: + items: + - const: dbi + - const: config + - const: ulreg + - const: smu + - const: mpu + + interrupts: + maxItems: 1 + + clocks: + items: + - description: PCIe reference clock + - description: PCIe system clock + - description: Auxiliary clock + + clock-names: + items: + - const: ref + - const: core + - const: aux + + num-lanes: + const: 2 + +required: + - reg + - reg-names + - interrupts + - "#interrupt-cells" + - interrupt-map + - interrupt-map-mask + - num-lanes + - clocks + - clock-names + - max-link-speed + +unevaluatedProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/irq.h> + #include <dt-bindings/interrupt-controller/arm-gic.h> + + soc { + #address-cells = <2>; + #size-cells = <2>; + + pcie: pcie@28400000 { + compatible = "toshiba,visconti-pcie"; + reg = <0x0 0x28400000 0x0 0x00400000>, + <0x0 0x70000000 0x0 0x10000000>, + <0x0 0x28050000 0x0 0x00010000>, + <0x0 0x24200000 0x0 0x00002000>, + <0x0 0x24162000 0x0 0x00001000>; + reg-names = "dbi", "config", "ulreg", "smu", "mpu"; + device_type = "pci"; + bus-range = <0x00 0xff>; + num-lanes = <2>; + num-viewport = <8>; + + #address-cells = <3>; + #size-cells = <2>; + #interrupt-cells = <1>; + ranges = <0x81000000 0 0x40000000 0 0x40000000 0 0x00010000>, + <0x82000000 0 0x50000000 0 0x50000000 0 0x20000000>; + interrupts = <GIC_SPI 215 IRQ_TYPE_LEVEL_HIGH>; + interrupt-names = "intr"; + interrupt-map-mask = <0 0 0 7>; + interrupt-map = + <0 0 0 1 &gic GIC_SPI 215 IRQ_TYPE_LEVEL_HIGH + 0 0 0 2 &gic GIC_SPI 215 IRQ_TYPE_LEVEL_HIGH + 0 0 0 3 &gic GIC_SPI 215 IRQ_TYPE_LEVEL_HIGH + 0 0 0 4 &gic GIC_SPI 215 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&extclk100mhz>, <&clk600mhz>, <&clk25mhz>; + clock-names = "ref", "core", "aux"; + max-link-speed = <2>; + }; + }; +... diff --git a/Documentation/devicetree/bindings/pci/uniphier-pcie.txt b/Documentation/devicetree/bindings/pci/uniphier-pcie.txt index c4b7381733a0..359585db049f 100644 --- a/Documentation/devicetree/bindings/pci/uniphier-pcie.txt +++ b/Documentation/devicetree/bindings/pci/uniphier-pcie.txt @@ -6,7 +6,7 @@ on Socionext UniPhier SoCs. UniPhier PCIe host controller is based on the Synopsys DesignWare PCI core. It shares common functions with the PCIe DesignWare core driver and inherits common properties defined in -Documentation/devicetree/bindings/pci/designware-pcie.txt. +Documentation/devicetree/bindings/pci/snps,dw-pcie.yaml. Required properties: - compatible: Should be "socionext,uniphier-pcie". diff --git a/Documentation/devicetree/bindings/phy/fsl,imx8mq-usb-phy.txt b/Documentation/devicetree/bindings/phy/fsl,imx8mq-usb-phy.txt deleted file mode 100644 index 7c70f2ad9942..000000000000 --- a/Documentation/devicetree/bindings/phy/fsl,imx8mq-usb-phy.txt +++ /dev/null @@ -1,20 +0,0 @@ -* Freescale i.MX8MQ USB3 PHY binding - -Required properties: -- compatible: Should be "fsl,imx8mq-usb-phy" or "fsl,imx8mp-usb-phy" -- #phys-cells: must be 0 (see phy-bindings.txt in this directory) -- reg: The base address and length of the registers -- clocks: phandles to the clocks for each clock listed in clock-names -- clock-names: must contain "phy" - -Optional properties: -- vbus-supply: A phandle to the regulator for USB VBUS. - -Example: - usb3_phy0: phy@381f0040 { - compatible = "fsl,imx8mq-usb-phy"; - reg = <0x381f0040 0x40>; - clocks = <&clk IMX8MQ_CLK_USB1_PHY_ROOT>; - clock-names = "phy"; - #phy-cells = <0>; - }; diff --git a/Documentation/devicetree/bindings/phy/fsl,imx8mq-usb-phy.yaml b/Documentation/devicetree/bindings/phy/fsl,imx8mq-usb-phy.yaml new file mode 100644 index 000000000000..2936f3510a6a --- /dev/null +++ b/Documentation/devicetree/bindings/phy/fsl,imx8mq-usb-phy.yaml @@ -0,0 +1,53 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/phy/fsl,imx8mq-usb-phy.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Freescale i.MX8MQ USB3 PHY binding + +maintainers: + - Li Jun <jun.li@nxp.com> + +properties: + compatible: + enum: + - fsl,imx8mq-usb-phy + - fsl,imx8mp-usb-phy + + reg: + maxItems: 1 + + "#phy-cells": + const: 0 + + clocks: + maxItems: 1 + + clock-names: + items: + - const: phy + + vbus-supply: + description: + A phandle to the regulator for USB VBUS. + +required: + - compatible + - reg + - "#phy-cells" + - clocks + - clock-names + +additionalProperties: false + +examples: + - | + #include <dt-bindings/clock/imx8mq-clock.h> + usb3_phy0: phy@381f0040 { + compatible = "fsl,imx8mq-usb-phy"; + reg = <0x381f0040 0x40>; + clocks = <&clk IMX8MQ_CLK_USB1_PHY_ROOT>; + clock-names = "phy"; + #phy-cells = <0>; + }; diff --git a/Documentation/devicetree/bindings/phy/hisilicon,phy-hi3670-pcie.yaml b/Documentation/devicetree/bindings/phy/hisilicon,phy-hi3670-pcie.yaml new file mode 100644 index 000000000000..17367a0275fe --- /dev/null +++ b/Documentation/devicetree/bindings/phy/hisilicon,phy-hi3670-pcie.yaml @@ -0,0 +1,82 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/phy/hisilicon,phy-hi3670-pcie.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: HiSilicon Kirin970 PCIe PHY + +maintainers: + - Mauro Carvalho Chehab <mchehab+huawei@kernel.org> + +description: |+ + Bindings for PCIe PHY on HiSilicon Kirin 970. + +properties: + compatible: + const: hisilicon,hi970-pcie-phy + + "#phy-cells": + const: 0 + + reg: + maxItems: 1 + description: PHY Control registers + + phy-supply: + description: The PCIe PHY power supply + + clocks: + items: + - description: PCIe PHY clock + - description: PCIe AUX clock + - description: PCIe APB PHY clock + - description: PCIe APB SYS clock + - description: PCIe ACLK clock + + clock-names: + items: + - const: phy_ref + - const: aux + - const: apb_phy + - const: apb_sys + - const: aclk + + hisilicon,eye-diagram-param: + $ref: /schemas/types.yaml#/definitions/uint32-array + description: Eye diagram for phy. + +required: + - "#phy-cells" + - compatible + - reg + - clocks + - clock-names + - hisilicon,eye-diagram-param + - phy-supply + +additionalProperties: false + +examples: + - | + #include <dt-bindings/clock/hi3670-clock.h> + + soc { + #address-cells = <2>; + #size-cells = <2>; + pcie_phy: pcie-phy@fc000000 { + compatible = "hisilicon,hi970-pcie-phy"; + reg = <0x0 0xfc000000 0x0 0x80000>; + #phy-cells = <0>; + phy-supply = <&ldo33>; + clocks = <&crg_ctrl HI3670_CLK_GATE_PCIEPHY_REF>, + <&crg_ctrl HI3670_CLK_GATE_PCIEAUX>, + <&crg_ctrl HI3670_PCLK_GATE_PCIE_PHY>, + <&crg_ctrl HI3670_PCLK_GATE_PCIE_SYS>, + <&crg_ctrl HI3670_ACLK_GATE_PCIE>; + clock-names = "phy_ref", "aux", + "apb_phy", "apb_sys", "aclk"; + hisilicon,eye-diagram-param = <0xffffffff 0xffffffff + 0xffffffff 0xffffffff 0xffffffff>; + }; + }; diff --git a/Documentation/devicetree/bindings/phy/intel,phy-keembay-usb.yaml b/Documentation/devicetree/bindings/phy/intel,keembay-phy-usb.yaml index a217bb8ac5bc..52815b6c2b88 100644 --- a/Documentation/devicetree/bindings/phy/intel,phy-keembay-usb.yaml +++ b/Documentation/devicetree/bindings/phy/intel,keembay-phy-usb.yaml @@ -1,7 +1,7 @@ # SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) %YAML 1.2 --- -$id: http://devicetree.org/schemas/phy/intel,phy-keembay-usb.yaml# +$id: http://devicetree.org/schemas/phy/intel,keembay-phy-usb.yaml# $schema: http://devicetree.org/meta-schemas/core.yaml# title: Intel Keem Bay USB PHY bindings diff --git a/Documentation/devicetree/bindings/phy/intel,lgm-emmc-phy.yaml b/Documentation/devicetree/bindings/phy/intel,lgm-emmc-phy.yaml index edd9d70a672a..954e67571dfd 100644 --- a/Documentation/devicetree/bindings/phy/intel,lgm-emmc-phy.yaml +++ b/Documentation/devicetree/bindings/phy/intel,lgm-emmc-phy.yaml @@ -23,9 +23,9 @@ description: |+ properties: compatible: - oneOf: - - const: intel,lgm-emmc-phy - - const: intel,keembay-emmc-phy + enum: + - intel,lgm-emmc-phy + - intel,keembay-emmc-phy "#phy-cells": const: 0 diff --git a/Documentation/devicetree/bindings/phy/mediatek,tphy.yaml b/Documentation/devicetree/bindings/phy/mediatek,tphy.yaml index ef9d9d4e6875..9e6c0f43f1c6 100644 --- a/Documentation/devicetree/bindings/phy/mediatek,tphy.yaml +++ b/Documentation/devicetree/bindings/phy/mediatek,tphy.yaml @@ -15,7 +15,7 @@ description: | controllers on MediaTek SoCs, includes USB2.0, USB3.0, PCIe and SATA. Layout differences of banks between T-PHY V1 (mt8173/mt2701) and - T-PHY V2 (mt2712) when works on USB mode: + T-PHY V2 (mt2712) / V3 (mt8195) when works on USB mode: ----------------------------------- Version 1: port offset bank @@ -34,7 +34,7 @@ description: | u2 port2 0x1800 U2PHY_COM ... - Version 2: + Version 2/3: port offset bank u2 port0 0x0000 MISC 0x0100 FMREG @@ -59,7 +59,8 @@ description: | SPLLC shared by u3 ports and FMREG shared by u2 ports on V1 are put back into each port; a new bank MISC for u2 ports and CHIP for u3 ports are - added on V2. + added on V2; the FMREG bank for slew rate calibration is not used anymore + and reserved on V3; properties: $nodename: @@ -79,8 +80,11 @@ properties: - mediatek,mt2712-tphy - mediatek,mt7629-tphy - mediatek,mt8183-tphy - - mediatek,mt8195-tphy - const: mediatek,generic-tphy-v2 + - items: + - enum: + - mediatek,mt8195-tphy + - const: mediatek,generic-tphy-v3 - const: mediatek,mt2701-u3phy deprecated: true - const: mediatek,mt2712-u3phy @@ -91,7 +95,7 @@ properties: description: Register shared by multiple ports, exclude port's private register. It is needed for T-PHY V1, such as mt2701 and mt8173, but not for - T-PHY V2, such as mt2712. + T-PHY V2/V3, such as mt2712. maxItems: 1 "#address-cells": @@ -197,6 +201,22 @@ patternProperties: Specify the flag to enable BC1.2 if support it type: boolean + mediatek,syscon-type: + $ref: /schemas/types.yaml#/definitions/phandle-array + maxItems: 1 + description: + A phandle to syscon used to access the register of type switch, + the field should always be 3 cells long. + items: + items: + - description: + The first cell represents a phandle to syscon + - description: + The second cell represents the register offset + - description: + The third cell represents the index of config segment + enum: [0, 1, 2, 3] + required: - reg - "#phy-cells" diff --git a/Documentation/devicetree/bindings/phy/qcom,qmp-phy.yaml b/Documentation/devicetree/bindings/phy/qcom,qmp-phy.yaml index f0497b8623ad..75be5650a198 100644 --- a/Documentation/devicetree/bindings/phy/qcom,qmp-phy.yaml +++ b/Documentation/devicetree/bindings/phy/qcom,qmp-phy.yaml @@ -18,6 +18,7 @@ properties: compatible: enum: - qcom,ipq6018-qmp-pcie-phy + - qcom,ipq6018-qmp-usb3-phy - qcom,ipq8074-qmp-pcie-phy - qcom,ipq8074-qmp-usb3-phy - qcom,msm8996-qmp-pcie-phy @@ -27,6 +28,7 @@ properties: - qcom,msm8998-qmp-ufs-phy - qcom,msm8998-qmp-usb3-phy - qcom,sc7180-qmp-usb3-phy + - qcom,sc8180x-qmp-pcie-phy - qcom,sc8180x-qmp-ufs-phy - qcom,sc8180x-qmp-usb3-phy - qcom,sdm845-qhp-pcie-phy @@ -34,6 +36,7 @@ properties: - qcom,sdm845-qmp-ufs-phy - qcom,sdm845-qmp-usb3-phy - qcom,sdm845-qmp-usb3-uni-phy + - qcom,sm6115-qmp-ufs-phy - qcom,sm8150-qmp-ufs-phy - qcom,sm8150-qmp-usb3-phy - qcom,sm8150-qmp-usb3-uni-phy @@ -326,6 +329,7 @@ allOf: compatible: contains: enum: + - qcom,sc8180x-qmp-pcie-phy - qcom,sdm845-qhp-pcie-phy - qcom,sdm845-qmp-pcie-phy - qcom,sdx55-qmp-pcie-phy diff --git a/Documentation/devicetree/bindings/phy/qcom,qmp-usb3-dp-phy.yaml b/Documentation/devicetree/bindings/phy/qcom,qmp-usb3-dp-phy.yaml index 217aa6c91893..60dc27834e1d 100644 --- a/Documentation/devicetree/bindings/phy/qcom,qmp-usb3-dp-phy.yaml +++ b/Documentation/devicetree/bindings/phy/qcom,qmp-usb3-dp-phy.yaml @@ -14,6 +14,8 @@ properties: compatible: enum: - qcom,sc7180-qmp-usb3-dp-phy + - qcom,sc7280-qmp-usb3-dp-phy + - qcom,sc8180x-qmp-usb3-dp-phy - qcom,sdm845-qmp-usb3-dp-phy - qcom,sm8250-qmp-usb3-dp-phy reg: diff --git a/Documentation/devicetree/bindings/phy/renesas,usb2-phy.yaml b/Documentation/devicetree/bindings/phy/renesas,usb2-phy.yaml index d5dc5a3cdceb..3a6e1165419c 100644 --- a/Documentation/devicetree/bindings/phy/renesas,usb2-phy.yaml +++ b/Documentation/devicetree/bindings/phy/renesas,usb2-phy.yaml @@ -30,6 +30,11 @@ properties: - renesas,usb2-phy-r8a77995 # R-Car D3 - const: renesas,rcar-gen3-usb2-phy + - items: + - enum: + - renesas,usb2-phy-r9a07g044 # RZ/G2{L,LC} + - const: renesas,rzg2l-usb2-phy # RZ/G2L family + reg: maxItems: 1 @@ -91,6 +96,16 @@ required: - clocks - '#phy-cells' +allOf: + - if: + properties: + compatible: + contains: + const: renesas,rzg2l-usb2-phy + then: + required: + - resets + additionalProperties: false examples: diff --git a/Documentation/devicetree/bindings/phy/samsung,ufs-phy.yaml b/Documentation/devicetree/bindings/phy/samsung,ufs-phy.yaml index 636cc501b54f..f6ed1a005e7a 100644 --- a/Documentation/devicetree/bindings/phy/samsung,ufs-phy.yaml +++ b/Documentation/devicetree/bindings/phy/samsung,ufs-phy.yaml @@ -16,6 +16,7 @@ properties: compatible: enum: - samsung,exynos7-ufs-phy + - samsung,exynosautov9-ufs-phy reg: maxItems: 1 diff --git a/Documentation/devicetree/bindings/phy/ti,phy-am654-serdes.txt b/Documentation/devicetree/bindings/phy/ti,phy-am654-serdes.txt deleted file mode 100644 index 64b286d2d398..000000000000 --- a/Documentation/devicetree/bindings/phy/ti,phy-am654-serdes.txt +++ /dev/null @@ -1,82 +0,0 @@ -TI AM654 SERDES - -Required properties: - - compatible: Should be "ti,phy-am654-serdes" - - reg : Address and length of the register set for the device. - - #phy-cells: determine the number of cells that should be given in the - phandle while referencing this phy. Should be "2". The 1st cell - corresponds to the phy type (should be one of the types specified in - include/dt-bindings/phy/phy.h) and the 2nd cell should be the serdes - lane function. - If SERDES0 is referenced 2nd cell should be: - 0 - USB3 - 1 - PCIe0 Lane0 - 2 - ICSS2 SGMII Lane0 - If SERDES1 is referenced 2nd cell should be: - 0 - PCIe1 Lane0 - 1 - PCIe0 Lane1 - 2 - ICSS2 SGMII Lane1 - - power-domains: As documented by the generic PM domain bindings in - Documentation/devicetree/bindings/power/power_domain.txt. - - clocks: List of clock-specifiers representing the input to the SERDES. - Should have 3 items representing the left input clock, external - reference clock and right input clock in that order. - - clock-output-names: List of clock names for each of the clock outputs of - SERDES. Should have 3 items for CMU reference clock, - left output clock and right output clock in that order. - - assigned-clocks: As defined in - Documentation/devicetree/bindings/clock/clock-bindings.txt - - assigned-clock-parents: As defined in - Documentation/devicetree/bindings/clock/clock-bindings.txt - - #clock-cells: Should be <1> to choose between the 3 output clocks. - Defined in Documentation/devicetree/bindings/clock/clock-bindings.txt - - The following macros are defined in dt-bindings/phy/phy-am654-serdes.h - for selecting the correct reference clock. This can be used while - specifying the clocks created by SERDES. - => AM654_SERDES_CMU_REFCLK - => AM654_SERDES_LO_REFCLK - => AM654_SERDES_RO_REFCLK - - - mux-controls: Phandle to the multiplexer that is used to select the lane - function. See #phy-cells above to see the multiplex values. - -Example: - -Example for SERDES0 is given below. It has 3 clock inputs; -left input reference clock as indicated by <&k3_clks 153 4>, external -reference clock as indicated by <&k3_clks 153 1> and right input -reference clock as indicated by <&serdes1 AM654_SERDES_LO_REFCLK>. (The -right input of SERDES0 is connected to the left output of SERDES1). - -SERDES0 registers 3 clock outputs as indicated in clock-output-names. The -first refers to the CMU reference clock, second refers to the left output -reference clock and the third refers to the right output reference clock. - -The assigned-clocks and assigned-clock-parents is used here to set the -parent of left input reference clock to MAINHSDIV_CLKOUT4 and parent of -CMU reference clock to left input reference clock. - -serdes0: serdes@900000 { - compatible = "ti,phy-am654-serdes"; - reg = <0x0 0x900000 0x0 0x2000>; - reg-names = "serdes"; - #phy-cells = <2>; - power-domains = <&k3_pds 153>; - clocks = <&k3_clks 153 4>, <&k3_clks 153 1>, - <&serdes1 AM654_SERDES_LO_REFCLK>; - clock-output-names = "serdes0_cmu_refclk", "serdes0_lo_refclk", - "serdes0_ro_refclk"; - assigned-clocks = <&k3_clks 153 4>, <&serdes0 AM654_SERDES_CMU_REFCLK>; - assigned-clock-parents = <&k3_clks 153 8>, <&k3_clks 153 4>; - ti,serdes-clk = <&serdes0_clk>; - mux-controls = <&serdes_mux 0>; - #clock-cells = <1>; -}; - -Example for PCIe consumer node using the SERDES PHY specifier is given below. -&pcie0_rc { - num-lanes = <2>; - phys = <&serdes0 PHY_TYPE_PCIE 1>, <&serdes1 PHY_TYPE_PCIE 1>; - phy-names = "pcie-phy0", "pcie-phy1"; -}; diff --git a/Documentation/devicetree/bindings/phy/ti,phy-am654-serdes.yaml b/Documentation/devicetree/bindings/phy/ti,phy-am654-serdes.yaml new file mode 100644 index 000000000000..62dcb84c08aa --- /dev/null +++ b/Documentation/devicetree/bindings/phy/ti,phy-am654-serdes.yaml @@ -0,0 +1,103 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/phy/ti,phy-am654-serdes.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: TI AM654 SERDES binding + +description: + This binding describes the TI AM654 SERDES. AM654 SERDES can be configured + to be used with either PCIe or USB or SGMII. + +maintainers: + - Kishon Vijay Abraham I <kishon@ti.com> + +properties: + compatible: + enum: + - ti,phy-am654-serdes + + reg: + maxItems: 1 + + reg-names: + items: + - const: serdes + + power-domains: + maxItems: 1 + + clocks: + maxItems: 3 + description: + Three input clocks referring to left input reference clock, refclk and right input reference + clock. + + assigned-clocks: + $ref: "/schemas/types.yaml#/definitions/phandle-array" + assigned-clock-parents: + $ref: "/schemas/types.yaml#/definitions/phandle-array" + + '#phy-cells': + const: 2 + description: + The 1st cell corresponds to the phy type (should be one of the types specified in + include/dt-bindings/phy/phy.h) and the 2nd cell should be the serdes lane function. + + ti,serdes-clk: + description: Phandle to the SYSCON entry required for configuring SERDES clock selection. + $ref: /schemas/types.yaml#/definitions/phandle + + '#clock-cells': + const: 1 + + mux-controls: + maxItems: 1 + description: Phandle to the SYSCON entry required for configuring SERDES lane function. + + clock-output-names: + oneOf: + - description: Clock output names for SERDES 0 + items: + - const: serdes0_cmu_refclk + - const: serdes0_lo_refclk + - const: serdes0_ro_refclk + - description: Clock output names for SERDES 1 + items: + - const: serdes1_cmu_refclk + - const: serdes1_lo_refclk + - const: serdes1_ro_refclk + +required: + - compatible + - reg + - power-domains + - clocks + - assigned-clocks + - assigned-clock-parents + - ti,serdes-clk + - mux-controls + - clock-output-names + +additionalProperties: false + +examples: + - | + #include <dt-bindings/phy/phy-am654-serdes.h> + + serdes0: serdes@900000 { + compatible = "ti,phy-am654-serdes"; + reg = <0x900000 0x2000>; + reg-names = "serdes"; + #phy-cells = <2>; + power-domains = <&k3_pds 153>; + clocks = <&k3_clks 153 4>, <&k3_clks 153 1>, + <&serdes1 AM654_SERDES_LO_REFCLK>; + clock-output-names = "serdes0_cmu_refclk", "serdes0_lo_refclk", "serdes0_ro_refclk"; + assigned-clocks = <&k3_clks 153 4>, <&serdes0 AM654_SERDES_CMU_REFCLK>; + assigned-clock-parents = <&k3_clks 153 8>, <&k3_clks 153 4>; + ti,serdes-clk = <&serdes0_clk>; + mux-controls = <&serdes_mux 0>; + #clock-cells = <1>; + }; diff --git a/Documentation/devicetree/bindings/pinctrl/fsl,imx8ulp-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/fsl,imx8ulp-pinctrl.yaml new file mode 100644 index 000000000000..86622c4f374b --- /dev/null +++ b/Documentation/devicetree/bindings/pinctrl/fsl,imx8ulp-pinctrl.yaml @@ -0,0 +1,79 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/pinctrl/fsl,imx8ulp-pinctrl.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Freescale IMX8ULP IOMUX Controller + +maintainers: + - Jacky Bai <ping.bai@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,imx8ulp-iomuxc1 + + 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: + description: + each entry consists of 5 integers and represents the mux and config + setting for one pin. The first 4 integers <mux_config_reg input_reg + mux_mode input_val> are specified using a PIN_FUNC_ID macro, which can + be found in <arch/arm64/boot/dts/freescale/imx8ulp-pinfunc.h>. The last + integer CONFIG is the pad setting value like pull-up on this pin. Please + refer to i.MX8ULP Reference Manual for detailed CONFIG settings. + $ref: /schemas/types.yaml#/definitions/uint32-matrix + items: + items: + - description: | + "mux_config_reg" indicates the offset of mux register. + - description: | + "input_reg" indicates the offset of select input register. + - description: | + "mux_mode" indicates the mux value to be applied. + - description: | + "input_val" indicates the select input value to be applied. + - description: | + "pad_setting" indicates the pad configuration value to be applied. + + required: + - fsl,pins + + additionalProperties: false + +required: + - compatible + - reg + +additionalProperties: false + +examples: + # Pinmux controller node + - | + iomuxc: pinctrl@298c0000 { + compatible = "fsl,imx8ulp-iomuxc1"; + reg = <0x298c0000 0x10000>; + + pinctrl_lpuart5: lpuart5grp { + fsl,pins = + <0x0138 0x08F0 0x4 0x3 0x3>, + <0x013C 0x08EC 0x4 0x3 0x3>; + }; + }; + +... diff --git a/Documentation/devicetree/bindings/pinctrl/ingenic,pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/ingenic,pinctrl.yaml index a4846d78111c..a12d0ceb7637 100644 --- a/Documentation/devicetree/bindings/pinctrl/ingenic,pinctrl.yaml +++ b/Documentation/devicetree/bindings/pinctrl/ingenic,pinctrl.yaml @@ -19,10 +19,10 @@ description: > 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 JZ4730, the JZ4740, the JZ4725B, the X1000 and the X1830 contains 4 GPIO ports, PA to PD, for a total of 128 - pins. The X2000 contains 5 GPIO ports, PA to PE, for a total of 160 pins. - The JZ4750, the JZ4755 the JZ4760, the JZ4770 and the JZ4780 contains 6 GPIO - ports, PA to PF, for a total of 192 pins. The JZ4775 contains 7 GPIO ports, - PA to PG, for a total of 224 pins. + pins. The X2000 and the X2100 contains 5 GPIO ports, PA to PE, for a total of + 160 pins. The JZ4750, the JZ4755 the JZ4760, the JZ4770 and the JZ4780 contains + 6 GPIO ports, PA to PF, for a total of 192 pins. The JZ4775 contains 7 GPIO + ports, PA to PG, for a total of 224 pins. maintainers: - Paul Cercueil <paul@crapouillou.net> @@ -47,6 +47,7 @@ properties: - ingenic,x1500-pinctrl - ingenic,x1830-pinctrl - ingenic,x2000-pinctrl + - ingenic,x2100-pinctrl - items: - const: ingenic,jz4760b-pinctrl - const: ingenic,jz4760-pinctrl @@ -85,6 +86,7 @@ patternProperties: - ingenic,x1500-gpio - ingenic,x1830-gpio - ingenic,x2000-gpio + - ingenic,x2100-gpio reg: items: diff --git a/Documentation/devicetree/bindings/pinctrl/intel,pinctrl-keembay.yaml b/Documentation/devicetree/bindings/pinctrl/intel,pinctrl-keembay.yaml new file mode 100644 index 000000000000..5e99d79499b4 --- /dev/null +++ b/Documentation/devicetree/bindings/pinctrl/intel,pinctrl-keembay.yaml @@ -0,0 +1,135 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/pinctrl/intel,pinctrl-keembay.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Intel Keem Bay pin controller Device Tree Bindings + +maintainers: + - Lakshmi Sowjanya D <lakshmi.sowjanya.d@intel.com> + +description: | + Intel Keem Bay SoC integrates a pin controller which enables control + of pin directions, input/output values and configuration + for a total of 80 pins. + +properties: + compatible: + const: intel,keembay-pinctrl + + reg: + maxItems: 2 + + gpio-controller: true + + '#gpio-cells': + const: 2 + + ngpios: + description: The number of GPIOs exposed. + const: 80 + + interrupts: + description: + Specifies the interrupt lines to be used by the controller. + Each interrupt line is shared by upto 4 GPIO lines. + maxItems: 8 + + interrupt-controller: true + + '#interrupt-cells': + const: 2 + +patternProperties: + '^gpio@[0-9a-f]*$': + type: object + + description: + Child nodes can be specified to contain pin configuration information, + which can then be utilized by pinctrl client devices. + The following properties are supported. + + properties: + pins: + description: | + The name(s) of the pins to be configured in the child node. + Supported pin names are "GPIO0" up to "GPIO79". + + bias-disable: true + + bias-pull-down: true + + bias-pull-up: true + + drive-strength: + description: IO pads drive strength in milli Ampere. + enum: [2, 4, 8, 12] + + bias-bus-hold: + type: boolean + + input-schmitt-enable: + type: boolean + + slew-rate: + description: GPIO slew rate control. + 0 - Fast(~100MHz) + 1 - Slow(~50MHz) + enum: [0, 1] + +additionalProperties: false + +required: + - compatible + - reg + - gpio-controller + - ngpios + - '#gpio-cells' + - interrupts + - interrupt-controller + - '#interrupt-cells' + +examples: + - | + #include <dt-bindings/interrupt-controller/arm-gic.h> + #include <dt-bindings/interrupt-controller/irq.h> + // Example 1 + gpio@0 { + compatible = "intel,keembay-pinctrl"; + reg = <0x600b0000 0x88>, + <0x600b0190 0x1ac>; + gpio-controller; + ngpios = <0x50>; + #gpio-cells = <0x2>; + interrupts = <GIC_SPI 94 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 95 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 96 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 97 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 98 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 99 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 100 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 101 IRQ_TYPE_LEVEL_HIGH>; + interrupt-controller; + #interrupt-cells = <2>; + }; + + // Example 2 + gpio@1 { + compatible = "intel,keembay-pinctrl"; + reg = <0x600c0000 0x88>, + <0x600c0190 0x1ac>; + gpio-controller; + ngpios = <0x50>; + #gpio-cells = <0x2>; + interrupts = <GIC_SPI 94 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 95 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 96 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 97 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 98 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 99 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 100 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 101 IRQ_TYPE_LEVEL_HIGH>; + interrupt-controller; + #interrupt-cells = <2>; + }; diff --git a/Documentation/devicetree/bindings/pinctrl/marvell,armada-37xx-pinctrl.txt b/Documentation/devicetree/bindings/pinctrl/marvell,armada-37xx-pinctrl.txt index 38dc56a57760..ecec514b3155 100644 --- a/Documentation/devicetree/bindings/pinctrl/marvell,armada-37xx-pinctrl.txt +++ b/Documentation/devicetree/bindings/pinctrl/marvell,armada-37xx-pinctrl.txt @@ -43,19 +43,19 @@ group emmc_nb group pwm0 - pin 11 (GPIO1-11) - - functions pwm, gpio + - functions pwm, led, gpio group pwm1 - pin 12 - - functions pwm, gpio + - functions pwm, led, gpio group pwm2 - pin 13 - - functions pwm, gpio + - functions pwm, led, gpio group pwm3 - pin 14 - - functions pwm, gpio + - functions pwm, led, gpio group pmic1 - pin 7 diff --git a/Documentation/devicetree/bindings/pinctrl/mediatek,mt65xx-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/mediatek,mt65xx-pinctrl.yaml new file mode 100644 index 000000000000..f8e6e138dc13 --- /dev/null +++ b/Documentation/devicetree/bindings/pinctrl/mediatek,mt65xx-pinctrl.yaml @@ -0,0 +1,206 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/pinctrl/mediatek,mt65xx-pinctrl.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Mediatek MT65xx Pin Controller Device Tree Bindings + +maintainers: + - Sean Wang <sean.wang@kernel.org> + +description: |+ + The Mediatek's Pin controller is used to control SoC pins. + +properties: + compatible: + enum: + - mediatek,mt2701-pinctrl + - mediatek,mt2712-pinctrl + - mediatek,mt6397-pinctrl + - mediatek,mt7623-pinctrl + - mediatek,mt8127-pinctrl + - mediatek,mt8135-pinctrl + - mediatek,mt8167-pinctrl + - mediatek,mt8173-pinctrl + - mediatek,mt8516-pinctrl + + reg: + maxItems: 1 + + pins-are-numbered: + $ref: /schemas/types.yaml#/definitions/flag + description: | + Specify the subnodes are using numbered pinmux to specify pins. + + gpio-controller: true + + "#gpio-cells": + const: 2 + description: | + Number of cells in GPIO specifier. Since the generic GPIO + binding is used, the amount of cells must be specified as 2. See the below + mentioned gpio binding representation for description of particular cells. + + mediatek,pctl-regmap: + $ref: /schemas/types.yaml#/definitions/phandle-array + minItems: 1 + maxItems: 2 + description: | + Should be phandles of the syscfg node. + + interrupt-controller: true + + interrupts: + minItems: 1 + maxItems: 3 + + "#interrupt-cells": + const: 2 + +required: + - compatible + - pins-are-numbered + - gpio-controller + - "#gpio-cells" + +patternProperties: + '-[0-9]+$': + type: object + additionalProperties: false + patternProperties: + 'pins': + type: object + additionalProperties: false + description: | + A pinctrl node should contain at least one subnodes representing the + pinctrl groups available on the machine. Each subnode will list the + pins it needs, and how they should be configured, with regard to muxer + configuration, pullups, drive strength, input enable/disable and input + schmitt. + $ref: "/schemas/pinctrl/pincfg-node.yaml" + + properties: + pinmux: + description: + integer array, represents gpio pin number and mux setting. + Supported pin number and mux varies for different SoCs, and are + defined as macros in <soc>-pinfunc.h directly. + + bias-disable: true + + bias-pull-up: + description: | + Besides generic pinconfig options, it can be used as the pull up + settings for 2 pull resistors, R0 and R1. User can configure those + special pins. Some macros have been defined for this usage, such + as MTK_PUPD_SET_R1R0_00. See dt-bindings/pinctrl/mt65xx.h for + valid arguments. + + bias-pull-down: true + + input-enable: true + + input-disable: true + + output-low: true + + output-high: true + + input-schmitt-enable: true + + input-schmitt-disable: true + + drive-strength: + description: | + Can support some arguments, such as MTK_DRIVE_4mA, MTK_DRIVE_6mA, + etc. See dt-bindings/pinctrl/mt65xx.h for valid arguments. + + required: + - pinmux + +additionalProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/irq.h> + #include <dt-bindings/interrupt-controller/arm-gic.h> + #include <dt-bindings/pinctrl/mt8135-pinfunc.h> + + soc { + #address-cells = <2>; + #size-cells = <2>; + + syscfg_pctl_a: syscfg-pctl-a@10005000 { + compatible = "mediatek,mt8135-pctl-a-syscfg", "syscon"; + reg = <0 0x10005000 0 0x1000>; + }; + + syscfg_pctl_b: syscfg-pctl-b@1020c020 { + compatible = "mediatek,mt8135-pctl-b-syscfg", "syscon"; + reg = <0 0x1020C020 0 0x1000>; + }; + + pinctrl@1c20800 { + compatible = "mediatek,mt8135-pinctrl"; + reg = <0 0x1000B000 0 0x1000>; + mediatek,pctl-regmap = <&syscfg_pctl_a>, <&syscfg_pctl_b>; + pins-are-numbered; + gpio-controller; + #gpio-cells = <2>; + interrupt-controller; + #interrupt-cells = <2>; + interrupts = <GIC_SPI 116 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 117 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 118 IRQ_TYPE_LEVEL_HIGH>; + + i2c0_pins_a: i2c0-0 { + pins1 { + pinmux = <MT8135_PIN_100_SDA0__FUNC_SDA0>, + <MT8135_PIN_101_SCL0__FUNC_SCL0>; + bias-disable; + }; + }; + + i2c1_pins_a: i2c1-0 { + pins { + pinmux = <MT8135_PIN_195_SDA1__FUNC_SDA1>, + <MT8135_PIN_196_SCL1__FUNC_SCL1>; + bias-pull-up = <MTK_PUPD_SET_R1R0_01>; + }; + }; + + i2c2_pins_a: i2c2-0 { + pins1 { + pinmux = <MT8135_PIN_193_SDA2__FUNC_SDA2>; + bias-pull-down; + }; + + pins2 { + pinmux = <MT8135_PIN_49_WATCHDOG__FUNC_GPIO49>; + bias-pull-up; + }; + }; + + i2c3_pins_a: i2c3-0 { + pins1 { + pinmux = <MT8135_PIN_40_DAC_CLK__FUNC_GPIO40>, + <MT8135_PIN_41_DAC_WS__FUNC_GPIO41>; + bias-pull-up = <MTK_PUPD_SET_R1R0_01>; + }; + + pins2 { + pinmux = <MT8135_PIN_35_SCL3__FUNC_SCL3>, + <MT8135_PIN_36_SDA3__FUNC_SDA3>; + output-low; + bias-pull-up = <MTK_PUPD_SET_R1R0_01>; + }; + + pins3 { + pinmux = <MT8135_PIN_57_JTCK__FUNC_GPIO57>, + <MT8135_PIN_60_JTDI__FUNC_JTDI>; + drive-strength = <32>; + }; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/pinctrl/mediatek,mt6797-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/mediatek,mt6797-pinctrl.yaml new file mode 100644 index 000000000000..76a6df75ed9c --- /dev/null +++ b/Documentation/devicetree/bindings/pinctrl/mediatek,mt6797-pinctrl.yaml @@ -0,0 +1,173 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/pinctrl/mediatek,mt6797-pinctrl.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Mediatek MT6797 Pin Controller Device Tree Bindings + +maintainers: + - Sean Wang <sean.wang@kernel.org> + +description: |+ + The MediaTek's MT6797 Pin controller is used to control SoC pins. + +properties: + compatible: + const: mediatek,mt6797-pinctrl + + reg: + minItems: 5 + maxItems: 5 + + reg-names: + items: + - const: gpio + - const: iocfgl + - const: iocfgb + - const: iocfgr + - const: iocfgt + + gpio-controller: true + + "#gpio-cells": + const: 2 + description: | + Number of cells in GPIO specifier. Since the generic GPIO + binding is used, the amount of cells must be specified as 2. See the below + mentioned gpio binding representation for description of particular cells. + + interrupt-controller: true + + interrupts: + maxItems: 1 + + "#interrupt-cells": + const: 2 + +required: + - compatible + - reg + - reg-names + - gpio-controller + - "#gpio-cells" + +patternProperties: + '-[0-9]+$': + type: object + additionalProperties: false + patternProperties: + 'pins': + type: object + additionalProperties: false + description: | + A pinctrl node should contain at least one subnodes representing the + pinctrl groups available on the machine. Each subnode will list the + pins it needs, and how they should be configured, with regard to muxer + configuration, pullups, drive strength, input enable/disable and input + schmitt. + $ref: "/schemas/pinctrl/pincfg-node.yaml" + + properties: + pinmux: + description: + integer array, represents gpio pin number and mux setting. + Supported pin number and mux varies for different SoCs, and are + defined as macros in <soc>-pinfunc.h directly. + + bias-disable: true + + bias-pull-up: true + + bias-pull-down: true + + input-enable: true + + input-disable: true + + output-enable: true + + output-low: true + + output-high: true + + input-schmitt-enable: true + + input-schmitt-disable: true + + drive-strength: + enum: [2, 4, 8, 12, 16] + + slew-rate: + enum: [0, 1] + + mediatek,pull-up-adv: + description: | + Pull up setings for 2 pull resistors, R0 and R1. User can + configure those special pins. Valid arguments are described as below: + 0: (R1, R0) = (0, 0) which means R1 disabled and R0 disabled. + 1: (R1, R0) = (0, 1) which means R1 disabled and R0 enabled. + 2: (R1, R0) = (1, 0) which means R1 enabled and R0 disabled. + 3: (R1, R0) = (1, 1) which means R1 enabled and R0 enabled. + $ref: /schemas/types.yaml#/definitions/uint32 + enum: [0, 1, 2, 3] + + mediatek,pull-down-adv: + description: | + Pull down settings for 2 pull resistors, R0 and R1. User can + configure those special pins. Valid arguments are described as below: + 0: (R1, R0) = (0, 0) which means R1 disabled and R0 disabled. + 1: (R1, R0) = (0, 1) which means R1 disabled and R0 enabled. + 2: (R1, R0) = (1, 0) which means R1 enabled and R0 disabled. + 3: (R1, R0) = (1, 1) which means R1 enabled and R0 enabled. + $ref: /schemas/types.yaml#/definitions/uint32 + enum: [0, 1, 2, 3] + + mediatek,tdsel: + description: | + An integer describing the steps for output level shifter duty + cycle when asserted (high pulse width adjustment). Valid arguments + are from 0 to 15. + $ref: /schemas/types.yaml#/definitions/uint32 + + mediatek,rdsel: + description: | + An integer describing the steps for input level shifter duty cycle + when asserted (high pulse width adjustment). Valid arguments are + from 0 to 63. + $ref: /schemas/types.yaml#/definitions/uint32 + + required: + - pinmux + +additionalProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/irq.h> + #include <dt-bindings/interrupt-controller/arm-gic.h> + #include <dt-bindings/pinctrl/mt6797-pinfunc.h> + + soc { + #address-cells = <2>; + #size-cells = <2>; + + pio: pinctrl@10005000 { + compatible = "mediatek,mt6797-pinctrl"; + reg = <0 0x10005000 0 0x1000>, + <0 0x10002000 0 0x400>, + <0 0x10002400 0 0x400>, + <0 0x10002800 0 0x400>, + <0 0x10002C00 0 0x400>; + reg-names = "gpio", "iocfgl", "iocfgb", "iocfgr", "iocfgt"; + gpio-controller; + #gpio-cells = <2>; + + uart_pins_a: uart-0 { + pins1 { + pinmux = <MT6797_GPIO232__FUNC_URXD1>, + <MT6797_GPIO233__FUNC_UTXD1>; + }; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/pinctrl/mediatek,mt7622-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/mediatek,mt7622-pinctrl.yaml new file mode 100644 index 000000000000..0feecd376c69 --- /dev/null +++ b/Documentation/devicetree/bindings/pinctrl/mediatek,mt7622-pinctrl.yaml @@ -0,0 +1,373 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/pinctrl/mediatek,mt7622-pinctrl.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Mediatek MT7622 Pin Controller Device Tree Bindings + +maintainers: + - Sean Wang <sean.wang@kernel.org> + +description: |+ + The MediaTek's MT7622 Pin controller is used to control SoC pins. + +properties: + compatible: + enum: + - mediatek,mt7622-pinctrl + - mediatek,mt7629-pinctrl + + reg: + maxItems: 1 + + reg-names: + items: + - const: eint + + gpio-controller: true + + "#gpio-cells": + const: 2 + description: | + Number of cells in GPIO specifier. Since the generic GPIO + binding is used, the amount of cells must be specified as 2. See the below + mentioned gpio binding representation for description of particular cells. + + interrupt-controller: true + + interrupts: + maxItems: 1 + + "#interrupt-cells": + const: 2 + +required: + - compatible + - reg + - gpio-controller + - "#gpio-cells" + +if: + required: + - interrupt-controller +then: + required: + - reg-names + - interrupts + - "#interrupt-cells" + +patternProperties: + '-[0-9]+$': + type: object + additionalProperties: false + patternProperties: + 'mux': + type: object + additionalProperties: false + description: | + pinmux configuration nodes. + $ref: "/schemas/pinctrl/pinmux-node.yaml" + properties: + function: + description: | + A string containing the name of the function to mux to the group. + enum: [emmc, eth, i2c, i2s, ir, led, flash, pcie, pmic, pwm, sd, + spi, tdm, uart, watchdog, wifi] + + groups: + description: | + An array of strings. Each string contains the name of a group. + + drive-strength: + enum: [4, 8, 12, 16] + + required: + - groups + - function + + allOf: + - if: + properties: + function: + const: emmc + then: + properties: + groups: + enum: [emmc, emmc_rst] + - if: + properties: + function: + const: eth + then: + properties: + groups: + enum: [esw, esw_p0_p1, esw_p2_p3_p4, rgmii_via_esw, + rgmii_via_gmac1, rgmii_via_gmac2, mdc_mdio] + - if: + properties: + function: + const: i2c + then: + properties: + groups: + enum: [i2c0, i2c_0, i2c_1, i2c1_0, i2c1_1, i2c1_2, i2c2_0, + i2c2_1, i2c2_2] + - if: + properties: + function: + const: i2s + then: + properties: + groups: + enum: [i2s_in_mclk_bclk_ws, i2s1_in_data, i2s2_in_data, + i2s3_in_data, i2s4_in_data, i2s_out_mclk_bclk_ws, + i2s1_out_data, i2s2_out_data, i2s3_out_data, + i2s4_out_data] + - if: + properties: + function: + const: ir + then: + properties: + groups: + enum: [ir_0_tx, ir_1_tx, ir_2_tx, ir_0_rx, ir_1_rx, ir_2_rx] + - if: + properties: + function: + const: led + then: + properties: + groups: + enum: [ephy_leds, ephy0_led, ephy1_led, ephy2_led, ephy3_led, + ephy4_led, wled, wf2g_led, wf5g_led] + - if: + properties: + function: + const: flash + then: + properties: + groups: + enum: [par_nand, snfi, spi_nor] + - if: + properties: + function: + const: pcie + then: + properties: + groups: + enum: [pcie0_0_waken, pcie0_1_waken, pcie1_0_waken, + pcie0_0_clkreq, pcie0_1_clkreq, pcie1_0_clkreq, + pcie0_pad_perst, pcie1_pad_perst, pcie_pereset, + pcie_wake, pcie_clkreq] + - if: + properties: + function: + const: pmic + then: + properties: + groups: + enum: [pmic_bus] + - if: + properties: + function: + const: pwm + then: + properties: + groups: + enum: [pwm_ch1_0, pwm_ch1_1, pwm_ch1_2, pwm_ch2_0, pwm_ch2_1, + pwm_ch2_2, pwm_ch3_0, pwm_ch3_1, pwm_ch3_2, pwm_ch4_0, + pwm_ch4_1, pwm_ch4_2, pwm_ch4_3, pwm_ch5_0, pwm_ch5_1, + pwm_ch5_2, pwm_ch6_0, pwm_ch6_1, pwm_ch6_2, pwm_ch6_3, + pwm_ch7_0, pwm_0, pwm_1] + - if: + properties: + function: + const: sd + then: + properties: + groups: + enum: [sd_0, sd_1] + - if: + properties: + function: + const: spi + then: + properties: + groups: + enum: [spic0_0, spic0_1, spic1_0, spic1_1, spic2_0_wp_hold, + spic2_0, spi_0, spi_1, spi_wp, spi_hold] + - if: + properties: + function: + const: tdm + then: + properties: + groups: + enum: [tdm_0_out_mclk_bclk_ws, tdm_0_in_mclk_bclk_ws, + tdm_0_out_data, tdm_0_in_data, tdm_1_out_mclk_bclk_ws, + tdm_1_in_mclk_bclk_ws, tdm_1_out_data, tdm_1_in_data] + - if: + properties: + function: + const: uart + then: + properties: + groups: + enum: [uart0_0_tx_rx, uart1_0_tx_rx, uart1_0_rts_cts, + uart1_1_tx_rx, uart1_1_rts_cts, uart2_0_tx_rx, + uart2_0_rts_cts, uart2_1_tx_rx, uart2_1_rts_cts, + uart2_2_tx_rx, uart2_2_rts_cts, uart2_3_tx_rx, + uart3_0_tx_rx, uart3_1_tx_rx, uart3_1_rts_cts, + uart4_0_tx_rx, uart4_1_tx_rx, uart4_1_rts_cts, + uart4_2_tx_rx, uart4_2_rts_cts, uart0_txd_rxd, + uart1_0_txd_rxd, uart1_0_cts_rts, uart1_1_txd_rxd, + uart1_1_cts_rts, uart2_0_txd_rxd, uart2_0_cts_rts, + uart2_1_txd_rxd, uart2_1_cts_rts] + - if: + properties: + function: + const: watchdog + then: + properties: + groups: + enum: [watchdog] + - if: + properties: + function: + const: wifi + then: + properties: + groups: + enum: [wf0_2g, wf0_5g] + + 'conf': + type: object + additionalProperties: false + description: | + pinconf configuration nodes. + $ref: "/schemas/pinctrl/pincfg-node.yaml" + + properties: + groups: + description: | + An array of strings. Each string contains the name of a group. + Valid values are the same as the pinmux node. + + pins: + description: | + An array of strings. Each string contains the name of a pin. + enum: [GPIO_A, I2S1_IN, I2S1_OUT, I2S_BCLK, I2S_WS, I2S_MCLK, TXD0, + RXD0, SPI_WP, SPI_HOLD, SPI_CLK, SPI_MOSI, SPI_MISO, SPI_CS, + I2C_SDA, I2C_SCL, I2S2_IN, I2S3_IN, I2S4_IN, I2S2_OUT, + I2S3_OUT, I2S4_OUT, GPIO_B, MDC, MDIO, G2_TXD0, G2_TXD1, + G2_TXD2, G2_TXD3, G2_TXEN, G2_TXC, G2_RXD0, G2_RXD1, G2_RXD2, + G2_RXD3, G2_RXDV, G2_RXC, NCEB, NWEB, NREB, NDL4, NDL5, NDL6, + NDL7, NRB, NCLE, NALE, NDL0, NDL1, NDL2, NDL3, MDI_TP_P0, + MDI_TN_P0, MDI_RP_P0, MDI_RN_P0, MDI_TP_P1, MDI_TN_P1, + MDI_RP_P1, MDI_RN_P1, MDI_RP_P2, MDI_RN_P2, MDI_TP_P2, + MDI_TN_P2, MDI_TP_P3, MDI_TN_P3, MDI_RP_P3, MDI_RN_P3, + MDI_RP_P4, MDI_RN_P4, MDI_TP_P4, MDI_TN_P4, PMIC_SCL, + PMIC_SDA, SPIC1_CLK, SPIC1_MOSI, SPIC1_MISO, SPIC1_CS, + GPIO_D, WATCHDOG, RTS3_N, CTS3_N, TXD3, RXD3, PERST0_N, + PERST1_N, WLED_N, EPHY_LED0_N, AUXIN0, AUXIN1, AUXIN2, + AUXIN3, TXD4, RXD4, RTS4_N, CST4_N, PWM1, PWM2, PWM3, PWM4, + PWM5, PWM6, PWM7, GPIO_E, TOP_5G_CLK, TOP_5G_DATA, + WF0_5G_HB0, WF0_5G_HB1, WF0_5G_HB2, WF0_5G_HB3, WF0_5G_HB4, + WF0_5G_HB5, WF0_5G_HB6, XO_REQ, TOP_RST_N, SYS_WATCHDOG, + EPHY_LED0_N_JTDO, EPHY_LED1_N_JTDI, EPHY_LED2_N_JTMS, + EPHY_LED3_N_JTCLK, EPHY_LED4_N_JTRST_N, WF2G_LED_N, + WF5G_LED_N, GPIO_9, GPIO_10, GPIO_11, GPIO_12, UART1_TXD, + UART1_RXD, UART1_CTS, UART1_RTS, UART2_TXD, UART2_RXD, + UART2_CTS, UART2_RTS, SMI_MDC, SMI_MDIO, PCIE_PERESET_N, + PWM_0, GPIO_0, GPIO_1, GPIO_2, GPIO_3, GPIO_4, GPIO_5, + GPIO_6, GPIO_7, GPIO_8, UART0_TXD, UART0_RXD, TOP_2G_CLK, + TOP_2G_DATA, WF0_2G_HB0, WF0_2G_HB1, WF0_2G_HB2, WF0_2G_HB3, + WF0_2G_HB4, WF0_2G_HB5, WF0_2G_HB6] + + bias-disable: true + + bias-pull-up: true + + bias-pull-down: true + + input-enable: true + + input-disable: true + + output-enable: true + + output-low: true + + output-high: true + + input-schmitt-enable: true + + input-schmitt-disable: true + + drive-strength: + enum: [4, 8, 12, 16] + + slew-rate: + enum: [0, 1] + + mediatek,tdsel: + description: | + An integer describing the steps for output level shifter duty + cycle when asserted (high pulse width adjustment). Valid arguments + are from 0 to 15. + $ref: /schemas/types.yaml#/definitions/uint32 + + mediatek,rdsel: + description: | + An integer describing the steps for input level shifter duty cycle + when asserted (high pulse width adjustment). Valid arguments are + from 0 to 63. + $ref: /schemas/types.yaml#/definitions/uint32 + + required: + - pins + +additionalProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/irq.h> + #include <dt-bindings/interrupt-controller/arm-gic.h> + + soc { + #address-cells = <2>; + #size-cells = <2>; + + pio: pinctrl@10211000 { + compatible = "mediatek,mt7622-pinctrl"; + reg = <0 0x10211000 0 0x1000>; + gpio-controller; + #gpio-cells = <2>; + + pinctrl_eth_default: eth-0 { + mux-mdio { + groups = "mdc_mdio"; + function = "eth"; + drive-strength = <12>; + }; + + mux-gmac2 { + groups = "rgmii_via_gmac2"; + function = "eth"; + drive-strength = <12>; + }; + + mux-esw { + groups = "esw"; + function = "eth"; + drive-strength = <8>; + }; + + conf-mdio { + pins = "MDC"; + bias-pull-up; + }; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/pinctrl/mediatek,mt8183-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/mediatek,mt8183-pinctrl.yaml new file mode 100644 index 000000000000..cc1509e9b981 --- /dev/null +++ b/Documentation/devicetree/bindings/pinctrl/mediatek,mt8183-pinctrl.yaml @@ -0,0 +1,228 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/pinctrl/mediatek,mt8183-pinctrl.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Mediatek MT8183 Pin Controller Device Tree Bindings + +maintainers: + - Sean Wang <sean.wang@kernel.org> + +description: |+ + The MediaTek's MT8183 Pin controller is used to control SoC pins. + +properties: + compatible: + const: mediatek,mt8183-pinctrl + + reg: + minItems: 10 + maxItems: 10 + + reg-names: + items: + - const: iocfg0 + - const: iocfg1 + - const: iocfg2 + - const: iocfg3 + - const: iocfg4 + - const: iocfg5 + - const: iocfg6 + - const: iocfg7 + - const: iocfg8 + - const: eint + + gpio-controller: true + + "#gpio-cells": + const: 2 + description: | + Number of cells in GPIO specifier. Since the generic GPIO + binding is used, the amount of cells must be specified as 2. See the below + mentioned gpio binding representation for description of particular cells. + + gpio-ranges: + minItems: 1 + maxItems: 5 + description: | + GPIO valid number range. + + interrupt-controller: true + + interrupts: + maxItems: 1 + + "#interrupt-cells": + const: 2 + +required: + - compatible + - reg + - gpio-controller + - "#gpio-cells" + - gpio-ranges + +patternProperties: + '-[0-9]+$': + type: object + additionalProperties: false + patternProperties: + 'pins': + type: object + additionalProperties: false + description: | + A pinctrl node should contain at least one subnodes representing the + pinctrl groups available on the machine. Each subnode will list the + pins it needs, and how they should be configured, with regard to muxer + configuration, pullups, drive strength, input enable/disable and input + schmitt. + $ref: "/schemas/pinctrl/pincfg-node.yaml" + + properties: + pinmux: + description: + integer array, represents gpio pin number and mux setting. + Supported pin number and mux varies for different SoCs, and are + defined as macros in <soc>-pinfunc.h directly. + + bias-disable: true + + bias-pull-up: true + + bias-pull-down: true + + input-enable: true + + input-disable: true + + output-low: true + + output-high: true + + input-schmitt-enable: true + + input-schmitt-disable: true + + drive-strength: + enum: [2, 4, 6, 8, 10, 12, 14, 16] + + mediatek,drive-strength-adv: + description: | + Describe the specific driving setup property. + For I2C pins, the existing generic driving setup can only support + 2/4/6/8/10/12/14/16mA driving. But in specific driving setup, they + can support 0.125/0.25/0.5/1mA adjustment. If we enable specific + driving setup, the existing generic setup will be disabled. + The specific driving setup is controlled by E1E0EN. + When E1=0/E0=0, the strength is 0.125mA. + When E1=0/E0=1, the strength is 0.25mA. + When E1=1/E0=0, the strength is 0.5mA. + When E1=1/E0=1, the strength is 1mA. + EN is used to enable or disable the specific driving setup. + Valid arguments are described as below: + 0: (E1, E0, EN) = (0, 0, 0) + 1: (E1, E0, EN) = (0, 0, 1) + 2: (E1, E0, EN) = (0, 1, 0) + 3: (E1, E0, EN) = (0, 1, 1) + 4: (E1, E0, EN) = (1, 0, 0) + 5: (E1, E0, EN) = (1, 0, 1) + 6: (E1, E0, EN) = (1, 1, 0) + 7: (E1, E0, EN) = (1, 1, 1) + So the valid arguments are from 0 to 7. + $ref: /schemas/types.yaml#/definitions/uint32 + enum: [0, 1, 2, 3, 4, 5, 6, 7] + + mediatek,pull-up-adv: + description: | + Pull up setings for 2 pull resistors, R0 and R1. User can + configure those special pins. Valid arguments are described as below: + 0: (R1, R0) = (0, 0) which means R1 disabled and R0 disabled. + 1: (R1, R0) = (0, 1) which means R1 disabled and R0 enabled. + 2: (R1, R0) = (1, 0) which means R1 enabled and R0 disabled. + 3: (R1, R0) = (1, 1) which means R1 enabled and R0 enabled. + $ref: /schemas/types.yaml#/definitions/uint32 + enum: [0, 1, 2, 3] + + mediatek,pull-down-adv: + description: | + Pull down settings for 2 pull resistors, R0 and R1. User can + configure those special pins. Valid arguments are described as below: + 0: (R1, R0) = (0, 0) which means R1 disabled and R0 disabled. + 1: (R1, R0) = (0, 1) which means R1 disabled and R0 enabled. + 2: (R1, R0) = (1, 0) which means R1 enabled and R0 disabled. + 3: (R1, R0) = (1, 1) which means R1 enabled and R0 enabled. + $ref: /schemas/types.yaml#/definitions/uint32 + enum: [0, 1, 2, 3] + + mediatek,tdsel: + description: | + An integer describing the steps for output level shifter duty + cycle when asserted (high pulse width adjustment). Valid arguments + are from 0 to 15. + $ref: /schemas/types.yaml#/definitions/uint32 + + mediatek,rdsel: + description: | + An integer describing the steps for input level shifter duty cycle + when asserted (high pulse width adjustment). Valid arguments are + from 0 to 63. + $ref: /schemas/types.yaml#/definitions/uint32 + + required: + - pinmux + +additionalProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/irq.h> + #include <dt-bindings/interrupt-controller/arm-gic.h> + #include <dt-bindings/pinctrl/mt8183-pinfunc.h> + + soc { + #address-cells = <2>; + #size-cells = <2>; + + pio: pinctrl@10005000 { + compatible = "mediatek,mt8183-pinctrl"; + reg = <0 0x10005000 0 0x1000>, + <0 0x11f20000 0 0x1000>, + <0 0x11e80000 0 0x1000>, + <0 0x11e70000 0 0x1000>, + <0 0x11e90000 0 0x1000>, + <0 0x11d30000 0 0x1000>, + <0 0x11d20000 0 0x1000>, + <0 0x11c50000 0 0x1000>, + <0 0x11f30000 0 0x1000>, + <0 0x1000b000 0 0x1000>; + reg-names = "iocfg0", "iocfg1", "iocfg2", + "iocfg3", "iocfg4", "iocfg5", + "iocfg6", "iocfg7", "iocfg8", + "eint"; + gpio-controller; + #gpio-cells = <2>; + gpio-ranges = <&pio 0 0 192>; + interrupt-controller; + interrupts = <GIC_SPI 177 IRQ_TYPE_LEVEL_HIGH>; + #interrupt-cells = <2>; + + i2c0_pins_a: i2c-0 { + pins1 { + pinmux = <PINMUX_GPIO48__FUNC_SCL5>, + <PINMUX_GPIO49__FUNC_SDA5>; + mediatek,pull-up-adv = <3>; + mediatek,drive-strength-adv = <7>; + }; + }; + + i2c1_pins_a: i2c-1 { + pins { + pinmux = <PINMUX_GPIO50__FUNC_SCL3>, + <PINMUX_GPIO51__FUNC_SDA3>; + mediatek,pull-down-adv = <2>; + mediatek,drive-strength-adv = <4>; + }; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/pinctrl/pinctrl-mt65xx.txt b/Documentation/devicetree/bindings/pinctrl/pinctrl-mt65xx.txt deleted file mode 100644 index 5fe2c26c28bf..000000000000 --- a/Documentation/devicetree/bindings/pinctrl/pinctrl-mt65xx.txt +++ /dev/null @@ -1,156 +0,0 @@ -* Mediatek MT65XX Pin Controller - -The Mediatek's Pin controller is used to control SoC pins. - -Required properties: -- compatible: value should be one of the following. - "mediatek,mt2701-pinctrl", compatible with mt2701 pinctrl. - "mediatek,mt2712-pinctrl", compatible with mt2712 pinctrl. - "mediatek,mt6397-pinctrl", compatible with mt6397 pinctrl. - "mediatek,mt7623-pinctrl", compatible with mt7623 pinctrl. - "mediatek,mt8127-pinctrl", compatible with mt8127 pinctrl. - "mediatek,mt8135-pinctrl", compatible with mt8135 pinctrl. - "mediatek,mt8167-pinctrl", compatible with mt8167 pinctrl. - "mediatek,mt8173-pinctrl", compatible with mt8173 pinctrl. - "mediatek,mt8365-pinctrl", compatible with mt8365 pinctrl. - "mediatek,mt8516-pinctrl", compatible with mt8516 pinctrl. -- pins-are-numbered: Specify the subnodes are using numbered pinmux to - specify pins. -- gpio-controller : Marks the device node as a gpio controller. -- #gpio-cells: number of cells in GPIO specifier. Since the generic GPIO - binding is used, the amount of cells must be specified as 2. See the below - mentioned gpio binding representation for description of particular cells. - - Eg: <&pio 6 0> - <[phandle of the gpio controller node] - [line number within the gpio controller] - [flags]> - - Values for gpio specifier: - - Line number: is a value between 0 to 202. - - Flags: bit field of flags, as defined in <dt-bindings/gpio/gpio.h>. - Only the following flags are supported: - 0 - GPIO_ACTIVE_HIGH - 1 - GPIO_ACTIVE_LOW - -Optional properties: -- mediatek,pctl-regmap: Should be a phandle of the syscfg node. -- reg: physicall address base for EINT registers -- interrupt-controller: Marks the device node as an interrupt controller -- #interrupt-cells: Should be two. -- interrupts : The interrupt outputs from the controller. - -Please refer to pinctrl-bindings.txt in this directory for details of the -common pinctrl bindings used by client devices. - -Subnode format -A pinctrl node should contain at least one subnodes representing the -pinctrl groups available on the machine. Each subnode will list the -pins it needs, and how they should be configured, with regard to muxer -configuration, pullups, drive strength, input enable/disable and input schmitt. - - node { - pinmux = <PIN_NUMBER_PINMUX>; - GENERIC_PINCONFIG; - }; - -Required properties: -- pinmux: integer array, represents gpio pin number and mux setting. - Supported pin number and mux varies for different SoCs, and are defined - as macros in boot/dts/<soc>-pinfunc.h directly. - -Optional properties: -- GENERIC_PINCONFIG: is the generic pinconfig options to use, bias-disable, - bias-pull-down, bias-pull-up, input-enable, input-disable, output-low, output-high, - input-schmitt-enable, input-schmitt-disable and drive-strength are valid. - - Some special pins have extra pull up strength, there are R0 and R1 pull-up - resistors available, but for user, it's only need to set R1R0 as 00, 01, 10 or 11. - So when config bias-pull-up, it support arguments for those special pins. - Some macros have been defined for this usage, such as MTK_PUPD_SET_R1R0_00. - See dt-bindings/pinctrl/mt65xx.h. - - When config drive-strength, it can support some arguments, such as - MTK_DRIVE_4mA, MTK_DRIVE_6mA, etc. See dt-bindings/pinctrl/mt65xx.h. - -Examples: - -#include "mt8135-pinfunc.h" - -... -{ - syscfg_pctl_a: syscfg-pctl-a@10005000 { - compatible = "mediatek,mt8135-pctl-a-syscfg", "syscon"; - reg = <0 0x10005000 0 0x1000>; - }; - - syscfg_pctl_b: syscfg-pctl-b@1020c020 { - compatible = "mediatek,mt8135-pctl-b-syscfg", "syscon"; - reg = <0 0x1020C020 0 0x1000>; - }; - - pinctrl@1c20800 { - compatible = "mediatek,mt8135-pinctrl"; - reg = <0 0x1000B000 0 0x1000>; - mediatek,pctl-regmap = <&syscfg_pctl_a>, <&syscfg_pctl_b>; - pins-are-numbered; - gpio-controller; - #gpio-cells = <2>; - interrupt-controller; - #interrupt-cells = <2>; - interrupts = <GIC_SPI 116 IRQ_TYPE_LEVEL_HIGH>, - <GIC_SPI 117 IRQ_TYPE_LEVEL_HIGH>, - <GIC_SPI 118 IRQ_TYPE_LEVEL_HIGH>; - - i2c0_pins_a: i2c0@0 { - pins1 { - pinmux = <MT8135_PIN_100_SDA0__FUNC_SDA0>, - <MT8135_PIN_101_SCL0__FUNC_SCL0>; - bias-disable; - }; - }; - - i2c1_pins_a: i2c1@0 { - pins { - pinmux = <MT8135_PIN_195_SDA1__FUNC_SDA1>, - <MT8135_PIN_196_SCL1__FUNC_SCL1>; - bias-pull-up = <55>; - }; - }; - - i2c2_pins_a: i2c2@0 { - pins1 { - pinmux = <MT8135_PIN_193_SDA2__FUNC_SDA2>; - bias-pull-down; - }; - - pins2 { - pinmux = <MT8135_PIN_49_WATCHDOG__FUNC_GPIO49>; - bias-pull-up; - }; - }; - - i2c3_pins_a: i2c3@0 { - pins1 { - pinmux = <MT8135_PIN_40_DAC_CLK__FUNC_GPIO40>, - <MT8135_PIN_41_DAC_WS__FUNC_GPIO41>; - bias-pull-up = <55>; - }; - - pins2 { - pinmux = <MT8135_PIN_35_SCL3__FUNC_SCL3>, - <MT8135_PIN_36_SDA3__FUNC_SDA3>; - output-low; - bias-pull-up = <55>; - }; - - pins3 { - pinmux = <MT8135_PIN_57_JTCK__FUNC_GPIO57>, - <MT8135_PIN_60_JTDI__FUNC_JTDI>; - drive-strength = <32>; - }; - }; - - ... - } -}; diff --git a/Documentation/devicetree/bindings/pinctrl/pinctrl-mt6797.txt b/Documentation/devicetree/bindings/pinctrl/pinctrl-mt6797.txt deleted file mode 100644 index bd83401e6179..000000000000 --- a/Documentation/devicetree/bindings/pinctrl/pinctrl-mt6797.txt +++ /dev/null @@ -1,83 +0,0 @@ -* MediaTek MT6797 Pin Controller - -The MediaTek's MT6797 Pin controller is used to control SoC pins. - -Required properties: -- compatible: Value should be one of the following. - "mediatek,mt6797-pinctrl", compatible with mt6797 pinctrl. -- reg: Should contain address and size for gpio, iocfgl, iocfgb, - iocfgr and iocfgt register bases. -- reg-names: An array of strings describing the "reg" entries. Must - contain "gpio", "iocfgl", "iocfgb", "iocfgr", "iocfgt". -- gpio-controller: Marks the device node as a gpio controller. -- #gpio-cells: Should be two. The first cell is the gpio pin number - and the second cell is used for optional parameters. - -Optional properties: -- interrupt-controller: Marks the device node as an interrupt controller. -- #interrupt-cells: Should be two. -- interrupts : The interrupt outputs from the controller. - -Please refer to pinctrl-bindings.txt in this directory for details of the -common pinctrl bindings used by client devices. - -Subnode format -A pinctrl node should contain at least one subnodes representing the -pinctrl groups available on the machine. Each subnode will list the -pins it needs, and how they should be configured, with regard to muxer -configuration, pullups, drive strength, input enable/disable and input schmitt. - - node { - pinmux = <PIN_NUMBER_PINMUX>; - GENERIC_PINCONFIG; - }; - -Required properties: -- pinmux: Integer array, represents gpio pin number and mux setting. - Supported pin number and mux varies for different SoCs, and are defined - as macros in dt-bindings/pinctrl/<soc>-pinfunc.h directly. - -Optional properties: -- GENERIC_PINCONFIG: is the generic pinconfig options to use, bias-disable, - bias-pull, bias-pull-down, input-enable, input-schmitt-enable, - input-schmitt-disable, output-enable output-low, output-high, - drive-strength, and slew-rate are valid. - - Valid arguments for 'slew-rate' are '0' for no slew rate controlled and - '1' for slower slew rate respectively. Valid arguments for 'drive-strength' - is limited, such as 2, 4, 8, 12, or 16 in mA. - - Some optional vendor properties as defined are valid to specify in a - pinconf subnode: - - mediatek,tdsel: An integer describing the steps for output level shifter - duty cycle when asserted (high pulse width adjustment). Valid arguments - are from 0 to 15. - - mediatek,rdsel: An integer describing the steps for input level shifter - duty cycle when asserted (high pulse width adjustment). Valid arguments - are from 0 to 63. - - mediatek,pull-up-adv: An integer describing the code R1R0 as 0, 1, 2 - or 3 for the advanced pull-up resistors. - - mediatek,pull-down-adv: An integer describing the code R1R0 as 0, 1, 2, - or 3 for the advanced pull-down resistors. - -Examples: - - pio: pinctrl@10005000 { - compatible = "mediatek,mt6797-pinctrl"; - reg = <0 0x10005000 0 0x1000>, - <0 0x10002000 0 0x400>, - <0 0x10002400 0 0x400>, - <0 0x10002800 0 0x400>, - <0 0x10002C00 0 0x400>; - reg-names = "gpio", "iocfgl", "iocfgb", - "iocfgr", "iocfgt"; - gpio-controller; - #gpio-cells = <2>; - - uart1_pins_a: uart1 { - pins1 { - pinmux = <MT6797_GPIO232__FUNC_URXD1>, - <MT6797_GPIO233__FUNC_UTXD1>; - }; - }; - }; diff --git a/Documentation/devicetree/bindings/pinctrl/pinctrl-mt7622.txt b/Documentation/devicetree/bindings/pinctrl/pinctrl-mt7622.txt deleted file mode 100644 index 7a7aca1ed705..000000000000 --- a/Documentation/devicetree/bindings/pinctrl/pinctrl-mt7622.txt +++ /dev/null @@ -1,490 +0,0 @@ -== MediaTek MT7622 pinctrl controller == - -Required properties for the root node: - - compatible: Should be one of the following - "mediatek,mt7622-pinctrl" for MT7622 SoC - "mediatek,mt7629-pinctrl" for MT7629 SoC - - reg: offset and length of the pinctrl space - - - gpio-controller: Marks the device node as a GPIO controller. - - #gpio-cells: Should be two. The first cell is the pin number and the - second is the GPIO flags. - -Optional properties: -- interrupt-controller : Marks the device node as an interrupt controller - -If the property interrupt-controller is defined, following property is required -- reg-names: A string describing the "reg" entries. Must contain "eint". -- interrupts : The interrupt output from the controller. -- #interrupt-cells: Should be two. - -Please refer to pinctrl-bindings.txt in this directory for details of the -common pinctrl bindings used by client devices, including the meaning of the -phrase "pin configuration node". - -MT7622 pin configuration nodes act as a container for an arbitrary number of -subnodes. Each of these subnodes represents some desired configuration for a -pin, a group, or a list of pins or groups. This configuration can include the -mux function to select on those pin(s)/group(s), and various pin configuration -parameters, such as pull-up, slew rate, etc. - -We support 2 types of configuration nodes. Those nodes can be either pinmux -nodes or pinconf nodes. Each configuration node can consist of multiple nodes -describing the pinmux and pinconf options. - -The name of each subnode doesn't matter as long as it is unique; all subnodes -should be enumerated and processed purely based on their content. - -== pinmux nodes content == - -The following generic properties as defined in pinctrl-bindings.txt are valid -to specify in a pinmux subnode: - -Required properties are: - - groups: An array of strings. Each string contains the name of a group. - Valid values for these names are listed below. - - function: A string containing the name of the function to mux to the - group. Valid values for function names are listed below. - -== pinconf nodes content == - -The following generic properties as defined in pinctrl-bindings.txt are valid -to specify in a pinconf subnode: - -Required properties are: - - pins: An array of strings. Each string contains the name of a pin. - Valid values for these names are listed below. - - groups: An array of strings. Each string contains the name of a group. - Valid values for these names are listed below. - -Optional properies are: - bias-disable, bias-pull, bias-pull-down, input-enable, - input-schmitt-enable, input-schmitt-disable, output-enable - output-low, output-high, drive-strength, slew-rate - - Valid arguments for 'slew-rate' are '0' for no slew rate controlled and '1' for - slower slew rate respectively. - Valid arguments for 'drive-strength', 4, 8, 12, or 16 in mA. - -The following specific properties as defined are valid to specify in a pinconf -subnode: - -Optional properties are: - - mediatek,tdsel: An integer describing the steps for output level shifter duty - cycle when asserted (high pulse width adjustment). Valid arguments are from 0 - to 15. - - mediatek,rdsel: An integer describing the steps for input level shifter duty - cycle when asserted (high pulse width adjustment). Valid arguments are from 0 - to 63. - -== Valid values for pins, function and groups on MT7622 == - -Valid values for pins are: -pins can be referenced via the pin names as the below table shown and the -related physical number is also put ahead of those names which helps cross -references to pins between groups to know whether pins assignment conflict -happens among devices try to acquire those available pins. - - Pin #: Valid values for pins - ----------------------------- - PIN 0: "GPIO_A" - PIN 1: "I2S1_IN" - PIN 2: "I2S1_OUT" - PIN 3: "I2S_BCLK" - PIN 4: "I2S_WS" - PIN 5: "I2S_MCLK" - PIN 6: "TXD0" - PIN 7: "RXD0" - PIN 8: "SPI_WP" - PIN 9: "SPI_HOLD" - PIN 10: "SPI_CLK" - PIN 11: "SPI_MOSI" - PIN 12: "SPI_MISO" - PIN 13: "SPI_CS" - PIN 14: "I2C_SDA" - PIN 15: "I2C_SCL" - PIN 16: "I2S2_IN" - PIN 17: "I2S3_IN" - PIN 18: "I2S4_IN" - PIN 19: "I2S2_OUT" - PIN 20: "I2S3_OUT" - PIN 21: "I2S4_OUT" - PIN 22: "GPIO_B" - PIN 23: "MDC" - PIN 24: "MDIO" - PIN 25: "G2_TXD0" - PIN 26: "G2_TXD1" - PIN 27: "G2_TXD2" - PIN 28: "G2_TXD3" - PIN 29: "G2_TXEN" - PIN 30: "G2_TXC" - PIN 31: "G2_RXD0" - PIN 32: "G2_RXD1" - PIN 33: "G2_RXD2" - PIN 34: "G2_RXD3" - PIN 35: "G2_RXDV" - PIN 36: "G2_RXC" - PIN 37: "NCEB" - PIN 38: "NWEB" - PIN 39: "NREB" - PIN 40: "NDL4" - PIN 41: "NDL5" - PIN 42: "NDL6" - PIN 43: "NDL7" - PIN 44: "NRB" - PIN 45: "NCLE" - PIN 46: "NALE" - PIN 47: "NDL0" - PIN 48: "NDL1" - PIN 49: "NDL2" - PIN 50: "NDL3" - PIN 51: "MDI_TP_P0" - PIN 52: "MDI_TN_P0" - PIN 53: "MDI_RP_P0" - PIN 54: "MDI_RN_P0" - PIN 55: "MDI_TP_P1" - PIN 56: "MDI_TN_P1" - PIN 57: "MDI_RP_P1" - PIN 58: "MDI_RN_P1" - PIN 59: "MDI_RP_P2" - PIN 60: "MDI_RN_P2" - PIN 61: "MDI_TP_P2" - PIN 62: "MDI_TN_P2" - PIN 63: "MDI_TP_P3" - PIN 64: "MDI_TN_P3" - PIN 65: "MDI_RP_P3" - PIN 66: "MDI_RN_P3" - PIN 67: "MDI_RP_P4" - PIN 68: "MDI_RN_P4" - PIN 69: "MDI_TP_P4" - PIN 70: "MDI_TN_P4" - PIN 71: "PMIC_SCL" - PIN 72: "PMIC_SDA" - PIN 73: "SPIC1_CLK" - PIN 74: "SPIC1_MOSI" - PIN 75: "SPIC1_MISO" - PIN 76: "SPIC1_CS" - PIN 77: "GPIO_D" - PIN 78: "WATCHDOG" - PIN 79: "RTS3_N" - PIN 80: "CTS3_N" - PIN 81: "TXD3" - PIN 82: "RXD3" - PIN 83: "PERST0_N" - PIN 84: "PERST1_N" - PIN 85: "WLED_N" - PIN 86: "EPHY_LED0_N" - PIN 87: "AUXIN0" - PIN 88: "AUXIN1" - PIN 89: "AUXIN2" - PIN 90: "AUXIN3" - PIN 91: "TXD4" - PIN 92: "RXD4" - PIN 93: "RTS4_N" - PIN 94: "CST4_N" - PIN 95: "PWM1" - PIN 96: "PWM2" - PIN 97: "PWM3" - PIN 98: "PWM4" - PIN 99: "PWM5" - PIN 100: "PWM6" - PIN 101: "PWM7" - PIN 102: "GPIO_E" - -Valid values for function are: - "emmc", "eth", "i2c", "i2s", "ir", "led", "flash", "pcie", - "pmic", "pwm", "sd", "spi", "tdm", "uart", "watchdog" - -Valid values for groups are: -additional data is put followingly with valid value allowing us to know which -applicable function and which relevant pins (in pin#) are able applied for that -group. - - Valid value function pins (in pin#) - ------------------------------------------------------------------------- - "emmc" "emmc" 40, 41, 42, 43, 44, 45, - 47, 48, 49, 50 - "emmc_rst" "emmc" 37 - "esw" "eth" 51, 52, 53, 54, 55, 56, - 57, 58, 59, 60, 61, 62, - 63, 64, 65, 66, 67, 68, - 69, 70 - "esw_p0_p1" "eth" 51, 52, 53, 54, 55, 56, - 57, 58 - "esw_p2_p3_p4" "eth" 59, 60, 61, 62, 63, 64, - 65, 66, 67, 68, 69, 70 - "rgmii_via_esw" "eth" 59, 60, 61, 62, 63, 64, - 65, 66, 67, 68, 69, 70 - "rgmii_via_gmac1" "eth" 59, 60, 61, 62, 63, 64, - 65, 66, 67, 68, 69, 70 - "rgmii_via_gmac2" "eth" 25, 26, 27, 28, 29, 30, - 31, 32, 33, 34, 35, 36 - "mdc_mdio" "eth" 23, 24 - "i2c0" "i2c" 14, 15 - "i2c1_0" "i2c" 55, 56 - "i2c1_1" "i2c" 73, 74 - "i2c1_2" "i2c" 87, 88 - "i2c2_0" "i2c" 57, 58 - "i2c2_1" "i2c" 75, 76 - "i2c2_2" "i2c" 89, 90 - "i2s_in_mclk_bclk_ws" "i2s" 3, 4, 5 - "i2s1_in_data" "i2s" 1 - "i2s2_in_data" "i2s" 16 - "i2s3_in_data" "i2s" 17 - "i2s4_in_data" "i2s" 18 - "i2s_out_mclk_bclk_ws" "i2s" 3, 4, 5 - "i2s1_out_data" "i2s" 2 - "i2s2_out_data" "i2s" 19 - "i2s3_out_data" "i2s" 20 - "i2s4_out_data" "i2s" 21 - "ir_0_tx" "ir" 16 - "ir_1_tx" "ir" 59 - "ir_2_tx" "ir" 99 - "ir_0_rx" "ir" 17 - "ir_1_rx" "ir" 60 - "ir_2_rx" "ir" 100 - "ephy_leds" "led" 86, 91, 92, 93, 94 - "ephy0_led" "led" 86 - "ephy1_led" "led" 91 - "ephy2_led" "led" 92 - "ephy3_led" "led" 93 - "ephy4_led" "led" 94 - "wled" "led" 85 - "par_nand" "flash" 37, 38, 39, 40, 41, 42, - 43, 44, 45, 46, 47, 48, - 49, 50 - "snfi" "flash" 8, 9, 10, 11, 12, 13 - "spi_nor" "flash" 8, 9, 10, 11, 12, 13 - "pcie0_0_waken" "pcie" 14 - "pcie0_1_waken" "pcie" 79 - "pcie1_0_waken" "pcie" 14 - "pcie0_0_clkreq" "pcie" 15 - "pcie0_1_clkreq" "pcie" 80 - "pcie1_0_clkreq" "pcie" 15 - "pcie0_pad_perst" "pcie" 83 - "pcie1_pad_perst" "pcie" 84 - "pmic_bus" "pmic" 71, 72 - "pwm_ch1_0" "pwm" 51 - "pwm_ch1_1" "pwm" 73 - "pwm_ch1_2" "pwm" 95 - "pwm_ch2_0" "pwm" 52 - "pwm_ch2_1" "pwm" 74 - "pwm_ch2_2" "pwm" 96 - "pwm_ch3_0" "pwm" 53 - "pwm_ch3_1" "pwm" 75 - "pwm_ch3_2" "pwm" 97 - "pwm_ch4_0" "pwm" 54 - "pwm_ch4_1" "pwm" 67 - "pwm_ch4_2" "pwm" 76 - "pwm_ch4_3" "pwm" 98 - "pwm_ch5_0" "pwm" 68 - "pwm_ch5_1" "pwm" 77 - "pwm_ch5_2" "pwm" 99 - "pwm_ch6_0" "pwm" 69 - "pwm_ch6_1" "pwm" 78 - "pwm_ch6_2" "pwm" 81 - "pwm_ch6_3" "pwm" 100 - "pwm_ch7_0" "pwm" 70 - "pwm_ch7_1" "pwm" 82 - "pwm_ch7_2" "pwm" 101 - "sd_0" "sd" 16, 17, 18, 19, 20, 21 - "sd_1" "sd" 25, 26, 27, 28, 29, 30 - "spic0_0" "spi" 63, 64, 65, 66 - "spic0_1" "spi" 79, 80, 81, 82 - "spic1_0" "spi" 67, 68, 69, 70 - "spic1_1" "spi" 73, 74, 75, 76 - "spic2_0_wp_hold" "spi" 8, 9 - "spic2_0" "spi" 10, 11, 12, 13 - "tdm_0_out_mclk_bclk_ws" "tdm" 8, 9, 10 - "tdm_0_in_mclk_bclk_ws" "tdm" 11, 12, 13 - "tdm_0_out_data" "tdm" 20 - "tdm_0_in_data" "tdm" 21 - "tdm_1_out_mclk_bclk_ws" "tdm" 57, 58, 59 - "tdm_1_in_mclk_bclk_ws" "tdm" 60, 61, 62 - "tdm_1_out_data" "tdm" 55 - "tdm_1_in_data" "tdm" 56 - "uart0_0_tx_rx" "uart" 6, 7 - "uart1_0_tx_rx" "uart" 55, 56 - "uart1_0_rts_cts" "uart" 57, 58 - "uart1_1_tx_rx" "uart" 73, 74 - "uart1_1_rts_cts" "uart" 75, 76 - "uart2_0_tx_rx" "uart" 3, 4 - "uart2_0_rts_cts" "uart" 1, 2 - "uart2_1_tx_rx" "uart" 51, 52 - "uart2_1_rts_cts" "uart" 53, 54 - "uart2_2_tx_rx" "uart" 59, 60 - "uart2_2_rts_cts" "uart" 61, 62 - "uart2_3_tx_rx" "uart" 95, 96 - "uart3_0_tx_rx" "uart" 57, 58 - "uart3_1_tx_rx" "uart" 81, 82 - "uart3_1_rts_cts" "uart" 79, 80 - "uart4_0_tx_rx" "uart" 61, 62 - "uart4_1_tx_rx" "uart" 91, 92 - "uart4_1_rts_cts" "uart" 93, 94 - "uart4_2_tx_rx" "uart" 97, 98 - "uart4_2_rts_cts" "uart" 95, 96 - "watchdog" "watchdog" 78 - - -== Valid values for pins, function and groups on MT7629 == - - Pin #: Valid values for pins - ----------------------------- - PIN 0: "TOP_5G_CLK" - PIN 1: "TOP_5G_DATA" - PIN 2: "WF0_5G_HB0" - PIN 3: "WF0_5G_HB1" - PIN 4: "WF0_5G_HB2" - PIN 5: "WF0_5G_HB3" - PIN 6: "WF0_5G_HB4" - PIN 7: "WF0_5G_HB5" - PIN 8: "WF0_5G_HB6" - PIN 9: "XO_REQ" - PIN 10: "TOP_RST_N" - PIN 11: "SYS_WATCHDOG" - PIN 12: "EPHY_LED0_N_JTDO" - PIN 13: "EPHY_LED1_N_JTDI" - PIN 14: "EPHY_LED2_N_JTMS" - PIN 15: "EPHY_LED3_N_JTCLK" - PIN 16: "EPHY_LED4_N_JTRST_N" - PIN 17: "WF2G_LED_N" - PIN 18: "WF5G_LED_N" - PIN 19: "I2C_SDA" - PIN 20: "I2C_SCL" - PIN 21: "GPIO_9" - PIN 22: "GPIO_10" - PIN 23: "GPIO_11" - PIN 24: "GPIO_12" - PIN 25: "UART1_TXD" - PIN 26: "UART1_RXD" - PIN 27: "UART1_CTS" - PIN 28: "UART1_RTS" - PIN 29: "UART2_TXD" - PIN 30: "UART2_RXD" - PIN 31: "UART2_CTS" - PIN 32: "UART2_RTS" - PIN 33: "MDI_TP_P1" - PIN 34: "MDI_TN_P1" - PIN 35: "MDI_RP_P1" - PIN 36: "MDI_RN_P1" - PIN 37: "MDI_RP_P2" - PIN 38: "MDI_RN_P2" - PIN 39: "MDI_TP_P2" - PIN 40: "MDI_TN_P2" - PIN 41: "MDI_TP_P3" - PIN 42: "MDI_TN_P3" - PIN 43: "MDI_RP_P3" - PIN 44: "MDI_RN_P3" - PIN 45: "MDI_RP_P4" - PIN 46: "MDI_RN_P4" - PIN 47: "MDI_TP_P4" - PIN 48: "MDI_TN_P4" - PIN 49: "SMI_MDC" - PIN 50: "SMI_MDIO" - PIN 51: "PCIE_PERESET_N" - PIN 52: "PWM_0" - PIN 53: "GPIO_0" - PIN 54: "GPIO_1" - PIN 55: "GPIO_2" - PIN 56: "GPIO_3" - PIN 57: "GPIO_4" - PIN 58: "GPIO_5" - PIN 59: "GPIO_6" - PIN 60: "GPIO_7" - PIN 61: "GPIO_8" - PIN 62: "SPI_CLK" - PIN 63: "SPI_CS" - PIN 64: "SPI_MOSI" - PIN 65: "SPI_MISO" - PIN 66: "SPI_WP" - PIN 67: "SPI_HOLD" - PIN 68: "UART0_TXD" - PIN 69: "UART0_RXD" - PIN 70: "TOP_2G_CLK" - PIN 71: "TOP_2G_DATA" - PIN 72: "WF0_2G_HB0" - PIN 73: "WF0_2G_HB1" - PIN 74: "WF0_2G_HB2" - PIN 75: "WF0_2G_HB3" - PIN 76: "WF0_2G_HB4" - PIN 77: "WF0_2G_HB5" - PIN 78: "WF0_2G_HB6" - -Valid values for function are: - "eth", "i2c", "led", "flash", "pcie", "pwm", "spi", "uart", - "watchdog", "wifi" - -Valid values for groups are: - Valid value function pins (in pin#) - ---------------------------------------------------------------- - "mdc_mdio" "eth" 23, 24 - "i2c_0" "i2c" 19, 20 - "i2c_1" "i2c" 53, 54 - "ephy_leds" "led" 12, 13, 14, 15, 16, - 17, 18 - "ephy0_led" "led" 12 - "ephy1_led" "led" 13 - "ephy2_led" "led" 14 - "ephy3_led" "led" 15 - "ephy4_led" "led" 16 - "wf2g_led" "led" 17 - "wf5g_led" "led" 18 - "snfi" "flash" 62, 63, 64, 65, 66, 67 - "spi_nor" "flash" 62, 63, 64, 65, 66, 67 - "pcie_pereset" "pcie" 51 - "pcie_wake" "pcie" 55 - "pcie_clkreq" "pcie" 56 - "pwm_0" "pwm" 52 - "pwm_1" "pwm" 61 - "spi_0" "spi" 21, 22, 23, 24 - "spi_1" "spi" 62, 63, 64, 65 - "spi_wp" "spi" 66 - "spi_hold" "spi" 67 - "uart0_txd_rxd" "uart" 68, 69 - "uart1_0_txd_rxd" "uart" 25, 26 - "uart1_0_cts_rts" "uart" 27, 28 - "uart1_1_txd_rxd" "uart" 53, 54 - "uart1_1_cts_rts" "uart" 55, 56 - "uart2_0_txd_rxd" "uart" 29, 30 - "uart2_0_cts_rts" "uart" 31, 32 - "uart2_1_txd_rxd" "uart" 57, 58 - "uart2_1_cts_rts" "uart" 59, 60 - "watchdog" "watchdog" 11 - "wf0_2g" "wifi" 70, 71, 72, 73, 74, - 75, 76, 77, 78 - "wf0_5g" "wifi" 0, 1, 2, 3, 4, 5, 6, - 7, 8, 9, 10 - -Example: - - pio: pinctrl@10211000 { - compatible = "mediatek,mt7622-pinctrl"; - reg = <0 0x10211000 0 0x1000>; - gpio-controller; - #gpio-cells = <2>; - - pinctrl_eth_default: eth-default { - mux-mdio { - groups = "mdc_mdio"; - function = "eth"; - drive-strength = <12>; - }; - - mux-gmac2 { - groups = "gmac2"; - function = "eth"; - drive-strength = <12>; - }; - - mux-esw { - groups = "esw"; - function = "eth"; - drive-strength = <8>; - }; - - conf-mdio { - pins = "MDC"; - bias-pull-up; - }; - }; - }; diff --git a/Documentation/devicetree/bindings/pinctrl/pinctrl-mt8183.txt b/Documentation/devicetree/bindings/pinctrl/pinctrl-mt8183.txt deleted file mode 100644 index eccbe3f55d3f..000000000000 --- a/Documentation/devicetree/bindings/pinctrl/pinctrl-mt8183.txt +++ /dev/null @@ -1,132 +0,0 @@ -* Mediatek MT8183 Pin Controller - -The Mediatek's Pin controller is used to control SoC pins. - -Required properties: -- compatible: value should be one of the following. - "mediatek,mt8183-pinctrl", compatible with mt8183 pinctrl. -- gpio-controller : Marks the device node as a gpio controller. -- #gpio-cells: number of cells in GPIO specifier. Since the generic GPIO - binding is used, the amount of cells must be specified as 2. See the below - mentioned gpio binding representation for description of particular cells. -- gpio-ranges : gpio valid number range. -- reg: physical address base for gpio base registers. There are 10 GPIO - physical address base in mt8183. - -Optional properties: -- reg-names: gpio base register names. There are 10 gpio base register - names in mt8183. They are "iocfg0", "iocfg1", "iocfg2", "iocfg3", "iocfg4", - "iocfg5", "iocfg6", "iocfg7", "iocfg8", "eint". -- interrupt-controller: Marks the device node as an interrupt controller -- #interrupt-cells: Should be two. -- interrupts : The interrupt outputs to sysirq. - -Please refer to pinctrl-bindings.txt in this directory for details of the -common pinctrl bindings used by client devices. - -Subnode format -A pinctrl node should contain at least one subnodes representing the -pinctrl groups available on the machine. Each subnode will list the -pins it needs, and how they should be configured, with regard to muxer -configuration, pullups, drive strength, input enable/disable and input schmitt. - - node { - pinmux = <PIN_NUMBER_PINMUX>; - GENERIC_PINCONFIG; - }; - -Required properties: -- pinmux: integer array, represents gpio pin number and mux setting. - Supported pin number and mux varies for different SoCs, and are defined - as macros in boot/dts/<soc>-pinfunc.h directly. - -Optional properties: -- GENERIC_PINCONFIG: is the generic pinconfig options to use, bias-disable, - bias-pull-down, bias-pull-up, input-enable, input-disable, output-low, - output-high, input-schmitt-enable, input-schmitt-disable - and drive-strength are valid. - - Some special pins have extra pull up strength, there are R0 and R1 pull-up - resistors available, but for user, it's only need to set R1R0 as 00, 01, - 10 or 11. So It needs config "mediatek,pull-up-adv" or - "mediatek,pull-down-adv" to support arguments for those special pins. - Valid arguments are from 0 to 3. - - mediatek,tdsel: An integer describing the steps for output level shifter - duty cycle when asserted (high pulse width adjustment). Valid arguments - are from 0 to 15. - mediatek,rdsel: An integer describing the steps for input level shifter - duty cycle when asserted (high pulse width adjustment). Valid arguments - are from 0 to 63. - - When config drive-strength, it can support some arguments, such as - MTK_DRIVE_4mA, MTK_DRIVE_6mA, etc. See dt-bindings/pinctrl/mt65xx.h. - It can only support 2/4/6/8/10/12/14/16mA in mt8183. - For I2C pins, there are existing generic driving setup and the specific - driving setup. I2C pins can only support 2/4/6/8/10/12/14/16mA driving - adjustment in generic driving setup. But in specific driving setup, - they can support 0.125/0.25/0.5/1mA adjustment. If we enable specific - driving setup for I2C pins, the existing generic driving setup will be - disabled. For some special features, we need the I2C pins specific - driving setup. The specific driving setup is controlled by E1E0EN. - So we need add extra vendor driving preperty instead of - the generic driving property. - We can add "mediatek,drive-strength-adv = <XXX>;" to describe the specific - driving setup property. "XXX" means the value of E1E0EN. EN is 0 or 1. - It is used to enable or disable the specific driving setup. - E1E0 is used to describe the detail strength specification of the I2C pin. - When E1=0/E0=0, the strength is 0.125mA. - When E1=0/E0=1, the strength is 0.25mA. - When E1=1/E0=0, the strength is 0.5mA. - When E1=1/E0=1, the strength is 1mA. - So the valid arguments of "mediatek,drive-strength-adv" are from 0 to 7. - -Examples: - -#include "mt8183-pinfunc.h" - -... -{ - pio: pinctrl@10005000 { - compatible = "mediatek,mt8183-pinctrl"; - reg = <0 0x10005000 0 0x1000>, - <0 0x11f20000 0 0x1000>, - <0 0x11e80000 0 0x1000>, - <0 0x11e70000 0 0x1000>, - <0 0x11e90000 0 0x1000>, - <0 0x11d30000 0 0x1000>, - <0 0x11d20000 0 0x1000>, - <0 0x11c50000 0 0x1000>, - <0 0x11f30000 0 0x1000>, - <0 0x1000b000 0 0x1000>; - reg-names = "iocfg0", "iocfg1", "iocfg2", - "iocfg3", "iocfg4", "iocfg5", - "iocfg6", "iocfg7", "iocfg8", - "eint"; - gpio-controller; - #gpio-cells = <2>; - gpio-ranges = <&pio 0 0 192>; - interrupt-controller; - interrupts = <GIC_SPI 177 IRQ_TYPE_LEVEL_HIGH>; - #interrupt-cells = <2>; - - i2c0_pins_a: i2c0 { - pins1 { - pinmux = <PINMUX_GPIO48__FUNC_SCL5>, - <PINMUX_GPIO49__FUNC_SDA5>; - mediatek,pull-up-adv = <3>; - mediatek,drive-strength-adv = <7>; - }; - }; - - i2c1_pins_a: i2c1 { - pins { - pinmux = <PINMUX_GPIO50__FUNC_SCL3>, - <PINMUX_GPIO51__FUNC_SDA3>; - mediatek,pull-down-adv = <2>; - mediatek,drive-strength-adv = <4>; - }; - }; - ... - }; -}; diff --git a/Documentation/devicetree/bindings/pinctrl/pinctrl-mt8195.yaml b/Documentation/devicetree/bindings/pinctrl/pinctrl-mt8195.yaml index 2f12ec59eee5..e17a399e0904 100644 --- a/Documentation/devicetree/bindings/pinctrl/pinctrl-mt8195.yaml +++ b/Documentation/devicetree/bindings/pinctrl/pinctrl-mt8195.yaml @@ -80,10 +80,7 @@ patternProperties: as macros in dt-bindings/pinctrl/<soc>-pinfunc.h directly. drive-strength: - description: | - It can support some arguments which is from 0 to 7. It can only support - 2/4/6/8/10/12/14/16mA in mt8195. - enum: [0, 1, 2, 3, 4, 5, 6, 7] + enum: [2, 4, 6, 8, 10, 12, 14, 16] bias-pull-down: true diff --git a/Documentation/devicetree/bindings/pinctrl/qcom,mdm9607-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/qcom,mdm9607-pinctrl.yaml new file mode 100644 index 000000000000..3b02dc6626ed --- /dev/null +++ b/Documentation/devicetree/bindings/pinctrl/qcom,mdm9607-pinctrl.yaml @@ -0,0 +1,133 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/pinctrl/qcom,mdm9607-pinctrl.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Qualcomm Technologies, Inc. MDM9607 TLMM block + +maintainers: + - Konrad Dybcio <konrad.dybcio@somainline.org> + +description: | + This binding describes the Top Level Mode Multiplexer block found in the + MDM9607 platform. + +allOf: + - $ref: /schemas/pinctrl/qcom,tlmm-common.yaml# + +properties: + compatible: + const: qcom,mdm9607-tlmm + + reg: + maxItems: 1 + + interrupts: true + interrupt-controller: true + '#interrupt-cells': true + gpio-controller: true + gpio-reserved-ranges: true + '#gpio-cells': true + gpio-ranges: true + wakeup-parent: true + +required: + - compatible + - reg + +additionalProperties: false + +patternProperties: + '-state$': + oneOf: + - $ref: "#/$defs/qcom-mdm9607-tlmm-state" + - patternProperties: + ".*": + $ref: "#/$defs/qcom-mdm9607-tlmm-state" + +'$defs': + qcom-mdm9607-tlmm-state: + type: object + description: + Pinctrl node's client devices use subnodes for desired pin configuration. + Client device subnodes use below standard properties. + $ref: "qcom,tlmm-common.yaml#/$defs/qcom-tlmm-state" + + properties: + pins: + description: + List of gpio pins affected by the properties specified in this + subnode. + items: + oneOf: + - pattern: "^gpio([1-9]|[1-7][0-9]|80)$" + - enum: [ sdc1_clk, sdc1_cmd, sdc1_data, sdc2_clk, sdc2_cmd, + sdc2_data, qdsd_cmd, qdsd_data0, qdsd_data1, qdsd_data2, + qdsd_data3 ] + minItems: 1 + maxItems: 16 + + function: + description: + Specify the alternative function to be configured for the specified + pins. + + enum: [ adsp_ext, atest_bbrx0, atest_bbrx1, atest_char, atest_char0, + atest_char1, atest_char2, atest_char3, + atest_combodac_to_gpio_native, atest_gpsadc_dtest0_native, + atest_gpsadc_dtest1_native, atest_tsens, backlight_en_b, + bimc_dte0, bimc_dte1, blsp1_spi, blsp2_spi, blsp3_spi, + blsp_i2c1, blsp_i2c2, blsp_i2c3, blsp_i2c4, blsp_i2c5, + blsp_i2c6, blsp_spi1, blsp_spi2, blsp_spi3, blsp_spi4, + blsp_spi5, blsp_spi6, blsp_uart1, blsp_uart2, blsp_uart3, + blsp_uart4, blsp_uart5, blsp_uart6, blsp_uim1, blsp_uim2, + codec_int, codec_rst, coex_uart, cri_trng, cri_trng0, + cri_trng1, dbg_out, ebi0_wrcdc, ebi2_a, ebi2_a_d_8_b, + ebi2_lcd, ebi2_lcd_cs_n_b, ebi2_lcd_te_b, eth_irq, eth_rst, + gcc_gp1_clk_a, gcc_gp1_clk_b, gcc_gp2_clk_a, gcc_gp2_clk_b, + gcc_gp3_clk_a, gcc_gp3_clk_b, gcc_plltest, gcc_tlmm, gmac_mdio, + gpio, gsm0_tx, lcd_rst, ldo_en, ldo_update, m_voc, modem_tsync, + nav_ptp_pps_in_a, nav_ptp_pps_in_b, nav_tsync_out_a, + nav_tsync_out_b, pa_indicator, pbs0, pbs1, pbs2, + pri_mi2s_data0_a, pri_mi2s_data1_a, pri_mi2s_mclk_a, + pri_mi2s_sck_a, pri_mi2s_ws_a, prng_rosc, ptp_pps_out_a, + ptp_pps_out_b, pwr_crypto_enabled_a, pwr_crypto_enabled_b, + pwr_modem_enabled_a, pwr_modem_enabled_b, pwr_nav_enabled_a, + pwr_nav_enabled_b, qdss_cti_trig_in_a0, qdss_cti_trig_in_a1, + qdss_cti_trig_in_b0, qdss_cti_trig_in_b1, qdss_cti_trig_out_a0, + qdss_cti_trig_out_a1, qdss_cti_trig_out_b0, qdss_cti_trig_out_b1, + qdss_traceclk_a, qdss_traceclk_b, qdss_tracectl_a, + qdss_tracectl_b, qdss_tracedata_a, qdss_tracedata_b, rcm_marker1, + rcm_marker2, sd_write, sec_mi2s, sensor_en, sensor_int2, + sensor_int3, sensor_rst, ssbi1, ssbi2, touch_rst, ts_int, + uim1_clk, uim1_data, uim1_present, uim1_reset, uim2_clk, + uim2_data, uim2_present, uim2_reset, uim_batt, wlan_en1, ] + + bias-disable: true + bias-pull-down: true + bias-pull-up: true + drive-strength: true + input-enable: true + output-high: true + output-low: true + + required: + - pins + - function + + additionalProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/arm-gic.h> + tlmm: pinctrl@1000000 { + compatible = "qcom,mdm9607-tlmm"; + reg = <0x01000000 0x300000>; + interrupts = <GIC_SPI 208 IRQ_TYPE_LEVEL_HIGH>; + gpio-controller; + gpio-ranges = <&msmgpio 0 0 80>; + #gpio-cells = <2>; + interrupt-controller; + #interrupt-cells = <2>; + }; diff --git a/Documentation/devicetree/bindings/pinctrl/qcom,pmic-gpio.txt b/Documentation/devicetree/bindings/pinctrl/qcom,pmic-gpio.txt deleted file mode 100644 index 161216daf463..000000000000 --- a/Documentation/devicetree/bindings/pinctrl/qcom,pmic-gpio.txt +++ /dev/null @@ -1,288 +0,0 @@ -Qualcomm PMIC GPIO block - -This binding describes the GPIO block(s) found in the 8xxx series of -PMIC's from Qualcomm. - -- compatible: - Usage: required - Value type: <string> - Definition: must be one of: - "qcom,pm8005-gpio" - "qcom,pm8018-gpio" - "qcom,pm8038-gpio" - "qcom,pm8058-gpio" - "qcom,pm8916-gpio" - "qcom,pm8917-gpio" - "qcom,pm8921-gpio" - "qcom,pm8941-gpio" - "qcom,pm8950-gpio" - "qcom,pm8994-gpio" - "qcom,pm8998-gpio" - "qcom,pma8084-gpio" - "qcom,pmi8950-gpio" - "qcom,pmi8994-gpio" - "qcom,pmi8998-gpio" - "qcom,pms405-gpio" - "qcom,pm660-gpio" - "qcom,pm660l-gpio" - "qcom,pm8150-gpio" - "qcom,pm8150b-gpio" - "qcom,pm8350-gpio" - "qcom,pm8350b-gpio" - "qcom,pm8350c-gpio" - "qcom,pmk8350-gpio" - "qcom,pm7325-gpio" - "qcom,pmr735a-gpio" - "qcom,pmr735b-gpio" - "qcom,pm6150-gpio" - "qcom,pm6150l-gpio" - "qcom,pm8008-gpio" - "qcom,pmx55-gpio" - - And must contain either "qcom,spmi-gpio" or "qcom,ssbi-gpio" - if the device is on an spmi bus or an ssbi bus respectively - -- reg: - Usage: required - Value type: <prop-encoded-array> - Definition: Register base of the GPIO block and length. - -- interrupts: - Usage: required - Value type: <prop-encoded-array> - Definition: Must contain an array of encoded interrupt specifiers for - each available GPIO - -- gpio-controller: - Usage: required - Value type: <none> - Definition: Mark the device node as a GPIO controller - -- #gpio-cells: - Usage: required - Value type: <u32> - Definition: Must be 2; - the first cell will be used to define gpio number and the - second denotes the flags for this gpio - -Please refer to ../gpio/gpio.txt and ../interrupt-controller/interrupts.txt for -a general description of GPIO and interrupt bindings. - -Please refer to pinctrl-bindings.txt in this directory for details of the -common pinctrl bindings used by client devices, including the meaning of the -phrase "pin configuration node". - -The pin configuration nodes act as a container for an arbitrary number of -subnodes. Each of these subnodes represents some desired configuration for a -pin or a list of pins. This configuration can include the -mux function to select on those pin(s), and various pin configuration -parameters, as listed below. - - -SUBNODES: - -The name of each subnode is not important; all subnodes should be enumerated -and processed purely based on their content. - -Each subnode only affects those parameters that are explicitly listed. In -other words, a subnode that lists a mux function but no pin configuration -parameters implies no information about any pin configuration parameters. -Similarly, a pin subnode that describes a pullup parameter implies no -information about e.g. the mux function. - -The following generic properties as defined in pinctrl-bindings.txt are valid -to specify in a pin configuration subnode: - -- pins: - Usage: required - Value type: <string-array> - Definition: List of gpio pins affected by the properties specified in - this subnode. Valid pins are: - gpio1-gpio4 for pm8005 - gpio1-gpio6 for pm8018 - gpio1-gpio12 for pm8038 - gpio1-gpio40 for pm8058 - gpio1-gpio4 for pm8916 - gpio1-gpio38 for pm8917 - gpio1-gpio44 for pm8921 - gpio1-gpio36 for pm8941 - gpio1-gpio8 for pm8950 (hole on gpio3) - gpio1-gpio22 for pm8994 - gpio1-gpio26 for pm8998 - gpio1-gpio22 for pma8084 - gpio1-gpio2 for pmi8950 - gpio1-gpio10 for pmi8994 - gpio1-gpio12 for pms405 (holes on gpio1, gpio9 and gpio10) - gpio1-gpio10 for pm8150 (holes on gpio2, gpio5, gpio7 - and gpio8) - gpio1-gpio12 for pm8150b (holes on gpio3, gpio4, gpio7) - gpio1-gpio12 for pm8150l (hole on gpio7) - gpio1-gpio10 for pm8350 - gpio1-gpio8 for pm8350b - gpio1-gpio9 for pm8350c - gpio1-gpio4 for pmk8350 - gpio1-gpio10 for pm7325 - gpio1-gpio4 for pmr735a - gpio1-gpio4 for pmr735b - gpio1-gpio10 for pm6150 - gpio1-gpio12 for pm6150l - gpio1-gpio2 for pm8008 - gpio1-gpio11 for pmx55 (holes on gpio3, gpio7, gpio10 - and gpio11) - -- function: - Usage: required - Value type: <string> - Definition: Specify the alternative function to be configured for the - specified pins. Valid values are: - "normal", - "paired", - "func1", - "func2", - "dtest1", - "dtest2", - "dtest3", - "dtest4", - And following values are supported by LV/MV GPIO subtypes: - "func3", - "func4" - -- bias-disable: - Usage: optional - Value type: <none> - Definition: The specified pins should be configured as no pull. - -- bias-pull-down: - Usage: optional - Value type: <none> - Definition: The specified pins should be configured as pull down. - -- bias-pull-up: - Usage: optional - Value type: <empty> - Definition: The specified pins should be configured as pull up. - -- qcom,pull-up-strength: - Usage: optional - Value type: <u32> - Definition: Specifies the strength to use for pull up, if selected. - Valid values are; as defined in - <dt-bindings/pinctrl/qcom,pmic-gpio.h>: - 1: 30uA (PMIC_GPIO_PULL_UP_30) - 2: 1.5uA (PMIC_GPIO_PULL_UP_1P5) - 3: 31.5uA (PMIC_GPIO_PULL_UP_31P5) - 4: 1.5uA + 30uA boost (PMIC_GPIO_PULL_UP_1P5_30) - If this property is omitted 30uA strength will be used if - pull up is selected - -- bias-high-impedance: - Usage: optional - Value type: <none> - Definition: The specified pins will put in high-Z mode and disabled. - -- input-enable: - Usage: optional - Value type: <none> - Definition: The specified pins are put in input mode. - -- output-high: - Usage: optional - Value type: <none> - Definition: The specified pins are configured in output mode, driven - high. - -- output-low: - Usage: optional - Value type: <none> - Definition: The specified pins are configured in output mode, driven - low. - -- power-source: - Usage: optional - Value type: <u32> - Definition: Selects the power source for the specified pins. Valid - power sources are defined per chip in - <dt-bindings/pinctrl/qcom,pmic-gpio.h> - -- qcom,drive-strength: - Usage: optional - Value type: <u32> - Definition: Selects the drive strength for the specified pins. Value - drive strengths are: - 0: no (PMIC_GPIO_STRENGTH_NO) - 1: high (PMIC_GPIO_STRENGTH_HIGH) 0.9mA @ 1.8V - 1.9mA @ 2.6V - 2: medium (PMIC_GPIO_STRENGTH_MED) 0.6mA @ 1.8V - 1.25mA @ 2.6V - 3: low (PMIC_GPIO_STRENGTH_LOW) 0.15mA @ 1.8V - 0.3mA @ 2.6V - as defined in <dt-bindings/pinctrl/qcom,pmic-gpio.h> - -- drive-push-pull: - Usage: optional - Value type: <none> - Definition: The specified pins are configured in push-pull mode. - -- drive-open-drain: - Usage: optional - Value type: <none> - Definition: The specified pins are configured in open-drain mode. - -- drive-open-source: - Usage: optional - Value type: <none> - Definition: The specified pins are configured in open-source mode. - -- qcom,analog-pass: - Usage: optional - Value type: <none> - Definition: The specified pins are configured in analog-pass-through mode. - -- qcom,atest: - Usage: optional - Value type: <u32> - Definition: Selects ATEST rail to route to GPIO when it's configured - in analog-pass-through mode. - Valid values are 1-4 corresponding to ATEST1 to ATEST4. - -- qcom,dtest-buffer: - Usage: optional - Value type: <u32> - Definition: Selects DTEST rail to route to GPIO when it's configured - as digital input. - Valid values are 1-4 corresponding to DTEST1 to DTEST4. - -Example: - - pm8921_gpio: gpio@150 { - compatible = "qcom,pm8921-gpio", "qcom,ssbi-gpio"; - reg = <0x150 0x160>; - interrupts = <192 1>, <193 1>, <194 1>, - <195 1>, <196 1>, <197 1>, - <198 1>, <199 1>, <200 1>, - <201 1>, <202 1>, <203 1>, - <204 1>, <205 1>, <206 1>, - <207 1>, <208 1>, <209 1>, - <210 1>, <211 1>, <212 1>, - <213 1>, <214 1>, <215 1>, - <216 1>, <217 1>, <218 1>, - <219 1>, <220 1>, <221 1>, - <222 1>, <223 1>, <224 1>, - <225 1>, <226 1>, <227 1>, - <228 1>, <229 1>, <230 1>, - <231 1>, <232 1>, <233 1>, - <234 1>, <235 1>; - - gpio-controller; - #gpio-cells = <2>; - - pm8921_gpio_keys: gpio-keys { - volume-keys { - pins = "gpio20", "gpio21"; - function = "normal"; - - input-enable; - bias-pull-up; - drive-push-pull; - qcom,drive-strength = <PMIC_GPIO_STRENGTH_NO>; - power-source = <PM8921_GPIO_S4>; - }; - }; - }; diff --git a/Documentation/devicetree/bindings/pinctrl/qcom,pmic-gpio.yaml b/Documentation/devicetree/bindings/pinctrl/qcom,pmic-gpio.yaml new file mode 100644 index 000000000000..9bd01db37dcd --- /dev/null +++ b/Documentation/devicetree/bindings/pinctrl/qcom,pmic-gpio.yaml @@ -0,0 +1,239 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/pinctrl/qcom,pmic-gpio.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Qualcomm PMIC GPIO block + +maintainers: + - Bjorn Andersson <bjorn.andersson@linaro.org> + +description: + This binding describes the GPIO block(s) found in the 8xxx series of + PMIC's from Qualcomm. + +properties: + compatible: + items: + - enum: + - qcom,pm660-gpio + - qcom,pm660l-gpio + - qcom,pm6150-gpio + - qcom,pm6150l-gpio + - qcom,pm7325-gpio + - qcom,pm8005-gpio + - qcom,pm8008-gpio + - qcom,pm8018-gpio + - qcom,pm8038-gpio + - qcom,pm8058-gpio + - qcom,pm8150-gpio + - qcom,pm8150b-gpio + - qcom,pm8350-gpio + - qcom,pm8350b-gpio + - qcom,pm8350c-gpio + - qcom,pm8916-gpio + - qcom,pm8917-gpio + - qcom,pm8921-gpio + - qcom,pm8941-gpio + - qcom,pm8950-gpio + - qcom,pm8994-gpio + - qcom,pm8998-gpio + - qcom,pma8084-gpio + - qcom,pmi8950-gpio + - qcom,pmi8994-gpio + - qcom,pmi8998-gpio + - qcom,pmk8350-gpio + - qcom,pmr735a-gpio + - qcom,pmr735b-gpio + - qcom,pms405-gpio + - qcom,pmx55-gpio + + - enum: + - qcom,spmi-gpio + - qcom,ssbi-gpio + + reg: + maxItems: 1 + + interrupt-controller: true + + '#interrupt-cells': + const: 2 + + gpio-controller: true + + gpio-ranges: + maxItems: 1 + + '#gpio-cells': + const: 2 + description: + The first cell will be used to define gpio number and the + second denotes the flags for this gpio + +additionalProperties: false + +required: + - compatible + - reg + - gpio-controller + - '#gpio-cells' + - gpio-ranges + - interrupt-controller + +patternProperties: + '-state$': + oneOf: + - $ref: "#/$defs/qcom-pmic-gpio-state" + - patternProperties: + ".*": + $ref: "#/$defs/qcom-pmic-gpio-state" + +$defs: + qcom-pmic-gpio-state: + type: object + allOf: + - $ref: "pinmux-node.yaml" + - $ref: "pincfg-node.yaml" + properties: + pins: + description: + List of gpio pins affected by the properties specified in + this subnode. Valid pins are + - gpio1-gpio10 for pm6150 + - gpio1-gpio12 for pm6150l + - gpio1-gpio10 for pm7325 + - gpio1-gpio4 for pm8005 + - gpio1-gpio2 for pm8008 + - gpio1-gpio6 for pm8018 + - gpio1-gpio12 for pm8038 + - gpio1-gpio40 for pm8058 + - gpio1-gpio10 for pm8150 (holes on gpio2, gpio5, + gpio7 and gpio8) + - gpio1-gpio12 for pm8150b (holes on gpio3, gpio4 + and gpio7) + - gpio1-gpio12 for pm8150l (hole on gpio7) + - gpio1-gpio4 for pm8916 + - gpio1-gpio10 for pm8350 + - gpio1-gpio8 for pm8350b + - gpio1-gpio9 for pm8350c + - gpio1-gpio38 for pm8917 + - gpio1-gpio44 for pm8921 + - gpio1-gpio36 for pm8941 + - gpio1-gpio8 for pm8950 (hole on gpio3) + - gpio1-gpio22 for pm8994 + - gpio1-gpio26 for pm8998 + - gpio1-gpio22 for pma8084 + - gpio1-gpio2 for pmi8950 + - gpio1-gpio10 for pmi8994 + - gpio1-gpio4 for pmk8350 + - gpio1-gpio4 for pmr735a + - gpio1-gpio4 for pmr735b + - gpio1-gpio12 for pms405 (holes on gpio1, gpio9 + and gpio10) + - gpio1-gpio11 for pmx55 (holes on gpio3, gpio7, gpio10 + and gpio11) + + items: + pattern: "^gpio([0-9]+)$" + + function: + items: + - enum: + - normal + - paired + - func1 + - func2 + - dtest1 + - dtest2 + - dtest3 + - dtest4 + - func3 # supported by LV/MV GPIO subtypes + - func4 # supported by LV/MV GPIO subtypes + + bias-disable: true + bias-pull-down: true + bias-pull-up: true + + qcom,pull-up-strength: + $ref: /schemas/types.yaml#/definitions/uint32 + description: + Specifies the strength to use for pull up, if selected. + Valid values are defined in + <dt-bindings/pinctrl/qcom,pmic-gpio.h> + If this property is omitted 30uA strength will be used + if pull up is selected + enum: [0, 1, 2, 3] + + bias-high-impedance: true + input-enable: true + output-high: true + output-low: true + power-source: true + + qcom,drive-strength: + $ref: /schemas/types.yaml#/definitions/uint32 + description: + Selects the drive strength for the specified pins + Valid drive strength values are defined in + <dt-bindings/pinctrl/qcom,pmic-gpio.h> + enum: [0, 1, 2, 3] + + drive-push-pull: true + drive-open-drain: true + drive-open-source: true + + qcom,analog-pass: + $ref: /schemas/types.yaml#/definitions/flag + description: + The specified pins are configured in + analog-pass-through mode. + + qcom,atest: + $ref: /schemas/types.yaml#/definitions/uint32 + description: + Selects ATEST rail to route to GPIO when it's + configured in analog-pass-through mode. + enum: [1, 2, 3, 4] + + qcom,dtest-buffer: + $ref: /schemas/types.yaml#/definitions/uint32 + description: + Selects DTEST rail to route to GPIO when it's + configured as digital input. + enum: [1, 2, 3, 4] + + required: + - pins + - function + + additionalProperties: false + +examples: + - | + #include <dt-bindings/pinctrl/qcom,pmic-gpio.h> + + pm8921_gpio: gpio@150 { + compatible = "qcom,pm8921-gpio", "qcom,ssbi-gpio"; + reg = <0x150 0x160>; + interrupt-controller; + #interrupt-cells = <2>; + gpio-controller; + gpio-ranges = <&pm8921_gpio 0 0 44>; + #gpio-cells = <2>; + + pm8921_gpio_keys: gpio-keys-state { + volume-keys { + pins = "gpio20", "gpio21"; + function = "normal"; + + input-enable; + bias-pull-up; + drive-push-pull; + qcom,drive-strength = <PMIC_GPIO_STRENGTH_NO>; + power-source = <PM8921_GPIO_S4>; + }; + }; + }; +... diff --git a/Documentation/devicetree/bindings/pinctrl/qcom,sm6115-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/qcom,sm6115-pinctrl.yaml new file mode 100644 index 000000000000..8fc06f6a3ef4 --- /dev/null +++ b/Documentation/devicetree/bindings/pinctrl/qcom,sm6115-pinctrl.yaml @@ -0,0 +1,179 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/pinctrl/qcom,sm6115-pinctrl.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Qualcomm Technologies, Inc. SM6115, SM4250 TLMM block + +maintainers: + - Iskren Chernev <iskren.chernev@gmail.com> + +description: + This binding describes the Top Level Mode Multiplexer block found in the + SM4250/6115 platforms. + +properties: + compatible: + const: qcom,sm6115-tlmm + + reg: + minItems: 3 + maxItems: 3 + + reg-names: + items: + - const: west + - const: south + - const: east + + interrupts: + description: Specifies the TLMM summary IRQ + maxItems: 1 + + interrupt-controller: true + + '#interrupt-cells': + description: + Specifies the PIN numbers and Flags, as defined in defined in + include/dt-bindings/interrupt-controller/irq.h + const: 2 + + gpio-controller: true + + '#gpio-cells': + description: Specifying the pin number and flags, as defined in + include/dt-bindings/gpio/gpio.h + const: 2 + + gpio-ranges: + maxItems: 1 + + wakeup-parent: + maxItems: 1 + +#PIN CONFIGURATION NODES +patternProperties: + '-state$': + oneOf: + - $ref: "#/$defs/qcom-sm6115-tlmm-state" + - patternProperties: + ".*": + $ref: "#/$defs/qcom-sm6115-tlmm-state" + +'$defs': + qcom-sm6115-tlmm-state: + type: object + description: + Pinctrl node's client devices use subnodes for desired pin configuration. + Client device subnodes use below standard properties. + $ref: "qcom,tlmm-common.yaml#/$defs/qcom-tlmm-state" + + properties: + pins: + description: + List of gpio pins affected by the properties specified in this + subnode. + items: + oneOf: + - pattern: "^gpio([0-9]|[1-9][0-9]|10[0-9]|11[0-2])$" + - enum: [ sdc1_rclk, sdc1_clk, sdc1_cmd, sdc1_data, + sdc2_clk, sdc2_cmd, sdc2_data, ufs_reset ] + minItems: 1 + maxItems: 36 + + function: + description: + Specify the alternative function to be configured for the specified + pins. + + enum: [ adsp_ext, agera_pll, atest, cam_mclk, cci_async, cci_i2c, + cci_timer, cri_trng, dac_calib, dbg_out, ddr_bist, ddr_pxi0, + ddr_pxi1, ddr_pxi2, ddr_pxi3, gcc_gp1, gcc_gp2, gcc_gp3, gpio, + gp_pdm0, gp_pdm1, gp_pdm2, gsm0_tx, gsm1_tx, jitter_bist, + mdp_vsync, mdp_vsync_out_0, mdp_vsync_out_1, mpm_pwr, mss_lte, + m_voc, nav_gpio, pa_indicator, pbs, pbs_out, phase_flag, + pll_bist, pll_bypassnl, pll_reset, prng_rosc, qdss_cti, + qdss_gpio, qup0, qup1, qup2, qup3, qup4, qup5, sdc1_tb, + sdc2_tb, sd_write, ssbi_wtr1, tgu, tsense_pwm, uim1_clk, + uim1_data, uim1_present, uim1_reset, uim2_clk, uim2_data, + uim2_present, uim2_reset, usb_phy, vfr_1, vsense_trigger, + wlan1_adc0, elan1_adc1 ] + + drive-strength: + enum: [2, 4, 6, 8, 10, 12, 14, 16] + default: 2 + description: + Selects the drive strength for the specified pins, in mA. + + bias-pull-down: true + + bias-pull-up: true + + bias-disable: true + + output-high: true + + output-low: true + + required: + - pins + + additionalProperties: false + +required: + - compatible + - reg + - reg-names + - interrupts + - interrupt-controller + - '#interrupt-cells' + - gpio-controller + - '#gpio-cells' + - gpio-ranges + +additionalProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/arm-gic.h> + tlmm: pinctrl@500000 { + compatible = "qcom,sm6115-tlmm"; + reg = <0x500000 0x400000>, + <0x900000 0x400000>, + <0xd00000 0x400000>; + reg-names = "west", "south", "east"; + interrupts = <GIC_SPI 227 IRQ_TYPE_LEVEL_HIGH>; + gpio-controller; + #gpio-cells = <2>; + interrupt-controller; + #interrupt-cells = <2>; + gpio-ranges = <&tlmm 0 0 114>; + + sdc2_on_state: sdc2-on-state { + clk { + pins = "sdc2_clk"; + bias-disable; + drive-strength = <16>; + }; + + cmd { + pins = "sdc2_cmd"; + bias-pull-up; + drive-strength = <10>; + }; + + data { + pins = "sdc2_data"; + bias-pull-up; + drive-strength = <10>; + }; + + sd-cd { + pins = "gpio88"; + function = "gpio"; + bias-pull-up; + drive-strength = <2>; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/pinctrl/renesas,rzg2l-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/renesas,rzg2l-pinctrl.yaml new file mode 100644 index 000000000000..ef68dabcf4dc --- /dev/null +++ b/Documentation/devicetree/bindings/pinctrl/renesas,rzg2l-pinctrl.yaml @@ -0,0 +1,155 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/pinctrl/renesas,rzg2l-pinctrl.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Renesas RZ/G2L combined Pin and GPIO controller + +maintainers: + - Geert Uytterhoeven <geert+renesas@glider.be> + - Lad Prabhakar <prabhakar.mahadev-lad.rj@bp.renesas.com> + +description: + The Renesas SoCs of the RZ/G2L series feature a combined Pin and GPIO + controller. + Pin multiplexing and GPIO configuration is performed on a per-pin basis. + Each port features up to 8 pins, each of them configurable for GPIO function + (port mode) or in alternate function mode. + Up to 8 different alternate function modes exist for each single pin. + +properties: + compatible: + enum: + - renesas,r9a07g044-pinctrl # RZ/G2{L,LC} + + reg: + maxItems: 1 + + gpio-controller: true + + '#gpio-cells': + const: 2 + description: + The first cell contains the global GPIO port index, constructed using the + RZG2L_GPIO() helper macro in <dt-bindings/pinctrl/rzg2l-pinctrl.h> and the + second cell represents consumer flag as mentioned in ../gpio/gpio.txt + E.g. "RZG2L_GPIO(39, 1)" for P39_1. + + gpio-ranges: + maxItems: 1 + + clocks: + maxItems: 1 + + power-domains: + maxItems: 1 + + resets: + items: + - description: GPIO_RSTN signal + - description: GPIO_PORT_RESETN signal + - description: GPIO_SPARE_RESETN signal + +additionalProperties: + anyOf: + - type: object + allOf: + - $ref: pincfg-node.yaml# + - $ref: pinmux-node.yaml# + + description: + Pin controller client devices use pin configuration subnodes (children + and grandchildren) for desired pin configuration. + Client device subnodes use below standard properties. + + properties: + phandle: true + pinmux: + description: + Values are constructed from GPIO port number, pin number, and + alternate function configuration number using the RZG2L_PORT_PINMUX() + helper macro in <dt-bindings/pinctrl/rzg2l-pinctrl.h>. + pins: true + drive-strength: + enum: [ 2, 4, 8, 12 ] + power-source: + enum: [ 1800, 2500, 3300 ] + slew-rate: true + gpio-hog: true + gpios: true + input-enable: true + output-high: true + output-low: true + line-name: true + + - type: object + properties: + phandle: true + + additionalProperties: + $ref: "#/additionalProperties/anyOf/0" + +required: + - compatible + - reg + - gpio-controller + - '#gpio-cells' + - gpio-ranges + - clocks + - power-domains + - resets + +examples: + - | + #include <dt-bindings/pinctrl/rzg2l-pinctrl.h> + #include <dt-bindings/clock/r9a07g044-cpg.h> + + pinctrl: pinctrl@11030000 { + compatible = "renesas,r9a07g044-pinctrl"; + reg = <0x11030000 0x10000>; + + gpio-controller; + #gpio-cells = <2>; + gpio-ranges = <&pinctrl 0 0 392>; + clocks = <&cpg CPG_MOD R9A07G044_GPIO_HCLK>; + resets = <&cpg R9A07G044_GPIO_RSTN>, + <&cpg R9A07G044_GPIO_PORT_RESETN>, + <&cpg R9A07G044_GPIO_SPARE_RESETN>; + power-domains = <&cpg>; + + scif0_pins: serial0 { + pinmux = <RZG2L_PORT_PINMUX(38, 0, 1)>, /* Tx */ + <RZG2L_PORT_PINMUX(38, 1, 1)>; /* Rx */ + }; + + i2c1_pins: i2c1 { + pins = "RIIC1_SDA", "RIIC1_SCL"; + input-enable; + }; + + sd1-pwr-en-hog { + gpio-hog; + gpios = <RZG2L_GPIO(39, 2) 0>; + output-high; + line-name = "sd1_pwr_en"; + }; + + sdhi1_pins: sd1 { + sd1_mux { + pinmux = <RZG2L_PORT_PINMUX(19, 0, 1)>, /* CD */ + <RZG2L_PORT_PINMUX(19, 1, 1)>; /* WP */ + power-source = <3300>; + }; + + sd1_data { + pins = "SD1_DATA0", "SD1_DATA1", "SD1_DATA2", "SD1_DATA3"; + power-source = <3300>; + }; + + sd1_ctrl { + pins = "SD1_CLK", "SD1_CMD"; + power-source = <3300>; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/pinctrl/samsung-pinctrl.txt b/Documentation/devicetree/bindings/pinctrl/samsung-pinctrl.txt index 38a1416fd2cd..e7a1b1880375 100644 --- a/Documentation/devicetree/bindings/pinctrl/samsung-pinctrl.txt +++ b/Documentation/devicetree/bindings/pinctrl/samsung-pinctrl.txt @@ -22,6 +22,7 @@ Required Properties: - "samsung,exynos5420-pinctrl": for Exynos5420 compatible pin-controller. - "samsung,exynos5433-pinctrl": for Exynos5433 compatible pin-controller. - "samsung,exynos7-pinctrl": for Exynos7 compatible pin-controller. + - "samsung,exynos850-pinctrl": for Exynos850 compatible pin-controller. - reg: Base address of the pin controller hardware module and length of the address space it occupies. diff --git a/Documentation/devicetree/bindings/pinctrl/st,stm32-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/st,stm32-pinctrl.yaml index 72877544ca78..dfee6d38a701 100644 --- a/Documentation/devicetree/bindings/pinctrl/st,stm32-pinctrl.yaml +++ b/Documentation/devicetree/bindings/pinctrl/st,stm32-pinctrl.yaml @@ -24,6 +24,7 @@ properties: - st,stm32f746-pinctrl - st,stm32f769-pinctrl - st,stm32h743-pinctrl + - st,stm32mp135-pinctrl - st,stm32mp157-pinctrl - st,stm32mp157-z-pinctrl diff --git a/Documentation/devicetree/bindings/pinctrl/xlnx,zynq-pinctrl.txt b/Documentation/devicetree/bindings/pinctrl/xlnx,zynq-pinctrl.txt deleted file mode 100644 index f488b0f77406..000000000000 --- a/Documentation/devicetree/bindings/pinctrl/xlnx,zynq-pinctrl.txt +++ /dev/null @@ -1,105 +0,0 @@ - Binding for Xilinx Zynq Pinctrl - -Required properties: -- compatible: "xlnx,zynq-pinctrl" -- syscon: phandle to SLCR -- reg: Offset and length of pinctrl space in SLCR - -Please refer to pinctrl-bindings.txt in this directory for details of the -common pinctrl bindings used by client devices, including the meaning of the -phrase "pin configuration node". - -Zynq's pin configuration nodes act as a container for an arbitrary number of -subnodes. Each of these subnodes represents some desired configuration for a -pin, a group, or a list of pins or groups. This configuration can include the -mux function to select on those pin(s)/group(s), and various pin configuration -parameters, such as pull-up, slew rate, etc. - -Each configuration node can consist of multiple nodes describing the pinmux and -pinconf options. Those nodes can be pinmux nodes or pinconf nodes. - -The name of each subnode is not important; all subnodes should be enumerated -and processed purely based on their content. - -Required properties for pinmux nodes are: - - groups: A list of pinmux groups. - - function: The name of a pinmux function to activate for the specified set - of groups. - -Required properties for configuration nodes: -One of: - - pins: a list of pin names - - groups: A list of pinmux groups. - -The following generic properties as defined in pinctrl-bindings.txt are valid -to specify in a pinmux subnode: - groups, function - -The following generic properties as defined in pinctrl-bindings.txt are valid -to specify in a pinconf subnode: - groups, pins, bias-disable, bias-high-impedance, bias-pull-up, slew-rate, - low-power-disable, low-power-enable - - Valid arguments for 'slew-rate' are '0' and '1' to select between slow and fast - respectively. - - Valid values for groups are: - ethernet0_0_grp, ethernet1_0_grp, mdio0_0_grp, mdio1_0_grp, - qspi0_0_grp, qspi1_0_grp, qspi_fbclk, qspi_cs1_grp, spi0_0_grp - spi0_2_grp, - spi0_X_ssY (X=0..2, Y=0..2), spi1_0_grp - spi1_3_grp, - spi1_X_ssY (X=0..3, Y=0..2), sdio0_0_grp - sdio0_2_grp, - sdio1_0_grp - sdio1_3_grp, sdio0_emio_wp, sdio0_emio_cd, sdio1_emio_wp, - sdio1_emio_cd, smc0_nor, smc0_nor_cs1_grp, smc0_nor_addr25_grp, smc0_nand, - can0_0_grp - can0_10_grp, can1_0_grp - can1_11_grp, uart0_0_grp - uart0_10_grp, - uart1_0_grp - uart1_11_grp, i2c0_0_grp - i2c0_10_grp, i2c1_0_grp - i2c1_10_grp, - ttc0_0_grp - ttc0_2_grp, ttc1_0_grp - ttc1_2_grp, swdt0_0_grp - swdt0_4_grp, - gpio0_0_grp - gpio0_53_grp, usb0_0_grp, usb1_0_grp - - Valid values for pins are: - MIO0 - MIO53 - - Valid values for function are: - ethernet0, ethernet1, mdio0, mdio1, qspi0, qspi1, qspi_fbclk, qspi_cs1, - spi0, spi0_ss, spi1, spi1_ss, sdio0, sdio0_pc, sdio0_cd, sdio0_wp, - sdio1, sdio1_pc, sdio1_cd, sdio1_wp, - smc0_nor, smc0_nor_cs1, smc0_nor_addr25, smc0_nand, can0, can1, uart0, uart1, - i2c0, i2c1, ttc0, ttc1, swdt0, gpio0, usb0, usb1 - -The following driver-specific properties as defined here are valid to specify in -a pin configuration subnode: - - io-standard: Configure the pin to use the selected IO standard according to - this mapping: - 1: LVCMOS18 - 2: LVCMOS25 - 3: LVCMOS33 - 4: HSTL - -Example: - pinctrl0: pinctrl@700 { - compatible = "xlnx,pinctrl-zynq"; - reg = <0x700 0x200>; - syscon = <&slcr>; - - pinctrl_uart1_default: uart1-default { - mux { - groups = "uart1_10_grp"; - function = "uart1"; - }; - - conf { - groups = "uart1_10_grp"; - slew-rate = <0>; - io-standard = <1>; - }; - - conf-rx { - pins = "MIO49"; - bias-high-impedance; - }; - - conf-tx { - pins = "MIO48"; - bias-disable; - }; - }; - }; diff --git a/Documentation/devicetree/bindings/pinctrl/xlnx,zynq-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/xlnx,zynq-pinctrl.yaml new file mode 100644 index 000000000000..ac97dbf6998e --- /dev/null +++ b/Documentation/devicetree/bindings/pinctrl/xlnx,zynq-pinctrl.yaml @@ -0,0 +1,214 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/pinctrl/xlnx,zynq-pinctrl.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Xilinx Zynq Pinctrl + +maintainers: + - Sai Krishna Potthuri <lakshmi.sai.krishna.potthuri@xilinx.com> + +description: | + Please refer to pinctrl-bindings.txt in this directory for details of the + common pinctrl bindings used by client devices, including the meaning of the + phrase "pin configuration node". + + Zynq's pin configuration nodes act as a container for an arbitrary number of + subnodes. Each of these subnodes represents some desired configuration for a + pin, a group, or a list of pins or groups. This configuration can include the + mux function to select on those pin(s)/group(s), and various pin configuration + parameters, such as pull-up, slew rate, etc. + + Each configuration node can consist of multiple nodes describing the pinmux and + pinconf options. Those nodes can be pinmux nodes or pinconf nodes. + + The name of each subnode is not important; all subnodes should be enumerated + and processed purely based on their content. + +properties: + compatible: + const: xlnx,zynq-pinctrl + + reg: + description: Specifies the base address and size of the SLCR space. + maxItems: 1 + + syscon: + description: + phandle to the SLCR. + +patternProperties: + '^(.*-)?(default|gpio)$': + type: object + patternProperties: + '^mux': + type: object + description: + Pinctrl node's client devices use subnodes for pin muxes, + which in turn use below standard properties. + $ref: pinmux-node.yaml# + + properties: + groups: + description: + List of groups to select (either this or "pins" must be + specified), available groups for this subnode. + items: + enum: [ethernet0_0_grp, ethernet1_0_grp, mdio0_0_grp, + mdio1_0_grp, qspi0_0_grp, qspi1_0_grp, qspi_fbclk, + qspi_cs1_grp, spi0_0_grp, spi0_1_grp, spi0_2_grp, + spi0_0_ss0, spi0_0_ss1, spi0_0_ss2, spi0_1_ss0, + spi0_1_ss1, spi0_1_ss2, spi0_2_ss0, spi0_2_ss1, + spi0_2_ss2, spi1_0_grp, spi1_1_grp, spi1_2_grp, + spi1_3_grp, spi1_0_ss0, spi1_0_ss1, spi1_0_ss2, + spi1_1_ss0, spi1_1_ss1, spi1_1_ss2, spi1_2_ss0, + spi1_2_ss1, spi1_2_ss2, spi1_3_ss0, spi1_3_ss1, + spi1_3_ss2, sdio0_0_grp, sdio0_1_grp, sdio0_2_grp, + sdio1_0_grp, sdio1_1_grp, sdio1_2_grp, sdio1_3_grp, + sdio0_emio_wp, sdio0_emio_cd, sdio1_emio_wp, + sdio1_emio_cd, smc0_nor, smc0_nor_cs1_grp, + smc0_nor_addr25_grp, smc0_nand, can0_0_grp, can0_1_grp, + can0_2_grp, can0_3_grp, can0_4_grp, can0_5_grp, + can0_6_grp, can0_7_grp, can0_8_grp, can0_9_grp, + can0_10_grp, can1_0_grp, can1_1_grp, can1_2_grp, + can1_3_grp, can1_4_grp, can1_5_grp, can1_6_grp, + can1_7_grp, can1_8_grp, can1_9_grp, can1_10_grp, + can1_11_grp, uart0_0_grp, uart0_1_grp, uart0_2_grp, + uart0_3_grp, uart0_4_grp, uart0_5_grp, uart0_6_grp, + uart0_7_grp, uart0_8_grp, uart0_9_grp, uart0_10_grp, + uart1_0_grp, uart1_1_grp, uart1_2_grp, uart1_3_grp, + uart1_4_grp, uart1_5_grp, uart1_6_grp, uart1_7_grp, + uart1_8_grp, uart1_9_grp, uart1_10_grp, uart1_11_grp, + i2c0_0_grp, i2c0_1_grp, i2c0_2_grp, i2c0_3_grp, + i2c0_4_grp, i2c0_5_grp, i2c0_6_grp, i2c0_7_grp, + i2c0_8_grp, i2c0_9_grp, i2c0_10_grp, i2c1_0_grp, + i2c1_1_grp, i2c1_2_grp, i2c1_3_grp, i2c1_4_grp, + i2c1_5_grp, i2c1_6_grp, i2c1_7_grp, i2c1_8_grp, + i2c1_9_grp, i2c1_10_grp, ttc0_0_grp, ttc0_1_grp, + ttc0_2_grp, ttc1_0_grp, ttc1_1_grp, ttc1_2_grp, + swdt0_0_grp, swdt0_1_grp, swdt0_2_grp, swdt0_3_grp, + swdt0_4_grp, gpio0_0_grp, gpio0_1_grp, gpio0_2_grp, + gpio0_3_grp, gpio0_4_grp, gpio0_5_grp, gpio0_6_grp, + gpio0_7_grp, gpio0_8_grp, gpio0_9_grp, gpio0_10_grp, + gpio0_11_grp, gpio0_12_grp, gpio0_13_grp, gpio0_14_grp, + gpio0_15_grp, gpio0_16_grp, gpio0_17_grp, gpio0_18_grp, + gpio0_19_grp, gpio0_20_grp, gpio0_21_grp, gpio0_22_grp, + gpio0_23_grp, gpio0_24_grp, gpio0_25_grp, gpio0_26_grp, + gpio0_27_grp, gpio0_28_grp, gpio0_29_grp, gpio0_30_grp, + gpio0_31_grp, gpio0_32_grp, gpio0_33_grp, gpio0_34_grp, + gpio0_35_grp, gpio0_36_grp, gpio0_37_grp, gpio0_38_grp, + gpio0_39_grp, gpio0_40_grp, gpio0_41_grp, gpio0_42_grp, + gpio0_43_grp, gpio0_44_grp, gpio0_45_grp, gpio0_46_grp, + gpio0_47_grp, gpio0_48_grp, gpio0_49_grp, gpio0_50_grp, + gpio0_51_grp, gpio0_52_grp, gpio0_53_grp, usb0_0_grp, + usb1_0_grp] + maxItems: 54 + + function: + description: + Specify the alternative function to be configured for the + given pin groups. + enum: [ethernet0, ethernet1, mdio0, mdio1, qspi0, qspi1, qspi_fbclk, + qspi_cs1, spi0, spi0_ss, spi1, spi1_ss, sdio0, sdio0_pc, + sdio0_cd, sdio0_wp, sdio1, sdio1_pc, sdio1_cd, sdio1_wp, + smc0_nor, smc0_nor_cs1, smc0_nor_addr25, smc0_nand, can0, + can1, uart0, uart1, i2c0, i2c1, ttc0, ttc1, swdt0, gpio0, + usb0, usb1] + + required: + - groups + - function + + additionalProperties: false + + '^conf': + type: object + description: + Pinctrl node's client devices use subnodes for pin configurations, + which in turn use the standard properties below. + $ref: pincfg-node.yaml# + + properties: + groups: + description: + List of pin groups as mentioned above. + + pins: + description: + List of pin names to select in this subnode. + items: + pattern: '^MIO([0-9]|[1-4][0-9]|5[0-3])$' + maxItems: 54 + + bias-pull-up: true + + bias-pull-down: true + + bias-disable: true + + bias-high-impedance: true + + low-power-enable: true + + low-power-disable: true + + slew-rate: + enum: [0, 1] + + power-source: + enum: [1, 2, 3, 4] + + oneOf: + - required: [ groups ] + - required: [ pins ] + + additionalProperties: false + + additionalProperties: false + +required: + - compatible + - reg + - syscon + +additionalProperties: false + +examples: + - | + #include <dt-bindings/pinctrl/pinctrl-zynq.h> + pinctrl0: pinctrl@700 { + compatible = "xlnx,zynq-pinctrl"; + reg = <0x700 0x200>; + syscon = <&slcr>; + + pinctrl_uart1_default: uart1-default { + mux { + groups = "uart1_10_grp"; + function = "uart1"; + }; + + conf { + groups = "uart1_10_grp"; + slew-rate = <0>; + power-source = <IO_STANDARD_LVCMOS18>; + }; + + conf-rx { + pins = "MIO49"; + bias-high-impedance; + }; + + conf-tx { + pins = "MIO48"; + bias-disable; + }; + }; + }; + + uart1 { + pinctrl-names = "default"; + pinctrl-0 = <&pinctrl_uart1_default>; + }; + +... diff --git a/Documentation/devicetree/bindings/power/qcom,rpmpd.yaml b/Documentation/devicetree/bindings/power/qcom,rpmpd.yaml index 4807b560f00d..239f37881cae 100644 --- a/Documentation/devicetree/bindings/power/qcom,rpmpd.yaml +++ b/Documentation/devicetree/bindings/power/qcom,rpmpd.yaml @@ -30,6 +30,7 @@ properties: - qcom,sc8180x-rpmhpd - qcom,sdm845-rpmhpd - qcom,sdx55-rpmhpd + - qcom,sm6115-rpmpd - qcom,sm8150-rpmhpd - qcom,sm8250-rpmhpd - qcom,sm8350-rpmhpd diff --git a/Documentation/devicetree/bindings/power/reset/xlnx,zynqmp-power.txt b/Documentation/devicetree/bindings/power/reset/xlnx,zynqmp-power.txt deleted file mode 100644 index bb529ecf8a57..000000000000 --- a/Documentation/devicetree/bindings/power/reset/xlnx,zynqmp-power.txt +++ /dev/null @@ -1,61 +0,0 @@ --------------------------------------------------------------------- -Device Tree Bindings for the Xilinx Zynq MPSoC Power Management --------------------------------------------------------------------- -The zynqmp-power node describes the power management configurations. -It will control remote suspend/shutdown interfaces. - -Required properties: - - compatible: Must contain: "xlnx,zynqmp-power" - - interrupts: Interrupt specifier - -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 { - compatible = "xlnx,zynqmp-firmware"; - method = "smc"; - - 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/reset/xlnx,zynqmp-power.yaml b/Documentation/devicetree/bindings/power/reset/xlnx,zynqmp-power.yaml new file mode 100644 index 000000000000..68d7c14a7163 --- /dev/null +++ b/Documentation/devicetree/bindings/power/reset/xlnx,zynqmp-power.yaml @@ -0,0 +1,83 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/power/reset/xlnx,zynqmp-power.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Xilinx Zynq MPSoC Power Management Device Tree Bindings + +maintainers: + - Michal Simek <michal.simek@xilinx.com> + +description: | + The zynqmp-power node describes the power management configurations. + It will control remote suspend/shutdown interfaces. + +properties: + compatible: + const: "xlnx,zynqmp-power" + + interrupts: + maxItems: 1 + + mboxes: + description: | + 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. + items: + - description: tx channel + - description: rx channel + + mbox-names: + description: + Name given to channels seen in the 'mboxes' property. + items: + - const: tx + - const: rx + +required: + - compatible + - interrupts + +additionalProperties: false + +examples: + - |+ + + // Example with interrupt method: + + firmware { + zynqmp-firmware { + zynqmp-power { + compatible = "xlnx,zynqmp-power"; + interrupts = <0 35 4>; + }; + }; + }; + + - |+ + + // Example with IPI mailbox method: + + firmware { + zynqmp-firmware { + zynqmp-power { + compatible = "xlnx,zynqmp-power"; + interrupt-parent = <&gic>; + interrupts = <0 35 4>; + mboxes = <&ipi_mailbox_pmu1 0>, + <&ipi_mailbox_pmu1 1>; + mbox-names = "tx", "rx"; + }; + }; + }; +... diff --git a/Documentation/devicetree/bindings/power/rockchip-io-domain.txt b/Documentation/devicetree/bindings/power/rockchip-io-domain.txt deleted file mode 100644 index e66fd4eab71c..000000000000 --- a/Documentation/devicetree/bindings/power/rockchip-io-domain.txt +++ /dev/null @@ -1,135 +0,0 @@ -Rockchip SRAM for IO Voltage Domains: -------------------------------------- - -IO domain voltages on some Rockchip SoCs are variable but need to be -kept in sync between the regulators and the SoC using a special -register. - -A specific example using rk3288: -- If the regulator hooked up to a pin like SDMMC0_VDD is 3.3V then - bit 7 of GRF_IO_VSEL needs to be 0. If the regulator hooked up to - that same pin is 1.8V then bit 7 of GRF_IO_VSEL needs to be 1. - -Said another way, this driver simply handles keeping bits in the SoC's -general register file (GRF) in sync with the actual value of a voltage -hooked up to the pins. - -Note that this driver specifically doesn't include: -- any logic for deciding what voltage we should set regulators to -- any logic for deciding whether regulators (or internal SoC blocks) - should have power or not have power - -If there were some other software that had the smarts of making -decisions about regulators, it would work in conjunction with this -driver. When that other software adjusted a regulator's voltage then -this driver would handle telling the SoC about it. A good example is -vqmmc for SD. In that case the dw_mmc driver simply is told about a -regulator. It changes the regulator between 3.3V and 1.8V at the -right time. This driver notices the change and makes sure that the -SoC is on the same page. - - -Required properties: -- compatible: should be one of: - - "rockchip,px30-io-voltage-domain" for px30 - - "rockchip,px30-pmu-io-voltage-domain" for px30 pmu-domains - - "rockchip,rk3188-io-voltage-domain" for rk3188 - - "rockchip,rk3228-io-voltage-domain" for rk3228 - - "rockchip,rk3288-io-voltage-domain" for rk3288 - - "rockchip,rk3328-io-voltage-domain" for rk3328 - - "rockchip,rk3368-io-voltage-domain" for rk3368 - - "rockchip,rk3368-pmu-io-voltage-domain" for rk3368 pmu-domains - - "rockchip,rk3399-io-voltage-domain" for rk3399 - - "rockchip,rk3399-pmu-io-voltage-domain" for rk3399 pmu-domains - - "rockchip,rv1108-io-voltage-domain" for rv1108 - - "rockchip,rv1108-pmu-io-voltage-domain" for rv1108 pmu-domains - -Deprecated properties: -- rockchip,grf: phandle to the syscon managing the "general register files" - Systems should move the io-domains to a sub-node of the grf simple-mfd. - -You specify supplies using the standard regulator bindings by including -a phandle the relevant regulator. All specified supplies must be able -to report their voltage. The IO Voltage Domain for any non-specified -supplies will be not be touched. - -Possible supplies for PX30: -- vccio6-supply: The supply connected to VCCIO6. -- vccio1-supply: The supply connected to VCCIO1. -- vccio2-supply: The supply connected to VCCIO2. -- vccio3-supply: The supply connected to VCCIO3. -- vccio4-supply: The supply connected to VCCIO4. -- vccio5-supply: The supply connected to VCCIO5. -- vccio-oscgpi-supply: The supply connected to VCCIO_OSCGPI. - -Possible supplies for PX30 pmu-domains: -- pmuio1-supply: The supply connected to PMUIO1. -- pmuio2-supply: The supply connected to PMUIO2. - -Possible supplies for rk3188: -- ap0-supply: The supply connected to AP0_VCC. -- ap1-supply: The supply connected to AP1_VCC. -- cif-supply: The supply connected to CIF_VCC. -- flash-supply: The supply connected to FLASH_VCC. -- lcdc0-supply: The supply connected to LCD0_VCC. -- lcdc1-supply: The supply connected to LCD1_VCC. -- vccio0-supply: The supply connected to VCCIO0. -- vccio1-supply: The supply connected to VCCIO1. - Sometimes also labeled VCCIO1 and VCCIO2. - -Possible supplies for rk3228: -- vccio1-supply: The supply connected to VCCIO1. -- vccio2-supply: The supply connected to VCCIO2. -- vccio3-supply: The supply connected to VCCIO3. -- vccio4-supply: The supply connected to VCCIO4. - -Possible supplies for rk3288: -- audio-supply: The supply connected to APIO4_VDD. -- bb-supply: The supply connected to APIO5_VDD. -- dvp-supply: The supply connected to DVPIO_VDD. -- flash0-supply: The supply connected to FLASH0_VDD. Typically for eMMC -- flash1-supply: The supply connected to FLASH1_VDD. Also known as SDIO1. -- gpio30-supply: The supply connected to APIO1_VDD. -- gpio1830 The supply connected to APIO2_VDD. -- lcdc-supply: The supply connected to LCDC_VDD. -- sdcard-supply: The supply connected to SDMMC0_VDD. -- wifi-supply: The supply connected to APIO3_VDD. Also known as SDIO0. - -Possible supplies for rk3368: -- audio-supply: The supply connected to APIO3_VDD. -- dvp-supply: The supply connected to DVPIO_VDD. -- flash0-supply: The supply connected to FLASH0_VDD. Typically for eMMC -- gpio30-supply: The supply connected to APIO1_VDD. -- gpio1830 The supply connected to APIO4_VDD. -- sdcard-supply: The supply connected to SDMMC0_VDD. -- wifi-supply: The supply connected to APIO2_VDD. Also known as SDIO0. - -Possible supplies for rk3368 pmu-domains: -- pmu-supply: The supply connected to PMUIO_VDD. -- vop-supply: The supply connected to LCDC_VDD. - -Possible supplies for rk3399: -- bt656-supply: The supply connected to APIO2_VDD. -- audio-supply: The supply connected to APIO5_VDD. -- sdmmc-supply: The supply connected to SDMMC0_VDD. -- gpio1830 The supply connected to APIO4_VDD. - -Possible supplies for rk3399 pmu-domains: -- pmu1830-supply:The supply connected to PMUIO2_VDD. - -Example: - - io-domains { - compatible = "rockchip,rk3288-io-voltage-domain"; - rockchip,grf = <&grf>; - - audio-supply = <&vcc18_codec>; - bb-supply = <&vcc33_io>; - dvp-supply = <&vcc_18>; - flash0-supply = <&vcc18_flashio>; - gpio1830-supply = <&vcc33_io>; - gpio30-supply = <&vcc33_pmuio>; - lcdc-supply = <&vcc33_lcd>; - sdcard-supply = <&vccio_sd>; - wifi-supply = <&vcc18_wl>; - }; diff --git a/Documentation/devicetree/bindings/power/rockchip-io-domain.yaml b/Documentation/devicetree/bindings/power/rockchip-io-domain.yaml new file mode 100644 index 000000000000..1727bf108979 --- /dev/null +++ b/Documentation/devicetree/bindings/power/rockchip-io-domain.yaml @@ -0,0 +1,360 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/power/rockchip-io-domain.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Rockchip SRAM for IO Voltage Domains + +maintainers: + - Heiko Stuebner <heiko@sntech.de> + +description: | + IO domain voltages on some Rockchip SoCs are variable but need to be + kept in sync between the regulators and the SoC using a special + register. + + A specific example using rk3288 + If the regulator hooked up to a pin like SDMMC0_VDD is 3.3V then + bit 7 of GRF_IO_VSEL needs to be 0. If the regulator hooked up to + that same pin is 1.8V then bit 7 of GRF_IO_VSEL needs to be 1. + + Said another way, this driver simply handles keeping bits in the SoCs + General Register File (GRF) in sync with the actual value of a voltage + hooked up to the pins. + + Note that this driver specifically does not include + any logic for deciding what voltage we should set regulators to + any logic for deciding whether regulators (or internal SoC blocks) + should have power or not have power + + If there were some other software that had the smarts of making + decisions about regulators, it would work in conjunction with this + driver. When that other software adjusted a regulators voltage then + this driver would handle telling the SoC about it. A good example is + vqmmc for SD. In that case the dw_mmc driver simply is told about a + regulator. It changes the regulator between 3.3V and 1.8V at the + right time. This driver notices the change and makes sure that the + SoC is on the same page. + + You specify supplies using the standard regulator bindings by including + a phandle the relevant regulator. All specified supplies must be able + to report their voltage. The IO Voltage Domain for any non-specified + supplies will be not be touched. + +properties: + compatible: + enum: + - rockchip,px30-io-voltage-domain + - rockchip,px30-pmu-io-voltage-domain + - rockchip,rk3188-io-voltage-domain + - rockchip,rk3228-io-voltage-domain + - rockchip,rk3288-io-voltage-domain + - rockchip,rk3328-io-voltage-domain + - rockchip,rk3368-io-voltage-domain + - rockchip,rk3368-pmu-io-voltage-domain + - rockchip,rk3399-io-voltage-domain + - rockchip,rk3399-pmu-io-voltage-domain + - rockchip,rk3568-pmu-io-voltage-domain + - rockchip,rv1108-io-voltage-domain + - rockchip,rv1108-pmu-io-voltage-domain + +required: + - compatible + +unevaluatedProperties: false + +allOf: + - $ref: "#/$defs/px30" + - $ref: "#/$defs/px30-pmu" + - $ref: "#/$defs/rk3188" + - $ref: "#/$defs/rk3228" + - $ref: "#/$defs/rk3288" + - $ref: "#/$defs/rk3328" + - $ref: "#/$defs/rk3368" + - $ref: "#/$defs/rk3368-pmu" + - $ref: "#/$defs/rk3399" + - $ref: "#/$defs/rk3399-pmu" + - $ref: "#/$defs/rk3568-pmu" + - $ref: "#/$defs/rv1108" + - $ref: "#/$defs/rv1108-pmu" + +$defs: + px30: + if: + properties: + compatible: + contains: + const: rockchip,px30-io-voltage-domain + + then: + properties: + vccio1-supply: + description: The supply connected to VCCIO1. + vccio2-supply: + description: The supply connected to VCCIO2. + vccio3-supply: + description: The supply connected to VCCIO3. + vccio4-supply: + description: The supply connected to VCCIO4. + vccio5-supply: + description: The supply connected to VCCIO5. + vccio6-supply: + description: The supply connected to VCCIO6. + vccio-oscgpi-supply: + description: The supply connected to VCCIO_OSCGPI. + + px30-pmu: + if: + properties: + compatible: + contains: + const: rockchip,px30-pmu-io-voltage-domain + + then: + properties: + pmuio1-supply: + description: The supply connected to PMUIO1. + pmuio2-supply: + description: The supply connected to PMUIO2. + + rk3188: + if: + properties: + compatible: + contains: + const: rockchip,rk3188-io-voltage-domain + + then: + properties: + ap0-supply: + description: The supply connected to AP0_VCC. + ap1-supply: + description: The supply connected to AP1_VCC. + cif-supply: + description: The supply connected to CIF_VCC. + flash-supply: + description: The supply connected to FLASH_VCC. + lcdc0-supply: + description: The supply connected to LCD0_VCC. + lcdc1-supply: + description: The supply connected to LCD1_VCC. + vccio0-supply: + description: The supply connected to VCCIO0. + vccio1-supply: + description: The supply connected to VCCIO1. Also labeled as VCCIO2. + + rk3228: + if: + properties: + compatible: + contains: + const: rockchip,rk3228-io-voltage-domain + + then: + properties: + vccio1-supply: + description: The supply connected to VCCIO1. + vccio2-supply: + description: The supply connected to VCCIO2. + vccio3-supply: + description: The supply connected to VCCIO3. + vccio4-supply: + description: The supply connected to VCCIO4. + + rk3288: + if: + properties: + compatible: + contains: + const: rockchip,rk3288-io-voltage-domain + + then: + properties: + audio-supply: + description: The supply connected to APIO4_VDD. + bb-supply: + description: The supply connected to APIO5_VDD. + dvp-supply: + description: The supply connected to DVPIO_VDD. + flash0-supply: + description: The supply connected to FLASH0_VDD. Typically for eMMC. + flash1-supply: + description: The supply connected to FLASH1_VDD. Also known as SDIO1. + gpio30-supply: + description: The supply connected to APIO1_VDD. + gpio1830-supply: + description: The supply connected to APIO2_VDD. + lcdc-supply: + description: The supply connected to LCDC_VDD. + sdcard-supply: + description: The supply connected to SDMMC0_VDD. + wifi-supply: + description: The supply connected to APIO3_VDD. Also known as SDIO0. + + rk3328: + if: + properties: + compatible: + contains: + const: rockchip,rk3328-io-voltage-domain + + then: + properties: + vccio1-supply: + description: The supply connected to VCCIO1. + vccio2-supply: + description: The supply connected to VCCIO2. + vccio3-supply: + description: The supply connected to VCCIO3. + vccio4-supply: + description: The supply connected to VCCIO4. + vccio5-supply: + description: The supply connected to VCCIO5. + vccio6-supply: + description: The supply connected to VCCIO6. + pmuio-supply: + description: The supply connected to VCCIO_PMU. + + rk3368: + if: + properties: + compatible: + contains: + const: rockchip,rk3368-io-voltage-domain + + then: + properties: + audio-supply: + description: The supply connected to APIO3_VDD. + dvp-supply: + description: The supply connected to DVPIO_VDD. + flash0-supply: + description: The supply connected to FLASH0_VDD. Typically for eMMC. + gpio30-supply: + description: The supply connected to APIO1_VDD. + gpio1830-supply: + description: The supply connected to APIO4_VDD. + sdcard-supply: + description: The supply connected to SDMMC0_VDD. + wifi-supply: + description: The supply connected to APIO2_VDD. Also known as SDIO0. + + rk3368-pmu: + if: + properties: + compatible: + contains: + const: rockchip,rk3368-pmu-io-voltage-domain + + then: + properties: + pmu-supply: + description: The supply connected to PMUIO_VDD. + vop-supply: + description: The supply connected to LCDC_VDD. + + rk3399: + if: + properties: + compatible: + contains: + const: rockchip,rk3399-io-voltage-domain + + then: + properties: + audio-supply: + description: The supply connected to APIO5_VDD. + bt656-supply: + description: The supply connected to APIO2_VDD. + gpio1830-supply: + description: The supply connected to APIO4_VDD. + sdmmc-supply: + description: The supply connected to SDMMC0_VDD. + + rk3399-pmu: + if: + properties: + compatible: + contains: + const: rockchip,rk3399-pmu-io-voltage-domain + + then: + properties: + pmu1830-supply: + description: The supply connected to PMUIO2_VDD. + + rk3568-pmu: + if: + properties: + compatible: + contains: + const: rockchip,rk3568-pmu-io-voltage-domain + + then: + properties: + pmuio1-supply: + description: The supply connected to PMUIO1. + pmuio2-supply: + description: The supply connected to PMUIO2. + vccio1-supply: + description: The supply connected to VCCIO1. + vccio2-supply: + description: The supply connected to VCCIO2. + vccio3-supply: + description: The supply connected to VCCIO3. + vccio4-supply: + description: The supply connected to VCCIO4. + vccio5-supply: + description: The supply connected to VCCIO5. + vccio6-supply: + description: The supply connected to VCCIO6. + vccio7-supply: + description: The supply connected to VCCIO7. + + rv1108: + if: + properties: + compatible: + contains: + const: rockchip,rv1108-io-voltage-domain + + then: + properties: + vccio1-supply: + description: The supply connected to APIO1_VDD. + vccio2-supply: + description: The supply connected to APIO2_VDD. + vccio3-supply: + description: The supply connected to APIO3_VDD. + vccio5-supply: + description: The supply connected to APIO5_VDD. + vccio6-supply: + description: The supply connected to APIO6_VDD. + + rv1108-pmu: + if: + properties: + compatible: + contains: + const: rockchip,rv1108-pmu-io-voltage-domain + + then: + properties: + pmu-supply: + description: The supply connected to PMUIO_VDD. + +examples: + - | + io-domains { + compatible = "rockchip,rk3288-io-voltage-domain"; + audio-supply = <&vcc18_codec>; + bb-supply = <&vcc33_io>; + dvp-supply = <&vcc_18>; + flash0-supply = <&vcc18_flashio>; + gpio1830-supply = <&vcc33_io>; + gpio30-supply = <&vcc33_pmuio>; + lcdc-supply = <&vcc33_lcd>; + sdcard-supply = <&vccio_sd>; + wifi-supply = <&vcc18_wl>; + }; diff --git a/Documentation/devicetree/bindings/power/supply/battery.yaml b/Documentation/devicetree/bindings/power/supply/battery.yaml index c3b4b7543591..d56ac484fec5 100644 --- a/Documentation/devicetree/bindings/power/supply/battery.yaml +++ b/Documentation/devicetree/bindings/power/supply/battery.yaml @@ -31,6 +31,20 @@ properties: compatible: const: simple-battery + device-chemistry: + description: This describes the chemical technology of the battery. + oneOf: + - const: nickel-cadmium + - const: nickel-metal-hydride + - const: lithium-ion + description: This is a blanket type for all lithium-ion batteries, + including those below. If possible, a precise compatible string + from below should be used, but sometimes it is unknown which specific + lithium ion battery is employed and this wide compatible can be used. + - const: lithium-ion-polymer + - const: lithium-ion-iron-phosphate + - const: lithium-ion-manganese-oxide + over-voltage-threshold-microvolt: description: battery over-voltage limit diff --git a/Documentation/devicetree/bindings/power/supply/maxim,max17042.yaml b/Documentation/devicetree/bindings/power/supply/maxim,max17042.yaml index c70f05ea6d27..971b53c58cc6 100644 --- a/Documentation/devicetree/bindings/power/supply/maxim,max17042.yaml +++ b/Documentation/devicetree/bindings/power/supply/maxim,max17042.yaml @@ -19,12 +19,15 @@ properties: - maxim,max17047 - maxim,max17050 - maxim,max17055 + - maxim,max77849-battery reg: maxItems: 1 interrupts: maxItems: 1 + description: | + The ALRT pin, an open-drain interrupt. maxim,rsns-microohm: $ref: /schemas/types.yaml#/definitions/uint32 diff --git a/Documentation/devicetree/bindings/power/supply/mt6360_charger.yaml b/Documentation/devicetree/bindings/power/supply/mt6360_charger.yaml new file mode 100644 index 000000000000..b89b15a5bfa4 --- /dev/null +++ b/Documentation/devicetree/bindings/power/supply/mt6360_charger.yaml @@ -0,0 +1,48 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/power/supply/mt6360_charger.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Battery charger driver for MT6360 PMIC from MediaTek Integrated. + +maintainers: + - Gene Chen <gene_chen@richtek.com> + +description: | + This module is part of the MT6360 MFD device. + Provides Battery Charger, Boost for OTG devices and BC1.2 detection. + +properties: + compatible: + const: mediatek,mt6360-chg + + richtek,vinovp-microvolt: + description: Maximum CHGIN regulation voltage in uV. + enum: [ 5500000, 6500000, 11000000, 14500000 ] + + + usb-otg-vbus-regulator: + type: object + description: OTG boost regulator. + $ref: /schemas/regulator/regulator.yaml# + +required: + - compatible + +additionalProperties: false + +examples: + - | + mt6360_charger: charger { + compatible = "mediatek,mt6360-chg"; + richtek,vinovp-microvolt = <14500000>; + + otg_vbus_regulator: usb-otg-vbus-regulator { + regulator-compatible = "usb-otg-vbus"; + regulator-name = "usb-otg-vbus"; + regulator-min-microvolt = <4425000>; + regulator-max-microvolt = <5825000>; + }; + }; +... diff --git a/Documentation/devicetree/bindings/power/supply/summit,smb347-charger.yaml b/Documentation/devicetree/bindings/power/supply/summit,smb347-charger.yaml index 983fc215c1e5..20862cdfc116 100644 --- a/Documentation/devicetree/bindings/power/supply/summit,smb347-charger.yaml +++ b/Documentation/devicetree/bindings/power/supply/summit,smb347-charger.yaml @@ -73,6 +73,26 @@ properties: - 1 # SMB3XX_SOFT_TEMP_COMPENSATE_CURRENT Current compensation - 2 # SMB3XX_SOFT_TEMP_COMPENSATE_VOLTAGE Voltage compensation + summit,inok-polarity: + description: | + Polarity of INOK signal indicating presence of external power supply. + $ref: /schemas/types.yaml#/definitions/uint32 + enum: + - 0 # SMB3XX_SYSOK_INOK_ACTIVE_LOW + - 1 # SMB3XX_SYSOK_INOK_ACTIVE_HIGH + + usb-vbus: + $ref: "../../regulator/regulator.yaml#" + type: object + + properties: + summit,needs-inok-toggle: + type: boolean + description: INOK signal is fixed and polarity needs to be toggled + in order to enable/disable output mode. + + unevaluatedProperties: false + allOf: - if: properties: @@ -134,6 +154,7 @@ examples: reg = <0x7f>; summit,enable-charge-control = <SMB3XX_CHG_ENABLE_PIN_ACTIVE_HIGH>; + summit,inok-polarity = <SMB3XX_SYSOK_INOK_ACTIVE_LOW>; summit,chip-temperature-threshold-celsius = <110>; summit,mains-current-limit-microamp = <2000000>; summit,usb-current-limit-microamp = <500000>; @@ -141,6 +162,15 @@ examples: summit,enable-mains-charging; monitored-battery = <&battery>; + + usb-vbus { + regulator-name = "usb_vbus"; + regulator-min-microvolt = <5000000>; + regulator-max-microvolt = <5000000>; + regulator-min-microamp = <750000>; + regulator-max-microamp = <750000>; + summit,needs-inok-toggle; + }; }; }; diff --git a/Documentation/devicetree/bindings/power/supply/x-powers,axp20x-ac-power-supply.yaml b/Documentation/devicetree/bindings/power/supply/x-powers,axp20x-ac-power-supply.yaml index dcda6660b8ed..de6a23aee977 100644 --- a/Documentation/devicetree/bindings/power/supply/x-powers,axp20x-ac-power-supply.yaml +++ b/Documentation/devicetree/bindings/power/supply/x-powers,axp20x-ac-power-supply.yaml @@ -21,10 +21,13 @@ allOf: properties: compatible: - enum: - - x-powers,axp202-ac-power-supply - - x-powers,axp221-ac-power-supply - - x-powers,axp813-ac-power-supply + oneOf: + - const: x-powers,axp202-ac-power-supply + - const: x-powers,axp221-ac-power-supply + - items: + - const: x-powers,axp803-ac-power-supply + - const: x-powers,axp813-ac-power-supply + - const: x-powers,axp813-ac-power-supply required: - compatible diff --git a/Documentation/devicetree/bindings/power/supply/x-powers,axp20x-battery-power-supply.yaml b/Documentation/devicetree/bindings/power/supply/x-powers,axp20x-battery-power-supply.yaml index 86e8a713d4e2..d055428ae39f 100644 --- a/Documentation/devicetree/bindings/power/supply/x-powers,axp20x-battery-power-supply.yaml +++ b/Documentation/devicetree/bindings/power/supply/x-powers,axp20x-battery-power-supply.yaml @@ -19,10 +19,14 @@ allOf: properties: compatible: - enum: - - x-powers,axp209-battery-power-supply - - x-powers,axp221-battery-power-supply - - x-powers,axp813-battery-power-supply + oneOf: + - const: x-powers,axp202-battery-power-supply + - const: x-powers,axp209-battery-power-supply + - const: x-powers,axp221-battery-power-supply + - items: + - const: x-powers,axp803-battery-power-supply + - const: x-powers,axp813-battery-power-supply + - const: x-powers,axp813-battery-power-supply required: - compatible diff --git a/Documentation/devicetree/bindings/power/supply/x-powers,axp20x-usb-power-supply.yaml b/Documentation/devicetree/bindings/power/supply/x-powers,axp20x-usb-power-supply.yaml index 61f1b320c157..0c371b55c9e1 100644 --- a/Documentation/devicetree/bindings/power/supply/x-powers,axp20x-usb-power-supply.yaml +++ b/Documentation/devicetree/bindings/power/supply/x-powers,axp20x-usb-power-supply.yaml @@ -20,11 +20,15 @@ allOf: properties: compatible: - enum: - - x-powers,axp202-usb-power-supply - - x-powers,axp221-usb-power-supply - - x-powers,axp223-usb-power-supply - - x-powers,axp813-usb-power-supply + oneOf: + - enum: + - x-powers,axp202-usb-power-supply + - x-powers,axp221-usb-power-supply + - x-powers,axp223-usb-power-supply + - x-powers,axp813-usb-power-supply + - items: + - const: x-powers,axp803-usb-power-supply + - const: x-powers,axp813-usb-power-supply required: diff --git a/Documentation/devicetree/bindings/regulator/fixed-regulator.yaml b/Documentation/devicetree/bindings/regulator/fixed-regulator.yaml index 8850c01bd470..9b131c6facbc 100644 --- a/Documentation/devicetree/bindings/regulator/fixed-regulator.yaml +++ b/Documentation/devicetree/bindings/regulator/fixed-regulator.yaml @@ -57,12 +57,14 @@ properties: maxItems: 1 power-domains: + deprecated: true description: Power domain to use for enable control. This binding is only available if the compatible is chosen to regulator-fixed-domain. maxItems: 1 required-opps: + deprecated: true description: Performance state to use for enable control. This binding is only available if the compatible is chosen to regulator-fixed-domain. The diff --git a/Documentation/devicetree/bindings/regulator/richtek,rt6245-regulator.yaml b/Documentation/devicetree/bindings/regulator/richtek,rt6245-regulator.yaml index 796ceac87445..e983d0e70c9b 100644 --- a/Documentation/devicetree/bindings/regulator/richtek,rt6245-regulator.yaml +++ b/Documentation/devicetree/bindings/regulator/richtek,rt6245-regulator.yaml @@ -77,7 +77,6 @@ examples: rt6245@34 { compatible = "richtek,rt6245"; - status = "okay"; reg = <0x34>; enable-gpios = <&gpio26 2 0>; diff --git a/Documentation/devicetree/bindings/regulator/richtek,rtq2134-regulator.yaml b/Documentation/devicetree/bindings/regulator/richtek,rtq2134-regulator.yaml new file mode 100644 index 000000000000..3f47e8e6c4fd --- /dev/null +++ b/Documentation/devicetree/bindings/regulator/richtek,rtq2134-regulator.yaml @@ -0,0 +1,106 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/regulator/richtek,rtq2134-regulator.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Richtek RTQ2134 SubPMIC Regulator + +maintainers: + - ChiYuan Huang <cy_huang@richtek.com> + +description: | + The RTQ2134 is a multi-phase, programmable power management IC that + integrates with four high efficient, synchronous step-down converter cores. + + Datasheet is available at + https://www.richtek.com/assets/product_file/RTQ2134-QA/DSQ2134-QA-01.pdf + +properties: + compatible: + enum: + - richtek,rtq2134 + + reg: + maxItems: 1 + + regulators: + type: object + + patternProperties: + "^buck[1-3]$": + type: object + $ref: regulator.yaml# + description: | + regulator description for buck[1-3]. + + properties: + richtek,use-vsel-dvs: + type: boolean + description: | + If specified, buck will listen to 'vsel' pin for dvs config. + Else, use dvs0 voltage by default. + + richtek,uv-shutdown: + type: boolean + description: | + If specified, use shutdown as UV action. Else, hiccup by default. + + unevaluatedProperties: false + + additionalProperties: false + +required: + - compatible + - reg + - regulators + +additionalProperties: false + +examples: + - | + i2c { + #address-cells = <1>; + #size-cells = <0>; + + rtq2134@18 { + compatible = "richtek,rtq2134"; + reg = <0x18>; + + regulators { + buck1 { + regulator-name = "rtq2134-buck1"; + regulator-min-microvolt = <300000>; + regulator-max-microvolt = <1850000>; + regulator-always-on; + richtek,use-vsel-dvs; + regulator-state-mem { + regulator-suspend-min-microvolt = <550000>; + regulator-suspend-max-microvolt = <550000>; + }; + }; + buck2 { + regulator-name = "rtq2134-buck2"; + regulator-min-microvolt = <1120000>; + regulator-max-microvolt = <1120000>; + regulator-always-on; + richtek,use-vsel-dvs; + regulator-state-mem { + regulator-suspend-min-microvolt = <1120000>; + regulator-suspend-max-microvolt = <1120000>; + }; + }; + buck3 { + regulator-name = "rtq2134-buck3"; + regulator-min-microvolt = <600000>; + regulator-max-microvolt = <600000>; + regulator-always-on; + richtek,use-vsel-dvs; + regulator-state-mem { + regulator-suspend-min-microvolt = <600000>; + regulator-suspend-max-microvolt = <600000>; + }; + }; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/regulator/richtek,rtq6752-regulator.yaml b/Documentation/devicetree/bindings/regulator/richtek,rtq6752-regulator.yaml new file mode 100644 index 000000000000..e6e5a9a7d940 --- /dev/null +++ b/Documentation/devicetree/bindings/regulator/richtek,rtq6752-regulator.yaml @@ -0,0 +1,76 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/regulator/richtek,rtq6752-regulator.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Richtek RTQ6752 TFT LCD Voltage Regulator + +maintainers: + - ChiYuan Huang <cy_huang@richtek.com> + +description: | + The RTQ6752 is an I2C interface pgorammable power management IC. It includes + two synchronous boost converter for PAVDD, and one synchronous NAVDD + buck-boost. The device is suitable for automotive TFT-LCD panel. + +properties: + compatible: + enum: + - richtek,rtq6752 + + reg: + maxItems: 1 + + enable-gpios: + description: | + A connection of the chip 'enable' gpio line. If not provided, treat it as + external pull up. + maxItems: 1 + + regulators: + type: object + + patternProperties: + "^(p|n)avdd$": + type: object + $ref: regulator.yaml# + description: | + regulator description for pavdd and navdd. + + additionalProperties: false + +required: + - compatible + - reg + - regulators + +additionalProperties: false + +examples: + - | + i2c { + #address-cells = <1>; + #size-cells = <0>; + + rtq6752@6b { + compatible = "richtek,rtq6752"; + reg = <0x6b>; + enable-gpios = <&gpio26 2 0>; + + regulators { + pavdd { + regulator-name = "rtq6752-pavdd"; + regulator-min-microvolt = <5000000>; + regulator-max-microvolt = <7300000>; + regulator-boot-on; + }; + navdd { + regulator-name = "rtq6752-navdd"; + regulator-min-microvolt = <5000000>; + regulator-max-microvolt = <7300000>; + regulator-boot-on; + }; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/regulator/socionext,uniphier-regulator.yaml b/Documentation/devicetree/bindings/regulator/socionext,uniphier-regulator.yaml new file mode 100644 index 000000000000..861d5f3c79e8 --- /dev/null +++ b/Documentation/devicetree/bindings/regulator/socionext,uniphier-regulator.yaml @@ -0,0 +1,85 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/regulator/socionext,uniphier-regulator.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Socionext UniPhier regulator controller + +description: | + This regulator controls VBUS and belongs to USB3 glue layer. Before using + the regulator, it is necessary to control the clocks and resets to enable + this layer. These clocks and resets should be described in each property. + +maintainers: + - Kunihiko Hayashi <hayashi.kunihiko@socionext.com> + +allOf: + - $ref: "regulator.yaml#" + +# USB3 Controller + +properties: + compatible: + enum: + - socionext,uniphier-pro4-usb3-regulator + - socionext,uniphier-pro5-usb3-regulator + - socionext,uniphier-pxs2-usb3-regulator + - socionext,uniphier-ld20-usb3-regulator + - socionext,uniphier-pxs3-usb3-regulator + + reg: + maxItems: 1 + + clocks: + minItems: 1 + maxItems: 2 + + clock-names: + oneOf: + - items: # for Pro4, Pro5 + - const: gio + - const: link + - items: # for others + - const: link + + resets: + minItems: 1 + maxItems: 2 + + reset-names: + oneOf: + - items: # for Pro4, Pro5 + - const: gio + - const: link + - items: + - const: link + +additionalProperties: false + +required: + - compatible + - reg + - clocks + - clock-names + - resets + - reset-names + +examples: + - | + usb-glue@65b00000 { + compatible = "simple-mfd"; + #address-cells = <1>; + #size-cells = <1>; + ranges = <0 0x65b00000 0x400>; + + usb_vbus0: regulators@100 { + compatible = "socionext,uniphier-ld20-usb3-regulator"; + reg = <0x100 0x10>; + clock-names = "link"; + clocks = <&sys_clk 14>; + reset-names = "link"; + resets = <&sys_rst 14>; + }; + }; + diff --git a/Documentation/devicetree/bindings/regulator/uniphier-regulator.txt b/Documentation/devicetree/bindings/regulator/uniphier-regulator.txt deleted file mode 100644 index 94fd38b0d163..000000000000 --- a/Documentation/devicetree/bindings/regulator/uniphier-regulator.txt +++ /dev/null @@ -1,58 +0,0 @@ -Socionext UniPhier Regulator Controller - -This describes the devicetree bindings for regulator controller implemented -on Socionext UniPhier SoCs. - -USB3 Controller ---------------- - -This regulator controls VBUS and belongs to USB3 glue layer. Before using -the regulator, it is necessary to control the clocks and resets to enable -this layer. These clocks and resets should be described in each property. - -Required properties: -- compatible: Should be - "socionext,uniphier-pro4-usb3-regulator" - for Pro4 SoC - "socionext,uniphier-pro5-usb3-regulator" - for Pro5 SoC - "socionext,uniphier-pxs2-usb3-regulator" - for PXs2 SoC - "socionext,uniphier-ld20-usb3-regulator" - for LD20 SoC - "socionext,uniphier-pxs3-usb3-regulator" - for PXs3 SoC -- reg: Specifies offset and length of the register set for the device. -- clocks: A list of phandles to the clock gate for USB3 glue layer. - According to the clock-names, appropriate clocks are required. -- clock-names: Should contain - "gio", "link" - for Pro4 and Pro5 SoCs - "link" - for others -- resets: A list of phandles to the reset control for USB3 glue layer. - According to the reset-names, appropriate resets are required. -- reset-names: Should contain - "gio", "link" - for Pro4 and Pro5 SoCs - "link" - for others - -See Documentation/devicetree/bindings/regulator/regulator.txt -for more details about the regulator properties. - -Example: - - usb-glue@65b00000 { - compatible = "socionext,uniphier-ld20-dwc3-glue", - "simple-mfd"; - #address-cells = <1>; - #size-cells = <1>; - ranges = <0 0x65b00000 0x400>; - - usb_vbus0: regulators@100 { - compatible = "socionext,uniphier-ld20-usb3-regulator"; - reg = <0x100 0x10>; - clock-names = "link"; - clocks = <&sys_clk 14>; - reset-names = "link"; - resets = <&sys_rst 14>; - }; - - phy { - ... - phy-supply = <&usb_vbus0>; - }; - ... - }; diff --git a/Documentation/devicetree/bindings/regulator/vqmmc-ipq4019-regulator.yaml b/Documentation/devicetree/bindings/regulator/vqmmc-ipq4019-regulator.yaml index 6f45582c914e..dd7a2f92634c 100644 --- a/Documentation/devicetree/bindings/regulator/vqmmc-ipq4019-regulator.yaml +++ b/Documentation/devicetree/bindings/regulator/vqmmc-ipq4019-regulator.yaml @@ -39,6 +39,5 @@ examples: regulator-min-microvolt = <1500000>; regulator-max-microvolt = <3000000>; regulator-always-on; - status = "disabled"; }; ... diff --git a/Documentation/devicetree/bindings/reserved-memory/reserved-memory.txt b/Documentation/devicetree/bindings/reserved-memory/reserved-memory.txt index e8d3096d922c..39b5f4c5a511 100644 --- a/Documentation/devicetree/bindings/reserved-memory/reserved-memory.txt +++ b/Documentation/devicetree/bindings/reserved-memory/reserved-memory.txt @@ -51,6 +51,23 @@ compatible (optional) - standard definition used as a shared pool of DMA buffers for a set of devices. It can be used by an operating system to instantiate the necessary pool management subsystem if necessary. + - restricted-dma-pool: This indicates a region of memory meant to be + used as a pool of restricted DMA buffers for a set of devices. The + memory region would be the only region accessible to those devices. + When using this, the no-map and reusable properties must not be set, + so the operating system can create a virtual mapping that will be used + for synchronization. The main purpose for restricted DMA is to + mitigate the lack of DMA access control on systems without an IOMMU, + which could result in the DMA accessing the system memory at + unexpected times and/or unexpected addresses, possibly leading to data + leakage or corruption. The feature on its own provides a basic level + of protection against the DMA overwriting buffer contents at + unexpected times. However, to protect against general data leakage and + system memory corruption, the system needs to provide way to lock down + the memory access, e.g., MPU. Note that since coherent allocation + needs remapping, one must set up another device coherent pool by + shared-dma-pool and use dma_alloc_from_dev_coherent instead for atomic + coherent allocation. - vendor specific string in the form <vendor>,[<device>-]<usage> no-map (optional) - empty property - Indicates the operating system must not create a virtual mapping @@ -85,10 +102,11 @@ memory-region-names (optional) - a list of names, one for each corresponding Example ------- -This example defines 3 contiguous regions are defined for Linux kernel: +This example defines 4 contiguous regions for Linux kernel: one default of all device drivers (named linux,cma@72000000 and 64MiB in size), -one dedicated to the framebuffer device (named framebuffer@78000000, 8MiB), and -one for multimedia processing (named multimedia-memory@77000000, 64MiB). +one dedicated to the framebuffer device (named framebuffer@78000000, 8MiB), +one for multimedia processing (named multimedia-memory@77000000, 64MiB), and +one for restricted dma pool (named restricted_dma_reserved@0x50000000, 64MiB). / { #address-cells = <1>; @@ -120,6 +138,11 @@ one for multimedia processing (named multimedia-memory@77000000, 64MiB). compatible = "acme,multimedia-memory"; reg = <0x77000000 0x4000000>; }; + + restricted_dma_reserved: restricted_dma_reserved { + compatible = "restricted-dma-pool"; + reg = <0x50000000 0x4000000>; + }; }; /* ... */ @@ -138,4 +161,11 @@ one for multimedia processing (named multimedia-memory@77000000, 64MiB). memory-region = <&multimedia_reserved>; /* ... */ }; + + pcie_device: pcie_device@0,0 { + reg = <0x83010000 0x0 0x00000000 0x0 0x00100000 + 0x83010000 0x0 0x00100000 0x0 0x00100000>; + memory-region = <&restricted_dma_reserved>; + /* ... */ + }; }; diff --git a/Documentation/devicetree/bindings/reset/hisilicon,hi3660-reset.yaml b/Documentation/devicetree/bindings/reset/hisilicon,hi3660-reset.yaml index 9bf40952e5b7..b0c41ab1a746 100644 --- a/Documentation/devicetree/bindings/reset/hisilicon,hi3660-reset.yaml +++ b/Documentation/devicetree/bindings/reset/hisilicon,hi3660-reset.yaml @@ -72,6 +72,5 @@ examples: resets = <&iomcu_rst 0x20 3>; pinctrl-names = "default"; pinctrl-0 = <&i2c0_pmx_func &i2c0_cfg_func>; - status = "disabled"; }; ... diff --git a/Documentation/devicetree/bindings/reset/intel,rcu-gw.yaml b/Documentation/devicetree/bindings/reset/intel,rcu-gw.yaml index 6b2d56cc3f38..13bf6bb3f097 100644 --- a/Documentation/devicetree/bindings/reset/intel,rcu-gw.yaml +++ b/Documentation/devicetree/bindings/reset/intel,rcu-gw.yaml @@ -57,7 +57,6 @@ examples: }; pwm: pwm@e0d00000 { - status = "disabled"; compatible = "intel,lgm-pwm"; reg = <0xe0d00000 0x30>; clocks = <&cgu0 1>; diff --git a/Documentation/devicetree/bindings/reset/qcom,aoss-reset.yaml b/Documentation/devicetree/bindings/reset/qcom,aoss-reset.yaml index e2d85a1e1d63..a054757f4d9f 100644 --- a/Documentation/devicetree/bindings/reset/qcom,aoss-reset.yaml +++ b/Documentation/devicetree/bindings/reset/qcom,aoss-reset.yaml @@ -21,6 +21,11 @@ properties: - const: "qcom,sc7180-aoss-cc" - const: "qcom,sdm845-aoss-cc" + - description: on SC7280 SoCs the following compatibles must be specified + items: + - const: "qcom,sc7280-aoss-cc" + - const: "qcom,sdm845-aoss-cc" + - description: on SDM845 SoCs the following compatibles must be specified items: - const: "qcom,sdm845-aoss-cc" diff --git a/Documentation/devicetree/bindings/reset/qcom,pdc-global.yaml b/Documentation/devicetree/bindings/reset/qcom,pdc-global.yaml index d7d8cec9419f..831ea8d5d83f 100644 --- a/Documentation/devicetree/bindings/reset/qcom,pdc-global.yaml +++ b/Documentation/devicetree/bindings/reset/qcom,pdc-global.yaml @@ -21,6 +21,10 @@ properties: - const: "qcom,sc7180-pdc-global" - const: "qcom,sdm845-pdc-global" + - description: on SC7280 SoCs the following compatibles must be specified + items: + - const: "qcom,sc7280-pdc-global" + - description: on SDM845 SoCs the following compatibles must be specified items: - const: "qcom,sdm845-pdc-global" diff --git a/Documentation/devicetree/bindings/reset/renesas,rzg2l-usbphy-ctrl.yaml b/Documentation/devicetree/bindings/reset/renesas,rzg2l-usbphy-ctrl.yaml new file mode 100644 index 000000000000..b13514e6783d --- /dev/null +++ b/Documentation/devicetree/bindings/reset/renesas,rzg2l-usbphy-ctrl.yaml @@ -0,0 +1,65 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/reset/renesas,rzg2l-usbphy-ctrl.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Renesas RZ/G2L USBPHY Control + +maintainers: + - Biju Das <biju.das.jz@bp.renesas.com> + +description: + The RZ/G2L USBPHY Control mainly controls reset and power down of the + USB/PHY. + +properties: + compatible: + items: + - enum: + - renesas,r9a07g044-usbphy-ctrl # RZ/G2{L,LC} + - const: renesas,rzg2l-usbphy-ctrl + + reg: + maxItems: 1 + + clocks: + maxItems: 1 + + resets: + maxItems: 1 + + power-domains: + maxItems: 1 + + '#reset-cells': + const: 1 + description: | + The phandle's argument in the reset specifier is the PHY reset associated + with the USB port. + 0 = Port 1 Phy reset + 1 = Port 2 Phy reset + +required: + - compatible + - reg + - clocks + - resets + - power-domains + - '#reset-cells' + +additionalProperties: false + +examples: + - | + #include <dt-bindings/clock/r9a07g044-cpg.h> + + phyrst: usbphy-ctrl@11c40000 { + compatible = "renesas,r9a07g044-usbphy-ctrl", + "renesas,rzg2l-usbphy-ctrl"; + reg = <0x11c40000 0x10000>; + clocks = <&cpg CPG_MOD R9A07G044_USB_PCLK>; + resets = <&cpg R9A07G044_USB_PRESETN>; + power-domains = <&cpg>; + #reset-cells = <1>; + }; diff --git a/Documentation/devicetree/bindings/reset/socionext,uniphier-glue-reset.yaml b/Documentation/devicetree/bindings/reset/socionext,uniphier-glue-reset.yaml new file mode 100644 index 000000000000..29e4a900cad7 --- /dev/null +++ b/Documentation/devicetree/bindings/reset/socionext,uniphier-glue-reset.yaml @@ -0,0 +1,88 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/reset/socionext,uniphier-glue-reset.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Socionext UniPhier peripheral core reset in glue layer + +description: | + Some peripheral core reset belongs to its own glue layer. Before using + this core reset, it is necessary to control the clocks and resets to + enable this layer. These clocks and resets should be described in each + property. + +maintainers: + - Kunihiko Hayashi <hayashi.kunihiko@socionext.com> + +properties: + compatible: + enum: + - socionext,uniphier-pro4-usb3-reset + - socionext,uniphier-pro5-usb3-reset + - socionext,uniphier-pxs2-usb3-reset + - socionext,uniphier-ld20-usb3-reset + - socionext,uniphier-pxs3-usb3-reset + - socionext,uniphier-pro4-ahci-reset + - socionext,uniphier-pxs2-ahci-reset + - socionext,uniphier-pxs3-ahci-reset + + reg: + maxItems: 1 + + "#reset-cells": + const: 1 + + clocks: + minItems: 1 + maxItems: 2 + + clock-names: + oneOf: + - items: # for Pro4, Pro5 + - const: gio + - const: link + - items: # for others + - const: link + + resets: + minItems: 1 + maxItems: 2 + + reset-names: + oneOf: + - items: # for Pro4, Pro5 + - const: gio + - const: link + - items: # for others + - const: link + +additionalProperties: false + +required: + - compatible + - reg + - "#reset-cells" + - clocks + - clock-names + - resets + - reset-names + +examples: + - | + usb-glue@65b00000 { + compatible = "simple-mfd"; + #address-cells = <1>; + #size-cells = <1>; + ranges = <0 0x65b00000 0x400>; + + usb_rst: reset@0 { + compatible = "socionext,uniphier-ld20-usb3-reset"; + reg = <0x0 0x4>; + #reset-cells = <1>; + clock-names = "link"; + clocks = <&sys_clk 14>; + reset-names = "link"; + resets = <&sys_rst 14>; + }; + }; diff --git a/Documentation/devicetree/bindings/reset/uniphier-reset.txt b/Documentation/devicetree/bindings/reset/uniphier-reset.txt deleted file mode 100644 index 88e06e5e8d23..000000000000 --- a/Documentation/devicetree/bindings/reset/uniphier-reset.txt +++ /dev/null @@ -1,61 +0,0 @@ -UniPhier glue reset controller - - -Peripheral core reset in glue layer ------------------------------------ - -Some peripheral core reset belongs to its own glue layer. Before using -this core reset, it is necessary to control the clocks and resets to enable -this layer. These clocks and resets should be described in each property. - -Required properties: -- compatible: Should be - "socionext,uniphier-pro4-usb3-reset" - for Pro4 SoC USB3 - "socionext,uniphier-pro5-usb3-reset" - for Pro5 SoC USB3 - "socionext,uniphier-pxs2-usb3-reset" - for PXs2 SoC USB3 - "socionext,uniphier-ld20-usb3-reset" - for LD20 SoC USB3 - "socionext,uniphier-pxs3-usb3-reset" - for PXs3 SoC USB3 - "socionext,uniphier-pro4-ahci-reset" - for Pro4 SoC AHCI - "socionext,uniphier-pxs2-ahci-reset" - for PXs2 SoC AHCI - "socionext,uniphier-pxs3-ahci-reset" - for PXs3 SoC AHCI -- #reset-cells: Should be 1. -- reg: Specifies offset and length of the register set for the device. -- clocks: A list of phandles to the clock gate for the glue layer. - According to the clock-names, appropriate clocks are required. -- clock-names: Should contain - "gio", "link" - for Pro4 and Pro5 SoCs - "link" - for others -- resets: A list of phandles to the reset control for the glue layer. - According to the reset-names, appropriate resets are required. -- reset-names: Should contain - "gio", "link" - for Pro4 and Pro5 SoCs - "link" - for others - -Example: - - usb-glue@65b00000 { - compatible = "socionext,uniphier-ld20-dwc3-glue", - "simple-mfd"; - #address-cells = <1>; - #size-cells = <1>; - ranges = <0 0x65b00000 0x400>; - - usb_rst: reset@0 { - compatible = "socionext,uniphier-ld20-usb3-reset"; - reg = <0x0 0x4>; - #reset-cells = <1>; - clock-names = "link"; - clocks = <&sys_clk 14>; - reset-names = "link"; - resets = <&sys_rst 14>; - }; - - regulator { - ... - }; - - phy { - ... - }; - ... - }; diff --git a/Documentation/devicetree/bindings/riscv/sifive-l2-cache.yaml b/Documentation/devicetree/bindings/riscv/sifive-l2-cache.yaml index 1d38ff76d18f..2b1f91603897 100644 --- a/Documentation/devicetree/bindings/riscv/sifive-l2-cache.yaml +++ b/Documentation/devicetree/bindings/riscv/sifive-l2-cache.yaml @@ -24,10 +24,10 @@ allOf: select: properties: compatible: - items: - - enum: - - sifive,fu540-c000-ccache - - sifive,fu740-c000-ccache + contains: + enum: + - sifive,fu540-c000-ccache + - sifive,fu740-c000-ccache required: - compatible diff --git a/Documentation/devicetree/bindings/riscv/starfive.yaml b/Documentation/devicetree/bindings/riscv/starfive.yaml new file mode 100644 index 000000000000..5b36243fd674 --- /dev/null +++ b/Documentation/devicetree/bindings/riscv/starfive.yaml @@ -0,0 +1,27 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/riscv/starfive.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: StarFive SoC-based boards + +maintainers: + - Michael Zhu <michael.zhu@starfivetech.com> + - Drew Fustini <drew@beagleboard.org> + +description: + StarFive SoC-based boards + +properties: + $nodename: + const: '/' + compatible: + oneOf: + - items: + - const: beagle,beaglev-starlight-jh7100-r0 + - const: starfive,jh7100 + +additionalProperties: true + +... diff --git a/Documentation/devicetree/bindings/rng/mtk-rng.yaml b/Documentation/devicetree/bindings/rng/mtk-rng.yaml index 61888e07bda0..bb32491ee8ae 100644 --- a/Documentation/devicetree/bindings/rng/mtk-rng.yaml +++ b/Documentation/devicetree/bindings/rng/mtk-rng.yaml @@ -21,6 +21,7 @@ properties: - enum: - mediatek,mt7622-rng - mediatek,mt7629-rng + - mediatek,mt7986-rng - mediatek,mt8365-rng - mediatek,mt8516-rng - const: mediatek,mt7623-rng diff --git a/Documentation/devicetree/bindings/rng/samsung,exynos5250-trng.txt b/Documentation/devicetree/bindings/rng/samsung,exynos5250-trng.txt deleted file mode 100644 index 5a613a4ec780..000000000000 --- a/Documentation/devicetree/bindings/rng/samsung,exynos5250-trng.txt +++ /dev/null @@ -1,17 +0,0 @@ -Exynos True Random Number Generator - -Required properties: - -- compatible : Should be "samsung,exynos5250-trng". -- reg : Specifies base physical address and size of the registers map. -- clocks : Phandle to clock-controller plus clock-specifier pair. -- clock-names : "secss" as a clock name. - -Example: - - rng@10830600 { - compatible = "samsung,exynos5250-trng"; - reg = <0x10830600 0x100>; - clocks = <&clock CLK_SSS>; - clock-names = "secss"; - }; diff --git a/Documentation/devicetree/bindings/rng/samsung,exynos5250-trng.yaml b/Documentation/devicetree/bindings/rng/samsung,exynos5250-trng.yaml new file mode 100644 index 000000000000..a50c34d5d199 --- /dev/null +++ b/Documentation/devicetree/bindings/rng/samsung,exynos5250-trng.yaml @@ -0,0 +1,44 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/rng/samsung,exynos5250-trng.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Samsung Exynos SoC True Random Number Generator + +maintainers: + - Krzysztof Kozlowski <krzysztof.kozlowski@canonical.com> + - Łukasz Stelmach <l.stelmach@samsung.com> + +properties: + compatible: + const: samsung,exynos5250-trng + + clocks: + maxItems: 1 + + clock-names: + items: + - const: secss + + reg: + maxItems: 1 + +required: + - compatible + - clocks + - clock-names + - reg + +additionalProperties: false + +examples: + - | + #include <dt-bindings/clock/exynos5250.h> + + rng@10830600 { + compatible = "samsung,exynos5250-trng"; + reg = <0x10830600 0x100>; + clocks = <&clock CLK_SSS>; + clock-names = "secss"; + }; diff --git a/Documentation/devicetree/bindings/rtc/microcrystal,rv3032.yaml b/Documentation/devicetree/bindings/rtc/microcrystal,rv3032.yaml index a2c55303810d..9593840a4a2b 100644 --- a/Documentation/devicetree/bindings/rtc/microcrystal,rv3032.yaml +++ b/Documentation/devicetree/bindings/rtc/microcrystal,rv3032.yaml @@ -53,7 +53,6 @@ examples: rtc@51 { compatible = "microcrystal,rv3032"; reg = <0x51>; - status = "okay"; pinctrl-0 = <&rtc_nint_pins>; interrupts-extended = <&gpio1 16 IRQ_TYPE_LEVEL_HIGH>; trickle-resistor-ohms = <7000>; diff --git a/Documentation/devicetree/bindings/serial/8250.yaml b/Documentation/devicetree/bindings/serial/8250.yaml index a0bf061b80fe..fa767440f281 100644 --- a/Documentation/devicetree/bindings/serial/8250.yaml +++ b/Documentation/devicetree/bindings/serial/8250.yaml @@ -66,6 +66,12 @@ properties: - const: nxp,lpc3220-uart - items: - enum: + - exar,xr16l2552 + - exar,xr16l2551 + - exar,xr16l2550 + - const: ns8250 + - items: + - enum: - altr,16550-FIFO32 - altr,16550-FIFO64 - altr,16550-FIFO128 diff --git a/Documentation/devicetree/bindings/serial/8250_omap.yaml b/Documentation/devicetree/bindings/serial/8250_omap.yaml index 1c826fcf5828..70ca61688bb9 100644 --- a/Documentation/devicetree/bindings/serial/8250_omap.yaml +++ b/Documentation/devicetree/bindings/serial/8250_omap.yaml @@ -79,6 +79,7 @@ properties: power-domains: true clock-frequency: true current-speed: true + overrun-throttle-ms: true required: - compatible @@ -90,10 +91,11 @@ additionalProperties: false if: properties: compatible: - oneOf: - - const: ti,omap2-uart - - const: ti,omap3-uart - - const: ti,omap4-uart + contains: + enum: + - ti,omap2-uart + - ti,omap3-uart + - ti,omap4-uart then: properties: diff --git a/Documentation/devicetree/bindings/serial/cdns,uart.txt b/Documentation/devicetree/bindings/serial/cdns,uart.txt deleted file mode 100644 index 4efc560f90ab..000000000000 --- a/Documentation/devicetree/bindings/serial/cdns,uart.txt +++ /dev/null @@ -1,27 +0,0 @@ -Binding for Cadence UART Controller - -Required properties: -- compatible : - Use "xlnx,xuartps","cdns,uart-r1p8" for Zynq-7xxx SoC. - Use "xlnx,zynqmp-uart","cdns,uart-r1p12" for Zynq Ultrascale+ MPSoC. -- reg: Should contain UART controller registers location and length. -- interrupts: Should contain UART controller interrupts. -- clocks: Must contain phandles to the UART clocks - See ../clocks/clock-bindings.txt for details. -- clock-names: Tuple to identify input clocks, must contain "uart_clk" and "pclk" - See ../clocks/clock-bindings.txt for details. - - -Optional properties: -- cts-override : Override the CTS modem status signal. This signal will - always be reported as active instead of being obtained from the modem status - register. Define this if your serial port does not use this pin - -Example: - uart@e0000000 { - compatible = "cdns,uart-r1p8"; - clocks = <&clkc 23>, <&clkc 40>; - clock-names = "uart_clk", "pclk"; - reg = <0xE0000000 0x1000>; - interrupts = <0 27 4>; - }; diff --git a/Documentation/devicetree/bindings/serial/cdns,uart.yaml b/Documentation/devicetree/bindings/serial/cdns,uart.yaml new file mode 100644 index 000000000000..fcdbe6f87e98 --- /dev/null +++ b/Documentation/devicetree/bindings/serial/cdns,uart.yaml @@ -0,0 +1,66 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/serial/cdns,uart.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Cadence UART Controller Device Tree Bindings + +maintainers: + - Michal Simek <michal.simek@xilinx.com> + +allOf: + - $ref: /schemas/serial.yaml# + +properties: + compatible: + oneOf: + - description: UART controller for Zynq-7xxx SoC + items: + - const: xlnx,xuartps + - const: cdns,uart-r1p8 + - description: UART controller for Zynq Ultrascale+ MPSoC + items: + - const: xlnx,zynqmp-uart + - const: cdns,uart-r1p12 + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + clocks: + maxItems: 2 + + clock-names: + items: + - const: uart_clk + - const: pclk + + cts-override: + description: | + Override the CTS modem status signal. This signal will + always be reported as active instead of being obtained + from the modem status register. Define this if your serial + port does not use this pin. + type: boolean + +required: + - compatible + - reg + - interrupts + - clocks + - clock-names + +unevaluatedProperties: false + +examples: + - | + uart0: serial@e0000000 { + compatible = "xlnx,xuartps", "cdns,uart-r1p8"; + clocks = <&clkc 23>, <&clkc 40>; + clock-names = "uart_clk", "pclk"; + reg = <0xE0000000 0x1000>; + interrupts = <0 27 4>; + }; diff --git a/Documentation/devicetree/bindings/serial/mtk-uart.txt b/Documentation/devicetree/bindings/serial/mtk-uart.txt index 64c4fb59acd1..b3a0bfef0d54 100644 --- a/Documentation/devicetree/bindings/serial/mtk-uart.txt +++ b/Documentation/devicetree/bindings/serial/mtk-uart.txt @@ -15,6 +15,7 @@ Required properties: * "mediatek,mt7622-uart" for MT7622 compatible UARTS * "mediatek,mt7623-uart" for MT7623 compatible UARTS * "mediatek,mt7629-uart" for MT7629 compatible UARTS + * "mediatek,mt7986-uart", "mediatek,mt6577-uart" for MT7986 compatible UARTS * "mediatek,mt8127-uart" for MT8127 compatible UARTS * "mediatek,mt8135-uart" for MT8135 compatible UARTS * "mediatek,mt8173-uart" for MT8173 compatible UARTS diff --git a/Documentation/devicetree/bindings/soc/litex/litex,soc-controller.yaml b/Documentation/devicetree/bindings/soc/litex/litex,soc-controller.yaml index c8b57c7fd08c..ecae9fa8561b 100644 --- a/Documentation/devicetree/bindings/soc/litex/litex,soc-controller.yaml +++ b/Documentation/devicetree/bindings/soc/litex/litex,soc-controller.yaml @@ -35,7 +35,6 @@ examples: soc_ctrl0: soc-controller@f0000000 { compatible = "litex,soc-controller"; reg = <0xf0000000 0xc>; - status = "okay"; }; ... diff --git a/Documentation/devicetree/bindings/soc/qcom/qcom,aoss-qmp.txt b/Documentation/devicetree/bindings/soc/qcom/qcom,aoss-qmp.txt deleted file mode 100644 index 783dc81b0f26..000000000000 --- a/Documentation/devicetree/bindings/soc/qcom/qcom,aoss-qmp.txt +++ /dev/null @@ -1,87 +0,0 @@ -Qualcomm Always-On Subsystem side channel binding - -This binding describes the hardware component responsible for side channel -requests to the always-on subsystem (AOSS), used for certain power management -requests that is not handled by the standard RPMh interface. Each client in the -SoC has it's own block of message RAM and IRQ for communication with the AOSS. -The protocol used to communicate in the message RAM is known as Qualcomm -Messaging Protocol (QMP) - -The AOSS side channel exposes control over a set of resources, used to control -a set of debug related clocks and to affect the low power state of resources -related to the secondary subsystems. These resources are exposed as a set of -power-domains. - -- compatible: - Usage: required - Value type: <string> - Definition: must be one of: - "qcom,sc7180-aoss-qmp" - "qcom,sc7280-aoss-qmp" - "qcom,sdm845-aoss-qmp" - "qcom,sm8150-aoss-qmp" - "qcom,sm8250-aoss-qmp" - "qcom,sm8350-aoss-qmp" - -- reg: - Usage: required - Value type: <prop-encoded-array> - Definition: the base address and size of the message RAM for this - client's communication with the AOSS - -- interrupts: - Usage: required - Value type: <prop-encoded-array> - Definition: should specify the AOSS message IRQ for this client - -- mboxes: - Usage: required - Value type: <prop-encoded-array> - Definition: reference to the mailbox representing the outgoing doorbell - in APCS for this client, as described in mailbox/mailbox.txt - -- #clock-cells: - Usage: optional - Value type: <u32> - Definition: must be 0 - The single clock represents the QDSS clock. - -- #power-domain-cells: - Usage: optional - Value type: <u32> - Definition: must be 1 - The provided power-domains are: - CDSP state (0), LPASS state (1), modem state (2), SLPI - state (3), SPSS state (4) and Venus state (5). - -= SUBNODES -The AOSS side channel also provides the controls for three cooling devices, -these are expressed as subnodes of the QMP node. The name of the node is used -to identify the resource and must therefor be "cx", "mx" or "ebi". - -- #cooling-cells: - Usage: optional - Value type: <u32> - Definition: must be 2 - -= EXAMPLE - -The following example represents the AOSS side-channel message RAM and the -mechanism exposing the power-domains, as found in SDM845. - - aoss_qmp: qmp@c300000 { - compatible = "qcom,sdm845-aoss-qmp"; - reg = <0x0c300000 0x100000>; - interrupts = <GIC_SPI 389 IRQ_TYPE_EDGE_RISING>; - mboxes = <&apss_shared 0>; - - #power-domain-cells = <1>; - - cx_cdev: cx { - #cooling-cells = <2>; - }; - - mx_cdev: mx { - #cooling-cells = <2>; - }; - }; diff --git a/Documentation/devicetree/bindings/soc/qcom/qcom,aoss-qmp.yaml b/Documentation/devicetree/bindings/soc/qcom/qcom,aoss-qmp.yaml new file mode 100644 index 000000000000..93e4b737ee1b --- /dev/null +++ b/Documentation/devicetree/bindings/soc/qcom/qcom,aoss-qmp.yaml @@ -0,0 +1,114 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/soc/qcom/qcom,aoss-qmp.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Qualcomm Always-On Subsystem side channel binding + +maintainers: + - Bjorn Andersson <bjorn.andersson@linaro.org> + +description: + This binding describes the hardware component responsible for side channel + requests to the always-on subsystem (AOSS), used for certain power management + requests that is not handled by the standard RPMh interface. Each client in the + SoC has it's own block of message RAM and IRQ for communication with the AOSS. + The protocol used to communicate in the message RAM is known as Qualcomm + Messaging Protocol (QMP) + + The AOSS side channel exposes control over a set of resources, used to control + a set of debug related clocks and to affect the low power state of resources + related to the secondary subsystems. These resources are exposed as a set of + power-domains. + +properties: + compatible: + items: + - enum: + - qcom,sc7180-aoss-qmp + - qcom,sc7280-aoss-qmp + - qcom,sc8180x-aoss-qmp + - qcom,sdm845-aoss-qmp + - qcom,sm8150-aoss-qmp + - qcom,sm8250-aoss-qmp + - qcom,sm8350-aoss-qmp + - const: qcom,aoss-qmp + + reg: + maxItems: 1 + description: + The base address and size of the message RAM for this client's + communication with the AOSS + + interrupts: + maxItems: 1 + description: + Should specify the AOSS message IRQ for this client + + mboxes: + maxItems: 1 + description: + Reference to the mailbox representing the outgoing doorbell in APCS for + this client, as described in mailbox/mailbox.txt + + "#clock-cells": + const: 0 + description: + The single clock represents the QDSS clock. + + "#power-domain-cells": + const: 1 + description: | + The provided power-domains are: + CDSP state (0), LPASS state (1), modem state (2), SLPI + state (3), SPSS state (4) and Venus state (5). + +required: + - compatible + - reg + - interrupts + - mboxes + - "#clock-cells" + +additionalProperties: false + +patternProperties: + "^(cx|mx|ebi)$": + type: object + description: + The AOSS side channel also provides the controls for three cooling devices, + these are expressed as subnodes of the QMP node. The name of the node is + used to identify the resource and must therefor be "cx", "mx" or "ebi". + + properties: + "#cooling-cells": + const: 2 + + required: + - "#cooling-cells" + + additionalProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/arm-gic.h> + + aoss_qmp: qmp@c300000 { + compatible = "qcom,sdm845-aoss-qmp", "qcom,aoss-qmp"; + reg = <0x0c300000 0x100000>; + interrupts = <GIC_SPI 389 IRQ_TYPE_EDGE_RISING>; + mboxes = <&apss_shared 0>; + + #clock-cells = <0>; + #power-domain-cells = <1>; + + cx_cdev: cx { + #cooling-cells = <2>; + }; + + mx_cdev: mx { + #cooling-cells = <2>; + }; + }; +... diff --git a/Documentation/devicetree/bindings/soc/qcom/qcom,geni-se.yaml b/Documentation/devicetree/bindings/soc/qcom/qcom,geni-se.yaml index 4663c2bcad50..a776cd37c297 100644 --- a/Documentation/devicetree/bindings/soc/qcom/qcom,geni-se.yaml +++ b/Documentation/devicetree/bindings/soc/qcom/qcom,geni-se.yaml @@ -51,6 +51,9 @@ properties: interconnect-names: const: qup-core + iommus: + maxItems: 1 + required: - compatible - reg diff --git a/Documentation/devicetree/bindings/soc/qcom/qcom,smd-rpm.yaml b/Documentation/devicetree/bindings/soc/qcom/qcom,smd-rpm.yaml index d511f01fcac6..cc3fe5ed7421 100644 --- a/Documentation/devicetree/bindings/soc/qcom/qcom,smd-rpm.yaml +++ b/Documentation/devicetree/bindings/soc/qcom/qcom,smd-rpm.yaml @@ -39,6 +39,7 @@ properties: - qcom,rpm-msm8996 - qcom,rpm-msm8998 - qcom,rpm-sdm660 + - qcom,rpm-sm6115 - qcom,rpm-sm6125 - qcom,rpm-qcs404 diff --git a/Documentation/devicetree/bindings/soc/rockchip/grf.yaml b/Documentation/devicetree/bindings/soc/rockchip/grf.yaml index 62fa72cfea34..dfebf425ca49 100644 --- a/Documentation/devicetree/bindings/soc/rockchip/grf.yaml +++ b/Documentation/devicetree/bindings/soc/rockchip/grf.yaml @@ -15,7 +15,6 @@ properties: - items: - enum: - rockchip,rk3288-sgrf - - rockchip,rv1108-pmugrf - rockchip,rv1108-usbgrf - const: syscon - items: @@ -41,6 +40,7 @@ properties: - rockchip,rk3568-grf - rockchip,rk3568-pmugrf - rockchip,rv1108-grf + - rockchip,rv1108-pmugrf - const: syscon - const: simple-mfd @@ -198,21 +198,28 @@ allOf: compatible: contains: enum: - - rockchip,px30-pmugrf - rockchip,px30-grf + - rockchip,px30-pmugrf + - rockchip,rk3188-grf - rockchip,rk3228-grf - rockchip,rk3288-grf - rockchip,rk3328-grf - - rockchip,rk3368-pmugrf - rockchip,rk3368-grf - - rockchip,rk3399-pmugrf + - rockchip,rk3368-pmugrf - rockchip,rk3399-grf + - rockchip,rk3399-pmugrf + - rockchip,rk3568-pmugrf + - rockchip,rv1108-grf + - rockchip,rv1108-pmugrf then: properties: io-domains: - description: - Documentation/devicetree/bindings/power/rockchip-io-domain.txt + type: object + + $ref: "/schemas/power/rockchip-io-domain.yaml#" + + unevaluatedProperties: false examples: - | diff --git a/Documentation/devicetree/bindings/soc/ti/ti,pruss.yaml b/Documentation/devicetree/bindings/soc/ti/ti,pruss.yaml index 9790617af1bc..9d128b9e7deb 100644 --- a/Documentation/devicetree/bindings/soc/ti/ti,pruss.yaml +++ b/Documentation/devicetree/bindings/soc/ti/ti,pruss.yaml @@ -68,6 +68,7 @@ properties: - ti,k2g-pruss # for 66AK2G SoC family - ti,am654-icssg # for K3 AM65x SoC family - ti,j721e-icssg # for K3 J721E SoC family + - ti,am642-icssg # for K3 AM64x SoC family reg: maxItems: 1 @@ -84,6 +85,8 @@ properties: dma-ranges: maxItems: 1 + dma-coherent: true + power-domains: description: | This property is as per sci-pm-domain.txt. @@ -231,8 +234,8 @@ patternProperties: description: | Industrial Ethernet Peripheral to manage/generate Industrial Ethernet functions such as time stamping. Each PRUSS has either 1 IEP (on AM335x, - AM437x, AM57xx & 66AK2G SoCs) or 2 IEPs (on K3 AM65x & J721E SoCs ). IEP - is used for creating PTP clocks and generating PPS signals. + AM437x, AM57xx & 66AK2G SoCs) or 2 IEPs (on K3 AM65x, J721E & AM64x SoCs). + IEP is used for creating PTP clocks and generating PPS signals. type: object @@ -323,17 +326,29 @@ additionalProperties: false # - interrupt-controller # - pru -if: - properties: - compatible: - contains: - enum: - - ti,k2g-pruss - - ti,am654-icssg - - ti,j721e-icssg -then: - required: - - power-domains +allOf: + - if: + properties: + compatible: + contains: + enum: + - ti,k2g-pruss + - ti,am654-icssg + - ti,j721e-icssg + - ti,am642-icssg + then: + required: + - power-domains + + - if: + properties: + compatible: + contains: + enum: + - ti,k2g-pruss + then: + required: + - dma-coherent examples: - | diff --git a/Documentation/devicetree/bindings/sound/davinci-mcasp-audio.txt b/Documentation/devicetree/bindings/sound/davinci-mcasp-audio.txt index c483dcec01f8..bd863bd69501 100644 --- a/Documentation/devicetree/bindings/sound/davinci-mcasp-audio.txt +++ b/Documentation/devicetree/bindings/sound/davinci-mcasp-audio.txt @@ -6,6 +6,7 @@ Required properties: "ti,da830-mcasp-audio" : for both DA830 & DA850 platforms "ti,am33xx-mcasp-audio" : for AM33xx platforms (AM33xx, AM43xx, TI81xx) "ti,dra7-mcasp-audio" : for DRA7xx platforms + "ti,omap4-mcasp-audio" : for OMAP4 - reg : Should contain reg specifiers for the entries in the reg-names property. - reg-names : Should contain: diff --git a/Documentation/devicetree/bindings/sound/ics43432.txt b/Documentation/devicetree/bindings/sound/ics43432.txt index b02e3a6c0fef..e6f05f2f6c4e 100644 --- a/Documentation/devicetree/bindings/sound/ics43432.txt +++ b/Documentation/devicetree/bindings/sound/ics43432.txt @@ -1,4 +1,4 @@ -Invensense ICS-43432 MEMS microphone with I2S output. +Invensense ICS-43432-compatible MEMS microphone with I2S output. There are no software configuration options for this device, indeed, the only host connection is the I2S interface. Apart from requirements on clock @@ -8,7 +8,9 @@ contain audio data. A hardware pin determines if the device outputs data on the left or right channel of the I2S frame. Required properties: - - compatible : Must be "invensense,ics43432" + - compatible: should be one of the following. + "invensense,ics43432": For the Invensense ICS43432 + "cui,cmm-4030d-261": For the CUI CMM-4030D-261-I2S-TR Example: diff --git a/Documentation/devicetree/bindings/sound/mt8195-afe-pcm.yaml b/Documentation/devicetree/bindings/sound/mt8195-afe-pcm.yaml new file mode 100644 index 000000000000..53e9434a6d9d --- /dev/null +++ b/Documentation/devicetree/bindings/sound/mt8195-afe-pcm.yaml @@ -0,0 +1,184 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/sound/mt8195-afe-pcm.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Mediatek AFE PCM controller for mt8195 + +maintainers: + - Trevor Wu <trevor.wu@mediatek.com> + +properties: + compatible: + const: mediatek,mt8195-audio + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + mediatek,topckgen: + $ref: "/schemas/types.yaml#/definitions/phandle" + description: The phandle of the mediatek topckgen controller + + power-domains: + maxItems: 1 + + clocks: + items: + - description: 26M clock + - description: audio pll1 clock + - description: audio pll2 clock + - description: clock divider for i2si1_mck + - description: clock divider for i2si2_mck + - description: clock divider for i2so1_mck + - description: clock divider for i2so2_mck + - description: clock divider for dptx_mck + - description: a1sys hoping clock + - description: audio intbus clock + - description: audio hires clock + - description: audio local bus clock + - description: mux for dptx_mck + - description: mux for i2so1_mck + - description: mux for i2so2_mck + - description: mux for i2si1_mck + - description: mux for i2si2_mck + - description: audio infra 26M clock + - description: infra bus clock + + clock-names: + items: + - const: clk26m + - const: apll1_ck + - const: apll2_ck + - const: apll12_div0 + - const: apll12_div1 + - const: apll12_div2 + - const: apll12_div3 + - const: apll12_div9 + - const: a1sys_hp_sel + - const: aud_intbus_sel + - const: audio_h_sel + - const: audio_local_bus_sel + - const: dptx_m_sel + - const: i2so1_m_sel + - const: i2so2_m_sel + - const: i2si1_m_sel + - const: i2si2_m_sel + - const: infra_ao_audio_26m_b + - const: scp_adsp_audiodsp + + mediatek,etdm-in1-chn-disabled: + $ref: /schemas/types.yaml#/definitions/uint8-array + maxItems: 24 + description: Specify which input channel should be disabled. + + mediatek,etdm-in2-chn-disabled: + $ref: /schemas/types.yaml#/definitions/uint8-array + maxItems: 16 + description: Specify which input channel should be disabled. + +patternProperties: + "^mediatek,etdm-in[1-2]-mclk-always-on-rate-hz$": + description: Specify etdm in mclk output rate for always on case. + + "^mediatek,etdm-out[1-3]-mclk-always-on-rate-hz$": + description: Specify etdm out mclk output rate for always on case. + + "^mediatek,etdm-in[1-2]-multi-pin-mode$": + type: boolean + description: if present, the etdm data mode is I2S. + + "^mediatek,etdm-out[1-3]-multi-pin-mode$": + type: boolean + description: if present, the etdm data mode is I2S. + + "^mediatek,etdm-in[1-2]-cowork-source$": + $ref: /schemas/types.yaml#/definitions/uint32 + description: | + etdm modules can share the same external clock pin. Specify + which etdm clock source is required by this etdm in moudule. + enum: + - 0 # etdm1_in + - 1 # etdm2_in + - 2 # etdm1_out + - 3 # etdm2_out + + "^mediatek,etdm-out[1-2]-cowork-source$": + $ref: /schemas/types.yaml#/definitions/uint32 + description: | + etdm modules can share the same external clock pin. Specify + which etdm clock source is required by this etdm out moudule. + enum: + - 0 # etdm1_in + - 1 # etdm2_in + - 2 # etdm1_out + - 3 # etdm2_out + +required: + - compatible + - reg + - interrupts + - mediatek,topckgen + - power-domains + - clocks + - clock-names + +additionalProperties: false + +examples: + - | + #include <dt-bindings/clock/mt8195-clk.h> + #include <dt-bindings/interrupt-controller/arm-gic.h> + #include <dt-bindings/interrupt-controller/irq.h> + #include <dt-bindings/power/mt8195-power.h> + + afe: mt8195-afe-pcm@10890000 { + compatible = "mediatek,mt8195-audio"; + reg = <0x10890000 0x10000>; + interrupts = <GIC_SPI 822 IRQ_TYPE_LEVEL_HIGH 0>; + mediatek,topckgen = <&topckgen>; + power-domains = <&spm MT8195_POWER_DOMAIN_AUDIO>; + clocks = <&clk26m>, + <&topckgen CLK_TOP_APLL1>, + <&topckgen CLK_TOP_APLL2>, + <&topckgen CLK_TOP_APLL12_DIV0>, + <&topckgen CLK_TOP_APLL12_DIV1>, + <&topckgen CLK_TOP_APLL12_DIV2>, + <&topckgen CLK_TOP_APLL12_DIV3>, + <&topckgen CLK_TOP_APLL12_DIV9>, + <&topckgen CLK_TOP_A1SYS_HP_SEL>, + <&topckgen CLK_TOP_AUD_INTBUS_SEL>, + <&topckgen CLK_TOP_AUDIO_H_SEL>, + <&topckgen CLK_TOP_AUDIO_LOCAL_BUS_SEL>, + <&topckgen CLK_TOP_DPTX_M_SEL>, + <&topckgen CLK_TOP_I2SO1_M_SEL>, + <&topckgen CLK_TOP_I2SO2_M_SEL>, + <&topckgen CLK_TOP_I2SI1_M_SEL>, + <&topckgen CLK_TOP_I2SI2_M_SEL>, + <&infracfg_ao CLK_INFRA_AO_AUDIO_26M_B>, + <&scp_adsp CLK_SCP_ADSP_AUDIODSP>; + clock-names = "clk26m", + "apll1_ck", + "apll2_ck", + "apll12_div0", + "apll12_div1", + "apll12_div2", + "apll12_div3", + "apll12_div9", + "a1sys_hp_sel", + "aud_intbus_sel", + "audio_h_sel", + "audio_local_bus_sel", + "dptx_m_sel", + "i2so1_m_sel", + "i2so2_m_sel", + "i2si1_m_sel", + "i2si2_m_sel", + "infra_ao_audio_26m_b", + "scp_adsp_audiodsp"; + }; + +... diff --git a/Documentation/devicetree/bindings/sound/mt8195-mt6359-rt1019-rt5682.yaml b/Documentation/devicetree/bindings/sound/mt8195-mt6359-rt1019-rt5682.yaml new file mode 100644 index 000000000000..20bc0ffd0e34 --- /dev/null +++ b/Documentation/devicetree/bindings/sound/mt8195-mt6359-rt1019-rt5682.yaml @@ -0,0 +1,47 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/sound/mt8195-mt6359-rt1019-rt5682.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Mediatek MT8195 with MT6359, RT1019 and RT5682 ASoC sound card driver + +maintainers: + - Trevor Wu <trevor.wu@mediatek.com> + +description: + This binding describes the MT8195 sound card. + +properties: + compatible: + const: mediatek,mt8195_mt6359_rt1019_rt5682 + + mediatek,platform: + $ref: "/schemas/types.yaml#/definitions/phandle" + description: The phandle of MT8195 ASoC platform. + + mediatek,dptx-codec: + $ref: "/schemas/types.yaml#/definitions/phandle" + description: The phandle of MT8195 Display Port Tx codec node. + + mediatek,hdmi-codec: + $ref: "/schemas/types.yaml#/definitions/phandle" + description: The phandle of MT8195 HDMI codec node. + +additionalProperties: false + +required: + - compatible + - mediatek,platform + +examples: + - | + + sound: mt8195-sound { + compatible = "mediatek,mt8195_mt6359_rt1019_rt5682"; + mediatek,platform = <&afe>; + pinctrl-names = "default"; + pinctrl-0 = <&aud_pins_default>; + }; + +... diff --git a/Documentation/devicetree/bindings/sound/qcom,sm8250.yaml b/Documentation/devicetree/bindings/sound/qcom,sm8250.yaml index 72ad9ab91832..7d57eb91657a 100644 --- a/Documentation/devicetree/bindings/sound/qcom,sm8250.yaml +++ b/Documentation/devicetree/bindings/sound/qcom,sm8250.yaml @@ -15,9 +15,9 @@ description: properties: compatible: - oneOf: - - const: qcom,sm8250-sndcard - - const: qcom,qrb5165-rb5-sndcard + enum: + - qcom,sm8250-sndcard + - qcom,qrb5165-rb5-sndcard audio-routing: $ref: /schemas/types.yaml#/definitions/non-unique-string-array diff --git a/Documentation/devicetree/bindings/sound/realtek,rt1015p.yaml b/Documentation/devicetree/bindings/sound/realtek,rt1015p.yaml index 644b68edf3e1..fdb7f295ef2d 100644 --- a/Documentation/devicetree/bindings/sound/realtek,rt1015p.yaml +++ b/Documentation/devicetree/bindings/sound/realtek,rt1015p.yaml @@ -15,7 +15,9 @@ description: | properties: compatible: - const: realtek,rt1015p + enum: + - realtek,rt1015p + - realtek,rt1019p sdb-gpios: description: diff --git a/Documentation/devicetree/bindings/sound/renesas,rsnd.yaml b/Documentation/devicetree/bindings/sound/renesas,rsnd.yaml index ee936d1aa724..c2930d65728e 100644 --- a/Documentation/devicetree/bindings/sound/renesas,rsnd.yaml +++ b/Documentation/devicetree/bindings/sound/renesas,rsnd.yaml @@ -114,7 +114,7 @@ properties: ports: $ref: /schemas/graph.yaml#/properties/ports - properties: + patternProperties: port(@[0-9a-f]+)?: $ref: audio-graph-port.yaml# unevaluatedProperties: false diff --git a/Documentation/devicetree/bindings/sound/renesas,rz-ssi.yaml b/Documentation/devicetree/bindings/sound/renesas,rz-ssi.yaml new file mode 100644 index 000000000000..414ff8035a4e --- /dev/null +++ b/Documentation/devicetree/bindings/sound/renesas,rz-ssi.yaml @@ -0,0 +1,118 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/sound/renesas,rz-ssi.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Renesas RZ/G2L ASoC Sound Serial Interface (SSIF-2) + +maintainers: + - Biju Das <biju.das.jz@bp.renesas.com> + +properties: + compatible: + items: + - enum: + - renesas,r9a07g044-ssi # RZ/G2{L,LC} + - const: renesas,rz-ssi + + reg: + maxItems: 1 + + interrupts: + maxItems: 4 + + interrupt-names: + items: + - const: int_req + - const: dma_rx + - const: dma_tx + - const: dma_rt + + clocks: + maxItems: 4 + + clock-names: + items: + - const: ssi + - const: ssi_sfr + - const: audio_clk1 + - const: audio_clk2 + + power-domains: + maxItems: 1 + + resets: + maxItems: 1 + + dmas: + minItems: 1 + maxItems: 2 + description: + The first cell represents a phandle to dmac + The second cell specifies the encoded MID/RID values of the SSI port + connected to the DMA client and the slave channel configuration + parameters. + bits[0:9] - Specifies MID/RID value of a SSI channel as below + MID/RID value of SSI rx0 = 0x256 + MID/RID value of SSI tx0 = 0x255 + MID/RID value of SSI rx1 = 0x25a + MID/RID value of SSI tx1 = 0x259 + MID/RID value of SSI rt2 = 0x25f + MID/RID value of SSI rx3 = 0x262 + MID/RID value of SSI tx3 = 0x261 + bit[10] - HIEN = 1, Detects a request in response to the rising edge + of the signal + bit[11] - LVL = 0, Detects based on the edge + bits[12:14] - AM = 2, Bus cycle mode + bit[15] - TM = 0, Single transfer mode + + dma-names: + oneOf: + - items: + - const: tx + - const: rx + - items: + - const: rt + + '#sound-dai-cells': + const: 0 + +required: + - compatible + - reg + - interrupts + - interrupt-names + - clocks + - clock-names + - resets + - '#sound-dai-cells' + +additionalProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/arm-gic.h> + #include <dt-bindings/clock/r9a07g044-cpg.h> + + ssi0: ssi@10049c00 { + compatible = "renesas,r9a07g044-ssi", + "renesas,rz-ssi"; + reg = <0x10049c00 0x400>; + interrupts = <GIC_SPI 326 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 327 IRQ_TYPE_EDGE_RISING>, + <GIC_SPI 328 IRQ_TYPE_EDGE_RISING>, + <GIC_SPI 329 IRQ_TYPE_EDGE_RISING>; + interrupt-names = "int_req", "dma_rx", "dma_tx", "dma_rt"; + clocks = <&cpg CPG_MOD R9A07G044_SSI0_PCLK2>, + <&cpg CPG_MOD R9A07G044_SSI0_PCLK_SFR>, + <&audio_clk1>, + <&audio_clk2>; + clock-names = "ssi", "ssi_sfr", "audio_clk1", "audio_clk2"; + power-domains = <&cpg>; + resets = <&cpg R9A07G044_SSI0_RST_M2_REG>; + dmas = <&dmac 0x2655>, + <&dmac 0x2656>; + dma-names = "tx", "rx"; + #sound-dai-cells = <0>; + }; diff --git a/Documentation/devicetree/bindings/sound/rockchip-i2s.yaml b/Documentation/devicetree/bindings/sound/rockchip-i2s.yaml index 245895b58a2f..5ea16b8ef93f 100644 --- a/Documentation/devicetree/bindings/sound/rockchip-i2s.yaml +++ b/Documentation/devicetree/bindings/sound/rockchip-i2s.yaml @@ -20,7 +20,9 @@ properties: - items: - enum: - rockchip,px30-i2s + - rockchip,rk1808-i2s - rockchip,rk3036-i2s + - rockchip,rk3128-i2s - rockchip,rk3188-i2s - rockchip,rk3228-i2s - rockchip,rk3288-i2s @@ -29,6 +31,7 @@ properties: - rockchip,rk3366-i2s - rockchip,rk3368-i2s - rockchip,rk3399-i2s + - rockchip,rv1126-i2s - const: rockchip,rk3066-i2s reg: @@ -61,6 +64,14 @@ properties: power-domains: maxItems: 1 + reset-names: + items: + - const: reset-m + - const: reset-h + + resets: + maxItems: 2 + rockchip,capture-channels: $ref: /schemas/types.yaml#/definitions/uint32 default: 2 diff --git a/Documentation/devicetree/bindings/sound/rockchip-spdif.yaml b/Documentation/devicetree/bindings/sound/rockchip-spdif.yaml index 62a61b68dfef..d0a24bf928d6 100644 --- a/Documentation/devicetree/bindings/sound/rockchip-spdif.yaml +++ b/Documentation/devicetree/bindings/sound/rockchip-spdif.yaml @@ -23,6 +23,7 @@ properties: - const: rockchip,rk3366-spdif - const: rockchip,rk3368-spdif - const: rockchip,rk3399-spdif + - const: rockchip,rk3568-spdif - items: - enum: - rockchip,rk3188-spdif diff --git a/Documentation/devicetree/bindings/sound/st,stm32-sai.yaml b/Documentation/devicetree/bindings/sound/st,stm32-sai.yaml index 06e83461705c..f97132400bb6 100644 --- a/Documentation/devicetree/bindings/sound/st,stm32-sai.yaml +++ b/Documentation/devicetree/bindings/sound/st,stm32-sai.yaml @@ -180,7 +180,6 @@ examples: pinctrl-names = "default", "sleep"; pinctrl-0 = <&sai2a_pins_a>, <&sai2b_pins_b>; pinctrl-1 = <&sai2a_sleep_pins_a>, <&sai2b_sleep_pins_b>; - status = "okay"; sai2a: audio-controller@4400b004 { #sound-dai-cells = <0>; @@ -190,7 +189,6 @@ examples: dma-names = "tx"; clocks = <&rcc SAI2_K>; clock-names = "sai_ck"; - status = "okay"; }; }; diff --git a/Documentation/devicetree/bindings/sound/ti,j721e-cpb-audio.yaml b/Documentation/devicetree/bindings/sound/ti,j721e-cpb-audio.yaml index ec06789b21df..6806f53a4aed 100644 --- a/Documentation/devicetree/bindings/sound/ti,j721e-cpb-audio.yaml +++ b/Documentation/devicetree/bindings/sound/ti,j721e-cpb-audio.yaml @@ -127,8 +127,6 @@ examples: compatible = "ti,j721e-cpb-audio"; model = "j721e-cpb"; - status = "okay"; - ti,cpb-mcasp = <&mcasp10>; ti,cpb-codec = <&pcm3168a_1>; diff --git a/Documentation/devicetree/bindings/sound/ti,j721e-cpb-ivi-audio.yaml b/Documentation/devicetree/bindings/sound/ti,j721e-cpb-ivi-audio.yaml index ee9f960de36b..859d369c71e2 100644 --- a/Documentation/devicetree/bindings/sound/ti,j721e-cpb-ivi-audio.yaml +++ b/Documentation/devicetree/bindings/sound/ti,j721e-cpb-ivi-audio.yaml @@ -119,8 +119,6 @@ examples: compatible = "ti,j721e-cpb-ivi-audio"; model = "j721e-cpb-ivi"; - status = "okay"; - ti,cpb-mcasp = <&mcasp10>; ti,cpb-codec = <&pcm3168a_1>; diff --git a/Documentation/devicetree/bindings/sound/tlv320adcx140.yaml b/Documentation/devicetree/bindings/sound/tlv320adcx140.yaml index 54d64785aad2..d77c8283526d 100644 --- a/Documentation/devicetree/bindings/sound/tlv320adcx140.yaml +++ b/Documentation/devicetree/bindings/sound/tlv320adcx140.yaml @@ -24,10 +24,10 @@ description: | properties: compatible: - oneOf: - - const: ti,tlv320adc3140 - - const: ti,tlv320adc5140 - - const: ti,tlv320adc6140 + enum: + - ti,tlv320adc3140 + - ti,tlv320adc5140 + - ti,tlv320adc6140 reg: maxItems: 1 diff --git a/Documentation/devicetree/bindings/spi/omap-spi.txt b/Documentation/devicetree/bindings/spi/omap-spi.txt deleted file mode 100644 index 487208c256c0..000000000000 --- a/Documentation/devicetree/bindings/spi/omap-spi.txt +++ /dev/null @@ -1,48 +0,0 @@ -OMAP2+ McSPI device - -Required properties: -- compatible : - - "ti,am654-mcspi" for AM654. - - "ti,omap2-mcspi" for OMAP2 & OMAP3. - - "ti,omap4-mcspi" for OMAP4+. -- ti,spi-num-cs : Number of chipselect supported by the instance. -- ti,hwmods: Name of the hwmod associated to the McSPI -- ti,pindir-d0-out-d1-in: Select the D0 pin as output and D1 as - input. The default is D0 as input and - D1 as output. - -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 for each chip select. -- 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 "rxN" and "txN" for RX and TX requests, - respectively, where N equals the chip select number. - -Examples: - -[hwmod populated DMA resources] - -mcspi1: mcspi@1 { - #address-cells = <1>; - #size-cells = <0>; - compatible = "ti,omap4-mcspi"; - ti,hwmods = "mcspi1"; - ti,spi-num-cs = <4>; -}; - -[generic DMA request binding] - -mcspi1: mcspi@1 { - #address-cells = <1>; - #size-cells = <0>; - compatible = "ti,omap4-mcspi"; - ti,hwmods = "mcspi1"; - ti,spi-num-cs = <2>; - dmas = <&edma 42 - &edma 43 - &edma 44 - &edma 45>; - dma-names = "tx0", "rx0", "tx1", "rx1"; -}; diff --git a/Documentation/devicetree/bindings/spi/omap-spi.yaml b/Documentation/devicetree/bindings/spi/omap-spi.yaml new file mode 100644 index 000000000000..e55538186cf6 --- /dev/null +++ b/Documentation/devicetree/bindings/spi/omap-spi.yaml @@ -0,0 +1,117 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/spi/omap-spi.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: SPI controller bindings for OMAP and K3 SoCs + +maintainers: + - Aswath Govindraju <a-govindraju@ti.com> + +allOf: + - $ref: spi-controller.yaml# + +properties: + compatible: + oneOf: + - items: + - enum: + - ti,am654-mcspi + - ti,am4372-mcspi + - const: ti,omap4-mcspi + - items: + - enum: + - ti,omap2-mcspi + - ti,omap4-mcspi + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + clocks: + maxItems: 1 + + power-domains: + maxItems: 1 + + ti,spi-num-cs: + $ref: /schemas/types.yaml#/definitions/uint32 + description: Number of chipselect supported by the instance. + minimum: 1 + maximum: 4 + + ti,hwmods: + $ref: /schemas/types.yaml#/definitions/string + description: + Must be "mcspi<n>", n being the instance number (1-based). + This property is applicable only on legacy platforms mainly omap2/3 + and ti81xx and should not be used on other platforms. + deprecated: true + + ti,pindir-d0-out-d1-in: + description: + Select the D0 pin as output and D1 as input. The default is D0 + as input and D1 as output. + type: boolean + + dmas: + description: + List of DMA specifiers with the controller specific format as + described in the generic DMA client binding. A tx and rx + specifier is required for each chip select. + minItems: 1 + maxItems: 8 + + dma-names: + description: + List of DMA request names. These strings correspond 1:1 with + the DMA sepecifiers listed in dmas. The string names is to be + "rxN" and "txN" for RX and TX requests, respectively. Where N + is the chip select number. + minItems: 1 + maxItems: 8 + +required: + - compatible + - reg + - interrupts + +unevaluatedProperties: false + +if: + properties: + compatible: + oneOf: + - const: ti,omap2-mcspi + - const: ti,omap4-mcspi + +then: + properties: + ti,hwmods: + items: + - pattern: "^mcspi([1-9])$" + +else: + properties: + ti,hwmods: false + +examples: + - | + #include <dt-bindings/interrupt-controller/irq.h> + #include <dt-bindings/interrupt-controller/arm-gic.h> + #include <dt-bindings/soc/ti,sci_pm_domain.h> + + spi@2100000 { + compatible = "ti,am654-mcspi","ti,omap4-mcspi"; + reg = <0x2100000 0x400>; + interrupts = <GIC_SPI 184 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&k3_clks 137 1>; + power-domains = <&k3_pds 137 TI_SCI_PD_EXCLUSIVE>; + #address-cells = <1>; + #size-cells = <0>; + dmas = <&main_udmap 0xc500>, <&main_udmap 0x4500>; + dma-names = "tx0", "rx0"; + }; diff --git a/Documentation/devicetree/bindings/spi/realtek,rtl-spi.yaml b/Documentation/devicetree/bindings/spi/realtek,rtl-spi.yaml index 30a62a211984..2f938c293f70 100644 --- a/Documentation/devicetree/bindings/spi/realtek,rtl-spi.yaml +++ b/Documentation/devicetree/bindings/spi/realtek,rtl-spi.yaml @@ -15,12 +15,12 @@ allOf: properties: compatible: - oneOf: - - const: realtek,rtl8380-spi - - const: realtek,rtl8382-spi - - const: realtek,rtl8391-spi - - const: realtek,rtl8392-spi - - const: realtek,rtl8393-spi + enum: + - realtek,rtl8380-spi + - realtek,rtl8382-spi + - realtek,rtl8391-spi + - realtek,rtl8392-spi + - realtek,rtl8393-spi reg: maxItems: 1 diff --git a/Documentation/devicetree/bindings/spi/rockchip-sfc.yaml b/Documentation/devicetree/bindings/spi/rockchip-sfc.yaml new file mode 100644 index 000000000000..339fb39529f3 --- /dev/null +++ b/Documentation/devicetree/bindings/spi/rockchip-sfc.yaml @@ -0,0 +1,91 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/spi/rockchip-sfc.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Rockchip Serial Flash Controller (SFC) + +maintainers: + - Heiko Stuebner <heiko@sntech.de> + - Chris Morgan <macromorgan@hotmail.com> + +allOf: + - $ref: spi-controller.yaml# + +properties: + compatible: + const: rockchip,sfc + description: + The rockchip sfc controller is a standalone IP with version register, + and the driver can handle all the feature difference inside the IP + depending on the version register. + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + clocks: + items: + - description: Bus Clock + - description: Module Clock + + clock-names: + items: + - const: clk_sfc + - const: hclk_sfc + + power-domains: + maxItems: 1 + + rockchip,sfc-no-dma: + description: Disable DMA and utilize FIFO mode only + type: boolean + +patternProperties: + "^flash@[0-3]$": + type: object + properties: + reg: + minimum: 0 + maximum: 3 + +required: + - compatible + - reg + - interrupts + - clocks + - clock-names + +unevaluatedProperties: false + +examples: + - | + #include <dt-bindings/clock/px30-cru.h> + #include <dt-bindings/interrupt-controller/arm-gic.h> + #include <dt-bindings/power/px30-power.h> + + sfc: spi@ff3a0000 { + compatible = "rockchip,sfc"; + reg = <0xff3a0000 0x4000>; + interrupts = <GIC_SPI 56 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&cru SCLK_SFC>, <&cru HCLK_SFC>; + clock-names = "clk_sfc", "hclk_sfc"; + pinctrl-0 = <&sfc_clk &sfc_cs &sfc_bus2>; + pinctrl-names = "default"; + power-domains = <&power PX30_PD_MMC_NAND>; + #address-cells = <1>; + #size-cells = <0>; + + flash@0 { + compatible = "jedec,spi-nor"; + reg = <0>; + spi-max-frequency = <108000000>; + spi-rx-bus-width = <2>; + spi-tx-bus-width = <2>; + }; + }; + +... diff --git a/Documentation/devicetree/bindings/spi/spi-mt65xx.txt b/Documentation/devicetree/bindings/spi/spi-mt65xx.txt index 4d0e4c15c4ea..2a24969159cc 100644 --- a/Documentation/devicetree/bindings/spi/spi-mt65xx.txt +++ b/Documentation/devicetree/bindings/spi/spi-mt65xx.txt @@ -11,6 +11,7 @@ Required properties: - mediatek,mt8135-spi: for mt8135 platforms - mediatek,mt8173-spi: for mt8173 platforms - mediatek,mt8183-spi: for mt8183 platforms + - mediatek,mt6893-spi: for mt6893 platforms - "mediatek,mt8192-spi", "mediatek,mt6765-spi": for mt8192 platforms - "mediatek,mt8195-spi", "mediatek,mt6765-spi": for mt8195 platforms - "mediatek,mt8516-spi", "mediatek,mt2712-spi": for mt8516 platforms diff --git a/Documentation/devicetree/bindings/spi/spi-sprd-adi.txt b/Documentation/devicetree/bindings/spi/spi-sprd-adi.txt deleted file mode 100644 index 2567c829e2dc..000000000000 --- a/Documentation/devicetree/bindings/spi/spi-sprd-adi.txt +++ /dev/null @@ -1,63 +0,0 @@ -Spreadtrum ADI controller - -ADI is the abbreviation of Anolog-Digital interface, which is used to access -analog chip (such as PMIC) from digital chip. ADI controller follows the SPI -framework for its hardware implementation is alike to SPI bus and its timing -is compatile to SPI timing. - -ADI controller has 50 channels including 2 software read/write channels and -48 hardware channels to access analog chip. For 2 software read/write channels, -users should set ADI registers to access analog chip. For hardware channels, -we can configure them to allow other hardware components to use it independently, -which means we can just link one analog chip address to one hardware channel, -then users can access the mapped analog chip address by this hardware channel -triggered by hardware components instead of ADI software channels. - -Thus we introduce one property named "sprd,hw-channels" to configure hardware -channels, the first value specifies the hardware channel id which is used to -transfer data triggered by hardware automatically, and the second value specifies -the analog chip address where user want to access by hardware components. - -Since we have multi-subsystems will use unique ADI to access analog chip, when -one system is reading/writing data by ADI software channels, that should be under -one hardware spinlock protection to prevent other systems from reading/writing -data by ADI software channels at the same time, or two parallel routine of setting -ADI registers will make ADI controller registers chaos to lead incorrect results. -Then we need one hardware spinlock to synchronize between the multiple subsystems. - -The new version ADI controller supplies multiple master channels for different -subsystem accessing, that means no need to add hardware spinlock to synchronize, -thus change the hardware spinlock support to be optional to keep backward -compatibility. - -Required properties: -- compatible: Should be "sprd,sc9860-adi". -- reg: Offset and length of ADI-SPI controller register space. -- #address-cells: Number of cells required to define a chip select address - on the ADI-SPI bus. Should be set to 1. -- #size-cells: Size of cells required to define a chip select address size - on the ADI-SPI bus. Should be set to 0. - -Optional properties: -- hwlocks: Reference to a phandle of a hwlock provider node. -- hwlock-names: Reference to hwlock name strings defined in the same order - as the hwlocks, should be "adi". -- sprd,hw-channels: This is an array of channel values up to 49 channels. - The first value specifies the hardware channel id which is used to - transfer data triggered by hardware automatically, and the second - value specifies the analog chip address where user want to access - by hardware components. - -SPI slave nodes must be children of the SPI controller node and can contain -properties described in Documentation/devicetree/bindings/spi/spi-bus.txt. - -Example: - adi_bus: spi@40030000 { - compatible = "sprd,sc9860-adi"; - reg = <0 0x40030000 0 0x10000>; - hwlocks = <&hwlock1 0>; - hwlock-names = "adi"; - #address-cells = <1>; - #size-cells = <0>; - sprd,hw-channels = <30 0x8c20>; - }; diff --git a/Documentation/devicetree/bindings/spi/sprd,spi-adi.yaml b/Documentation/devicetree/bindings/spi/sprd,spi-adi.yaml new file mode 100644 index 000000000000..fe014020da69 --- /dev/null +++ b/Documentation/devicetree/bindings/spi/sprd,spi-adi.yaml @@ -0,0 +1,104 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) + +%YAML 1.2 +--- +$id: "http://devicetree.org/schemas/spi/sprd,spi-adi.yaml#" +$schema: "http://devicetree.org/meta-schemas/core.yaml#" + +title: Spreadtrum ADI controller + +maintainers: + - Orson Zhai <orsonzhai@gmail.com> + - Baolin Wang <baolin.wang7@gmail.com> + - Chunyan Zhang <zhang.lyra@gmail.com> + +description: | + ADI is the abbreviation of Anolog-Digital interface, which is used to access + analog chip (such as PMIC) from digital chip. ADI controller follows the SPI + framework for its hardware implementation is alike to SPI bus and its timing + is compatile to SPI timing. + + ADI controller has 50 channels including 2 software read/write channels and + 48 hardware channels to access analog chip. For 2 software read/write channels, + users should set ADI registers to access analog chip. For hardware channels, + we can configure them to allow other hardware components to use it independently, + which means we can just link one analog chip address to one hardware channel, + then users can access the mapped analog chip address by this hardware channel + triggered by hardware components instead of ADI software channels. + + Thus we introduce one property named "sprd,hw-channels" to configure hardware + channels, the first value specifies the hardware channel id which is used to + transfer data triggered by hardware automatically, and the second value specifies + the analog chip address where user want to access by hardware components. + + Since we have multi-subsystems will use unique ADI to access analog chip, when + one system is reading/writing data by ADI software channels, that should be under + one hardware spinlock protection to prevent other systems from reading/writing + data by ADI software channels at the same time, or two parallel routine of setting + ADI registers will make ADI controller registers chaos to lead incorrect results. + Then we need one hardware spinlock to synchronize between the multiple subsystems. + + The new version ADI controller supplies multiple master channels for different + subsystem accessing, that means no need to add hardware spinlock to synchronize, + thus change the hardware spinlock support to be optional to keep backward + compatibility. + +allOf: + - $ref: /spi/spi-controller.yaml# + +properties: + compatible: + enum: + - sprd,sc9860-adi + - sprd,sc9863-adi + - sprd,ums512-adi + + reg: + maxItems: 1 + + hwlocks: + maxItems: 1 + + hwlock-names: + const: adi + + sprd,hw-channels: + $ref: /schemas/types.yaml#/definitions/uint32-matrix + description: A list of hardware channels + minItems: 1 + maxItems: 48 + items: + items: + - description: The hardware channel id which is used to transfer data + triggered by hardware automatically, channel id 0-1 are for software + use, 2-49 are hardware channels. + minimum: 2 + maximum: 49 + - description: The analog chip address where user want to access by + hardware components. + +required: + - compatible + - reg + - '#address-cells' + - '#size-cells' + +unevaluatedProperties: false + +examples: + - | + aon { + #address-cells = <2>; + #size-cells = <2>; + + adi_bus: spi@40030000 { + compatible = "sprd,sc9860-adi"; + reg = <0 0x40030000 0 0x10000>; + hwlocks = <&hwlock1 0>; + hwlock-names = "adi"; + #address-cells = <1>; + #size-cells = <0>; + sprd,hw-channels = <30 0x8c20>; + }; + }; +... diff --git a/Documentation/devicetree/bindings/thermal/qcom-tsens.yaml b/Documentation/devicetree/bindings/thermal/qcom-tsens.yaml index 4a2eaf28e3fd..d3b9e9b600a2 100644 --- a/Documentation/devicetree/bindings/thermal/qcom-tsens.yaml +++ b/Documentation/devicetree/bindings/thermal/qcom-tsens.yaml @@ -48,6 +48,7 @@ properties: - qcom,sc7180-tsens - qcom,sc7280-tsens - qcom,sc8180x-tsens + - qcom,sdm630-tsens - qcom,sdm845-tsens - qcom,sm8150-tsens - qcom,sm8250-tsens diff --git a/Documentation/devicetree/bindings/timer/arm,sp804.yaml b/Documentation/devicetree/bindings/timer/arm,sp804.yaml index 960e2bd66a97..41be7cdab2ec 100644 --- a/Documentation/devicetree/bindings/timer/arm,sp804.yaml +++ b/Documentation/devicetree/bindings/timer/arm,sp804.yaml @@ -23,9 +23,9 @@ select: properties: compatible: contains: - oneOf: - - const: arm,sp804 - - const: hisilicon,sp804 + enum: + - arm,sp804 + - hisilicon,sp804 required: - compatible diff --git a/Documentation/devicetree/bindings/timer/energymicro,efm32-timer.txt b/Documentation/devicetree/bindings/timer/energymicro,efm32-timer.txt deleted file mode 100644 index e502c11b2211..000000000000 --- a/Documentation/devicetree/bindings/timer/energymicro,efm32-timer.txt +++ /dev/null @@ -1,23 +0,0 @@ -* EFM32 timer hardware - -The efm32 Giant Gecko SoCs come with four 16 bit timers. Two counters can be -connected to form a 32 bit counter. Each timer has three Compare/Capture -channels and can be used as PWM or Quadrature Decoder. Available clock sources -are the cpu's HFPERCLK (with a 10-bit prescaler) or an external pin. - -Required properties: -- compatible : Should be "energymicro,efm32-timer" -- reg : Address and length of the register set -- clocks : Should contain a reference to the HFPERCLK - -Optional properties: -- interrupts : Reference to the timer interrupt - -Example: - -timer@40010c00 { - compatible = "energymicro,efm32-timer"; - reg = <0x40010c00 0x400>; - interrupts = <14>; - clocks = <&cmu clk_HFPERCLKTIMER3>; -}; diff --git a/Documentation/devicetree/bindings/timer/rockchip,rk-timer.txt b/Documentation/devicetree/bindings/timer/rockchip,rk-timer.txt deleted file mode 100644 index d65fdce7c7f0..000000000000 --- a/Documentation/devicetree/bindings/timer/rockchip,rk-timer.txt +++ /dev/null @@ -1,27 +0,0 @@ -Rockchip rk timer - -Required properties: -- compatible: should be: - "rockchip,rv1108-timer", "rockchip,rk3288-timer": for Rockchip RV1108 - "rockchip,rk3036-timer", "rockchip,rk3288-timer": for Rockchip RK3036 - "rockchip,rk3066-timer", "rockchip,rk3288-timer": for Rockchip RK3066 - "rockchip,rk3188-timer", "rockchip,rk3288-timer": for Rockchip RK3188 - "rockchip,rk3228-timer", "rockchip,rk3288-timer": for Rockchip RK3228 - "rockchip,rk3229-timer", "rockchip,rk3288-timer": for Rockchip RK3229 - "rockchip,rk3288-timer": for Rockchip RK3288 - "rockchip,rk3368-timer", "rockchip,rk3288-timer": for Rockchip RK3368 - "rockchip,rk3399-timer": for Rockchip RK3399 -- reg: base address of the timer register starting with TIMERS CONTROL register -- interrupts: should contain the interrupts for Timer0 -- clocks : must contain an entry for each entry in clock-names -- clock-names : must include the following entries: - "timer", "pclk" - -Example: - timer: timer@ff810000 { - compatible = "rockchip,rk3288-timer"; - reg = <0xff810000 0x20>; - interrupts = <GIC_SPI 72 IRQ_TYPE_LEVEL_HIGH>; - clocks = <&xin24m>, <&cru PCLK_TIMER>; - clock-names = "timer", "pclk"; - }; diff --git a/Documentation/devicetree/bindings/timer/rockchip,rk-timer.yaml b/Documentation/devicetree/bindings/timer/rockchip,rk-timer.yaml new file mode 100644 index 000000000000..e26ecb5893ae --- /dev/null +++ b/Documentation/devicetree/bindings/timer/rockchip,rk-timer.yaml @@ -0,0 +1,64 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/timer/rockchip,rk-timer.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Rockchip Timer Device Tree Bindings + +maintainers: + - Daniel Lezcano <daniel.lezcano@linaro.org> + +properties: + compatible: + oneOf: + - const: rockchip,rk3288-timer + - const: rockchip,rk3399-timer + - items: + - enum: + - rockchip,rv1108-timer + - rockchip,rk3036-timer + - rockchip,rk3066-timer + - rockchip,rk3188-timer + - rockchip,rk3228-timer + - rockchip,rk3229-timer + - rockchip,rk3288-timer + - rockchip,rk3368-timer + - rockchip,px30-timer + - const: rockchip,rk3288-timer + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + clocks: + minItems: 2 + maxItems: 2 + + clock-names: + items: + - const: pclk + - const: timer + +required: + - compatible + - reg + - interrupts + - clocks + - clock-names + +additionalProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/arm-gic.h> + #include <dt-bindings/clock/rk3288-cru.h> + + timer: timer@ff810000 { + compatible = "rockchip,rk3288-timer"; + reg = <0xff810000 0x20>; + interrupts = <GIC_SPI 72 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&cru PCLK_TIMER>, <&xin24m>; + clock-names = "pclk", "timer"; + }; diff --git a/Documentation/devicetree/bindings/trivial-devices.yaml b/Documentation/devicetree/bindings/trivial-devices.yaml index 919a4bf03a5a..1e4b3464d734 100644 --- a/Documentation/devicetree/bindings/trivial-devices.yaml +++ b/Documentation/devicetree/bindings/trivial-devices.yaml @@ -33,6 +33,8 @@ properties: - ad,ad7414 # ADM9240: Complete System Hardware Monitor for uProcessor-Based Systems - ad,adm9240 + # AD5110 - Nonvolatile Digital Potentiometer + - adi,ad5110 # Analog Devices ADP5585 Keypad Decoder and I/O Expansion - adi,adp5585 # Analog Devices ADP5585 Keypad Decoder and I/O Expansion with support for Row5 @@ -61,6 +63,8 @@ properties: - capella,cm32181 # CM3232: Ambient Light Sensor - capella,cm3232 + # CM3323: Ambient Light Sensor + - capella,cm3323 # High-Precision Digital Thermometer - dallas,ds1631 # Total-Elapsed-Time Recorder with Alarm @@ -143,6 +147,8 @@ properties: - maxim,ds1803-100 # Low-Power, 4-/12-Channel, 2-Wire Serial, 12-Bit ADCs - maxim,max1237 + # Temperature Sensor, I2C interface + - maxim,max1619 # 10-bit 10 kOhm linear programable voltage divider - maxim,max5481 # 10-bit 50 kOhm linear programable voltage divider @@ -269,6 +275,8 @@ properties: - sensirion,sgpc3 # Sensirion multi-pixel gas sensor with I2C interface - sensirion,sgp30 + # Sensirion gas sensor with I2C interface + - sensirion,sgp40 # Sensortek 3 axis accelerometer - sensortek,stk8312 # Sensortek 3 axis accelerometer diff --git a/Documentation/devicetree/bindings/usb/generic-ehci.yaml b/Documentation/devicetree/bindings/usb/generic-ehci.yaml index 8089dc956ba3..8913497624de 100644 --- a/Documentation/devicetree/bindings/usb/generic-ehci.yaml +++ b/Documentation/devicetree/bindings/usb/generic-ehci.yaml @@ -34,6 +34,7 @@ properties: - allwinner,sun6i-a31-ehci - allwinner,sun7i-a20-ehci - allwinner,sun8i-a23-ehci + - allwinner,sun8i-a83t-ehci - allwinner,sun8i-h3-ehci - allwinner,sun8i-r40-ehci - allwinner,sun9i-a80-ehci @@ -142,6 +143,11 @@ properties: iommus: maxItems: 1 + dr_mode: + enum: + - host + - otg + required: - compatible - reg diff --git a/Documentation/devicetree/bindings/usb/generic-ohci.yaml b/Documentation/devicetree/bindings/usb/generic-ohci.yaml index 0f5f6ea702d0..acbf94fa5f74 100644 --- a/Documentation/devicetree/bindings/usb/generic-ohci.yaml +++ b/Documentation/devicetree/bindings/usb/generic-ohci.yaml @@ -24,6 +24,7 @@ properties: - allwinner,sun6i-a31-ohci - allwinner,sun7i-a20-ohci - allwinner,sun8i-a23-ohci + - allwinner,sun8i-a83t-ohci - allwinner,sun8i-h3-ohci - allwinner,sun8i-r40-ohci - allwinner,sun9i-a80-ohci @@ -109,6 +110,11 @@ properties: iommus: maxItems: 1 + dr_mode: + enum: + - host + - otg + required: - compatible - reg diff --git a/Documentation/devicetree/bindings/usb/mediatek,mtk-xhci.yaml b/Documentation/devicetree/bindings/usb/mediatek,mtk-xhci.yaml index 240882b12565..11f7bacd4e2b 100644 --- a/Documentation/devicetree/bindings/usb/mediatek,mtk-xhci.yaml +++ b/Documentation/devicetree/bindings/usb/mediatek,mtk-xhci.yaml @@ -31,6 +31,7 @@ properties: - mediatek,mt8173-xhci - mediatek,mt8183-xhci - mediatek,mt8192-xhci + - mediatek,mt8195-xhci - const: mediatek,mtk-xhci reg: @@ -152,6 +153,11 @@ properties: description: The mask to disable u3ports, bit0 for u3port0, bit1 for u3port1, ... etc + mediatek,u2p-dis-msk: + $ref: /schemas/types.yaml#/definitions/uint32 + description: The mask to disable u2ports, bit0 for u2port0, + bit1 for u2port1, ... etc + "#address-cells": const: 1 diff --git a/Documentation/devicetree/bindings/usb/mediatek,mtu3.yaml b/Documentation/devicetree/bindings/usb/mediatek,mtu3.yaml index dbc7876e0a0b..77db1233516e 100644 --- a/Documentation/devicetree/bindings/usb/mediatek,mtu3.yaml +++ b/Documentation/devicetree/bindings/usb/mediatek,mtu3.yaml @@ -38,7 +38,18 @@ properties: - const: ippc interrupts: - maxItems: 1 + description: + use "interrupts-extended" when the interrupts are connected to the + separate interrupt controllers + minItems: 1 + items: + - description: SSUSB device controller interrupt + - description: optional, wakeup interrupt used to support runtime PM + + interrupt-names: + items: + - const: device + - const: wakeup power-domains: description: A phandle to USB power domain node to control USB's MTCMOS @@ -106,7 +117,7 @@ properties: extcon: deprecated: true description: | - Phandle to the extcon device detecting the IDDIG/VBUS state, neede + Phandle to the extcon device detecting the IDDIG state, needed when supports dual-role mode. It's considered valid for compatibility reasons, not allowed for new bindings, and use "usb-role-switch" property instead. @@ -116,6 +127,10 @@ properties: description: Support role switch. type: boolean + role-switch-default-mode: + enum: [host, peripheral] + default: host + connector: $ref: /connector/usb-connector.yaml# description: @@ -166,6 +181,12 @@ properties: description: The mask to disable u3ports, bit0 for u3port0, bit1 for u3port1, ... etc + mediatek,u2p-dis-msk: + $ref: /schemas/types.yaml#/definitions/uint32 + description: The mask to disable u2ports, bit0 for u2port0, + bit1 for u2port1, ... etc; but can't disable u2port0 if dual role mode + is enabled, so will be skipped in this case. + # Required child node when support dual-role patternProperties: "^usb@[0-9a-f]+$": @@ -178,6 +199,7 @@ patternProperties: dependencies: connector: [ 'usb-role-switch' ] port: [ 'usb-role-switch' ] + role-switch-default-mode: [ 'usb-role-switch' ] wakeup-source: [ 'mediatek,syscon-wakeup' ] required: @@ -230,7 +252,7 @@ examples: }; }; - # Enable/disable device by an input gpio for VBUS pin + # Dual role switch by gpio-usb-b-connector - | #include <dt-bindings/gpio/gpio.h> #include <dt-bindings/power/mt2712-power.h> @@ -244,13 +266,27 @@ examples: power-domains = <&scpsys MT2712_POWER_DOMAIN_USB2>; clocks = <&topckgen CLK_TOP_USB30_SEL>; clock-names = "sys_ck"; - dr_mode = "peripheral"; + dr_mode = "otg"; usb-role-switch; + #address-cells = <1>; + #size-cells = <1>; + ranges; + + host0: usb@11270000 { + compatible = "mediatek,mt2712-xhci", "mediatek,mtk-xhci"; + reg = <0x11270000 0x1000>; + reg-names = "mac"; + interrupts = <GIC_SPI 123 IRQ_TYPE_LEVEL_LOW>; + power-domains = <&scpsys MT2712_POWER_DOMAIN_USB>; + clocks = <&topckgen CLK_TOP_USB30_SEL>, <&clk26m>; + clock-names = "sys_ck", "ref_ck"; + }; connector { compatible = "gpio-usb-b-connector", "usb-b-connector"; type = "micro"; - vbus-gpios = <&pio 13 GPIO_ACTIVE_HIGH>; + id-gpios = <&pio 12 GPIO_ACTIVE_HIGH>; + vbus-supply = <&usb_p0_vbus>; }; }; @@ -268,6 +304,7 @@ examples: wakeup-source; dr_mode = "otg"; usb-role-switch; + role-switch-default-mode = "host"; #address-cells = <1>; #size-cells = <1>; ranges; diff --git a/Documentation/devicetree/bindings/usb/mediatek,musb.yaml b/Documentation/devicetree/bindings/usb/mediatek,musb.yaml index 84ddacfdbe9b..03d62d60ce5f 100644 --- a/Documentation/devicetree/bindings/usb/mediatek,musb.yaml +++ b/Documentation/devicetree/bindings/usb/mediatek,musb.yaml @@ -19,6 +19,7 @@ properties: - enum: - mediatek,mt8516-musb - mediatek,mt2701-musb + - mediatek,mt7623-musb - const: mediatek,mtk-musb reg: diff --git a/Documentation/devicetree/bindings/usb/qcom,dwc3.yaml b/Documentation/devicetree/bindings/usb/qcom,dwc3.yaml index 4e6451789806..e70afc40edb2 100644 --- a/Documentation/devicetree/bindings/usb/qcom,dwc3.yaml +++ b/Documentation/devicetree/bindings/usb/qcom,dwc3.yaml @@ -17,6 +17,7 @@ properties: - qcom,msm8998-dwc3 - qcom,sc7180-dwc3 - qcom,sc7280-dwc3 + - qcom,sdm660-dwc3 - qcom,sdm845-dwc3 - qcom,sdx55-dwc3 - qcom,sm4250-dwc3 diff --git a/Documentation/devicetree/bindings/usb/renesas,usbhs.yaml b/Documentation/devicetree/bindings/usb/renesas,usbhs.yaml index ad73339ffe1d..012fe80a7611 100644 --- a/Documentation/devicetree/bindings/usb/renesas,usbhs.yaml +++ b/Documentation/devicetree/bindings/usb/renesas,usbhs.yaml @@ -17,7 +17,9 @@ properties: - const: renesas,rza1-usbhs - items: - - const: renesas,usbhs-r7s9210 # RZ/A2 + - enum: + - renesas,usbhs-r7s9210 # RZ/A2 + - renesas,usbhs-r9a07g044 # RZ/G2{L,LC} - const: renesas,rza2-usbhs - items: @@ -59,7 +61,8 @@ properties: - description: USB 2.0 clock selector interrupts: - maxItems: 1 + minItems: 1 + maxItems: 4 renesas,buswait: $ref: /schemas/types.yaml#/definitions/uint32 @@ -108,6 +111,25 @@ required: - clocks - interrupts +allOf: + - if: + properties: + compatible: + contains: + const: renesas,usbhs-r9a07g044 + then: + properties: + interrupts: + items: + - description: U2P_IXL_INT + - description: U2P_INT_DMA[0] + - description: U2P_INT_DMA[1] + - description: U2P_INT_DMAERR + else: + properties: + interrupts: + maxItems: 1 + additionalProperties: false examples: diff --git a/Documentation/devicetree/bindings/usb/snps,dwc3.yaml b/Documentation/devicetree/bindings/usb/snps,dwc3.yaml index 41416fbd92aa..078fb7889593 100644 --- a/Documentation/devicetree/bindings/usb/snps,dwc3.yaml +++ b/Documentation/devicetree/bindings/usb/snps,dwc3.yaml @@ -289,10 +289,21 @@ properties: maximum: 16 tx-fifo-resize: - description: Determines if the FIFO *has* to be reallocated - deprecated: true + description: Determines if the TX fifos can be dynamically resized depending + on the number of IN endpoints used and if bursting is supported. This + may help improve bandwidth on platforms with higher system latencies, as + increased fifo space allows for the controller to prefetch data into its + internal memory. type: boolean + tx-fifo-max-num: + description: Specifies the max number of packets the txfifo resizing logic + can account for when higher endpoint bursting is used. (bMaxBurst > 6) The + higher the number, the more fifo space the txfifo resizing logic will + allocate for that endpoint. + $ref: /schemas/types.yaml#/definitions/uint8 + minimum: 3 + snps,incr-burst-type-adjustment: description: Value for INCR burst type of GSBUSCFG0 register, undefined length INCR diff --git a/Documentation/devicetree/bindings/vendor-prefixes.yaml b/Documentation/devicetree/bindings/vendor-prefixes.yaml index 07fb0d25fc15..a867f7102c35 100644 --- a/Documentation/devicetree/bindings/vendor-prefixes.yaml +++ b/Documentation/devicetree/bindings/vendor-prefixes.yaml @@ -271,6 +271,8 @@ patternProperties: description: Shenzen Chuangsiqi Technology Co.,Ltd. "^cubietech,.*": description: Cubietech, Ltd. + "^cui,.*": + description: CUI Devices "^cypress,.*": description: Cypress Semiconductor Corporation "^cznic,.*": @@ -339,6 +341,8 @@ patternProperties: description: eGalax_eMPIA Technology Inc "^einfochips,.*": description: Einfochips + "^eink,.*": + description: E Ink Corporation "^elan,.*": description: Elan Microelectronic Corp. "^element14,.*": @@ -563,6 +567,8 @@ patternProperties: description: ITE Tech. Inc. "^itead,.*": description: ITEAD Intelligent Systems Co.Ltd + "^itian,.*": + description: ITian Corporation "^iwave,.*": description: iWave Systems Technologies Pvt. Ltd. "^jdi,.*": @@ -735,6 +741,8 @@ patternProperties: description: MiraMEMS Sensing Technology Co., Ltd. "^mitsubishi,.*": description: Mitsubishi Electric Corporation + "^mntre,.*": + description: MNT Research GmbH "^modtronix,.*": description: Modtronix Engineering "^mosaixtech,.*": @@ -936,6 +944,8 @@ patternProperties: description: Chengdu Kaixuan Information Technology Co., Ltd. "^qiaodian,.*": description: QiaoDian XianShi Corporation + "^qishenglong,.*": + description: Shenzhen QiShenglong Industrialist Co., Ltd. "^qnap,.*": description: QNAP Systems, Inc. "^radxa,.*": @@ -1066,6 +1076,8 @@ patternProperties: description: Silicon Integrated Systems Corp. "^sitronix,.*": description: Sitronix Technology Corporation + "^skov,.*": + description: SKOV A/S "^skyworks,.*": description: Skyworks Solutions, Inc. "^smartlabs,.*": @@ -1111,6 +1123,10 @@ patternProperties: "^st-ericsson,.*": description: ST-Ericsson deprecated: true + "^storlink,.*": + description: StorLink Semiconductors, Inc. + "^storm,.*": + description: Storm Semiconductor, Inc. "^summit,.*": description: Summit microelectronics "^sunchip,.*": @@ -1143,6 +1159,8 @@ patternProperties: description: TechNexion "^technologic,.*": description: Technologic Systems + "^teltonika,.*": + description: Teltonika Networks "^tempo,.*": description: Tempo Semiconductor "^techstar,.*": @@ -1165,6 +1183,8 @@ patternProperties: description: Tecon Microprocessor Technologies, LLC. "^topeet,.*": description: Topeet + "^topic,.*": + description: Topic Embedded Systems "^toppoly,.*": description: TPO (deprecated, use tpo) deprecated: true @@ -1184,6 +1204,8 @@ patternProperties: description: TPO "^tq,.*": description: TQ-Systems GmbH + "^traverse,.*": + description: Traverse Technologies Australia Pty Ltd "^tronfy,.*": description: Tronfy "^tronsmart,.*": @@ -1268,6 +1290,8 @@ patternProperties: description: Shenzhen whwave Electronics, Inc. "^wi2wi,.*": description: Wi2Wi, Inc. + "^wiligear,.*": + description: Wiligear, Ltd. "^winbond,.*": description: Winbond Electronics corp. "^winstar,.*": diff --git a/Documentation/driver-api/dma-buf.rst b/Documentation/driver-api/dma-buf.rst index 7f21425d9435..f5ac4c90b237 100644 --- a/Documentation/driver-api/dma-buf.rst +++ b/Documentation/driver-api/dma-buf.rst @@ -88,6 +88,9 @@ consider though: - The DMA buffer FD is also pollable, see `Implicit Fence Poll Support`_ below for details. +- The DMA buffer FD also supports a few dma-buf-specific ioctls, see + `DMA Buffer ioctls`_ below for details. + Basic Operation and Device DMA Access ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -106,6 +109,16 @@ Implicit Fence Poll Support .. kernel-doc:: drivers/dma-buf/dma-buf.c :doc: implicit fence polling +DMA-BUF statistics +~~~~~~~~~~~~~~~~~~ +.. kernel-doc:: drivers/dma-buf/dma-buf-sysfs-stats.c + :doc: overview + +DMA Buffer ioctls +~~~~~~~~~~~~~~~~~ + +.. kernel-doc:: include/uapi/linux/dma-buf.h + Kernel Functions and Structures Reference ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/Documentation/driver-api/fpga/fpga-bridge.rst b/Documentation/driver-api/fpga/fpga-bridge.rst index 198aadafd3e7..8d650b4e2ce6 100644 --- a/Documentation/driver-api/fpga/fpga-bridge.rst +++ b/Documentation/driver-api/fpga/fpga-bridge.rst @@ -4,11 +4,11 @@ FPGA Bridge API to implement a new FPGA bridge ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -* struct fpga_bridge — The FPGA Bridge structure -* struct fpga_bridge_ops — Low level Bridge driver ops -* devm_fpga_bridge_create() — Allocate and init a bridge struct -* fpga_bridge_register() — Register a bridge -* fpga_bridge_unregister() — Unregister a bridge +* struct fpga_bridge - The FPGA Bridge structure +* struct fpga_bridge_ops - Low level Bridge driver ops +* devm_fpga_bridge_create() - Allocate and init a bridge struct +* fpga_bridge_register() - Register a bridge +* fpga_bridge_unregister() - Unregister a bridge .. kernel-doc:: include/linux/fpga/fpga-bridge.h :functions: fpga_bridge diff --git a/Documentation/driver-api/fpga/fpga-mgr.rst b/Documentation/driver-api/fpga/fpga-mgr.rst index 917ee22db429..4d926b452cb3 100644 --- a/Documentation/driver-api/fpga/fpga-mgr.rst +++ b/Documentation/driver-api/fpga/fpga-mgr.rst @@ -101,12 +101,12 @@ in state. API for implementing a new FPGA Manager driver ---------------------------------------------- -* ``fpga_mgr_states`` — Values for :c:expr:`fpga_manager->state`. -* struct fpga_manager — the FPGA manager struct -* struct fpga_manager_ops — Low level FPGA manager driver ops -* devm_fpga_mgr_create() — Allocate and init a manager struct -* fpga_mgr_register() — Register an FPGA manager -* fpga_mgr_unregister() — Unregister an FPGA manager +* ``fpga_mgr_states`` - Values for :c:expr:`fpga_manager->state`. +* struct fpga_manager - the FPGA manager struct +* struct fpga_manager_ops - Low level FPGA manager driver ops +* devm_fpga_mgr_create() - Allocate and init a manager struct +* fpga_mgr_register() - Register an FPGA manager +* fpga_mgr_unregister() - Unregister an FPGA manager .. kernel-doc:: include/linux/fpga/fpga-mgr.h :functions: fpga_mgr_states diff --git a/Documentation/driver-api/fpga/fpga-programming.rst b/Documentation/driver-api/fpga/fpga-programming.rst index 002392dab04f..fb4da4240e96 100644 --- a/Documentation/driver-api/fpga/fpga-programming.rst +++ b/Documentation/driver-api/fpga/fpga-programming.rst @@ -84,10 +84,10 @@ will generate that list. Here's some sample code of what to do next:: API for programming an FPGA --------------------------- -* fpga_region_program_fpga() — Program an FPGA -* fpga_image_info() — Specifies what FPGA image to program -* fpga_image_info_alloc() — Allocate an FPGA image info struct -* fpga_image_info_free() — Free an FPGA image info struct +* fpga_region_program_fpga() - Program an FPGA +* fpga_image_info() - Specifies what FPGA image to program +* fpga_image_info_alloc() - Allocate an FPGA image info struct +* fpga_image_info_free() - Free an FPGA image info struct .. kernel-doc:: drivers/fpga/fpga-region.c :functions: fpga_region_program_fpga diff --git a/Documentation/driver-api/fpga/fpga-region.rst b/Documentation/driver-api/fpga/fpga-region.rst index 363a8171ab0a..2636a27c11b2 100644 --- a/Documentation/driver-api/fpga/fpga-region.rst +++ b/Documentation/driver-api/fpga/fpga-region.rst @@ -45,19 +45,19 @@ An example of usage can be seen in the probe function of [#f2]_. API to add a new FPGA region ---------------------------- -* struct fpga_region — The FPGA region struct -* devm_fpga_region_create() — Allocate and init a region struct -* fpga_region_register() — Register an FPGA region -* fpga_region_unregister() — Unregister an FPGA region +* struct fpga_region - The FPGA region struct +* devm_fpga_region_create() - Allocate and init a region struct +* fpga_region_register() - Register an FPGA region +* fpga_region_unregister() - Unregister an FPGA region The FPGA region's probe function will need to get a reference to the FPGA Manager it will be using to do the programming. This usually would happen during the region's probe function. -* fpga_mgr_get() — Get a reference to an FPGA manager, raise ref count -* of_fpga_mgr_get() — Get a reference to an FPGA manager, raise ref count, +* fpga_mgr_get() - Get a reference to an FPGA manager, raise ref count +* of_fpga_mgr_get() - Get a reference to an FPGA manager, raise ref count, given a device node. -* fpga_mgr_put() — Put an FPGA manager +* fpga_mgr_put() - Put an FPGA manager The FPGA region will need to specify which bridges to control while programming the FPGA. The region driver can build a list of bridges during probe time @@ -66,11 +66,11 @@ the list of bridges to program just before programming (:c:expr:`fpga_region->get_bridges`). The FPGA bridge framework supplies the following APIs to handle building or tearing down that list. -* fpga_bridge_get_to_list() — Get a ref of an FPGA bridge, add it to a +* fpga_bridge_get_to_list() - Get a ref of an FPGA bridge, add it to a list -* of_fpga_bridge_get_to_list() — Get a ref of an FPGA bridge, add it to a +* of_fpga_bridge_get_to_list() - Get a ref of an FPGA bridge, add it to a list, given a device node -* fpga_bridges_put() — Given a list of bridges, put them +* fpga_bridges_put() - Given a list of bridges, put them .. kernel-doc:: include/linux/fpga/fpga-region.h :functions: fpga_region diff --git a/Documentation/driver-api/index.rst b/Documentation/driver-api/index.rst index f5a3207aa7fa..c57c609ad2eb 100644 --- a/Documentation/driver-api/index.rst +++ b/Documentation/driver-api/index.rst @@ -85,7 +85,6 @@ available subsections can be seen below. io-mapping io_ordering generic-counter - lightnvm-pblk memory-devices/index men-chameleon-bus ntb diff --git a/Documentation/driver-api/lightnvm-pblk.rst b/Documentation/driver-api/lightnvm-pblk.rst deleted file mode 100644 index 1040ed1cec81..000000000000 --- a/Documentation/driver-api/lightnvm-pblk.rst +++ /dev/null @@ -1,21 +0,0 @@ -pblk: Physical Block Device Target -================================== - -pblk implements a fully associative, host-based FTL that exposes a traditional -block I/O interface. Its primary responsibilities are: - - - Map logical addresses onto physical addresses (4KB granularity) in a - logical-to-physical (L2P) table. - - Maintain the integrity and consistency of the L2P table as well as its - recovery from normal tear down and power outage. - - Deal with controller- and media-specific constrains. - - Handle I/O errors. - - Implement garbage collection. - - Maintain consistency across the I/O stack during synchronization points. - -For more information please refer to: - - http://lightnvm.io - -which maintains updated FAQs, manual pages, technical documentation, tools, -contacts, etc. diff --git a/Documentation/driver-api/media/camera-sensor.rst b/Documentation/driver-api/media/camera-sensor.rst index 7160336aa475..c7d4891bd24e 100644 --- a/Documentation/driver-api/media/camera-sensor.rst +++ b/Documentation/driver-api/media/camera-sensor.rst @@ -3,10 +3,10 @@ Writing camera sensor drivers ============================= -CSI-2 ------ +CSI-2 and parallel (BT.601 and BT.656) busses +--------------------------------------------- -Please see what is written on :ref:`MIPI_CSI_2`. +Please see :ref:`transmitter-receiver`. Handling clocks --------------- @@ -26,15 +26,16 @@ user. ACPI ~~~~ -Read the "clock-frequency" _DSD property to denote the frequency. The driver can -rely on this frequency being used. +Read the ``clock-frequency`` _DSD property to denote the frequency. The driver +can rely on this frequency being used. Devicetree ~~~~~~~~~~ -The currently preferred way to achieve this is using "assigned-clock-rates" -property. See Documentation/devicetree/bindings/clock/clock-bindings.txt for -more information. The driver then gets the frequency using clk_get_rate(). +The currently preferred way to achieve this is using ``assigned-clocks``, +``assigned-clock-parents`` and ``assigned-clock-rates`` properties. See +``Documentation/devicetree/bindings/clock/clock-bindings.txt`` for more +information. The driver then gets the frequency using ``clk_get_rate()``. This approach has the drawback that there's no guarantee that the frequency hasn't been modified directly or indirectly by another driver, or supported by @@ -55,7 +56,7 @@ processing pipeline as one or more sub-devices with different cropping and scaling configurations. The output size of the device is the result of a series of cropping and scaling operations from the device's pixel array's size. -An example of such a driver is the smiapp driver (see drivers/media/i2c/smiapp). +An example of such a driver is the CCS driver (see ``drivers/media/i2c/ccs``). Register list based drivers ~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -67,7 +68,7 @@ level are independent. How a driver picks such configuration is based on the format set on a source pad at the end of the device's internal pipeline. Most sensor drivers are implemented this way, see e.g. -drivers/media/i2c/imx319.c for an example. +``drivers/media/i2c/imx319.c`` for an example. Frame interval configuration ---------------------------- @@ -94,9 +95,10 @@ large variety of devices beyond camera sensors. Devices that have no analogue crop, use the full source image size, i.e. pixel array size. Horizontal and vertical blanking are specified by ``V4L2_CID_HBLANK`` and -``V4L2_CID_VBLANK``, respectively. The unit of these controls are lines. The -pixel rate is specified by ``V4L2_CID_PIXEL_RATE`` in the same sub-device. The -unit of that control is Hz. +``V4L2_CID_VBLANK``, respectively. The unit of the ``V4L2_CID_HBLANK`` control +is pixels and the unit of the ``V4L2_CID_VBLANK`` is lines. The pixel rate in +the sensor's **pixel array** is specified by ``V4L2_CID_PIXEL_RATE`` in the same +sub-device. The unit of that control is pixels per second. Register list based drivers need to implement read-only sub-device nodes for the purpose. Devices that are not register list based need these to configure the @@ -125,14 +127,14 @@ general, the device must be powered on at least when its registers are being accessed and when it is streaming. Existing camera sensor drivers may rely on the old -:c:type:`v4l2_subdev_core_ops`->s_power() callback for bridge or ISP drivers to +struct v4l2_subdev_core_ops->s_power() callback for bridge or ISP drivers to manage their power state. This is however **deprecated**. If you feel you need to begin calling an s_power from an ISP or a bridge driver, instead please add runtime PM support to the sensor driver you are using. Likewise, new drivers should not use s_power. Please see examples in e.g. ``drivers/media/i2c/ov8856.c`` and -``drivers/media/i2c/smiapp/smiapp-core.c``. The two drivers work in both ACPI +``drivers/media/i2c/ccs/ccs-core.c``. The two drivers work in both ACPI and DT based systems. Control framework @@ -149,16 +151,3 @@ used to obtain device's power state after the power state transition: The function returns a non-zero value if it succeeded getting the power count or runtime PM was disabled, in either of which cases the driver may proceed to access the device. - -Controls --------- - -For camera sensors that are connected to a bus where transmitter and receiver -require common configuration set by drivers, such as CSI-2 or parallel (BT.601 -or BT.656) bus, the ``V4L2_CID_LINK_FREQ`` control is mandatory on transmitter -drivers. Receiver drivers can use the ``V4L2_CID_LINK_FREQ`` to query the -frequency used on the bus. - -The transmitter drivers should also implement ``V4L2_CID_PIXEL_RATE`` control in -order to tell the maximum pixel rate to the receiver. This is required on raw -camera sensors. diff --git a/Documentation/driver-api/media/cec-core.rst b/Documentation/driver-api/media/cec-core.rst index 56345eae9a26..c6194ee81c41 100644 --- a/Documentation/driver-api/media/cec-core.rst +++ b/Documentation/driver-api/media/cec-core.rst @@ -130,9 +130,12 @@ To enable/disable the hardware:: int (*adap_enable)(struct cec_adapter *adap, bool enable); This callback enables or disables the CEC hardware. Enabling the CEC hardware -means powering it up in a state where no logical addresses are claimed. This -op assumes that the physical address (adap->phys_addr) is valid when enable is -true and will not change while the CEC adapter remains enabled. The initial +means powering it up in a state where no logical addresses are claimed. The +physical address will always be valid if CEC_CAP_NEEDS_HPD is set. If that +capability is not set, then the physical address can change while the CEC +hardware is enabled. CEC drivers should not set CEC_CAP_NEEDS_HPD unless +the hardware design requires that as this will make it impossible to wake +up displays that pull the HPD low when in standby mode. The initial state of the CEC adapter after calling cec_allocate_adapter() is disabled. Note that adap_enable must return 0 if enable is false. diff --git a/Documentation/driver-api/media/csi2.rst b/Documentation/driver-api/media/csi2.rst deleted file mode 100644 index 11c52b0be8b8..000000000000 --- a/Documentation/driver-api/media/csi2.rst +++ /dev/null @@ -1,94 +0,0 @@ -.. SPDX-License-Identifier: GPL-2.0 - -.. _MIPI_CSI_2: - -MIPI CSI-2 -========== - -CSI-2 is a data bus intended for transferring images from cameras to -the host SoC. It is defined by the `MIPI alliance`_. - -.. _`MIPI alliance`: http://www.mipi.org/ - -Media bus formats ------------------ - -See :ref:`v4l2-mbus-pixelcode` for details on which media bus formats should -be used for CSI-2 interfaces. - -Transmitter drivers -------------------- - -CSI-2 transmitter, such as a sensor or a TV tuner, drivers need to -provide the CSI-2 receiver with information on the CSI-2 bus -configuration. These include the V4L2_CID_LINK_FREQ and -V4L2_CID_PIXEL_RATE controls and -(:c:type:`v4l2_subdev_video_ops`->s_stream() callback). These -interface elements must be present on the sub-device represents the -CSI-2 transmitter. - -The V4L2_CID_LINK_FREQ control is used to tell the receiver driver the -frequency (and not the symbol rate) of the link. The V4L2_CID_PIXEL_RATE -control may be used by the receiver to obtain the pixel rate the transmitter -uses. The :c:type:`v4l2_subdev_video_ops`->s_stream() callback provides an -ability to start and stop the stream. - -The value of the V4L2_CID_PIXEL_RATE is calculated as follows:: - - pixel_rate = link_freq * 2 * nr_of_lanes * 16 / k / bits_per_sample - -where - -.. list-table:: variables in pixel rate calculation - :header-rows: 1 - - * - variable or constant - - description - * - link_freq - - The value of the V4L2_CID_LINK_FREQ integer64 menu item. - * - nr_of_lanes - - Number of data lanes used on the CSI-2 link. This can - be obtained from the OF endpoint configuration. - * - 2 - - Two bits are transferred per clock cycle per lane. - * - bits_per_sample - - Number of bits per sample. - * - k - - 16 for D-PHY and 7 for C-PHY - -The transmitter drivers must, if possible, configure the CSI-2 -transmitter to *LP-11 mode* whenever the transmitter is powered on but -not active, and maintain *LP-11 mode* until stream on. Only at stream -on should the transmitter activate the clock on the clock lane and -transition to *HS mode*. - -Some transmitters do this automatically but some have to be explicitly -programmed to do so, and some are unable to do so altogether due to -hardware constraints. - -Stopping the transmitter -^^^^^^^^^^^^^^^^^^^^^^^^ - -A transmitter stops sending the stream of images as a result of -calling the ``.s_stream()`` callback. Some transmitters may stop the -stream at a frame boundary whereas others stop immediately, -effectively leaving the current frame unfinished. The receiver driver -should not make assumptions either way, but function properly in both -cases. - -Receiver drivers ----------------- - -Before the receiver driver may enable the CSI-2 transmitter by using -the :c:type:`v4l2_subdev_video_ops`->s_stream(), it must have powered -the transmitter up by using the -:c:type:`v4l2_subdev_core_ops`->s_power() callback. This may take -place either indirectly by using :c:func:`v4l2_pipeline_pm_get` or -directly. - -Formats -------- - -The media bus pixel codes document parallel formats. Should the pixel data be -transported over a serial bus, the media bus pixel code that describes a -parallel format that transfers a sample on a single clock cycle is used. diff --git a/Documentation/driver-api/media/index.rst b/Documentation/driver-api/media/index.rst index 813d7db59da7..08e206567408 100644 --- a/Documentation/driver-api/media/index.rst +++ b/Documentation/driver-api/media/index.rst @@ -37,7 +37,7 @@ Documentation/userspace-api/media/index.rst rc-core mc-core cec-core - csi2 + tx-rx camera-sensor drivers/index diff --git a/Documentation/driver-api/media/tx-rx.rst b/Documentation/driver-api/media/tx-rx.rst new file mode 100644 index 000000000000..e1e9258dd862 --- /dev/null +++ b/Documentation/driver-api/media/tx-rx.rst @@ -0,0 +1,133 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. _transmitter-receiver: + +Pixel data transmitter and receiver drivers +=========================================== + +V4L2 supports various devices that transmit and receive pixel data. Examples of +these devices include a camera sensor, a TV tuner and a parallel or a CSI-2 +receiver in an SoC. + +Bus types +--------- + +The following busses are the most common. This section discusses these two only. + +MIPI CSI-2 +^^^^^^^^^^ + +CSI-2 is a data bus intended for transferring images from cameras to +the host SoC. It is defined by the `MIPI alliance`_. + +.. _`MIPI alliance`: https://www.mipi.org/ + +Parallel +^^^^^^^^ + +`BT.601`_ and `BT.656`_ are the most common parallel busses. + +.. _`BT.601`: https://en.wikipedia.org/wiki/Rec._601 +.. _`BT.656`: https://en.wikipedia.org/wiki/ITU-R_BT.656 + +Transmitter drivers +------------------- + +Transmitter drivers generally need to provide the receiver drivers with the +configuration of the transmitter. What is required depends on the type of the +bus. These are common for both busses. + +Media bus pixel code +^^^^^^^^^^^^^^^^^^^^ + +See :ref:`v4l2-mbus-pixelcode`. + +Link frequency +^^^^^^^^^^^^^^ + +The :ref:`V4L2_CID_LINK_FREQ <v4l2-cid-link-freq>` control is used to tell the +receiver the frequency of the bus (i.e. it is not the same as the symbol rate). + +``.s_stream()`` callback +^^^^^^^^^^^^^^^^^^^^^^^^ + +The struct struct v4l2_subdev_video_ops->s_stream() callback is used by the +receiver driver to control the transmitter driver's streaming state. + + +CSI-2 transmitter drivers +------------------------- + +Pixel rate +^^^^^^^^^^ + +The pixel rate on the bus is calculated as follows:: + + pixel_rate = link_freq * 2 * nr_of_lanes * 16 / k / bits_per_sample + +where + +.. list-table:: variables in pixel rate calculation + :header-rows: 1 + + * - variable or constant + - description + * - link_freq + - The value of the ``V4L2_CID_LINK_FREQ`` integer64 menu item. + * - nr_of_lanes + - Number of data lanes used on the CSI-2 link. This can + be obtained from the OF endpoint configuration. + * - 2 + - Data is transferred on both rising and falling edge of the signal. + * - bits_per_sample + - Number of bits per sample. + * - k + - 16 for D-PHY and 7 for C-PHY + +.. note:: + + The pixel rate calculated this way is **not** the same thing as the + pixel rate on the camera sensor's pixel array which is indicated by the + :ref:`V4L2_CID_PIXEL_RATE <v4l2-cid-pixel-rate>` control. + +LP-11 and LP-111 modes +^^^^^^^^^^^^^^^^^^^^^^ + +As part of transitioning to high speed mode, a CSI-2 transmitter typically +briefly sets the bus to LP-11 or LP-111 state, depending on the PHY. This period +may be as short as 100 µs, during which the receiver observes this state and +proceeds its own part of high speed mode transition. + +Most receivers are capable of autonomously handling this once the software has +configured them to do so, but there are receivers which require software +involvement in observing LP-11 or LP-111 state. 100 µs is a brief period to hit +in software, especially when there is no interrupt telling something is +happening. + +One way to address this is to configure the transmitter side explicitly to LP-11 +or LP-111 mode, which requires support from the transmitter hardware. This is +not universally available. Many devices return to this state once streaming is +stopped while the state after power-on is LP-00 or LP-000. + +The ``.pre_streamon()`` callback may be used to prepare a transmitter for +transitioning to streaming state, but not yet start streaming. Similarly, the +``.post_streamoff()`` callback is used to undo what was done by the +``.pre_streamon()`` callback. The caller of ``.pre_streamon()`` is thus required +to call ``.post_streamoff()`` for each successful call of ``.pre_streamon()``. + +In the context of CSI-2, the ``.pre_streamon()`` callback is used to transition +the transmitter to the LP-11 or LP-111 mode. This also requires powering on the +device, so this should be only done when it is needed. + +Receiver drivers that do not need explicit LP-11 or LP-111 mode setup are waived +from calling the two callbacks. + +Stopping the transmitter +^^^^^^^^^^^^^^^^^^^^^^^^ + +A transmitter stops sending the stream of images as a result of +calling the ``.s_stream()`` callback. Some transmitters may stop the +stream at a frame boundary whereas others stop immediately, +effectively leaving the current frame unfinished. The receiver driver +should not make assumptions either way, but function properly in both +cases. diff --git a/Documentation/driver-api/nfc/nfc-hci.rst b/Documentation/driver-api/nfc/nfc-hci.rst index eb8a1a14e919..f10fe53aa9fe 100644 --- a/Documentation/driver-api/nfc/nfc-hci.rst +++ b/Documentation/driver-api/nfc/nfc-hci.rst @@ -181,7 +181,7 @@ xmit_from_hci(): The llc must be registered with nfc before it can be used. Do that by calling:: - nfc_llc_register(const char *name, struct nfc_llc_ops *ops); + nfc_llc_register(const char *name, const struct nfc_llc_ops *ops); Again, note that the llc does not handle the physical link. It is thus very easy to mix any physical link with any llc for a given chip driver. diff --git a/Documentation/driver-api/thermal/nouveau_thermal.rst b/Documentation/driver-api/thermal/nouveau_thermal.rst index 79ece266cf6d..aa10db6df309 100644 --- a/Documentation/driver-api/thermal/nouveau_thermal.rst +++ b/Documentation/driver-api/thermal/nouveau_thermal.rst @@ -90,7 +90,7 @@ Bug reports ----------- Thermal management on Nouveau is new and may not work on all cards. If you have -inquiries, please ping mupuf on IRC (#nouveau, freenode). +inquiries, please ping mupuf on IRC (#nouveau, OFTC). Bug reports should be filled on Freedesktop's bug tracker. Please follow https://nouveau.freedesktop.org/wiki/Bugs diff --git a/Documentation/driver-api/vfio.rst b/Documentation/driver-api/vfio.rst index 606eed8823ce..c663b6f97825 100644 --- a/Documentation/driver-api/vfio.rst +++ b/Documentation/driver-api/vfio.rst @@ -255,11 +255,13 @@ vfio_unregister_group_dev() respectively:: void vfio_init_group_dev(struct vfio_device *device, struct device *dev, const struct vfio_device_ops *ops); + void vfio_uninit_group_dev(struct vfio_device *device); int vfio_register_group_dev(struct vfio_device *device); void vfio_unregister_group_dev(struct vfio_device *device); The driver should embed the vfio_device in its own structure and call -vfio_init_group_dev() to pre-configure it before going to registration. +vfio_init_group_dev() to pre-configure it before going to registration +and call vfio_uninit_group_dev() after completing the un-registration. vfio_register_group_dev() indicates to the core to begin tracking the iommu_group of the specified dev and register the dev as owned by a VFIO bus driver. Once vfio_register_group_dev() returns it is possible for userspace to diff --git a/Documentation/fault-injection/fault-injection.rst b/Documentation/fault-injection/fault-injection.rst index f47d05ed0d94..4a25c5eb6f07 100644 --- a/Documentation/fault-injection/fault-injection.rst +++ b/Documentation/fault-injection/fault-injection.rst @@ -24,6 +24,10 @@ Available fault injection capabilities injects futex deadlock and uaddr fault errors. +- fail_sunrpc + + injects kernel RPC client and server failures. + - fail_make_request injects disk IO errors on devices permitted by setting @@ -151,6 +155,20 @@ configuration of fault-injection capabilities. default is 'N', setting it to 'Y' will disable failure injections when dealing with private (address space) futexes. +- /sys/kernel/debug/fail_sunrpc/ignore-client-disconnect: + + Format: { 'Y' | 'N' } + + default is 'N', setting it to 'Y' will disable disconnect + injection on the RPC client. + +- /sys/kernel/debug/fail_sunrpc/ignore-server-disconnect: + + Format: { 'Y' | 'N' } + + default is 'N', setting it to 'Y' will disable disconnect + injection on the RPC server. + - /sys/kernel/debug/fail_function/inject: Format: { 'function-name' | '!function-name' | '' } diff --git a/Documentation/fault-injection/provoke-crashes.rst b/Documentation/fault-injection/provoke-crashes.rst index a20ba5d93932..3abe84225613 100644 --- a/Documentation/fault-injection/provoke-crashes.rst +++ b/Documentation/fault-injection/provoke-crashes.rst @@ -29,8 +29,7 @@ recur_count cpoint_name Where in the kernel to trigger the action. It can be one of INT_HARDWARE_ENTRY, INT_HW_IRQ_EN, INT_TASKLET_ENTRY, - FS_DEVRW, MEM_SWAPOUT, TIMERADD, SCSI_DISPATCH_CMD, - IDE_CORE_CP, or DIRECT + FS_DEVRW, MEM_SWAPOUT, TIMERADD, SCSI_QUEUE_RQ, or DIRECT. cpoint_type Indicates the action to be taken on hitting the crash point. diff --git a/Documentation/features/vm/THP/arch-support.txt b/Documentation/features/vm/THP/arch-support.txt index e8238cb2a4da..7dbd6967b37e 100644 --- a/Documentation/features/vm/THP/arch-support.txt +++ b/Documentation/features/vm/THP/arch-support.txt @@ -22,7 +22,7 @@ | openrisc: | .. | | parisc: | TODO | | powerpc: | ok | - | riscv: | TODO | + | riscv: | ok | | s390: | ok | | sh: | .. | | sparc: | ok | diff --git a/Documentation/filesystems/cifs/index.rst b/Documentation/filesystems/cifs/index.rst new file mode 100644 index 000000000000..1c8597a679ab --- /dev/null +++ b/Documentation/filesystems/cifs/index.rst @@ -0,0 +1,10 @@ +=============================== +CIFS +=============================== + + +.. toctree:: + :maxdepth: 1 + + ksmbd + cifsroot diff --git a/Documentation/filesystems/cifs/ksmbd.rst b/Documentation/filesystems/cifs/ksmbd.rst new file mode 100644 index 000000000000..a1326157d53f --- /dev/null +++ b/Documentation/filesystems/cifs/ksmbd.rst @@ -0,0 +1,165 @@ +.. SPDX-License-Identifier: GPL-2.0 + +========================== +KSMBD - SMB3 Kernel Server +========================== + +KSMBD is a linux kernel server which implements SMB3 protocol in kernel space +for sharing files over network. + +KSMBD architecture +================== + +The subset of performance related operations belong in kernelspace and +the other subset which belong to operations which are not really related with +performance in userspace. So, DCE/RPC management that has historically resulted +into number of buffer overflow issues and dangerous security bugs and user +account management are implemented in user space as ksmbd.mountd. +File operations that are related with performance (open/read/write/close etc.) +in kernel space (ksmbd). This also allows for easier integration with VFS +interface for all file operations. + +ksmbd (kernel daemon) +--------------------- + +When the server daemon is started, It starts up a forker thread +(ksmbd/interface name) at initialization time and open a dedicated port 445 +for listening to SMB requests. Whenever new clients make request, Forker +thread will accept the client connection and fork a new thread for dedicated +communication channel between the client and the server. It allows for parallel +processing of SMB requests(commands) from clients as well as allowing for new +clients to make new connections. Each instance is named ksmbd/1~n(port number) +to indicate connected clients. Depending on the SMB request types, each new +thread can decide to pass through the commands to the user space (ksmbd.mountd), +currently DCE/RPC commands are identified to be handled through the user space. +To further utilize the linux kernel, it has been chosen to process the commands +as workitems and to be executed in the handlers of the ksmbd-io kworker threads. +It allows for multiplexing of the handlers as the kernel take care of initiating +extra worker threads if the load is increased and vice versa, if the load is +decreased it destroys the extra worker threads. So, after connection is +established with client. Dedicated ksmbd/1..n(port number) takes complete +ownership of receiving/parsing of SMB commands. Each received command is worked +in parallel i.e., There can be multiple clients commands which are worked in +parallel. After receiving each command a separated kernel workitem is prepared +for each command which is further queued to be handled by ksmbd-io kworkers. +So, each SMB workitem is queued to the kworkers. This allows the benefit of load +sharing to be managed optimally by the default kernel and optimizing client +performance by handling client commands in parallel. + +ksmbd.mountd (user space daemon) +-------------------------------- + +ksmbd.mountd is userspace process to, transfer user account and password that +are registered using ksmbd.adduser(part of utils for user space). Further it +allows sharing information parameters that parsed from smb.conf to ksmbd in +kernel. For the execution part it has a daemon which is continuously running +and connected to the kernel interface using netlink socket, it waits for the +requests(dcerpc and share/user info). It handles RPC calls (at a minimum few +dozen) that are most important for file server from NetShareEnum and +NetServerGetInfo. Complete DCE/RPC response is prepared from the user space +and passed over to the associated kernel thread for the client. + + +KSMBD Feature Status +==================== + +============================== ================================================= +Feature name Status +============================== ================================================= +Dialects Supported. SMB2.1 SMB3.0, SMB3.1.1 dialects + (intentionally excludes security vulnerable SMB1 + dialect). +Auto Negotiation Supported. +Compound Request Supported. +Oplock Cache Mechanism Supported. +SMB2 leases(v1 lease) Supported. +Directory leases(v2 lease) Planned for future. +Multi-credits Supported. +NTLM/NTLMv2 Supported. +HMAC-SHA256 Signing Supported. +Secure negotiate Supported. +Signing Update Supported. +Pre-authentication integrity Supported. +SMB3 encryption(CCM, GCM) Supported. (CCM and GCM128 supported, GCM256 in + progress) +SMB direct(RDMA) Partially Supported. SMB3 Multi-channel is + required to connect to Windows client. +SMB3 Multi-channel Partially Supported. Planned to implement + replay/retry mechanisms for future. +SMB3.1.1 POSIX extension Supported. +ACLs Partially Supported. only DACLs available, SACLs + (auditing) is planned for the future. For + ownership (SIDs) ksmbd generates random subauth + values(then store it to disk) and use uid/gid + get from inode as RID for local domain SID. + The current acl implementation is limited to + standalone server, not a domain member. + Integration with Samba tools is being worked on + to allow future support for running as a domain + member. +Kerberos Supported. +Durable handle v1,v2 Planned for future. +Persistent handle Planned for future. +SMB2 notify Planned for future. +Sparse file support Supported. +DCE/RPC support Partially Supported. a few calls(NetShareEnumAll, + NetServerGetInfo, SAMR, LSARPC) that are needed + for file server handled via netlink interface + from ksmbd.mountd. Additional integration with + Samba tools and libraries via upcall is being + investigated to allow support for additional + DCE/RPC management calls (and future support + for Witness protocol e.g.) +ksmbd/nfsd interoperability Planned for future. The features that ksmbd + support are Leases, Notify, ACLs and Share modes. +============================== ================================================= + + +How to run +========== + +1. Download ksmbd-tools and compile them. + - https://github.com/cifsd-team/ksmbd-tools + +2. Create user/password for SMB share. + + # mkdir /etc/ksmbd/ + # ksmbd.adduser -a <Enter USERNAME for SMB share access> + +3. Create /etc/ksmbd/smb.conf file, add SMB share in smb.conf file + - Refer smb.conf.example and + https://github.com/cifsd-team/ksmbd-tools/blob/master/Documentation/configuration.txt + +4. Insert ksmbd.ko module + + # insmod ksmbd.ko + +5. Start ksmbd user space daemon + # ksmbd.mountd + +6. Access share from Windows or Linux using CIFS + +Shutdown KSMBD +============== + +1. kill user and kernel space daemon + # sudo ksmbd.control -s + +How to turn debug print on +========================== + +Each layer +/sys/class/ksmbd-control/debug + +1. Enable all component prints + # sudo ksmbd.control -d "all" + +2. Enable one of components(smb, auth, vfs, oplock, ipc, conn, rdma) + # sudo ksmbd.control -d "smb" + +3. Show what prints are enable. + # cat/sys/class/ksmbd-control/debug + [smb] auth vfs oplock ipc conn [rdma] + +4. Disable prints: + If you try the selected component once more, It is disabled without brackets. diff --git a/Documentation/filesystems/erofs.rst b/Documentation/filesystems/erofs.rst index 832839fcf4c3..b97579b7d8fb 100644 --- a/Documentation/filesystems/erofs.rst +++ b/Documentation/filesystems/erofs.rst @@ -84,6 +84,9 @@ cache_strategy=%s Select a strategy for cached decompression from now on: It still does in-place I/O decompression for the rest compressed physical clusters. ========== ============================================= +dax={always,never} Use direct access (no page cache). See + Documentation/filesystems/dax.rst. +dax A legacy option which is an alias for ``dax=always``. =================== ========================================================= On-disk details @@ -153,13 +156,14 @@ may not. All metadatas can be now observed in two different spaces (views): Xattrs, extents, data inline are followed by the corresponding inode with proper alignment, and they could be optional for different data mappings. - _currently_ total 4 valid data mappings are supported: + _currently_ total 5 data layouts are supported: == ==================================================================== 0 flat file data without data inline (no extent); 1 fixed-sized output data compression (with non-compacted indexes); 2 flat file data with tail packing data inline (no extent); - 3 fixed-sized output data compression (with compacted indexes, v5.3+). + 3 fixed-sized output data compression (with compacted indexes, v5.3+); + 4 chunk-based file (v5.15+). == ==================================================================== The size of the optional xattrs is indicated by i_xattr_count in inode @@ -210,6 +214,17 @@ Note that apart from the offset of the first filename, nameoff0 also indicates the total number of directory entries in this block since it is no need to introduce another on-disk field at all. +Chunk-based file +---------------- +In order to support chunk-based data deduplication, a new inode data layout has +been supported since Linux v5.15: Files are split in equal-sized data chunks +with ``extents`` area of the inode metadata indicating how to get the chunk +data: these can be simply as a 4-byte block address array or in the 8-byte +chunk index form (see struct erofs_inode_chunk_index in erofs_fs.h for more +details.) + +By the way, chunk-based files are all uncompressed for now. + Data compression ---------------- EROFS implements LZ4 fixed-sized output compression which generates fixed-sized diff --git a/Documentation/filesystems/ext4/globals.rst b/Documentation/filesystems/ext4/globals.rst index 368bf7662b96..b17418974fd3 100644 --- a/Documentation/filesystems/ext4/globals.rst +++ b/Documentation/filesystems/ext4/globals.rst @@ -11,3 +11,4 @@ have static metadata at fixed locations. .. include:: bitmaps.rst .. include:: mmp.rst .. include:: journal.rst +.. include:: orphan.rst diff --git a/Documentation/filesystems/ext4/inodes.rst b/Documentation/filesystems/ext4/inodes.rst index a65baffb4ebf..6c5ce666e63f 100644 --- a/Documentation/filesystems/ext4/inodes.rst +++ b/Documentation/filesystems/ext4/inodes.rst @@ -498,11 +498,11 @@ structure -- inode change time (ctime), access time (atime), data modification time (mtime), and deletion time (dtime). The four fields are 32-bit signed integers that represent seconds since the Unix epoch (1970-01-01 00:00:00 GMT), which means that the fields will overflow in -January 2038. For inodes that are not linked from any directory but are -still open (orphan inodes), the dtime field is overloaded for use with -the orphan list. The superblock field ``s_last_orphan`` points to the -first inode in the orphan list; dtime is then the number of the next -orphaned inode, or zero if there are no more orphans. +January 2038. If the filesystem does not have orphan_file feature, inodes +that are not linked from any directory but are still open (orphan inodes) have +the dtime field overloaded for use with the orphan list. The superblock field +``s_last_orphan`` points to the first inode in the orphan list; dtime is then +the number of the next orphaned inode, or zero if there are no more orphans. If the inode structure size ``sb->s_inode_size`` is larger than 128 bytes and the ``i_inode_extra`` field is large enough to encompass the diff --git a/Documentation/filesystems/ext4/orphan.rst b/Documentation/filesystems/ext4/orphan.rst new file mode 100644 index 000000000000..bb19ecd1b626 --- /dev/null +++ b/Documentation/filesystems/ext4/orphan.rst @@ -0,0 +1,52 @@ +.. SPDX-License-Identifier: GPL-2.0 + +Orphan file +----------- + +In unix there can inodes that are unlinked from directory hierarchy but that +are still alive because they are open. In case of crash the filesystem has to +clean up these inodes as otherwise they (and the blocks referenced from them) +would leak. Similarly if we truncate or extend the file, we need not be able +to perform the operation in a single journalling transaction. In such case we +track the inode as orphan so that in case of crash extra blocks allocated to +the file get truncated. + +Traditionally ext4 tracks orphan inodes in a form of single linked list where +superblock contains the inode number of the last orphan inode (s\_last\_orphan +field) and then each inode contains inode number of the previously orphaned +inode (we overload i\_dtime inode field for this). However this filesystem +global single linked list is a scalability bottleneck for workloads that result +in heavy creation of orphan inodes. When orphan file feature +(COMPAT\_ORPHAN\_FILE) is enabled, the filesystem has a special inode +(referenced from the superblock through s\_orphan_file_inum) with several +blocks. Each of these blocks has a structure: + +.. list-table:: + :widths: 8 8 24 40 + :header-rows: 1 + + * - Offset + - Type + - Name + - Description + * - 0x0 + - Array of \_\_le32 entries + - Orphan inode entries + - Each \_\_le32 entry is either empty (0) or it contains inode number of + an orphan inode. + * - blocksize - 8 + - \_\_le32 + - ob\_magic + - Magic value stored in orphan block tail (0x0b10ca04) + * - blocksize - 4 + - \_\_le32 + - ob\_checksum + - Checksum of the orphan block. + +When a filesystem with orphan file feature is writeably mounted, we set +RO\_COMPAT\_ORPHAN\_PRESENT feature in the superblock to indicate there may +be valid orphan entries. In case we see this feature when mounting the +filesystem, we read the whole orphan file and process all orphan inodes found +there as usual. When cleanly unmounting the filesystem we remove the +RO\_COMPAT\_ORPHAN\_PRESENT feature to avoid unnecessary scanning of the orphan +file and also make the filesystem fully compatible with older kernels. diff --git a/Documentation/filesystems/ext4/special_inodes.rst b/Documentation/filesystems/ext4/special_inodes.rst index 9061aabba827..94f304e3a0a7 100644 --- a/Documentation/filesystems/ext4/special_inodes.rst +++ b/Documentation/filesystems/ext4/special_inodes.rst @@ -36,3 +36,20 @@ ext4 reserves some inode for special features, as follows: * - 11 - Traditional first non-reserved inode. Usually this is the lost+found directory. See s\_first\_ino in the superblock. +Note that there are also some inodes allocated from non-reserved inode numbers +for other filesystem features which are not referenced from standard directory +hierarchy. These are generally reference from the superblock. They are: + +.. list-table:: + :widths: 20 50 + :header-rows: 1 + + * - Superblock field + - Description + + * - s\_lpf\_ino + - Inode number of lost+found directory. + * - s\_prj\_quota\_inum + - Inode number of quota file tracking project quotas + * - s\_orphan\_file\_inum + - Inode number of file tracking orphan inodes. diff --git a/Documentation/filesystems/ext4/super.rst b/Documentation/filesystems/ext4/super.rst index 2eb1ab20498d..f6a548e957bb 100644 --- a/Documentation/filesystems/ext4/super.rst +++ b/Documentation/filesystems/ext4/super.rst @@ -479,7 +479,11 @@ The ext4 superblock is laid out as follows in - Filename charset encoding flags. * - 0x280 - \_\_le32 - - s\_reserved[95] + - s\_orphan\_file\_inum + - Orphan file inode number. + * - 0x284 + - \_\_le32 + - s\_reserved[94] - Padding to the end of the block. * - 0x3FC - \_\_le32 @@ -603,6 +607,11 @@ following: the journal, JBD2 incompat feature (JBD2\_FEATURE\_INCOMPAT\_FAST\_COMMIT) gets set (COMPAT\_FAST\_COMMIT). + * - 0x1000 + - Orphan file allocated. This is the special file for more efficient + tracking of unlinked but still open inodes. When there may be any + entries in the file, we additionally set proper rocompat feature + (RO\_COMPAT\_ORPHAN\_PRESENT). .. _super_incompat: @@ -713,6 +722,10 @@ the following: - Filesystem tracks project quotas. (RO\_COMPAT\_PROJECT) * - 0x8000 - Verity inodes may be present on the filesystem. (RO\_COMPAT\_VERITY) + * - 0x10000 + - Indicates orphan file may have valid orphan entries and thus we need + to clean them up when mounting the filesystem + (RO\_COMPAT\_ORPHAN\_PRESENT). .. _super_def_hash: diff --git a/Documentation/filesystems/f2fs.rst b/Documentation/filesystems/f2fs.rst index ff9e7cc97c65..09de6ebbbdfa 100644 --- a/Documentation/filesystems/f2fs.rst +++ b/Documentation/filesystems/f2fs.rst @@ -185,6 +185,7 @@ fault_type=%d Support configuring fault injection type, should be FAULT_KVMALLOC 0x000000002 FAULT_PAGE_ALLOC 0x000000004 FAULT_PAGE_GET 0x000000008 + FAULT_ALLOC_BIO 0x000000010 (obsolete) FAULT_ALLOC_NID 0x000000020 FAULT_ORPHAN 0x000000040 FAULT_BLOCK 0x000000080 @@ -195,6 +196,7 @@ fault_type=%d Support configuring fault injection type, should be FAULT_CHECKPOINT 0x000001000 FAULT_DISCARD 0x000002000 FAULT_WRITE_IO 0x000004000 + FAULT_SLAB_ALLOC 0x000008000 =================== =========== mode=%s Control block allocation mode which supports "adaptive" and "lfs". In "lfs" mode, there should be no random @@ -312,6 +314,14 @@ inlinecrypt When possible, encrypt/decrypt the contents of encrypted Documentation/block/inline-encryption.rst. atgc Enable age-threshold garbage collection, it provides high effectiveness and efficiency on background GC. +discard_unit=%s Control discard unit, the argument can be "block", "segment" + and "section", issued discard command's offset/size will be + aligned to the unit, by default, "discard_unit=block" is set, + so that small discard functionality is enabled. + For blkzoned device, "discard_unit=section" will be set by + default, it is helpful for large sized SMR or ZNS devices to + reduce memory cost by getting rid of fs metadata supports small + discard. ======================== ============================================================ Debugfs Entries @@ -857,8 +867,11 @@ Compression implementation directly in order to guarantee potential data updates later to the space. Instead, the main goal is to reduce data writes to flash disk as much as possible, resulting in extending disk life time as well as relaxing IO - congestion. Alternatively, we've added ioctl interface to reclaim compressed - space and show it to user after putting the immutable bit. + congestion. Alternatively, we've added ioctl(F2FS_IOC_RELEASE_COMPRESS_BLOCKS) + interface to reclaim compressed space and show it to user after putting the + immutable bit. Immutable bit, after release, it doesn't allow writing/mmaping + on the file, until reserving compressed space via + ioctl(F2FS_IOC_RESERVE_COMPRESS_BLOCKS) or truncating filesize to zero. Compress metadata layout:: diff --git a/Documentation/filesystems/fscrypt.rst b/Documentation/filesystems/fscrypt.rst index 44b67ebd6e40..0eb799d9d05a 100644 --- a/Documentation/filesystems/fscrypt.rst +++ b/Documentation/filesystems/fscrypt.rst @@ -1063,11 +1063,6 @@ astute users may notice some differences in behavior: - DAX (Direct Access) is not supported on encrypted files. -- The st_size of an encrypted symlink will not necessarily give the - length of the symlink target as required by POSIX. It will actually - give the length of the ciphertext, which will be slightly longer - than the plaintext due to NUL-padding and an extra 2-byte overhead. - - The maximum length of an encrypted symlink is 2 bytes shorter than the maximum length of an unencrypted symlink. For example, on an EXT4 filesystem with a 4K block size, unencrypted symlinks can be up @@ -1235,12 +1230,12 @@ the user-supplied name to get the ciphertext. Lookups without the key are more complicated. The raw ciphertext may contain the ``\0`` and ``/`` characters, which are illegal in -filenames. Therefore, readdir() must base64-encode the ciphertext for -presentation. For most filenames, this works fine; on ->lookup(), the -filesystem just base64-decodes the user-supplied name to get back to -the raw ciphertext. +filenames. Therefore, readdir() must base64url-encode the ciphertext +for presentation. For most filenames, this works fine; on ->lookup(), +the filesystem just base64url-decodes the user-supplied name to get +back to the raw ciphertext. -However, for very long filenames, base64 encoding would cause the +However, for very long filenames, base64url encoding would cause the filename length to exceed NAME_MAX. To prevent this, readdir() actually presents long filenames in an abbreviated form which encodes a strong "hash" of the ciphertext filename, along with the optional diff --git a/Documentation/filesystems/idmappings.rst b/Documentation/filesystems/idmappings.rst new file mode 100644 index 000000000000..1229a75ec75d --- /dev/null +++ b/Documentation/filesystems/idmappings.rst @@ -0,0 +1,1026 @@ +.. SPDX-License-Identifier: GPL-2.0 + +Idmappings +========== + +Most filesystem developers will have encountered idmappings. They are used when +reading from or writing ownership to disk, reporting ownership to userspace, or +for permission checking. This document is aimed at filesystem developers that +want to know how idmappings work. + +Formal notes +------------ + +An idmapping is essentially a translation of a range of ids into another or the +same range of ids. The notational convention for idmappings that is widely used +in userspace is:: + + u:k:r + +``u`` indicates the first element in the upper idmapset ``U`` and ``k`` +indicates the first element in the lower idmapset ``K``. The ``r`` parameter +indicates the range of the idmapping, i.e. how many ids are mapped. From now +on, we will always prefix ids with ``u`` or ``k`` to make it clear whether +we're talking about an id in the upper or lower idmapset. + +To see what this looks like in practice, let's take the following idmapping:: + + u22:k10000:r3 + +and write down the mappings it will generate:: + + u22 -> k10000 + u23 -> k10001 + u24 -> k10002 + +From a mathematical viewpoint ``U`` and ``K`` are well-ordered sets and an +idmapping is an order isomorphism from ``U`` into ``K``. So ``U`` and ``K`` are +order isomorphic. In fact, ``U`` and ``K`` are always well-ordered subsets of +the set of all possible ids useable on a given system. + +Looking at this mathematically briefly will help us highlight some properties +that make it easier to understand how we can translate between idmappings. For +example, we know that the inverse idmapping is an order isomorphism as well:: + + k10000 -> u22 + k10001 -> u23 + k10002 -> u24 + +Given that we are dealing with order isomorphisms plus the fact that we're +dealing with subsets we can embedd idmappings into each other, i.e. we can +sensibly translate between different idmappings. For example, assume we've been +given the three idmappings:: + + 1. u0:k10000:r10000 + 2. u0:k20000:r10000 + 3. u0:k30000:r10000 + +and id ``k11000`` which has been generated by the first idmapping by mapping +``u1000`` from the upper idmapset down to ``k11000`` in the lower idmapset. + +Because we're dealing with order isomorphic subsets it is meaningful to ask +what id ``k11000`` corresponds to in the second or third idmapping. The +straightfoward algorithm to use is to apply the inverse of the first idmapping, +mapping ``k11000`` up to ``u1000``. Afterwards, we can map ``u1000`` down using +either the second idmapping mapping or third idmapping mapping. The second +idmapping would map ``u1000`` down to ``21000``. The third idmapping would map +``u1000`` down to ``u31000``. + +If we were given the same task for the following three idmappings:: + + 1. u0:k10000:r10000 + 2. u0:k20000:r200 + 3. u0:k30000:r300 + +we would fail to translate as the sets aren't order isomorphic over the full +range of the first idmapping anymore (However they are order isomorphic over +the full range of the second idmapping.). Neither the second or third idmapping +contain ``u1000`` in the upper idmapset ``U``. This is equivalent to not having +an id mapped. We can simply say that ``u1000`` is unmapped in the second and +third idmapping. The kernel will report unmapped ids as the overflowuid +``(uid_t)-1`` or overflowgid ``(gid_t)-1`` to userspace. + +The algorithm to calculate what a given id maps to is pretty simple. First, we +need to verify that the range can contain our target id. We will skip this step +for simplicity. After that if we want to know what ``id`` maps to we can do +simple calculations: + +- If we want to map from left to right:: + + u:k:r + id - u + k = n + +- If we want to map from right to left:: + + u:k:r + id - k + u = n + +Instead of "left to right" we can also say "down" and instead of "right to +left" we can also say "up". Obviously mapping down and up invert each other. + +To see whether the simple formulas above work, consider the following two +idmappings:: + + 1. u0:k20000:r10000 + 2. u500:k30000:r10000 + +Assume we are given ``k21000`` in the lower idmapset of the first idmapping. We +want to know what id this was mapped from in the upper idmapset of the first +idmapping. So we're mapping up in the first idmapping:: + + id - k + u = n + k21000 - k20000 + u0 = u1000 + +Now assume we are given the id ``u1100`` in the upper idmapset of the second +idmapping and we want to know what this id maps down to in the lower idmapset +of the second idmapping. This means we're mapping down in the second +idmapping:: + + id - u + k = n + u1100 - u500 + k30000 = k30600 + +General notes +------------- + +In the context of the kernel an idmapping can be interpreted as mapping a range +of userspace ids into a range of kernel ids:: + + userspace-id:kernel-id:range + +A userspace id is always an element in the upper idmapset of an idmapping of +type ``uid_t`` or ``gid_t`` and a kernel id is always an element in the lower +idmapset of an idmapping of type ``kuid_t`` or ``kgid_t``. From now on +"userspace id" will be used to refer to the well known ``uid_t`` and ``gid_t`` +types and "kernel id" will be used to refer to ``kuid_t`` and ``kgid_t``. + +The kernel is mostly concerned with kernel ids. They are used when performing +permission checks and are stored in an inode's ``i_uid`` and ``i_gid`` field. +A userspace id on the other hand is an id that is reported to userspace by the +kernel, or is passed by userspace to the kernel, or a raw device id that is +written or read from disk. + +Note that we are only concerned with idmappings as the kernel stores them not +how userspace would specify them. + +For the rest of this document we will prefix all userspace ids with ``u`` and +all kernel ids with ``k``. Ranges of idmappings will be prefixed with ``r``. So +an idmapping will be written as ``u0:k10000:r10000``. + +For example, the id ``u1000`` is an id in the upper idmapset or "userspace +idmapset" starting with ``u1000``. And it is mapped to ``k11000`` which is a +kernel id in the lower idmapset or "kernel idmapset" starting with ``k10000``. + +A kernel id is always created by an idmapping. Such idmappings are associated +with user namespaces. Since we mainly care about how idmappings work we're not +going to be concerned with how idmappings are created nor how they are used +outside of the filesystem context. This is best left to an explanation of user +namespaces. + +The initial user namespace is special. It always has an idmapping of the +following form:: + + u0:k0:r4294967295 + +which is an identity idmapping over the full range of ids available on this +system. + +Other user namespaces usually have non-identity idmappings such as:: + + u0:k10000:r10000 + +When a process creates or wants to change ownership of a file, or when the +ownership of a file is read from disk by a filesystem, the userspace id is +immediately translated into a kernel id according to the idmapping associated +with the relevant user namespace. + +For instance, consider a file that is stored on disk by a filesystem as being +owned by ``u1000``: + +- If a filesystem were to be mounted in the initial user namespaces (as most + filesystems are) then the initial idmapping will be used. As we saw this is + simply the identity idmapping. This would mean id ``u1000`` read from disk + would be mapped to id ``k1000``. So an inode's ``i_uid`` and ``i_gid`` field + would contain ``k1000``. + +- If a filesystem were to be mounted with an idmapping of ``u0:k10000:r10000`` + then ``u1000`` read from disk would be mapped to ``k11000``. So an inode's + ``i_uid`` and ``i_gid`` would contain ``k11000``. + +Translation algorithms +---------------------- + +We've already seen briefly that it is possible to translate between different +idmappings. We'll now take a closer look how that works. + +Crossmapping +~~~~~~~~~~~~ + +This translation algorithm is used by the kernel in quite a few places. For +example, it is used when reporting back the ownership of a file to userspace +via the ``stat()`` system call family. + +If we've been given ``k11000`` from one idmapping we can map that id up in +another idmapping. In order for this to work both idmappings need to contain +the same kernel id in their kernel idmapsets. For example, consider the +following idmappings:: + + 1. u0:k10000:r10000 + 2. u20000:k10000:r10000 + +and we are mapping ``u1000`` down to ``k11000`` in the first idmapping . We can +then translate ``k11000`` into a userspace id in the second idmapping using the +kernel idmapset of the second idmapping:: + + /* Map the kernel id up into a userspace id in the second idmapping. */ + from_kuid(u20000:k10000:r10000, k11000) = u21000 + +Note, how we can get back to the kernel id in the first idmapping by inverting +the algorithm:: + + /* Map the userspace id down into a kernel id in the second idmapping. */ + make_kuid(u20000:k10000:r10000, u21000) = k11000 + + /* Map the kernel id up into a userspace id in the first idmapping. */ + from_kuid(u0:k10000:r10000, k11000) = u1000 + +This algorithm allows us to answer the question what userspace id a given +kernel id corresponds to in a given idmapping. In order to be able to answer +this question both idmappings need to contain the same kernel id in their +respective kernel idmapsets. + +For example, when the kernel reads a raw userspace id from disk it maps it down +into a kernel id according to the idmapping associated with the filesystem. +Let's assume the filesystem was mounted with an idmapping of +``u0:k20000:r10000`` and it reads a file owned by ``u1000`` from disk. This +means ``u1000`` will be mapped to ``k21000`` which is what will be stored in +the inode's ``i_uid`` and ``i_gid`` field. + +When someone in userspace calls ``stat()`` or a related function to get +ownership information about the file the kernel can't simply map the id back up +according to the filesystem's idmapping as this would give the wrong owner if +the caller is using an idmapping. + +So the kernel will map the id back up in the idmapping of the caller. Let's +assume the caller has the slighly unconventional idmapping +``u3000:k20000:r10000`` then ``k21000`` would map back up to ``u4000``. +Consequently the user would see that this file is owned by ``u4000``. + +Remapping +~~~~~~~~~ + +It is possible to translate a kernel id from one idmapping to another one via +the userspace idmapset of the two idmappings. This is equivalent to remapping +a kernel id. + +Let's look at an example. We are given the following two idmappings:: + + 1. u0:k10000:r10000 + 2. u0:k20000:r10000 + +and we are given ``k11000`` in the first idmapping. In order to translate this +kernel id in the first idmapping into a kernel id in the second idmapping we +need to perform two steps: + +1. Map the kernel id up into a userspace id in the first idmapping:: + + /* Map the kernel id up into a userspace id in the first idmapping. */ + from_kuid(u0:k10000:r10000, k11000) = u1000 + +2. Map the userspace id down into a kernel id in the second idmapping:: + + /* Map the userspace id down into a kernel id in the second idmapping. */ + make_kuid(u0:k20000:r10000, u1000) = k21000 + +As you can see we used the userspace idmapset in both idmappings to translate +the kernel id in one idmapping to a kernel id in another idmapping. + +This allows us to answer the question what kernel id we would need to use to +get the same userspace id in another idmapping. In order to be able to answer +this question both idmappings need to contain the same userspace id in their +respective userspace idmapsets. + +Note, how we can easily get back to the kernel id in the first idmapping by +inverting the algorithm: + +1. Map the kernel id up into a userspace id in the second idmapping:: + + /* Map the kernel id up into a userspace id in the second idmapping. */ + from_kuid(u0:k20000:r10000, k21000) = u1000 + +2. Map the userspace id down into a kernel id in the first idmapping:: + + /* Map the userspace id down into a kernel id in the first idmapping. */ + make_kuid(u0:k10000:r10000, u1000) = k11000 + +Another way to look at this translation is to treat it as inverting one +idmapping and applying another idmapping if both idmappings have the relevant +userspace id mapped. This will come in handy when working with idmapped mounts. + +Invalid translations +~~~~~~~~~~~~~~~~~~~~ + +It is never valid to use an id in the kernel idmapset of one idmapping as the +id in the userspace idmapset of another or the same idmapping. While the kernel +idmapset always indicates an idmapset in the kernel id space the userspace +idmapset indicates a userspace id. So the following translations are forbidden:: + + /* Map the userspace id down into a kernel id in the first idmapping. */ + make_kuid(u0:k10000:r10000, u1000) = k11000 + + /* INVALID: Map the kernel id down into a kernel id in the second idmapping. */ + make_kuid(u10000:k20000:r10000, k110000) = k21000 + ~~~~~~~ + +and equally wrong:: + + /* Map the kernel id up into a userspace id in the first idmapping. */ + from_kuid(u0:k10000:r10000, k11000) = u1000 + + /* INVALID: Map the userspace id up into a userspace id in the second idmapping. */ + from_kuid(u20000:k0:r10000, u1000) = k21000 + ~~~~~ + +Idmappings when creating filesystem objects +------------------------------------------- + +The concepts of mapping an id down or mapping an id up are expressed in the two +kernel functions filesystem developers are rather familiar with and which we've +already used in this document:: + + /* Map the userspace id down into a kernel id. */ + make_kuid(idmapping, uid) + + /* Map the kernel id up into a userspace id. */ + from_kuid(idmapping, kuid) + +We will take an abbreviated look into how idmappings figure into creating +filesystem objects. For simplicity we will only look at what happens when the +VFS has already completed path lookup right before it calls into the filesystem +itself. So we're concerned with what happens when e.g. ``vfs_mkdir()`` is +called. We will also assume that the directory we're creating filesystem +objects in is readable and writable for everyone. + +When creating a filesystem object the caller will look at the caller's +filesystem ids. These are just regular ``uid_t`` and ``gid_t`` userspace ids +but they are exclusively used when determining file ownership which is why they +are called "filesystem ids". They are usually identical to the uid and gid of +the caller but can differ. We will just assume they are always identical to not +get lost in too many details. + +When the caller enters the kernel two things happen: + +1. Map the caller's userspace ids down into kernel ids in the caller's + idmapping. + (To be precise, the kernel will simply look at the kernel ids stashed in the + credentials of the current task but for our education we'll pretend this + translation happens just in time.) +2. Verify that the caller's kernel ids can be mapped up to userspace ids in the + filesystem's idmapping. + +The second step is important as regular filesystem will ultimately need to map +the kernel id back up into a userspace id when writing to disk. +So with the second step the kernel guarantees that a valid userspace id can be +written to disk. If it can't the kernel will refuse the creation request to not +even remotely risk filesystem corruption. + +The astute reader will have realized that this is simply a varation of the +crossmapping algorithm we mentioned above in a previous section. First, the +kernel maps the caller's userspace id down into a kernel id according to the +caller's idmapping and then maps that kernel id up according to the +filesystem's idmapping. + +Example 1 +~~~~~~~~~ + +:: + + caller id: u1000 + caller idmapping: u0:k0:r4294967295 + filesystem idmapping: u0:k0:r4294967295 + +Both the caller and the filesystem use the identity idmapping: + +1. Map the caller's userspace ids into kernel ids in the caller's idmapping:: + + make_kuid(u0:k0:r4294967295, u1000) = k1000 + +2. Verify that the caller's kernel ids can be mapped to userspace ids in the + filesystem's idmapping. + + For this second step the kernel will call the function + ``fsuidgid_has_mapping()`` which ultimately boils down to calling + ``from_kuid()``:: + + from_kuid(u0:k0:r4294967295, k1000) = u1000 + +In this example both idmappings are the same so there's nothing exciting going +on. Ultimately the userspace id that lands on disk will be ``u1000``. + +Example 2 +~~~~~~~~~ + +:: + + caller id: u1000 + caller idmapping: u0:k10000:r10000 + filesystem idmapping: u0:k20000:r10000 + +1. Map the caller's userspace ids down into kernel ids in the caller's + idmapping:: + + make_kuid(u0:k10000:r10000, u1000) = k11000 + +2. Verify that the caller's kernel ids can be mapped up to userspace ids in the + filesystem's idmapping:: + + from_kuid(u0:k20000:r10000, k11000) = u-1 + +It's immediately clear that while the caller's userspace id could be +successfully mapped down into kernel ids in the caller's idmapping the kernel +ids could not be mapped up according to the filesystem's idmapping. So the +kernel will deny this creation request. + +Note that while this example is less common, because most filesystem can't be +mounted with non-initial idmappings this is a general problem as we can see in +the next examples. + +Example 3 +~~~~~~~~~ + +:: + + caller id: u1000 + caller idmapping: u0:k10000:r10000 + filesystem idmapping: u0:k0:r4294967295 + +1. Map the caller's userspace ids down into kernel ids in the caller's + idmapping:: + + make_kuid(u0:k10000:r10000, u1000) = k11000 + +2. Verify that the caller's kernel ids can be mapped up to userspace ids in the + filesystem's idmapping:: + + from_kuid(u0:k0:r4294967295, k11000) = u11000 + +We can see that the translation always succeeds. The userspace id that the +filesystem will ultimately put to disk will always be identical to the value of +the kernel id that was created in the caller's idmapping. This has mainly two +consequences. + +First, that we can't allow a caller to ultimately write to disk with another +userspace id. We could only do this if we were to mount the whole fileystem +with the caller's or another idmapping. But that solution is limited to a few +filesystems and not very flexible. But this is a use-case that is pretty +important in containerized workloads. + +Second, the caller will usually not be able to create any files or access +directories that have stricter permissions because none of the filesystem's +kernel ids map up into valid userspace ids in the caller's idmapping + +1. Map raw userspace ids down to kernel ids in the filesystem's idmapping:: + + make_kuid(u0:k0:r4294967295, u1000) = k1000 + +2. Map kernel ids up to userspace ids in the caller's idmapping:: + + from_kuid(u0:k10000:r10000, k1000) = u-1 + +Example 4 +~~~~~~~~~ + +:: + + file id: u1000 + caller idmapping: u0:k10000:r10000 + filesystem idmapping: u0:k0:r4294967295 + +In order to report ownership to userspace the kernel uses the crossmapping +algorithm introduced in a previous section: + +1. Map the userspace id on disk down into a kernel id in the filesystem's + idmapping:: + + make_kuid(u0:k0:r4294967295, u1000) = k1000 + +2. Map the kernel id up into a userspace id in the caller's idmapping:: + + from_kuid(u0:k10000:r10000, k1000) = u-1 + +The crossmapping algorithm fails in this case because the kernel id in the +filesystem idmapping cannot be mapped up to a userspace id in the caller's +idmapping. Thus, the kernel will report the ownership of this file as the +overflowid. + +Example 5 +~~~~~~~~~ + +:: + + file id: u1000 + caller idmapping: u0:k10000:r10000 + filesystem idmapping: u0:k20000:r10000 + +In order to report ownership to userspace the kernel uses the crossmapping +algorithm introduced in a previous section: + +1. Map the userspace id on disk down into a kernel id in the filesystem's + idmapping:: + + make_kuid(u0:k20000:r10000, u1000) = k21000 + +2. Map the kernel id up into a userspace id in the caller's idmapping:: + + from_kuid(u0:k10000:r10000, k21000) = u-1 + +Again, the crossmapping algorithm fails in this case because the kernel id in +the filesystem idmapping cannot be mapped to a userspace id in the caller's +idmapping. Thus, the kernel will report the ownership of this file as the +overflowid. + +Note how in the last two examples things would be simple if the caller would be +using the initial idmapping. For a filesystem mounted with the initial +idmapping it would be trivial. So we only consider a filesystem with an +idmapping of ``u0:k20000:r10000``: + +1. Map the userspace id on disk down into a kernel id in the filesystem's + idmapping:: + + make_kuid(u0:k20000:r10000, u1000) = k21000 + +2. Map the kernel id up into a userspace id in the caller's idmapping:: + + from_kuid(u0:k0:r4294967295, k21000) = u21000 + +Idmappings on idmapped mounts +----------------------------- + +The examples we've seen in the previous section where the caller's idmapping +and the filesystem's idmapping are incompatible causes various issues for +workloads. For a more complex but common example, consider two containers +started on the host. To completely prevent the two containers from affecting +each other, an administrator may often use different non-overlapping idmappings +for the two containers:: + + container1 idmapping: u0:k10000:r10000 + container2 idmapping: u0:k20000:r10000 + filesystem idmapping: u0:k30000:r10000 + +An administrator wanting to provide easy read-write access to the following set +of files:: + + dir id: u0 + dir/file1 id: u1000 + dir/file2 id: u2000 + +to both containers currently can't. + +Of course the administrator has the option to recursively change ownership via +``chown()``. For example, they could change ownership so that ``dir`` and all +files below it can be crossmapped from the filesystem's into the container's +idmapping. Let's assume they change ownership so it is compatible with the +first container's idmapping:: + + dir id: u10000 + dir/file1 id: u11000 + dir/file2 id: u12000 + +This would still leave ``dir`` rather useless to the second container. In fact, +``dir`` and all files below it would continue to appear owned by the overflowid +for the second container. + +Or consider another increasingly popular example. Some service managers such as +systemd implement a concept called "portable home directories". A user may want +to use their home directories on different machines where they are assigned +different login userspace ids. Most users will have ``u1000`` as the login id +on their machine at home and all files in their home directory will usually be +owned by ``u1000``. At uni or at work they may have another login id such as +``u1125``. This makes it rather difficult to interact with their home directory +on their work machine. + +In both cases changing ownership recursively has grave implications. The most +obvious one is that ownership is changed globally and permanently. In the home +directory case this change in ownership would even need to happen everytime the +user switches from their home to their work machine. For really large sets of +files this becomes increasingly costly. + +If the user is lucky, they are dealing with a filesystem that is mountable +inside user namespaces. But this would also change ownership globally and the +change in ownership is tied to the lifetime of the filesystem mount, i.e. the +superblock. The only way to change ownership is to completely unmount the +filesystem and mount it again in another user namespace. This is usually +impossible because it would mean that all users currently accessing the +filesystem can't anymore. And it means that ``dir`` still can't be shared +between two containers with different idmappings. +But usually the user doesn't even have this option since most filesystems +aren't mountable inside containers. And not having them mountable might be +desirable as it doesn't require the filesystem to deal with malicious +filesystem images. + +But the usecases mentioned above and more can be handled by idmapped mounts. +They allow to expose the same set of dentries with different ownership at +different mounts. This is achieved by marking the mounts with a user namespace +through the ``mount_setattr()`` system call. The idmapping associated with it +is then used to translate from the caller's idmapping to the filesystem's +idmapping and vica versa using the remapping algorithm we introduced above. + +Idmapped mounts make it possible to change ownership in a temporary and +localized way. The ownership changes are restricted to a specific mount and the +ownership changes are tied to the lifetime of the mount. All other users and +locations where the filesystem is exposed are unaffected. + +Filesystems that support idmapped mounts don't have any real reason to support +being mountable inside user namespaces. A filesystem could be exposed +completely under an idmapped mount to get the same effect. This has the +advantage that filesystems can leave the creation of the superblock to +privileged users in the initial user namespace. + +However, it is perfectly possible to combine idmapped mounts with filesystems +mountable inside user namespaces. We will touch on this further below. + +Remapping helpers +~~~~~~~~~~~~~~~~~ + +Idmapping functions were added that translate between idmappings. They make use +of the remapping algorithm we've introduced earlier. We're going to look at +two: + +- ``i_uid_into_mnt()`` and ``i_gid_into_mnt()`` + + The ``i_*id_into_mnt()`` functions translate filesystem's kernel ids into + kernel ids in the mount's idmapping:: + + /* Map the filesystem's kernel id up into a userspace id in the filesystem's idmapping. */ + from_kuid(filesystem, kid) = uid + + /* Map the filesystem's userspace id down ito a kernel id in the mount's idmapping. */ + make_kuid(mount, uid) = kuid + +- ``mapped_fsuid()`` and ``mapped_fsgid()`` + + The ``mapped_fs*id()`` functions translate the caller's kernel ids into + kernel ids in the filesystem's idmapping. This translation is achieved by + remapping the caller's kernel ids using the mount's idmapping:: + + /* Map the caller's kernel id up into a userspace id in the mount's idmapping. */ + from_kuid(mount, kid) = uid + + /* Map the mount's userspace id down into a kernel id in the filesystem's idmapping. */ + make_kuid(filesystem, uid) = kuid + +Note that these two functions invert each other. Consider the following +idmappings:: + + caller idmapping: u0:k10000:r10000 + filesystem idmapping: u0:k20000:r10000 + mount idmapping: u0:k10000:r10000 + +Assume a file owned by ``u1000`` is read from disk. The filesystem maps this id +to ``k21000`` according to it's idmapping. This is what is stored in the +inode's ``i_uid`` and ``i_gid`` fields. + +When the caller queries the ownership of this file via ``stat()`` the kernel +would usually simply use the crossmapping algorithm and map the filesystem's +kernel id up to a userspace id in the caller's idmapping. + +But when the caller is accessing the file on an idmapped mount the kernel will +first call ``i_uid_into_mnt()`` thereby translating the filesystem's kernel id +into a kernel id in the mount's idmapping:: + + i_uid_into_mnt(k21000): + /* Map the filesystem's kernel id up into a userspace id. */ + from_kuid(u0:k20000:r10000, k21000) = u1000 + + /* Map the filesystem's userspace id down ito a kernel id in the mount's idmapping. */ + make_kuid(u0:k10000:r10000, u1000) = k11000 + +Finally, when the kernel reports the owner to the caller it will turn the +kernel id in the mount's idmapping into a userspace id in the caller's +idmapping:: + + from_kuid(u0:k10000:r10000, k11000) = u1000 + +We can test whether this algorithm really works by verifying what happens when +we create a new file. Let's say the user is creating a file with ``u1000``. + +The kernel maps this to ``k11000`` in the caller's idmapping. Usually the +kernel would now apply the crossmapping, verifying that ``k11000`` can be +mapped to a userspace id in the filesystem's idmapping. Since ``k11000`` can't +be mapped up in the filesystem's idmapping directly this creation request +fails. + +But when the caller is accessing the file on an idmapped mount the kernel will +first call ``mapped_fs*id()`` thereby translating the caller's kernel id into +a kernel id according to the mount's idmapping:: + + mapped_fsuid(k11000): + /* Map the caller's kernel id up into a userspace id in the mount's idmapping. */ + from_kuid(u0:k10000:r10000, k11000) = u1000 + + /* Map the mount's userspace id down into a kernel id in the filesystem's idmapping. */ + make_kuid(u0:k20000:r10000, u1000) = k21000 + +When finally writing to disk the kernel will then map ``k21000`` up into a +userspace id in the filesystem's idmapping:: + + from_kuid(u0:k20000:r10000, k21000) = u1000 + +As we can see, we end up with an invertible and therefore information +preserving algorithm. A file created from ``u1000`` on an idmapped mount will +also be reported as being owned by ``u1000`` and vica versa. + +Let's now briefly reconsider the failing examples from earlier in the context +of idmapped mounts. + +Example 2 reconsidered +~~~~~~~~~~~~~~~~~~~~~~ + +:: + + caller id: u1000 + caller idmapping: u0:k10000:r10000 + filesystem idmapping: u0:k20000:r10000 + mount idmapping: u0:k10000:r10000 + +When the caller is using a non-initial idmapping the common case is to attach +the same idmapping to the mount. We now perform three steps: + +1. Map the caller's userspace ids into kernel ids in the caller's idmapping:: + + make_kuid(u0:k10000:r10000, u1000) = k11000 + +2. Translate the caller's kernel id into a kernel id in the filesystem's + idmapping:: + + mapped_fsuid(k11000): + /* Map the kernel id up into a userspace id in the mount's idmapping. */ + from_kuid(u0:k10000:r10000, k11000) = u1000 + + /* Map the userspace id down into a kernel id in the filesystem's idmapping. */ + make_kuid(u0:k20000:r10000, u1000) = k21000 + +2. Verify that the caller's kernel ids can be mapped to userspace ids in the + filesystem's idmapping:: + + from_kuid(u0:k20000:r10000, k21000) = u1000 + +So the ownership that lands on disk will be ``u1000``. + +Example 3 reconsidered +~~~~~~~~~~~~~~~~~~~~~~ + +:: + + caller id: u1000 + caller idmapping: u0:k10000:r10000 + filesystem idmapping: u0:k0:r4294967295 + mount idmapping: u0:k10000:r10000 + +The same translation algorithm works with the third example. + +1. Map the caller's userspace ids into kernel ids in the caller's idmapping:: + + make_kuid(u0:k10000:r10000, u1000) = k11000 + +2. Translate the caller's kernel id into a kernel id in the filesystem's + idmapping:: + + mapped_fsuid(k11000): + /* Map the kernel id up into a userspace id in the mount's idmapping. */ + from_kuid(u0:k10000:r10000, k11000) = u1000 + + /* Map the userspace id down into a kernel id in the filesystem's idmapping. */ + make_kuid(u0:k0:r4294967295, u1000) = k1000 + +2. Verify that the caller's kernel ids can be mapped to userspace ids in the + filesystem's idmapping:: + + from_kuid(u0:k0:r4294967295, k21000) = u1000 + +So the ownership that lands on disk will be ``u1000``. + +Example 4 reconsidered +~~~~~~~~~~~~~~~~~~~~~~ + +:: + + file id: u1000 + caller idmapping: u0:k10000:r10000 + filesystem idmapping: u0:k0:r4294967295 + mount idmapping: u0:k10000:r10000 + +In order to report ownership to userspace the kernel now does three steps using +the translation algorithm we introduced earlier: + +1. Map the userspace id on disk down into a kernel id in the filesystem's + idmapping:: + + make_kuid(u0:k0:r4294967295, u1000) = k1000 + +2. Translate the kernel id into a kernel id in the mount's idmapping:: + + i_uid_into_mnt(k1000): + /* Map the kernel id up into a userspace id in the filesystem's idmapping. */ + from_kuid(u0:k0:r4294967295, k1000) = u1000 + + /* Map the userspace id down into a kernel id in the mounts's idmapping. */ + make_kuid(u0:k10000:r10000, u1000) = k11000 + +3. Map the kernel id up into a userspace id in the caller's idmapping:: + + from_kuid(u0:k10000:r10000, k11000) = u1000 + +Earlier, the caller's kernel id couldn't be crossmapped in the filesystems's +idmapping. With the idmapped mount in place it now can be crossmapped into the +filesystem's idmapping via the mount's idmapping. The file will now be created +with ``u1000`` according to the mount's idmapping. + +Example 5 reconsidered +~~~~~~~~~~~~~~~~~~~~~~ + +:: + + file id: u1000 + caller idmapping: u0:k10000:r10000 + filesystem idmapping: u0:k20000:r10000 + mount idmapping: u0:k10000:r10000 + +Again, in order to report ownership to userspace the kernel now does three +steps using the translation algorithm we introduced earlier: + +1. Map the userspace id on disk down into a kernel id in the filesystem's + idmapping:: + + make_kuid(u0:k20000:r10000, u1000) = k21000 + +2. Translate the kernel id into a kernel id in the mount's idmapping:: + + i_uid_into_mnt(k21000): + /* Map the kernel id up into a userspace id in the filesystem's idmapping. */ + from_kuid(u0:k20000:r10000, k21000) = u1000 + + /* Map the userspace id down into a kernel id in the mounts's idmapping. */ + make_kuid(u0:k10000:r10000, u1000) = k11000 + +3. Map the kernel id up into a userspace id in the caller's idmapping:: + + from_kuid(u0:k10000:r10000, k11000) = u1000 + +Earlier, the file's kernel id couldn't be crossmapped in the filesystems's +idmapping. With the idmapped mount in place it now can be crossmapped into the +filesystem's idmapping via the mount's idmapping. The file is now owned by +``u1000`` according to the mount's idmapping. + +Changing ownership on a home directory +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +We've seen above how idmapped mounts can be used to translate between +idmappings when either the caller, the filesystem or both uses a non-initial +idmapping. A wide range of usecases exist when the caller is using +a non-initial idmapping. This mostly happens in the context of containerized +workloads. The consequence is as we have seen that for both, filesystem's +mounted with the initial idmapping and filesystems mounted with non-initial +idmappings, access to the filesystem isn't working because the kernel ids can't +be crossmapped between the caller's and the filesystem's idmapping. + +As we've seen above idmapped mounts provide a solution to this by remapping the +caller's or filesystem's idmapping according to the mount's idmapping. + +Aside from containerized workloads, idmapped mounts have the advantage that +they also work when both the caller and the filesystem use the initial +idmapping which means users on the host can change the ownership of directories +and files on a per-mount basis. + +Consider our previous example where a user has their home directory on portable +storage. At home they have id ``u1000`` and all files in their home directory +are owned by ``u1000`` whereas at uni or work they have login id ``u1125``. + +Taking their home directory with them becomes problematic. They can't easily +access their files, they might not be able to write to disk without applying +lax permissions or ACLs and even if they can, they will end up with an annoying +mix of files and directories owned by ``u1000`` and ``u1125``. + +Idmapped mounts allow to solve this problem. A user can create an idmapped +mount for their home directory on their work computer or their computer at home +depending on what ownership they would prefer to end up on the portable storage +itself. + +Let's assume they want all files on disk to belong to ``u1000``. When the user +plugs in their portable storage at their work station they can setup a job that +creates an idmapped mount with the minimal idmapping ``u1000:k1125:r1``. So now +when they create a file the kernel performs the following steps we already know +from above::: + + caller id: u1125 + caller idmapping: u0:k0:r4294967295 + filesystem idmapping: u0:k0:r4294967295 + mount idmapping: u1000:k1125:r1 + +1. Map the caller's userspace ids into kernel ids in the caller's idmapping:: + + make_kuid(u0:k0:r4294967295, u1125) = k1125 + +2. Translate the caller's kernel id into a kernel id in the filesystem's + idmapping:: + + mapped_fsuid(k1125): + /* Map the kernel id up into a userspace id in the mount's idmapping. */ + from_kuid(u1000:k1125:r1, k1125) = u1000 + + /* Map the userspace id down into a kernel id in the filesystem's idmapping. */ + make_kuid(u0:k0:r4294967295, u1000) = k1000 + +2. Verify that the caller's kernel ids can be mapped to userspace ids in the + filesystem's idmapping:: + + from_kuid(u0:k0:r4294967295, k1000) = u1000 + +So ultimately the file will be created with ``u1000`` on disk. + +Now let's briefly look at what ownership the caller with id ``u1125`` will see +on their work computer: + +:: + + file id: u1000 + caller idmapping: u0:k0:r4294967295 + filesystem idmapping: u0:k0:r4294967295 + mount idmapping: u1000:k1125:r1 + +1. Map the userspace id on disk down into a kernel id in the filesystem's + idmapping:: + + make_kuid(u0:k0:r4294967295, u1000) = k1000 + +2. Translate the kernel id into a kernel id in the mount's idmapping:: + + i_uid_into_mnt(k1000): + /* Map the kernel id up into a userspace id in the filesystem's idmapping. */ + from_kuid(u0:k0:r4294967295, k1000) = u1000 + + /* Map the userspace id down into a kernel id in the mounts's idmapping. */ + make_kuid(u1000:k1125:r1, u1000) = k1125 + +3. Map the kernel id up into a userspace id in the caller's idmapping:: + + from_kuid(u0:k0:r4294967295, k1125) = u1125 + +So ultimately the caller will be reported that the file belongs to ``u1125`` +which is the caller's userspace id on their workstation in our example. + +The raw userspace id that is put on disk is ``u1000`` so when the user takes +their home directory back to their home computer where they are assigned +``u1000`` using the initial idmapping and mount the filesystem with the initial +idmapping they will see all those files owned by ``u1000``. + +Shortcircuting +-------------- + +Currently, the implementation of idmapped mounts enforces that the filesystem +is mounted with the initial idmapping. The reason is simply that none of the +filesystems that we targeted were mountable with a non-initial idmapping. But +that might change soon enough. As we've seen above, thanks to the properties of +idmappings the translation works for both filesystems mounted with the initial +idmapping and filesystem with non-initial idmappings. + +Based on this current restriction to filesystem mounted with the initial +idmapping two noticeable shortcuts have been taken: + +1. We always stash a reference to the initial user namespace in ``struct + vfsmount``. Idmapped mounts are thus mounts that have a non-initial user + namespace attached to them. + + In order to support idmapped mounts this needs to be changed. Instead of + stashing the initial user namespace the user namespace the filesystem was + mounted with must be stashed. An idmapped mount is then any mount that has + a different user namespace attached then the filesystem was mounted with. + This has no user-visible consequences. + +2. The translation algorithms in ``mapped_fs*id()`` and ``i_*id_into_mnt()`` + are simplified. + + Let's consider ``mapped_fs*id()`` first. This function translates the + caller's kernel id into a kernel id in the filesystem's idmapping via + a mount's idmapping. The full algorithm is:: + + mapped_fsuid(kid): + /* Map the kernel id up into a userspace id in the mount's idmapping. */ + from_kuid(mount-idmapping, kid) = uid + + /* Map the userspace id down into a kernel id in the filesystem's idmapping. */ + make_kuid(filesystem-idmapping, uid) = kuid + + We know that the filesystem is always mounted with the initial idmapping as + we enforce this in ``mount_setattr()``. So this can be shortened to:: + + mapped_fsuid(kid): + /* Map the kernel id up into a userspace id in the mount's idmapping. */ + from_kuid(mount-idmapping, kid) = uid + + /* Map the userspace id down into a kernel id in the filesystem's idmapping. */ + KUIDT_INIT(uid) = kuid + + Similarly, for ``i_*id_into_mnt()`` which translated the filesystem's kernel + id into a mount's kernel id:: + + i_uid_into_mnt(kid): + /* Map the kernel id up into a userspace id in the filesystem's idmapping. */ + from_kuid(filesystem-idmapping, kid) = uid + + /* Map the userspace id down into a kernel id in the mounts's idmapping. */ + make_kuid(mount-idmapping, uid) = kuid + + Again, we know that the filesystem is always mounted with the initial + idmapping as we enforce this in ``mount_setattr()``. So this can be + shortened to:: + + i_uid_into_mnt(kid): + /* Map the kernel id up into a userspace id in the filesystem's idmapping. */ + __kuid_val(kid) = uid + + /* Map the userspace id down into a kernel id in the mounts's idmapping. */ + make_kuid(mount-idmapping, uid) = kuid + +Handling filesystems mounted with non-initial idmappings requires that the +translation functions be converted to their full form. They can still be +shortcircuited on non-idmapped mounts. This has no user-visible consequences. diff --git a/Documentation/filesystems/index.rst b/Documentation/filesystems/index.rst index 246af51b277a..c0ad233963ae 100644 --- a/Documentation/filesystems/index.rst +++ b/Documentation/filesystems/index.rst @@ -34,6 +34,7 @@ algorithms work. quota seq_file sharedsubtree + idmappings automount-support @@ -72,7 +73,7 @@ Documentation for filesystem implementations. befs bfs btrfs - cifs/cifsroot + cifs/index ceph coda configfs @@ -100,6 +101,7 @@ Documentation for filesystem implementations. nilfs2 nfs/index ntfs + ntfs3 ocfs2 ocfs2-online-filecheck omfs diff --git a/Documentation/filesystems/locking.rst b/Documentation/filesystems/locking.rst index 2183fd8cc350..d36fe79167b3 100644 --- a/Documentation/filesystems/locking.rst +++ b/Documentation/filesystems/locking.rst @@ -70,7 +70,7 @@ prototypes:: const char *(*get_link) (struct dentry *, struct inode *, struct delayed_call *); void (*truncate) (struct inode *); int (*permission) (struct inode *, int, unsigned int); - int (*get_acl)(struct inode *, int); + struct posix_acl * (*get_acl)(struct inode *, int, bool); int (*setattr) (struct dentry *, struct iattr *); int (*getattr) (const struct path *, struct kstat *, u32, unsigned int); ssize_t (*listxattr) (struct dentry *, char *, size_t); @@ -271,19 +271,19 @@ prototypes:: locking rules: All except set_page_dirty and freepage may block -====================== ======================== ========= -ops PageLocked(page) i_rwsem -====================== ======================== ========= +====================== ======================== ========= =============== +ops PageLocked(page) i_rwsem invalidate_lock +====================== ======================== ========= =============== writepage: yes, unlocks (see below) -readpage: yes, unlocks +readpage: yes, unlocks shared writepages: set_page_dirty no -readahead: yes, unlocks -readpages: no +readahead: yes, unlocks shared +readpages: no shared write_begin: locks the page exclusive write_end: yes, unlocks exclusive bmap: -invalidatepage: yes +invalidatepage: yes exclusive releasepage: yes freepage: yes direct_IO: @@ -295,7 +295,7 @@ is_partially_uptodate: yes error_remove_page: yes swap_activate: no swap_deactivate: no -====================== ======================== ========= +====================== ======================== ========= =============== ->write_begin(), ->write_end() and ->readpage() may be called from the request handler (/dev/loop). @@ -378,7 +378,10 @@ keep it that way and don't breed new callers. ->invalidatepage() is called when the filesystem must attempt to drop some or all of the buffers from the page when it is being truncated. It returns zero on success. If ->invalidatepage is zero, the kernel uses -block_invalidatepage() instead. +block_invalidatepage() instead. The filesystem must exclusively acquire +invalidate_lock before invalidating page cache in truncate / hole punch path +(and thus calling into ->invalidatepage) to block races between page cache +invalidation and page cache filling functions (fault, read, ...). ->releasepage() is called when the kernel is about to try to drop the buffers from the page in preparation for freeing it. It returns zero to @@ -506,6 +509,7 @@ prototypes:: ssize_t (*write) (struct file *, const char __user *, size_t, loff_t *); ssize_t (*read_iter) (struct kiocb *, struct iov_iter *); ssize_t (*write_iter) (struct kiocb *, struct iov_iter *); + int (*iopoll) (struct kiocb *kiocb, bool spin); int (*iterate) (struct file *, struct dir_context *); int (*iterate_shared) (struct file *, struct dir_context *); __poll_t (*poll) (struct file *, struct poll_table_struct *); @@ -518,12 +522,6 @@ prototypes:: int (*fsync) (struct file *, loff_t start, loff_t end, int datasync); int (*fasync) (int, struct file *, int); int (*lock) (struct file *, int, struct file_lock *); - ssize_t (*readv) (struct file *, const struct iovec *, unsigned long, - loff_t *); - ssize_t (*writev) (struct file *, const struct iovec *, unsigned long, - loff_t *); - ssize_t (*sendfile) (struct file *, loff_t *, size_t, read_actor_t, - void __user *); ssize_t (*sendpage) (struct file *, struct page *, int, size_t, loff_t *, int); unsigned long (*get_unmapped_area)(struct file *, unsigned long, @@ -536,6 +534,14 @@ prototypes:: size_t, unsigned int); int (*setlease)(struct file *, long, struct file_lock **, void **); long (*fallocate)(struct file *, int, loff_t, loff_t); + void (*show_fdinfo)(struct seq_file *m, struct file *f); + unsigned (*mmap_capabilities)(struct file *); + ssize_t (*copy_file_range)(struct file *, loff_t, struct file *, + loff_t, size_t, unsigned int); + loff_t (*remap_file_range)(struct file *file_in, loff_t pos_in, + struct file *file_out, loff_t pos_out, + loff_t len, unsigned int remap_flags); + int (*fadvise)(struct file *, loff_t, loff_t, int); locking rules: All may block. @@ -570,6 +576,25 @@ in sys_read() and friends. the lease within the individual filesystem to record the result of the operation +->fallocate implementation must be really careful to maintain page cache +consistency when punching holes or performing other operations that invalidate +page cache contents. Usually the filesystem needs to call +truncate_inode_pages_range() to invalidate relevant range of the page cache. +However the filesystem usually also needs to update its internal (and on disk) +view of file offset -> disk block mapping. Until this update is finished, the +filesystem needs to block page faults and reads from reloading now-stale page +cache contents from the disk. Since VFS acquires mapping->invalidate_lock in +shared mode when loading pages from disk (filemap_fault(), filemap_read(), +readahead paths), the fallocate implementation must take the invalidate_lock to +prevent reloading. + +->copy_file_range and ->remap_file_range implementations need to serialize +against modifications of file data while the operation is running. For +blocking changes through write(2) and similar operations inode->i_rwsem can be +used. To block changes to file contents via a memory mapping during the +operation, the filesystem must take mapping->invalidate_lock to coordinate +with ->page_mkwrite. + dquot_operations ================ @@ -627,11 +652,11 @@ pfn_mkwrite: yes access: yes ============= ========= =========================== -->fault() is called when a previously not present pte is about -to be faulted in. The filesystem must find and return the page associated -with the passed in "pgoff" in the vm_fault structure. If it is possible that -the page may be truncated and/or invalidated, then the filesystem must lock -the page, then ensure it is not already truncated (the page lock will block +->fault() is called when a previously not present pte is about to be faulted +in. The filesystem must find and return the page associated with the passed in +"pgoff" in the vm_fault structure. If it is possible that the page may be +truncated and/or invalidated, then the filesystem must lock invalidate_lock, +then ensure the page is not already truncated (invalidate_lock will block subsequent truncate), and then return with VM_FAULT_LOCKED, and the page locked. The VM will unlock the page. @@ -644,12 +669,14 @@ page table entry. Pointer to entry associated with the page is passed in "pte" field in vm_fault structure. Pointers to entries for other offsets should be calculated relative to "pte". -->page_mkwrite() is called when a previously read-only pte is -about to become writeable. The filesystem again must ensure that there are -no truncate/invalidate races, and then return with the page locked. If -the page has been truncated, the filesystem should not look up a new page -like the ->fault() handler, but simply return with VM_FAULT_NOPAGE, which -will cause the VM to retry the fault. +->page_mkwrite() is called when a previously read-only pte is about to become +writeable. The filesystem again must ensure that there are no +truncate/invalidate races or races with operations such as ->remap_file_range +or ->copy_file_range, and then return with the page locked. Usually +mapping->invalidate_lock is suitable for proper serialization. If the page has +been truncated, the filesystem should not look up a new page like the ->fault() +handler, but simply return with VM_FAULT_NOPAGE, which will cause the VM to +retry the fault. ->pfn_mkwrite() is the same as page_mkwrite but when the pte is VM_PFNMAP or VM_MIXEDMAP with a page-less entry. Expected return is diff --git a/Documentation/filesystems/mandatory-locking.rst b/Documentation/filesystems/mandatory-locking.rst deleted file mode 100644 index 9ce73544a8f0..000000000000 --- a/Documentation/filesystems/mandatory-locking.rst +++ /dev/null @@ -1,188 +0,0 @@ -.. SPDX-License-Identifier: GPL-2.0 - -===================================================== -Mandatory File Locking For The Linux Operating System -===================================================== - - Andy Walker <andy@lysaker.kvaerner.no> - - 15 April 1996 - - (Updated September 2007) - -0. Why you should avoid mandatory locking ------------------------------------------ - -The Linux implementation is prey to a number of difficult-to-fix race -conditions which in practice make it not dependable: - - - The write system call checks for a mandatory lock only once - at its start. It is therefore possible for a lock request to - be granted after this check but before the data is modified. - A process may then see file data change even while a mandatory - lock was held. - - Similarly, an exclusive lock may be granted on a file after - the kernel has decided to proceed with a read, but before the - read has actually completed, and the reading process may see - the file data in a state which should not have been visible - to it. - - Similar races make the claimed mutual exclusion between lock - and mmap similarly unreliable. - -1. What is mandatory locking? ------------------------------- - -Mandatory locking is kernel enforced file locking, as opposed to the more usual -cooperative file locking used to guarantee sequential access to files among -processes. File locks are applied using the flock() and fcntl() system calls -(and the lockf() library routine which is a wrapper around fcntl().) It is -normally a process' responsibility to check for locks on a file it wishes to -update, before applying its own lock, updating the file and unlocking it again. -The most commonly used example of this (and in the case of sendmail, the most -troublesome) is access to a user's mailbox. The mail user agent and the mail -transfer agent must guard against updating the mailbox at the same time, and -prevent reading the mailbox while it is being updated. - -In a perfect world all processes would use and honour a cooperative, or -"advisory" locking scheme. However, the world isn't perfect, and there's -a lot of poorly written code out there. - -In trying to address this problem, the designers of System V UNIX came up -with a "mandatory" locking scheme, whereby the operating system kernel would -block attempts by a process to write to a file that another process holds a -"read" -or- "shared" lock on, and block attempts to both read and write to a -file that a process holds a "write " -or- "exclusive" lock on. - -The System V mandatory locking scheme was intended to have as little impact as -possible on existing user code. The scheme is based on marking individual files -as candidates for mandatory locking, and using the existing fcntl()/lockf() -interface for applying locks just as if they were normal, advisory locks. - -.. Note:: - - 1. In saying "file" in the paragraphs above I am actually not telling - the whole truth. System V locking is based on fcntl(). The granularity of - fcntl() is such that it allows the locking of byte ranges in files, in - addition to entire files, so the mandatory locking rules also have byte - level granularity. - - 2. POSIX.1 does not specify any scheme for mandatory locking, despite - borrowing the fcntl() locking scheme from System V. The mandatory locking - scheme is defined by the System V Interface Definition (SVID) Version 3. - -2. Marking a file for mandatory locking ---------------------------------------- - -A file is marked as a candidate for mandatory locking by setting the group-id -bit in its file mode but removing the group-execute bit. This is an otherwise -meaningless combination, and was chosen by the System V implementors so as not -to break existing user programs. - -Note that the group-id bit is usually automatically cleared by the kernel when -a setgid file is written to. This is a security measure. The kernel has been -modified to recognize the special case of a mandatory lock candidate and to -refrain from clearing this bit. Similarly the kernel has been modified not -to run mandatory lock candidates with setgid privileges. - -3. Available implementations ----------------------------- - -I have considered the implementations of mandatory locking available with -SunOS 4.1.x, Solaris 2.x and HP-UX 9.x. - -Generally I have tried to make the most sense out of the behaviour exhibited -by these three reference systems. There are many anomalies. - -All the reference systems reject all calls to open() for a file on which -another process has outstanding mandatory locks. This is in direct -contravention of SVID 3, which states that only calls to open() with the -O_TRUNC flag set should be rejected. The Linux implementation follows the SVID -definition, which is the "Right Thing", since only calls with O_TRUNC can -modify the contents of the file. - -HP-UX even disallows open() with O_TRUNC for a file with advisory locks, not -just mandatory locks. That would appear to contravene POSIX.1. - -mmap() is another interesting case. All the operating systems mentioned -prevent mandatory locks from being applied to an mmap()'ed file, but HP-UX -also disallows advisory locks for such a file. SVID actually specifies the -paranoid HP-UX behaviour. - -In my opinion only MAP_SHARED mappings should be immune from locking, and then -only from mandatory locks - that is what is currently implemented. - -SunOS is so hopeless that it doesn't even honour the O_NONBLOCK flag for -mandatory locks, so reads and writes to locked files always block when they -should return EAGAIN. - -I'm afraid that this is such an esoteric area that the semantics described -below are just as valid as any others, so long as the main points seem to -agree. - -4. Semantics ------------- - -1. Mandatory locks can only be applied via the fcntl()/lockf() locking - interface - in other words the System V/POSIX interface. BSD style - locks using flock() never result in a mandatory lock. - -2. If a process has locked a region of a file with a mandatory read lock, then - other processes are permitted to read from that region. If any of these - processes attempts to write to the region it will block until the lock is - released, unless the process has opened the file with the O_NONBLOCK - flag in which case the system call will return immediately with the error - status EAGAIN. - -3. If a process has locked a region of a file with a mandatory write lock, all - attempts to read or write to that region block until the lock is released, - unless a process has opened the file with the O_NONBLOCK flag in which case - the system call will return immediately with the error status EAGAIN. - -4. Calls to open() with O_TRUNC, or to creat(), on a existing file that has - any mandatory locks owned by other processes will be rejected with the - error status EAGAIN. - -5. Attempts to apply a mandatory lock to a file that is memory mapped and - shared (via mmap() with MAP_SHARED) will be rejected with the error status - EAGAIN. - -6. Attempts to create a shared memory map of a file (via mmap() with MAP_SHARED) - that has any mandatory locks in effect will be rejected with the error status - EAGAIN. - -5. Which system calls are affected? ------------------------------------ - -Those which modify a file's contents, not just the inode. That gives read(), -write(), readv(), writev(), open(), creat(), mmap(), truncate() and -ftruncate(). truncate() and ftruncate() are considered to be "write" actions -for the purposes of mandatory locking. - -The affected region is usually defined as stretching from the current position -for the total number of bytes read or written. For the truncate calls it is -defined as the bytes of a file removed or added (we must also consider bytes -added, as a lock can specify just "the whole file", rather than a specific -range of bytes.) - -Note 3: I may have overlooked some system calls that need mandatory lock -checking in my eagerness to get this code out the door. Please let me know, or -better still fix the system calls yourself and submit a patch to me or Linus. - -6. Warning! ------------ - -Not even root can override a mandatory lock, so runaway processes can wreak -havoc if they lock crucial files. The way around it is to change the file -permissions (remove the setgid bit) before trying to read or write to it. -Of course, that might be a bit tricky if the system is hung :-( - -7. The "mand" mount option --------------------------- -Mandatory locking is disabled on all filesystems by default, and must be -administratively enabled by mounting with "-o mand". That mount option -is only allowed if the mounting task has the CAP_SYS_ADMIN capability. - -Since kernel v4.5, it is possible to disable mandatory locking -altogether by setting CONFIG_MANDATORY_FILE_LOCKING to "n". A kernel -with this disabled will reject attempts to mount filesystems with the -"mand" mount option with the error status EPERM. diff --git a/Documentation/filesystems/ntfs3.rst b/Documentation/filesystems/ntfs3.rst new file mode 100644 index 000000000000..ffe9ea0c1499 --- /dev/null +++ b/Documentation/filesystems/ntfs3.rst @@ -0,0 +1,106 @@ +.. SPDX-License-Identifier: GPL-2.0 + +===== +NTFS3 +===== + + +Summary and Features +==================== + +NTFS3 is fully functional NTFS Read-Write driver. The driver works with +NTFS versions up to 3.1, normal/compressed/sparse files +and journal replaying. File system type to use on mount is 'ntfs3'. + +- This driver implements NTFS read/write support for normal, sparse and + compressed files. +- Supports native journal replaying; +- Supports extended attributes + Predefined extended attributes: + - 'system.ntfs_security' gets/sets security + descriptor (SECURITY_DESCRIPTOR_RELATIVE) + - 'system.ntfs_attrib' gets/sets ntfs file/dir attributes. + Note: applied to empty files, this allows to switch type between + sparse(0x200), compressed(0x800) and normal; +- Supports NFS export of mounted NTFS volumes. + +Mount Options +============= + +The list below describes mount options supported by NTFS3 driver in addition to +generic ones. + +=============================================================================== + +nls=name This option informs the driver how to interpret path + strings and translate them to Unicode and back. If + this option is not set, the default codepage will be + used (CONFIG_NLS_DEFAULT). + Examples: + 'nls=utf8' + +uid= +gid= +umask= Controls the default permissions for files/directories created + after the NTFS volume is mounted. + +fmask= +dmask= Instead of specifying umask which applies both to + files and directories, fmask applies only to files and + dmask only to directories. + +nohidden Files with the Windows-specific HIDDEN (FILE_ATTRIBUTE_HIDDEN) + attribute will not be shown under Linux. + +sys_immutable Files with the Windows-specific SYSTEM + (FILE_ATTRIBUTE_SYSTEM) attribute will be marked as system + immutable files. + +discard Enable support of the TRIM command for improved performance + on delete operations, which is recommended for use with the + solid-state drives (SSD). + +force Forces the driver to mount partitions even if 'dirty' flag + (volume dirty) is set. Not recommended for use. + +sparse Create new files as "sparse". + +showmeta Use this parameter to show all meta-files (System Files) on + a mounted NTFS partition. + By default, all meta-files are hidden. + +prealloc Preallocate space for files excessively when file size is + increasing on writes. Decreases fragmentation in case of + parallel write operations to different files. + +no_acs_rules "No access rules" mount option sets access rights for + files/folders to 777 and owner/group to root. This mount + option absorbs all other permissions: + - permissions change for files/folders will be reported + as successful, but they will remain 777; + - owner/group change will be reported as successful, but + they will stay as root + +acl Support POSIX ACLs (Access Control Lists). Effective if + supported by Kernel. Not to be confused with NTFS ACLs. + The option specified as acl enables support for POSIX ACLs. + +noatime All files and directories will not update their last access + time attribute if a partition is mounted with this parameter. + This option can speed up file system operation. + +=============================================================================== + +ToDo list +========= + +- Full journaling support (currently journal replaying is supported) over JBD. + + +References +========== +https://www.paragon-software.com/home/ntfs-linux-professional/ + - Commercial version of the NTFS driver for Linux. + +almaz.alexandrovich@paragon-software.com + - Direct e-mail address for feedback and requests on the NTFS3 implementation. diff --git a/Documentation/filesystems/overlayfs.rst b/Documentation/filesystems/overlayfs.rst index 455ca86eb4fc..7da6c30ed596 100644 --- a/Documentation/filesystems/overlayfs.rst +++ b/Documentation/filesystems/overlayfs.rst @@ -427,6 +427,9 @@ b) If a file residing on a lower layer is opened for read-only and then memory mapped with MAP_SHARED, then subsequent changes to the file are not reflected in the memory mapping. +c) If a file residing on a lower layer is being executed, then opening that +file for write or truncating the file will not be denied with ETXTBSY. + The following options allow overlayfs to act more like a standards compliant filesystem: diff --git a/Documentation/filesystems/vfs.rst b/Documentation/filesystems/vfs.rst index 14c31eced416..bf5c48066fac 100644 --- a/Documentation/filesystems/vfs.rst +++ b/Documentation/filesystems/vfs.rst @@ -432,7 +432,7 @@ As of kernel 2.6.22, the following members are defined: const char *(*get_link) (struct dentry *, struct inode *, struct delayed_call *); int (*permission) (struct user_namespace *, struct inode *, int); - int (*get_acl)(struct inode *, int); + struct posix_acl * (*get_acl)(struct inode *, int, bool); int (*setattr) (struct user_namespace *, struct dentry *, struct iattr *); int (*getattr) (struct user_namespace *, const struct path *, struct kstat *, u32, unsigned int); ssize_t (*listxattr) (struct dentry *, char *, size_t); diff --git a/Documentation/firmware-guide/acpi/dsd/graph.rst b/Documentation/firmware-guide/acpi/dsd/graph.rst index 4341299aa937..0ced07cb1be3 100644 --- a/Documentation/firmware-guide/acpi/dsd/graph.rst +++ b/Documentation/firmware-guide/acpi/dsd/graph.rst @@ -159,7 +159,7 @@ References [2] Devicetree. https://www.devicetree.org, referenced 2016-10-03. -[3] Documentation/devicetree/bindings/graph.txt +[3] Documentation/devicetree/bindings/graph.txt [4] Device Properties UUID For _DSD. https://www.uefi.org/sites/default/files/resources/_DSD-device-properties-UUID.pdf, diff --git a/Documentation/fpga/dfl.rst b/Documentation/fpga/dfl.rst index 75df90d1e54c..ef9eec71f6f3 100644 --- a/Documentation/fpga/dfl.rst +++ b/Documentation/fpga/dfl.rst @@ -10,7 +10,7 @@ Authors: - Xu Yilun <yilun.xu@intel.com> The Device Feature List (DFL) FPGA framework (and drivers according to -this framework) hides the very details of low layer hardwares and provides +this framework) hides the very details of low layer hardware and provides unified interfaces to userspace. Applications could use these interfaces to configure, enumerate, open and access FPGA accelerators on platforms which implement the DFL in the device memory. Besides this, the DFL framework @@ -205,7 +205,7 @@ given Device Feature Lists and create platform devices for feature devices also abstracts operations for the private features and exposes common ops to feature device drivers. -The FPGA DFL Device could be different hardwares, e.g. PCIe device, platform +The FPGA DFL Device could be different hardware, e.g. PCIe device, platform device and etc. Its driver module is always loaded first once the device is created by the system. This driver plays an infrastructural role in the driver architecture. It locates the DFLs in the device memory, handles them diff --git a/Documentation/gpu/drm-kms.rst b/Documentation/gpu/drm-kms.rst index 87e5023e3f55..1ef7951ded5e 100644 --- a/Documentation/gpu/drm-kms.rst +++ b/Documentation/gpu/drm-kms.rst @@ -159,6 +159,8 @@ KMS Core Structures and Functions .. kernel-doc:: drivers/gpu/drm/drm_mode_config.c :export: +.. _kms_base_object_abstraction: + Modeset Base Object Abstraction =============================== @@ -463,6 +465,35 @@ KMS Properties This section of the documentation is primarily aimed at user-space developers. For the driver APIs, see the other sections. +Requirements +------------ + +KMS drivers might need to add extra properties to support new features. Each +new property introduced in a driver needs to meet a few requirements, in +addition to the one mentioned above: + +* It must be standardized, documenting: + + * The full, exact, name string; + * If the property is an enum, all the valid value name strings; + * What values are accepted, and what these values mean; + * What the property does and how it can be used; + * How the property might interact with other, existing properties. + +* It must provide a generic helper in the core code to register that + property on the object it attaches to. + +* Its content must be decoded by the core and provided in the object's + associated state structure. That includes anything drivers might want + to precompute, like struct drm_clip_rect for planes. + +* Its initial state must match the behavior prior to the property + introduction. This might be a fixed value matching what the hardware + does, or it may be inherited from the state the firmware left the + system in during boot. + +* An IGT test must be submitted where reasonable. + Property Types and Blob Property Support ---------------------------------------- @@ -508,8 +539,8 @@ Plane Composition Properties Damage Tracking Properties -------------------------- -.. kernel-doc:: drivers/gpu/drm/drm_damage_helper.c - :doc: overview +.. kernel-doc:: drivers/gpu/drm/drm_plane.c + :doc: damage tracking Color Management Properties --------------------------- diff --git a/Documentation/gpu/drm-uapi.rst b/Documentation/gpu/drm-uapi.rst index 04bdc7a91d53..199afb503ab1 100644 --- a/Documentation/gpu/drm-uapi.rst +++ b/Documentation/gpu/drm-uapi.rst @@ -37,6 +37,15 @@ Primary Nodes, DRM Master and Authentication .. kernel-doc:: include/drm/drm_auth.h :internal: + +.. _drm_leasing: + +DRM Display Resource Leasing +============================ + +.. kernel-doc:: drivers/gpu/drm/drm_lease.c + :doc: drm leasing + Open-Source Userspace Requirements ================================== @@ -457,6 +466,19 @@ Userspace API Structures .. kernel-doc:: include/uapi/drm/drm_mode.h :doc: overview +.. _crtc_index: + +CRTC index +---------- + +CRTC's have both an object ID and an index, and they are not the same thing. +The index is used in cases where a densely packed identifier for a CRTC is +needed, for instance a bitmask of CRTC's. The member possible_crtcs of struct +drm_mode_get_plane is an example. + +DRM_IOCTL_MODE_GETRESOURCES populates a structure with an array of CRTC ID's, +and the CRTC index is its position in this array. + .. kernel-doc:: include/uapi/drm/drm.h :internal: diff --git a/Documentation/gpu/i915.rst b/Documentation/gpu/i915.rst index 42ce0196930a..204ebdaadb45 100644 --- a/Documentation/gpu/i915.rst +++ b/Documentation/gpu/i915.rst @@ -422,9 +422,16 @@ Batchbuffer Parsing User Batchbuffer Execution -------------------------- +.. kernel-doc:: drivers/gpu/drm/i915/gem/i915_gem_context_types.h + .. kernel-doc:: drivers/gpu/drm/i915/gem/i915_gem_execbuffer.c :doc: User command execution +Scheduling +---------- +.. kernel-doc:: drivers/gpu/drm/i915/i915_scheduler_types.h + :functions: i915_sched_engine + Logical Rings, Logical Ring Contexts and Execlists -------------------------------------------------- @@ -518,6 +525,14 @@ GuC-based command submission .. kernel-doc:: drivers/gpu/drm/i915/gt/uc/intel_guc_submission.c :doc: GuC-based command submission +GuC ABI +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. kernel-doc:: drivers/gpu/drm/i915/gt/uc/abi/guc_messages_abi.h +.. kernel-doc:: drivers/gpu/drm/i915/gt/uc/abi/guc_communication_mmio_abi.h +.. kernel-doc:: drivers/gpu/drm/i915/gt/uc/abi/guc_communication_ctb_abi.h +.. kernel-doc:: drivers/gpu/drm/i915/gt/uc/abi/guc_actions_abi.h + HuC --- .. kernel-doc:: drivers/gpu/drm/i915/gt/uc/intel_huc.c diff --git a/Documentation/gpu/rfc/i915_gem_lmem.rst b/Documentation/gpu/rfc/i915_gem_lmem.rst index 675ba8620d66..b421a3c1806e 100644 --- a/Documentation/gpu/rfc/i915_gem_lmem.rst +++ b/Documentation/gpu/rfc/i915_gem_lmem.rst @@ -18,114 +18,5 @@ real, with all the uAPI bits is: * Route shmem backend over to TTM SYSTEM for discrete * TTM purgeable object support * Move i915 buddy allocator over to TTM - * MMAP ioctl mode(see `I915 MMAP`_) - * SET/GET ioctl caching(see `I915 SET/GET CACHING`_) * Send RFC(with mesa-dev on cc) for final sign off on the uAPI * Add pciid for DG1 and turn on uAPI for real - -New object placement and region query uAPI -========================================== -Starting from DG1 we need to give userspace the ability to allocate buffers from -device local-memory. Currently the driver supports gem_create, which can place -buffers in system memory via shmem, and the usual assortment of other -interfaces, like dumb buffers and userptr. - -To support this new capability, while also providing a uAPI which will work -beyond just DG1, we propose to offer three new bits of uAPI: - -DRM_I915_QUERY_MEMORY_REGIONS ------------------------------ -New query ID which allows userspace to discover the list of supported memory -regions(like system-memory and local-memory) for a given device. We identify -each region with a class and instance pair, which should be unique. The class -here would be DEVICE or SYSTEM, and the instance would be zero, on platforms -like DG1. - -Side note: The class/instance design is borrowed from our existing engine uAPI, -where we describe every physical engine in terms of its class, and the -particular instance, since we can have more than one per class. - -In the future we also want to expose more information which can further -describe the capabilities of a region. - -.. kernel-doc:: include/uapi/drm/i915_drm.h - :functions: drm_i915_gem_memory_class drm_i915_gem_memory_class_instance drm_i915_memory_region_info drm_i915_query_memory_regions - -GEM_CREATE_EXT --------------- -New ioctl which is basically just gem_create but now allows userspace to provide -a chain of possible extensions. Note that if we don't provide any extensions and -set flags=0 then we get the exact same behaviour as gem_create. - -Side note: We also need to support PXP[1] in the near future, which is also -applicable to integrated platforms, and adds its own gem_create_ext extension, -which basically lets userspace mark a buffer as "protected". - -.. kernel-doc:: include/uapi/drm/i915_drm.h - :functions: drm_i915_gem_create_ext - -I915_GEM_CREATE_EXT_MEMORY_REGIONS ----------------------------------- -Implemented as an extension for gem_create_ext, we would now allow userspace to -optionally provide an immutable list of preferred placements at creation time, -in priority order, for a given buffer object. For the placements we expect -them each to use the class/instance encoding, as per the output of the regions -query. Having the list in priority order will be useful in the future when -placing an object, say during eviction. - -.. kernel-doc:: include/uapi/drm/i915_drm.h - :functions: drm_i915_gem_create_ext_memory_regions - -One fair criticism here is that this seems a little over-engineered[2]. If we -just consider DG1 then yes, a simple gem_create.flags or something is totally -all that's needed to tell the kernel to allocate the buffer in local-memory or -whatever. However looking to the future we need uAPI which can also support -upcoming Xe HP multi-tile architecture in a sane way, where there can be -multiple local-memory instances for a given device, and so using both class and -instance in our uAPI to describe regions is desirable, although specifically -for DG1 it's uninteresting, since we only have a single local-memory instance. - -Existing uAPI issues -==================== -Some potential issues we still need to resolve. - -I915 MMAP ---------- -In i915 there are multiple ways to MMAP GEM object, including mapping the same -object using different mapping types(WC vs WB), i.e multiple active mmaps per -object. TTM expects one MMAP at most for the lifetime of the object. If it -turns out that we have to backpedal here, there might be some potential -userspace fallout. - -I915 SET/GET CACHING --------------------- -In i915 we have set/get_caching ioctl. TTM doesn't let us to change this, but -DG1 doesn't support non-snooped pcie transactions, so we can just always -allocate as WB for smem-only buffers. If/when our hw gains support for -non-snooped pcie transactions then we must fix this mode at allocation time as -a new GEM extension. - -This is related to the mmap problem, because in general (meaning, when we're -not running on intel cpus) the cpu mmap must not, ever, be inconsistent with -allocation mode. - -Possible idea is to let the kernel picks the mmap mode for userspace from the -following table: - -smem-only: WB. Userspace does not need to call clflush. - -smem+lmem: We only ever allow a single mode, so simply allocate this as uncached -memory, and always give userspace a WC mapping. GPU still does snooped access -here(assuming we can't turn it off like on DG1), which is a bit inefficient. - -lmem only: always WC - -This means on discrete you only get a single mmap mode, all others must be -rejected. That's probably going to be a new default mode or something like -that. - -Links -===== -[1] https://patchwork.freedesktop.org/series/86798/ - -[2] https://gitlab.freedesktop.org/mesa/mesa/-/merge_requests/5599#note_553791 diff --git a/Documentation/gpu/rfc/i915_parallel_execbuf.h b/Documentation/gpu/rfc/i915_parallel_execbuf.h new file mode 100644 index 000000000000..8cbe2c4e0172 --- /dev/null +++ b/Documentation/gpu/rfc/i915_parallel_execbuf.h @@ -0,0 +1,122 @@ +/* SPDX-License-Identifier: MIT */ +/* + * Copyright © 2021 Intel Corporation + */ + +#define I915_CONTEXT_ENGINES_EXT_PARALLEL_SUBMIT 2 /* see i915_context_engines_parallel_submit */ + +/** + * struct drm_i915_context_engines_parallel_submit - Configure engine for + * parallel submission. + * + * Setup a slot in the context engine map to allow multiple BBs to be submitted + * in a single execbuf IOCTL. Those BBs will then be scheduled to run on the GPU + * in parallel. Multiple hardware contexts are created internally in the i915 + * run these BBs. Once a slot is configured for N BBs only N BBs can be + * submitted in each execbuf IOCTL and this is implicit behavior e.g. The user + * doesn't tell the execbuf IOCTL there are N BBs, the execbuf IOCTL knows how + * many BBs there are based on the slot's configuration. The N BBs are the last + * N buffer objects or first N if I915_EXEC_BATCH_FIRST is set. + * + * The default placement behavior is to create implicit bonds between each + * context if each context maps to more than 1 physical engine (e.g. context is + * a virtual engine). Also we only allow contexts of same engine class and these + * contexts must be in logically contiguous order. Examples of the placement + * behavior described below. Lastly, the default is to not allow BBs to + * preempted mid BB rather insert coordinated preemption on all hardware + * contexts between each set of BBs. Flags may be added in the future to change + * both of these default behaviors. + * + * Returns -EINVAL if hardware context placement configuration is invalid or if + * the placement configuration isn't supported on the platform / submission + * interface. + * Returns -ENODEV if extension isn't supported on the platform / submission + * interface. + * + * .. code-block:: none + * + * Example 1 pseudo code: + * CS[X] = generic engine of same class, logical instance X + * INVALID = I915_ENGINE_CLASS_INVALID, I915_ENGINE_CLASS_INVALID_NONE + * set_engines(INVALID) + * set_parallel(engine_index=0, width=2, num_siblings=1, + * engines=CS[0],CS[1]) + * + * Results in the following valid placement: + * CS[0], CS[1] + * + * Example 2 pseudo code: + * CS[X] = generic engine of same class, logical instance X + * INVALID = I915_ENGINE_CLASS_INVALID, I915_ENGINE_CLASS_INVALID_NONE + * set_engines(INVALID) + * set_parallel(engine_index=0, width=2, num_siblings=2, + * engines=CS[0],CS[2],CS[1],CS[3]) + * + * Results in the following valid placements: + * CS[0], CS[1] + * CS[2], CS[3] + * + * This can also be thought of as 2 virtual engines described by 2-D array + * in the engines the field with bonds placed between each index of the + * virtual engines. e.g. CS[0] is bonded to CS[1], CS[2] is bonded to + * CS[3]. + * VE[0] = CS[0], CS[2] + * VE[1] = CS[1], CS[3] + * + * Example 3 pseudo code: + * CS[X] = generic engine of same class, logical instance X + * INVALID = I915_ENGINE_CLASS_INVALID, I915_ENGINE_CLASS_INVALID_NONE + * set_engines(INVALID) + * set_parallel(engine_index=0, width=2, num_siblings=2, + * engines=CS[0],CS[1],CS[1],CS[3]) + * + * Results in the following valid and invalid placements: + * CS[0], CS[1] + * CS[1], CS[3] - Not logical contiguous, return -EINVAL + */ +struct drm_i915_context_engines_parallel_submit { + /** + * @base: base user extension. + */ + struct i915_user_extension base; + + /** + * @engine_index: slot for parallel engine + */ + __u16 engine_index; + + /** + * @width: number of contexts per parallel engine + */ + __u16 width; + + /** + * @num_siblings: number of siblings per context + */ + __u16 num_siblings; + + /** + * @mbz16: reserved for future use; must be zero + */ + __u16 mbz16; + + /** + * @flags: all undefined flags must be zero, currently not defined flags + */ + __u64 flags; + + /** + * @mbz64: reserved for future use; must be zero + */ + __u64 mbz64[3]; + + /** + * @engines: 2-d array of engine instances to configure parallel engine + * + * length = width (i) * num_siblings (j) + * index = j + i * num_siblings + */ + struct i915_engine_class_instance engines[0]; + +} __packed; + diff --git a/Documentation/gpu/rfc/i915_scheduler.rst b/Documentation/gpu/rfc/i915_scheduler.rst new file mode 100644 index 000000000000..cbda75065dad --- /dev/null +++ b/Documentation/gpu/rfc/i915_scheduler.rst @@ -0,0 +1,148 @@ +========================================= +I915 GuC Submission/DRM Scheduler Section +========================================= + +Upstream plan +============= +For upstream the overall plan for landing GuC submission and integrating the +i915 with the DRM scheduler is: + +* Merge basic GuC submission + * Basic submission support for all gen11+ platforms + * Not enabled by default on any current platforms but can be enabled via + modparam enable_guc + * Lots of rework will need to be done to integrate with DRM scheduler so + no need to nit pick everything in the code, it just should be + functional, no major coding style / layering errors, and not regress + execlists + * Update IGTs / selftests as needed to work with GuC submission + * Enable CI on supported platforms for a baseline + * Rework / get CI heathly for GuC submission in place as needed +* Merge new parallel submission uAPI + * Bonding uAPI completely incompatible with GuC submission, plus it has + severe design issues in general, which is why we want to retire it no + matter what + * New uAPI adds I915_CONTEXT_ENGINES_EXT_PARALLEL context setup step + which configures a slot with N contexts + * After I915_CONTEXT_ENGINES_EXT_PARALLEL a user can submit N batches to + a slot in a single execbuf IOCTL and the batches run on the GPU in + paralllel + * Initially only for GuC submission but execlists can be supported if + needed +* Convert the i915 to use the DRM scheduler + * GuC submission backend fully integrated with DRM scheduler + * All request queues removed from backend (e.g. all backpressure + handled in DRM scheduler) + * Resets / cancels hook in DRM scheduler + * Watchdog hooks into DRM scheduler + * Lots of complexity of the GuC backend can be pulled out once + integrated with DRM scheduler (e.g. state machine gets + simplier, locking gets simplier, etc...) + * Execlists backend will minimum required to hook in the DRM scheduler + * Legacy interface + * Features like timeslicing / preemption / virtual engines would + be difficult to integrate with the DRM scheduler and these + features are not required for GuC submission as the GuC does + these things for us + * ROI low on fully integrating into DRM scheduler + * Fully integrating would add lots of complexity to DRM + scheduler + * Port i915 priority inheritance / boosting feature in DRM scheduler + * Used for i915 page flip, may be useful to other DRM drivers as + well + * Will be an optional feature in the DRM scheduler + * Remove in-order completion assumptions from DRM scheduler + * Even when using the DRM scheduler the backends will handle + preemption, timeslicing, etc... so it is possible for jobs to + finish out of order + * Pull out i915 priority levels and use DRM priority levels + * Optimize DRM scheduler as needed + +TODOs for GuC submission upstream +================================= + +* Need an update to GuC firmware / i915 to enable error state capture +* Open source tool to decode GuC logs +* Public GuC spec + +New uAPI for basic GuC submission +================================= +No major changes are required to the uAPI for basic GuC submission. The only +change is a new scheduler attribute: I915_SCHEDULER_CAP_STATIC_PRIORITY_MAP. +This attribute indicates the 2k i915 user priority levels are statically mapped +into 3 levels as follows: + +* -1k to -1 Low priority +* 0 Medium priority +* 1 to 1k High priority + +This is needed because the GuC only has 4 priority bands. The highest priority +band is reserved with the kernel. This aligns with the DRM scheduler priority +levels too. + +Spec references: +---------------- +* https://www.khronos.org/registry/EGL/extensions/IMG/EGL_IMG_context_priority.txt +* https://www.khronos.org/registry/vulkan/specs/1.2-extensions/html/chap5.html#devsandqueues-priority +* https://spec.oneapi.com/level-zero/latest/core/api.html#ze-command-queue-priority-t + +New parallel submission uAPI +============================ +The existing bonding uAPI is completely broken with GuC submission because +whether a submission is a single context submit or parallel submit isn't known +until execbuf time activated via the I915_SUBMIT_FENCE. To submit multiple +contexts in parallel with the GuC the context must be explicitly registered with +N contexts and all N contexts must be submitted in a single command to the GuC. +The GuC interfaces do not support dynamically changing between N contexts as the +bonding uAPI does. Hence the need for a new parallel submission interface. Also +the legacy bonding uAPI is quite confusing and not intuitive at all. Furthermore +I915_SUBMIT_FENCE is by design a future fence, so not really something we should +continue to support. + +The new parallel submission uAPI consists of 3 parts: + +* Export engines logical mapping +* A 'set_parallel' extension to configure contexts for parallel + submission +* Extend execbuf2 IOCTL to support submitting N BBs in a single IOCTL + +Export engines logical mapping +------------------------------ +Certain use cases require BBs to be placed on engine instances in logical order +(e.g. split-frame on gen11+). The logical mapping of engine instances can change +based on fusing. Rather than making UMDs be aware of fusing, simply expose the +logical mapping with the existing query engine info IOCTL. Also the GuC +submission interface currently only supports submitting multiple contexts to +engines in logical order which is a new requirement compared to execlists. +Lastly, all current platforms have at most 2 engine instances and the logical +order is the same as uAPI order. This will change on platforms with more than 2 +engine instances. + +A single bit will be added to drm_i915_engine_info.flags indicating that the +logical instance has been returned and a new field, +drm_i915_engine_info.logical_instance, returns the logical instance. + +A 'set_parallel' extension to configure contexts for parallel submission +------------------------------------------------------------------------ +The 'set_parallel' extension configures a slot for parallel submission of N BBs. +It is a setup step that must be called before using any of the contexts. See +I915_CONTEXT_ENGINES_EXT_LOAD_BALANCE or I915_CONTEXT_ENGINES_EXT_BOND for +similar existing examples. Once a slot is configured for parallel submission the +execbuf2 IOCTL can be called submitting N BBs in a single IOCTL. Initially only +supports GuC submission. Execlists supports can be added later if needed. + +Add I915_CONTEXT_ENGINES_EXT_PARALLEL_SUBMIT and +drm_i915_context_engines_parallel_submit to the uAPI to implement this +extension. + +.. kernel-doc:: Documentation/gpu/rfc/i915_parallel_execbuf.h + :functions: drm_i915_context_engines_parallel_submit + +Extend execbuf2 IOCTL to support submitting N BBs in a single IOCTL +------------------------------------------------------------------- +Contexts that have been configured with the 'set_parallel' extension can only +submit N BBs in a single execbuf2 IOCTL. The BBs are either the last N objects +in the drm_i915_gem_exec_object2 list or the first N if I915_EXEC_BATCH_FIRST is +set. The number of BBs is implicit based on the slot submitted and how it has +been configured by 'set_parallel' or other extensions. No uAPI changes are +required to the execbuf2 IOCTL. diff --git a/Documentation/gpu/rfc/index.rst b/Documentation/gpu/rfc/index.rst index 05670442ca1b..91e93a705230 100644 --- a/Documentation/gpu/rfc/index.rst +++ b/Documentation/gpu/rfc/index.rst @@ -19,3 +19,7 @@ host such documentation: .. toctree:: i915_gem_lmem.rst + +.. toctree:: + + i915_scheduler.rst diff --git a/Documentation/gpu/vkms.rst b/Documentation/gpu/vkms.rst index 2c9b376da5ca..941f0e7e5eef 100644 --- a/Documentation/gpu/vkms.rst +++ b/Documentation/gpu/vkms.rst @@ -98,9 +98,17 @@ with VKMS maintainers. IGT better support ------------------ -- Investigate: (1) test cases on kms_plane that are failing due to timeout on - capturing CRC; (2) when running kms_flip test cases in sequence, some - successful individual test cases are failing randomly. +Debugging: + +- kms_plane: some test cases are failing due to timeout on capturing CRC; + +- kms_flip: when running test cases in sequence, some successful individual + test cases are failing randomly; when individually, some successful test + cases display in the log the following error:: + + [drm:vkms_prepare_fb [vkms]] ERROR vmap failed: -4 + +Virtual hardware (vblank-less) mode: - VKMS already has support for vblanks simulated via hrtimers, which can be tested with kms_flip test; in some way, we can say that VKMS already mimics @@ -116,7 +124,17 @@ Add Plane Features There's lots of plane features we could add support for: -- Real overlay planes, not just cursor. +- Multiple overlay planes. [Good to get started] + +- Clearing primary plane: clear primary plane before plane composition (at the + start) for correctness of pixel blend ops. It also guarantees alpha channel + is cleared in the target buffer for stable crc. [Good to get started] + +- ARGB format on primary plane: blend the primary plane into background with + translucent alpha. + +- Support when the primary plane isn't exactly matching the output size: blend + the primary plane into the black background. - Full alpha blending on all planes. @@ -129,13 +147,8 @@ There's lots of plane features we could add support for: cursor api). For all of these, we also want to review the igt test coverage and make sure -all relevant igt testcases work on vkms. - -Prime Buffer Sharing --------------------- - -- Syzbot report - WARNING in vkms_gem_free_object: - https://syzkaller.appspot.com/bug?extid=e7ad70d406e74d8fc9d0 +all relevant igt testcases work on vkms. They are good options for internship +project. Runtime Configuration --------------------- @@ -153,7 +166,7 @@ module. Use/Test-cases: the refresh rate. The currently proposed solution is to expose vkms configuration through -configfs. All existing module options should be supported through configfs +configfs. All existing module options should be supported through configfs too. Writeback support @@ -162,6 +175,7 @@ Writeback support - The writeback and CRC capture operations share the use of composer_enabled boolean to ensure vblanks. Probably, when these operations work together, composer_enabled needs to refcounting the composer state to proper work. + [Good to get started] - Add support for cloned writeback outputs and related test cases using a cloned output in the IGT kms_writeback. diff --git a/Documentation/hwmon/aquacomputer_d5next.rst b/Documentation/hwmon/aquacomputer_d5next.rst new file mode 100644 index 000000000000..1f4bb4ba2e4b --- /dev/null +++ b/Documentation/hwmon/aquacomputer_d5next.rst @@ -0,0 +1,61 @@ +.. SPDX-License-Identifier: GPL-2.0-or-later + +Kernel driver aquacomputer-d5next +================================= + +Supported devices: + +* Aquacomputer D5 Next watercooling pump + +Author: Aleksa Savic + +Description +----------- + +This driver exposes hardware sensors of the Aquacomputer D5 Next watercooling +pump, which communicates through a proprietary USB HID protocol. + +Available sensors are pump and fan speed, power, voltage and current, as +well as coolant temperature. Also available through debugfs are the serial +number, firmware version and power-on count. + +Attaching a fan is optional and allows it to be controlled using temperature +curves directly from the pump. If it's not connected, the fan-related sensors +will report zeroes. + +The pump can be configured either through software or via its physical +interface. Configuring the pump through this driver is not implemented, as it +seems to require sending it a complete configuration. That includes addressable +RGB LEDs, for which there is no standard sysfs interface. Thus, that task is +better suited for userspace tools. + +Usage notes +----------- + +The pump communicates via HID reports. The driver is loaded automatically by +the kernel and supports hotswapping. + +Sysfs entries +------------- + +============ ============================================= +temp1_input Coolant temperature (in millidegrees Celsius) +fan1_input Pump speed (in RPM) +fan2_input Fan speed (in RPM) +power1_input Pump power (in micro Watts) +power2_input Fan power (in micro Watts) +in0_input Pump voltage (in milli Volts) +in1_input Fan voltage (in milli Volts) +in2_input +5V rail voltage (in milli Volts) +curr1_input Pump current (in milli Amperes) +curr2_input Fan current (in milli Amperes) +============ ============================================= + +Debugfs entries +--------------- + +================ =============================================== +serial_number Serial number of the pump +firmware_version Version of installed firmware +power_cycles Count of how many times the pump was powered on +================ =============================================== diff --git a/Documentation/hwmon/index.rst b/Documentation/hwmon/index.rst index bc01601ea81a..f790f1260c33 100644 --- a/Documentation/hwmon/index.rst +++ b/Documentation/hwmon/index.rst @@ -39,6 +39,7 @@ Hardware Monitoring Kernel Drivers adt7475 aht10 amc6821 + aquacomputer_d5next asb100 asc7621 aspeed-pwm-tacho @@ -160,6 +161,7 @@ Hardware Monitoring Kernel Drivers pwm-fan q54sj108a2 raspberrypi-hwmon + sbrmi sbtsi_temp sch5627 sch5636 diff --git a/Documentation/hwmon/sbrmi.rst b/Documentation/hwmon/sbrmi.rst new file mode 100644 index 000000000000..296049e13ac9 --- /dev/null +++ b/Documentation/hwmon/sbrmi.rst @@ -0,0 +1,79 @@ +.. SPDX-License-Identifier: GPL-2.0-or-later + +Kernel driver sbrmi +=================== + +Supported hardware: + + * Sideband Remote Management Interface (SB-RMI) compliant AMD SoC + device connected to the BMC via the APML. + + Prefix: 'sbrmi' + + Addresses scanned: This driver doesn't support address scanning. + + To instantiate this driver on an AMD CPU with SB-RMI + support, the i2c bus number would be the bus connected from the board + management controller (BMC) to the CPU. + The SMBus address is really 7 bits. Some vendors and the SMBus + specification show the address as 8 bits, left justified with the R/W + bit as a write (0) making bit 0. Some vendors use only the 7 bits + to describe the address. + As mentioned in AMD's APML specification, The SB-RMI address is + normally 78h(0111 100W) or 3Ch(011 1100) for socket 0 and 70h(0111 000W) + or 38h(011 1000) for socket 1, but it could vary based on hardware + address select pins. + + Datasheet: The SB-RMI interface and protocol along with the Advanced + Platform Management Link (APML) Specification is available + as part of the open source SoC register reference at: + + https://www.amd.com/en/support/tech-docs?keyword=55898 + +Author: Akshay Gupta <akshay.gupta@amd.com> + +Description +----------- + +The APML provides a way to communicate with the SB Remote Management interface +(SB-RMI) module from the external SMBus master that can be used to report socket +power on AMD platforms using mailbox command and resembles a typical 8-pin remote +power sensor's I2C interface to BMC. + +This driver implements current power with power cap and power cap max. + +sysfs-Interface +--------------- +Power sensors can be queried and set via the standard ``hwmon`` interface +on ``sysfs``, under the directory ``/sys/class/hwmon/hwmonX`` for some value +of ``X`` (search for the ``X`` such that ``/sys/class/hwmon/hwmonX/name`` has +content ``sbrmi``) + +================ ===== ======================================================== +Name Perm Description +================ ===== ======================================================== +power1_input RO Current Power consumed +power1_cap RW Power limit can be set between 0 and power1_cap_max +power1_cap_max RO Maximum powerlimit calculated and reported by the SMU FW +================ ===== ======================================================== + +The following example show how the 'Power' attribute from the i2c-addresses +can be monitored using the userspace utilities like ``sensors`` binary:: + + # sensors + sbrmi-i2c-1-38 + Adapter: bcm2835 I2C adapter + power1: 61.00 W (cap = 225.00 W) + + sbrmi-i2c-1-3c + Adapter: bcm2835 I2C adapter + power1: 28.39 W (cap = 224.77 W) + # + +Also, Below shows how get and set the values from sysfs entries individually:: + # cat /sys/class/hwmon/hwmon1/power1_cap_max + 225000000 + + # echo 180000000 > /sys/class/hwmon/hwmon1/power1_cap + # cat /sys/class/hwmon/hwmon1/power1_cap + 180000000 diff --git a/Documentation/hwmon/scpi-hwmon.rst b/Documentation/hwmon/scpi-hwmon.rst index eee7022b44db..1e3f83ec0658 100644 --- a/Documentation/hwmon/scpi-hwmon.rst +++ b/Documentation/hwmon/scpi-hwmon.rst @@ -32,5 +32,5 @@ Usage Notes The driver relies on device tree node to indicate the presence of SCPI support in the kernel. See -Documentation/devicetree/bindings/arm/arm,scpi.txt for details of the +Documentation/devicetree/bindings/firmware/arm,scpi.yaml for details of the devicetree node. diff --git a/Documentation/hwmon/sht4x.rst b/Documentation/hwmon/sht4x.rst index 3b37abcd4a46..c318e5582ead 100644 --- a/Documentation/hwmon/sht4x.rst +++ b/Documentation/hwmon/sht4x.rst @@ -42,4 +42,4 @@ humidity1_input Measured humidity in %H update_interval The minimum interval for polling the sensor, in milliseconds. Writable. Must be at least 2000. -============== ============================================= +=============== ============================================ diff --git a/Documentation/i2c/index.rst b/Documentation/i2c/index.rst index 8b76217e370a..6270f1fd7d4e 100644 --- a/Documentation/i2c/index.rst +++ b/Documentation/i2c/index.rst @@ -17,6 +17,7 @@ Introduction busses/index i2c-topology muxes/i2c-mux-gpio + i2c-sysfs Writing device drivers ====================== diff --git a/Documentation/kbuild/llvm.rst b/Documentation/kbuild/llvm.rst index b18401d2ba82..e87ed5479963 100644 --- a/Documentation/kbuild/llvm.rst +++ b/Documentation/kbuild/llvm.rst @@ -38,7 +38,7 @@ Cross Compiling A single Clang compiler binary will typically contain all supported backends, which can help simplify cross compiling. :: - ARCH=arm64 CROSS_COMPILE=aarch64-linux-gnu- make CC=clang + make ARCH=arm64 CC=clang CROSS_COMPILE=aarch64-linux-gnu- ``CROSS_COMPILE`` is not used to prefix the Clang compiler binary, instead ``CROSS_COMPILE`` is used to set a command line flag: ``--target=<triple>``. For @@ -60,8 +60,27 @@ They can be enabled individually. The full list of the parameters: :: OBJCOPY=llvm-objcopy OBJDUMP=llvm-objdump READELF=llvm-readelf \ HOSTCC=clang HOSTCXX=clang++ HOSTAR=llvm-ar HOSTLD=ld.lld -Currently, the integrated assembler is disabled by default. You can pass -``LLVM_IAS=1`` to enable it. +The integrated assembler is enabled by default. You can pass ``LLVM_IAS=0`` to +disable it. + +Omitting CROSS_COMPILE +---------------------- + +As explained above, ``CROSS_COMPILE`` is used to set ``--target=<triple>``. + +If ``CROSS_COMPILE`` is not specified, the ``--target=<triple>`` is inferred +from ``ARCH``. + +That means if you use only LLVM tools, ``CROSS_COMPILE`` becomes unnecessary. + +For example, to cross-compile the arm64 kernel:: + + make ARCH=arm64 LLVM=1 + +If ``LLVM_IAS=0`` is specified, ``CROSS_COMPILE`` is also used to derive +``--prefix=<path>`` to search for the GNU assembler and linker. :: + + make ARCH=arm64 LLVM=1 LLVM_IAS=0 CROSS_COMPILE=aarch64-linux-gnu- Supported Architectures ----------------------- diff --git a/Documentation/leds/well-known-leds.txt b/Documentation/leds/well-known-leds.txt new file mode 100644 index 000000000000..4a8b9dc4bf52 --- /dev/null +++ b/Documentation/leds/well-known-leds.txt @@ -0,0 +1,58 @@ +-*- org -*- + +It is somehow important to provide consistent interface to the +userland. LED devices have one problem there, and that is naming of +directories in /sys/class/leds. It would be nice if userland would +just know right "name" for given LED function, but situation got more +complex. + +Anyway, if backwards compatibility is not an issue, new code should +use one of the "good" names from this list, and you should extend the +list where applicable. + +Legacy names are listed, too; in case you are writing application that +wants to use particular feature, you should probe for good name, first, +but then try the legacy ones, too. + +Notice there's a list of functions in include/dt-bindings/leds/common.h . + +* Keyboards + +Good: "input*:*:capslock" +Good: "input*:*:scrolllock" +Good: "input*:*:numlock" +Legacy: "shift-key-light" (Motorola Droid 4, capslock) + +Set of common keyboard LEDs, going back to PC AT or so. + +Legacy: "tpacpi::thinklight" (IBM/Lenovo Thinkpads) +Legacy: "lp5523:kb{1,2,3,4,5,6}" (Nokia N900) + +Frontlight/backlight of main keyboard. + +Legacy: "button-backlight" (Motorola Droid 4) + +Some phones have touch buttons below screen; it is different from main +keyboard. And this is their backlight. + +* Sound subsystem + +Good: "platform:*:mute" +Good: "platform:*:micmute" + +LEDs on notebook body, indicating that sound input / output is muted. + +* System notification + +Legacy: "status-led:{red,green,blue}" (Motorola Droid 4) +Legacy: "lp5523:{r,g,b}" (Nokia N900) + +Phones usually have multi-color status LED. + +* Power management + +Good: "platform:*:charging" (allwinner sun50i) + +* Screen + +Good: ":backlight" (Motorola Droid 4) diff --git a/Documentation/networking/af_xdp.rst b/Documentation/networking/af_xdp.rst index 42576880aa4a..60b217b436be 100644 --- a/Documentation/networking/af_xdp.rst +++ b/Documentation/networking/af_xdp.rst @@ -243,8 +243,8 @@ Configuration Flags and Socket Options These are the various configuration flags that can be used to control and monitor the behavior of AF_XDP sockets. -XDP_COPY and XDP_ZERO_COPY bind flags -------------------------------------- +XDP_COPY and XDP_ZEROCOPY bind flags +------------------------------------ When you bind to a socket, the kernel will first try to use zero-copy copy. If zero-copy is not supported, it will fall back on using copy @@ -252,7 +252,7 @@ mode, i.e. copying all packets out to user space. But if you would like to force a certain mode, you can use the following flags. If you pass the XDP_COPY flag to the bind call, the kernel will force the socket into copy mode. If it cannot use copy mode, the bind call will -fail with an error. Conversely, the XDP_ZERO_COPY flag will force the +fail with an error. Conversely, the XDP_ZEROCOPY flag will force the socket into zero-copy mode or fail. XDP_SHARED_UMEM bind flag diff --git a/Documentation/networking/batman-adv.rst b/Documentation/networking/batman-adv.rst index 74821d29a22f..b85563ea3682 100644 --- a/Documentation/networking/batman-adv.rst +++ b/Documentation/networking/batman-adv.rst @@ -157,7 +157,7 @@ Contact Please send us comments, experiences, questions, anything :) IRC: - #batman on irc.freenode.org + #batadv on ircs://irc.hackint.org/ Mailing-list: b.a.t.m.a.n@open-mesh.org (optional subscription at https://lists.open-mesh.org/mailman3/postorius/lists/b.a.t.m.a.n.lists.open-mesh.org/) diff --git a/Documentation/networking/bonding.rst b/Documentation/networking/bonding.rst index 62f2aab8eaec..31cfd7d674a6 100644 --- a/Documentation/networking/bonding.rst +++ b/Documentation/networking/bonding.rst @@ -501,6 +501,18 @@ fail_over_mac This option was added in bonding version 3.2.0. The "follow" policy was added in bonding version 3.3.0. +lacp_active + Option specifying whether to send LACPDU frames periodically. + + off or 0 + LACPDU frames acts as "speak when spoken to". + + on or 1 + LACPDU frames are sent along the configured links + periodically. See lacp_rate for more details. + + The default is on. + lacp_rate Option specifying the rate in which we'll ask our link partner diff --git a/Documentation/networking/device_drivers/ethernet/freescale/dpaa2/dpio-driver.rst b/Documentation/networking/device_drivers/ethernet/freescale/dpaa2/dpio-driver.rst index c50fd46631e0..e4ebfe62a183 100644 --- a/Documentation/networking/device_drivers/ethernet/freescale/dpaa2/dpio-driver.rst +++ b/Documentation/networking/device_drivers/ethernet/freescale/dpaa2/dpio-driver.rst @@ -1,5 +1,6 @@ .. include:: <isonum.txt> +=================================== DPAA2 DPIO (Data Path I/O) Overview =================================== diff --git a/Documentation/networking/device_drivers/ethernet/freescale/dpaa2/index.rst b/Documentation/networking/device_drivers/ethernet/freescale/dpaa2/index.rst index ee40fcc5ddff..62f4a4aff6ec 100644 --- a/Documentation/networking/device_drivers/ethernet/freescale/dpaa2/index.rst +++ b/Documentation/networking/device_drivers/ethernet/freescale/dpaa2/index.rst @@ -9,3 +9,4 @@ DPAA2 Documentation dpio-driver ethernet-driver mac-phy-support + switch-driver diff --git a/Documentation/networking/device_drivers/ethernet/freescale/dpaa2/switch-driver.rst b/Documentation/networking/device_drivers/ethernet/freescale/dpaa2/switch-driver.rst new file mode 100644 index 000000000000..8bf411b857d4 --- /dev/null +++ b/Documentation/networking/device_drivers/ethernet/freescale/dpaa2/switch-driver.rst @@ -0,0 +1,217 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. include:: <isonum.txt> + +=================== +DPAA2 Switch driver +=================== + +:Copyright: |copy| 2021 NXP + +The DPAA2 Switch driver probes on the Datapath Switch (DPSW) object which can +be instantiated on the following DPAA2 SoCs and their variants: LS2088A and +LX2160A. + +The driver uses the switch device driver model and exposes each switch port as +a network interface, which can be included in a bridge or used as a standalone +interface. Traffic switched between ports is offloaded into the hardware. + +The DPSW can have ports connected to DPNIs or to DPMACs for external access. +:: + + [ethA] [ethB] [ethC] [ethD] [ethE] [ethF] + : : : : : : + : : : : : : + [dpaa2-eth] [dpaa2-eth] [ dpaa2-switch ] + : : : : : : kernel + ============================================================================= + : : : : : : hardware + [DPNI] [DPNI] [============= DPSW =================] + | | | | | | + | ---------- | [DPMAC] [DPMAC] + ------------------------------- | | + | | + [PHY] [PHY] + +Creating an Ethernet Switch +=========================== + +The dpaa2-switch driver probes on DPSW devices found on the fsl-mc bus. These +devices can be either created statically through the boot time configuration +file - DataPath Layout (DPL) - or at runtime using the DPAA2 object APIs +(incorporated already into the restool userspace tool). + +At the moment, the dpaa2-switch driver imposes the following restrictions on +the DPSW object that it will probe: + + * The minimum number of FDBs should be at least equal to the number of switch + interfaces. This is necessary so that separation of switch ports can be + done, ie when not under a bridge, each switch port will have its own FDB. + :: + + fsl_dpaa2_switch dpsw.0: The number of FDBs is lower than the number of ports, cannot probe + + * Both the broadcast and flooding configuration should be per FDB. This + enables the driver to restrict the broadcast and flooding domains of each + FDB depending on the switch ports that are sharing it (aka are under the + same bridge). + :: + + fsl_dpaa2_switch dpsw.0: Flooding domain is not per FDB, cannot probe + fsl_dpaa2_switch dpsw.0: Broadcast domain is not per FDB, cannot probe + + * The control interface of the switch should not be disabled + (DPSW_OPT_CTRL_IF_DIS not passed as a create time option). Without the + control interface, the driver is not capable to provide proper Rx/Tx traffic + support on the switch port netdevices. + :: + + fsl_dpaa2_switch dpsw.0: Control Interface is disabled, cannot probe + +Besides the configuration of the actual DPSW object, the dpaa2-switch driver +will need the following DPAA2 objects: + + * 1 DPMCP - A Management Command Portal object is needed for any interraction + with the MC firmware. + + * 1 DPBP - A Buffer Pool is used for seeding buffers intended for the Rx path + on the control interface. + + * Access to at least one DPIO object (Software Portal) is needed for any + enqueue/dequeue operation to be performed on the control interface queues. + The DPIO object will be shared, no need for a private one. + +Switching features +================== + +The driver supports the configuration of L2 forwarding rules in hardware for +port bridging as well as standalone usage of the independent switch interfaces. + +The hardware is not configurable with respect to VLAN awareness, thus any DPAA2 +switch port should be used only in usecases with a VLAN aware bridge:: + + $ ip link add dev br0 type bridge vlan_filtering 1 + + $ ip link add dev br1 type bridge + $ ip link set dev ethX master br1 + Error: fsl_dpaa2_switch: Cannot join a VLAN-unaware bridge + +Topology and loop detection through STP is supported when ``stp_state 1`` is +used at bridge create :: + + $ ip link add dev br0 type bridge vlan_filtering 1 stp_state 1 + +L2 FDB manipulation (add/delete/dump) is supported. + +HW FDB learning can be configured on each switch port independently through +bridge commands. When the HW learning is disabled, a fast age procedure will be +run and any previously learnt addresses will be removed. +:: + + $ bridge link set dev ethX learning off + $ bridge link set dev ethX learning on + +Restricting the unknown unicast and multicast flooding domain is supported, but +not independently of each other:: + + $ ip link set dev ethX type bridge_slave flood off mcast_flood off + $ ip link set dev ethX type bridge_slave flood off mcast_flood on + Error: fsl_dpaa2_switch: Cannot configure multicast flooding independently of unicast. + +Broadcast flooding on a switch port can be disabled/enabled through the brport sysfs:: + + $ echo 0 > /sys/bus/fsl-mc/devices/dpsw.Y/net/ethX/brport/broadcast_flood + +Offloads +======== + +Routing actions (redirect, trap, drop) +-------------------------------------- + +The DPAA2 switch is able to offload flow-based redirection of packets making +use of ACL tables. Shared filter blocks are supported by sharing a single ACL +table between multiple ports. + +The following flow keys are supported: + + * Ethernet: dst_mac/src_mac + * IPv4: dst_ip/src_ip/ip_proto/tos + * VLAN: vlan_id/vlan_prio/vlan_tpid/vlan_dei + * L4: dst_port/src_port + +Also, the matchall filter can be used to redirect the entire traffic received +on a port. + +As per flow actions, the following are supported: + + * drop + * mirred egress redirect + * trap + +Each ACL entry (filter) can be setup with only one of the listed +actions. + +Example 1: send frames received on eth4 with a SA of 00:01:02:03:04:05 to the +CPU:: + + $ tc qdisc add dev eth4 clsact + $ tc filter add dev eth4 ingress flower src_mac 00:01:02:03:04:05 skip_sw action trap + +Example 2: drop frames received on eth4 with VID 100 and PCP of 3:: + + $ tc filter add dev eth4 ingress protocol 802.1q flower skip_sw vlan_id 100 vlan_prio 3 action drop + +Example 3: redirect all frames received on eth4 to eth1:: + + $ tc filter add dev eth4 ingress matchall action mirred egress redirect dev eth1 + +Example 4: Use a single shared filter block on both eth5 and eth6:: + + $ tc qdisc add dev eth5 ingress_block 1 clsact + $ tc qdisc add dev eth6 ingress_block 1 clsact + $ tc filter add block 1 ingress flower dst_mac 00:01:02:03:04:04 skip_sw \ + action trap + $ tc filter add block 1 ingress protocol ipv4 flower src_ip 192.168.1.1 skip_sw \ + action mirred egress redirect dev eth3 + +Mirroring +~~~~~~~~~ + +The DPAA2 switch supports only per port mirroring and per VLAN mirroring. +Adding mirroring filters in shared blocks is also supported. + +When using the tc-flower classifier with the 802.1q protocol, only the +''vlan_id'' key will be accepted. Mirroring based on any other fields from the +802.1q protocol will be rejected:: + + $ tc qdisc add dev eth8 ingress_block 1 clsact + $ tc filter add block 1 ingress protocol 802.1q flower skip_sw vlan_prio 3 action mirred egress mirror dev eth6 + Error: fsl_dpaa2_switch: Only matching on VLAN ID supported. + We have an error talking to the kernel + +If a mirroring VLAN filter is requested on a port, the VLAN must to be +installed on the switch port in question either using ''bridge'' or by creating +a VLAN upper device if the switch port is used as a standalone interface:: + + $ tc qdisc add dev eth8 ingress_block 1 clsact + $ tc filter add block 1 ingress protocol 802.1q flower skip_sw vlan_id 200 action mirred egress mirror dev eth6 + Error: VLAN must be installed on the switch port. + We have an error talking to the kernel + + $ bridge vlan add vid 200 dev eth8 + $ tc filter add block 1 ingress protocol 802.1q flower skip_sw vlan_id 200 action mirred egress mirror dev eth6 + + $ ip link add link eth8 name eth8.200 type vlan id 200 + $ tc filter add block 1 ingress protocol 802.1q flower skip_sw vlan_id 200 action mirred egress mirror dev eth6 + +Also, it should be noted that the mirrored traffic will be subject to the same +egress restrictions as any other traffic. This means that when a mirrored +packet will reach the mirror port, if the VLAN found in the packet is not +installed on the port it will get dropped. + +The DPAA2 switch supports only a single mirroring destination, thus multiple +mirror rules can be installed but their ''to'' port has to be the same:: + + $ tc filter add block 1 ingress protocol 802.1q flower skip_sw vlan_id 200 action mirred egress mirror dev eth6 + $ tc filter add block 1 ingress protocol 802.1q flower skip_sw vlan_id 100 action mirred egress mirror dev eth7 + Error: fsl_dpaa2_switch: Multiple mirror ports not supported. + We have an error talking to the kernel diff --git a/Documentation/networking/device_drivers/ethernet/mellanox/mlx5.rst b/Documentation/networking/device_drivers/ethernet/mellanox/mlx5.rst index ef8cb62e82a1..4b59cf2c599f 100644 --- a/Documentation/networking/device_drivers/ethernet/mellanox/mlx5.rst +++ b/Documentation/networking/device_drivers/ethernet/mellanox/mlx5.rst @@ -656,3 +656,47 @@ Bridge offloads tracepoints: $ cat /sys/kernel/debug/tracing/trace ... ip-5387 [000] ...1 573713: mlx5_esw_bridge_vport_cleanup: vport_num=1 + +Eswitch QoS tracepoints: + +- mlx5_esw_vport_qos_create: trace creation of transmit scheduler arbiter for vport:: + + $ echo mlx5:mlx5_esw_vport_qos_create >> /sys/kernel/debug/tracing/set_event + $ cat /sys/kernel/debug/tracing/trace + ... + <...>-23496 [018] .... 73136.838831: mlx5_esw_vport_qos_create: (0000:82:00.0) vport=2 tsar_ix=4 bw_share=0, max_rate=0 group=000000007b576bb3 + +- mlx5_esw_vport_qos_config: trace configuration of transmit scheduler arbiter for vport:: + + $ echo mlx5:mlx5_esw_vport_qos_config >> /sys/kernel/debug/tracing/set_event + $ cat /sys/kernel/debug/tracing/trace + ... + <...>-26548 [023] .... 75754.223823: mlx5_esw_vport_qos_config: (0000:82:00.0) vport=1 tsar_ix=3 bw_share=34, max_rate=10000 group=000000007b576bb3 + +- mlx5_esw_vport_qos_destroy: trace deletion of transmit scheduler arbiter for vport:: + + $ echo mlx5:mlx5_esw_vport_qos_destroy >> /sys/kernel/debug/tracing/set_event + $ cat /sys/kernel/debug/tracing/trace + ... + <...>-27418 [004] .... 76546.680901: mlx5_esw_vport_qos_destroy: (0000:82:00.0) vport=1 tsar_ix=3 + +- mlx5_esw_group_qos_create: trace creation of transmit scheduler arbiter for rate group:: + + $ echo mlx5:mlx5_esw_group_qos_create >> /sys/kernel/debug/tracing/set_event + $ cat /sys/kernel/debug/tracing/trace + ... + <...>-26578 [008] .... 75776.022112: mlx5_esw_group_qos_create: (0000:82:00.0) group=000000008dac63ea tsar_ix=5 + +- mlx5_esw_group_qos_config: trace configuration of transmit scheduler arbiter for rate group:: + + $ echo mlx5:mlx5_esw_group_qos_config >> /sys/kernel/debug/tracing/set_event + $ cat /sys/kernel/debug/tracing/trace + ... + <...>-27303 [020] .... 76461.455356: mlx5_esw_group_qos_config: (0000:82:00.0) group=000000008dac63ea tsar_ix=5 bw_share=100 max_rate=20000 + +- mlx5_esw_group_qos_destroy: trace deletion of transmit scheduler arbiter for group:: + + $ echo mlx5:mlx5_esw_group_qos_destroy >> /sys/kernel/debug/tracing/set_event + $ cat /sys/kernel/debug/tracing/trace + ... + <...>-27418 [006] .... 76547.187258: mlx5_esw_group_qos_destroy: (0000:82:00.0) group=000000007b576bb3 tsar_ix=1 diff --git a/Documentation/networking/devlink/devlink-params.rst b/Documentation/networking/devlink/devlink-params.rst index 54c9f107c4b0..4878907e9232 100644 --- a/Documentation/networking/devlink/devlink-params.rst +++ b/Documentation/networking/devlink/devlink-params.rst @@ -97,6 +97,18 @@ own name. * - ``enable_roce`` - Boolean - Enable handling of RoCE traffic in the device. + * - ``enable_eth`` + - Boolean + - When enabled, the device driver will instantiate Ethernet specific + auxiliary device of the devlink device. + * - ``enable_rdma`` + - Boolean + - When enabled, the device driver will instantiate RDMA specific + auxiliary device of the devlink device. + * - ``enable_vnet`` + - Boolean + - When enabled, the device driver will instantiate VDPA networking + specific auxiliary device of the devlink device. * - ``internal_err_reset`` - Boolean - When enabled, the device driver will reset the device on internal diff --git a/Documentation/networking/devlink/hns3.rst b/Documentation/networking/devlink/hns3.rst new file mode 100644 index 000000000000..4562a6e4782f --- /dev/null +++ b/Documentation/networking/devlink/hns3.rst @@ -0,0 +1,25 @@ +.. SPDX-License-Identifier: GPL-2.0 + +==================== +hns3 devlink support +==================== + +This document describes the devlink features implemented by the ``hns3`` +device driver. + +The ``hns3`` driver supports reloading via ``DEVLINK_CMD_RELOAD``. + +Info versions +============= + +The ``hns3`` driver reports the following versions + +.. list-table:: devlink info versions implemented + :widths: 10 10 80 + + * - Name + - Type + - Description + * - ``fw`` + - running + - Used to represent the firmware version. diff --git a/Documentation/networking/devlink/index.rst b/Documentation/networking/devlink/index.rst index b3b9e0692088..45b5f8b341df 100644 --- a/Documentation/networking/devlink/index.rst +++ b/Documentation/networking/devlink/index.rst @@ -34,6 +34,7 @@ parameters, info versions, and other features it supports. :maxdepth: 1 bnxt + hns3 ionic ice mlx4 @@ -42,7 +43,6 @@ parameters, info versions, and other features it supports. mv88e6xxx netdevsim nfp - sja1105 qed ti-cpsw-switch am65-nuss-cpsw-switch diff --git a/Documentation/networking/devlink/sja1105.rst b/Documentation/networking/devlink/sja1105.rst deleted file mode 100644 index e2679c274085..000000000000 --- a/Documentation/networking/devlink/sja1105.rst +++ /dev/null @@ -1,49 +0,0 @@ -.. SPDX-License-Identifier: GPL-2.0 - -======================= -sja1105 devlink support -======================= - -This document describes the devlink features implemented -by the ``sja1105`` device driver. - -Parameters -========== - -.. list-table:: Driver-specific parameters implemented - :widths: 5 5 5 85 - - * - Name - - Type - - Mode - - Description - * - ``best_effort_vlan_filtering`` - - Boolean - - runtime - - Allow plain ETH_P_8021Q headers to be used as DSA tags. - - Benefits: - - - Can terminate untagged traffic over switch net - devices even when enslaved to a bridge with - vlan_filtering=1. - - Can terminate VLAN-tagged traffic over switch net - devices even when enslaved to a bridge with - vlan_filtering=1, with some constraints (no more than - 7 non-pvid VLANs per user port). - - Can do QoS based on VLAN PCP and VLAN membership - admission control for autonomously forwarded frames - (regardless of whether they can be terminated on the - CPU or not). - - Drawbacks: - - - User cannot use VLANs in range 1024-3071. If the - switch receives frames with such VIDs, it will - misinterpret them as DSA tags. - - Switch uses Shared VLAN Learning (FDB lookup uses - only DMAC as key). - - When VLANs span cross-chip topologies, the total - number of permitted VLANs may be less than 7 per - port, due to a maximum number of 32 VLAN retagging - rules per switch. diff --git a/Documentation/networking/dsa/dsa.rst b/Documentation/networking/dsa/dsa.rst index 20baacf2bc5c..89bb4fa4c362 100644 --- a/Documentation/networking/dsa/dsa.rst +++ b/Documentation/networking/dsa/dsa.rst @@ -200,19 +200,6 @@ receive all frames regardless of the value of the MAC DA. This can be done by setting the ``promisc_on_master`` property of the ``struct dsa_device_ops``. Note that this assumes a DSA-unaware master driver, which is the norm. -Hardware manufacturers are strongly discouraged to do this, but some tagging -protocols might not provide source port information on RX for all packets, but -e.g. only for control traffic (link-local PDUs). In this case, by implementing -the ``filter`` method of ``struct dsa_device_ops``, the tagger might select -which packets are to be redirected on RX towards the virtual DSA user network -interfaces, and which are to be left in the DSA master's RX data path. - -It might also happen (although silicon vendors are strongly discouraged to -produce hardware like this) that a tagging protocol splits the switch-specific -information into a header portion and a tail portion, therefore not falling -cleanly into any of the above 3 categories. DSA does not support this -configuration. - Master network devices ---------------------- @@ -663,6 +650,22 @@ Bridge layer CPU port, and flooding towards the CPU port should also be enabled, due to a lack of an explicit address filtering mechanism in the DSA core. +- ``port_bridge_tx_fwd_offload``: bridge layer function invoked after + ``port_bridge_join`` when a driver sets ``ds->num_fwd_offloading_bridges`` to + a non-zero value. Returning success in this function activates the TX + forwarding offload bridge feature for this port, which enables the tagging + protocol driver to inject data plane packets towards the bridging domain that + the port is a part of. Data plane packets are subject to FDB lookup, hardware + learning on the CPU port, and do not override the port STP state. + Additionally, replication of data plane packets (multicast, flooding) is + handled in hardware and the bridge driver will transmit a single skb for each + packet that needs replication. The method is provided as a configuration + point for drivers that need to configure the hardware for enabling this + feature. + +- ``port_bridge_tx_fwd_unoffload``: bridge layer function invoken when a driver + leaves a bridge port which had the TX forwarding offload feature enabled. + Bridge VLAN filtering --------------------- diff --git a/Documentation/networking/dsa/sja1105.rst b/Documentation/networking/dsa/sja1105.rst index da4057ba37f1..564caeebe2b2 100644 --- a/Documentation/networking/dsa/sja1105.rst +++ b/Documentation/networking/dsa/sja1105.rst @@ -65,199 +65,6 @@ If that changed setting can be transmitted to the switch through the dynamic reconfiguration interface, it is; otherwise the switch is reset and reprogrammed with the updated static configuration. -Traffic support -=============== - -The switches do not have hardware support for DSA tags, except for "slow -protocols" for switch control as STP and PTP. For these, the switches have two -programmable filters for link-local destination MACs. -These are used to trap BPDUs and PTP traffic to the master netdevice, and are -further used to support STP and 1588 ordinary clock/boundary clock -functionality. For frames trapped to the CPU, source port and switch ID -information is encoded by the hardware into the frames. - -But by leveraging ``CONFIG_NET_DSA_TAG_8021Q`` (a software-defined DSA tagging -format based on VLANs), general-purpose traffic termination through the network -stack can be supported under certain circumstances. - -Depending on VLAN awareness state, the following operating modes are possible -with the switch: - -- Mode 1 (VLAN-unaware): a port is in this mode when it is used as a standalone - net device, or when it is enslaved to a bridge with ``vlan_filtering=0``. -- Mode 2 (fully VLAN-aware): a port is in this mode when it is enslaved to a - bridge with ``vlan_filtering=1``. Access to the entire VLAN range is given to - the user through ``bridge vlan`` commands, but general-purpose (anything - other than STP, PTP etc) traffic termination is not possible through the - switch net devices. The other packets can be still by user space processed - through the DSA master interface (similar to ``DSA_TAG_PROTO_NONE``). -- Mode 3 (best-effort VLAN-aware): a port is in this mode when enslaved to a - bridge with ``vlan_filtering=1``, and the devlink property of its parent - switch named ``best_effort_vlan_filtering`` is set to ``true``. When - configured like this, the range of usable VIDs is reduced (0 to 1023 and 3072 - to 4094), so is the number of usable VIDs (maximum of 7 non-pvid VLANs per - port*), and shared VLAN learning is performed (FDB lookup is done only by - DMAC, not also by VID). - -To summarize, in each mode, the following types of traffic are supported over -the switch net devices: - -+-------------+-----------+--------------+------------+ -| | Mode 1 | Mode 2 | Mode 3 | -+=============+===========+==============+============+ -| Regular | Yes | No | Yes | -| traffic | | (use master) | | -+-------------+-----------+--------------+------------+ -| Management | Yes | Yes | Yes | -| traffic | | | | -| (BPDU, PTP) | | | | -+-------------+-----------+--------------+------------+ - -To configure the switch to operate in Mode 3, the following steps can be -followed:: - - ip link add dev br0 type bridge - # swp2 operates in Mode 1 now - ip link set dev swp2 master br0 - # swp2 temporarily moves to Mode 2 - ip link set dev br0 type bridge vlan_filtering 1 - [ 61.204770] sja1105 spi0.1: Reset switch and programmed static config. Reason: VLAN filtering - [ 61.239944] sja1105 spi0.1: Disabled switch tagging - # swp3 now operates in Mode 3 - devlink dev param set spi/spi0.1 name best_effort_vlan_filtering value true cmode runtime - [ 64.682927] sja1105 spi0.1: Reset switch and programmed static config. Reason: VLAN filtering - [ 64.711925] sja1105 spi0.1: Enabled switch tagging - # Cannot use VLANs in range 1024-3071 while in Mode 3. - bridge vlan add dev swp2 vid 1025 untagged pvid - RTNETLINK answers: Operation not permitted - bridge vlan add dev swp2 vid 100 - bridge vlan add dev swp2 vid 101 untagged - bridge vlan - port vlan ids - swp5 1 PVID Egress Untagged - - swp2 1 PVID Egress Untagged - 100 - 101 Egress Untagged - - swp3 1 PVID Egress Untagged - - swp4 1 PVID Egress Untagged - - br0 1 PVID Egress Untagged - bridge vlan add dev swp2 vid 102 - bridge vlan add dev swp2 vid 103 - bridge vlan add dev swp2 vid 104 - bridge vlan add dev swp2 vid 105 - bridge vlan add dev swp2 vid 106 - bridge vlan add dev swp2 vid 107 - # Cannot use mode than 7 VLANs per port while in Mode 3. - [ 3885.216832] sja1105 spi0.1: No more free subvlans - -\* "maximum of 7 non-pvid VLANs per port": Decoding VLAN-tagged packets on the -CPU in mode 3 is possible through VLAN retagging of packets that go from the -switch to the CPU. In cross-chip topologies, the port that goes to the CPU -might also go to other switches. In that case, those other switches will see -only a retagged packet (which only has meaning for the CPU). So if they are -interested in this VLAN, they need to apply retagging in the reverse direction, -to recover the original value from it. This consumes extra hardware resources -for this switch. There is a maximum of 32 entries in the Retagging Table of -each switch device. - -As an example, consider this cross-chip topology:: - - +-------------------------------------------------+ - | Host SoC | - | +-------------------------+ | - | | DSA master for embedded | | - | | switch (non-sja1105) | | - | +--------+-------------------------+--------+ | - | | embedded L2 switch | | - | | | | - | | +--------------+ +--------------+ | | - | | |DSA master for| |DSA master for| | | - | | | SJA1105 1 | | SJA1105 2 | | | - +--+---+--------------+-----+--------------+---+--+ - - +-----------------------+ +-----------------------+ - | SJA1105 switch 1 | | SJA1105 switch 2 | - +-----+-----+-----+-----+ +-----+-----+-----+-----+ - |sw1p0|sw1p1|sw1p2|sw1p3| |sw2p0|sw2p1|sw2p2|sw2p3| - +-----+-----+-----+-----+ +-----+-----+-----+-----+ - -To reach the CPU, SJA1105 switch 1 (spi/spi2.1) uses the same port as is uses -to reach SJA1105 switch 2 (spi/spi2.2), which would be port 4 (not drawn). -Similarly for SJA1105 switch 2. - -Also consider the following commands, that add VLAN 100 to every sja1105 user -port:: - - devlink dev param set spi/spi2.1 name best_effort_vlan_filtering value true cmode runtime - devlink dev param set spi/spi2.2 name best_effort_vlan_filtering value true cmode runtime - ip link add dev br0 type bridge - for port in sw1p0 sw1p1 sw1p2 sw1p3 \ - sw2p0 sw2p1 sw2p2 sw2p3; do - ip link set dev $port master br0 - done - ip link set dev br0 type bridge vlan_filtering 1 - for port in sw1p0 sw1p1 sw1p2 sw1p3 \ - sw2p0 sw2p1 sw2p2; do - bridge vlan add dev $port vid 100 - done - ip link add link br0 name br0.100 type vlan id 100 && ip link set dev br0.100 up - ip addr add 192.168.100.3/24 dev br0.100 - bridge vlan add dev br0 vid 100 self - - bridge vlan - port vlan ids - sw1p0 1 PVID Egress Untagged - 100 - - sw1p1 1 PVID Egress Untagged - 100 - - sw1p2 1 PVID Egress Untagged - 100 - - sw1p3 1 PVID Egress Untagged - 100 - - sw2p0 1 PVID Egress Untagged - 100 - - sw2p1 1 PVID Egress Untagged - 100 - - sw2p2 1 PVID Egress Untagged - 100 - - sw2p3 1 PVID Egress Untagged - - br0 1 PVID Egress Untagged - 100 - -SJA1105 switch 1 consumes 1 retagging entry for each VLAN on each user port -towards the CPU. It also consumes 1 retagging entry for each non-pvid VLAN that -it is also interested in, which is configured on any port of any neighbor -switch. - -In this case, SJA1105 switch 1 consumes a total of 11 retagging entries, as -follows: - -- 8 retagging entries for VLANs 1 and 100 installed on its user ports - (``sw1p0`` - ``sw1p3``) -- 3 retagging entries for VLAN 100 installed on the user ports of SJA1105 - switch 2 (``sw2p0`` - ``sw2p2``), because it also has ports that are - interested in it. The VLAN 1 is a pvid on SJA1105 switch 2 and does not need - reverse retagging. - -SJA1105 switch 2 also consumes 11 retagging entries, but organized as follows: - -- 7 retagging entries for the bridge VLANs on its user ports (``sw2p0`` - - ``sw2p3``). -- 4 retagging entries for VLAN 100 installed on the user ports of SJA1105 - switch 1 (``sw1p0`` - ``sw1p3``). - Switching features ================== @@ -282,33 +89,10 @@ untagged), and therefore this mode is also supported. Segregating the switch ports in multiple bridges is supported (e.g. 2 + 2), but all bridges should have the same level of VLAN awareness (either both have -``vlan_filtering`` 0, or both 1). Also an inevitable limitation of the fact -that VLAN awareness is global at the switch level is that once a bridge with -``vlan_filtering`` enslaves at least one switch port, the other un-bridged -ports are no longer available for standalone traffic termination. +``vlan_filtering`` 0, or both 1). Topology and loop detection through STP is supported. -L2 FDB manipulation (add/delete/dump) is currently possible for the first -generation devices. Aging time of FDB entries, as well as enabling fully static -management (no address learning and no flooding of unknown traffic) is not yet -configurable in the driver. - -A special comment about bridging with other netdevices (illustrated with an -example): - -A board has eth0, eth1, swp0@eth1, swp1@eth1, swp2@eth1, swp3@eth1. -The switch ports (swp0-3) are under br0. -It is desired that eth0 is turned into another switched port that communicates -with swp0-3. - -If br0 has vlan_filtering 0, then eth0 can simply be added to br0 with the -intended results. -If br0 has vlan_filtering 1, then a new br1 interface needs to be created that -enslaves eth0 and eth1 (the DSA master of the switch ports). This is because in -this mode, the switch ports beneath br0 are not capable of regular traffic, and -are only used as a conduit for switchdev operations. - Offloads ======== diff --git a/Documentation/networking/ethtool-netlink.rst b/Documentation/networking/ethtool-netlink.rst index c86628e6a235..d9b55b7a1a4d 100644 --- a/Documentation/networking/ethtool-netlink.rst +++ b/Documentation/networking/ethtool-netlink.rst @@ -595,6 +595,14 @@ Link extended substates: that is not formally supported, which led to signal integrity issues + + ``ETHTOOL_LINK_EXT_SUBSTATE_BSI_SERDES_REFERENCE_CLOCK_LOST`` The external clock signal for + SerDes is too weak or + unavailable. + + ``ETHTOOL_LINK_EXT_SUBSTATE_BSI_SERDES_ALOS`` The received signal for + SerDes is too weak because + analog loss of signal. ================================================================= ============================= Cable issue substates: @@ -939,12 +947,25 @@ Kernel response contents: ``ETHTOOL_A_COALESCE_TX_USECS_HIGH`` u32 delay (us), high Tx ``ETHTOOL_A_COALESCE_TX_MAX_FRAMES_HIGH`` u32 max packets, high Tx ``ETHTOOL_A_COALESCE_RATE_SAMPLE_INTERVAL`` u32 rate sampling interval + ``ETHTOOL_A_COALESCE_USE_CQE_TX`` bool timer reset mode, Tx + ``ETHTOOL_A_COALESCE_USE_CQE_RX`` bool timer reset mode, Rx =========================================== ====== ======================= Attributes are only included in reply if their value is not zero or the corresponding bit in ``ethtool_ops::supported_coalesce_params`` is set (i.e. they are declared as supported by driver). +Timer reset mode (``ETHTOOL_A_COALESCE_USE_CQE_TX`` and +``ETHTOOL_A_COALESCE_USE_CQE_RX``) controls the interaction between packet +arrival and the various time based delay parameters. By default timers are +expected to limit the max delay between any packet arrival/departure and a +corresponding interrupt. In this mode timer should be started by packet +arrival (sometimes delivery of previous interrupt) and reset when interrupt +is delivered. +Setting the appropriate attribute to 1 will enable ``CQE`` mode, where +each packet event resets the timer. In this mode timer is used to force +the interrupt if queue goes idle, while busy queues depend on the packet +limit to trigger interrupts. COALESCE_SET ============ @@ -977,6 +998,8 @@ Request contents: ``ETHTOOL_A_COALESCE_TX_USECS_HIGH`` u32 delay (us), high Tx ``ETHTOOL_A_COALESCE_TX_MAX_FRAMES_HIGH`` u32 max packets, high Tx ``ETHTOOL_A_COALESCE_RATE_SAMPLE_INTERVAL`` u32 rate sampling interval + ``ETHTOOL_A_COALESCE_USE_CQE_TX`` bool timer reset mode, Tx + ``ETHTOOL_A_COALESCE_USE_CQE_RX`` bool timer reset mode, Rx =========================================== ====== ======================= Request is rejected if it attributes declared as unsupported by driver (i.e. diff --git a/Documentation/networking/filter.rst b/Documentation/networking/filter.rst index 3e2221f4abe4..ce2b8e8bb9ab 100644 --- a/Documentation/networking/filter.rst +++ b/Documentation/networking/filter.rst @@ -320,13 +320,6 @@ Examples for low-level BPF: ret #-1 drop: ret #0 -**(Accelerated) VLAN w/ id 10**:: - - ld vlan_tci - jneq #10, drop - ret #-1 - drop: ret #0 - **icmp random packet sampling, 1 in 4**:: ldh [12] @@ -358,6 +351,22 @@ Examples for low-level BPF: bad: ret #0 /* SECCOMP_RET_KILL_THREAD */ good: ret #0x7fff0000 /* SECCOMP_RET_ALLOW */ +Examples for low-level BPF extension: + +**Packet for interface index 13**:: + + ld ifidx + jneq #13, drop + ret #-1 + drop: ret #0 + +**(Accelerated) VLAN w/ id 10**:: + + ld vlan_tci + jneq #10, drop + ret #-1 + drop: ret #0 + The above example code can be placed into a file (here called "foo"), and then be passed to the bpf_asm tool for generating opcodes, output that xt_bpf and cls_bpf understands and can directly be loaded with. Example with above @@ -629,8 +638,8 @@ extension, PTP dissector/classifier, and much more. They are all internally converted by the kernel into the new instruction set representation and run in the eBPF interpreter. For in-kernel handlers, this all works transparently by using bpf_prog_create() for setting up the filter, resp. -bpf_prog_destroy() for destroying it. The macro -BPF_PROG_RUN(filter, ctx) transparently invokes eBPF interpreter or JITed +bpf_prog_destroy() for destroying it. The function +bpf_prog_run(filter, ctx) transparently invokes eBPF interpreter or JITed code to run the filter. 'filter' is a pointer to struct bpf_prog that we got from bpf_prog_create(), and 'ctx' the given context (e.g. skb pointer). All constraints and restrictions from bpf_check_classic() apply diff --git a/Documentation/networking/index.rst b/Documentation/networking/index.rst index e9ce55992aa9..58bc8cd367c6 100644 --- a/Documentation/networking/index.rst +++ b/Documentation/networking/index.rst @@ -57,6 +57,7 @@ Contents: gen_stats gtp ila + ioam6-sysctl ipddp ip_dynaddr ipsec @@ -68,6 +69,7 @@ Contents: l2tp lapb-module mac80211-injection + mctp mpls-sysctl mptcp-sysctl multiqueue diff --git a/Documentation/networking/ioam6-sysctl.rst b/Documentation/networking/ioam6-sysctl.rst new file mode 100644 index 000000000000..c18cab2c481a --- /dev/null +++ b/Documentation/networking/ioam6-sysctl.rst @@ -0,0 +1,26 @@ +.. SPDX-License-Identifier: GPL-2.0 + +===================== +IOAM6 Sysfs variables +===================== + + +/proc/sys/net/conf/<iface>/ioam6_* variables: +============================================= + +ioam6_enabled - BOOL + Accept (= enabled) or ignore (= disabled) IPv6 IOAM options on ingress + for this interface. + + * 0 - disabled (default) + * 1 - enabled + +ioam6_id - SHORT INTEGER + Define the IOAM id of this interface. + + Default is ~0. + +ioam6_id_wide - INTEGER + Define the wide IOAM id of this interface. + + Default is ~0. diff --git a/Documentation/networking/ip-sysctl.rst b/Documentation/networking/ip-sysctl.rst index b3fa522e4cd9..d91ab28718d4 100644 --- a/Documentation/networking/ip-sysctl.rst +++ b/Documentation/networking/ip-sysctl.rst @@ -826,7 +826,7 @@ tcp_fastopen_blackhole_timeout_sec - INTEGER initial value when the blackhole issue goes away. 0 to disable the blackhole detection. - By default, it is set to 1hr. + By default, it is set to 0 (feature is disabled). tcp_fastopen_key - list of comma separated 32-digit hexadecimal INTEGERs The list consists of a primary key and an optional backup key. The @@ -1926,6 +1926,23 @@ fib_notify_on_flag_change - INTEGER - 1 - Emit notifications. - 2 - Emit notifications only for RTM_F_OFFLOAD_FAILED flag change. +ioam6_id - INTEGER + Define the IOAM id of this node. Uses only 24 bits out of 32 in total. + + Min: 0 + Max: 0xFFFFFF + + Default: 0xFFFFFF + +ioam6_id_wide - LONG INTEGER + Define the wide IOAM id of this node. Uses only 56 bits out of 64 in + total. Can be different from ioam6_id. + + Min: 0 + Max: 0xFFFFFFFFFFFFFF + + Default: 0xFFFFFFFFFFFFFF + IPv6 Fragmentation: ip6frag_high_thresh - INTEGER diff --git a/Documentation/networking/mctp.rst b/Documentation/networking/mctp.rst new file mode 100644 index 000000000000..6100cdc220f6 --- /dev/null +++ b/Documentation/networking/mctp.rst @@ -0,0 +1,213 @@ +.. SPDX-License-Identifier: GPL-2.0 + +============================================== +Management Component Transport Protocol (MCTP) +============================================== + +net/mctp/ contains protocol support for MCTP, as defined by DMTF standard +DSP0236. Physical interface drivers ("bindings" in the specification) are +provided in drivers/net/mctp/. + +The core code provides a socket-based interface to send and receive MCTP +messages, through an AF_MCTP, SOCK_DGRAM socket. + +Structure: interfaces & networks +================================ + +The kernel models the local MCTP topology through two items: interfaces and +networks. + +An interface (or "link") is an instance of an MCTP physical transport binding +(as defined by DSP0236, section 3.2.47), likely connected to a specific hardware +device. This is represented as a ``struct netdevice``. + +A network defines a unique address space for MCTP endpoints by endpoint-ID +(described by DSP0236, section 3.2.31). A network has a user-visible identifier +to allow references from userspace. Route definitions are specific to one +network. + +Interfaces are associated with one network. A network may be associated with one +or more interfaces. + +If multiple networks are present, each may contain endpoint IDs (EIDs) that are +also present on other networks. + +Sockets API +=========== + +Protocol definitions +-------------------- + +MCTP uses ``AF_MCTP`` / ``PF_MCTP`` for the address- and protocol- families. +Since MCTP is message-based, only ``SOCK_DGRAM`` sockets are supported. + +.. code-block:: C + + int sd = socket(AF_MCTP, SOCK_DGRAM, 0); + +The only (current) value for the ``protocol`` argument is 0. + +As with all socket address families, source and destination addresses are +specified with a ``sockaddr`` type, with a single-byte endpoint address: + +.. code-block:: C + + typedef __u8 mctp_eid_t; + + struct mctp_addr { + mctp_eid_t s_addr; + }; + + struct sockaddr_mctp { + unsigned short int smctp_family; + int smctp_network; + struct mctp_addr smctp_addr; + __u8 smctp_type; + __u8 smctp_tag; + }; + + #define MCTP_NET_ANY 0x0 + #define MCTP_ADDR_ANY 0xff + + +Syscall behaviour +----------------- + +The following sections describe the MCTP-specific behaviours of the standard +socket system calls. These behaviours have been chosen to map closely to the +existing sockets APIs. + +``bind()`` : set local socket address +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Sockets that receive incoming request packets will bind to a local address, +using the ``bind()`` syscall. + +.. code-block:: C + + struct sockaddr_mctp addr; + + addr.smctp_family = AF_MCTP; + addr.smctp_network = MCTP_NET_ANY; + addr.smctp_addr.s_addr = MCTP_ADDR_ANY; + addr.smctp_type = MCTP_TYPE_PLDM; + addr.smctp_tag = MCTP_TAG_OWNER; + + int rc = bind(sd, (struct sockaddr *)&addr, sizeof(addr)); + +This establishes the local address of the socket. Incoming MCTP messages that +match the network, address, and message type will be received by this socket. +The reference to 'incoming' is important here; a bound socket will only receive +messages with the TO bit set, to indicate an incoming request message, rather +than a response. + +The ``smctp_tag`` value will configure the tags accepted from the remote side of +this socket. Given the above, the only valid value is ``MCTP_TAG_OWNER``, which +will result in remotely "owned" tags being routed to this socket. Since +``MCTP_TAG_OWNER`` is set, the 3 least-significant bits of ``smctp_tag`` are not +used; callers must set them to zero. + +A ``smctp_network`` value of ``MCTP_NET_ANY`` will configure the socket to +receive incoming packets from any locally-connected network. A specific network +value will cause the socket to only receive incoming messages from that network. + +The ``smctp_addr`` field specifies a local address to bind to. A value of +``MCTP_ADDR_ANY`` configures the socket to receive messages addressed to any +local destination EID. + +The ``smctp_type`` field specifies which message types to receive. Only the +lower 7 bits of the type is matched on incoming messages (ie., the +most-significant IC bit is not part of the match). This results in the socket +receiving packets with and without a message integrity check footer. + +``sendto()``, ``sendmsg()``, ``send()`` : transmit an MCTP message +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +An MCTP message is transmitted using one of the ``sendto()``, ``sendmsg()`` or +``send()`` syscalls. Using ``sendto()`` as the primary example: + +.. code-block:: C + + struct sockaddr_mctp addr; + char buf[14]; + ssize_t len; + + /* set message destination */ + addr.smctp_family = AF_MCTP; + addr.smctp_network = 0; + addr.smctp_addr.s_addr = 8; + addr.smctp_tag = MCTP_TAG_OWNER; + addr.smctp_type = MCTP_TYPE_ECHO; + + /* arbitrary message to send, with message-type header */ + buf[0] = MCTP_TYPE_ECHO; + memcpy(buf + 1, "hello, world!", sizeof(buf) - 1); + + len = sendto(sd, buf, sizeof(buf), 0, + (struct sockaddr_mctp *)&addr, sizeof(addr)); + +The network and address fields of ``addr`` define the remote address to send to. +If ``smctp_tag`` has the ``MCTP_TAG_OWNER``, the kernel will ignore any bits set +in ``MCTP_TAG_VALUE``, and generate a tag value suitable for the destination +EID. If ``MCTP_TAG_OWNER`` is not set, the message will be sent with the tag +value as specified. If a tag value cannot be allocated, the system call will +report an errno of ``EAGAIN``. + +The application must provide the message type byte as the first byte of the +message buffer passed to ``sendto()``. If a message integrity check is to be +included in the transmitted message, it must also be provided in the message +buffer, and the most-significant bit of the message type byte must be 1. + +The ``sendmsg()`` system call allows a more compact argument interface, and the +message buffer to be specified as a scatter-gather list. At present no ancillary +message types (used for the ``msg_control`` data passed to ``sendmsg()``) are +defined. + +Transmitting a message on an unconnected socket with ``MCTP_TAG_OWNER`` +specified will cause an allocation of a tag, if no valid tag is already +allocated for that destination. The (destination-eid,tag) tuple acts as an +implicit local socket address, to allow the socket to receive responses to this +outgoing message. If any previous allocation has been performed (to for a +different remote EID), that allocation is lost. + +Sockets will only receive responses to requests they have sent (with TO=1) and +may only respond (with TO=0) to requests they have received. + +``recvfrom()``, ``recvmsg()``, ``recv()`` : receive an MCTP message +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +An MCTP message can be received by an application using one of the +``recvfrom()``, ``recvmsg()``, or ``recv()`` system calls. Using ``recvfrom()`` +as the primary example: + +.. code-block:: C + + struct sockaddr_mctp addr; + socklen_t addrlen; + char buf[14]; + ssize_t len; + + addrlen = sizeof(addr); + + len = recvfrom(sd, buf, sizeof(buf), 0, + (struct sockaddr_mctp *)&addr, &addrlen); + + /* We can expect addr to describe an MCTP address */ + assert(addrlen >= sizeof(buf)); + assert(addr.smctp_family == AF_MCTP); + + printf("received %zd bytes from remote EID %d\n", rc, addr.smctp_addr); + +The address argument to ``recvfrom`` and ``recvmsg`` is populated with the +remote address of the incoming message, including tag value (this will be needed +in order to reply to the message). + +The first byte of the message buffer will contain the message type byte. If an +integrity check follows the message, it will be included in the received buffer. + +The ``recv()`` system call behaves in a similar way, but does not provide a +remote address to the application. Therefore, these are only useful if the +remote address is already known, or the message does not require a reply. + +Like the send calls, sockets will only receive responses to requests they have +sent (TO=1) and may only respond (TO=0) to requests they have received. diff --git a/Documentation/networking/mptcp-sysctl.rst b/Documentation/networking/mptcp-sysctl.rst index 76d939e688b8..b0d4da71e68e 100644 --- a/Documentation/networking/mptcp-sysctl.rst +++ b/Documentation/networking/mptcp-sysctl.rst @@ -45,3 +45,15 @@ allow_join_initial_addr_port - BOOLEAN This is a per-namespace sysctl. Default: 1 + +stale_loss_cnt - INTEGER + The number of MPTCP-level retransmission intervals with no traffic and + pending outstanding data on a given subflow required to declare it stale. + The packet scheduler ignores stale subflows. + A low stale_loss_cnt value allows for fast active-backup switch-over, + an high value maximize links utilization on edge scenarios e.g. lossy + link with high BER or peer pausing the data processing. + + This is a per-namespace sysctl. + + Default: 4 diff --git a/Documentation/networking/netdev-FAQ.rst b/Documentation/networking/netdev-FAQ.rst index 91b2cf712801..e26532f49760 100644 --- a/Documentation/networking/netdev-FAQ.rst +++ b/Documentation/networking/netdev-FAQ.rst @@ -228,6 +228,23 @@ before posting to the mailing list. The patchwork build bot instance gets overloaded very easily and netdev@vger really doesn't need more traffic if we can help it. +netdevsim is great, can I extend it for my out-of-tree tests? +------------------------------------------------------------- + +No, `netdevsim` is a test vehicle solely for upstream tests. +(Please add your tests under tools/testing/selftests/.) + +We also give no guarantees that `netdevsim` won't change in the future +in a way which would break what would normally be considered uAPI. + +Is netdevsim considered a "user" of an API? +------------------------------------------- + +Linux kernel has a long standing rule that no API should be added unless +it has a real, in-tree user. Mock-ups and tests based on `netdevsim` are +strongly encouraged when adding new APIs, but `netdevsim` in itself +is **not** considered a use case/user. + Any other tips to help ensure my net/net-next patch gets OK'd? -------------------------------------------------------------- Attention to detail. Re-read your own work as if you were the diff --git a/Documentation/networking/netdevices.rst b/Documentation/networking/netdevices.rst index 17bdcb746dcf..9e4cccb90b87 100644 --- a/Documentation/networking/netdevices.rst +++ b/Documentation/networking/netdevices.rst @@ -222,6 +222,35 @@ ndo_do_ioctl: Synchronization: rtnl_lock() semaphore. Context: process + This is only called by network subsystems internally, + not by user space calling ioctl as it was in before + linux-5.14. + +ndo_siocbond: + Synchronization: rtnl_lock() semaphore. + Context: process + + Used by the bonding driver for the SIOCBOND family of + ioctl commands. + +ndo_siocwandev: + Synchronization: rtnl_lock() semaphore. + Context: process + + Used by the drivers/net/wan framework to handle + the SIOCWANDEV ioctl with the if_settings structure. + +ndo_siocdevprivate: + Synchronization: rtnl_lock() semaphore. + Context: process + + This is used to implement SIOCDEVPRIVATE ioctl helpers. + These should not be added to new drivers, so don't use. + +ndo_eth_ioctl: + Synchronization: rtnl_lock() semaphore. + Context: process + ndo_get_stats: Synchronization: rtnl_lock() semaphore, dev_base_lock rwlock, or RCU. Context: atomic (can't sleep under rwlock or RCU) diff --git a/Documentation/networking/nf_conntrack-sysctl.rst b/Documentation/networking/nf_conntrack-sysctl.rst index d31ed6c1cb0d..34ca762ea56f 100644 --- a/Documentation/networking/nf_conntrack-sysctl.rst +++ b/Documentation/networking/nf_conntrack-sysctl.rst @@ -184,6 +184,13 @@ nf_conntrack_gre_timeout_stream - INTEGER (seconds) This extended timeout will be used in case there is an GRE stream detected. +nf_hooks_lwtunnel - BOOLEAN + - 0 - disabled (default) + - not 0 - enabled + + If this option is enabled, the lightweight tunnel netfilter hooks are + enabled. This option cannot be disabled once it is enabled. + nf_flowtable_tcp_timeout - INTEGER (seconds) default 30 @@ -191,19 +198,9 @@ nf_flowtable_tcp_timeout - INTEGER (seconds) TCP connections may be offloaded from nf conntrack to nf flow table. Once aged, the connection is returned to nf conntrack with tcp pickup timeout. -nf_flowtable_tcp_pickup - INTEGER (seconds) - default 120 - - TCP connection timeout after being aged from nf flow table offload. - nf_flowtable_udp_timeout - INTEGER (seconds) default 30 Control offload timeout for udp connections. UDP connections may be offloaded from nf conntrack to nf flow table. Once aged, the connection is returned to nf conntrack with udp pickup timeout. - -nf_flowtable_udp_pickup - INTEGER (seconds) - default 30 - - UDP connection timeout after being aged from nf flow table offload. diff --git a/Documentation/networking/operstates.rst b/Documentation/networking/operstates.rst index 9c918f7cb0e8..1ee2141e8ef1 100644 --- a/Documentation/networking/operstates.rst +++ b/Documentation/networking/operstates.rst @@ -73,7 +73,9 @@ IF_OPER_LOWERLAYERDOWN (3): state (f.e. VLAN). IF_OPER_TESTING (4): - Unused in current kernel. + Interface is in testing mode, for example executing driver self-tests + or media (cable) test. It can't be used for normal traffic until tests + complete. IF_OPER_DORMANT (5): Interface is L1 up, but waiting for an external event, f.e. for a @@ -111,7 +113,7 @@ it as lower layer. Note that for certain kind of soft-devices, which are not managing any real hardware, it is possible to set this bit from userspace. One -should use TVL IFLA_CARRIER to do so. +should use TLV IFLA_CARRIER to do so. netif_carrier_ok() can be used to query that bit. diff --git a/Documentation/networking/pktgen.rst b/Documentation/networking/pktgen.rst index 7afa1c9f1183..1225f0f63ff0 100644 --- a/Documentation/networking/pktgen.rst +++ b/Documentation/networking/pktgen.rst @@ -248,26 +248,24 @@ Usage::: -i : ($DEV) output interface/device (required) -s : ($PKT_SIZE) packet size - -d : ($DEST_IP) destination IP + -d : ($DEST_IP) destination IP. CIDR (e.g. 198.18.0.0/15) is also allowed -m : ($DST_MAC) destination MAC-addr + -p : ($DST_PORT) destination PORT range (e.g. 433-444) is also allowed -t : ($THREADS) threads to start + -f : ($F_THREAD) index of first thread (zero indexed CPU number) -c : ($SKB_CLONE) SKB clones send before alloc new SKB + -n : ($COUNT) num messages to send per thread, 0 means indefinitely -b : ($BURST) HW level bursting of SKBs -v : ($VERBOSE) verbose -x : ($DEBUG) debug + -6 : ($IP6) IPv6 + -w : ($DELAY) Tx Delay value (ns) + -a : ($APPEND) Script will not reset generator's state, but will append its config The global variables being set are also listed. E.g. the required interface/device parameter "-i" sets variable $DEV. Copy the pktgen_sampleXX scripts and modify them to fit your own needs. -The old scripts:: - - pktgen.conf-1-2 # 1 CPU 2 dev - pktgen.conf-1-1-rdos # 1 CPU 1 dev w. route DoS - pktgen.conf-1-1-ip6 # 1 CPU 1 dev ipv6 - pktgen.conf-1-1-ip6-rdos # 1 CPU 1 dev ipv6 w. route DoS - pktgen.conf-1-1-flows # 1 CPU 1 dev multiple flows. - Interrupt affinity =================== @@ -398,7 +396,7 @@ Current commands and configuration options References: - ftp://robur.slu.se/pub/Linux/net-development/pktgen-testing/ -- tp://robur.slu.se/pub/Linux/net-development/pktgen-testing/examples/ +- ftp://robur.slu.se/pub/Linux/net-development/pktgen-testing/examples/ Paper from Linux-Kongress in Erlangen 2004. - ftp://robur.slu.se/pub/Linux/net-development/pktgen-testing/pktgen_paper.pdf diff --git a/Documentation/networking/timestamping.rst b/Documentation/networking/timestamping.rst index 7db3985359bc..a722eb30e014 100644 --- a/Documentation/networking/timestamping.rst +++ b/Documentation/networking/timestamping.rst @@ -625,7 +625,7 @@ interfaces of a DSA switch to share the same PHC. By design, PTP timestamping with a DSA switch does not need any special handling in the driver for the host port it is attached to. However, when the host port also supports PTP timestamping, DSA will take care of intercepting -the ``.ndo_do_ioctl`` calls towards the host port, and block attempts to enable +the ``.ndo_eth_ioctl`` calls towards the host port, and block attempts to enable hardware timestamping on it. This is because the SO_TIMESTAMPING API does not allow the delivery of multiple hardware timestamps for the same packet, so anybody else except for the DSA switch port must be prevented from doing so. @@ -688,7 +688,7 @@ ethtool ioctl operations for them need to be mediated by their respective MAC driver. Therefore, as opposed to DSA switches, modifications need to be done to each individual MAC driver for PHY timestamping support. This entails: -- Checking, in ``.ndo_do_ioctl``, whether ``phy_has_hwtstamp(netdev->phydev)`` +- Checking, in ``.ndo_eth_ioctl``, whether ``phy_has_hwtstamp(netdev->phydev)`` is true or not. If it is, then the MAC driver should not process this request but instead pass it on to the PHY using ``phy_mii_ioctl()``. @@ -747,7 +747,7 @@ For example, a typical driver design for TX timestamping might be to split the transmission part into 2 portions: 1. "TX": checks whether PTP timestamping has been previously enabled through - the ``.ndo_do_ioctl`` ("``priv->hwtstamp_tx_enabled == true``") and the + the ``.ndo_eth_ioctl`` ("``priv->hwtstamp_tx_enabled == true``") and the current skb requires a TX timestamp ("``skb_shinfo(skb)->tx_flags & SKBTX_HW_TSTAMP``"). If this is true, it sets the "``skb_shinfo(skb)->tx_flags |= SKBTX_IN_PROGRESS``" flag. Note: as diff --git a/Documentation/networking/vrf.rst b/Documentation/networking/vrf.rst index 0dde145043bc..0a9a6f968cb9 100644 --- a/Documentation/networking/vrf.rst +++ b/Documentation/networking/vrf.rst @@ -144,6 +144,19 @@ default VRF are only handled by a socket not bound to any VRF:: netfilter rules on the VRF device can be used to limit access to services running in the default VRF context as well. +Using VRF-aware applications (applications which simultaneously create sockets +outside and inside VRFs) in conjunction with ``net.ipv4.tcp_l3mdev_accept=1`` +is possible but may lead to problems in some situations. With that sysctl +value, it is unspecified which listening socket will be selected to handle +connections for VRF traffic; ie. either a socket bound to the VRF or an unbound +socket may be used to accept new connections from a VRF. This somewhat +unexpected behavior can lead to problems if sockets are configured with extra +options (ex. TCP MD5 keys) with the expectation that VRF traffic will +exclusively be handled by sockets bound to VRFs, as would be the case with +``net.ipv4.tcp_l3mdev_accept=0``. Finally and as a reminder, regardless of +which listening socket is selected, established sockets will be created in the +VRF based on the ingress interface, as documented earlier. + -------------------------------------------------------------------------------- Using iproute2 for VRFs diff --git a/Documentation/powerpc/associativity.rst b/Documentation/powerpc/associativity.rst new file mode 100644 index 000000000000..4d01c7368561 --- /dev/null +++ b/Documentation/powerpc/associativity.rst @@ -0,0 +1,105 @@ +============================ +NUMA resource associativity +============================ + +Associativity represents the groupings of the various platform resources into +domains of substantially similar mean performance relative to resources outside +of that domain. Resources subsets of a given domain that exhibit better +performance relative to each other than relative to other resources subsets +are represented as being members of a sub-grouping domain. This performance +characteristic is presented in terms of NUMA node distance within the Linux kernel. +From the platform view, these groups are also referred to as domains. + +PAPR interface currently supports different ways of communicating these resource +grouping details to the OS. These are referred to as Form 0, Form 1 and Form2 +associativity grouping. Form 0 is the oldest format and is now considered deprecated. + +Hypervisor indicates the type/form of associativity used via "ibm,architecture-vec-5 property". +Bit 0 of byte 5 in the "ibm,architecture-vec-5" property indicates usage of Form 0 or Form 1. +A value of 1 indicates the usage of Form 1 associativity. For Form 2 associativity +bit 2 of byte 5 in the "ibm,architecture-vec-5" property is used. + +Form 0 +------ +Form 0 associativity supports only two NUMA distances (LOCAL and REMOTE). + +Form 1 +------ +With Form 1 a combination of ibm,associativity-reference-points, and ibm,associativity +device tree properties are used to determine the NUMA distance between resource groups/domains. + +The “ibm,associativity” property contains a list of one or more numbers (domainID) +representing the resource’s platform grouping domains. + +The “ibm,associativity-reference-points” property contains a list of one or more numbers +(domainID index) that represents the 1 based ordinal in the associativity lists. +The list of domainID indexes represents an increasing hierarchy of resource grouping. + +ex: +{ primary domainID index, secondary domainID index, tertiary domainID index.. } + +Linux kernel uses the domainID at the primary domainID index as the NUMA node id. +Linux kernel computes NUMA distance between two domains by recursively comparing +if they belong to the same higher-level domains. For mismatch at every higher +level of the resource group, the kernel doubles the NUMA distance between the +comparing domains. + +Form 2 +------- +Form 2 associativity format adds separate device tree properties representing NUMA node distance +thereby making the node distance computation flexible. Form 2 also allows flexible primary +domain numbering. With numa distance computation now detached from the index value in +"ibm,associativity-reference-points" property, Form 2 allows a large number of primary domain +ids at the same domainID index representing resource groups of different performance/latency +characteristics. + +Hypervisor indicates the usage of FORM2 associativity using bit 2 of byte 5 in the +"ibm,architecture-vec-5" property. + +"ibm,numa-lookup-index-table" property contains a list of one or more numbers representing +the domainIDs present in the system. The offset of the domainID in this property is +used as an index while computing numa distance information via "ibm,numa-distance-table". + +prop-encoded-array: The number N of the domainIDs encoded as with encode-int, followed by +N domainID encoded as with encode-int + +For ex: +"ibm,numa-lookup-index-table" = {4, 0, 8, 250, 252}. The offset of domainID 8 (2) is used when +computing the distance of domain 8 from other domains present in the system. For the rest of +this document, this offset will be referred to as domain distance offset. + +"ibm,numa-distance-table" property contains a list of one or more numbers representing the NUMA +distance between resource groups/domains present in the system. + +prop-encoded-array: The number N of the distance values encoded as with encode-int, followed by +N distance values encoded as with encode-bytes. The max distance value we could encode is 255. +The number N must be equal to the square of m where m is the number of domainIDs in the +numa-lookup-index-table. + +For ex: +ibm,numa-lookup-index-table = <3 0 8 40>; +ibm,numa-distace-table = <9>, /bits/ 8 < 10 20 80 20 10 160 80 160 10>; + +:: + + | 0 8 40 + --|------------ + | + 0 | 10 20 80 + | + 8 | 20 10 160 + | + 40| 80 160 10 + +A possible "ibm,associativity" property for resources in node 0, 8 and 40 + +{ 3, 6, 7, 0 } +{ 3, 6, 9, 8 } +{ 3, 6, 7, 40} + +With "ibm,associativity-reference-points" { 0x3 } + +"ibm,lookup-index-table" helps in having a compact representation of distance matrix. +Since domainID can be sparse, the matrix of distances can also be effectively sparse. +With "ibm,lookup-index-table" we can achieve a compact representation of +distance information. diff --git a/Documentation/powerpc/index.rst b/Documentation/powerpc/index.rst index bf5f1a2bdbdf..0f7d3c495693 100644 --- a/Documentation/powerpc/index.rst +++ b/Documentation/powerpc/index.rst @@ -7,6 +7,7 @@ powerpc .. toctree:: :maxdepth: 1 + associativity booting bootwrapper cpu_families diff --git a/Documentation/process/deprecated.rst b/Documentation/process/deprecated.rst index 9d83b8db8874..8ced754a5a0f 100644 --- a/Documentation/process/deprecated.rst +++ b/Documentation/process/deprecated.rst @@ -164,7 +164,9 @@ Paraphrasing Linus's current `guidance <https://lore.kernel.org/lkml/CA+55aFwQEd up to Linus's scrutiny, maybe you can use "%px", along with making sure you have sensible permissions. -And finally, know that a toggle for "%p" hashing will `not be accepted <https://lore.kernel.org/lkml/CA+55aFwieC1-nAs+NFq9RTwaR8ef9hWa4MjNBWL41F-8wM49eA@mail.gmail.com/>`_. +If you are debugging something where "%p" hashing is causing problems, +you can temporarily boot with the debug flag "`no_hash_pointers +<https://git.kernel.org/linus/5ead723a20e0447bc7db33dc3070b420e5f80aa6>`_". Variable Length Arrays (VLAs) ----------------------------- diff --git a/Documentation/process/submitting-patches.rst b/Documentation/process/submitting-patches.rst index 0852bcf73630..8ad6b93f91e6 100644 --- a/Documentation/process/submitting-patches.rst +++ b/Documentation/process/submitting-patches.rst @@ -216,11 +216,11 @@ cannot find a maintainer for the subsystem you are working on, Andrew Morton (akpm@linux-foundation.org) serves as a maintainer of last resort. You should also normally choose at least one mailing list to receive a copy -of your patch set. linux-kernel@vger.kernel.org functions as a list of -last resort, but the volume on that list has caused a number of developers -to tune it out. Look in the MAINTAINERS file for a subsystem-specific -list; your patch will probably get more attention there. Please do not -spam unrelated lists, though. +of your patch set. linux-kernel@vger.kernel.org should be used by default +for all patches, but the volume on that list has caused a number of +developers to tune it out. Look in the MAINTAINERS file for a +subsystem-specific list; your patch will probably get more attention there. +Please do not spam unrelated lists, though. Many kernel-related lists are hosted on vger.kernel.org; you can find a list of them at http://vger.kernel.org/vger-lists.html. There are diff --git a/Documentation/sound/alsa-configuration.rst b/Documentation/sound/alsa-configuration.rst index b36af65a08ed..65f61695f561 100644 --- a/Documentation/sound/alsa-configuration.rst +++ b/Documentation/sound/alsa-configuration.rst @@ -1059,6 +1059,12 @@ The model name ``generic`` is treated as a special case. When this model is given, the driver uses the generic codec parser without "codec-patch". It's sometimes good for testing and debugging. +The model option can be used also for aliasing to another PCI or codec +SSID. When it's passed in the form of ``model=XXXX:YYYY`` where XXXX +and YYYY are the sub-vendor and sub-device IDs in hex numbers, +respectively, the driver will refer to that SSID as a reference to the +quirk table. + If the default configuration doesn't work and one of the above matches with your device, report it together with alsa-info.sh output (with ``--no-upload`` option) to kernel bugzilla or alsa-devel @@ -2252,6 +2258,27 @@ delayed_register The driver prints a message like "Found post-registration device assignment: 1234abcd:04" for such a device, so that user can notice the need. +quirk_flags + Contains the bit flags for various device specific workarounds. + Applied to the corresponding card index. + + * bit 0: Skip reading sample rate for devices + * bit 1: Create Media Controller API entries + * bit 2: Allow alignment on audio sub-slot at transfer + * bit 3: Add length specifier to transfers + * bit 4: Start playback stream at first in implement feedback mode + * bit 5: Skip clock selector setup + * bit 6: Ignore errors from clock source search + * bit 7: Indicates ITF-USB DSD based DACs + * bit 8: Add a delay of 20ms at each control message handling + * bit 9: Add a delay of 1-2ms at each control message handling + * bit 10: Add a delay of 5-6ms at each control message handling + * bit 11: Add a delay of 50ms at each interface setup + * bit 12: Perform sample rate validations at probe + * bit 13: Disable runtime PM autosuspend + * bit 14: Ignore errors for mixer access + * bit 15: Support generic DSD raw U32_BE format + * bit 16: Set up the interface at first like UAC1 This module supports multiple devices, autoprobe and hotplugging. @@ -2261,11 +2288,14 @@ check. NB: ``ignore_ctl_error=1`` may help when you get an error at accessing the mixer element such as URB error -22. This happens on some -buggy USB device or the controller. +buggy USB device or the controller. This workaround corresponds to +the ``quirk_flags`` bit 14, too. -NB: quirk_alias option is provided only for testing / development. +NB: ``quirk_alias`` option is provided only for testing / development. If you want to have a proper support, contact to upstream for adding the matching quirk in the driver code statically. +Ditto for ``quirk_flags``. If a device is known to require specific +workarounds, please report to the upstream. Module snd-usb-caiaq -------------------- diff --git a/Documentation/sound/hd-audio/notes.rst b/Documentation/sound/hd-audio/notes.rst index cf4d7158af78..d118b6fe269b 100644 --- a/Documentation/sound/hd-audio/notes.rst +++ b/Documentation/sound/hd-audio/notes.rst @@ -215,6 +215,17 @@ There are a few special model option values: * when ``generic`` is passed, the codec-specific parser is skipped and only the generic parser is used. +A new style for the model option that was introduced since 5.15 kernel +is to pass the PCI or codec SSID in the form of ``model=XXXX:YYYY`` +where XXXX and YYYY are the sub-vendor and sub-device IDs in hex +numbers, respectively. This is a kind of aliasing to another device; +when this form is given, the driver will refer to that SSID as a +reference to the quirk table. It'd be useful especially when the +target quirk isn't listed in the model table. For example, passing +model=103c:8862 will apply the quirk for HP ProBook 445 G8 (which +isn't found in the model table as of writing) as long as the device is +handled equivalently by the same driver. + Speaker and Headphone Output ---------------------------- diff --git a/Documentation/sound/kernel-api/writing-an-alsa-driver.rst b/Documentation/sound/kernel-api/writing-an-alsa-driver.rst index 01d59b8aea92..176b73583b7a 100644 --- a/Documentation/sound/kernel-api/writing-an-alsa-driver.rst +++ b/Documentation/sound/kernel-api/writing-an-alsa-driver.rst @@ -3368,7 +3368,7 @@ This ensures that the device can be closed and the driver unloaded without losing data. This callback is optional. If you do not set ``drain`` in the struct -snd_rawmidi_ops structure, ALSA will simply wait for 50 milliseconds +snd_rawmidi_ops structure, ALSA will simply wait for 50 milliseconds instead. Miscellaneous Devices @@ -4172,6 +4172,39 @@ module license as GPL, etc., otherwise the system is shown as “tainted”. MODULE_LICENSE("GPL"); +Device-Managed Resources +======================== + +In the examples above, all resources are allocated and released +manually. But human beings are lazy in nature, especially developers +are lazier. So there are some ways to automate the release part; it's +the (device-)managed resources aka devres or devm family. For +example, an object allocated via :c:func:`devm_kmalloc()` will be +freed automatically at unbinding the device. + +ALSA core provides also the device-managed helper, namely, +:c:func:`snd_devm_card_new()` for creating a card object. +Call this functions instead of the normal :c:func:`snd_card_new()`, +and you can forget the explicit :c:func:`snd_card_free()` call, as +it's called automagically at error and removal paths. + +One caveat is that the call of :c:func:`snd_card_free()` would be put +at the beginning of the call chain only after you call +:c:func:`snd_card_register()`. + +Also, the ``private_free`` callback is always called at the card free, +so be careful to put the hardware clean-up procedure in +``private_free`` callback. It might be called even before you +actually set up at an earlier error path. For avoiding such an +invalid initialization, you can set ``private_free`` callback after +:c:func:`snd_card_register()` call succeeds. + +Another thing to be remarked is that you should use device-managed +helpers for each component as much as possible once when you manage +the card in that way. Mixing up with the normal and the managed +resources may screw up the release order. + + How To Put Your Driver Into ALSA Tree ===================================== diff --git a/Documentation/sphinx/requirements.txt b/Documentation/sphinx/requirements.txt index 489f6626de67..9a35f50798a6 100644 --- a/Documentation/sphinx/requirements.txt +++ b/Documentation/sphinx/requirements.txt @@ -1,3 +1,2 @@ -docutils -Sphinx==2.4.4 sphinx_rtd_theme +Sphinx==2.4.4 diff --git a/Documentation/trace/coresight/coresight-config.rst b/Documentation/trace/coresight/coresight-config.rst new file mode 100644 index 000000000000..a4e3ef295240 --- /dev/null +++ b/Documentation/trace/coresight/coresight-config.rst @@ -0,0 +1,244 @@ +.. SPDX-License-Identifier: GPL-2.0 + +====================================== +CoreSight System Configuration Manager +====================================== + + :Author: Mike Leach <mike.leach@linaro.org> + :Date: October 2020 + +Introduction +============ + +The CoreSight System Configuration manager is an API that allows the +programming of the CoreSight system with pre-defined configurations that +can then be easily enabled from sysfs or perf. + +Many CoreSight components can be programmed in complex ways - especially ETMs. +In addition, components can interact across the CoreSight system, often via +the cross trigger components such as CTI and CTM. These system settings can +be defined and enabled as named configurations. + + +Basic Concepts +============== + +This section introduces the basic concepts of a CoreSight system configuration. + + +Features +-------- + +A feature is a named set of programming for a CoreSight device. The programming +is device dependent, and can be defined in terms of absolute register values, +resource usage and parameter values. + +The feature is defined using a descriptor. This descriptor is used to load onto +a matching device, either when the feature is loaded into the system, or when the +CoreSight device is registered with the configuration manager. + +The load process involves interpreting the descriptor into a set of register +accesses in the driver - the resource usage and parameter descriptions +translated into appropriate register accesses. This interpretation makes it easy +and efficient for the feature to be programmed onto the device when required. + +The feature will not be active on the device until the feature is enabled, and +the device itself is enabled. When the device is enabled then enabled features +will be programmed into the device hardware. + +A feature is enabled as part of a configuration being enabled on the system. + + +Parameter Value +~~~~~~~~~~~~~~~ + +A parameter value is a named value that may be set by the user prior to the +feature being enabled that can adjust the behaviour of the operation programmed +by the feature. + +For example, this could be a count value in a programmed operation that repeats +at a given rate. When the feature is enabled then the current value of the +parameter is used in programming the device. + +The feature descriptor defines a default value for a parameter, which is used +if the user does not supply a new value. + +Users can update parameter values using the configfs API for the CoreSight +system - which is described below. + +The current value of the parameter is loaded into the device when the feature +is enabled on that device. + + +Configurations +-------------- + +A configuration defines a set of features that are to be used in a trace +session where the configuration is selected. For any trace session only one +configuration may be selected. + +The features defined may be on any type of device that is registered +to support system configuration. A configuration may select features to be +enabled on a class of devices - i.e. any ETMv4, or specific devices, e.g. a +specific CTI on the system. + +As with the feature, a descriptor is used to define the configuration. +This will define the features that must be enabled as part of the configuration +as well as any preset values that can be used to override default parameter +values. + + +Preset Values +~~~~~~~~~~~~~ + +Preset values are easily selectable sets of parameter values for the features +that the configuration uses. The number of values in a single preset set, equals +the sum of parameter values in the features used by the configuration. + +e.g. a configuration consists of 3 features, one has 2 parameters, one has +a single parameter, and another has no parameters. A single preset set will +therefore have 3 values. + +Presets are optionally defined by the configuration, up to 15 can be defined. +If no preset is selected, then the parameter values defined in the feature +are used as normal. + + +Operation +~~~~~~~~~ + +The following steps take place in the operation of a configuration. + +1) In this example, the configuration is 'autofdo', which has an + associated feature 'strobing' that works on ETMv4 CoreSight Devices. + +2) The configuration is enabled. For example 'perf' may select the + configuration as part of its command line:: + + perf record -e cs_etm/autofdo/ myapp + + which will enable the 'autofdo' configuration. + +3) perf starts tracing on the system. As each ETMv4 that perf uses for + trace is enabled, the configuration manager will check if the ETMv4 + has a feature that relates to the currently active configuration. + In this case 'strobing' is enabled & programmed into the ETMv4. + +4) When the ETMv4 is disabled, any registers marked as needing to be + saved will be read back. + +5) At the end of the perf session, the configuration will be disabled. + + +Viewing Configurations and Features +=================================== + +The set of configurations and features that are currently loaded into the +system can be viewed using the configfs API. + +Mount configfs as normal and the 'cs-syscfg' subsystem will appear:: + + $ ls /config + cs-syscfg stp-policy + +This has two sub-directories:: + + $ cd cs-syscfg/ + $ ls + configurations features + +The system has the configuration 'autofdo' built in. It may be examined as +follows:: + + $ cd configurations/ + $ ls + autofdo + $ cd autofdo/ + $ ls + description preset1 preset3 preset5 preset7 preset9 + feature_refs preset2 preset4 preset6 preset8 + $ cat description + Setup ETMs with strobing for autofdo + $ cat feature_refs + strobing + +Each preset declared has a preset<n> subdirectory declared. The values for +the preset can be examined:: + + $ cat preset1/values + strobing.window = 0x1388 strobing.period = 0x2 + $ cat preset2/values + strobing.window = 0x1388 strobing.period = 0x4 + +The features referenced by the configuration can be examined in the features +directory:: + + $ cd ../../features/strobing/ + $ ls + description matches nr_params params + $ cat description + Generate periodic trace capture windows. + parameter 'window': a number of CPU cycles (W) + parameter 'period': trace enabled for W cycles every period x W cycles + $ cat matches + SRC_ETMV4 + $ cat nr_params + 2 + +Move to the params directory to examine and adjust parameters:: + + cd params + $ ls + period window + $ cd period + $ ls + value + $ cat value + 0x2710 + # echo 15000 > value + # cat value + 0x3a98 + +Parameters adjusted in this way are reflected in all device instances that have +loaded the feature. + + +Using Configurations in perf +============================ + +The configurations loaded into the CoreSight configuration management are +also declared in the perf 'cs_etm' event infrastructure so that they can +be selected when running trace under perf:: + + $ ls /sys/devices/cs_etm + configurations format perf_event_mux_interval_ms sinks type + events nr_addr_filters power + +Key directories here are 'configurations' - which lists the loaded +configurations, and 'events' - a generic perf directory which allows +selection on the perf command line.:: + + $ ls configurations/ + autofdo + $ cat configurations/autofdo + 0xa7c3dddd + +As with the sinks entries, this provides a hash of the configuration name. +The entry in the 'events' directory uses perfs built in syntax generator +to substitute the syntax for the name when evaluating the command:: + + $ ls events/ + autofdo + $ cat events/autofdo + configid=0xa7c3dddd + +The 'autofdo' configuration may be selected on the perf command line:: + + $ perf record -e cs_etm/autofdo/u --per-thread <application> + +A preset to override the current parameter values can also be selected:: + + $ perf record -e cs_etm/autofdo,preset=1/u --per-thread <application> + +When configurations are selected in this way, then the trace sink used is +automatically selected. diff --git a/Documentation/trace/coresight/coresight.rst b/Documentation/trace/coresight/coresight.rst index 1ec8dc35b1d8..a15571d96cc8 100644 --- a/Documentation/trace/coresight/coresight.rst +++ b/Documentation/trace/coresight/coresight.rst @@ -620,6 +620,19 @@ channels on the CTM (Cross Trigger Matrix). A separate documentation file is provided to explain the use of these devices. (Documentation/trace/coresight/coresight-ect.rst) [#fourth]_. +CoreSight System Configuration +------------------------------ + +CoreSight components can be complex devices with many programming options. +Furthermore, components can be programmed to interact with each other across the +complete system. + +A CoreSight System Configuration manager is provided to allow these complex programming +configurations to be selected and used easily from perf and sysfs. + +See the separate document for further information. +(Documentation/trace/coresight/coresight-config.rst) [#fifth]_. + .. [#first] Documentation/ABI/testing/sysfs-bus-coresight-devices-stm @@ -628,3 +641,5 @@ A separate documentation file is provided to explain the use of these devices. .. [#third] https://github.com/Linaro/perf-opencsd .. [#fourth] Documentation/trace/coresight/coresight-ect.rst + +.. [#fifth] Documentation/trace/coresight/coresight-config.rst diff --git a/Documentation/trace/ftrace.rst b/Documentation/trace/ftrace.rst index cfc81e98e0b8..4e5b26f03d5b 100644 --- a/Documentation/trace/ftrace.rst +++ b/Documentation/trace/ftrace.rst @@ -2762,7 +2762,7 @@ listed in: put_prev_task_idle kmem_cache_create pick_next_task_rt - get_online_cpus + cpus_read_lock pick_next_task_fair mutex_lock [...] diff --git a/Documentation/translations/conf.py b/Documentation/translations/conf.py new file mode 100644 index 000000000000..92cdbba74229 --- /dev/null +++ b/Documentation/translations/conf.py @@ -0,0 +1,12 @@ +# -*- coding: utf-8 -*- +# SPDX-License-Identifier: GPL-2.0 + +# -- Additinal options for LaTeX output ---------------------------------- +# font config for ascii-art alignment + +latex_elements['preamble'] += ''' + \\IfFontExistsTF{Noto Sans CJK SC}{ + % For CJK ascii-art alignment + \\setmonofont{Noto Sans Mono CJK SC}[AutoFakeSlant] + }{} +''' diff --git a/Documentation/translations/index.rst b/Documentation/translations/index.rst index 556b050884fc..1175a47d07f0 100644 --- a/Documentation/translations/index.rst +++ b/Documentation/translations/index.rst @@ -8,6 +8,7 @@ Translations :maxdepth: 1 zh_CN/index + zh_TW/index it_IT/index ko_KR/index ja_JP/index diff --git a/Documentation/translations/it_IT/core-api/symbol-namespaces.rst b/Documentation/translations/it_IT/core-api/symbol-namespaces.rst index aa851a57a4b0..42f5d04e38ec 100644 --- a/Documentation/translations/it_IT/core-api/symbol-namespaces.rst +++ b/Documentation/translations/it_IT/core-api/symbol-namespaces.rst @@ -42,15 +42,15 @@ nomi: EXPORT_SYMBOL_NS() ed EXPORT_SYMBOL_NS_GPL(). Queste macro richiedono un argomento aggiuntivo: lo spazio dei nomi. Tenete presente che per via dell'espansione delle macro questo argomento deve essere un simbolo di preprocessore. Per esempio per esportare il -simbolo `usb_stor_suspend` nello spazio dei nomi `USB_STORAGE` usate:: +simbolo ``usb_stor_suspend`` nello spazio dei nomi ``USB_STORAGE`` usate:: EXPORT_SYMBOL_NS(usb_stor_suspend, USB_STORAGE); Di conseguenza, nella tabella dei simboli del kernel ci sarà una voce -rappresentata dalla struttura `kernel_symbol` che avrà il campo -`namespace` (spazio dei nomi) impostato. Un simbolo esportato senza uno spazio -dei nomi avrà questo campo impostato a `NULL`. Non esiste uno spazio dei nomi -di base. Il programma `modpost` e il codice in kernel/module.c usano lo spazio +rappresentata dalla struttura ``kernel_symbol`` che avrà il campo +``namespace`` (spazio dei nomi) impostato. Un simbolo esportato senza uno spazio +dei nomi avrà questo campo impostato a ``NULL``. Non esiste uno spazio dei nomi +di base. Il programma ``modpost`` e il codice in kernel/module.c usano lo spazio dei nomi, rispettivamente, durante la compilazione e durante il caricamento di un modulo. @@ -65,7 +65,7 @@ ed EXPORT_SYMBOL_GPL() che non specificano esplicitamente uno spazio dei nomi. Ci sono molti modi per specificare questo simbolo di preprocessore e il loro uso dipende dalle preferenze del manutentore di un sottosistema. La prima -possibilità è quella di definire il simbolo nel `Makefile` del sottosistema. +possibilità è quella di definire il simbolo nel ``Makefile`` del sottosistema. Per esempio per esportare tutti i simboli definiti in usb-common nello spazio dei nomi USB_COMMON, si può aggiungere la seguente linea in drivers/usb/common/Makefile:: @@ -97,7 +97,7 @@ USB_STORAGE usando la seguente dichiarazione:: MODULE_IMPORT_NS(USB_STORAGE); -Questo creerà un'etichetta `modinfo` per ogni spazio dei nomi +Questo creerà un'etichetta ``modinfo`` per ogni spazio dei nomi importato. Un risvolto di questo fatto è che gli spazi dei nomi importati da un modulo possono essere ispezionati tramite modinfo:: @@ -116,7 +116,7 @@ mancanti. 4. Caricare moduli che usano simboli provenienti da spazi dei nomi ================================================================== -Quando un modulo viene caricato (per esempio usando `insmod`), il kernel +Quando un modulo viene caricato (per esempio usando ``insmod``), il kernel verificherà la disponibilità di ogni simbolo usato e se lo spazio dei nomi che potrebbe contenerli è stato importato. Il comportamento di base del kernel è di rifiutarsi di caricare quei moduli che non importano tutti gli spazi dei @@ -144,22 +144,22 @@ Lo scenario tipico di chi scrive un modulo potrebbe essere:: - scrivere codice che dipende da un simbolo appartenente ad uno spazio dei nomi non importato - - eseguire `make` + - eseguire ``make`` - aver notato un avviso da modpost che parla di un'importazione mancante - - eseguire `make nsdeps` per aggiungere import nel posto giusto + - eseguire ``make nsdeps`` per aggiungere import nel posto giusto Per i manutentori di sottosistemi che vogliono aggiungere uno spazio dei nomi, -l'approccio è simile. Di nuovo, eseguendo `make nsdeps` aggiungerà le +l'approccio è simile. Di nuovo, eseguendo ``make nsdeps`` aggiungerà le importazioni mancanti nei moduli inclusi nel kernel:: - spostare o aggiungere simboli ad uno spazio dei nomi (per esempio usando EXPORT_SYMBOL_NS()) - - eseguire `make` (preferibilmente con allmodconfig per coprire tutti + - eseguire ``make`` (preferibilmente con allmodconfig per coprire tutti i moduli del kernel) - aver notato un avviso da modpost che parla di un'importazione mancante - - eseguire `make nsdeps` per aggiungere import nel posto giusto + - eseguire ``make nsdeps`` per aggiungere import nel posto giusto Potete anche eseguire nsdeps per moduli esterni. Solitamente si usa così:: diff --git a/Documentation/translations/it_IT/kernel-hacking/hacking.rst b/Documentation/translations/it_IT/kernel-hacking/hacking.rst index f6beb385b4ac..b4ea00f1b583 100644 --- a/Documentation/translations/it_IT/kernel-hacking/hacking.rst +++ b/Documentation/translations/it_IT/kernel-hacking/hacking.rst @@ -634,7 +634,7 @@ Definita in ``include/linux/export.h`` Questa è una variate di `EXPORT_SYMBOL()` che permette di specificare uno spazio dei nomi. Lo spazio dei nomi è documentato in -:doc:`../core-api/symbol-namespaces` +Documentation/translations/it_IT/core-api/symbol-namespaces.rst. :c:func:`EXPORT_SYMBOL_NS_GPL()` -------------------------------- @@ -643,7 +643,7 @@ Definita in ``include/linux/export.h`` Questa è una variate di `EXPORT_SYMBOL_GPL()` che permette di specificare uno spazio dei nomi. Lo spazio dei nomi è documentato in -:doc:`../core-api/symbol-namespaces` +Documentation/translations/it_IT/core-api/symbol-namespaces.rst. Procedure e convenzioni ======================= diff --git a/Documentation/translations/it_IT/process/deprecated.rst b/Documentation/translations/it_IT/process/deprecated.rst index 07c79d4bafca..987f45ee1804 100644 --- a/Documentation/translations/it_IT/process/deprecated.rst +++ b/Documentation/translations/it_IT/process/deprecated.rst @@ -183,9 +183,11 @@ di Linus: affrontare il giudizio di Linus, allora forse potrai usare "%px", assicurandosi anche di averne il permesso. -Infine, sappi che un cambio in favore di "%p" con hash `non verrà -accettato -<https://lore.kernel.org/lkml/CA+55aFwieC1-nAs+NFq9RTwaR8ef9hWa4MjNBWL41F-8wM49eA@mail.gmail.com/>`_. +Potete disabilitare temporaneamente l'hashing di "%p" nel caso in cui questa +funzionalità vi sia d'ostacolo durante una sessione di debug. Per farlo +aggiungete l'opzione di debug "`no_hash_pointers +<https://git.kernel.org/linus/5ead723a20e0447bc7db33dc3070b420e5f80aa6>`_" alla +riga di comando del kernel. Vettori a dimensione variabile (VLA) ------------------------------------ diff --git a/Documentation/translations/it_IT/process/stable-kernel-rules.rst b/Documentation/translations/it_IT/process/stable-kernel-rules.rst index 283d62541c4f..83f48afe48b9 100644 --- a/Documentation/translations/it_IT/process/stable-kernel-rules.rst +++ b/Documentation/translations/it_IT/process/stable-kernel-rules.rst @@ -41,12 +41,6 @@ Regole sul tipo di patch che vengono o non vengono accettate nei sorgenti Procedura per sottomettere patch per i sorgenti -stable ------------------------------------------------------- - - Se la patch contiene modifiche a dei file nelle cartelle net/ o drivers/net, - allora seguite le linee guida descritte in - :ref:`Documentation/translations/it_IT/networking/netdev-FAQ.rst <it_netdev-FAQ>`; - ma solo dopo aver verificato al seguente indirizzo che la patch non sia - già in coda: - https://patchwork.kernel.org/bundle/netdev/stable/?state=* - Una patch di sicurezza non dovrebbero essere gestite (solamente) dal processo di revisione -stable, ma dovrebbe seguire le procedure descritte in :ref:`Documentation/translations/it_IT/admin-guide/security-bugs.rst <it_securitybugs>`. diff --git a/Documentation/translations/it_IT/process/submitting-patches.rst b/Documentation/translations/it_IT/process/submitting-patches.rst index ded95048b9a8..458d9d24b9c0 100644 --- a/Documentation/translations/it_IT/process/submitting-patches.rst +++ b/Documentation/translations/it_IT/process/submitting-patches.rst @@ -14,14 +14,15 @@ una certa familiarità col "sistema". Questo testo è una raccolta di suggerimenti che aumenteranno significativamente le probabilità di vedere le vostre patch accettate. -Questo documento contiene un vasto numero di suggerimenti concisi. Per -maggiori dettagli su come funziona il processo di sviluppo del kernel leggete -:doc:`development-process`. -Leggete anche :doc:`submit-checklist` per una lista di punti da -verificare prima di inviare del codice. Se state inviando un driver, -allora leggete anche :doc:`submitting-drivers`; per delle patch +Questo documento contiene un vasto numero di suggerimenti concisi. Per maggiori +dettagli su come funziona il processo di sviluppo del kernel leggete +Documentation/translations/it_IT/process/development-process.rst. Leggete anche +Documentation/translations/it_IT/process/submit-checklist.rst per una lista di +punti da verificare prima di inviare del codice. Se state inviando un driver, +allora leggete anche +Documentation/translations/it_IT/process/submitting-drivers.rst; per delle patch relative alle associazioni per Device Tree leggete -:doc:`submitting-patches`. +Documentation/translations/it_IT/process/submitting-patches.rst. Questa documentazione assume che sappiate usare ``git`` per preparare le patch. Se non siete pratici di ``git``, allora è bene che lo impariate; @@ -193,7 +194,7 @@ ed integrate. --------------------------------------------- Controllate che la vostra patch non violi lo stile del codice, maggiori -dettagli sono disponibili in :ref:`Documentation/translations/it_IT/process/coding-style.rst <it_codingstyle>`. +dettagli sono disponibili in Documentation/translations/it_IT/process/coding-style.rst. Non farlo porta semplicemente a una perdita di tempo da parte dei revisori e voi vedrete la vostra patch rifiutata, probabilmente senza nemmeno essere stata letta. @@ -230,13 +231,13 @@ scripts/get_maintainer.pl può esservi d'aiuto. Se non riuscite a trovare un manutentore per il sottosistema su cui state lavorando, allora Andrew Morton (akpm@linux-foundation.org) sarà la vostra ultima possibilità. -Normalmente, dovreste anche scegliere una lista di discussione a cui inviare -la vostra serie di patch. La lista di discussione linux-kernel@vger.kernel.org -è proprio l'ultima spiaggia, il volume di email su questa lista fa si che -diversi sviluppatori non la seguano. Guardate nel file MAINTAINERS per trovare -la lista di discussione dedicata ad un sottosistema; probabilmente lì la vostra -patch riceverà molta più attenzione. Tuttavia, per favore, non spammate le -liste di discussione che non sono interessate al vostro lavoro. +Normalmente, dovreste anche scegliere una lista di discussione a cui inviare la +vostra serie di patch. La lista di discussione linux-kernel@vger.kernel.org +dovrebbe essere usata per inviare tutte le patch, ma il traffico è tale per cui +diversi sviluppatori la trascurano. Guardate nel file MAINTAINERS per trovare la +lista di discussione dedicata ad un sottosistema; probabilmente lì la vostra +patch riceverà molta più attenzione. Tuttavia, per favore, non spammate le liste +di discussione che non sono interessate al vostro lavoro. Molte delle liste di discussione relative al kernel vengono ospitate su vger.kernel.org; potete trovare un loro elenco alla pagina @@ -257,7 +258,7 @@ embargo potrebbe essere preso in considerazione per dare il tempo alle distribuzioni di prendere la patch e renderla disponibile ai loro utenti; in questo caso, ovviamente, la patch non dovrebbe essere inviata su alcuna lista di discussione pubblica. Leggete anche -:doc:`/admin-guide/security-bugs`. +Documentation/admin-guide/security-bugs.rst. Patch che correggono bachi importanti su un kernel già rilasciato, dovrebbero essere inviate ai manutentori dei kernel stabili aggiungendo la seguente riga:: @@ -266,12 +267,7 @@ essere inviate ai manutentori dei kernel stabili aggiungendo la seguente riga:: nella vostra patch, nell'area dedicata alle firme (notate, NON come destinatario delle e-mail). In aggiunta a questo file, dovreste leggere anche -:ref:`Documentation/translations/it_IT/process/stable-kernel-rules.rst <it_stable_kernel_rules>` - -Tuttavia, notate, che alcuni manutentori di sottosistema preferiscono avere -l'ultima parola su quali patch dovrebbero essere aggiunte ai kernel stabili. -La rete di manutentori, in particolare, non vorrebbe vedere i singoli -sviluppatori aggiungere alle loro patch delle righe come quella sopracitata. +Documentation/translations/it_IT/process/stable-kernel-rules.rst. Se le modifiche hanno effetti sull'interfaccia con lo spazio utente, per favore inviate una patch per le pagine man ai manutentori di suddette pagine (elencati @@ -330,7 +326,7 @@ così la possibilità che il vostro allegato-MIME venga accettato. Eccezione: se il vostro servizio di posta storpia le patch, allora qualcuno potrebbe chiedervi di rinviarle come allegato MIME. -Leggete :doc:`/translations/it_IT/process/email-clients` +Leggete Documentation/translations/it_IT/process/email-clients.rst per dei suggerimenti sulla configurazione del programmi di posta elettronica per l'invio di patch intatte. @@ -351,7 +347,7 @@ richiede molto tempo, e a volte i revisori diventano burberi. Tuttavia, anche in questo caso, rispondete con educazione e concentratevi sul problema che hanno evidenziato. -Leggete :doc:`/translations/it_IT/process/email-clients` per +Leggete Documentation/translations/it_IT/process/email-clients.rst per le raccomandazioni sui programmi di posta elettronica e l'etichetta da usare sulle liste di discussione. @@ -369,6 +365,16 @@ aver inviato le patch correttamente. Aspettate almeno una settimana prima di rinviare le modifiche o sollecitare i revisori - probabilmente anche di più durante la finestra d'integrazione. +Potete anche rinviare la patch, o la serie di patch, dopo un paio di settimane +aggiungendo la parola "RESEND" nel titolo:: + + [PATCH Vx RESEND] sub/sys: Condensed patch summary + +Ma non aggiungete "RESEND" quando state sottomettendo una versione modificata +della vostra patch, o serie di patch - "RESEND" si applica solo alla +sottomissione di patch, o serie di patch, che non hanno subito modifiche +dall'ultima volta che sono state inviate. + Aggiungete PATCH nell'oggetto ----------------------------- @@ -795,8 +801,7 @@ Greg Kroah-Hartman, "Come scocciare un manutentore di un sottosistema" No!!!! Basta gigantesche bombe patch alle persone sulla lista linux-kernel@vger.kernel.org! <https://lore.kernel.org/r/20050711.125305.08322243.davem@davemloft.net> -Kernel Documentation/translations/it_IT/process/coding-style.rst: - :ref:`Documentation/translations/it_IT/process/coding-style.rst <it_codingstyle>` +Kernel Documentation/translations/it_IT/process/coding-style.rst. E-mail di Linus Torvalds sul formato canonico di una patch: <https://lore.kernel.org/r/Pine.LNX.4.58.0504071023190.28951@ppc970.osdl.org> diff --git a/Documentation/translations/ja_JP/howto.rst b/Documentation/translations/ja_JP/howto.rst index 73ebdab4ced7..d667f9d8a02a 100644 --- a/Documentation/translations/ja_JP/howto.rst +++ b/Documentation/translations/ja_JP/howto.rst @@ -1,3 +1,7 @@ +.. raw:: latex + + \kerneldocCJKoff + NOTE: This is a version of Documentation/process/howto.rst translated into Japanese. This document is maintained by Tsugikazu Shibata <tshibata@ab.jp.nec.com> @@ -11,6 +15,10 @@ try to update the original English file first. ---------------------------------- +.. raw:: latex + + \kerneldocCJKon + この文書は、 Documentation/process/howto.rst の和訳です。 diff --git a/Documentation/translations/ja_JP/index.rst b/Documentation/translations/ja_JP/index.rst index f94ba62d41c3..88d4d98eed15 100644 --- a/Documentation/translations/ja_JP/index.rst +++ b/Documentation/translations/ja_JP/index.rst @@ -3,6 +3,7 @@ \renewcommand\thesection* \renewcommand\thesubsection* \kerneldocCJKon + \kerneldocBeginJP Japanese translations ===================== @@ -11,3 +12,7 @@ Japanese translations :maxdepth: 1 howto + +.. raw:: latex + + \kerneldocEndJP diff --git a/Documentation/translations/ko_KR/howto.rst b/Documentation/translations/ko_KR/howto.rst index a2bdd564c907..e3cdf0c84892 100644 --- a/Documentation/translations/ko_KR/howto.rst +++ b/Documentation/translations/ko_KR/howto.rst @@ -1,3 +1,7 @@ +.. raw:: latex + + \kerneldocCJKoff + NOTE: This is a version of Documentation/process/howto.rst translated into korean This document is maintained by Minchan Kim <minchan@kernel.org> @@ -11,6 +15,10 @@ try to update the original English file first. ---------------------------------- +.. raw:: latex + + \kerneldocCJKon + 이 문서는 Documentation/process/howto.rst 의 한글 번역입니다. diff --git a/Documentation/translations/ko_KR/index.rst b/Documentation/translations/ko_KR/index.rst index 6ae258118bdf..f636b482fb4c 100644 --- a/Documentation/translations/ko_KR/index.rst +++ b/Documentation/translations/ko_KR/index.rst @@ -3,6 +3,7 @@ \renewcommand\thesection* \renewcommand\thesubsection* \kerneldocCJKon + \kerneldocBeginKR 한국어 번역 =========== @@ -26,3 +27,4 @@ .. raw:: latex \normalsize + \kerneldocEndKR diff --git a/Documentation/translations/zh_CN/accounting/index.rst b/Documentation/translations/zh_CN/accounting/index.rst new file mode 100644 index 000000000000..362e907b41f9 --- /dev/null +++ b/Documentation/translations/zh_CN/accounting/index.rst @@ -0,0 +1,25 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/accounting/index.rst +:Translator: Yang Yang <yang.yang29@zte.com.cn> + +.. _cn_accounting_index.rst: + + +==== +计数 +==== + +.. toctree:: + :maxdepth: 1 + + psi + +Todolist: + + cgroupstats + delay-accounting + taskstats + taskstats-struct diff --git a/Documentation/translations/zh_CN/accounting/psi.rst b/Documentation/translations/zh_CN/accounting/psi.rst new file mode 100644 index 000000000000..a0ddb7bd257c --- /dev/null +++ b/Documentation/translations/zh_CN/accounting/psi.rst @@ -0,0 +1,155 @@ +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/accounting/psi.rst +:Translator: Yang Yang <yang.yang29@zte.com.cn> + +.. _cn_psi.rst: + + +================= +PSI——压力阻塞信息 +================= + +:日期: April, 2018 +:作者: Johannes Weiner <hannes@cmpxchg.org> + +当CPU、memory或IO设备处于竞争状态，业务负载会遭受时延毛刺、吞吐量降低， +及面临OOM的风险。 + +如果没有一种准确的方法度量系统竞争程度，则有两种后果：一种是用户过于节制， +未充分利用系统资源；另一种是过度使用，经常性面临业务中断的风险。 + +psi特性能够识别和量化资源竞争导致的业务中断，及其对复杂负载乃至整个系统在 +时间上的影响。 + +准确度量因资源不足造成的生产力损失，有助于用户基于硬件调整业务负载，或基 +于业务负载配置硬件。 + +psi能够实时的提供相关信息，因此系统可基于psi实现动态的负载管理。如实施 +卸载、迁移、策略性的停止或杀死低优先级或可重启的批处理任务。 + +psi帮助用户实现硬件资源利用率的最大化。同时无需牺牲业务负载健康度，也无需 +面临OOM等造成业务中断的风险。 + +压力接口 +======== + +压力信息可通过/proc/pressure/ --cpu、memory、io文件分别获取。 + +CPU相关信息格式如下： + + some avg10=0.00 avg60=0.00 avg300=0.00 total=0 + +内存和IO相关信息如下： + + some avg10=0.00 avg60=0.00 avg300=0.00 total=0 + full avg10=0.00 avg60=0.00 avg300=0.00 total=0 + +some行代表至少有一个任务阻塞于特定资源的时间占比。 + +full行代表所有非idle任务同时阻塞于特定资源的时间占比。在这种状态下CPU资源 +完全被浪费，相对于正常运行，业务负载由于耗费更多时间等待而受到严重影响。 + +由于此情况严重影响系统性能，因此清楚的识别本情况并与some行所代表的情况区分开， +将有助于分析及提升系统性能。这就是full独立于some行的原因。 + +avg代表阻塞时间占比（百分比），为最近10秒、60秒、300秒内的均值。这样我们 +既可观察到短期事件的影响，也可看到中等及长时间内的趋势。total代表总阻塞 +时间（单位微秒），可用于观察时延毛刺，这种毛刺可能在均值中无法体现。 + +监控压力门限 +============ + +用户可注册触发器，通过poll()监控资源压力是否超过门限。 + +触发器定义：指定时间窗口期内累积阻塞时间的最大值。比如可定义500ms内积累 +100ms阻塞，即触发一次唤醒事件。 + +触发器注册方法：用户打开代表特定资源的psi接口文件，写入门限、时间窗口的值。 +所打开的文件描述符用于等待事件，可使用select()、poll()、epoll()。 +写入信息的格式如下： + + <some|full> <stall amount in us> <time window in us> + +示例：向/proc/pressure/memory写入"some 150000 1000000"将新增触发器，将在 +1秒内至少一个任务阻塞于内存的总时间超过150ms时触发。向/proc/pressure/io写入 +"full 50000 1000000"将新增触发器，将在1秒内所有任务都阻塞于io的总时间超过50ms时触发。 + +触发器可针对多个psi度量值设置，同一个psi度量值可设置多个触发器。每个触发器需要 +单独的文件描述符用于轮询，以区分于其他触发器。所以即使对于同一个psi接口文件， +每个触发器也需要单独的调用open()。 + +监控器在被监控资源进入阻塞状态时启动，在系统退出阻塞状态后停用。系统进入阻塞 +状态后，监控psi增长的频率为每监控窗口刷新10次。 + +内核接受的窗口为500ms~10s，所以监控间隔为50ms~1s。设置窗口下限目的是为了 +防止过于频繁的轮询。设置窗口上限的目的是因为窗口过长则无意义，此时查看 +psi接口提供的均值即可。 + +监控器在激活后，至少在跟踪窗口期间将保持活动状态。以避免随着系统进入和退出 +阻塞状态，监控器过于频繁的进入和退出活动状态。 + +用户态通知在监控窗口内会受到速率限制。当对应的文件描述符关闭，触发器会自动注销。 + +用户态监控器使用示例 +==================== + +:: + + #include <errno.h> + #include <fcntl.h> + #include <stdio.h> + #include <poll.h> + #include <string.h> + #include <unistd.h> + + /* 监控内存部分阻塞，监控时间窗口为1秒、阻塞门限为150毫秒。*/ + int main() { + const char trig[] = "some 150000 1000000"; + struct pollfd fds; + int n; + + fds.fd = open("/proc/pressure/memory", O_RDWR | O_NONBLOCK); + if (fds.fd < 0) { + printf("/proc/pressure/memory open error: %s\n", + strerror(errno)); + return 1; + } + fds.events = POLLPRI; + + if (write(fds.fd, trig, strlen(trig) + 1) < 0) { + printf("/proc/pressure/memory write error: %s\n", + strerror(errno)); + return 1; + } + + printf("waiting for events...\n"); + while (1) { + n = poll(&fds, 1, -1); + if (n < 0) { + printf("poll error: %s\n", strerror(errno)); + return 1; + } + if (fds.revents & POLLERR) { + printf("got POLLERR, event source is gone\n"); + return 0; + } + if (fds.revents & POLLPRI) { + printf("event triggered!\n"); + } else { + printf("unknown event received: 0x%x\n", fds.revents); + return 1; + } + } + + return 0; + } + +Cgroup2接口 +=========== + +对于CONFIG_CGROUP=y及挂载了cgroup2文件系统的系统，能够获取cgroups内任务的psi。 +此场景下cgroupfs挂载点的子目录包含cpu.pressure、memory.pressure、io.pressure文件， +内容格式与/proc/pressure/下的文件相同。 + +可设置基于cgroup的psi监控器，方法与系统级psi监控器相同。 diff --git a/Documentation/translations/zh_CN/core-api/cachetlb.rst b/Documentation/translations/zh_CN/core-api/cachetlb.rst index 8376485a534d..55827b8a7c53 100644 --- a/Documentation/translations/zh_CN/core-api/cachetlb.rst +++ b/Documentation/translations/zh_CN/core-api/cachetlb.rst @@ -298,15 +298,6 @@ HyperSparc cpu就是这样一个具有这种属性的cpu。 用。默认的实现是nop（对于所有相干的架构应该保持这样）。对于不一致性 的架构，它应该刷新vmaddr处的页面缓存。 - ``void flush_kernel_dcache_page(struct page *page)`` - - 当内核需要修改一个用kmap获得的用户页时，它会在所有修改完成后（但在 - kunmapping之前）调用这个函数，以使底层页面达到最新状态。这里假定用 - 户没有不一致性的缓存副本（即原始页面是从类似get_user_pages()的机制 - 中获得的）。默认的实现是一个nop，在所有相干的架构上都应该如此。在不 - 一致性的架构上，这应该刷新内核缓存中的页面（使用page_address(page)）。 - - ``void flush_icache_range(unsigned long start, unsigned long end)`` 当内核存储到它将执行的地址中时（例如在加载模块时），这个函数被调用。 diff --git a/Documentation/translations/zh_CN/core-api/cpu_hotplug.rst b/Documentation/translations/zh_CN/core-api/cpu_hotplug.rst new file mode 100644 index 000000000000..85a264287426 --- /dev/null +++ b/Documentation/translations/zh_CN/core-api/cpu_hotplug.rst @@ -0,0 +1,348 @@ +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/core-api/cpu_hotplug.rst +:翻译: + + 司延腾 Yanteng Si <siyanteng@loongson.cn> + +:校译: + + 吴想成 Wu XiangCheng <bobwxc@email.cn> + +.. _cn_core_api_cpu_hotplug: + +================= +内核中的CPU热拔插 +================= + +:时间: 2016年12月 +:作者: Sebastian Andrzej Siewior <bigeasy@linutronix.de>, + Rusty Russell <rusty@rustcorp.com.au>, + Srivatsa Vaddagiri <vatsa@in.ibm.com>, + Ashok Raj <ashok.raj@intel.com>, + Joel Schopp <jschopp@austin.ibm.com> + +简介 +==== + +现代系统架构的演进已经在处理器中引入了先进的错误报告和纠正能力。有一些OEM也支 +持可热拔插的NUMA（Non Uniform Memory Access，非统一内存访问）硬件,其中物理 +节点的插入和移除需要支持CPU热插拔。 + +这样的进步要求内核可用的CPU被移除，要么是出于配置的原因，要么是出于RAS的目的， +以保持一个不需要的CPU不在系统执行路径。因此需要在Linux内核中支持CPU热拔插。 + +CPU热拔插支持的一个更新颖的用途是它在SMP的暂停恢复支持中的应用。双核和超线程支 +持使得即使是笔记本电脑也能运行不支持这些方法的SMP内核。 + + +命令行开关 +========== + +``maxcpus=n`` + 限制启动时的CPU为 *n* 个。例如，如果你有四个CPU，使用 ``maxcpus=2`` 将只能启 + 动两个。你可以选择稍后让其他CPU上线。 + +``nr_cpus=n`` + 限制内核将支持的CPU总量。如果这里提供的数量低于实际可用的CPU数量，那么其他CPU + 以后就不能上线了。 + +``additional_cpus=n`` + 使用它来限制可热插拔的CPU。该选项设置 + ``cpu_possible_mask = cpu_present_mask + additional_cpus`` + + 这个选项只限于IA64架构。 + +``possible_cpus=n`` + 这个选项设置 ``cpu_possible_mask`` 中的 ``possible_cpus`` 位。 + + 这个选项只限于X86和S390架构。 + +``cpu0_hotplug`` + 允许关闭CPU0。 + + 这个选项只限于X86架构。 + +CPU位图 +======= + +``cpu_possible_mask`` + 系统中可能可用CPU的位图。这是用来为per_cpu变量分配一些启动时的内存，这些变量 + 不会随着CPU的可用或移除而增加/减少。一旦在启动时的发现阶段被设置，该映射就是静态 + 的，也就是说，任何时候都不会增加或删除任何位。根据你的系统需求提前准确地调整它 + 可以节省一些启动时的内存。 + +``cpu_online_mask`` + 当前在线的所有CPU的位图。在一个CPU可用于内核调度并准备接收设备的中断后，它被 + 设置在 ``__cpu_up()`` 中。当使用 ``__cpu_disable()`` 关闭一个CPU时，它被清 + 空，在此之前，所有的操作系统服务包括中断都被迁移到另一个目标CPU。 + +``cpu_present_mask`` + 系统中当前存在的CPU的位图。它们并非全部在线。当物理热拔插被相关的子系统 + （如ACPI）处理时，可以改变和添加新的位或从位图中删除，这取决于事件是 + hot-add/hot-remove。目前还没有定死规定。典型的用法是在启动时启动拓扑结构，这时 + 热插拔被禁用。 + +你真的不需要操作任何系统的CPU映射。在大多数情况下，它们应该是只读的。当设置每个 +CPU资源时，几乎总是使用 ``cpu_possible_mask`` 或 ``for_each_possible_cpu()`` +来进行迭代。宏 ``for_each_cpu()`` 可以用来迭代一个自定义的CPU掩码。 + +不要使用 ``cpumask_t`` 以外的任何东西来表示CPU的位图。 + + +使用CPU热拔插 +============= + +内核选项 *CONFIG_HOTPLUG_CPU* 需要被启用。它目前可用于多种架构，包括ARM、MIPS、 +PowerPC和X86。配置是通过sysfs接口完成的:: + + $ ls -lh /sys/devices/system/cpu + total 0 + drwxr-xr-x 9 root root 0 Dec 21 16:33 cpu0 + drwxr-xr-x 9 root root 0 Dec 21 16:33 cpu1 + drwxr-xr-x 9 root root 0 Dec 21 16:33 cpu2 + drwxr-xr-x 9 root root 0 Dec 21 16:33 cpu3 + drwxr-xr-x 9 root root 0 Dec 21 16:33 cpu4 + drwxr-xr-x 9 root root 0 Dec 21 16:33 cpu5 + drwxr-xr-x 9 root root 0 Dec 21 16:33 cpu6 + drwxr-xr-x 9 root root 0 Dec 21 16:33 cpu7 + drwxr-xr-x 2 root root 0 Dec 21 16:33 hotplug + -r--r--r-- 1 root root 4.0K Dec 21 16:33 offline + -r--r--r-- 1 root root 4.0K Dec 21 16:33 online + -r--r--r-- 1 root root 4.0K Dec 21 16:33 possible + -r--r--r-- 1 root root 4.0K Dec 21 16:33 present + +文件 *offline* 、 *online* 、*possible* 、*present* 代表CPU掩码。每个CPU文件 +夹包含一个 *online* 文件，控制逻辑上的开（1）和关（0）状态。要在逻辑上关闭CPU4:: + + $ echo 0 > /sys/devices/system/cpu/cpu4/online + smpboot: CPU 4 is now offline + +一旦CPU被关闭，它将从 */proc/interrupts* 、*/proc/cpuinfo* 中被删除，也不应该 +被 *top* 命令显示出来。要让CPU4重新上线:: + + $ echo 1 > /sys/devices/system/cpu/cpu4/online + smpboot: Booting Node 0 Processor 4 APIC 0x1 + +CPU又可以使用了。这应该对所有的CPU都有效。CPU0通常比较特殊，被排除在CPU热拔插之外。 +在X86上，内核选项 *CONFIG_BOOTPARAM_HOTPLUG_CPU0* 必须被启用，以便能够关闭CPU0。 +或者，可以使用内核命令选项 *cpu0_hotplug* 。CPU0的一些已知的依赖性: + +* 从休眠/暂停中恢复。如果CPU0处于离线状态，休眠/暂停将失败。 +* PIC中断。如果检测到PIC中断，CPU0就不能被移除。 + +如果你发现CPU0上有任何依赖性，请告知Fenghua Yu <fenghua.yu@intel.com>。 + +CPU的热拔插协作 +=============== + +下线情况 +-------- + +一旦CPU被逻辑关闭，注册的热插拔状态的清除回调将被调用，从 ``CPUHP_ONLINE`` 开始，在 +``CPUHP_OFFLINE`` 状态结束。这包括: + +* 如果任务因暂停操作而被冻结，那么 *cpuhp_tasks_frozen* 将被设置为true。 + +* 所有进程都会从这个将要离线的CPU迁移到新的CPU上。新的CPU是从每个进程的当前cpuset中 + 选择的，它可能是所有在线CPU的一个子集。 + +* 所有针对这个CPU的中断都被迁移到新的CPU上。 + +* 计时器也会被迁移到新的CPU上。 + +* 一旦所有的服务被迁移，内核会调用一个特定的例程 ``__cpu_disable()`` 来进行特定的清 + 理。 + +使用热插拔API +------------- + +一旦一个CPU下线或上线，就有可能收到通知。这对某些需要根据可用CPU数量执行某种设置或清 +理功能的驱动程序来说可能很重要:: + + #include <linux/cpuhotplug.h> + + ret = cpuhp_setup_state(CPUHP_AP_ONLINE_DYN, "X/Y:online", + Y_online, Y_prepare_down); + +*X* 是子系统， *Y* 是特定的驱动程序。 *Y_online* 回调将在所有在线CPU的注册过程中被调用。 +如果在线回调期间发生错误， *Y_prepare_down* 回调将在所有之前调用过在线回调的CPU上调 +用。注册完成后，一旦有CPU上线， *Y_online* 回调将被调用，当CPU关闭时， *Y_prepare_down* +将被调用。所有之前在 *Y_online* 中分配的资源都应该在 *Y_prepare_down* 中释放。如果在 +注册过程中发生错误，返回值 *ret* 为负值。否则会返回一个正值，其中包含动态分配状态 +（ *CPUHP_AP_ONLINE_DYN* ）的分配热拔插。对于预定义的状态，它将返回0。 + +该回调可以通过调用 ``cpuhp_remove_state()`` 来删除。如果是动态分配的状态 +（ *CPUHP_AP_ONLINE_DYN* ），则使用返回的状态。在移除热插拔状态的过程中，将调用拆解回调。 + +多个实例 +~~~~~~~~ + +如果一个驱动程序有多个实例，并且每个实例都需要独立执行回调，那么很可能应该使用 +``multi-state`` 。首先需要注册一个多状态的状态:: + + ret = cpuhp_setup_state_multi(CPUHP_AP_ONLINE_DYN, "X/Y:online, + Y_online, Y_prepare_down); + Y_hp_online = ret; + +``cpuhp_setup_state_multi()`` 的行为与 ``cpuhp_setup_state()`` 类似，只是它 +为多状态准备了回调，但不调用回调。这是一个一次性的设置。 +一旦分配了一个新的实例，你需要注册这个新实例:: + + ret = cpuhp_state_add_instance(Y_hp_online, &d->node); + +这个函数将把这个实例添加到你先前分配的 ``Y_hp_online`` 状态，并在所有在线的 +CPU上调用先前注册的回调（ ``Y_online`` ）。 *node* 元素是你的每个实例数据结构 +中的一个 ``struct hlist_node`` 成员。 + +在移除该实例时:: + + cpuhp_state_remove_instance(Y_hp_online, &d->node) + +应该被调用，这将在所有在线CPU上调用拆分回调。 + +手动设置 +~~~~~~~~ + +通常情况下，在注册或移除状态时调用setup和teamdown回调是很方便的，因为通常在CPU上线 +（下线）和驱动的初始设置（关闭）时需要执行该操作。然而，每个注册和删除功能也有一个 +_nocalls的后缀，如果不希望调用回调，则不调用所提供的回调。在手动设置（或关闭）期间， +应该使用 ``get_online_cpus()`` 和 ``put_online_cpus()`` 函数来抑制CPU热插拔操作。 + + +事件的顺序 +---------- + +热插拔状态被定义在 ``include/linux/cpuhotplug.h``: + +* ``CPUHP_OFFLINE`` ... ``CPUHP_AP_OFFLINE`` 状态是在CPU启动前调用的。 + +* ``CPUHP_AP_OFFLINE`` ... ``CPUHP_AP_ONLINE`` 状态是在CPU被启动后被调用的。 + 中断是关闭的，调度程序还没有在这个CPU上活动。从 ``CPUHP_AP_OFFLINE`` 开始， + 回调被调用到目标CPU上。 + +* ``CPUHP_AP_ONLINE_DYN`` 和 ``CPUHP_AP_ONLINE_DYN_END`` 之间的状态被保留 + 给动态分配。 + +* 这些状态在CPU关闭时以相反的顺序调用，从 ``CPUHP_ONLINE`` 开始，在 ``CPUHP_OFFLINE`` + 停止。这里的回调是在将被关闭的CPU上调用的，直到 ``CPUHP_AP_OFFLINE`` 。 + +通过 ``CPUHP_AP_ONLINE_DYN`` 动态分配的状态通常已经足够了。然而，如果在启动或关闭 +期间需要更早的调用，那么应该获得一个显式状态。如果热拔插事件需要相对于另一个热拔插事 +件的特定排序，也可能需要一个显式状态。 + +测试热拔插状态 +============== + +验证自定义状态是否按预期工作的一个方法是关闭一个CPU，然后再把它上线。也可以把CPU放到某 +些状态（例如 ``CPUHP_AP_ONLINE`` ），然后再回到 ``CPUHP_ONLINE`` 。这将模拟在 +``CPUHP_AP_ONLINE`` 之后的一个状态出现错误，从而导致回滚到在线状态。 + +所有注册的状态都被列举在 ``/sys/devices/system/cpu/hotplug/states`` :: + + $ tail /sys/devices/system/cpu/hotplug/states + 138: mm/vmscan:online + 139: mm/vmstat:online + 140: lib/percpu_cnt:online + 141: acpi/cpu-drv:online + 142: base/cacheinfo:online + 143: virtio/net:online + 144: x86/mce:online + 145: printk:online + 168: sched:active + 169: online + +要将CPU4回滚到 ``lib/percpu_cnt:online`` ，再回到在线状态，只需发出:: + + $ cat /sys/devices/system/cpu/cpu4/hotplug/state + 169 + $ echo 140 > /sys/devices/system/cpu/cpu4/hotplug/target + $ cat /sys/devices/system/cpu/cpu4/hotplug/state + 140 + +需要注意的是，状态140的清除回调已经被调用。现在重新上线:: + + $ echo 169 > /sys/devices/system/cpu/cpu4/hotplug/target + $ cat /sys/devices/system/cpu/cpu4/hotplug/state + 169 + +启用追踪事件后，单个步骤也是可见的:: + + # TASK-PID CPU# TIMESTAMP FUNCTION + # | | | | | + bash-394 [001] 22.976: cpuhp_enter: cpu: 0004 target: 140 step: 169 (cpuhp_kick_ap_work) + cpuhp/4-31 [004] 22.977: cpuhp_enter: cpu: 0004 target: 140 step: 168 (sched_cpu_deactivate) + cpuhp/4-31 [004] 22.990: cpuhp_exit: cpu: 0004 state: 168 step: 168 ret: 0 + cpuhp/4-31 [004] 22.991: cpuhp_enter: cpu: 0004 target: 140 step: 144 (mce_cpu_pre_down) + cpuhp/4-31 [004] 22.992: cpuhp_exit: cpu: 0004 state: 144 step: 144 ret: 0 + cpuhp/4-31 [004] 22.993: cpuhp_multi_enter: cpu: 0004 target: 140 step: 143 (virtnet_cpu_down_prep) + cpuhp/4-31 [004] 22.994: cpuhp_exit: cpu: 0004 state: 143 step: 143 ret: 0 + cpuhp/4-31 [004] 22.995: cpuhp_enter: cpu: 0004 target: 140 step: 142 (cacheinfo_cpu_pre_down) + cpuhp/4-31 [004] 22.996: cpuhp_exit: cpu: 0004 state: 142 step: 142 ret: 0 + bash-394 [001] 22.997: cpuhp_exit: cpu: 0004 state: 140 step: 169 ret: 0 + bash-394 [005] 95.540: cpuhp_enter: cpu: 0004 target: 169 step: 140 (cpuhp_kick_ap_work) + cpuhp/4-31 [004] 95.541: cpuhp_enter: cpu: 0004 target: 169 step: 141 (acpi_soft_cpu_online) + cpuhp/4-31 [004] 95.542: cpuhp_exit: cpu: 0004 state: 141 step: 141 ret: 0 + cpuhp/4-31 [004] 95.543: cpuhp_enter: cpu: 0004 target: 169 step: 142 (cacheinfo_cpu_online) + cpuhp/4-31 [004] 95.544: cpuhp_exit: cpu: 0004 state: 142 step: 142 ret: 0 + cpuhp/4-31 [004] 95.545: cpuhp_multi_enter: cpu: 0004 target: 169 step: 143 (virtnet_cpu_online) + cpuhp/4-31 [004] 95.546: cpuhp_exit: cpu: 0004 state: 143 step: 143 ret: 0 + cpuhp/4-31 [004] 95.547: cpuhp_enter: cpu: 0004 target: 169 step: 144 (mce_cpu_online) + cpuhp/4-31 [004] 95.548: cpuhp_exit: cpu: 0004 state: 144 step: 144 ret: 0 + cpuhp/4-31 [004] 95.549: cpuhp_enter: cpu: 0004 target: 169 step: 145 (console_cpu_notify) + cpuhp/4-31 [004] 95.550: cpuhp_exit: cpu: 0004 state: 145 step: 145 ret: 0 + cpuhp/4-31 [004] 95.551: cpuhp_enter: cpu: 0004 target: 169 step: 168 (sched_cpu_activate) + cpuhp/4-31 [004] 95.552: cpuhp_exit: cpu: 0004 state: 168 step: 168 ret: 0 + bash-394 [005] 95.553: cpuhp_exit: cpu: 0004 state: 169 step: 140 ret: 0 + +可以看到，CPU4一直下降到时间戳22.996，然后又上升到95.552。所有被调用的回调， +包括它们的返回代码都可以在跟踪中看到。 + +架构的要求 +========== + +需要具备以下功能和配置： + +``CONFIG_HOTPLUG_CPU`` + 这个配置项需要在Kconfig中启用 + +``__cpu_up()`` + 调出一个cpu的架构接口 + +``__cpu_disable()`` + 关闭CPU的架构接口，在此程序返回后，内核不能再处理任何中断。这包括定时器的关闭。 + +``__cpu_die()`` + 这实际上是为了确保CPU的死亡。实际上，看看其他架构中实现CPU热拔插的一些示例代 + 码。对于那个特定的架构，处理器被从 ``idle()`` 循环中拿下来。 ``__cpu_die()`` + 通常会等待一些per_cpu状态的设置，以确保处理器的死亡例程被调用来保持活跃。 + +用户空间通知 +============ + +在CPU成功上线或下线后，udev事件被发送。一个udev规则，比如:: + + SUBSYSTEM=="cpu", DRIVERS=="processor", DEVPATH=="/devices/system/cpu/*", RUN+="the_hotplug_receiver.sh" + +将接收所有事件。一个像这样的脚本:: + + #!/bin/sh + + if [ "${ACTION}" = "offline" ] + then + echo "CPU ${DEVPATH##*/} offline" + + elif [ "${ACTION}" = "online" ] + then + echo "CPU ${DEVPATH##*/} online" + + fi + +可以进一步处理该事件。 + +内核内联文档参考 +================ + +该API在以下内核代码中: + +include/linux/cpuhotplug.h diff --git a/Documentation/translations/zh_CN/core-api/genericirq.rst b/Documentation/translations/zh_CN/core-api/genericirq.rst new file mode 100644 index 000000000000..05ccb954c18d --- /dev/null +++ b/Documentation/translations/zh_CN/core-api/genericirq.rst @@ -0,0 +1,409 @@ +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/core-api/genericirq.rst + +:翻译: + + 司延腾 Yanteng Si <siyanteng@loongson.cn> + +:校译: + + 吴想成 Wu XiangCheng <bobwxc@email.cn> + +.. include:: <isonum.txt> + +.. _cn_core-api_genericirq: + +================ +Linux通用IRQ处理 +================ + +:版权: |copy| 2005-2010: Thomas Gleixner +:版权: |copy| 2005-2006: Ingo Molnar + +简介 +==== + +通用中断处理层是为了给设备驱动程序提供一个完整的中断处理抽象（层）。它能够处 +理所有不同类型的中断控制器硬件。设备驱动程序使用通用API函数来请求、启用、禁 +用和释放中断。驱动程序不需要知道任何关于硬件处理中断的细节，所以它们可以在不同的 +平台上使用而不需要修改代码。 + +本文档提供给那些希望在通用IRQ处理层的帮助下实现基于其架构的中断子系统的开发 +者。 + +理论依据 +======== + +Linux中中断处理的原始实现使用__do_IRQ()超级处理程序，它能够处理每种类型的 +中断逻辑。 + +最初，Russell King确定了不同类型的处理程序，以便为Linux 2.5/2.6中的ARM中 +断处理程序实现建立一个相当通用的集合。他区分了以下几种类型: + +- 电平触发型 + +- 边沿触发型 + +- 简单型 + +在实现过程中，我们发现了另一种类型: + +- 响应EOI（end of interrupt）型 + +在SMP的__do_IRQ()超级处理程序中，还需定义一种类型： + +- 每cpu型（针对CPU SMP） + +这种高层IRQ处理程序的拆分实现使我们能够为每个特定的中断类型优化中断处理的流 +程。这减少了该特定代码路径的复杂性，并允许对特定类型进行优化处理。 + +最初的通用IRQ实现使用hw_interrupt_type结构体及其 ``->ack`` ``->end`` 等回 +调来区分超级处理程序中的流控制。这导致了流逻辑和低级硬件逻辑的混合，也导致了 +不必要的代码重复：例如i386中的 ``ioapic_level_irq`` 和 ``ioapic_edge_irq`` ， +这两个IRQ类型共享许多低级的细节，但有不同的流处理。 + +一个更自然的抽象是“irq流”和“芯片细节”的干净分离。 + +分析一些架构的IRQ子系统的实现可以发现，他们中的大多数可以使用一套通用的“irq +流”方法，只需要添加芯片级的特定代码。这种分离对于那些需要IRQ流本身而不需要芯 +片细节的特定（子）架构也很有价值——以提供了一个更透明的IRQ子系统设计。 + +每个中断描述符都被分配给它自己的高层流程处理程序，这通常是一个通用的实现。(这 +种高层次的流程处理程序的实现也使得提供解复用处理程序变得简单，这可以在各种架 +构的嵌入式平台上找到。) + +这种分离使得通用中断处理层更加灵活和可扩展。例如，一个（子）架构可以使用通用 +的IRQ流实现“电平触发型”中断，并添加一个（子）架构特定的“边沿型”实现。 + +为了使向新模型的过渡更容易，并防止破坏现有实现，__do_IRQ()超级处理程序仍然 +可用。这导致了一种暂时的双重性。随着时间的推移，新的模型应该在越来越多的架构中 +被使用，因为它能使IRQ子系统更小更干净。它已经被废弃三年了，即将被删除。 + +已知的缺陷和假设 +================ + +没有（但愿如此）。 + +抽象层 +====== + +中断代码中主要有三个抽象层次: + +1. 高级别的驱动API + +2. 高级别的IRQ流处理器 + +3. 芯片级的硬件封装 + +中断控制流 +---------- + +每个中断都由一个中断描述符结构体irq_desc来描述。中断是由一个“无符号整型”的数值来 +引用的，它在描述符结构体数组中选择相应的中断描述符结构体。描述符结构体包含状态 +信息和指向中断流方法和中断芯片结构的指针，这些都是分配给这个中断的。 + +每当中断触发时，低级架构代码通过调用desc->handle_irq()调用到通用中断代码中。 +这个高层IRQ处理函数只使用由分配的芯片描述符结构体引用的desc->irq_data.chip +基元。 + +高级驱动程序API +--------------- + +高层驱动API由以下函数组成: + +- request_irq() + +- request_threaded_irq() + +- free_irq() + +- disable_irq() + +- enable_irq() + +- disable_irq_nosync() (SMP only) + +- synchronize_irq() (SMP only) + +- irq_set_irq_type() + +- irq_set_irq_wake() + +- irq_set_handler_data() + +- irq_set_chip() + +- irq_set_chip_data() + +详见自动生成的函数文档。 + +.. note:: + + 由于文档构建流程所限，中文文档中并没有引入自动生成的函数文档，所以请读者直接 + 阅读源码注释。 + +电平触发型IRQ流处理程序 +----------------------- + +通用层提供了一套预定义的irq-flow方法: + +- handle_level_irq() + +- handle_edge_irq() + +- handle_fasteoi_irq() + +- handle_simple_irq() + +- handle_percpu_irq() + +- handle_edge_eoi_irq() + +- handle_bad_irq() + +中断流处理程序（无论是预定义的还是架构特定的）由架构在启动期间或设备初始化期间分配给 +特定中断。 + +默认流实现 +~~~~~~~~~~ + +辅助函数 +^^^^^^^^ + +辅助函数调用芯片基元，并被默认流实现所使用。以下是实现的辅助函数（简化摘录）:: + + default_enable(struct irq_data *data) + { + desc->irq_data.chip->irq_unmask(data); + } + + default_disable(struct irq_data *data) + { + if (!delay_disable(data)) + desc->irq_data.chip->irq_mask(data); + } + + default_ack(struct irq_data *data) + { + chip->irq_ack(data); + } + + default_mask_ack(struct irq_data *data) + { + if (chip->irq_mask_ack) { + chip->irq_mask_ack(data); + } else { + chip->irq_mask(data); + chip->irq_ack(data); + } + } + + noop(struct irq_data *data)) + { + } + + + +默认流处理程序的实现 +~~~~~~~~~~~~~~~~~~~~ + +电平触发型IRQ流处理器 +^^^^^^^^^^^^^^^^^^^^^ + +handle_level_irq为电平触发型的中断提供了一个通用实现。 + +实现的控制流如下（简化摘录）:: + + desc->irq_data.chip->irq_mask_ack(); + handle_irq_event(desc->action); + desc->irq_data.chip->irq_unmask(); + + +默认的需回应IRQ流处理器 +^^^^^^^^^^^^^^^^^^^^^^^ + +handle_fasteoi_irq为中断提供了一个通用的实现，它只需要在处理程序的末端有一个EOI。 + +实现的控制流如下（简化摘录）:: + + handle_irq_event(desc->action); + desc->irq_data.chip->irq_eoi(); + + +默认的边沿触发型IRQ流处理器 +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +handle_edge_irq为边沿触发型的中断提供了一个通用的实现。 + +实现的控制流如下（简化摘录）:: + + if (desc->status & running) { + desc->irq_data.chip->irq_mask_ack(); + desc->status |= pending | masked; + return; + } + desc->irq_data.chip->irq_ack(); + desc->status |= running; + do { + if (desc->status & masked) + desc->irq_data.chip->irq_unmask(); + desc->status &= ~pending; + handle_irq_event(desc->action); + } while (status & pending); + desc->status &= ~running; + + +默认的简单型IRQ流处理器 +^^^^^^^^^^^^^^^^^^^^^^^ + +handle_simple_irq提供了一个简单型中断的通用实现。 + +.. note:: + + 简单型的流处理程序不调用任何处理程序/芯片基元。 + +实现的控制流程如下（简化摘录）:: + + handle_irq_event(desc->action); + + +默认的每CPU型流处理程序 +^^^^^^^^^^^^^^^^^^^^^^^ + +handle_percpu_irq为每CPU型中断提供一个通用的实现。 + +每个CPU中断只在SMP上可用，该处理程序提供了一个没有锁的简化版本。 + +以下是控制流的实现（简化摘录）:: + + if (desc->irq_data.chip->irq_ack) + desc->irq_data.chip->irq_ack(); + handle_irq_event(desc->action); + if (desc->irq_data.chip->irq_eoi) + desc->irq_data.chip->irq_eoi(); + + +EOI边沿型IRQ流处理器 +^^^^^^^^^^^^^^^^^^^^ + +handle_edge_eoi_irq提供了一个异常的边沿触发型处理程序，它只用于拯救powerpc/cell +上的一个严重失控的irq控制器。 + +坏的IRQ流处理器 +^^^^^^^^^^^^^^^ + +handle_bad_irq用于处理没有真正分配处理程序的假中断。 + +特殊性和优化 +~~~~~~~~~~~~ + +通用函数是为“干净”的架构和芯片设计的，它们没有平台特定的IRQ处理特殊性。如果一 +个架构需要在“流”的层面上实现特殊性，那么它可以通过覆盖高层的IRQ-流处理程序来实 +现。 + +延迟中断禁用 +~~~~~~~~~~~~ + +每个中断可选择的功能是由Russell King在ARM中断实现中引入的，当调用disable_irq() +时，不会在硬件层面上屏蔽中断。中断保持启用状态，而在中断事件发生时在流处理器中被 +屏蔽。这可以防止在硬件上丢失边沿中断，因为硬件上不存储边沿中断事件，而中断在硬件 +级被禁用。当一个中断在IRQ_DISABLED标志被设置时到达，那么该中断在硬件层面被屏蔽， +IRQ_PENDING位被设置。当中断被enable_irq()重新启用时，将检查挂起位，如果它被设置， +中断将通过硬件或软件重发机制重新发送。(当你想使用延迟中断禁用功能，而你的硬件又不 +能重新触发中断时，有必要启用CONFIG_HARDIRQS_SW_RESEND。) 延迟中断禁止功能是不可 +配置的。 + +芯片级硬件封装 +-------------- + +芯片级硬件描述符结构体 :c:type:`irq_chip` 包含了所有与芯片直接相关的功能，这些功 +能可以被irq流实现所利用。 + +- ``irq_ack`` + +- ``irq_mask_ack`` - 可选的，建议使用的性能 + +- ``irq_mask`` + +- ``irq_unmask`` + +- ``irq_eoi`` - 可选的，EOI流处理程序需要 + +- ``irq_retrigger`` - 可选的 + +- ``irq_set_type`` - 可选的 + +- ``irq_set_wake`` - 可选的 + +这些基元的意思是严格意义上的：ack是指ACK，masking是指对IRQ线的屏蔽，等等。这取决 +于流处理器如何使用这些基本的低级功能单元。 + +__do_IRQ入口点 +============== + +最初的实现__do_IRQ()是所有类型中断的替代入口点。它已经不存在了。 + +这个处理程序被证明不适合所有的中断硬件，因此被重新实现了边沿/级别/简单/超高速中断 +的拆分功能。这不仅是一个功能优化。它也缩短了中断的代码路径。 + +在SMP上的锁 +=========== + +芯片寄存器的锁定是由定义芯片基元的架构决定的。每个寄存器的结构通过desc->lock，由 +通用层保护。 + +通用中断芯片 +============ + +为了避免复制相同的IRQ芯片实现，核心提供了一个可配置的通用中断芯片实现。开发者在自 +己实现相同的功能之前，应该仔细检查通用芯片是否符合他们的需求，并以稍微不同的方式实 +现相同的功能。 + +该API在以下内核代码中: + +kernel/irq/generic-chip.c + +结构体 +====== + +本章包含自动生成的结构体文档，这些结构体在通用IRQ层中使用。 + +该API在以下内核代码中: + +include/linux/irq.h + +include/linux/interrupt.h + +提供的通用函数 +============== + +这一章包含了自动生成的内核API函数的文档，这些函数被导出。 + +该API在以下内核代码中: + +kernel/irq/manage.c + +kernel/irq/chip.c + +提供的内部函数 +============== + +本章包含自动生成的内部函数的文档。 + +该API在以下内核代码中: + +kernel/irq/irqdesc.c + +kernel/irq/handle.c + +kernel/irq/chip.c + +鸣谢 +==== + +感谢以下人士对本文档作出的贡献： + +1. Thomas Gleixner tglx@linutronix.de + +2. Ingo Molnar mingo@elte.hu diff --git a/Documentation/translations/zh_CN/core-api/index.rst b/Documentation/translations/zh_CN/core-api/index.rst index b4bde9396339..d5e947d8b6f1 100644 --- a/Documentation/translations/zh_CN/core-api/index.rst +++ b/Documentation/translations/zh_CN/core-api/index.rst @@ -80,14 +80,17 @@ Todolist: :maxdepth: 1 cachetlb + cpu_hotplug + genericirq + memory-hotplug + protection-keys Todolist: - cpu_hotplug memory-hotplug + cpu_hotplug genericirq - protection-keys 内存管理 diff --git a/Documentation/translations/zh_CN/core-api/memory-hotplug.rst b/Documentation/translations/zh_CN/core-api/memory-hotplug.rst new file mode 100644 index 000000000000..161f4d2c18cc --- /dev/null +++ b/Documentation/translations/zh_CN/core-api/memory-hotplug.rst @@ -0,0 +1,126 @@ +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/core-api/memory_hotplug.rst + +:翻译: + + 司延腾 Yanteng Si <siyanteng@loongson.cn> + +:校译: + + 吴想成 Wu XiangCheng <bobwxc@email.cn> + +.. _cn_core-api_memory-hotplug: + +========== +内存热插拔 +========== + +内存热拔插事件通知器 +==================== + +热插拔事件被发送到一个通知队列中。 + +在 ``include/linux/memory.h`` 中定义了六种类型的通知： + +MEM_GOING_ONLINE + 在新内存可用之前生成，以便能够为子系统处理内存做准备。页面分配器仍然无法从新 + 的内存中进行分配。 + +MEM_CANCEL_ONLINE + 如果MEM_GOING_ONLINE失败，则生成。 + +MEM_ONLINE + 当内存成功上线时产生。回调可以从新的内存中分配页面。 + +MEM_GOING_OFFLINE + 在开始对内存进行下线处理时生成。从内存中的分配不再可能，但是一些要下线的内存 + 仍然在使用。回调可以用来释放一个子系统在指定内存块中已知的内存。 + +MEM_CANCEL_OFFLINE + 如果MEM_GOING_OFFLINE失败，则生成。来自我们试图离线的内存块中的内存又可以使 + 用了。 + +MEM_OFFLINE + 在内存下线完成后生成。 + +可以通过调用如下函数来注册一个回调程序: + + hotplug_memory_notifier(callback_func, priority) + +优先级数值较高的回调函数在数值较低的回调函数之前被调用。 + +一个回调函数必须有以下原型:: + + int callback_func( + struct notifier_block *self, unsigned long action, void *arg); + +回调函数的第一个参数（self）是指向回调函数本身的通知器链块的一个指针。第二个参 +数（action）是上述的事件类型之一。第三个参数（arg）传递一个指向 +memory_notify结构体的指针:: + + struct memory_notify { + unsigned long start_pfn; + unsigned long nr_pages; + int status_change_nid_normal; + int status_change_nid_high; + int status_change_nid; + } + +- start_pfn是在线/离线内存的start_pfn。 + +- nr_pages是在线/离线内存的页数。 + +- status_change_nid_normal是当nodemask的N_NORMAL_MEMORY被设置/清除时设置节 + 点id，如果是-1，则nodemask状态不改变。 + +- status_change_nid_high是当nodemask的N_HIGH_MEMORY被设置/清除时设置的节点 + id，如果这个值为-1，那么nodemask状态不会改变。 + +- status_change_nid是当nodemask的N_MEMORY被（将）设置/清除时设置的节点id。这 + 意味着一个新的（没上线的）节点通过联机获得新的内存，而一个节点失去了所有的内 + 存。如果这个值为-1，那么nodemask的状态就不会改变。 + + 如果 status_changed_nid* >= 0，回调应该在必要时为节点创建/丢弃结构体。 + +回调程序应返回 ``include/linux/notifier.h`` 中定义的NOTIFY_DONE, NOTIFY_OK, +NOTIFY_BAD, NOTIFY_STOP中的一个值。 + +NOTIFY_DONE和NOTIFY_OK对进一步处理没有影响。 + +NOTIFY_BAD是作为对MEM_GOING_ONLINE、MEM_GOING_OFFLINE、MEM_ONLINE或MEM_OFFLINE +动作的回应，用于取消热插拔。它停止对通知队列的进一步处理。 + +NOTIFY_STOP停止对通知队列的进一步处理。 + +内部锁 +====== + +当添加/删除使用内存块设备（即普通RAM）的内存时，device_hotplug_lock应该被保持 +为: + +- 针对在线/离线请求进行同步（例如，通过sysfs）。这样一来，内存块设备只有在内存 + 被完全添加后才能被用户空间访问（.online/.state属性）。而在删除内存时，我们知 + 道没有人在临界区。 + +- 与CPU热拔插或类似操作同步（例如ACPI和PPC相关操作） + +特别是，在添加内存和用户空间试图以比预期更快的速度上线该内存时，有可能出现锁反转， +使用device_hotplug_lock可以避免此情况: + +- device_online()将首先接受device_lock()，然后是mem_hotplug_lock。 + +- add_memory_resource()将首先使用mem_hotplug_lock，然后是device_lock()（在创 + 建设备时，在bus_add_device()期间）。 + +由于在使用device_lock()之前，设备对用户空间是可见的，这可能导致锁的反转。 + +内存的上线/下线应该通过device_online()/device_offline()完成————确保它与通过 +sysfs进行的操作正确同步。建议持有device_hotplug_lock（例如，保护online_type）。 + +当添加/删除/上线/下线内存或者添加/删除异构或设备内存时，我们应该始终持有写模式的 +mem_hotplug_lock，以序列化内存热插拔（例如访问全局/区域变量）。 + +此外，mem_hotplug_lock（与device_hotplug_lock相反）在读取模式下允许一个相当 +有效的get_online_mems/put_online_mems实现，所以访问内存的代码可以防止该内存 +消失。 diff --git a/Documentation/translations/zh_CN/core-api/protection-keys.rst b/Documentation/translations/zh_CN/core-api/protection-keys.rst new file mode 100644 index 000000000000..d07830050153 --- /dev/null +++ b/Documentation/translations/zh_CN/core-api/protection-keys.rst @@ -0,0 +1,99 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/core-api/protection-keys.rst + +:翻译: + + 司延腾 Yanteng Si <siyanteng@loongson.cn> + +:校译: + + 吴想成 Wu XiangCheng <bobwxc@email.cn> + +.. _cn_core-api_protection-keys: + +============ +内存保护密钥 +============ + +用户空间的内存保护密钥（Memory Protection Keys for Userspace，PKU，亦 +即PKEYs）是英特尔Skylake（及以后）“可扩展处理器”服务器CPU上的一项功能。 +它将在未来的非服务器英特尔处理器和未来的AMD处理器中可用。 + +对于任何希望测试或使用该功能的人来说，它在亚马逊的EC2 C5实例中是可用的， +并且已知可以在那里使用Ubuntu 17.04镜像运行。 + +内存保护密钥提供了一种机制来执行基于页面的保护，但在应用程序改变保护域 +时不需要修改页表。它的工作原理是在每个页表项中为“保护密钥”分配4个以 +前被忽略的位，从而提供16个可能的密钥。 + +还有一个新的用户可访问寄存器（PKRU），为每个密钥提供两个单独的位（访 +问禁止和写入禁止）。作为一个CPU寄存器，PKRU在本质上是线程本地的，可能 +会给每个线程提供一套不同于其他线程的保护措施。 + +有两条新指令（RDPKRU/WRPKRU）用于读取和写入新的寄存器。该功能仅在64位 +模式下可用，尽管物理地址扩展页表中理论上有空间。这些权限只在数据访问上 +强制执行，对指令获取没有影响。 + + +系统调用 +======== + +有3个系统调用可以直接与pkeys进行交互:: + + int pkey_alloc(unsigned long flags, unsigned long init_access_rights) + int pkey_free(int pkey); + int pkey_mprotect(unsigned long start, size_t len, + unsigned long prot, int pkey); + +在使用一个pkey之前，必须先用pkey_alloc()分配它。一个应用程序直接调用 +WRPKRU指令，以改变一个密钥覆盖的内存的访问权限。在这个例子中，WRPKRU +被一个叫做pkey_set()的C函数所封装:: + + int real_prot = PROT_READ|PROT_WRITE; + pkey = pkey_alloc(0, PKEY_DISABLE_WRITE); + ptr = mmap(NULL, PAGE_SIZE, PROT_NONE, MAP_ANONYMOUS|MAP_PRIVATE, -1, 0); + ret = pkey_mprotect(ptr, PAGE_SIZE, real_prot, pkey); + ... application runs here + +现在，如果应用程序需要更新'ptr'处的数据，它可以获得访问权，进行更新， +然后取消其写访问权:: + + pkey_set(pkey, 0); // clear PKEY_DISABLE_WRITE + *ptr = foo; // assign something + pkey_set(pkey, PKEY_DISABLE_WRITE); // set PKEY_DISABLE_WRITE again + +现在，当它释放内存时，它也将释放pkey，因为它不再被使用了:: + + munmap(ptr, PAGE_SIZE); + pkey_free(pkey); + +.. note:: pkey_set()是RDPKRU和WRPKRU指令的一个封装器。在tools/testing/selftests/x86/protection_keys.c中可以找到一个实现实例。 + tools/testing/selftests/x86/protection_keys.c. + +行为 +==== + +内核试图使保护密钥与普通的mprotect()的行为一致。例如，如果你这样做:: + + mprotect(ptr, size, PROT_NONE); + something(ptr); + +这样做的时候，你可以期待保护密钥的相同效果:: + + pkey = pkey_alloc(0, PKEY_DISABLE_WRITE | PKEY_DISABLE_READ); + pkey_mprotect(ptr, size, PROT_READ|PROT_WRITE, pkey); + something(ptr); + +无论something()是否是对'ptr'的直接访问，这都应该为真。 +如:: + + *ptr = foo; + +或者当内核代表应用程序进行访问时，比如read():: + + read(fd, ptr, 1); + +在这两种情况下，内核都会发送一个SIGSEGV，但当违反保护密钥时，si_code +将被设置为SEGV_PKERR，而当违反普通的mprotect()权限时，则是SEGV_ACCERR。 diff --git a/Documentation/translations/zh_CN/dev-tools/index.rst b/Documentation/translations/zh_CN/dev-tools/index.rst index e6c99f2f543f..0f770b8664e9 100644 --- a/Documentation/translations/zh_CN/dev-tools/index.rst +++ b/Documentation/translations/zh_CN/dev-tools/index.rst @@ -11,6 +11,9 @@ 目前这些文档已经整理在一起，不需要再花费额外的精力。 欢迎任何补丁。 +有关测试专用工具的简要概述，参见 +Documentation/translations/zh_CN/dev-tools/testing-overview.rst + .. class:: toc-title 目录 @@ -18,6 +21,7 @@ .. toctree:: :maxdepth: 2 + testing-overview gcov kasan @@ -29,6 +33,7 @@ Todolist: - ubsan - kmemleak - kcsan + - kfence - gdb-kernel-debugging - kgdb - kselftest diff --git a/Documentation/translations/zh_CN/dev-tools/testing-overview.rst b/Documentation/translations/zh_CN/dev-tools/testing-overview.rst new file mode 100644 index 000000000000..b7a1d13da6c6 --- /dev/null +++ b/Documentation/translations/zh_CN/dev-tools/testing-overview.rst @@ -0,0 +1,109 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/dev-tools/testing-overview.rst +:Translator: 胡皓文 Hu Haowen <src.res@email.cn> + +============ +内核测试指南 +============ + +有许多不同的工具可以用于测试Linux内核，因此了解什么时候使用它们可能 +很困难。本文档粗略概述了它们之间的区别，并阐释了它们是怎样糅合在一起 +的。 + +编写和运行测试 +============== + +大多数内核测试都是用kselftest或KUnit框架之一编写的。它们都让运行测试 +更加简化，并为编写新测试提供帮助。 + +如果你想验证内核的行为——尤其是内核的特定部分——那你就要使用kUnit或 +kselftest。 + +KUnit和kselftest的区别 +---------------------- + +.. note:: + 由于本文段中部分术语尚无较好的对应中文释义，可能导致与原文含义 + 存在些许差异，因此建议读者结合原文 + （Documentation/dev-tools/testing-overview.rst）辅助阅读。 + 如对部分翻译有异议或有更好的翻译意见，欢迎联系译者进行修订。 + +KUnit（Documentation/dev-tools/kunit/index.rst）是用于“白箱”测 +试的一个完整的内核内部系统：因为测试代码是内核的一部分，所以它能够访 +问用户空间不能访问到的内部结构和功能。 + +因此，KUnit测试最好针对内核中较小的、自包含的部分，以便能够独立地测 +试。“单元”测试的概念亦是如此。 + +比如，一个KUnit测试可能测试一个单独的内核功能（甚至通过一个函数测试 +一个单一的代码路径，例如一个错误处理案例），而不是整个地测试一个特性。 + +这也使得KUnit测试构建和运行非常地快，从而能够作为开发流程的一部分被 +频繁地运行。 + +有关更详细的介绍，请参阅KUnit测试代码风格指南 +Documentation/dev-tools/kunit/style.rst + +kselftest（Documentation/dev-tools/kselftest.rst），相对来说，大量用 +于用户空间，并且通常测试用户空间的脚本或程序。 + +这使得编写复杂的测试，或者需要操作更多全局系统状态的测试更加容易（诸 +如生成进程之类）。然而，从kselftest直接调用内核函数是不行的。这也就 +意味着只有通过某种方式（如系统调用、驱动设备、文件系统等）导出到了用 +户空间的内核功能才能使用kselftest来测试。为此，有些测试包含了一个伴 +生的内核模块用于导出更多的信息和功能。不过，对于基本上或者完全在内核 +中运行的测试，KUnit可能是更佳工具。 + +kselftest也因此非常适合于全部功能的测试，因为这些功能会将接口暴露到 +用户空间，从而能够被测试，而不是展现实现细节。“system”测试和 +“end-to-end”测试亦是如此。 + +比如，一个新的系统调用应该伴随有新的kselftest测试。 + +代码覆盖率工具 +============== + +支持两种不同代码之间的覆盖率测量工具。它们可以用来验证一项测试执行的 +确切函数或代码行。这有助于决定内核被测试了多少，或用来查找合适的测试 +中没有覆盖到的极端情况。 + +Documentation/translations/zh_CN/dev-tools/gcov.rst 是GCC的覆盖率测试 +工具，能用于获取内核的全局或每个模块的覆盖率。与KCOV不同的是，这个工具 +不记录每个任务的覆盖率。覆盖率数据可以通过debugfs读取，并通过常规的 +gcov工具进行解释。 + +Documentation/dev-tools/kcov.rst 是能够构建在内核之中，用于在每个任务 +的层面捕捉覆盖率的一个功能。因此，它对于模糊测试和关于代码执行期间信 +息的其它情况非常有用，比如在一个单一系统调用里使用它就很有用。 + +动态分析工具 +============ + +内核也支持许多动态分析工具，用以检测正在运行的内核中出现的多种类型的 +问题。这些工具通常每个去寻找一类不同的缺陷，比如非法内存访问，数据竞 +争等并发问题，或整型溢出等其他未定义行为。 + +如下所示： + +* kmemleak检测可能的内存泄漏。参阅 + Documentation/dev-tools/kmemleak.rst +* KASAN检测非法内存访问，如数组越界和释放后重用（UAF）。参阅 + Documentation/dev-tools/kasan.rst +* UBSAN检测C标准中未定义的行为，如整型溢出。参阅 + Documentation/dev-tools/ubsan.rst +* KCSAN检测数据竞争。参阅 Documentation/dev-tools/kcsan.rst +* KFENCE是一个低开销的内存问题检测器，比KASAN更快且能被用于批量构建。 + 参阅 Documentation/dev-tools/kfence.rst +* lockdep是一个锁定正确性检测器。参阅 + Documentation/locking/lockdep-design.rst +* 除此以外，在内核中还有一些其它的调试工具，大多数能在 + lib/Kconfig.debug 中找到。 + +这些工具倾向于对内核进行整体测试，并且不像kselftest和KUnit一样“传递”。 +它们可以通过在启用这些工具时运行内核测试以与kselftest或KUnit结合起来： +之后你就能确保这些错误在测试过程中都不会发生了。 + +一些工具与KUnit和kselftest集成，并且在检测到问题时会自动打断测试。 diff --git a/Documentation/translations/zh_CN/index.rst b/Documentation/translations/zh_CN/index.rst index 1f953d3439a5..a34e58733ac8 100644 --- a/Documentation/translations/zh_CN/index.rst +++ b/Documentation/translations/zh_CN/index.rst @@ -5,6 +5,7 @@ \renewcommand\thesection* \renewcommand\thesubsection* \kerneldocCJKon + \kerneldocBeginSC .. _linux_doc_zh: @@ -17,6 +18,11 @@ **翻译计划:** 内核中文文档欢迎任何翻译投稿，特别是关于内核用户和管理员指南部分。 +这是中文内核文档树的顶级目录。内核文档，就像内核本身一样，在很大程度上是一 +项正在进行的工作；当我们努力将许多分散的文件整合成一个连贯的整体时尤其如此。 +另外，随时欢迎您对内核文档进行改进；如果您想提供帮助，请加入vger.kernel.org +上的linux-doc邮件列表。 + 许可证文档 ---------- @@ -97,12 +103,14 @@ TODOList: iio/index sound/index filesystems/index + virt/index + infiniband/index + accounting/index TODOList: * driver-api/index * locking/index -* accounting/index * block/index * cdrom/index * ide/index @@ -111,7 +119,6 @@ TODOList: * hid/index * i2c/index * isdn/index -* infiniband/index * leds/index * netlabel/index * networking/index @@ -122,7 +129,6 @@ TODOList: * spi/index * w1/index * watchdog/index -* virt/index * input/index * hwmon/index * gpu/index @@ -184,3 +190,7 @@ TODOList: ---------- * :ref:`genindex` + +.. raw:: latex + + \kerneldocEndSC diff --git a/Documentation/translations/zh_CN/infiniband/core_locking.rst b/Documentation/translations/zh_CN/infiniband/core_locking.rst new file mode 100644 index 000000000000..42f08038d44b --- /dev/null +++ b/Documentation/translations/zh_CN/infiniband/core_locking.rst @@ -0,0 +1,115 @@ + +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/infiniband/core_locking.rst + +:翻译: + + 司延腾 Yanteng Si <siyanteng@loongson.cn> + +:校译: + + 王普宇 Puyu Wang <realpuyuwang@gmail.com> + 时奎亮 Alex Shi <alexs@kernel.org> + +.. _cn_infiniband_core_locking: + +================== +infiniband中间层锁 +================== + + 本指南试图明确infiniband中间层的锁假设。它描述了对位于中间层以下的低 + 级驱动程序和使用中间层的上层协议的要求。 + +睡眠和中断环境 +============== + + 除了以下异常情况，ib_device结构体中所有方法的低级驱动实现都可以睡眠。 + 这些异常情况是列表中的任意的方法: + + - create_ah + - modify_ah + - query_ah + - destroy_ah + - post_send + - post_recv + - poll_cq + - req_notify_cq + + 他们可能不可以睡眠，而且必须可以从任何上下文中调用。 + + 向上层协议使用者输出的相应函数: + + - rdma_create_ah + - rdma_modify_ah + - rdma_query_ah + - rdma_destroy_ah + - ib_post_send + - ib_post_recv + - ib_req_notify_cq + + 因此，在任何情况下都可以安全调用（它们）。 + + 此外，该函数 + + - ib_dispatch_event + + 被底层驱动用来通过中间层调度异步事件的“A”，也可以从任何上下文中安全调 + 用。 + +可重入性 +-------- + + 由低级驱动程序导出的ib_device结构体中的所有方法必须是完全可重入的。 + 即使使用同一对象的多个函数调用被同时运行，低级驱动程序也需要执行所有 + 必要的同步以保持一致性。 + + IB中间层不执行任何函数调用的序列化。 + + 因为低级驱动程序是可重入的，所以不要求上层协议使用者任何顺序执行。然 + 而，为了得到合理的结果，可能需要一些顺序。例如，一个使用者可以在多个 + CPU上同时安全地调用ib_poll_cq()。然而，不同的ib_poll_cq()调用之间 + 的工作完成信息的顺序没有被定义。 + +回调 +---- + + 低级驱动程序不得直接从与ib_device方法调用相同的调用链中执行回调。例 + 如，低级驱动程序不允许从post_send方法直接调用使用者的完成事件处理程 + 序。相反，低级驱动程序应该推迟这个回调，例如，调度一个tasklet来执行 + 这个回调。 + + 低层驱动负责确保同一CQ的多个完成事件处理程序不被同时调用。驱动程序必 + 须保证一个给定的CQ的事件处理程序在同一时间只有一个在运行。换句话说， + 以下情况是不允许的:: + + CPU1 CPU2 + + low-level driver -> + consumer CQ event callback: + /* ... */ + ib_req_notify_cq(cq, ...); + low-level driver -> + /* ... */ consumer CQ event callback: + /* ... */ + return from CQ event handler + + 完成事件和异步事件回调的运行环境没有被定义。 根据低级别的驱动程序，它可能是 + 进程上下文、softirq上下文或中断上下文。上层协议使用者可能不会在回调中睡眠。 + +热插拔 +------ + + 当一个低级驱动程序调用ib_register_device()时，它宣布一个设备已经 + 准备好供使用者使用，所有的初始化必须在这个调用之前完成。设备必须保 + 持可用，直到驱动对ib_unregister_device()的调用返回。 + + 低级驱动程序必须从进程上下文调用ib_register_device()和 + ib_unregister_device()。如果使用者在这些调用中回调到驱动程序，它 + 不能持有任何可能导致死锁的semaphores。 + + 一旦其结构体ib_client的add方法被调用，上层协议使用者就可以开始使用 + 一个IB设备。使用者必须在从移除方法返回之前完成所有的清理工作并释放 + 与设备相关的所有资源。 + + 使用者被允许在其添加和删除方法中睡眠。 diff --git a/Documentation/translations/zh_CN/infiniband/index.rst b/Documentation/translations/zh_CN/infiniband/index.rst new file mode 100644 index 000000000000..5634cc48379f --- /dev/null +++ b/Documentation/translations/zh_CN/infiniband/index.rst @@ -0,0 +1,40 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/infiniband/index.rst + +:翻译: + + 司延腾 Yanteng Si <siyanteng@loongson.cn> + +:校译: + + 王普宇 Puyu Wang <realpuyuwang@gmail.com> + 时奎亮 Alex Shi <alexs@kernel.org> + +.. _cn_infiniband_index: + +========== +infiniband +========== + +.. toctree:: + :maxdepth: 1 + + core_locking + ipoib + opa_vnic + sysfs + tag_matching + user_mad + user_verbs + + + +.. only:: subproject and html + + Indices + ======= + + * :ref:`genindex` diff --git a/Documentation/translations/zh_CN/infiniband/ipoib.rst b/Documentation/translations/zh_CN/infiniband/ipoib.rst new file mode 100644 index 000000000000..56517ea5fe9d --- /dev/null +++ b/Documentation/translations/zh_CN/infiniband/ipoib.rst @@ -0,0 +1,111 @@ +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/infiniband/ipoib.rst + +:翻译: + + 司延腾 Yanteng Si <siyanteng@loongson.cn> + +:校译: + + 王普宇 Puyu Wang <realpuyuwang@gmail.com> + 时奎亮 Alex Shi <alexs@kernel.org> + +.. _cn_infiniband_ipoib: + +========================= +infiniband上的IP（IPoIB） +========================= + + ib_ipoib驱动是IETF ipoib工作组发布的RFC 4391和4392所规定的 + infiniband上IP协议的一个实现。它是一个“本地”实现，即把接口类型设置为 + ARPHRD_INFINIBAND，硬件地址长度为20（早期的专有实现向内核伪装为以太网 + 接口）。 + +分区和P_Keys +============ + + 当IPoIB驱动被加载时，它会使用索引为0的P_Key给每个端口创建一个接口。要用 + 不同的P_Key创建一个接口，将所需的P_Key写入主接口的 + /sys/class/net/<intf name>/create_child文件里面。比如说:: + + echo 0x8001 > /sys/class/net/ib0/create_child + + 这将用P_Key 0x8001创建一个名为ib0.8001的接口。要删除一个子接口，使用 + ``delete_child`` 文件:: + + echo 0x8001 > /sys/class/net/ib0/delete_child + + 任何接口的P_Key都由“pkey”文件给出，而子接口的主接口在“parent”中。 + + 子接口的创建/删除也可以使用IPoIB的rtnl_link_ops来完成，使用两种 + 方式创建的子接口的行为是一样的。 + +数据报与连接模式 +================ + + IPoIB驱动支持两种操作模式：数据报和连接。模式是通过接口的 + /sys/class/net/<intf name>/mode文件设置和读取的。 + + 在数据报模式下，使用IB UD（不可靠数据报）传输，因此接口MTU等于IB L2 MTU + 减去IPoIB封装头（4字节）。例如，在一个典型的具有2K MTU的IB结构中，IPoIB + MTU将是2048 - 4 = 2044字节。 + + 在连接模式下，使用IB RC（可靠的连接）传输。连接模式利用IB传输的连接特性， + 允许MTU达到最大的IP包大小64K，这减少了处理大型UDP数据包、TCP段等所需的 + IP包数量，提高了大型信息的性能。 + + 在连接模式下，接口的UD QP仍被用于组播和与不支持连接模式的对等体的通信。 + 在这种情况下，ICMP PMTU数据包的RX仿真被用来使网络堆栈对这些邻居使用较 + 小的UD MTU。 + +无状态卸载 +========== + + 如果IB HW支持IPoIB无状态卸载，IPoIB会向网络堆栈广播TCP/IP校验和/或大量 + 传送（LSO）负载转移能力。 + + 大量传送（LSO）负载转移也已实现，可以使用ethtool调用打开/关闭。目前，LRO + 只支持具有校验和卸载能力的设备。 + + 无状态卸载只在数据报模式下支持。 + +中断管理 +======== + + 如果底层IB设备支持CQ事件管理，可以使用ethtool来设置中断缓解参数，从而减少 + 处理中断产生的开销。IPoIB的主要代码路径不使用TX完成信号的事件，所以只支持 + RX管理。 + +调试信息 +======== + + 通过将CONFIG_INFINIBAND_IPOIB_DEBUG设置为“y”来编译IPoIB驱动，跟踪信 + 息被编译到驱动中。通过将模块参数debug_level和mcast_debug_level设置为1来 + 打开它们。这些参数可以在运行时通过/sys/module/ib_ipoib/的文件来控制。 + + CONFIG_INFINIBAND_IPOIB_DEBUG也启用debugfs虚拟文件系统中的文件。通过挂 + 载这个文件系统，例如用:: + + mount -t debugfs none /sys/kernel/debug + + 可以从/sys/kernel/debug/ipoib/ib0_mcg等文件中获得关于多播组的统计数据。 + + 这个选项对性能的影响可以忽略不计，所以在正常运行时，在debug_level设置为 + 0的情况下启用这个选项是安全的。 + + CONFIG_INFINIBAND_IPOIB_DEBUG_DATA当data_debug_level设置为1时，可以 + 在数据路径中启用更多的调试输出。 然而，即使禁用输出，启用这个配置选项也 + 会影响性能，因为它在快速路径中增加了测试。 + +引用 +==== + + 在InfiniBand上传输IP（IPoIB）（RFC 4391）。 + http://ietf.org/rfc/rfc4391.txt + + infiniband上的IP:上的IP架构（RFC 4392）。 + http://ietf.org/rfc/rfc4392.txt + + infiniband上的IP: 连接模式 (RFC 4755) + http://ietf.org/rfc/rfc4755.txt diff --git a/Documentation/translations/zh_CN/infiniband/opa_vnic.rst b/Documentation/translations/zh_CN/infiniband/opa_vnic.rst new file mode 100644 index 000000000000..12b147fbf792 --- /dev/null +++ b/Documentation/translations/zh_CN/infiniband/opa_vnic.rst @@ -0,0 +1,156 @@ +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/infiniband/opa_vnic.rst + +:翻译: + + 司延腾 Yanteng Si <siyanteng@loongson.cn> + +:校译: + + 王普宇 Puyu Wang <realpuyuwang@gmail.com> + 时奎亮 Alex Shi <alexs@kernel.org> + +.. _cn_infiniband_opa_vnic: + +============================================= +英特尔全路径（OPA）虚拟网络接口控制器（VNIC） +============================================= + +英特尔全路径（OPA）虚拟网络接口控制器（VNIC）功能通过封装HFI节点之间的以 +太网数据包，支持Omni-Path结构上的以太网功能。 + +体系结构 +======== + +Omni-Path封装的以太网数据包的交换模式涉及Omni-Path结构拓扑上覆盖的一个或 +多个虚拟以太网交换机。Omni-Path结构上的HFI节点的一个子集被允许在特定的虚 +拟以太网交换机上交换封装的以太网数据包。虚拟以太网交换机是通过配置结构上的 +HFI节点实现的逻辑抽象，用于生成和处理报头。在最简单的配置中，整个结构的所有 +HFI节点通过一个虚拟以太网交换机交换封装的以太网数据包。一个虚拟以太网交换机， +实际上是一个独立的以太网网络。该配置由以太网管理器（EM）执行，它是可信的结 +构管理器（FM）应用程序的一部分。HFI节点可以有多个VNIC，每个连接到不同的虚 +拟以太网交换机。下图介绍了两个虚拟以太网交换机与两个HFI节点的情况:: + + +-------------------+ + | 子网/ | + | 以太网 | + | 管理 | + +-------------------+ + / / + / / + / / + / / + +-----------------------------+ +------------------------------+ + | 虚拟以太网切换 | | 虚拟以太网切换 | + | +---------+ +---------+ | | +---------+ +---------+ | + | | VPORT | | VPORT | | | | VPORT | | VPORT | | + +--+---------+----+---------+-+ +-+---------+----+---------+---+ + | \ / | + | \ / | + | \/ | + | / \ | + | / \ | + +-----------+------------+ +-----------+------------+ + | VNIC | VNIC | | VNIC | VNIC | + +-----------+------------+ +-----------+------------+ + | HFI | | HFI | + +------------------------+ +------------------------+ + + +Omni-Path封装的以太网数据包格式如下所述。 + +==================== ================================ +位 域 +==================== ================================ +Quad Word 0: +0-19 SLID (低20位) +20-30 长度 (以四字为单位) +31 BECN 位 +32-51 DLID (低20位) +52-56 SC (服务级别) +57-59 RC (路由控制) +60 FECN 位 +61-62 L2 (=10, 16B 格式) +63 LT (=1, 链路传输头 Flit) + +Quad Word 1: +0-7 L4 type (=0x78 ETHERNET) +8-11 SLID[23:20] +12-15 DLID[23:20] +16-31 PKEY +32-47 熵 +48-63 保留 + +Quad Word 2: +0-15 保留 +16-31 L4 头 +32-63 以太网数据包 + +Quad Words 3 to N-1: +0-63 以太网数据包 (pad拓展) + +Quad Word N (last): +0-23 以太网数据包 (pad拓展) +24-55 ICRC +56-61 尾 +62-63 LT (=01, 链路传输尾 Flit) +==================== ================================ + +以太网数据包在传输端被填充，以确保VNIC OPA数据包是四字对齐的。“尾”字段 +包含填充的字节数。在接收端，“尾”字段被读取，在将数据包向上传递到网络堆 +栈之前，填充物被移除（与ICRC、尾和OPA头一起）。 + +L4头字段包含VNIC端口所属的虚拟以太网交换机ID。在接收端，该字段用于将收 +到的VNIC数据包去多路复用到不同的VNIC端口。 + +驱动设计 +======== + +英特尔OPA VNIC的软件设计如下图所示。OPA VNIC功能有一个依赖于硬件的部分 +和一个独立于硬件的部分。 + +对IB设备分配和释放RDMA netdev设备的支持已经被加入。RDMA netdev支持与 +网络堆栈的对接，从而创建标准的网络接口。OPA_VNIC是一个RDMA netdev设备 +类型。 + +依赖于HW的VNIC功能是HFI1驱动的一部分。它实现了分配和释放OPA_VNIC RDMA +netdev的动作。它涉及VNIC功能的HW资源分配/管理。它与网络堆栈接口并实现所 +需的net_device_ops功能。它在传输路径中期待Omni-Path封装的以太网数据包， +并提供对它们的HW访问。在将数据包向上传递到网络堆栈之前，它把Omni-Path头 +从接收的数据包中剥离。它还实现了RDMA netdev控制操作。 + +OPA VNIC模块实现了独立于硬件的VNIC功能。它由两部分组成。VNIC以太网管理 +代理（VEMA）作为一个IB客户端向IB核心注册，并与IB MAD栈接口。它与以太网 +管理器（EM）和VNIC netdev交换管理信息。VNIC netdev部分分配和释放OPA_VNIC +RDMA netdev设备。它在需要时覆盖由依赖HW的VNIC驱动设置的net_device_ops函数， +以适应任何控制操作。它还处理以太网数据包的封装，在传输路径中使用Omni-Path头。 +对于每个VNIC接口，封装所需的信息是由EM通过VEMA MAD接口配置的。它还通过调用 +RDMA netdev控制操作将任何控制信息传递给依赖于HW的驱动程序:: + + +-------------------+ +----------------------+ + | | | Linux | + | IB MAD | | 网络 | + | | | 栈 | + +-------------------+ +----------------------+ + | | | + | | | + +----------------------------+ | + | | | + | OPA VNIC 模块 | | + | (OPA VNIC RDMA Netdev | | + | & EMA 函数) | | + | | | + +----------------------------+ | + | | + | | + +------------------+ | + | IB 核心 | | + +------------------+ | + | | + | | + +--------------------------------------------+ + | | + | HFI1 驱动和 VNIC 支持 | + | | + +--------------------------------------------+ diff --git a/Documentation/translations/zh_CN/infiniband/sysfs.rst b/Documentation/translations/zh_CN/infiniband/sysfs.rst new file mode 100644 index 000000000000..e9a48b0b2ba6 --- /dev/null +++ b/Documentation/translations/zh_CN/infiniband/sysfs.rst @@ -0,0 +1,21 @@ +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/infiniband/sysfs.rst + +:翻译: + + 司延腾 Yanteng Si <siyanteng@loongson.cn> + +:校译: + + 王普宇 Puyu Wang <realpuyuwang@gmail.com> + 时奎亮 Alex Shi <alexs@kernel.org> + +.. _cn_infiniband_sysfs: + +========= +Sysfs文件 +========= + +sysfs接口已移至 +Documentation/ABI/stable/sysfs-class-infiniband. diff --git a/Documentation/translations/zh_CN/infiniband/tag_matching.rst b/Documentation/translations/zh_CN/infiniband/tag_matching.rst new file mode 100644 index 000000000000..19b99587b862 --- /dev/null +++ b/Documentation/translations/zh_CN/infiniband/tag_matching.rst @@ -0,0 +1,63 @@ +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/infiniband/tag_matching.rst + +:翻译: + + 司延腾 Yanteng Si <siyanteng@loongson.cn> + +:校译: + + 王普宇 Puyu Wang <realpuyuwang@gmail.com> + 时奎亮 Alex Shi <alexs@kernel.org> + +.. _cn_infiniband_tag_matching: + +============ +标签匹配逻辑 +============ + +MPI标准定义了一套规则，称为标签匹配，用于将源发送操作与目的接收匹配。以下参数必 +须与以下源和目的参数相匹配: + +* 沟通者 +* 用户标签--通配符(wild card)可由接收方指定 +* 来源等级--通配符可由接收方指定 +* 目的地等级 – wild + +排序规则要求，当一对以上的发送和接收消息信封可能匹配时，包括最早发布-发送和最早 +发布-接收的一对是必须用来满足匹配操作的一对。然而，这并不意味着标签是按照它们被 +创建的顺序消耗的，例如，如果早期的标签不能用来满足匹配规则，那么后来生成的标签 +可能被消耗。 + +当消息从发送方发送到接收方时，通信库可能试图在相应的匹配接收被发布之后或之前处 +理该操作。如果匹配的接收被发布，这就是一个预期的消息，否则就被称为一个意外的消 +息。实现时经常为这两种不同的匹配实例使用不同的匹配方案。 + +为了减少MPI库的内存占用，MPI实现通常使用两种不同的协议来实现这一目的: + +1. Eager协议--当发送方处理完发送时，完整的信息就会被发送。在send_cq中会收到 +一个完成发送的通知，通知缓冲区可以被重新使用。 + +2. Rendezvous协议--发送方在第一次通知接收方时发送标签匹配头，也许还有一部分 +数据。当相应的缓冲区被发布时，响应者将使用头中的信息，直接向匹配的缓冲区发起 +RDMA读取操作。为了使缓冲区得到重用，需要收到一个fin消息。 + +标签匹配的实现 +============== + +使用的匹配对象有两种类型，即发布的接收列表和意外消息列表。应用程序通过调用发布 +的接收列表中的MPI接收例程发布接收缓冲区，并使用MPI发送例程发布发送消息。发布的 +接收列表的头部可以由硬件来维护，而软件则要对这个列表进行跟踪。 + +当发送开始并到达接收端时，如果没有为这个到达的消息预先发布接收，它将被传递给软 +件并被放在意外（unexpect）消息列表中。否则，将对该匹配进行处理，包括交会处理， +如果合适的话，将数据传送到指定的接收缓冲区。这允许接收方MPI标签匹配与计算重叠。 + +当一个接收信息被发布时，通信库将首先检查软件的意外信息列表，以寻找一个匹配的接 +收信息。如果找到一个匹配的，数据就会被送到用户缓冲区，使用一个软件控制的协议。 +UCX的实现根据数据大小，使用急切或交会协议。如果没有找到匹配，整个预置的接收列 +表由硬件维护，并且有空间在这个列表中增加一个预置的接收，这个接收被传递给硬件。 +软件要对这个列表进行跟踪，以帮助处理MPI取消操作。此外，由于硬件和软件在标签匹 +配操作方面预计不会紧密同步，这个影子列表被用来检测预先发布的接收被传递到硬件的 +情况，因为匹配的意外消息正在从硬件传递到软件。 diff --git a/Documentation/translations/zh_CN/infiniband/user_mad.rst b/Documentation/translations/zh_CN/infiniband/user_mad.rst new file mode 100644 index 000000000000..d9ab2edfb559 --- /dev/null +++ b/Documentation/translations/zh_CN/infiniband/user_mad.rst @@ -0,0 +1,164 @@ +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/infiniband/user_mad.rst + +:翻译: + + 司延腾 Yanteng Si <siyanteng@loongson.cn> + +:校译: + + 王普宇 Puyu Wang <realpuyuwang@gmail.com> + 时奎亮 Alex Shi <alexs@kernel.org> + +.. _cn_infiniband_user_mad: + +=============== +用户空间MAD访问 +=============== + +设备文件 +======== + + 每个InfiniBand设备的每个端口都有一个“umad”设备和一个“issm”设备连接。 + 例如，一个双端口的HCA将有两个umad设备和两个issm设备，而一个交换机将 + 有每个类型的一个设备（对于交换机端口0）。 + +创建MAD代理 +=========== + + 一个MAD代理可以通过填写一个结构体ib_user_mad_reg_req来创建，然后在 + 适当的设备文件的文件描述符上调用IB_USER_MAD_REGISTER_AGENT ioctl。 + 如果注册请求成功，结构体中会返回一个32位的ID。比如说:: + + struct ib_user_mad_reg_req req = { /* ... */ }; + ret = ioctl(fd, IB_USER_MAD_REGISTER_AGENT, (char *) &req); + if (!ret) + my_agent = req.id; + else + perror("agent register"); + + 代理可以通过IB_USER_MAD_UNREGISTER_AGENT ioctl取消注册。另外，所有 + 通过文件描述符注册的代理在描述符关闭时将被取消注册。 + + 2014 + 现在提供了一个新的注册IOctl，允许在注册时提供额外的字段。这个注册 + 调用的用户隐含了对pkey_index的使用（见下文）。现在提供了一个新的 + 注册IOctl，允许在注册时提供额外的字段。这个注册调用的用户隐含了对 + pkey_index的使用（见下文）。 + +接收MADs +======== + + 使用read()接收MAD。现在接收端支持RMPP。传给read()的缓冲区必须至少是 + 一个struct ib_user_mad + 256字节。比如说: + + 如果传递的缓冲区不足以容纳收到的MAD（RMPP），errno被设置为ENOSPC，需 + 要的缓冲区长度被设置在mad.length中。 + + 正常MAD(非RMPP)的读取示例:: + + struct ib_user_mad *mad; + mad = malloc(sizeof *mad + 256); + ret = read(fd, mad, sizeof *mad + 256); + if (ret != sizeof mad + 256) { + perror("read"); + free(mad); + } + + RMPP读取示例:: + + struct ib_user_mad *mad; + mad = malloc(sizeof *mad + 256); + ret = read(fd, mad, sizeof *mad + 256); + if (ret == -ENOSPC)) { + length = mad.length; + free(mad); + mad = malloc(sizeof *mad + length); + ret = read(fd, mad, sizeof *mad + length); + } + if (ret < 0) { + perror("read"); + free(mad); + } + + 除了实际的MAD内容外，其他结构体ib_user_mad字段将被填入收到的MAD的信 + 息。例如，远程LID将在mad.lid中。 + + 如果发送超时，将产生一个接收，mad.status设置为ETIMEDOUT。否则，当一个 + MAD被成功接收后，mad.status将是0。 + + poll()/select()可以用来等待一个MAD可以被读取。 + + poll()/select()可以用来等待，直到可以读取一个MAD。 + +发送MADs +======== + + MADs是用write()发送的。发送的代理ID应该填入MAD的id字段，目的地LID应该 + 填入lid字段，以此类推。发送端确实支持RMPP，所以可以发送任意长度的MAD。 + 比如说:: + + struct ib_user_mad *mad; + + mad = malloc(sizeof *mad + mad_length); + + /* fill in mad->data */ + + mad->hdr.id = my_agent; /* req.id from agent registration */ + mad->hdr.lid = my_dest; /* in network byte order... */ + /* etc. */ + + ret = write(fd, &mad, sizeof *mad + mad_length); + if (ret != sizeof *mad + mad_length) + perror("write"); + +交换IDs +======= + + umad设备的用户可以在发送的MAD中使用交换ID字段的低32位（也就是网络字节顺序中 + 最小有效的一半字段）来匹配请求/响应对。上面的32位是保留给内核使用的，在发送 + MAD之前会被改写。 + +P_Key索引处理 +============= + + 旧的ib_umad接口不允许为发送的MAD设置P_Key索引，也没有提供获取接收的MAD的 + P_Key索引的方法。一个带有pkey_index成员的struct ib_user_mad_hdr的新布局已 + 经被定义；然而，为了保持与旧的应用程序的二进制兼容性，除非在文件描述符被用于 + 其他用途之前调用IB_USER_MAD_ENABLE_PKEY或IB_USER_MAD_REGISTER_AGENT2 ioctl + 之一，否则不会使用这种新布局。 + + 在2008年9月，IB_USER_MAD_ABI_VERSION将被增加到6，默认使用新的ib_user_mad_hdr + 结构布局，并且IB_USER_MAD_ENABLE_PKEY ioctl将被删除。 + +设置IsSM功能位 +============== + + 要为一个端口设置IsSM功能位，只需打开相应的issm设备文件。如果IsSM位已经被设置，那 + 么打开调用将阻塞，直到该位被清除（或者如果O_NONBLOCK标志被传递给open()，则立即返 + 回，errno设置为EAGAIN）。当issm文件被关闭时，IsSM位将被清除。在issm文件上不能进 + 行任何读、写或其他操作。 + +/dev文件 +======== + +为了用 udev自动创建相应的字符设备文件，一个类似:: + + KERNEL=="umad*", NAME="infiniband/%k" + KERNEL=="issm*", NAME="infiniband/%k" + + 的规则可以被使用。它将创建节点的名字:: + + /dev/infiniband/umad0 + /dev/infiniband/issm0 + + 为第一个端口，以此类推。与这些设备相关的infiniband设备和端口可以从以下文件中确定:: + + /sys/class/infiniband_mad/umad0/ibdev + /sys/class/infiniband_mad/umad0/port + + 和:: + + /sys/class/infiniband_mad/issm0/ibdev + /sys/class/infiniband_mad/issm0/port diff --git a/Documentation/translations/zh_CN/infiniband/user_verbs.rst b/Documentation/translations/zh_CN/infiniband/user_verbs.rst new file mode 100644 index 000000000000..970bc1a4e396 --- /dev/null +++ b/Documentation/translations/zh_CN/infiniband/user_verbs.rst @@ -0,0 +1,72 @@ +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/infiniband/user_verbs.rst + +:翻译: + + 司延腾 Yanteng Si <siyanteng@loongson.cn> + +:校译: + + 王普宇 Puyu Wang <realpuyuwang@gmail.com> + 时奎亮 Alex Shi <alexs@kernel.org> + +.. _cn_infiniband_user_verbs: + +================= +用户空间verbs访问 +================= + + ib_uverbs模块，通过启用CONFIG_INFINIBAND_USER_VERBS构建，使用户空间 + 通过“verbs”直接访问IB硬件，如InfiniBand架构规范第11章所述。 + + 要使用verbs，需要libibverbs库，可从https://github.com/linux-rdma/rdma-core。 + libibverbs包含一个独立于设备的API，用于使用ib_uverbs接口。libibverbs + 还需要为你的InfiniBand硬件提供适当的独立于设备的内核和用户空间驱动。例如， + 要使用Mellanox HCA，你需要安装ib_mthca内核模块和libmthca用户空间驱动。 + +用户-内核通信 +============= + + 用户空间通过/dev/infiniband/uverbsN字符设备与内核进行慢速路径、资源管理 + 操作的通信。快速路径操作通常是通过直接写入硬件寄存器mmap()到用户空间来完成 + 的，没有系统调用或上下文切换到内核。 + + 命令是通过在这些设备文件上的write()s发送给内核的。ABI在 + drivers/infiniband/include/ib_user_verbs.h中定义。需要内核响应的命令的结 + 构包含一个64位字段，用来传递一个指向输出缓冲区的指针。状态作为write()系统调 + 用的返回值被返回到用户空间。 + +资源管理 +======== + + 由于所有IB资源的创建和销毁都是通过文件描述符传递的命令完成的，所以内核可以跟 + 踪那些被附加到给定用户空间上下文的资源。ib_uverbs模块维护着idr表，用来在 + 内核指针和不透明的用户空间句柄之间进行转换，这样内核指针就不会暴露给用户空间， + 而用户空间也无法欺骗内核去跟踪一个假的指针。 + + 这也允许内核在一个进程退出时进行清理，并防止一个进程触及另一个进程的资源。 + +内存固定 +======== + + 直接的用户空间I/O要求与作为潜在I/O目标的内存区域保持在同一物理地址上。ib_uverbs + 模块通过get_user_pages()和put_page()调用来管理内存区域的固定和解除固定。它还核 + 算进程的pinned_vm中被固定的内存量，并检查非特权进程是否超过其RLIMIT_MEMLOCK限制。 + + 被多次固定的页面在每次被固定时都会被计数，所以pinned_vm的值可能会高估一个进程所 + 固定的页面数量。 + +/dev文件 +======== + + 要想用udev自动创建适当的字符设备文件，可以采用如下规则:: + + KERNEL=="uverbs*", NAME="infiniband/%k" + + 可以使用。 这将创建设备节点，名为:: + + /dev/infiniband/uverbs0 + + 等等。由于InfiniBand的用户空间verbs对于非特权进程来说应该是安全的，因此在udev规 + 则中加入适当的MODE或GROUP可能是有用的。 diff --git a/Documentation/translations/zh_CN/process/coding-style.rst b/Documentation/translations/zh_CN/process/coding-style.rst index b8c484a84d10..638d714bec83 100644 --- a/Documentation/translations/zh_CN/process/coding-style.rst +++ b/Documentation/translations/zh_CN/process/coding-style.rst @@ -268,8 +268,7 @@ C 程序员不使用类似 ThisVariableIsATemporaryCounter 这样华丽的名字 ``count_active_users()`` 或者类似的名字，你不应该叫它 ``cntuser()`` 。 在函数名中包含函数类型 (所谓的匈牙利命名法) 是脑子出了问题——编译器知道那些类 -型而且能够检查那些类型，这样做只能把程序员弄糊涂了。难怪微软总是制造出有问题 -的程序。 +型而且能够检查那些类型，这样做只能把程序员弄糊涂了。 本地变量名应该简短，而且能够表达相关的含义。如果你有一些随机的整数型的循环计 数器，它应该被称为 ``i`` 。叫它 ``loop_counter`` 并无益处，如果它没有被误解的 diff --git a/Documentation/translations/zh_CN/virt/acrn/cpuid.rst b/Documentation/translations/zh_CN/virt/acrn/cpuid.rst new file mode 100644 index 000000000000..6f7be545611b --- /dev/null +++ b/Documentation/translations/zh_CN/virt/acrn/cpuid.rst @@ -0,0 +1,56 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. include:: ../../disclaimer-zh_CN.rst + +:Original: Documentation/virt/acrn/cpuid.rst + +:翻译: + + 司延腾 Yanteng Si <siyanteng@loongson.cn> + +:校译: + + 时奎亮 Alex Shi <alexs@kernel.org> + +.. _cn_virt_acrn_cpuid: + +============== +ACRN CPUID位域 +============== + +在ACRN超级管理器上运行的客户虚拟机可以使用CPUID检查其一些功能。 + +ACRN的cpuid函数是: + +函数: 0x40000000 + +返回:: + + eax = 0x40000010 + ebx = 0x4e524341 + ecx = 0x4e524341 + edx = 0x4e524341 + +注意，ebx，ecx和edx中的这个值对应于字符串“ACRNACRNACRN”。eax中的值对应于这个叶子 +中存在的最大cpuid函数，如果将来有更多的函数加入，将被更新。 + +函数: define ACRN_CPUID_FEATURES (0x40000001) + +返回:: + + ebx, ecx, edx + eax = an OR'ed group of (1 << flag) + +其中 ``flag`` 的定义如下: + +================================= =========== ================================ +标志 值 描述 +================================= =========== ================================ +ACRN_FEATURE_PRIVILEGED_VM 0 客户虚拟机是一个有特权的虚拟机 +================================= =========== ================================ + +函数: 0x40000010 + +返回:: + + ebx, ecx, edx + eax = (Virtual) TSC frequency in kHz. diff --git a/Documentation/translations/zh_CN/virt/acrn/index.rst b/Documentation/translations/zh_CN/virt/acrn/index.rst new file mode 100644 index 000000000000..34605d87f103 --- /dev/null +++ b/Documentation/translations/zh_CN/virt/acrn/index.rst @@ -0,0 +1,25 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. include:: ../../disclaimer-zh_CN.rst + +:Original: Documentation/virt/acrn/index.rst + +:翻译: + + 司延腾 Yanteng Si <siyanteng@loongson.cn> + +:校译: + + 时奎亮 Alex Shi <alexs@kernel.org> + +.. _cn_virt_acrn_index: + +============== +ACRN超级管理器 +============== + +.. toctree:: + :maxdepth: 1 + + introduction + io-request + cpuid diff --git a/Documentation/translations/zh_CN/virt/acrn/introduction.rst b/Documentation/translations/zh_CN/virt/acrn/introduction.rst new file mode 100644 index 000000000000..7182415cb087 --- /dev/null +++ b/Documentation/translations/zh_CN/virt/acrn/introduction.rst @@ -0,0 +1,52 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. include:: ../../disclaimer-zh_CN.rst + +:Original: Documentation/virt/acrn/introduction.rst + +:翻译: + + 司延腾 Yanteng Si <siyanteng@loongson.cn> + +:校译: + + 时奎亮 Alex Shi <alexs@kernel.org> + +.. _cn_virt_acrn_introduction: + +ACRN超级管理器介绍 +================== + +ACRN超级管理器是一个第一类超级管理器，直接在裸机硬件上运行。它有一个特权管理虚拟机，称为服 +务虚拟机，用于管理用户虚拟机和进行I/O仿真。 + +ACRN用户空间是一个运行在服务虚拟机中的应用程序，它根据命令行配置为用户虚拟机仿真设备。 +ACRN管理程序服务模块（HSM）是服务虚拟机中的一个内核模块，为ACRN用户空间提供管理程序服 +务。 + +下图展示了该架构。 + +:: + + 服务端VM 用户端VM + +----------------------------+ | +------------------+ + | +--------------+ | | | | + | |ACRN用户空间 | | | | | + | +--------------+ | | | | + |-----------------ioctl------| | | | ... + |内核空间 +----------+ | | | | + | | HSM | | | | 驱动 | + | +----------+ | | | | + +--------------------|-------+ | +------------------+ + +---------------------hypercall----------------------------------------+ + | ACRN超级管理器 | + +----------------------------------------------------------------------+ + | 硬件 | + +----------------------------------------------------------------------+ + +ACRN用户空间为用户虚拟机分配内存，配置和初始化用户虚拟机使用的设备，加载虚拟引导程序， +初始化虚拟CPU状态，处理来自用户虚拟机的I/O请求访问。它使用ioctls来与HSM通信。HSM通过 +与ACRN超级管理器的hypercalls进行交互来实现管理服务。HSM向用户空间输出一个char设备接口 +（/dev/acrn_hsm）。 + +ACRN超级管理器是开源的，任何人都可以贡献。源码库在 +https://github.com/projectacrn/acrn-hypervisor。 diff --git a/Documentation/translations/zh_CN/virt/acrn/io-request.rst b/Documentation/translations/zh_CN/virt/acrn/io-request.rst new file mode 100644 index 000000000000..4b4e7186d9a5 --- /dev/null +++ b/Documentation/translations/zh_CN/virt/acrn/io-request.rst @@ -0,0 +1,99 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. include:: ../../disclaimer-zh_CN.rst + +:Original: Documentation/virt/acrn/io-request.rst + +:翻译: + + 司延腾 Yanteng Si <siyanteng@loongson.cn> + +:校译: + + 时奎亮 Alex Shi <alexs@kernel.org> + +.. _cn_virt_acrn_io-request: + +I/O请求处理 +=========== + +客户虚拟机的I/O请求由超级管理器构建，由ACRN超级管理器服务模块分发到与I/O请求的地址范 +围相对应的I/O客户端。I/O请求处理的细节将在以下章节描述。 + +1. I/O请求 +---------- + +对于每个客户虚拟机，有一个共享的4KB字节的内存区域，用于超级管理器和服务虚拟机之间的 +I/O请求通信。一个I/O请求是一个256字节的结构体缓冲区，它是 "acrn_io_request" 结构 +体，当客户虚拟机中发生被困的I/O访问时，由超级管理器的I/O处理器填充。服务虚拟机中的 +ACRN用户空间首先分配一个4KB字节的页面，并将缓冲区的GPA（客户物理地址）传递给管理平 +台。缓冲区被用作16个I/O请求槽的数组，每个I/O请求槽为256字节。这个数组是按vCPU ID +索引的。 + +2. I/O客户端 +------------ + +一个I/O客户端负责处理客户虚拟机的I/O请求，其访问的GPA在一定范围内。每个客户虚拟机 +可以关联多个I/O客户端。每个客户虚拟机都有一个特殊的客户端，称为默认客户端，负责处理 +所有不在其他客户端范围内的I/O请求。ACRN用户空间充当每个客户虚拟机的默认客户端。 + +下面的图示显示了I/O请求共享缓冲区、I/O请求和I/O客户端之间的关系。 + +:: + + +------------------------------------------------------+ + | 服务VM | + |+--------------------------------------------------+ | + || +----------------------------------------+ | | + || | 共享页 ACRN用户空间 | | | + || | +-----------------+ +------------+ | | | + || +----+->| acrn_io_request |<-+ 默认 | | | | + || | | | +-----------------+ | I/O客户端 | | | | + || | | | | ... | +------------+ | | | + || | | | +-----------------+ | | | + || | +-|--------------------------------------+ | | + ||---|----|-----------------------------------------| | + || | | 内核 | | + || | | +----------------------+ | | + || | | | +-------------+ HSM | | | + || | +--------------+ | | | | + || | | | I/O客户端 | | | | + || | | | | | | | + || | | +-------------+ | | | + || | +----------------------+ | | + |+---|----------------------------------------------+ | + +----|-------------------------------------------------+ + | + +----|-------------------------------------------------+ + | +-+-----------+ | + | | I/O处理 | ACRN超级管理器 | + | +-------------+ | + +------------------------------------------------------+ + +3. I/O请求状态转换 +------------------ + +一个ACRN I/O请求的状态转换如下。 + +:: + + FREE -> PENDING -> PROCESSING -> COMPLETE -> FREE -> ... + +- FREE: 这个I/O请求槽是空的 +- PENDING: 在这个槽位上有一个有效的I/O请求正在等待 +- PROCESSING: 正在处理I/O请求 +- COMPLETE: 该I/O请求已被处理 + +处于COMPLETE或FREE状态的I/O请求是由超级管理器拥有的。HSM和ACRN用户空间负责处理其 +他的。 + +4. I/O请求的处理流程 +-------------------- + +a. 当客户虚拟机中发生被陷入的I/O访问时，超级管理器的I/O处理程序将把I/O请求填充为 + PENDING状态。 +b. 超级管理器向服务虚拟机发出一个向上调用，这是一个通知中断。 +c. upcall处理程序会安排一个工作者来调度I/O请求。 +d. 工作者寻找PENDING I/O请求，根据I/O访问的地址将其分配给不同的注册客户，将其 + 状态更新为PROCESSING，并通知相应的客户进行处理。 +e. 被通知的客户端处理指定的I/O请求。 +f. HSM将I/O请求状态更新为COMPLETE，并通过hypercalls通知超级管理器完成。 diff --git a/Documentation/translations/zh_CN/virt/guest-halt-polling.rst b/Documentation/translations/zh_CN/virt/guest-halt-polling.rst new file mode 100644 index 000000000000..b798d1cf0b48 --- /dev/null +++ b/Documentation/translations/zh_CN/virt/guest-halt-polling.rst @@ -0,0 +1,87 @@ +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/virt/guest-halt-polling.rst + +:翻译: + + 司延腾 Yanteng Si <siyanteng@loongson.cn> + +:校译: + + 时奎亮 Alex Shi <alexs@kernel.org> + +.. _cn_virt_guest-halt-polling: + +======================================== +客户机停机轮询机制（Guest halt polling） +======================================== + +cpuidle_haltpoll驱动，与haltpoll管理器一起，允许客户机vcpus在停机前轮询 +一定的时间。 + +这为物理机侧的轮询提供了以下好处: + + 1) 在执行轮询时，POLL标志被设置，这允许远程vCPU在执行唤醒时避免发送 + IPI（以及处理IPI的相关成本）。 + + 2) 可以避免虚拟机退出的成本。 + +客户机侧轮询的缺点是，即使在物理机中的其他可运行任务中也会进行轮询。 + +其基本逻辑如下。一个全局值，即guest_halt_poll_ns，是由用户配置的，表示允 +许轮询的最大时间量。这个值是固定的。 + +每个vcpu都有一个可调整的guest_halt_poll_ns（"per-cpu guest_halt_poll_ns"）， +它由算法响应事件进行调整（解释如下）。 + +模块参数 +======== + +haltpoll管理器有5个可调整的模块参数: + +1) guest_halt_poll_ns: + +轮询停机前执行的最大时间，以纳秒为单位。 + +默认值: 200000 + +2) guest_halt_poll_shrink: + +当唤醒事件发生在全局的guest_halt_poll_ns之后，用于缩减每个CPU的guest_halt_poll_ns +的划分系数。 + +默认值: 2 + +3) guest_halt_poll_grow: + +当事件发生在per-cpu guest_halt_poll_ns之后但在global guest_halt_poll_ns之前， +用于增长per-cpu guest_halt_poll_ns的乘法系数。 + +默认值: 2 + +4) guest_halt_poll_grow_start: + +在系统空闲的情况下，每个cpu guest_halt_poll_ns最终达到零。这个值设置了增长时的 +初始每cpu guest_halt_poll_ns。这个值可以从10000开始增加，以避免在最初的增长阶 +段出现失误。: + +10k, 20k, 40k, ... (例如，假设guest_halt_poll_grow=2). + +默认值: 50000 + +5) guest_halt_poll_allow_shrink: + +允许缩减的Bool参数。设置为N以避免它（一旦达到全局的guest_halt_poll_ns值，每CPU的 +guest_halt_poll_ns将保持高位）。 + +默认值: Y + +模块参数可以从Debugfs文件中设置，在:: + + /sys/module/haltpoll/parameters/ + +进一步说明 +========== + +- 在设置guest_halt_poll_ns参数时应该小心，因为一个大的值有可能使几乎是完全空闲机 + 器上的cpu使用率达到100%。 diff --git a/Documentation/translations/zh_CN/virt/index.rst b/Documentation/translations/zh_CN/virt/index.rst new file mode 100644 index 000000000000..f8dd13681341 --- /dev/null +++ b/Documentation/translations/zh_CN/virt/index.rst @@ -0,0 +1,38 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/virt/index.rst + +:翻译: + + 司延腾 Yanteng Si <siyanteng@loongson.cn> + +:校译: + + 时奎亮 Alex Shi <alexs@kernel.org> + +.. _cn_virt_index: + +=============== +Linux虚拟化支持 +=============== + +.. toctree:: + :maxdepth: 2 + + paravirt_ops + guest-halt-polling + ne_overview + acrn/index + +TODOLIST: + + kvm/index + uml/user_mode_linux_howto_v2 + +.. only:: html and subproject + + Indices + ======= + + * :ref:`genindex` diff --git a/Documentation/translations/zh_CN/virt/ne_overview.rst b/Documentation/translations/zh_CN/virt/ne_overview.rst new file mode 100644 index 000000000000..2455b371abea --- /dev/null +++ b/Documentation/translations/zh_CN/virt/ne_overview.rst @@ -0,0 +1,88 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/virt/ne_overview.rst + +:翻译: + + 司延腾 Yanteng Si <siyanteng@loongson.cn> + +:校译: + + 时奎亮 Alex Shi <alexs@kernel.org> + +.. _cn_virt_ne_overview: + +============== +Nitro Enclaves +============== + +概述 +==== + +Nitro Enclaves（NE）是亚马逊弹性计算云（EC2）的一项新功能，允许客户在EC2实 +例中划分出孤立的计算环境[1]。 + +例如，一个处理敏感数据并在虚拟机中运行的应用程序，可以与在同一虚拟机中运行的 +其他应用程序分开。然后，这个应用程序在一个独立于主虚拟机的虚拟机中运行，即 +enclave。 + +一个enclave与催生它的虚拟机一起运行。这种设置符合低延迟应用的需要。为enclave +分配的资源，如内存和CPU，是从主虚拟机中分割出来的。每个enclave都被映射到一 +个运行在主虚拟机中的进程，该进程通过一个ioctl接口与NE驱动进行通信。 + +在这个意义上，有两个组成部分。 + +1. 一个enclave抽象进程——一个运行在主虚拟机客体中的用户空间进程，它使用NE驱动 +提供的ioctl接口来生成一个enclave虚拟机（这就是下面的2）。 + +有一个NE模拟的PCI设备暴露给主虚拟机。这个新的PCI设备的驱动被包含在NE驱动中。 + +ioctl逻辑被映射到PCI设备命令，例如，NE_START_ENCLAVE ioctl映射到一个enclave +启动PCI命令。然后，PCI设备命令被翻译成在管理程序方面采取的行动；也就是在运 +行主虚拟机的主机上运行的Nitro管理程序。Nitro管理程序是基于KVM核心技术的。 + +2. enclave本身——一个运行在与催生它的主虚拟机相同的主机上的虚拟机。内存和CPU +从主虚拟机中分割出来，专门用于enclave虚拟机。enclave没有连接持久性存储。 + +从主虚拟机中分割出来并给enclave的内存区域需要对齐2 MiB/1 GiB物理连续的内存 +区域（或这个大小的倍数，如8 MiB）。该内存可以通过使用hugetlbfs从用户空间分 +配[2][3]。一个enclave的内存大小需要至少64 MiB。enclave内存和CPU需要来自同 +一个NUMA节点。 + +一个enclave在专用的核心上运行。CPU 0及其同级别的CPU需要保持对主虚拟机的可用 +性。CPU池必须由具有管理能力的用户为NE目的进行设置。关于CPU池的格式，请看内核 +文档[4]中的cpu list部分。 + +enclave通过本地通信通道与主虚拟机进行通信，使用virtio-vsock[5]。主虚拟机有 +virtio-pci vsock模拟设备，而飞地虚拟机有virtio-mmio vsock模拟设备。vsock +设备使用eventfd作为信令。enclave虚拟机看到通常的接口——本地APIC和IOAPIC——从 +virtio-vsock设备获得中断。virtio-mmio设备被放置在典型的4 GiB以下的内存中。 + +在enclave中运行的应用程序需要和将在enclave虚拟机中运行的操作系统（如内核、 +ramdisk、init）一起被打包到enclave镜像中。enclave虚拟机有自己的内核并遵循标 +准的Linux启动协议[6]。 + +内核bzImage、内核命令行、ramdisk（s）是enclave镜像格式（EIF）的一部分；另外 +还有一个EIF头，包括元数据，如magic number、eif版本、镜像大小和CRC。 + +哈希值是为整个enclave镜像（EIF）、内核和ramdisk（s）计算的。例如，这被用来检 +查在enclave虚拟机中加载的enclave镜像是否是打算运行的那个。 + +这些加密测量包括在由Nitro超级管理器成的签名证明文件中，并进一步用来证明enclave +的身份；KMS是NE集成的服务的一个例子，它检查证明文件。 + +enclave镜像（EIF）被加载到enclave内存中，偏移量为8 MiB。enclave中的初始进程 +连接到主虚拟机的vsock CID和一个预定义的端口--9000，以发送一个心跳值--0xb7。这 +个机制用于在主虚拟机中检查enclave是否已经启动。主虚拟机的CID是3。 + +如果enclave虚拟机崩溃或优雅地退出，NE驱动会收到一个中断事件。这个事件会通过轮询 +通知机制进一步发送到运行在主虚拟机中的用户空间enclave进程。然后，用户空间enclave +进程就可以退出了。 + +[1] https://aws.amazon.com/ec2/nitro/nitro-enclaves/ +[2] https://www.kernel.org/doc/html/latest/admin-guide/mm/hugetlbpage.html +[3] https://lwn.net/Articles/807108/ +[4] https://www.kernel.org/doc/html/latest/admin-guide/kernel-parameters.html +[5] https://man7.org/linux/man-pages/man7/vsock.7.html +[6] https://www.kernel.org/doc/html/latest/x86/boot.html diff --git a/Documentation/translations/zh_CN/virt/paravirt_ops.rst b/Documentation/translations/zh_CN/virt/paravirt_ops.rst new file mode 100644 index 000000000000..06b122bc915d --- /dev/null +++ b/Documentation/translations/zh_CN/virt/paravirt_ops.rst @@ -0,0 +1,41 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/virt/paravirt_ops.rst + +:翻译: + + 司延腾 Yanteng Si <siyanteng@loongson.cn> + +:校译: + + 陈飞杨 Feiyang Chen <chenfeiyang@loongson.cn> + 时奎亮 Alex Shi <alexs@kernel.org> + +.. _cn_virt_paravirt_ops: + +============ +半虚拟化操作 +============ + +Linux提供了对不同管理程序虚拟化技术的支持。历史上，为了支持不同的虚拟机超级管理器 +（hypervisor，下文简称超级管理器），需要不同的二进制内核，这个限制已经被pv_ops移 +除了。Linux pv_ops是一个虚拟化API，它能够支持不同的管理程序。它允许每个管理程序 +优先于关键操作，并允许单一的内核二进制文件在所有支持的执行环境中运行，包括本机——没 +有任何管理程序。 + +pv_ops提供了一组函数指针，代表了与低级关键指令和各领域高级功能相对应的操作。 +pv-ops允许在运行时进行优化，在启动时对低级关键操作进行二进制修补。 + +pv_ops操作被分为三类: + +- 简单的间接调用 + 这些操作对应于高水平的函数，众所周知，间接调用的开销并不十分重要。 + +- 间接调用，允许用二进制补丁进行优化 + 通常情况下，这些操作对应于低级别的关键指令。它们被频繁地调用，并且是对性能关 + 键。开销是非常重要的。 + +- 一套用于手写汇编代码的宏程序 + 手写的汇编代码（.S文件）也需要半虚拟化，因为它们包括敏感指令或其中的一些代 + 码路径对性能非常关键。 diff --git a/Documentation/translations/zh_TW/IRQ.txt b/Documentation/translations/zh_TW/IRQ.txt new file mode 100644 index 000000000000..73d435a0d1e7 --- /dev/null +++ b/Documentation/translations/zh_TW/IRQ.txt @@ -0,0 +1,41 @@ +Chinese translated version of Documentation/core-api/irq/index.rst + +If you have any comment or update to the content, please contact the +original document maintainer directly. However, if you have a problem +communicating in English you can also ask the Chinese maintainer for +help. Contact the Chinese maintainer if this translation is outdated +or if there is a problem with the translation. + +Maintainer: Eric W. Biederman <ebiederman@xmission.com> +Traditional Chinese maintainer: Hu Haowen <src.res@email.cn> +--------------------------------------------------------------------- +Documentation/core-api/irq/index.rst 的繁體中文翻譯 + +如果想評論或更新本文的內容，請直接聯繫原文檔的維護者。如果你使用英文 +交流有困難的話，也可以向繁體中文版維護者求助。如果本翻譯更新不及時或 +者翻譯存在問題，請聯繫繁體中文版維護者。 + +英文版維護者： Eric W. Biederman <ebiederman@xmission.com> +繁體中文版維護者： 胡皓文 Hu Haowen <src.res@email.cn> +繁體中文版翻譯者： 胡皓文 Hu Haowen <src.res@email.cn> +繁體中文版校譯者： 胡皓文 Hu Haowen <src.res@email.cn> + + +以下爲正文 +--------------------------------------------------------------------- +何爲 IRQ? + +一個 IRQ 是來自某個設備的一個中斷請求。目前，它們可以來自一個硬體引腳， +或來自一個數據包。多個設備可能連接到同個硬體引腳，從而共享一個 IRQ。 + +一個 IRQ 編號是用於告知硬體中斷源的內核標識。通常情況下，這是一個 +全局 irq_desc 數組的索引，但是除了在 linux/interrupt.h 中的實現， +具體的細節是體系結構特定的。 + +一個 IRQ 編號是設備上某個可能的中斷源的枚舉。通常情況下，枚舉的編號是 +該引腳在系統內中斷控制器的所有輸入引腳中的編號。對於 ISA 總線中的情況， +枚舉的是在兩個 i8259 中斷控制器中 16 個輸入引腳。 + +架構可以對 IRQ 編號指定額外的含義，在硬體涉及任何手工配置的情況下， +是被提倡的。ISA 的 IRQ 是一個分配這類額外含義的典型例子。 + diff --git a/Documentation/translations/zh_TW/admin-guide/README.rst b/Documentation/translations/zh_TW/admin-guide/README.rst new file mode 100644 index 000000000000..b752e50359e6 --- /dev/null +++ b/Documentation/translations/zh_TW/admin-guide/README.rst @@ -0,0 +1,351 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. include:: ../disclaimer-zh_TW.rst + +:Original: Documentation/admin-guide/README.rst + +:譯者: + + 吳想成 Wu XiangCheng <bobwxc@email.cn> + 胡皓文 Hu Haowen <src.res@email.cn> + +Linux內核5.x版本 <http://kernel.org/> +========================================= + +以下是Linux版本5的發行註記。仔細閱讀它們， +它們會告訴你這些都是什麼，解釋如何安裝內核，以及遇到問題時該如何做。 + +什麼是Linux？ +--------------- + + Linux是Unix作業系統的克隆版本，由Linus Torvalds在一個鬆散的網絡黑客 + （Hacker，無貶義）團隊的幫助下從頭開始編寫。它旨在實現兼容POSIX和 + 單一UNIX規範。 + + 它具有在現代成熟的Unix中應當具有的所有功能，包括真正的多任務處理、虛擬內存、 + 共享庫、按需加載、共享的寫時拷貝（COW）可執行文件、恰當的內存管理以及包括 + IPv4和IPv6在內的複合網絡棧。 + + Linux在GNU通用公共許可證，版本2（GNU GPLv2）下分發，詳見隨附的COPYING文件。 + +它能在什麼樣的硬體上運行？ +----------------------------- + + 雖然Linux最初是爲32位的x86 PC機（386或更高版本）開發的，但今天它也能運行在 + （至少）Compaq Alpha AXP、Sun SPARC與UltraSPARC、Motorola 68000、PowerPC、 + PowerPC64、ARM、Hitachi SuperH、Cell、IBM S/390、MIPS、HP PA-RISC、Intel + IA-64、DEC VAX、AMD x86-64 Xtensa和ARC架構上。 + + Linux很容易移植到大多數通用的32位或64位體系架構，只要它們有一個分頁內存管理 + 單元（PMMU）和一個移植的GNU C編譯器（gcc；GNU Compiler Collection，GCC的一 + 部分）。Linux也被移植到許多沒有PMMU的體系架構中，儘管功能顯然受到了一定的 + 限制。 + Linux也被移植到了其自己上。現在可以將內核作爲用戶空間應用程式運行——這被 + 稱爲用戶模式Linux（UML）。 + +文檔 +----- +網際網路上和書籍上都有大量的電子文檔，既有Linux專屬文檔，也有與一般UNIX問題相關 +的文檔。我建議在任何Linux FTP站點上查找LDP（Linux文檔項目）書籍的文檔子目錄。 +本自述文件並不是關於系統的文檔：有更好的可用資源。 + + - 網際網路上和書籍上都有大量的（電子）文檔，既有Linux專屬文檔，也有與普通 + UNIX問題相關的文檔。我建議在任何有LDP（Linux文檔項目）書籍的Linux FTP + 站點上查找文檔子目錄。本自述文件並不是關於系統的文檔：有更好的可用資源。 + + - 文檔/子目錄中有各種自述文件：例如，這些文件通常包含一些特定驅動程序的 + 內核安裝說明。請閱讀 + :ref:`Documentation/process/changes.rst <changes>` 文件，它包含了升級內核 + 可能會導致的問題的相關信息。 + +安裝內核原始碼 +--------------- + + - 如果您要安裝完整的原始碼，請把內核tar檔案包放在您有權限的目錄中（例如您 + 的主目錄）並將其解包:: + + xz -cd linux-5.x.tar.xz | tar xvf - + + 將「X」替換成最新內核的版本號。 + + 【不要】使用 /usr/src/linux 目錄！這裡有一組庫頭文件使用的內核頭文件 + （通常是不完整的）。它們應該與庫匹配，而不是被內核的變化搞得一團糟。 + + - 您還可以通過打補丁在5.x版本之間升級。補丁以xz格式分發。要通過打補丁進行 + 安裝，請獲取所有較新的補丁文件，進入內核原始碼（linux-5.x）的目錄並 + 執行:: + + xz -cd ../patch-5.x.xz | patch -p1 + + 請【按順序】替換所有大於當前原始碼樹版本的「x」，這樣就可以了。您可能想要 + 刪除備份文件（文件名類似xxx~ 或 xxx.orig)，並確保沒有失敗的補丁（文件名 + 類似xxx# 或 xxx.rej）。如果有，不是你就是我犯了錯誤。 + + 與5.x內核的補丁不同，5.x.y內核（也稱爲穩定版內核）的補丁不是增量的，而是 + 直接應用於基本的5.x內核。例如，如果您的基本內核是5.0，並且希望應用5.0.3 + 補丁，則不應先應用5.0.1和5.0.2的補丁。類似地，如果您運行的是5.0.2內核， + 並且希望跳轉到5.0.3，那麼在應用5.0.3補丁之前，必須首先撤銷5.0.2補丁 + （即patch -R）。更多關於這方面的內容，請閱讀 + :ref:`Documentation/process/applying-patches.rst <applying_patches>` 。 + + 或者，腳本 patch-kernel 可以用來自動化這個過程。它能確定當前內核版本並 + 應用找到的所有補丁:: + + linux/scripts/patch-kernel linux + + 上面命令中的第一個參數是內核原始碼的位置。補丁是在當前目錄應用的，但是 + 可以將另一個目錄指定爲第二個參數。 + + - 確保沒有過時的 .o 文件和依賴項:: + + cd linux + make mrproper + + 現在您應該已經正確安裝了原始碼。 + +軟體要求 +--------- + + 編譯和運行5.x內核需要各種軟體包的最新版本。請參考 + :ref:`Documentation/process/changes.rst <changes>` + 來了解最低版本要求以及如何升級軟體包。請注意，使用過舊版本的這些包可能會 + 導致很難追蹤的間接錯誤，因此不要以爲在生成或操作過程中出現明顯問題時可以 + 只更新包。 + +爲內核建立目錄 +--------------- + + 編譯內核時，默認情況下所有輸出文件都將與內核原始碼放在一起。使用 + ``make O=output/dir`` 選項可以爲輸出文件（包括 .config）指定備用位置。 + 例如:: + + kernel source code: /usr/src/linux-5.x + build directory: /home/name/build/kernel + + 要配置和構建內核，請使用:: + + cd /usr/src/linux-5.x + make O=/home/name/build/kernel menuconfig + make O=/home/name/build/kernel + sudo make O=/home/name/build/kernel modules_install install + + 請注意：如果使用了 ``O=output/dir`` 選項，那麼它必須用於make的所有調用。 + +配置內核 +--------- + + 即使只升級一個小版本，也不要跳過此步驟。每個版本中都會添加新的配置選項， + 如果配置文件沒有按預定設置，就會出現奇怪的問題。如果您想以最少的工作量 + 將現有配置升級到新版本，請使用 ``makeoldconfig`` ，它只會詢問您新配置 + 選項的答案。 + + - 其他配置命令包括:: + + "make config" 純文本界面。 + + "make menuconfig" 基於文本的彩色菜單、選項列表和對話框。 + + "make nconfig" 增強的基於文本的彩色菜單。 + + "make xconfig" 基於Qt的配置工具。 + + "make gconfig" 基於GTK+的配置工具。 + + "make oldconfig" 基於現有的 ./.config 文件選擇所有選項，並詢問 + 新配置選項。 + + "make olddefconfig" + 類似上一個，但不詢問直接將新選項設置爲默認值。 + + "make defconfig" 根據體系架構，使用arch/$arch/defconfig或 + arch/$arch/configs/${PLATFORM}_defconfig中的 + 默認選項值創建./.config文件。 + + "make ${PLATFORM}_defconfig" + 使用arch/$arch/configs/${PLATFORM}_defconfig中 + 的默認選項值創建一個./.config文件。 + 用「makehelp」來獲取您體系架構中所有可用平台的列表。 + + "make allyesconfig" + 通過儘可能將選項值設置爲「y」，創建一個 + ./.config文件。 + + "make allmodconfig" + 通過儘可能將選項值設置爲「m」，創建一個 + ./.config文件。 + + "make allnoconfig" 通過儘可能將選項值設置爲「n」，創建一個 + ./.config文件。 + + "make randconfig" 通過隨機設置選項值來創建./.config文件。 + + "make localmodconfig" 基於當前配置和加載的模塊（lsmod）創建配置。禁用 + 已加載的模塊不需要的任何模塊選項。 + + 要爲另一台計算機創建localmodconfig，請將該計算機 + 的lsmod存儲到一個文件中，並將其作爲lsmod參數傳入。 + + 此外，通過在參數LMC_KEEP中指定模塊的路徑，可以將 + 模塊保留在某些文件夾或kconfig文件中。 + + target$ lsmod > /tmp/mylsmod + target$ scp /tmp/mylsmod host:/tmp + + host$ make LSMOD=/tmp/mylsmod \ + LMC_KEEP="drivers/usb:drivers/gpu:fs" \ + localmodconfig + + 上述方法在交叉編譯時也適用。 + + "make localyesconfig" 與localmodconfig類似，只是它會將所有模塊選項轉換 + 爲內置（=y）。你可以同時通過LMC_KEEP保留模塊。 + + "make kvmconfig" 爲kvm客體內核支持啓用其他選項。 + + "make xenconfig" 爲xen dom0客體內核支持啓用其他選項。 + + "make tinyconfig" 配置儘可能小的內核。 + + 更多關於使用Linux內核配置工具的信息，見文檔 + Documentation/kbuild/kconfig.rst。 + + - ``make config`` 注意事項: + + - 包含不必要的驅動程序會使內核變大，並且在某些情況下會導致問題： + 探測不存在的控制器卡可能會混淆其他控制器。 + + - 如果存在協處理器，則編譯了數學仿真的內核仍將使用協處理器：在 + 這種情況下，數學仿真永遠不會被使用。內核會稍微大一點，但不管 + 是否有數學協處理器，都可以在不同的機器上工作。 + + - 「kernel hacking」配置細節通常會導致更大或更慢的內核（或兩者 + 兼而有之），甚至可以通過配置一些例程來主動嘗試破壞壞代碼以發現 + 內核問題，從而降低內核的穩定性（kmalloc()）。因此，您可能應該 + 用於研究「開發」、「實驗」或「調試」特性相關問題。 + +編譯內核 +--------- + + - 確保您至少有gcc 4.9可用。 + 有關更多信息，請參閱 :ref:`Documentation/process/changes.rst <changes>` 。 + + 請注意，您仍然可以使用此內核運行a.out用戶程序。 + + - 執行 ``make`` 來創建壓縮內核映像。如果您安裝了lilo以適配內核makefile， + 那麼也可以進行 ``makeinstall`` ，但是您可能需要先檢查特定的lilo設置。 + + 實際安裝必須以root身份執行，但任何正常構建都不需要。 + 無須徒然使用root身份。 + + - 如果您將內核的任何部分配置爲模塊，那麼還必須執行 ``make modules_install`` 。 + + - 詳細的內核編譯/生成輸出： + + 通常，內核構建系統在相當安靜的模式下運行（但不是完全安靜）。但是有時您或 + 其他內核開發人員需要看到編譯、連結或其他命令的執行過程。爲此，可使用 + 「verbose（詳細）」構建模式。 + 向 ``make`` 命令傳遞 ``V=1`` 來實現，例如:: + + make V=1 all + + 如需構建系統也給出內個目標重建的願意，請使用 ``V=2`` 。默認爲 ``V=0`` 。 + + - 準備一個備份內核以防出錯。對於開發版本尤其如此，因爲每個新版本都包含 + 尚未調試的新代碼。也要確保保留與該內核對應的模塊的備份。如果要安裝 + 與工作內核版本號相同的新內核，請在進行 ``make modules_install`` 安裝 + 之前備份modules目錄。 + + 或者，在編譯之前，使用內核配置選項「LOCALVERSION」向常規內核版本附加 + 一個唯一的後綴。LOCALVERSION可以在「General Setup」菜單中設置。 + + - 爲了引導新內核，您需要將內核映像（例如編譯後的 + .../linux/arch/x86/boot/bzImage）複製到常規可引導內核的位置。 + + - 不再支持在沒有LILO等啓動裝載程序幫助的情況下直接從軟盤引導內核。 + + 如果從硬碟引導Linux，很可能使用LILO，它使用/etc/lilo.conf文件中 + 指定的內核映像文件。內核映像文件通常是/vmlinuz、/boot/vmlinuz、 + /bzImage或/boot/bzImage。使用新內核前，請保存舊映像的副本，並複製 + 新映像覆蓋舊映像。然後您【必須重新運行LILO】來更新加載映射！否則， + 將無法啓動新的內核映像。 + + 重新安裝LILO通常需要運行/sbin/LILO。您可能希望編輯/etc/lilo.conf + 文件爲舊內核映像指定一個條目（例如/vmlinux.old)防止新的不能正常 + 工作。有關更多信息，請參閱LILO文檔。 + + 重新安裝LILO之後，您應該就已經準備好了。關閉系統，重新啓動，盡情 + 享受吧！ + + 如果需要更改內核映像中的默認根設備、視頻模式等，請在適當的地方使用 + 啓動裝載程序的引導選項。無需重新編譯內核即可更改這些參數。 + + - 使用新內核重新啓動並享受它吧。 + +若遇到問題 +----------- + + - 如果您發現了一些可能由於內核缺陷所導致的問題，請檢查MAINTAINERS（維護者） + 文件看看是否有人與令您遇到麻煩的內核部分相關。如果無人在此列出，那麼第二 + 個最好的方案就是把它們發給我（torvalds@linux-foundation.org），也可能發送 + 到任何其他相關的郵件列表或新聞組。 + + - 在所有的缺陷報告中，【請】告訴我們您在說什麼內核，如何復現問題，以及您的 + 設置是什麼的（使用您的常識）。如果問題是新的，請告訴我；如果問題是舊的， + 請嘗試告訴我您什麼時候首次注意到它。 + + - 如果缺陷導致如下消息:: + + unable to handle kernel paging request at address C0000010 + Oops: 0002 + EIP: 0010:XXXXXXXX + eax: xxxxxxxx ebx: xxxxxxxx ecx: xxxxxxxx edx: xxxxxxxx + esi: xxxxxxxx edi: xxxxxxxx ebp: xxxxxxxx + ds: xxxx es: xxxx fs: xxxx gs: xxxx + Pid: xx, process nr: xx + xx xx xx xx xx xx xx xx xx xx + + 或者類似的內核調試信息顯示在屏幕上或在系統日誌里，請【如實】複製它。 + 可能對你來說轉儲（dump）看起來不可理解，但它確實包含可能有助於調試問題的 + 信息。轉儲上方的文本也很重要：它說明了內核轉儲代碼的原因（在上面的示例中， + 是由於內核指針錯誤）。更多關於如何理解轉儲的信息，請參見 + Documentation/admin-guide/bug-hunting.rst。 + + - 如果使用 CONFIG_KALLSYMS 編譯內核，則可以按原樣發送轉儲，否則必須使用 + ``ksymoops`` 程序來理解轉儲（但通常首選使用CONFIG_KALLSYMS編譯）。 + 此實用程序可從 + https://www.kernel.org/pub/linux/utils/kernel/ksymoops/ 下載。 + 或者，您可以手動執行轉儲查找： + + - 在調試像上面這樣的轉儲時，如果您可以查找EIP值的含義，這將非常有幫助。 + 十六進位值本身對我或其他任何人都沒有太大幫助：它會取決於特定的內核設置。 + 您應該做的是從EIP行獲取十六進位值（忽略 ``0010:`` ），然後在內核名字列表 + 中查找它，以查看哪個內核函數包含有問題的地址。 + + 要找到內核函數名，您需要找到與顯示症狀的內核相關聯的系統二進位文件。就是 + 文件「linux/vmlinux」。要提取名字列表並將其與內核崩潰中的EIP進行匹配， + 請執行:: + + nm vmlinux | sort | less + + 這將爲您提供一個按升序排序的內核地址列表，從中很容易找到包含有問題的地址 + 的函數。請注意，內核調試消息提供的地址不一定與函數地址完全匹配（事實上， + 這是不可能的），因此您不能只「grep」列表：不過列表將爲您提供每個內核函數 + 的起點，因此通過查找起始地址低於你正在搜索的地址，但後一個函數的高於的 + 函數，你會找到您想要的。實際上，在您的問題報告中加入一些「上下文」可能是 + 一個好主意，給出相關的上下幾行。 + + 如果您由於某些原因無法完成上述操作（如您使用預編譯的內核映像或類似的映像）， + 請儘可能多地告訴我您的相關設置信息，這會有所幫助。有關詳細信息請閱讀 + 『Documentation/admin-guide/reporting-issues.rst』。 + + - 或者，您可以在正在運行的內核上使用gdb（只讀的；即不能更改值或設置斷點）。 + 爲此，請首先使用-g編譯內核；適當地編輯arch/x86/Makefile，然後執行 ``make + clean`` 。您還需要啓用CONFIG_PROC_FS（通過 ``make config`` ）。 + + 使用新內核重新啓動後，執行 ``gdb vmlinux /proc/kcore`` 。現在可以使用所有 + 普通的gdb命令。查找系統崩潰點的命令是 ``l *0xXXXXXXXX`` （將xxx替換爲EIP + 值）。 + + 用gdb無法調試一個當前未運行的內核是由於gdb（錯誤地）忽略了編譯內核的起始 + 偏移量。 + diff --git a/Documentation/translations/zh_TW/admin-guide/bug-bisect.rst b/Documentation/translations/zh_TW/admin-guide/bug-bisect.rst new file mode 100644 index 000000000000..41a39aebb8d6 --- /dev/null +++ b/Documentation/translations/zh_TW/admin-guide/bug-bisect.rst @@ -0,0 +1,85 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. include:: ../disclaimer-zh_TW.rst + +:Original: :doc:`../../../admin-guide/bug-bisect` + +:譯者: + + 吳想成 Wu XiangCheng <bobwxc@email.cn> + 胡皓文 Hu Haowen <src.res@email.cn> + +二分（bisect）缺陷 ++++++++++++++++++++ + +（英文版）最後更新：2016年10月28日 + +引言 +===== + +始終嘗試由來自kernel.org的原始碼構建的最新內核。如果您沒有信心這樣做，請將 +錯誤報告給您的發行版供應商，而不是內核開發人員。 + +找到缺陷（bug）並不總是那麼容易，不過仍然得去找。如果你找不到它，不要放棄。 +儘可能多的向相關維護人員報告您發現的信息。請參閱MAINTAINERS文件以了解您所 +關注的子系統的維護人員。 + +在提交錯誤報告之前，請閱讀「Documentation/admin-guide/reporting-issues.rst」。 + +設備未出現（Devices not appearing） +==================================== + +這通常是由udev/systemd引起的。在將其歸咎於內核之前先檢查一下。 + +查找導致缺陷的補丁 +=================== + +使用 ``git`` 提供的工具可以很容易地找到缺陷，只要缺陷是可復現的。 + +操作步驟： + +- 從git原始碼構建內核 +- 以此開始二分 [#f1]_:: + + $ git bisect start + +- 標記損壞的變更集:: + + $ git bisect bad [commit] + +- 標記正常工作的變更集:: + + $ git bisect good [commit] + +- 重新構建內核並測試 +- 使用以下任一與git bisect進行交互:: + + $ git bisect good + + 或:: + + $ git bisect bad + + 這取決於您測試的變更集上是否有缺陷 +- 在一些交互之後，git bisect將給出可能導致缺陷的變更集。 + +- 例如，如果您知道當前版本有問題，而4.8版本是正常的，則可以執行以下操作:: + + $ git bisect start + $ git bisect bad # Current version is bad + $ git bisect good v4.8 + + +.. [#f1] 您可以（可選地）在開始git bisect的時候提供good或bad參數 + ``git bisect start [BAD] [GOOD]`` + +如需進一步參考，請閱讀： + +- ``git-bisect`` 的手冊頁 +- `Fighting regressions with git bisect（用git bisect解決回歸） + <https://www.kernel.org/pub/software/scm/git/docs/git-bisect-lk2009.html>`_ +- `Fully automated bisecting with "git bisect run"（使用git bisect run + 來全自動二分） <https://lwn.net/Articles/317154>`_ +- `Using Git bisect to figure out when brokenness was introduced + （使用Git二分來找出何時引入了錯誤） <http://webchick.net/node/99>`_ + diff --git a/Documentation/translations/zh_TW/admin-guide/bug-hunting.rst b/Documentation/translations/zh_TW/admin-guide/bug-hunting.rst new file mode 100644 index 000000000000..4d813aec77d2 --- /dev/null +++ b/Documentation/translations/zh_TW/admin-guide/bug-hunting.rst @@ -0,0 +1,344 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. include:: ../disclaimer-zh_TW.rst + +:Original: :doc:`../../../admin-guide/bug-hunting` + +:譯者: + + 吳想成 Wu XiangCheng <bobwxc@email.cn> + 胡皓文 Hu Haowen <src.res@email.cn> + +追蹤缺陷 +========= + +內核錯誤報告通常附帶如下堆棧轉儲:: + + ------------[ cut here ]------------ + WARNING: CPU: 1 PID: 28102 at kernel/module.c:1108 module_put+0x57/0x70 + Modules linked in: dvb_usb_gp8psk(-) dvb_usb dvb_core nvidia_drm(PO) nvidia_modeset(PO) snd_hda_codec_hdmi snd_hda_intel snd_hda_codec snd_hwdep snd_hda_core snd_pcm snd_timer snd soundcore nvidia(PO) [last unloaded: rc_core] + CPU: 1 PID: 28102 Comm: rmmod Tainted: P WC O 4.8.4-build.1 #1 + Hardware name: MSI MS-7309/MS-7309, BIOS V1.12 02/23/2009 + 00000000 c12ba080 00000000 00000000 c103ed6a c1616014 00000001 00006dc6 + c1615862 00000454 c109e8a7 c109e8a7 00000009 ffffffff 00000000 f13f6a10 + f5f5a600 c103ee33 00000009 00000000 00000000 c109e8a7 f80ca4d0 c109f617 + Call Trace: + [<c12ba080>] ? dump_stack+0x44/0x64 + [<c103ed6a>] ? __warn+0xfa/0x120 + [<c109e8a7>] ? module_put+0x57/0x70 + [<c109e8a7>] ? module_put+0x57/0x70 + [<c103ee33>] ? warn_slowpath_null+0x23/0x30 + [<c109e8a7>] ? module_put+0x57/0x70 + [<f80ca4d0>] ? gp8psk_fe_set_frontend+0x460/0x460 [dvb_usb_gp8psk] + [<c109f617>] ? symbol_put_addr+0x27/0x50 + [<f80bc9ca>] ? dvb_usb_adapter_frontend_exit+0x3a/0x70 [dvb_usb] + [<f80bb3bf>] ? dvb_usb_exit+0x2f/0xd0 [dvb_usb] + [<c13d03bc>] ? usb_disable_endpoint+0x7c/0xb0 + [<f80bb48a>] ? dvb_usb_device_exit+0x2a/0x50 [dvb_usb] + [<c13d2882>] ? usb_unbind_interface+0x62/0x250 + [<c136b514>] ? __pm_runtime_idle+0x44/0x70 + [<c13620d8>] ? __device_release_driver+0x78/0x120 + [<c1362907>] ? driver_detach+0x87/0x90 + [<c1361c48>] ? bus_remove_driver+0x38/0x90 + [<c13d1c18>] ? usb_deregister+0x58/0xb0 + [<c109fbb0>] ? SyS_delete_module+0x130/0x1f0 + [<c1055654>] ? task_work_run+0x64/0x80 + [<c1000fa5>] ? exit_to_usermode_loop+0x85/0x90 + [<c10013f0>] ? do_fast_syscall_32+0x80/0x130 + [<c1549f43>] ? sysenter_past_esp+0x40/0x6a + ---[ end trace 6ebc60ef3981792f ]--- + +這樣的堆棧跟蹤提供了足夠的信息來識別內核原始碼中發生錯誤的那一行。根據問題的 +嚴重性，它還可能包含 **「Oops」** 一詞，比如:: + + BUG: unable to handle kernel NULL pointer dereference at (null) + IP: [<c06969d4>] iret_exc+0x7d0/0xa59 + *pdpt = 000000002258a001 *pde = 0000000000000000 + Oops: 0002 [#1] PREEMPT SMP + ... + +儘管有 **Oops** 或其他類型的堆棧跟蹤，但通常需要找到出問題的行來識別和處理缺 +陷。在本章中，我們將參考「Oops」來了解需要分析的各種堆棧跟蹤。 + +如果內核是用 ``CONFIG_DEBUG_INFO`` 編譯的，那麼可以使用文件： +`scripts/decode_stacktrace.sh` 。 + +連結的模塊 +----------- + +受到汙染或正在加載/卸載的模塊用「（…）」標記，汙染標誌在 +`Documentation/admin-guide/tainted-kernels.rst` 文件中進行了描述，「正在被加 +載」用「+」標註，「正在被卸載」用「-」標註。 + + +Oops消息在哪？ +--------------- + +通常，Oops文本由klogd從內核緩衝區讀取，然後交給 ``syslogd`` ，後者將其寫入 +syslog文件，通常是 ``/var/log/messages`` （取決於 ``/etc/syslog.conf`` ）。 +在使用systemd的系統上，它也可以由 ``journald`` 守護進程存儲，並通過運行 +``journalctl`` 命令進行訪問。 + +有時 ``klogd`` 會掛掉，這種情況下您可以運行 ``dmesg > file`` 從內核緩衝區 +讀取數據並保存它。或者您可以 ``cat /proc/kmsg > file`` ，但是您必須適時 +中斷以停止傳輸，因爲 ``kmsg`` 是一個「永無止境的文件」。 + +如果機器嚴重崩潰，無法輸入命令或磁碟不可用，那還有三個選項： + +(1) 手動複製屏幕上的文本，並在機器重新啓動後輸入。很難受，但這是突然崩潰下 + 唯一的選擇。或者你可以用數位相機拍下屏幕——雖然不那麼好，但總比什麼都沒 + 有好。如果消息滾動超出控制台頂部，使用更高解析度（例如 ``vga=791`` ） + 引導啓動將允許您閱讀更多文本。（警告：這需要 ``vesafb`` ，因此對「早期」 + 的Oppses沒有幫助） + +(2) 從串口終端啓動（參見 + :ref:`Documentation/admin-guide/serial-console.rst <serial_console>` ）， + 在另一台機器上運行數據機然後用你喜歡的通信程序捕獲輸出。 + Minicom運行良好。 + +(3) 使用Kdump（參閱 Documentation/admin-guide/kdump/kdump.rst ），使用 + Documentation/admin-guide/kdump/gdbmacros.txt 中的dmesg gdbmacro從舊內存 + 中提取內核環形緩衝區。 + +找到缺陷位置 +------------- + +如果你能指出缺陷在內核原始碼中的位置，則報告缺陷的效果會非常好。這有兩種方法。 +通常來說使用 ``gdb`` 會比較容易，不過內核需要用調試信息來預編譯。 + +gdb +^^^^ + +GNU 調試器（GNU debugger， ``gdb`` ）是從 ``vmlinux`` 文件中找出OOPS的確切 +文件和行號的最佳方法。 + +在使用 ``CONFIG_DEBUG_INFO`` 編譯的內核上使用gdb效果最好。可通過運行以下命令 +進行設置:: + + $ ./scripts/config -d COMPILE_TEST -e DEBUG_KERNEL -e DEBUG_INFO + +在用 ``CONFIG_DEBUG_INFO`` 編譯的內核上，你可以直接從OOPS複製EIP值:: + + EIP: 0060:[<c021e50e>] Not tainted VLI + +並使用GDB來將其翻譯成可讀形式:: + + $ gdb vmlinux + (gdb) l *0xc021e50e + +如果沒有啓用 ``CONFIG_DEBUG_INFO`` ，則使用OOPS的函數偏移:: + + EIP is at vt_ioctl+0xda8/0x1482 + +並在啓用 ``CONFIG_DEBUG_INFO`` 的情況下重新編譯內核:: + + $ ./scripts/config -d COMPILE_TEST -e DEBUG_KERNEL -e DEBUG_INFO + $ make vmlinux + $ gdb vmlinux + (gdb) l *vt_ioctl+0xda8 + 0x1888 is in vt_ioctl (drivers/tty/vt/vt_ioctl.c:293). + 288 { + 289 struct vc_data *vc = NULL; + 290 int ret = 0; + 291 + 292 console_lock(); + 293 if (VT_BUSY(vc_num)) + 294 ret = -EBUSY; + 295 else if (vc_num) + 296 vc = vc_deallocate(vc_num); + 297 console_unlock(); + +或者若您想要更詳細的顯示:: + + (gdb) p vt_ioctl + $1 = {int (struct tty_struct *, unsigned int, unsigned long)} 0xae0 <vt_ioctl> + (gdb) l *0xae0+0xda8 + +您也可以使用對象文件作爲替代:: + + $ make drivers/tty/ + $ gdb drivers/tty/vt/vt_ioctl.o + (gdb) l *vt_ioctl+0xda8 + +如果你有調用跟蹤，類似:: + + Call Trace: + [<ffffffff8802c8e9>] :jbd:log_wait_commit+0xa3/0xf5 + [<ffffffff810482d9>] autoremove_wake_function+0x0/0x2e + [<ffffffff8802770b>] :jbd:journal_stop+0x1be/0x1ee + ... + +這表明問題可能在 :jbd: 模塊中。您可以在gdb中加載該模塊並列出相關代碼:: + + $ gdb fs/jbd/jbd.ko + (gdb) l *log_wait_commit+0xa3 + +.. note:: + + 您還可以對堆棧跟蹤處的任何函數調用執行相同的操作，例如:: + + [<f80bc9ca>] ? dvb_usb_adapter_frontend_exit+0x3a/0x70 [dvb_usb] + + 上述調用發生的位置可以通過以下方式看到:: + + $ gdb drivers/media/usb/dvb-usb/dvb-usb.o + (gdb) l *dvb_usb_adapter_frontend_exit+0x3a + +objdump +^^^^^^^^ + +要調試內核，請使用objdump並從崩潰輸出中查找十六進位偏移，以找到有效的代碼/匯 +編行。如果沒有調試符號，您將看到所示例程的彙編程序代碼，但是如果內核有調試 +符號，C代碼也將可見（調試符號可以在內核配置菜單的hacking項中啓用）。例如:: + + $ objdump -r -S -l --disassemble net/dccp/ipv4.o + +.. note:: + + 您需要處於內核樹的頂層以便此獲得您的C文件。 + +如果您無法訪問原始碼，仍然可以使用以下方法調試一些崩潰轉儲（如Dave Miller的 +示例崩潰轉儲輸出所示）:: + + EIP is at +0x14/0x4c0 + ... + Code: 44 24 04 e8 6f 05 00 00 e9 e8 fe ff ff 8d 76 00 8d bc 27 00 00 + 00 00 55 57 56 53 81 ec bc 00 00 00 8b ac 24 d0 00 00 00 8b 5d 08 + <8b> 83 3c 01 00 00 89 44 24 14 8b 45 28 85 c0 89 44 24 18 0f 85 + + Put the bytes into a "foo.s" file like this: + + .text + .globl foo + foo: + .byte .... /* bytes from Code: part of OOPS dump */ + + Compile it with "gcc -c -o foo.o foo.s" then look at the output of + "objdump --disassemble foo.o". + + Output: + + ip_queue_xmit: + push %ebp + push %edi + push %esi + push %ebx + sub $0xbc, %esp + mov 0xd0(%esp), %ebp ! %ebp = arg0 (skb) + mov 0x8(%ebp), %ebx ! %ebx = skb->sk + mov 0x13c(%ebx), %eax ! %eax = inet_sk(sk)->opt + +`scripts/decodecode` 文件可以用來自動完成大部分工作，這取決於正在調試的CPU +體系結構。 + +報告缺陷 +--------- + +一旦你通過定位缺陷找到了其發生的地方，你可以嘗試自己修復它或者向上游報告它。 + +爲了向上游報告，您應該找出用於開發受影響代碼的郵件列表。這可以使用 ``get_maintainer.pl`` 。 + + +例如，您在gspca的sonixj.c文件中發現一個缺陷，則可以通過以下方法找到它的維護者:: + + $ ./scripts/get_maintainer.pl -f drivers/media/usb/gspca/sonixj.c + Hans Verkuil <hverkuil@xs4all.nl> (odd fixer:GSPCA USB WEBCAM DRIVER,commit_signer:1/1=100%) + Mauro Carvalho Chehab <mchehab@kernel.org> (maintainer:MEDIA INPUT INFRASTRUCTURE (V4L/DVB),commit_signer:1/1=100%) + Tejun Heo <tj@kernel.org> (commit_signer:1/1=100%) + Bhaktipriya Shridhar <bhaktipriya96@gmail.com> (commit_signer:1/1=100%,authored:1/1=100%,added_lines:4/4=100%,removed_lines:9/9=100%) + linux-media@vger.kernel.org (open list:GSPCA USB WEBCAM DRIVER) + linux-kernel@vger.kernel.org (open list) + +請注意它將指出： + +- 最後接觸原始碼的開發人員（如果這是在git樹中完成的）。在上面的例子中是Tejun + 和Bhaktipriya（在這個特定的案例中，沒有人真正參與這個文件的開發）； +- 驅動維護人員（Hans Verkuil）； +- 子系統維護人員（Mauro Carvalho Chehab）； +- 驅動程序和/或子系統郵件列表（linux-media@vger.kernel.org）； +- Linux內核郵件列表（linux-kernel@vger.kernel.org）。 + +通常，修復缺陷的最快方法是將它報告給用於開發相關代碼的郵件列表（linux-media +ML），抄送驅動程序維護者（Hans）。 + +如果你完全不知道該把報告寄給誰，且 ``get_maintainer.pl`` 也沒有提供任何有用 +的信息，請發送到linux-kernel@vger.kernel.org。 + +感謝您的幫助，這使Linux儘可能穩定:-) + +修復缺陷 +--------- + +如果你懂得編程，你不僅可以通過報告錯誤來幫助我們，還可以提供一個解決方案。 +畢竟，開源就是分享你的工作，你不想因爲你的天才而被認可嗎？ + +如果你決定這樣做，請在制定解決方案後將其提交到上游。 + +請務必閱讀 +:ref:`Documentation/process/submitting-patches.rst <submittingpatches>` ， +以幫助您的代碼被接受。 + + +--------------------------------------------------------------------------- + +用 ``klogd`` 進行Oops跟蹤的注意事項 +------------------------------------ + +爲了幫助Linus和其他內核開發人員， ``klogd`` 對保護故障的處理提供了大量支持。 +爲了完整支持地址解析，至少應該使用 ``sysklogd`` 包的1.3-pl3版本。 + +當發生保護故障時， ``klogd`` 守護進程會自動將內核日誌消息中的重要地址轉換爲 +它們的等效符號。然後通過 ``klogd`` 使用的任何報告機制來轉發這個已翻譯的內核 +消息。保護錯誤消息可以直接從消息文件中剪切出來並轉發給內核開發人員。 + +``klogd`` 執行兩種類型的地址解析，靜態翻譯和動態翻譯。靜態翻譯使用System.map +文件。爲了進行靜態轉換， ``klogd`` 守護進程必須能夠在守護進程初始化時找到系 +統映射文件。有關 ``klogd`` 如何搜索映射文件的信息，請參見klogd手冊頁。 + +當使用內核可加載模塊時，動態地址轉換非常重要。由於內核模塊的內存是從內核的 +動態內存池中分配的，因此無論是模塊的開頭還是模塊中的函數和符號都沒有固定的 +位置。 + +內核支持系統調用，允許程序確定加載哪些模塊及其在內存中的位置。klogd守護進程 +使用這些系統調用構建了一個符號表，可用於調試可加載內核模塊中發生的保護錯誤。 + +klogd至少會提供產生保護故障的模塊的名稱。如果可加載模塊的開發人員選擇從模塊 +導出符號信息，則可能會有其他可用的符號信息。 + +由於內核模塊環境可以是動態的，因此當模塊環境發生變化時，必須有一種通知 +``klogd`` 守護進程的機制。有一些可用的命令行選項允許klogd向當前正在執行的守 +護進程發出信號示意應該刷新符號信息。有關更多信息，請參閱 ``klogd`` 手冊頁。 + +sysklogd發行版附帶了一個補丁，它修改了 ``modules-2.0.0`` 包，以便在加載或 +卸載模塊時自動向klogd發送信號。應用此補丁基本上可無縫支持調試內核可加載模塊 +發生的保護故障。 + +以下是 ``klogd`` 處理的可加載模塊中的保護故障示例:: + + Aug 29 09:51:01 blizard kernel: Unable to handle kernel paging request at virtual address f15e97cc + Aug 29 09:51:01 blizard kernel: current->tss.cr3 = 0062d000, %cr3 = 0062d000 + Aug 29 09:51:01 blizard kernel: *pde = 00000000 + Aug 29 09:51:01 blizard kernel: Oops: 0002 + Aug 29 09:51:01 blizard kernel: CPU: 0 + Aug 29 09:51:01 blizard kernel: EIP: 0010:[oops:_oops+16/3868] + Aug 29 09:51:01 blizard kernel: EFLAGS: 00010212 + Aug 29 09:51:01 blizard kernel: eax: 315e97cc ebx: 003a6f80 ecx: 001be77b edx: 00237c0c + Aug 29 09:51:01 blizard kernel: esi: 00000000 edi: bffffdb3 ebp: 00589f90 esp: 00589f8c + Aug 29 09:51:01 blizard kernel: ds: 0018 es: 0018 fs: 002b gs: 002b ss: 0018 + Aug 29 09:51:01 blizard kernel: Process oops_test (pid: 3374, process nr: 21, stackpage=00589000) + Aug 29 09:51:01 blizard kernel: Stack: 315e97cc 00589f98 0100b0b4 bffffed4 0012e38e 00240c64 003a6f80 00000001 + Aug 29 09:51:01 blizard kernel: 00000000 00237810 bfffff00 0010a7fa 00000003 00000001 00000000 bfffff00 + Aug 29 09:51:01 blizard kernel: bffffdb3 bffffed4 ffffffda 0000002b 0007002b 0000002b 0000002b 00000036 + Aug 29 09:51:01 blizard kernel: Call Trace: [oops:_oops_ioctl+48/80] [_sys_ioctl+254/272] [_system_call+82/128] + Aug 29 09:51:01 blizard kernel: Code: c7 00 05 00 00 00 eb 08 90 90 90 90 90 90 90 90 89 ec 5d c3 + +--------------------------------------------------------------------------- + +:: + + Dr. G.W. Wettstein Oncology Research Div. Computing Facility + Roger Maris Cancer Center INTERNET: greg@wind.rmcc.com + 820 4th St. N. + Fargo, ND 58122 + Phone: 701-234-7556 + diff --git a/Documentation/translations/zh_TW/admin-guide/clearing-warn-once.rst b/Documentation/translations/zh_TW/admin-guide/clearing-warn-once.rst new file mode 100644 index 000000000000..bdc1a22046cf --- /dev/null +++ b/Documentation/translations/zh_TW/admin-guide/clearing-warn-once.rst @@ -0,0 +1,16 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. include:: ../disclaimer-zh_TW.rst + +:Translator: 胡皓文 Hu Haowen <src.res@email.cn> + +清除 WARN_ONCE +-------------- + +WARN_ONCE / WARN_ON_ONCE / printk_once 僅僅列印一次消息. + +echo 1 > /sys/kernel/debug/clear_warn_once + +可以清除這種狀態並且再次允許列印一次告警信息，這對於運行測試集後重現問題 +很有用。 + diff --git a/Documentation/translations/zh_TW/admin-guide/cpu-load.rst b/Documentation/translations/zh_TW/admin-guide/cpu-load.rst new file mode 100644 index 000000000000..be087cef1967 --- /dev/null +++ b/Documentation/translations/zh_TW/admin-guide/cpu-load.rst @@ -0,0 +1,112 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. include:: ../disclaimer-zh_TW.rst + +:Translator: 胡皓文 Hu Haowen <src.res@email.cn> + +======== +CPU 負載 +======== + +Linux通過``/proc/stat``和``/proc/uptime``導出各種信息，用戶空間工具 +如top(1)使用這些信息計算系統花費在某個特定狀態的平均時間。 +例如： + + $ iostat + Linux 2.6.18.3-exp (linmac) 02/20/2007 + + avg-cpu: %user %nice %system %iowait %steal %idle + 10.01 0.00 2.92 5.44 0.00 81.63 + + ... + +這裡系統認爲在默認採樣周期內有10.01%的時間工作在用戶空間，2.92%的時 +間用在系統空間，總體上有81.63%的時間是空閒的。 + +大多數情況下``/proc/stat``的信息幾乎真實反映了系統信息，然而，由於內 +核採集這些數據的方式/時間的特點，有時這些信息根本不可靠。 + +那麼這些信息是如何被搜集的呢？每當時間中斷觸發時，內核查看此刻運行的 +進程類型，並增加與此類型/狀態進程對應的計數器的值。這種方法的問題是 +在兩次時間中斷之間系統（進程）能夠在多種狀態之間切換多次，而計數器只 +增加最後一種狀態下的計數。 + +舉例 +--- + +假設系統有一個進程以如下方式周期性地占用cpu:: + + 兩個時鐘中斷之間的時間線 + |-----------------------| + ^ ^ + |_ 開始運行 | + |_ 開始睡眠 + （很快會被喚醒） + +在上面的情況下，根據``/proc/stat``的信息（由於當系統處於空閒狀態時， +時間中斷經常會發生）系統的負載將會是0 + +大家能夠想像內核的這種行爲會發生在許多情況下，這將導致``/proc/stat`` +中存在相當古怪的信息:: + + /* gcc -o hog smallhog.c */ + #include <time.h> + #include <limits.h> + #include <signal.h> + #include <sys/time.h> + #define HIST 10 + + static volatile sig_atomic_t stop; + + static void sighandler (int signr) + { + (void) signr; + stop = 1; + } + static unsigned long hog (unsigned long niters) + { + stop = 0; + while (!stop && --niters); + return niters; + } + int main (void) + { + int i; + struct itimerval it = { .it_interval = { .tv_sec = 0, .tv_usec = 1 }, + .it_value = { .tv_sec = 0, .tv_usec = 1 } }; + sigset_t set; + unsigned long v[HIST]; + double tmp = 0.0; + unsigned long n; + signal (SIGALRM, &sighandler); + setitimer (ITIMER_REAL, &it, NULL); + + hog (ULONG_MAX); + for (i = 0; i < HIST; ++i) v[i] = ULONG_MAX - hog (ULONG_MAX); + for (i = 0; i < HIST; ++i) tmp += v[i]; + tmp /= HIST; + n = tmp - (tmp / 3.0); + + sigemptyset (&set); + sigaddset (&set, SIGALRM); + + for (;;) { + hog (n); + sigwait (&set, &i); + } + return 0; + } + + +參考 +--- + +- https://lore.kernel.org/r/loom.20070212T063225-663@post.gmane.org +- Documentation/filesystems/proc.rst (1.8) + + +謝謝 +--- + +Con Kolivas, Pavel Machek + diff --git a/Documentation/translations/zh_TW/admin-guide/index.rst b/Documentation/translations/zh_TW/admin-guide/index.rst new file mode 100644 index 000000000000..293c20245783 --- /dev/null +++ b/Documentation/translations/zh_TW/admin-guide/index.rst @@ -0,0 +1,135 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. include:: ../disclaimer-zh_TW.rst + +:Original: :doc:`../../../admin-guide/index` +:Translator: 胡皓文 Hu Haowen <src.res@email.cn> + +Linux 內核用戶和管理員指南 +========================== + +下面是一組隨時間添加到內核中的面向用戶的文檔的集合。到目前爲止，還沒有一個 +整體的順序或組織 - 這些材料不是一個單一的，連貫的文件！幸運的話，情況會隨著 +時間的推移而迅速改善。 + +這個初始部分包含總體信息，包括描述內核的README， 關於內核參數的文檔等。 + +.. toctree:: + :maxdepth: 1 + + README + +Todolist: + + kernel-parameters + devices + sysctl/index + +本節介紹CPU漏洞及其緩解措施。 + +Todolist: + + hw-vuln/index + +下面的一組文檔，針對的是試圖跟蹤問題和bug的用戶。 + +.. toctree:: + :maxdepth: 1 + + reporting-issues + security-bugs + bug-hunting + bug-bisect + tainted-kernels + init + +Todolist: + + reporting-bugs + ramoops + dynamic-debug-howto + kdump/index + perf/index + +這是應用程式開發人員感興趣的章節的開始。可以在這裡找到涵蓋內核ABI各個 +方面的文檔。 + +Todolist: + + sysfs-rules + +本手冊的其餘部分包括各種指南，介紹如何根據您的喜好配置內核的特定行爲。 + + +.. toctree:: + :maxdepth: 1 + + clearing-warn-once + cpu-load + unicode + +Todolist: + + acpi/index + aoe/index + auxdisplay/index + bcache + binderfs + binfmt-misc + blockdev/index + bootconfig + braille-console + btmrvl + cgroup-v1/index + cgroup-v2 + cifs/index + cputopology + dell_rbu + device-mapper/index + edid + efi-stub + ext4 + nfs/index + gpio/index + highuid + hw_random + initrd + iostats + java + jfs + kernel-per-CPU-kthreads + laptops/index + lcd-panel-cgram + ldm + lockup-watchdogs + LSM/index + md + media/index + mm/index + module-signing + mono + namespaces/index + numastat + parport + perf-security + pm/index + pnp + rapidio + ras + rtc + serial-console + svga + sysrq + thunderbolt + ufs + vga-softcursor + video-output + xfs + +.. only:: subproject and html + + Indices + ======= + + * :ref:`genindex` + diff --git a/Documentation/translations/zh_TW/admin-guide/init.rst b/Documentation/translations/zh_TW/admin-guide/init.rst new file mode 100644 index 000000000000..32cdf134948f --- /dev/null +++ b/Documentation/translations/zh_TW/admin-guide/init.rst @@ -0,0 +1,58 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. include:: ../disclaimer-zh_TW.rst + +:Original: :doc:`../../../admin-guide/init` + +:譯者: + + 吳想成 Wu XiangCheng <bobwxc@email.cn> + 胡皓文 Hu Haowen <src.res@email.cn> + +解釋「No working init found.」啓動掛起消息 +========================================== + +:作者: + + Andreas Mohr <andi at lisas period de> + + Cristian Souza <cristianmsbr at gmail period com> + +本文檔提供了加載初始化二進位（init binary）失敗的一些高層級原因（大致按執行 +順序列出）。 + +1) **無法掛載根文件系統Unable to mount root FS** ：請設置「debug」內核參數（在 + 引導加載程序bootloader配置文件或CONFIG_CMDLINE）以獲取更詳細的內核消息。 + +2) **初始化二進位不存在於根文件系統上init binary doesn't exist on rootfs** ： + 確保您的根文件系統類型正確（並且 ``root=`` 內核參數指向正確的分區）；擁有 + 所需的驅動程序，例如SCSI或USB等存儲硬體；文件系統（ext3、jffs2等）是內建的 + （或者作爲模塊由initrd預加載）。 + +3) **控制台設備損壞Broken console device** ： ``console= setup`` 中可能存在 + 衝突 --> 初始控制台不可用（initial console unavailable）。例如，由於串行 + IRQ問題（如缺少基於中斷的配置）導致的某些串行控制台不可靠。嘗試使用不同的 + ``console= device`` 或像 ``netconsole=`` 。 + +4) **二進位存在但依賴項不可用Binary exists but dependencies not available** ： + 例如初始化二進位的必需庫依賴項，像 ``/lib/ld-linux.so.2`` 丟失或損壞。使用 + ``readelf -d <INIT>|grep NEEDED`` 找出需要哪些庫。 + +5) **無法加載二進位Binary cannot be loaded** ：請確保二進位的體系結構與您的 + 硬體匹配。例如i386不匹配x86_64，或者嘗試在ARM硬體上加載x86。如果您嘗試在 + 此處加載非二進位文件（shell腳本？），您應該確保腳本在其工作頭（shebang + header）行 ``#!/...`` 中指定能正常工作的解釋器（包括其庫依賴項）。在處理 + 腳本之前，最好先測試一個簡單的非腳本二進位文件，比如 ``/bin/sh`` ，並確認 + 它能成功執行。要了解更多信息，請將代碼添加到 ``init/main.c`` 以顯示 + kernel_execve()的返回值。 + +當您發現新的失敗原因時，請擴展本解釋（畢竟加載初始化二進位是一個 **關鍵** 且 +艱難的過渡步驟，需要儘可能無痛地進行），然後向LKML提交一個補丁。 + +待辦事項： + +- 通過一個可以存儲 ``kernel_execve()`` 結果值的結構體數組實現各種 + ``run_init_process()`` 調用，並在失敗時通過疊代 **所有** 結果來記錄一切 + （非常重要的可用性修復）。 +- 試著使實現本身在一般情況下更有幫助，例如在受影響的地方提供額外的錯誤消息。 + diff --git a/Documentation/translations/zh_TW/admin-guide/reporting-issues.rst b/Documentation/translations/zh_TW/admin-guide/reporting-issues.rst new file mode 100644 index 000000000000..27638e199f13 --- /dev/null +++ b/Documentation/translations/zh_TW/admin-guide/reporting-issues.rst @@ -0,0 +1,1337 @@ +.. SPDX-License-Identifier: (GPL-2.0+ OR CC-BY-4.0) +.. + If you want to distribute this text under CC-BY-4.0 only, please use 'The + Linux kernel developers' for author attribution and link this as source: + https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/plain/Documentation/admin-guide/reporting-issues.rst +.. + Note: Only the content of this RST file as found in the Linux kernel sources + is available under CC-BY-4.0, as versions of this text that were processed + (for example by the kernel's build system) might contain content taken from + files which use a more restrictive license. + +.. include:: ../disclaimer-zh_TW.rst + +:Original: Documentation/admin-guide/reporting-issues.rst + +:譯者: + + 吳想成 Wu XiangCheng <bobwxc@email.cn> + 胡皓文 Hu Haowen <src.res@email.cn> + + +報告問題 ++++++++++ + + +簡明指南（亦即 太長不看） +========================== + +您面臨的是否爲同系列穩定版或長期支持內核的普通內核的回歸？是否仍然受支持？ +請搜索 `LKML內核郵件列表 <https://lore.kernel.org/lkml/>`_ 和 +`Linux穩定版郵件列表 <https://lore.kernel.org/stable/>`_ 存檔中匹配的報告並 +加入討論。如果找不到匹配的報告，請安裝該系列的最新版本。如果它仍然出現問題， +報告給穩定版郵件列表（stable@vger.kernel.org）。 + +在所有其他情況下，請儘可能猜測是哪個內核部分導致了問題。查看MAINTAINERS文件， +了解開發人員希望如何得知問題，大多數情況下，報告問題都是通過電子郵件和抄送 +相關郵件列表進行的。檢查報告目的地的存檔中是否已有匹配的報告；也請搜索 +`LKML <https://lore.kernel.org/lkml/>`_ 和網絡。如果找不到可加入的討論，請 +安裝 `最新的主線內核 <https://kernel.org/>`_ 。如果仍存在問題，請發送報告。 + +問題已經解決了，但是您希望看到它在一個仍然支持的穩定版或長期支持系列中得到 +解決？請安裝其最新版本。如果它出現了問題，那麼在主線中搜索修復它的更改，並 +檢查是否正在回傳（backporting）或者已放棄；如果兩者都沒有，那麼可詢問處理 +更改的人員。 + +**通用提醒** ：當安裝和測試上述內核時，請確保它是普通的（即：沒有補丁，也沒 +有使用附加模塊）。還要確保它是在一個正常的環境中構建和運行，並且在問題發生 +之前沒有被汙染（tainted）。 + +在編寫報告時，要涵蓋與問題相關的所有信息，如使用的內核和發行版。在碰見回歸時， +嘗試給出引入它的更改的提交ID，二分可以找到它。如果您同時面臨Linux內核的多個 +問題，請分別報告每個問題。 + +一旦報告發出，請回答任何出現的問題，並儘可能地提供幫助。這包括通過不時重新 +測試新版本並發送狀態更新來推動進展。 + + +如何向內核維護人員報告問題的逐步指南 +===================================== + +上面的簡明指南概述了如何向Linux內核開發人員報告問題。對於已經熟悉向自由和開 +源軟體（FLOSS）項目報告問題的人來說，這可能是他們所需要的全部內容。對於其他 +人，本部分更爲詳細，並一步一步地描述。爲了便於閱讀，它仍然儘量簡潔，並省略 +了許多細節；這些在逐步指南後的參考章節中進行了描述，該章節更詳細地解釋了每 +個步驟。 + +注意：本節涉及的方面比簡明指南多，順序也稍有不同。這符合你的利益，以確保您 +儘早意識到看起來像Linux內核毛病的問題可能實際上是由其他原因引起的。這些步驟 +可以確保你最終不會覺得在這一過程中投入的時間是浪費： + + * 您是否面臨硬體或軟體供應商提供的Linux內核的問題？那麼基本上您最好停止閱讀 + 本文檔，轉而向您的供應商報告問題，除非您願意自己安裝最新的Linux版本。尋找 + 和解決問題往往需要後者。 + + * 使用您喜愛的網絡搜尋引擎對現有報告進行粗略搜索；此外，請檢查 + `Linux內核郵件列表（LKML） <https://lore.kernel.org/lkml/>`_ 的存檔。如果 + 找到匹配的報告，請加入討論而不是發送新報告。 + + * 看看你正在處理的問題是否爲回歸問題、安全問題或非常嚴重的問題：這些都是需 + 要在接下來的一些步驟中特別處理的「高優先級問題」。 + + * 確保不是內核環境導致了您面臨的問題。 + + * 創建一個新的備份，並將系統修復和恢復工具放在手邊。 + + * 確保您的系統不會通過動態構建額外的內核模塊來增強其內核，像DKMS這樣的解決 + 方案可能在您不知情的情況下就在本地進行了這樣的工作。 + + * 當問題發生時，檢查您的內核是否被「汙染」，因爲使內核設置這個標誌的事件可能 + 會導致您面臨的問題。 + + * 粗略地寫下如何重現這個問題。如果您同時處理多個問題，請爲每個問題單獨寫注 + 釋，並確保它們在新啓動的系統上獨立出現。這是必要的，因爲每個問題都需要分 + 別報告給內核開發人員，除非它們嚴重糾纏在一起。 + + * 如果您正面臨穩定版或長期支持版本線的回歸（例如從5.10.4更新到5.10.5時出現 + 故障），請查看後文「報告穩定版和長期支持內核線的回歸」小節。 + + * 定位可能引起問題的驅動程序或內核子系統。找出其開發人員期望的報告的方式和 + 位置。注意：大多數情況下不會是 bugzilla.kernel.org，因爲問題通常需要通 + 過郵件發送給維護人員和公共郵件列表。 + + * 在缺陷追蹤器或問題相關郵件列表的存檔中徹底搜索可能與您的問題匹配的報告。 + 如果你發現了一些相關討論，請加入討論而不是發送新的報告。 + +在完成這些準備之後，你將進入主要部分： + + * 除非您已經在運行最新的「主線」Linux內核，否則最好在報告流程前安裝它。在某些 + 情況下，使用最新的「穩定版」Linux進行測試和報告也是可以接受的替代方案；在 + 合併窗口期間，這實際上可能是最好的方法，但在開發階段最好還是暫停幾天。無論 + 你選擇什麼版本，最好使用「普通」構建。忽略這些建議會大大增加您的報告被拒絕 + 或忽略的風險。 + + * 確保您剛剛安裝的內核在運行時不會「汙染」自己。 + + * 在您剛剛安裝的內核中復現這個問題。如果它沒有出現，請查看下方只發生在 + 穩定版和長期支持內核的問題的說明。 + + * 優化你的筆記：試著找到並寫出最直接的復現問題的方法。確保最終結果包含所有 + 重要的細節，同時讓第一次聽說的人容易閱讀和理解。如果您在此過程中學到了一 + 些東西，請考慮再次搜索關於該問題的現有報告。 + + * 如果失敗涉及「panic」、「Oops」、「warning」或「BUG」，請考慮解碼內核日誌以查找觸 + 發錯誤的代碼行。 + + * 如果您的問題是回歸問題，請儘可能縮小引入問題時的範圍。 + + * 通過詳細描述問題來開始編寫報告。記得包括以下條目：您爲復現而安裝的最新內 + 核版本、使用的Linux發行版以及關於如何復現該問題的說明。如果可能，將內核 + 構建配置（.config）和 ``dmesg`` 的輸出放在網上的某個地方，並連結到它。包 + 含或上傳所有其他可能相關的信息，如Oops的輸出/截圖或來自 ``lspci`` 的輸出 + 。一旦你寫完了這個主要部分，請在上方插入一個正常長度的段落快速概述問題和 + 影響。再在此之上添加一個簡單描述問題的句子，以得到人們的閱讀。現在給出一 + 個更短的描述性標題或主題。然後就可以像MAINTAINERS文件告訴你的那樣發送或 + 提交報告了，除非你在處理一個「高優先級問題」：它們需要按照下面「高優先級問 + 題的特殊處理」所述特別關照。 + + * 等待別人的反應，繼續推進事情，直到你能夠接受這樣或那樣的結果。因此，請公 + 開和及時地回應任何詢問。測試提出的修復。積極地測試：至少重新測試每個新主 + 線版本的首個候選版本（RC），並報告你的結果。如果出現拖延，就友好地提醒一 + 下。如果你沒有得到任何幫助或者未能滿意，請試著自己幫助自己。 + + +報告穩定版和長期支持內核線的回歸 +---------------------------------- + +如果您發現了穩定版或長期支持內核版本線中的回歸問題並按上述流程跳到這裡，那麼 +請閱讀本小節。即例如您在從5.10.4更新到5.10.5時出現了問題（從5.9.15到5.10.5則 +不是）。開發人員希望儘快修復此類回歸，因此有一個簡化流程來報告它們： + + * 檢查內核開發人員是否仍然維護你關心的Linux內核版本線：去 `kernel.org 的首頁 + <https://kernel.org/>`_ ，確保此特定版本線的最新版沒有「[EOL]」標記。 + + * 檢查 `Linux穩定版郵件列表 <https://lore.kernel.org/stable/>`_ 中的現有報告。 + + * 從特定的版本線安裝最新版本作爲純淨內核。確保這個內核沒有被汙染，並且仍然 + 存在問題，因爲問題可能已經在那裡被修復了。如果您第一次發現供應商內核的問題， + 請檢查已知最新版本的普通構建是否可以正常運行。 + + * 向Linux穩定版郵件列表發送一個簡短的問題報告(stable@vger.kernel.org)。大致 + 描述問題，並解釋如何復現。講清楚首個出現問題的版本和最後一個工作正常的版本。 + 然後等待進一步的指示。 + +下面的參考章節部分詳細解釋了這些步驟中的每一步。 + + +報告只發生在較舊內核版本線的問題 +---------------------------------- + +若您嘗試了上述的最新主線內核，但未能在那裡復現問題，那麼本小節適用於您；以下 +流程有助於使問題在仍然支持的穩定版或長期支持版本線，或者定期基於最新穩定版或 +長期支持內核的供應商內核中得到修復。如果是這種情況，請執行以下步驟： + + * 請做好準備，接下來的幾個步驟可能無法在舊版本中解決問題：修復可能太大或太 + 冒險，無法移植到那裡。 + + * 執行前節「報告穩定版和長期支持內核線的回歸」中的前三個步驟。 + + * 在Linux內核版本控制系統中搜索修復主線問題的更改，因爲它的提交消息可能會 + 告訴你修復是否已經計劃好了支持。如果你沒有找到，搜索適當的郵件列表，尋找 + 討論此類問題或同行評議可能修復的帖子；然後檢查討論是否認爲修復不適合支持。 + 如果支持根本不被考慮，加入最新的討論，詢問是否有可能。 + + * 前面的步驟之一應該會給出一個解決方案。如果仍未能成功，請向可能引起問題的 + 子系統的維護人員詢問建議；抄送特定子系統的郵件列表以及穩定版郵件列表 + +下面的參考章節部分詳細解釋了這些步驟中的每一步。 + + +參考章節：向內核維護者報告問題 +=============================== + +上面的詳細指南簡要地列出了所有主要步驟，這對大多數人來說應該足夠了。但有時， +即使是有經驗的用戶也可能想知道如何實際執行這些步驟之一。這就是本節的目的， +因爲它將提供關於上述每個步驟的更多細節。請將此作爲參考文檔：可以從頭到尾 +閱讀它。但它主要是爲了瀏覽和查找如何實際執行這些步驟的詳細信息。 + +在深入挖掘細節之前，我想先給你一些一般性建議： + + * Linux內核開發人員很清楚這個過程很複雜，比其他的FLOSS項目要求更多。我們很 + 希望讓它更簡單。但這需要在不同的地方以及一些基礎設施上付諸努力，這些基礎 + 設施需要持續的維護；尚未有人站出來做這些工作，所以目前情況就是這樣。 + + * 與某些供應商簽訂的保證或支持合同並不能使您有權要求上游Linux內核社區的開 + 發人員進行修復：這樣的合同完全在Linux內核、其開發社區和本文檔的範圍之外。 + 這就是爲什麼在這種情況下，你不能要求任何契約保證，即使開發人員處理的問 + 題對供應商有效。如果您想主張您的權利，使用供應商的支持渠道代替。當這樣做 + 的時候，你可能想提出你希望看到這個問題在上游Linux內核中修復；可以這是確 + 保最終修復將被納入所有Linux發行版的唯一方法來鼓勵他們。 + + * 如果您從未向FLOSS項目報告過任何問題，那麼您應該考慮閱讀 `如何有效地報告 + 缺陷 <https://www.chiark.greenend.org.uk/~sgtatham/bugs.html>`_ ， `如何 + 以明智的方式提問 <http://www.catb.org/esr/faqs/smart-questions.html>`_ ， + 和 `如何提出好問題 <https://jvns.ca/blog/good-questions/>`_ 。 + +解決這些問題之後，可以在下面找到如何正確地向Linux內核報告問題的詳細信息。 + + +確保您使用的是上游Linux內核 +---------------------------- + + *您是否面臨硬體或軟體供應商提供的Linux內核的問題？那麼基本上您最好停止閱 + 讀本文檔，轉而向您的供應商報告問題，除非您願意自己安裝最新的Linux版本。 + 尋找和解決問題往往需要後者。* + +與大多數程式設計師一樣，Linux內核開發人員不喜歡花時間處理他們維護的原始碼中根本 +不會發生的問題的報告。這只會浪費每個人的時間，尤其是你的時間。不幸的是，當 +涉及到內核時，這樣的情況很容易發生，並且常常導致雙方氣餒。這是因爲幾乎所有預 +裝在設備（台式機、筆記本電腦、智慧型手機、路由器等）上的Linux內核，以及大多數 +由Linux發行商提供的內核，都與由kernel.org發行的官方Linux內核相距甚遠：從Linux +開發的角度來看，這些供應商提供的內核通常是古老的或者經過了大量修改，通常兩點 +兼具。 + +大多數供應商內核都不適合用來向Linux內核開發人員報告問題：您在其中遇到的問題 +可能已經由Linux內核開發人員在數月或數年前修復；此外，供應商的修改和增強可能 +會導致您面臨的問題，即使它們看起來很小或者完全不相關。這就是爲什麼您應該向 +供應商報告這些內核的問題。它的開發者應該查看報告，如果它是一個上游問題，直接 +於上游修復或將報告轉發到那裡。在實踐中，這有時行不通。因此，您可能需要考慮 +通過自己安裝最新的Linux內核內核來繞過供應商。如果如果您選擇此方法，那麼本指 +南後面的步驟將解釋如何在排除了其他可能導致您的問題的原因後執行此操作。 + +注意前段使用的詞語是「大多數」，因爲有時候開發人員實際上願意處理供應商內核出現 +的問題報告。他們是否這麼做很大程度上取決於開發人員和相關問題。如果發行版只 +根據最近的Linux版本對內核進行了較小修改，那麼機會就比較大；例如對於Debian +GNU/Linux Sid或Fedora Rawhide所提供的主線內核。一些開發人員還將接受基於最新 +穩定內核的發行版內核問題報告，只要它改動不大；例如Arch Linux、常規Fedora版本 +和openSUSE Turboweed。但是請記住，您最好使用主線Linux，並避免在此流程中使用 +穩定版內核，如「安裝一個新的內核進行測試」一節中所詳述。 + +當然，您可以忽略所有這些建議，並向上游Linux開發人員報告舊的或經過大量修改的 +供應商內核的問題。但是注意，這樣的報告經常被拒絕或忽視，所以自行小心考慮一下。 +不過這還是比根本不報告問題要好：有時候這樣的報告會直接或間接地幫助解決之後的 +問題。 + + +搜索現有報告（第一部分） +------------------------- + + *使用您喜愛的網絡搜尋引擎對現有報告進行粗略搜索；此外，請檢查Linux內核 + 郵件列表（LKML）的存檔。如果找到匹配的報告，請加入討論而不是發送新報告。* + +報告一個別人已經提出的問題，對每個人來說都是浪費時間，尤其是作爲報告人的你。 +所以徹底檢查是否有人已經報告了這個問題，這對你自己是有利的。在流程中的這一步， +可以只執行一個粗略的搜索：一旦您知道您的問題需要報告到哪裡，稍後的步驟將告訴 +您如何詳細搜索。儘管如此，不要倉促完成這一步，它可以節省您的時間和減少麻煩。 + +只需先用你最喜歡的搜尋引擎在網際網路上搜索。然後再搜索Linux內核郵件列表（LKML） +存檔。 + +如果搜索結果實在太多，可以考慮讓你的搜尋引擎將搜索時間範圍限制在過去的一個 +月或一年。而且無論你在哪裡搜索，一定要用恰當的搜索關鍵詞；也要變化幾次關鍵 +詞。同時，試著從別人的角度看問題：這將幫助你想出其他的關鍵詞。另外，一定不 +要同時使用過多的關鍵詞。記住搜索時要同時嘗試包含和不包含內核驅動程序的名稱 +或受影響的硬體組件的名稱等信息。但其確切的品牌名稱（比如說「華碩紅魔 Radeon +RX 5700 XT Gaming OC」）往往幫助不大，因爲它太具體了。相反，嘗試搜索術語，如 +型號（Radeon 5700 或 Radeon 5000）和核心代號（「Navi」或「Navi10」），以及包含 +和不包含其製造商（「AMD」）。 + +如果你發現了關於你的問題的現有報告，請加入討論，因爲你可能會提供有價值的額 +外信息。這一點很重要，即使是在修復程序已經準備好或處於最後階段，因爲開發人 +員可能會尋找能夠提供額外信息或測試建議修復程序的人。跳到「發布報告後的責任」 +一節，了解有關如何正確參與的細節。 + +注意，搜索 `bugzilla.kernel.org <https://bugzilla.kernel.org/>`_ 網站可能 +也是一個好主意，因爲這可能會提供有價值的見解或找到匹配的報告。如果您發現後者， +請記住：大多數子系統都希望在不同的位置報告，如下面「你需要將問題報告到何處」 +一節中所述。因此本應處理這個問題的開發人員甚至可能不知道bugzilla的工單。所以 +請檢查工單中的問題是否已經按照本文檔所述得到報告，如果沒有，請考慮這樣做。 + +高優先級的問題？ +----------------- + + *看看你正在處理的問題是否是回歸問題、安全問題或非常嚴重的問題：這些都是 + 需要在接下來的一些步驟中特別處理的「高優先級問題」。* + +Linus Torvalds和主要的Linux內核開發人員希望看到一些問題儘快得到解決，因此在 +報告過程中有一些「高優先級問題」的處理略有不同。有三種情況符合條件:回歸、安全 +問題和非常嚴重的問題。 + +如果在舊版本的Linux內核中工作的東西不能在新版本的Linux內核中工作，或者某種 +程度上在新版本的Linux內核中工作得更差，那麼你就需要處理「回歸」。因此，當一個 +在Linux 5.7中表現良好的WiFi驅動程序在5.8中表現不佳或根本不能工作時，這是一 +種回歸。如果應用程式在新的內核中出現不穩定的現象，這也是一種回歸，這可能是 +由於內核和用戶空間之間的接口（如procfs和sysfs）發生不兼容的更改造成的。顯著 +的性能降低或功耗增加也可以稱爲回歸。但是請記住:新內核需要使用與舊內核相似的 +配置來構建（參見下面如何實現這一點）。這是因爲內核開發人員在實現新特性時有 +時無法避免不兼容性；但是爲了避免回歸，這些特性必須在構建配置期間顯式地啓用。 + +什麼是安全問題留給您自己判斷。在繼續之前，請考慮閱讀 +「Documentation/translations/zh_TW/admin-guide/security-bugs.rst」， +因爲它提供了如何最恰當地處理安全問題的額外細節。 + +當發生了完全無法接受的糟糕事情時，此問題就是一個「非常嚴重的問題」。例如， +Linux內核破壞了它處理的數據或損壞了它運行的硬體。當內核突然顯示錯誤消息 +（「kernel panic」）並停止工作，或者根本沒有任何停止信息時，您也在處理一個嚴重 +的問題。注意：不要混淆「panic」（內核停止自身的致命錯誤）和「Oops」（可恢復錯誤）， +因爲顯示後者之後內核仍然在運行。 + + +確保環境健康 +-------------- + + *確保不是內核所處環境導致了你所面臨的問題。* + +看起來很像內核問題的問題有時是由構建或運行時環境引起的。很難完全排除這種問 +題，但你應該儘量減少這種問題： + + * 構建內核時，請使用經過驗證的工具，因爲編譯器或二進位文件中的錯誤可能會導 + 致內核出現錯誤行爲。 + + * 確保您的計算機組件在其設計規範內運行；這對處理器、內存和主板尤爲重要。因 + 此，當面臨潛在的內核問題時，停止低電壓或超頻。 + + * 儘量確保不是硬體故障導致了你的問題。例如，內存損壞會導致大量的問題，這些 + 問題會表現爲看起來像內核問題。 + + * 如果你正在處理一個文件系統問題，你可能需要用 ``fsck`` 檢查一下文件系統， + 因爲它可能會以某種方式被損壞，從而導致無法預期的內核行爲。 + + * 在處理回歸問題時，要確保沒有在更新內核的同時發生了其他變化。例如，這個問 + 題可能是由同時更新的其他軟體引起的。也有可能是在你第一次重啓進入新內核時， + 某個硬體巧合地壞了。更新系統 BIOS 或改變 BIOS 設置中的某些內容也會導致 + 一些看起來很像內核回歸的問題。 + + +爲緊急情況做好準備 +------------------- + + *創建一個全新的備份，並將系統修復和還原工具放在手邊* + +我得提醒您，您正在和計算機打交道，計算機有時會出現意想不到的事情，尤其是當 +您折騰其作業系統的內核等關鍵部件時。而這就是你在這個過程中要做的事情。因此， +一定要創建一個全新的備份；還要確保你手頭有修復或重裝作業系統的所有工具， +以及恢復備份所需的一切。 + + +確保你的內核不會被增強 +------------------------ + + *確保您的系統不會通過動態構建額外的內核模塊來增強其內核，像DKMS這樣的解 + 決方案可能在您不知情的情況下就在本地進行了這樣的工作。* + +如果內核以任何方式得到增強，那麼問題報告被忽略或拒絕的風險就會急劇增加。這就 +是爲什麼您應該刪除或禁用像akmods和DKMS這樣的機制：這些機制會自動構建額外內核 +模塊，例如當您安裝新的Linux內核或第一次引導它時。也要記得同時刪除他們可能安裝 +的任何模塊。然後重新啓動再繼續。 + +注意，你可能不知道你的系統正在使用這些解決方案之一：當你安裝 Nvidia 專有圖 +形驅動程序、VirtualBox 或其他需要 Linux 內核以外的模塊支持的軟體時，它們通 +常會靜默設置。這就是爲什麼你可能需要卸載這些軟體的軟體包，以擺脫任何第三方 +內核模塊。 + + +檢測「汙染」標誌 +---------------- + + *當問題發生時，檢查您的內核是否被「汙染」，因爲使內核設置這個標誌的事件可 + 能會導致您面臨的問題。* + +當某些可能會導致看起來完全不相關的後續錯誤的事情發生時，內核會用「汙染 +（taint）」標誌標記自己。如果您的內核受到汙染，那麼您面臨的可能是這樣的錯誤。 +因此在投入更多時間到這個過程中之前，儘早排除此情況可能對你有好處。這是這個 +步驟出現在這裡的唯一原因，因爲這個過程稍後會告訴您安裝最新的主線內核；然後 +您將需要再次檢查汙染標誌，因爲當它出問題的時候內核報告會關注它。 + +在正在運行的系統上檢查內核是否汙染非常容易：如果 ``cat /proc/sys/kernel/tainted`` +返回「0」，那麼內核沒有被汙染，一切正常。在某些情況下無法檢查該文件；這就是 +爲什麼當內核報告內部問題（「kernel bug」）、可恢復錯誤（「kernel Oops」）或停止 +操作前不可恢復的錯誤（「kernel panic」）時，它也會提到汙染狀態。當其中一個錯 +誤發生時，查看列印的錯誤消息的頂部，搜索以「CPU:」開頭的行。如果發現問題時內 +核未被汙染，那麼它應該以「Not infected」結束；如果你看到「Tainted:」且後跟一些 +空格和字母，那就被汙染了。 + +如果你的內核被汙染了，請閱讀「Documentation/translations/zh_TW/admin-guide/tainted-kernels.rst」 +以找出原因。設法消除汙染因素。通常是由以下三種因素之一引起的： + + 1. 發生了一個可恢復的錯誤（「kernel Oops」），內核汙染了自己，因爲內核知道在 + 此之後它可能會出現奇怪的行爲錯亂。在這種情況下，檢查您的內核或系統日誌， + 並尋找以下列文字開頭的部分:: + + Oops: 0000 [#1] SMP + + 如方括號中的「#1」所示，這是自啓動以來的第一次Oops。每個Oops和此後發生的 + 任何其他問題都可能是首個Oops的後續問題，即使這兩個問題看起來完全不相關。 + 通過消除首個Oops的原因並在之後復現該問題，可以排除這種情況。有時僅僅 + 重新啓動就足夠了，有時更改配置後重新啓動可以消除Oops。但是在這個流程中 + 不要花費太多時間在這一點上，因爲引起Oops的原因可能已經在您稍後將按流程 + 安裝的新Linux內核版本中修復了。 + + 2. 您的系統使用的軟體安裝了自己的內核模塊，例如Nvidia的專有圖形驅動程序或 + VirtualBox。當內核從外部源（即使它們是開源的）加載此類模塊時，它會汙染 + 自己：它們有時會在不相關的內核區域導致錯誤，從而可能導致您面臨的問題。 + 因此，當您想要向Linux內核開發人員報告問題時，您必須阻止這些模塊加載。 + 大多數情況下最簡單的方法是：臨時卸載這些軟體，包括它們可能已經安裝的任 + 何模塊。之後重新啓動。 + + 3. 當內核加載駐留在Linux內核原始碼staging樹中的模塊時，它也會汙染自身。這 + 是一個特殊的區域，代碼（主要是驅動程序）還沒有達到正常Linux內核的質量 + 標準。當您報告此種模塊的問題時，內核受到汙染顯然是沒有問題的；只需確保 + 問題模塊是造成汙染的唯一原因。如果問題發生在一個不相關的區域，重新啓動 + 並通過指定 ``foo.blacklist=1`` 作爲內核參數臨時阻止該模塊被加載（用有 + 問題的模塊名替換「foo」）。 + + +記錄如何重現問題 +------------------ + + *粗略地寫下如何重現這個問題。如果您同時處理多個問題，請爲每個問題單獨寫 + 注釋，並確保它們在新啓動的系統上獨立出現。這是必要的，因爲每個問題都需 + 要分別報告給內核開發人員，除非它們嚴重糾纏在一起。* + +如果你同時處理多個問題，必須分別報告每個問題，因爲它們可能由不同的開發人員 +處理。在一份報告中描述多種問題，也會讓其他人難以將其分開。因此只有在問題嚴 +重糾纏的情況下，才能將問題合併在一份報告中。 + +此外，在報告過程中，你必須測試該問題是否發生在其他內核版本上。因此，如果您 +知道如何在一個新啓動的系統上快速重現問題，將使您的工作更加輕鬆。 + +注意：報告只發生過一次的問題往往是沒有結果的，因爲它們可能是由於宇宙輻射導 +致的位翻轉。所以你應該嘗試通過重現問題來排除這種情況，然後再繼續。如果你有 +足夠的經驗來區分由於硬體故障引起的一次性錯誤和難以重現的罕見內核問題，可以 +忽略這個建議。 + + +穩定版或長期支持內核的回歸？ +----------------------------- + + *如果您正面臨穩定版或長期支持版本線的回歸（例如從5.10.4更新到5.10.5時出現 + 故障），請查看後文「報告穩定版和長期支持內核線的回歸」小節。* + +穩定版和長期支持內核版本線中的回歸是Linux開發人員非常希望解決的問題，這樣的 +問題甚至比主線開發分支中的回歸更不應出現，因爲它們會很快影響到很多人。開發人員 +希望儘快了解此類問題，因此有一個簡化流程來報告這些問題。注意，使用更新內核版 +本線的回歸（比如從5.9.15切換到5.10.5時出現故障）不符合條件。 + + +你需要將問題報告到何處 +------------------------ + + *定位可能引起問題的驅動程序或內核子系統。找出其開發人員期望的報告的方式 + 和位置。注意：大多數情況下不會是bugzilla.kernel.org，因爲問題通常需要通 + 過郵件發送給維護人員和公共郵件列表。* + +將報告發送給合適的人是至關重要的，因爲Linux內核是一個大項目，大多數開發人員 +只熟悉其中的一小部分。例如，相當多的程式設計師只關心一個驅動程序，比如一個WiFi +晶片驅動程序；它的開發人員可能對疏遠的或不相關的「子系統」（如TCP堆棧、 +PCIe/PCI子系統、內存管理或文件系統）的內部知識了解很少或完全不了解。 + +問題在於：Linux內核缺少一個，可以簡單地將問題歸檔並讓需要了解它的開發人員了 +解它的，中心化缺陷跟蹤器。這就是爲什麼你必須找到正確的途徑來自己報告問題。 +您可以在腳本的幫助下做到這一點（見下文），但它主要針對的是內核開發人員和專 +家。對於其他人來說，MAINTAINERS（維護人員）文件是更好的選擇。 + +如何閱讀MAINTAINERS維護者文件 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +爲了說明如何使用 :ref:`MAINTAINERS <maintainers>` 文件，讓我們假設您的筆記 +本電腦中的WiFi在更新內核後突然出現了錯誤行爲。這種情況下可能是WiFi驅動的問 +題。顯然，它也可能由於驅動基於的某些代碼，但除非你懷疑有這樣的東西會附著在 +驅動程序上。如果真的是其他的問題，驅動程序的開發人員會讓合適的人參與進來。 + +遺憾的是，沒有通用且簡單的辦法來檢查哪個代碼驅動了特定硬體組件。 + +在WiFi驅動出現問題的情況下，你可能想查看 ``lspci -k`` 的輸出，因爲它列出了 +PCI/PCIe總線上的設備和驅動它的內核模塊:: + + [user@something ~]$ lspci -k + [...] + 3a:00.0 Network controller: Qualcomm Atheros QCA6174 802.11ac Wireless Network Adapter (rev 32) + Subsystem: Bigfoot Networks, Inc. Device 1535 + Kernel driver in use: ath10k_pci + Kernel modules: ath10k_pci + [...] + +但如果你的WiFi晶片通過USB或其他內部總線連接，這種方法就行不通了。在這種情況 +下，您可能需要檢查您的WiFi管理器或 ``ip link`` 的輸出。尋找有問題的網絡接口 +的名稱，它可能類似於「wlp58s0」。此名稱可以用來找到驅動它的模塊:: + + [user@something ~]$ realpath --relative-to=/sys/module//sys/class/net/wlp58s0/device/driver/module + ath10k_pci + +如果這些技巧不能進一步幫助您，請嘗試在網上搜索如何縮小相關驅動程序或子系統 +的範圍。如果你不確定是哪一個：試著猜一下，即使你猜得不好，也會有人會幫助你 +的。 + +一旦您知道了相應的驅動程序或子系統，您就希望在MAINTAINERS文件中搜索它。如果 +是「ath10k_pci」，您不會找到任何東西，因爲名稱太具體了。有時你需要在網上尋找 +幫助；但在此之前，請嘗試使用一個稍短或修改過的名稱來搜索MAINTAINERS文件，因 +爲這樣你可能會發現類似這樣的東西:: + + QUALCOMM ATHEROS ATH10K WIRELESS DRIVER + Mail: A. Some Human <shuman@example.com> + Mailing list: ath10k@lists.infradead.org + Status: Supported + Web-page: https://wireless.wiki.kernel.org/en/users/Drivers/ath10k + SCM: git git://git.kernel.org/pub/scm/linux/kernel/git/kvalo/ath.git + Files: drivers/net/wireless/ath/ath10k/ + +注意：如果您閱讀在Linux原始碼樹的根目錄中找到的原始維護者文件，則行描述將是 +縮寫。例如，「Mail:（郵件）」將是「M:」，「Mailing list:（郵件列表）」將是「L」， +「Status:（狀態）」將是「S:」。此文件頂部有一段解釋了這些和其他縮寫。 + +首先查看「Status」狀態行。理想情況下，它應該得到「Supported（支持）」或 +「Maintained（維護）」。如果狀態爲「Obsolete（過時的）」，那麼你在使用一些過時的 +方法，需要轉換到新的解決方案上。有時候，只有在感到有動力時，才會有人爲代碼 +提供「Odd Fixes」。如果碰見「Orphan」，你就完全不走運了，因爲再也沒有人關心代碼 +了，只剩下這些選項:準備好與問題共存，自己修復它，或者找一個願意修復它的程式設計師。 + +檢查狀態後，尋找以「bug:」開頭的一行：它將告訴你在哪裡可以找到子系統特定的缺 +陷跟蹤器來提交你的問題。上面的例子沒有此行。大多數部分都是這樣，因爲 Linux +內核的開發完全是由郵件驅動的。很少有子系統使用缺陷跟蹤器，且其中只有一部分 +依賴於 bugzilla.kernel.org。 + +在這種以及其他很多情況下，你必須尋找以「Mail:」開頭的行。這些行提到了特定代碼 +的維護者的名字和電子郵件地址。也可以查找以「Mailing list:」開頭的行，它告訴你 +開發代碼的公共郵件列表。你的報告之後需要通過郵件發到這些地址。另外，對於所有 +通過電子郵件發送的問題報告，一定要抄送 Linux Kernel Mailing List（LKML） +<linux-kernel@vger.kernel.org>。在以後通過郵件發送問題報告時，不要遺漏任何 +一個郵件列表!維護者都是大忙人，可能會把一些工作留給子系統特定列表上的其他開 +發者；而 LKML 很重要，因爲需要一個可以找到所有問題報告的地方。 + + +藉助腳本找到維護者 +~~~~~~~~~~~~~~~~~~~~ + +對於手頭有Linux源碼的人來說，有第二個可以找到合適的報告地點的選擇：腳本 +「scripts/get_maintainer.pl」，它嘗試找到所有要聯繫的人。它會查詢MAINTAINERS +文件，並需要用相關原始碼的路徑來調用。對於編譯成模塊的驅動程序，經常可以用 +這樣的命令找到:: + + $ modinfo ath10k_pci | grep filename | sed 's!/lib/modules/.*/kernel/!!; s!filename:!!; s!\.ko\(\|\.xz\)!!' + drivers/net/wireless/ath/ath10k/ath10k_pci.ko + +將其中的部分內容傳遞給腳本:: + + $ ./scripts/get_maintainer.pl -f drivers/net/wireless/ath/ath10k* + Some Human <shuman@example.com> (supporter:QUALCOMM ATHEROS ATH10K WIRELESS DRIVER) + Another S. Human <asomehuman@example.com> (maintainer:NETWORKING DRIVERS) + ath10k@lists.infradead.org (open list:QUALCOMM ATHEROS ATH10K WIRELESS DRIVER) + linux-wireless@vger.kernel.org (open list:NETWORKING DRIVERS (WIRELESS)) + netdev@vger.kernel.org (open list:NETWORKING DRIVERS) + linux-kernel@vger.kernel.org (open list) + +不要把你的報告發給所有的人。發送給維護者，腳本稱之爲「supporter:」；另外抄送 +代碼最相關的郵件列表，以及 Linux 內核郵件列表（LKML）。在此例中，你需要將報 +告發送給 「Some Human <shuman@example.com>」 ，並抄送 +「ath10k@lists.infradead.org」和「linux-kernel@vger.kernel.org」。 + +注意：如果你用 git 克隆了 Linux 原始碼，你可能需要用--git 再次調用 +get_maintainer.pl。腳本會查看提交歷史，以找到最近哪些人參與了相關代碼的編寫， +因爲他們可能會提供幫助。但要小心使用這些結果，因爲它很容易讓你誤入歧途。 +例如，這種情況常常會發生在很少被修改的地方（比如老舊的或未維護的驅動程序）： +有時這樣的代碼會在樹級清理期間被根本不關心此驅動程序的開發者修改。 + + +搜索現有報告（第二部分） +-------------------------- + + *在缺陷追蹤器或問題相關郵件列表的存檔中徹底搜索可能與您的問題匹配的報告。 + 如果找到匹配的報告，請加入討論而不是發送新報告。* + +如前所述：報告一個別人已經提出的問題，對每個人來說都是浪費時間，尤其是作爲報告 +人的你。這就是爲什麼你應該再次搜索現有的報告。現在你已經知道問題需要報告到哪裡。 +如果是郵件列表，那麼一般在 `lore.kernel.org <https://lore.kernel.org/>`_ 可以 +找到相應存檔。 + +但有些列表運行在其他地方。例如前面步驟中當例子的ath10k WiFi驅動程序就是這種 +情況。但是你通常可以在網上很容易地找到這些列表的檔案。例如搜索「archive +ath10k@lists.infradead.org」，將引導您到ath10k郵件列表的信息頁，該頁面頂部連結 +到其 `列表存檔 <https://lists.infradead.org/pipermail/ath10k/>`_ 。遺憾的是， +這個列表和其他一些列表缺乏搜索其存檔的功能。在這種情況下可以使用常規的網際網路 +搜尋引擎，並添加類似「site:lists.infadead.org/pipermail/ath10k/」這 +樣的搜索條件，這會把結果限制在該連結中的檔案。 + +也請進一步搜索網絡、LKML和bugzilla.kernel.org網站。 + +有關如何搜索以及在找到匹配報告時如何操作的詳細信息，請參閱上面的「搜索現有報告 +（第一部分）」。 + +不要急著完成報告過程的這一步：花30到60分鐘甚至更多的時間可以爲你和其他人節省 / +減少相當多的時間和麻煩。 + + +安裝一個新的內核進行測試 +-------------------------- + + *除非您已經在運行最新的「主線」Linux內核，否則最好在報告流程前安裝它。在 + 某些情況下，使用最新的「穩定版」Linux進行測試和報告也是可以接受的替代方案； + 在合併窗口期間，這實際上可能是最好的方法，但在開發階段最好還是暫停幾天。 + 無論你選擇什麼版本，最好使用「普通」構建。忽略這些建議會大大增加您的報告 + 被拒絕或忽略的風險。* + +正如第一步的詳細解釋中所提到的：與大多數程式設計師一樣，與大多數程式設計師一樣，Linux +內核開發人員不喜歡花時間處理他們維護的原始碼中根本不會發生的問題的報告。這隻 +會浪費每個人的時間，尤其是你的時間。這就是爲什麼在報告問題之前，您必須先確認 +問題仍然存在於最新的上游代碼中，這符合每個人的利益。您可以忽略此建議，但如前 +所述：這樣做會極大地增加問題報告被拒絕或被忽略的風險。 + +內核「最新上游」的範圍通常指： + + * 安裝一個主線內核；最新的穩定版內核也可以是一個選擇，但大多數時候都最好避免。 + 長期支持內核（有時稱爲「LTS內核」）不適合此流程。下一小節將更詳細地解釋所有 + 這些。 + + * 下一小節描述獲取和安裝這樣一個內核的方法。它還指出了使用預編譯內核是可以的， + 但普通的內核更好，這意味著：它是直接使用從 `kernel.org <https://kernel.org/>`_ + 獲得的Linux原始碼構建並且沒有任何方式修改或增強。 + + +選擇適合測試的版本 +~~~~~~~~~~~~~~~~~~~~ + +前往 `kernel.org <https://kernel.org/>`_ 來決定使用哪個版本。忽略那個寫著 +「Latest release最新版本」的巨大黃色按鈕，往下看有一個表格。在表格的頂部，你會 +看到一行以「mainline」開頭的字樣，大多數情況下它會指向一個版本號類似「5.8-rc2」 +的預發布版本。如果是這樣的話，你將需要使用這個主線內核進行測試。不要讓「rc」 +嚇到你，這些「開發版內核」實際上非常可靠——而且你已經按照上面的指示做了備份， +不是嗎？ + +大概每九到十周，「mainline」可能會給你指出一個版本號類似「5.7」的正式版本。如果 +碰見這種情況，請考慮暫停報告過程，直到下一個版本的第一個預發布（5.8-rc1）出 +現在 `kernel.org <https://kernel.org/>`_ 上。這是因爲 Linux 的開發周期正在 +兩周的「合併窗口」內。大部分的改動和所有干擾性的改動都會在這段時間內被合併到 +下一個版本中。在此期間使用主線是比較危險的。內核開發者通常也很忙，可能沒有 +多餘的時間來處理問題報告。這也是很有可能在合併窗口中應用了許多修改來修復你 +所面臨的問題；這就是爲什麼你很快就得用一個新的內核版本重新測試，就像下面「發 +布報告後的責任」一節中所述的那樣。 + +這就是爲什麼要等到合併窗口結束後才去做。但是如果你處理的是一些不應該等待的 +東西，則無需這樣做。在這種情況下，可以考慮通過 git 獲取最新的主線內核（見下 +文），或者使用 kernel.org 上提供的最新穩定版本。如果 mainline 因爲某些原因 +不無法正常工作，那麼使用它也是可以接受的。總的來說：用它來重現問題也比完全 +不報告問題要好。 + +最好避免在合併窗口外使用最新的穩定版內核，因爲所有修復都必須首先應用於主線。 +這就是爲什麼檢查最新的主線內核是如此重要：你希望看到在舊版本線修復的任何問題 +需要先在主線修復，然後才能得到回傳，這可能需要幾天或幾周。另一個原因是：您 +希望的修復對於回傳來說可能太難或太冒險；因此再次報告問題不太可能改變任何事情。 + +這些方面也部分表明了爲什麼長期支持內核（有時稱爲「LTS內核」）不適合報告流程： +它們與當前代碼的距離太遠。因此，先去測試主線，然後再按流程走：如果主線沒有 +出現問題，流程將指導您如何在舊版本線中修復它。 + +如何獲得新的 Linux 內核 +~~~~~~~~~~~~~~~~~~~~~~~~~ + +你可以使用預編譯或自編譯的內核進行測試；如果你選擇後者，可以使用 git 獲取源 +代碼，或者下載其 tar 存檔包。 + +**使用預編譯的內核** ：這往往是最快速、最簡單、最安全的方法——尤其是在你不熟 +悉 Linux 內核的情況下。問題是：發行商或附加存儲庫提供的大多數版本都是從修改 +過的Linux原始碼構建的。因此它們不是普通的，通常不適合於測試和問題報告：這些 +更改可能會導致您面臨的問題或以某種方式影響問題。 + +但是如果您使用的是流行的Linux發行版，那麼您就很幸運了：對於大部分的發行版， +您可以在網上找到包含最新主線或穩定版本Linux內核包的存儲庫。使用這些是完全可 +以的，只要從存儲庫的描述中確認它們是普通的或者至少接近普通。此外，請確保軟體 +包包含kernel.org上提供的最新版本內核。如果這些軟體包的時間超過一周，那麼它們 +可能就不合適了，因爲新的主線和穩定版內核通常至少每周發布一次。 + +請注意，您以後可能需要手動構建自己的內核：有時這是調試或測試修復程序所必需的， +如後文所述。還要注意，預編譯的內核可能缺少在出現panic、Oops、warning或BUG時 +解碼內核列印的消息所需的調試符號；如果您計劃解碼這些消息，最好自己編譯內核 +（有關詳細信息，請參閱本小節結尾和「解碼失敗信息」小節）。 + +**使用git** ：熟悉 git 的開發者和有經驗的 Linux 用戶通常最好直接從 +`kernel.org 上的官方開發倉庫 +<https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/>`_ +中獲取最新的 Linux 內核原始碼。這些很可能比最新的主線預發布版本更新一些。不 +用擔心：它們和正式的預發布版本一樣可靠，除非內核的開發周期目前正處於合併窗 +口中。不過即便如此，它們也是相當可靠的。 + +**常規方法** ：不熟悉 git 的人通常最好從 `kernel.org <https://kernel.org/>`_ +下載源碼的tar 存檔包。 + +如何實際構建一個內核並不在這裡描述，因爲許多網站已經解釋了必要的步驟。如果 +你是新手，可以考慮按照那些建議使用 ``make localmodconfig`` 來做，它將嘗試獲 +取你當前內核的配置，然後根據你的系統進行一些調整。這樣做並不能使編譯出來的 +內核更好，但可以更快地編譯。 + +注意：如果您正在處理來自內核的pannc、Oops、warning或BUG，請在配置內核時嘗試 +啓用 CONFIG_KALLSYMS 選項。此外，還可以啓用 CONFIG_DEBUG_KERNEL 和 +CONFIG_DEBUG_INFO；後者是相關選項，但只有啓用前者才能開啓。請注意， +CONFIG_DEBUG_INFO 會需要更多儲存空間來構建內核。但這是值得的，因爲這些選項將 +允許您稍後精確定位觸發問題的確切代碼行。下面的「解碼失敗信息」一節對此進行了更 +詳細的解釋。 + +但請記住：始終記錄遇到的問題，以防難以重現。發送未解碼的報告總比不報告要好。 + + +檢查「汙染」標誌 +---------------- + + *確保您剛剛安裝的內核在運行時不會「汙染」自己。* + +正如上面已經詳細介紹過的：當發生一些可能會導致一些看起來完全不相關的後續錯 +誤的事情時，內核會設置一個「汙染」標誌。這就是爲什麼你需要檢查你剛剛安裝的內 +核是否有設置此標誌。如果有的話，幾乎在任何情況下你都需要在報告問題之前先消 +除它。詳細的操作方法請看上面的章節。 + + +用新內核重現問題 +------------------ + + *在您剛剛安裝的內核中復現這個問題。如果它沒有出現，請查看下方只發生在 + 穩定版和長期支持內核的問題的說明。* + +檢查這個問題是否發生在你剛剛安裝的新 Linux 內核版本上。如果新內核已經修復了， +可以考慮使用此版本線，放棄報告問題。但是請記住，只要它沒有在 `kernel.org +<https://kernel.org/>`_ 的穩定版和長期版（以及由這些版本衍生出來的廠商內核） +中得到修復，其他用戶可能仍然會受到它的困擾。如果你喜歡使用其中的一個，或 +者只是想幫助它們的用戶，請前往下面的「報告只發生在較舊內核版本線的問題」一節。 + + +優化復現問題的描述 +-------------------- + + *優化你的筆記：試著找到並寫出最直接的復現問題的方法。確保最終結果包含所 + 有重要的細節，同時讓第一次聽說的人容易閱讀和理解。如果您在此過程中學到 + 了一些東西，請考慮再次搜索關於該問題的現有報告。* + +過於複雜的報告會讓別人很難理解。因此請儘量找到一個可以直接描述、易於以書面 +形式理解的再現方法。包含所有重要的細節，但同時也要儘量保持簡短。 + +在這在前面的步驟中，你很可能已經了解了一些關於你所面臨的問題的點。利用這些 +知識，再次搜索可以轉而加入的現有報告。 + + +解碼失敗信息 +------------- + + *如果失敗涉及「panic」、「Oops」、「warning」或「BUG」，請考慮解碼內核日誌以查找 + 觸發錯誤的代碼行。* + +當內核檢測到內部問題時，它會記錄一些有關已執行代碼的信息。這使得在原始碼中精 +確定位觸發問題的行並顯示如何調用它成爲可能。但只有在配置內核時啓用了 +CONFIG_DEBUG_INFO 和 CONFIG_KALLSYMS選項時，這種方法才起效。如果已啓用此選項， +請考慮解碼內核日誌中的信息。這將使我們更容易理解是什麼導致了「panic」、「Oops」、 +「warning」或「BUG」，從而增加了有人提供修復的機率。 + +解碼可以通過Linux原始碼樹中的腳本來完成。如果您運行的內核是之前自己編譯的， +這樣這樣調用它:: + + [user@something ~]$ sudo dmesg | ./linux-5.10.5/scripts/decode_stacktrace.sh ./linux-5.10.5/vmlinux + /usr/lib/debug/lib/modules/5.10.10-4.1.x86_64/vmlinux /usr/src/kernels/5.10.10-4.1.x86_64/ + +如果您運行的是打包好的普通內核，則可能需要安裝帶有調試符號的相應包。然後按以下 +方式調用腳本（如果發行版未打包，則可能需要從Linux原始碼獲取）:: + + [user@something ~]$ sudo dmesg | ./linux-5.10.5/scripts/decode_stacktrace.sh \ + /usr/lib/debug/lib/modules/5.10.10-4.1.x86_64/vmlinux /usr/src/kernels/5.10.10-4.1.x86_64/ + +腳本將解碼如下的日誌行，這些日誌行顯示內核在發生錯誤時正在執行的代碼的地址:: + + [ 68.387301] RIP: 0010:test_module_init+0x5/0xffa [test_module] + +解碼之後，這些行將變成這樣:: + + [ 68.387301] RIP: 0010:test_module_init (/home/username/linux-5.10.5/test-module/test-module.c:16) test_module + +在本例中，執行的代碼是從文件「~/linux-5.10.5/test-module/test-module.c」構建的， +錯誤出現在第16行的指令中。 + +該腳本也會如此解碼以「Call trace」開頭的部分中提到的地址，該部分顯示出現問題的 +函數的路徑。此外，腳本還會顯示內核正在執行的代碼部分的彙編輸出。 + +注意，如果你沒法做到這一點，只需跳過這一步，並在報告中說明原因。如果你幸運的 +話，可能無需解碼。如果需要的話，也許有人會幫你做這件事情。還要注意，這只是解 +碼內核堆棧跟蹤的幾種方法之一。有時需要採取不同的步驟來檢索相關的詳細信息。 +別擔心，如果您碰到的情況需要這樣做，開發人員會告訴您該怎麼做。 + + +對回歸的特別關照 +----------------- + + *如果您的問題是回歸問題，請儘可能縮小引入問題時的範圍。* + +Linux 首席開發者 Linus Torvalds 認爲 Linux 內核永遠不應惡化，這就是爲什麼他 +認爲回歸是不可接受的，並希望看到它們被迅速修復。這就是爲什麼引入了回歸的改 +動導致的問題若無法通過其他方式快速解決，通常會被迅速撤銷。因此，報告回歸有 +點像「王炸」，會迅速得到修復。但要做到這一點，需要知道導致回歸的變化。通常情 +況下，要由報告者來追查罪魁禍首，因爲維護者往往沒有時間或手頭設置不便來自行 +重現它。 + +有一個叫做「二分」的過程可以來尋找變化，這在 +「Documentation/translations/zh_TW/admin-guide/bug-bisect.rst」文檔中進行了詳細 +的描述，這個過程通常需要你構建十到二十個內核鏡像，每次都嘗試在構建下一個鏡像 +之前重現問題。是的，這需要花費一些時間，但不用擔心，它比大多數人想像的要快得多。 +多虧了「binary search二進位搜索」，這將引導你在原始碼管理系統中找到導致回歸的提交。 +一旦你找到它，就在網上搜索其主題、提交ID和縮短的提交ID（提交ID的前12個字符）。 +如果有的話，這將引導您找到關於它的現有報告。 + +需要注意的是，二分法需要一點竅門，不是每個人都懂得訣竅，也需要相當多的努力， +不是每個人都願意投入。儘管如此，還是強烈建議自己進行一次二分。如果你真的 +不能或者不想走這條路，至少要找出是哪個主線內核引入的回歸。比如說從 5.5.15 +切換到 5.8.4 的時候出現了一些問題，那麼至少可以嘗試一下相近的所有的主線版本 +（5.6、5.7 和 5.8）來檢查它是什麼時候出現的。除非你想在一個穩定版或長期支持 +內核中找到一個回歸，否則要避免測試那些編號有三段的版本（5.6.12、5.7.8），因 +爲那會使結果難以解釋，可能會讓你的測試變得無用。一旦你找到了引入回歸的主要 +版本，就可以放心地繼續報告了。但請記住：在不知道罪魁禍首的情況下，開發人員 +是否能夠提供幫助取決於手頭的問題。有時他們可能會從報告中確認是什麼出現了問 +題，並能修復它；有時他們可能無法提供幫助，除非你進行二分。 + +當處理回歸問題時，請確保你所面臨的問題真的是由內核引起的，而不是由其他東西 +引起的，如上文所述。 + +在整個過程中，請記住：只有當舊內核和新內核的配置相似時，問題才算回歸。最好 +的方法是：把配置文件（``.config``）從舊的工作內核直接複製到你嘗試的每個新內 +核版本。之後運行 ``make oldnoconfig`` 來調整它以適應新版本的需要，而不啓用 +任何新的功能，因爲那些功能也可能導致回歸。 + + +撰寫並發送報告 +--------------- + + *通過詳細描述問題來開始編寫報告。記得包括以下條目：您爲復現而安裝的最新 + 內核版本、使用的Linux發行版以及關於如何復現該問題的說明。如果可能，將內 + 核構建配置（.config）和 ``dmesg`` 的輸出放在網上的某個地方，並連結到它。 + 包含或上傳所有其他可能相關的信息，如Oops的輸出/截圖或來自 ``lspci`` + 的輸出。一旦你寫完了這個主要部分，請在上方插入一個正常長度的段落快速概 + 述問題和影響。再在此之上添加一個簡單描述問題的句子，以得到人們的閱讀。 + 現在給出一個更短的描述性標題或主題。然後就可以像MAINTAINERS文件告訴你的 + 那樣發送或提交報告了，除非你在處理一個「高優先級問題」：它們需要按照下面 + 「高優先級問題的特殊處理」所述特別關照。* + +現在你已經準備好了一切，是時候寫你的報告了。上文前言中連結的三篇文檔對如何 +寫報告做了部分解釋。這就是爲什麼本文將只提到一些基本的內容以及 Linux 內核特 +有的東西。 + +有一點是符合這兩類的：你的報告中最關鍵的部分是標題/主題、第一句話和第一段。 +開發者經常會收到許多郵件。因此，他們往往只是花幾秒鐘的時間瀏覽一下郵件，然 +後再決定繼續下一封或仔細查看。因此，你報告的開頭越好，有人研究並幫助你的機 +會就越大。這就是爲什麼你應該暫時忽略他們，先寫出詳細的報告。;-) + +每份報告都應提及的事項 +~~~~~~~~~~~~~~~~~~~~~~~~ + +詳細描述你的問題是如何發生在你安裝的新純淨內核上的。試著包含你之前寫的和優 +化過的分步說明，概述你和其他人如何重現這個問題；在極少數無法重現的情況下， +儘量描述你做了什麼來觸發它。 + +還應包括其他人爲了解該問題及其環境而可能需要的所有相關信息。實際需要的東西 +在很大程度上取決於具體問題，但有些事項你總是應該包括在內： + + * ``cat /proc/version`` 的輸出，其中包含 Linux 內核版本號和構建時的編譯器。 + + * 機器正在運行的 Linux 發行版（ ``hostnamectl | grep 「Operating System「`` ） + + * CPU 和作業系統的架構（ ``uname -mi`` ） + + * 如果您正在處理回歸，並進行了二分，請提及導致回歸的變更的主題和提交ID。 + +許多情況下，讓讀你報告的人多了解兩件事也是明智之舉： + + * 用於構建 Linux 內核的配置（「.config」文件） + + * 內核的信息，你從 ``dmesg`` 得到的信息寫到一個文件里。確保它以像「Linux + version 5.8-1 (foobar@example.com) (gcc (GCC) 10.2.1, GNU ld version + 2.34) #1 SMP Mon Aug 3 14:54:37 UTC 2020」這樣的行開始，如果沒有，那麼第 + 一次啓動階段的重要信息已經被丟棄了。在這種情況下，可以考慮使用 + ``journalctl -b 0 -k`` ；或者你也可以重啓，重現這個問題，然後調用 + ``dmesg`` 。 + +這兩個文件很大，所以直接把它們放到你的報告中是個壞主意。如果你是在缺陷跟蹤 +器中提交問題，那麼將它們附加到工單中。如果你通過郵件報告問題，不要用附件附 +上它們，因爲那會使郵件變得太大，可以按下列之一做： + + * 將文件上傳到某個公開的地方（你的網站，公共文件粘貼服務，在 + `bugzilla.kernel.org <https://bugzilla.kernel.org/>`_ 上創建的工單……）， + 並在你的報告中放上連結。理想情況下請使用允許這些文件保存很多年的地方，因 + 爲它們可能在很多年後對別人有用；例如 5 年或 10 年後，一個開發者正在修改 + 一些代碼，而這些代碼正是爲了修復你的問題。 + + * 把文件放在一邊，然後說明你會在他人回復時再單獨發送。只要記得報告發出去後， + 真正做到這一點就可以了。;-) + +提供這些東西可能是明智的 +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +根據問題的不同，你可能需要提供更多的背景數據。這裡有一些關於提供什麼比較好 +的建議： + + * 如果你處理的是內核的「warning」、「OOPS」或「panic」，請包含它。如果你不能複製 + 粘貼它，試著用netconsole網絡終端遠程跟蹤或者至少拍一張屏幕的照片。 + + * 如果問題可能與你的電腦硬體有關，請說明你使用的是什麼系統。例如，如果你的 + 顯卡有問題，請提及它的製造商，顯卡的型號，以及使用的晶片。如果是筆記本電 + 腦，請提及它的型號名稱，但儘量確保意義明確。例如「戴爾 XPS 13」就不很明確， + 因爲它可能是 2012 年的那款，那款除了看起來和現在銷售的沒有什麼不同之外， + 兩者沒有任何共同之處。因此，在這種情況下，要加上準確的型號，例如 2019 + 年內推出的 XPS 13 型號爲「9380」或「7390」。像「聯想 Thinkpad T590」這樣的名字 + 也有些含糊不清：這款筆記本有帶獨立顯卡和不帶的子型號，所以要儘量找到準確 + 的型號名稱或註明主要部件。 + + * 說明正在使用的相關軟體。如果你在加載模塊時遇到了問題，你要說明正在使用的 + kmod、systemd 和 udev 的版本。如果其中一個 DRM 驅動出現問題，你要說明 + libdrm 和 Mesa 的版本；還要說明你的 Wayland 合成器或 X-Server 及其驅動。 + 如果你有文件系統問題，請註明相應的文件系統實用程序的版本（e2fsprogs, + btrfs-progs, xfsprogs……）。 + + * 從內核中收集可能有用的額外信息。例如， ``lspci -nn`` 的輸出可以幫助別人 + 識別你使用的硬體。如果你的硬體有問題，你甚至可以給出 ``sudo lspci -vvv`` + 的結果，因爲它提供了組件是如何配置的信息。對於一些問題，可能最好包含 + ``/proc/cpuinfo`` ， ``/proc/ioports`` ， ``/proc/iomem`` ， + ``/proc/modules`` 或 ``/proc/scsi/scsi`` 等文件的內容。一些子系統還提 + 供了收集相關信息的工具。 ``alsa-info.sh`` `就是這樣一個工具，它是音頻/聲 + 音子系統開發者提供的 <https://www.alsa-project.org/wiki/AlsaInfo>`_ 。 + +這些例子應該會給你一些知識點，讓你知道附上什麼數據可能是明智的，但你自己也 +要想一想，哪些數據對別人會有幫助。不要太擔心忘記一些東西，因爲開發人員會要 +求提供他們需要的額外細節。但從一開始就把所有重要的東西都提供出來，會增加別 +人仔細查看的機會。 + + +重要部分：報告的開頭 +~~~~~~~~~~~~~~~~~~~~~~ + +現在你已經準備好了報告的詳細部分，讓我們進入最重要的部分：開頭幾句。現在到 +報告的最前面，在你剛才寫的部分之前加上類似「The detailed description:」（詳細 +描述）這樣的內容，並在最前面插入兩個新行。現在寫一個正常長度的段落，大致概 +述這個問題。去掉所有枯燥的細節，把重點放在讀者需要知道的關鍵部分，以讓人了 +解這是怎麼回事；如果你認爲這個缺陷影響了很多用戶，就提一下這點來吸引大家關 +注。 + +做好這一點後，在頂部再插入兩行，寫一句話的摘要，快速解釋報告的內容。之後你 +要更加抽象，爲報告寫一個更短的主題/標題。 + +現在你已經寫好了這部分，請花點時間來優化它，因爲它是你的報告中最重要的部分： +很多人會先讀這部分，然後才會決定是否值得花時間閱讀其他部分。 + +現在就像 :ref:`MAINTAINERS <maintainers>` 維護者文件告訴你的那樣發送或提交 +報告，除非它是前面概述的那些「高優先級問題」之一：在這種情況下，請先閱讀下一 +小節，然後再發送報告。 + +高優先級問題的特殊處理 +~~~~~~~~~~~~~~~~~~~~~~~~ + +高優先級問題的報告需要特殊處理。 + +**非常嚴重的缺陷** ：確保在主題或工單標題以及第一段中明顯標出 severeness +（非常嚴重的）。 + +**回歸** ：如果問題是一個回歸，請在郵件的主題或缺陷跟蹤器的標題中添加 +[REGRESSION]。如果您沒有進行二分，請至少註明您測試的最新主線版本（比如 5.7） +和出現問題的最新版本（比如 5.8）。如果您成功地進行了二分，請註明導致回歸 +的提交ID和主題。也請添加該變更的作者到你的報告中；如果您需要將您的缺陷提交 +到缺陷跟蹤器中，請將報告以私人郵件的形式轉發給他，並註明報告提交地點。 + +**安全問題** ：對於這種問題，你將必須評估：如果細節被公開披露，是否會對其他 +用戶產生短期風險。如果不會，只需按照所述繼續報告問題。如果有此風險，你需要 +稍微調整一下報告流程。 + + * 如果 MAINTAINERS 文件指示您通過郵件報告問題，請不要抄送任何公共郵件列表。 + + * 如果你應該在缺陷跟蹤器中提交問題，請確保將工單標記爲「私有」或「安全問題」。 + 如果缺陷跟蹤器沒有提供保持報告私密性的方法，那就別想了，把你的報告以私人 + 郵件的形式發送給維護者吧。 + +在這兩種情況下，都一定要將報告發到 MAINTAINERS 文件中「安全聯絡」部分列出的 +地址。理想的情況是在發送報告的時候直接抄送他們。如果您在缺陷跟蹤器中提交了 +報告，請將報告的文本轉發到這些地址；但請在報告的頂部加上注釋，表明您提交了 +報告，並附上工單連結。 + +更多信息請參見「Documentation/translations/zh_TW/admin-guide/security-bugs.rst」。 + + +發布報告後的責任 +------------------ + + *等待別人的反應，繼續推進事情，直到你能夠接受這樣或那樣的結果。因此，請 + 公開和及時地回應任何詢問。測試提出的修復。積極地測試：至少重新測試每個 + 新主線版本的首個候選版本（RC），並報告你的結果。如果出現拖延，就友好地 + 提醒一下。如果你沒有得到任何幫助或者未能滿意，請試著自己幫助自己。* + +如果你的報告非常優秀，而且你真的很幸運，那麼某個開發者可能會立即發現導致問 +題的原因；然後他們可能會寫一個補丁來修復、測試它，並直接發送給主線集成，同 +時標記它以便以後回溯到需要它的穩定版和長期支持內核。那麼你需要做的就是回復 +一句「Thank you very much」（非常感謝），然後在發布後換上修復好的版本。 + +但這種理想狀況很少發生。這就是爲什麼你把報告拿出來之後工作才開始。你要做的 +事情要視情況而定，但通常會是下面列出的事情。但在深入研究細節之前，這裡有幾 +件重要的事情，你需要記住這部分的過程。 + + +關於進一步互動的一般建議 +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +**總是公開回復** ：當你在缺陷跟蹤器中提交問題時，一定要在那裡回復，不要私下 +聯繫任何開發者。對於郵件報告，在回復您收到的任何郵件時，總是使用「全部回復」 +功能。這包括帶有任何你可能想要添加到你的報告中的額外數據的郵件：進入郵件應 +用程序「已發送」文件夾，並在郵件上使用「全部回復」來回復報告。這種方法可以確保 +公共郵件列表和其他所有參與者都能及時了解情況；它還能保持郵件線程的完整性， +這對於郵件列表將所有相關郵件歸爲一類是非常重要的。 + +只有兩種情況不適合在缺陷跟蹤器或「全部回復」中發表評論： + + * 有人讓你私下發東西。 + + * 你被告知要發送一些東西，但注意到其中包含需要保密的敏感信息。在這種情況下， + 可以私下發送給要求發送的開發者。但要在工單或郵件中註明你是這麼做的，這 + 樣其他人就知道你尊重了這個要求。 + +**在請求解釋或幫助之前先研究一下** ：在這部分過程中，有人可能會告訴你用尚未 +掌握的技能做一些事情。例如你可能會被要求使用一些你從未聽說過的測試工具；或 +者你可能會被要求在 Linux 內核原始碼上應用一個補丁來測試它是否有幫助。在某些 +情況下，發個回復詢問如何做就可以了。但在走這條路之前，儘量通過在網際網路上搜 +索自行找到答案；或者考慮在其他地方詢問建議。比如詢問朋友，或者到你平時常去 +的聊天室或論壇發帖諮詢。 + +**要有耐心** ：如果你真的很幸運，你可能會在幾個小時內收到對你的報告的答覆。 +但大多數情況下會花費更多的時間，因爲維護者分散在全球各地，因此可能在不同的 +時區——在那裡他們已經享受著遠離鍵盤的夜晚。 + +一般來說，內核開發者需要一到五個工作日來回復報告。有時會花費更長的時間，因 +爲他們可能正忙於合併窗口、其他工作、參加開發者會議，或者只是在享受一個漫長 +的暑假。 + +「高優先級的問題」（見上面的解釋）例外：維護者應該儘快解決這些問題；這就是爲 +什麼你應該最多等待一個星期（如果是緊急的事情，則只需兩天），然後再發送友好 +的提醒。 + +有時維護者可能沒有及時回復；有時候可能會出現分歧，例如一個問題是否符合回歸 +的條件。在這種情況下，在郵件列表上提出你的顧慮，並請求其他人公開或私下回復 +如何繼續推進。如果失敗了，可能應該讓更高級別的維護者介入。如果是 WiFi 驅動， +那就是無線維護者；如果沒有更高級別的維護者，或者其他一切努力都失敗了，那 +這可能是一種罕見的、可以讓 Linus Torvalds 參與進來的情況。 + +**主動測試** ：每當一個新的主線內核版本的第一個預發布版本（rc1）發布的時候， +去檢查一下這個問題是否得到了解決，或者是否有什麼重要的變化。在工單中或在 +回復報告的郵件中提及結果（確保所有參與討論的人都被抄送）。這將表明你的承諾 +和你願意幫忙。如果問題持續存在，它也會提醒開發者確保他們不會忘記它。其他一 +些不定期的重新測試（例如用rc3、rc5 和最終版本）也是一個好主意，但只有在相關 +的東西發生變化或者你正在寫什麼東西的時候才報告你的結果。 + +這些些常規的事情就不說了，我們來談談報告後如何幫助解決問題的細節。 + +查詢和測試請求 +~~~~~~~~~~~~~~~ + +如果你的報告得到了回復則需履行以下責任： + +**檢查與你打交道的人** ：大多數情況下，會是維護者或特定代碼區域的開發人員對 +你的報告做出回應。但由於問題通常是公開報告的，所以回復的可能是任何人——包括 +那些想要幫忙的人，但最後可能會用他們的問題或請求引導你完全偏離軌道。這很少 +發生，但這是快速上網搜搜看你正在與誰互動是明智之舉的許多原因之一。通過這樣 +做，你也可以知道你的報告是否被正確的人聽到，因爲如果討論沒有導致滿意的問題 +解決方案而淡出，之後可能需要提醒維護者（見下文）。 + +**查詢數據** ：通常你會被要求測試一些東西或提供更多細節。儘快提供所要求的信 +息，因爲你已經得到了可能會幫助你的人的注意，你等待的時間越長就有越可能失去 +關注；如果你不在數個工作日內提供信息，甚至可能出現這種結果。 + +**測試請求** ：當你被要求測試一個診斷補丁或可能的修復時，也要儘量及時測試。 +但要做得恰當，一定不要急於求成：混淆事情很容易發生，這會給所有人帶來許多困 +惑。例如一個常見的錯誤是以爲應用了一個帶修復的建議補丁，但事實上並沒有。即 +使是有經驗的測試人員也會偶爾發生這樣的事情，但當有修復的內核和沒有修復的內 +核表現得一樣時，他們大多時候會注意到。 + +當沒有任何實質性進展時該怎麼辦 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +有些報告不會得到負有相關責任的 Linux 內核開發者的任何反應；或者圍繞這個問題 +的討論有所發展，但漸漸淡出，沒有任何實質內容產出。 + +在這種情況下，要等兩個星期（最好是三個星期）後再發出友好的提醒：也許當你的 +報告到達時，維護者剛剛離開鍵盤一段時間，或者有更重要的事情要處理。在寫提醒 +信的時候，要善意地問一下，是否還需要你這邊提供什麼來讓事情推進下去。如果報 +告是通過郵件發出來的，那就在郵件的第一行回覆你的初始郵件（見上文），其中包 +括下方的原始報告的完整引用：這是少數幾種情況下，這樣的「TOFU」（Text Over, +Fullquote Under文字在上，完整引用在下）是正確的做法，因爲這樣所有的收件人都 +會以適當的順序立即讓細節到手頭上來。 + +在提醒之後，再等三周的回覆。如果你仍然沒有得到適當的反饋，你首先應該重新考 +慮你的方法。你是否可能嘗試接觸了錯誤的人？是不是報告也許令人反感或者太混亂， +以至於人們決定完全遠離它？排除這些因素的最好方法是：把報告給一兩個熟悉 +FLOSS 問題報告的人看，詢問他們的意見。同時徵求他們關於如何繼續推進的建議。 +這可能意味著：準備一份更好的報告，讓這些人在你發出去之前對它進行審查。這樣 +的方法完全可以；只需說明這是關於這個問題的第二份改進的報告，並附上第一份報 +告的連結。 + +如果報告是恰當的，你可以發送第二封提醒信；在其中詢問爲什麼報告沒有得到任何 +回復。第二封提醒郵件的好時機是在新 Linux 內核版本的首個預發布版本（'rc1'） +發布後不久，因爲無論如何你都應該在那個時候重新測試並提供狀態更新（見上文）。 + +如果第二次提醒的結果又在一周內沒有任何反應，可以嘗試聯繫上級維護者詢問意見： +即使再忙的維護者在這時候也至少應該發過某種確認。 + +記住要做好失望的準備：理想狀況下維護者最好對每一個問題報告做出回應，但他們 +只有義務解決之前列出的「高優先級問題」。所以，如果你得到的回覆是「謝謝你的報告， +我目前有更重要的問題要處理，在可預見的未來沒有時間去研究這個問題」，那請不 +要太沮喪。 + +也有可能在缺陷跟蹤器或列表中進行了一些討論之後，什麼都沒有發生，提醒也無助 +於激勵大家進行修復。這種情況可能是毀滅性的，但在 Linux 內核開發中確實會發生。 +這些和其他得不到幫助的原因在本文結尾處的「爲什麼有些問題在被報告後沒有得到 +任何回應或者仍然沒有修復」中進行了解釋。 + +如果你沒有得到任何幫助或問題最終沒有得到解決，不要沮喪：Linux 內核是 FLOSS， +因此你仍然可以自己幫助自己。例如，你可以試著找到其他受影響的人，和他們一 +起合作來解決這個問題。這樣的團隊可以一起準備一份新的報告，提到團隊有多少人， +爲什麼你們認爲這是應該得到解決的事情。也許你們還可以一起縮小確切原因或引 +入回歸的變化，這往往會使修復更容易。而且如果運氣好的話，團隊中可能會有懂點 +編程的人，也許能寫出一個修複方案。 + + + +「報告穩定版和長期支持內核線的回歸」的參考 +------------------------------------------ + +本小節提供了在穩定版和長期支持內核線中面對回歸時需要執行的步驟的詳細信息。 + +確保特定版本線仍然受支持 +~~~~~~~~~~~~~~~~~~~~~~~~~ + + *檢查內核開發人員是否仍然維護你關心的Linux內核版本線：去 kernel.org 的 + 首頁，確保此特定版本線的最新版沒有「[EOL]」標記。* + +大多數內核版本線只支持三個月左右，因爲延長維護時間會帶來相當多的工作。因此， +每年只會選擇一個版本來支持至少兩年（通常是六年）。這就是爲什麼你需要檢查 +內核開發者是否還支持你關心的版本線。 + +注意，如果 `kernel.org <https://kernel.org/>`_ 在首頁上列出了兩個「穩定」版本， +你應該考慮切換到較新的版本，而忘掉較舊的版本：對它的支持可能很快就會結束。 +然後，它將被標記爲「生命周期結束」（EOL）。達到這個程度的版本線仍然會在 +`kernel.org <https://kernel.org/>`_ 首頁上被顯示一兩周，但不適合用於測試和 +報告。 + +搜索穩定版郵件列表 +~~~~~~~~~~~~~~~~~~~ + + *檢查Linux穩定版郵件列表中的現有報告。* + +也許你所面臨的問題已經被發現，並且已經或即將被修復。因此，請在 `Linux 穩定 +版郵件列表的檔案 <https://lore.kernel.org/stable/>`_ 中搜索類似問題的報告。 +如果你找到任何匹配的問題，可以考慮加入討論，除非修復工作已經完成並計劃很快 +得到應用。 + +用最新版本復現問題 +~~~~~~~~~~~~~~~~~~~ + + *從特定的版本線安裝最新版本作爲純淨內核。確保這個內核沒有被汙染，並且仍 + 然存在問題，因爲問題可能已經在那裡被修復了。* + +在投入更多時間到這個過程中之前，你要檢查這個問題是否在你關注的版本線的最新 +版本中已經得到了修復。這個內核需要是純淨的，在問題發生之前不應該被汙染，正 +如上面已經在測試主線的過程中詳細介紹過的一樣。 + +您是否是第一次注意到供應商內核的回歸？供應商的更改可能會發生變化。你需要重新 +檢查排除來這個問題。當您從5.10.4-vendor.42更新到5.10.5-vendor.43時，記錄損壞 +的信息。然後在測試了前一段中所述的最新5.10版本之後，檢查Linux 5.10.4的普通版本 +是否也可以正常工作。如果問題在那裡出現，那就不符合上游回歸的條件，您需要切換 +回主逐步指南來報告問題。 + +報告回歸 +~~~~~~~~~~ + + *向Linux穩定版郵件列表發送一個簡短的問題報告(stable@vger.kernel.org)。 + 大致描述問題，並解釋如何復現。講清楚首個出現問題的版本和最後一個工作正常 + 的版本。然後等待進一步的指示。* + +當報告在穩定版或長期支持內核線內發生的回歸（例如在從5.10.4更新到5.10.5時）， +一份簡短的報告足以快速報告問題。因此只需要粗略的描述。 + +但是請注意，如果您能夠指明引入問題的確切版本，這將對開發人員有很大幫助。因此 +如果有時間的話，請嘗試使用普通內核找到該版本。讓我們假設發行版發布Linux內核 +5.10.5到5.10.8的更新時發生了故障。那麼按照上面的指示，去檢查該版本線中的最新 +內核，比如5.10.9。如果問題出現，請嘗試普通5.10.5，以確保供應商應用的補丁不會 +干擾。如果問題沒有出現，那麼嘗試5.10.7，然後直到5.10.8或5.10.6（取決於結果） +找到第一個引入問題的版本。在報告中寫明這一點，並指出5.10.9仍然存在故障。 + +前一段基本粗略地概述了「二分」方法。一旦報告出來，您可能會被要求做一個正確的 +報告，因爲它允許精確地定位導致問題的確切更改（然後很容易被恢復以快速修復問題）。 +因此如果時間允許，考慮立即進行適當的二分。有關如何詳細信息，請參閱「對回歸的 +特別關照」部分和文檔「Documentation/translations/zh_TW/admin-guide/bug-bisect.rst」。 + + +「報告僅在舊內核版本線中發生的問題」的參考 +------------------------------------------ + +本節詳細介紹了如果無法用主線內核重現問題，但希望在舊版本線（又稱穩定版內核和 +長期支持內核）中修復問題時需要採取的步驟。 + +有些修復太複雜 +~~~~~~~~~~~~~~~ + + *請做好準備，接下來的幾個步驟可能無法在舊版本中解決問題：修復可能太大或 + 太冒險，無法移植到那裡。* + +即使是微小的、看似明顯的代碼變化，有時也會帶來新的、完全意想不到的問題。穩 +定版和長期支持內核的維護者非常清楚這一點，因此他們只對這些內核進行符合 +「Documentation/translations/zh_TW/process/stable-kernel-rules.rst」中所列出的 +規則的修改。 + +複雜或有風險的修改不符合條件，因此只能應用於主線。其他的修復很容易被回溯到 +最新的穩定版和長期支持內核，但是風險太大，無法集成到舊版內核中。所以要注意 +你所希望的修復可能是那些不會被回溯到你所關心的版本線的修復之一。在這種情況 +下，你將別無選擇，要麼忍受這個問題，要麼切換到一個較新的 Linux 版本，除非你 +想自己把修復補丁應用到你的內核中。 + +通用準備 +~~~~~~~~~~ + + *執行上面「報告僅在舊內核版本線中發生的問題」一節中的前三個步驟。* + +您需要執行本指南另一節中已經描述的幾個步驟。這些步驟將讓您： + + * 檢查內核開發人員是否仍然維護您關心的Linux內核版本行。 + + * 在Linux穩定郵件列表中搜索退出的報告。 + + * 檢查最新版本。 + + +檢查代碼歷史和搜索現有的討論 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + *在Linux內核版本控制系統中搜索修復主線問題的更改，因爲它的提交消息可能 + 會告訴你修復是否已經計劃好了支持。如果你沒有找到，搜索適當的郵件列表， + 尋找討論此類問題或同行評議可能修復的帖子；然後檢查討論是否認爲修復不適 + 合支持。如果支持根本不被考慮，加入最新的討論，詢問是否有可能。* + +在許多情況下，你所處理的問題會發生在主線上，但已在主線上得到了解決。修正它 +的提交也需要被回溯才能解決這個問題。這就是爲什麼你要搜索它或任何相關討論。 + + * 首先嘗試在存放 Linux 內核原始碼的 Git 倉庫中找到修復。你可以通過 + `kernel.org 上的網頁 + <https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/>`_ + 或 `GitHub 上的鏡像 <https://github.com/torvalds/linux>`_ 來實現；如果你 + 有一個本地克隆，你也可以在命令行用 ``git log --grep=<pattern>`` 來搜索。 + + 如果你找到了修復，請查看提交消息的尾部是否包含了類似這樣的「穩定版標籤」： + + Cc: <stable@vger.kernel.org> # 5.4+ + + 像上面這行，開發者標記了安全修復可以回傳到 5.4 及以後的版本。大多數情況 + 下，它會在兩周內被應用到那裡，但有時需要更長的時間。 + + * 如果提交沒有告訴你任何東西，或者你找不到修復，請再找找關於這個問題的討論。 + 用你最喜歡的搜尋引擎搜索網絡，以及 `Linux kernel developers mailing + list 內核開發者郵件列表 <https://lore.kernel.org/lkml/>`_ 的檔案。也可以 + 閱讀上面的 `定位導致問題的內核區域` 一節，然後按照說明找到導致問題的子系 + 統：它的缺陷跟蹤器或郵件列表存檔中可能有你要找的答案。 + + * 如果你看到了一個計劃的修復，請按上所述在版本控制系統中搜索它，因爲提交可 + 能會告訴你是否可以進行回溯。 + + * 檢查討論中是否有任何跡象表明，該修復程序可能風險太大，無法回溯到你關心 + 的版本線。如果是這樣的話，你必須忍受這個問題，或者切換到應用了修復的內 + 核版本線。 + + * 如果修復的問題未包含穩定版標籤，並且沒有討論過回溯問題，請加入討論：如 + 果合適的話，請提及你所面對的問題的版本，以及你希望看到它被修復。 + + +請求建議 +~~~~~~~~~ + + *前面的步驟之一應該會給出一個解決方案。如果仍未能成功，請向可能引起問題 + 的子系統的維護人員詢問建議；抄送特定子系統的郵件列表以及穩定版郵件列表。* + +如果前面的三個步驟都沒有讓你更接近解決方案，那麼只剩下一個選擇：請求建議。 +在你發給可能是問題根源的子系統的維護者的郵件中這樣做；抄送子系統的郵件列表 +以及穩定版郵件列表（stable@vger.kernel.org）。 + + +爲什麼有些問題在報告後沒有任何回應或仍未解決？ +=============================================== + +當向 Linux 開發者報告問題時，要注意只有「高優先級的問題」（回歸、安全問題、嚴 +重問題）才一定會得到解決。如果維護者或其他人都失敗了，Linus Torvalds 他自己 +會確保這一點。他們和其他內核開發者也會解決很多其他問題。但是要知道，有時他 +們也會不能或不願幫忙；有時甚至沒有人發報告給他們。 + +最好的解釋就是那些內核開發者常常是在業餘時間爲 Linux 內核做出貢獻。內核中的 +不少驅動程序都是由這樣的程式設計師編寫的，往往只是因爲他們想讓自己的硬體可以在 +自己喜歡的作業系統上使用。 + +這些程式設計師大多數時候會很樂意修復別人報告的問題。但是沒有人可以強迫他們這樣 +做，因爲他們是自願貢獻的。 + +還有一些情況下，這些開發者真的很想解決一個問題，但卻不能解決：有時他們缺乏 +硬體編程文檔來解決問題。這種情況往往由於公開的文檔太簡陋，或者驅動程序是通 +過逆向工程編寫的。 + +業餘開發者遲早也會不再關心某驅動。也許他們的測試硬體壞了，被更高級的玩意取 +代了，或者是太老了以至於只能在計算機博物館裡找到。有時開發者根本就不關心他 +們的代碼和 Linux 了，因爲在他們的生活中一些不同的東西變得更重要了。在某些情 +況下，沒有人願意接手維護者的工作——也沒有人可以被強迫，因爲對 Linux 內核的貢 +獻是自願的。然而被遺棄的驅動程序仍然存在於內核中：它們對人們仍然有用，刪除 +它們可能導致回歸。 + +對於那些爲 Linux 內核工作而獲得報酬的開發者來說，情況並沒有什麼不同。這些人 +現在貢獻了大部分的變更。但是他們的僱主遲早也會停止關注他們的代碼或者讓程序 +員專注於其他事情。例如，硬體廠商主要通過銷售新硬體來賺錢；因此，他們中的不 +少人並沒有投入太多時間和精力來維護他們多年前就停止銷售的東西的 Linux 內核驅 +動。企業級 Linux 發行商往往持續維護的時間比較長，但在新版本中往往會把對老舊 +和稀有硬體的支持放在一邊，以限制範圍。一旦公司拋棄了一些代碼，往往由業餘貢 +獻者接手，但正如上面提到的：他們遲早也會放下代碼。 + +優先級是一些問題沒有被修復的另一個原因，因爲維護者相當多的時候是被迫設置這 +些優先級的，因爲在 Linux 上工作的時間是有限的。對於業餘時間或者僱主給予他們 +的開發人員用於上游內核維護工作的時間也是如此。有時維護人員也會被報告淹沒， +即使一個驅動程序幾乎完美地工作。爲了不被完全纏住，程式設計師可能別無選擇，只能 +對問題報告進行優先級排序而拒絕其中的一些報告。 + +不過這些都不用太過擔心，很多驅動都有積極的維護者，他們對儘可能多的解決問題 +相當感興趣。 + + +結束語 +======= + +與其他免費/自由&開源軟體（Free/Libre & Open Source Software，FLOSS）相比， +向 Linux 內核開發者報告問題是很難的：這個文檔的長度和複雜性以及字裡行間的內 +涵都說明了這一點。但目前就是這樣了。這篇文字的主要作者希望通過記錄現狀來爲 +以後改善這種狀況打下一些基礎。 + diff --git a/Documentation/translations/zh_TW/admin-guide/security-bugs.rst b/Documentation/translations/zh_TW/admin-guide/security-bugs.rst new file mode 100644 index 000000000000..eed260ef0c37 --- /dev/null +++ b/Documentation/translations/zh_TW/admin-guide/security-bugs.rst @@ -0,0 +1,78 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. include:: ../disclaimer-zh_TW.rst + +:Original: :doc:`../../../admin-guide/security-bugs` + +:譯者: + + 吳想成 Wu XiangCheng <bobwxc@email.cn> + 胡皓文 Hu Haowen <src.res@email.cn> + +安全缺陷 +========= + +Linux內核開發人員非常重視安全性。因此我們想知道何時發現了安全漏洞，以便儘快 +修復和披露。請向Linux內核安全團隊報告安全漏洞。 + +聯絡 +----- + +可以通過電子郵件<security@kernel.org>聯繫Linux內核安全團隊。這是一個安全人員 +的私有列表，他們將幫助驗證錯誤報告並開發和發布修復程序。如果您已經有了一個 +修復，請將其包含在您的報告中，這樣可以大大加快進程。安全團隊可能會從區域維護 +人員那裡獲得額外的幫助，以理解和修復安全漏洞。 + +與任何缺陷一樣，提供的信息越多，診斷和修復就越容易。如果您不清楚哪些信息有用， +請查看「Documentation/translations/zh_TW/admin-guide/reporting-issues.rst」中 +概述的步驟。任何利用漏洞的攻擊代碼都非常有用，未經報告者同意不會對外發布，除 +非已經公開。 + +請儘可能發送無附件的純文本電子郵件。如果所有的細節都藏在附件里，那麼就很難對 +一個複雜的問題進行上下文引用的討論。把它想像成一個 +:doc:`常規的補丁提交 <../process/submitting-patches>` （即使你還沒有補丁）： +描述問題和影響，列出復現步驟，然後給出一個建議的解決方案，所有這些都是純文本的。 + +披露和限制信息 +--------------- + +安全列表不是公開渠道。爲此，請參見下面的協作。 + +一旦開發出了健壯的補丁，發布過程就開始了。對公開的缺陷的修復會立即發布。 + +儘管我們傾向於在未公開缺陷的修復可用時即發布補丁，但應報告者或受影響方的請求， +這可能會被推遲到發布過程開始後的7日內，如果根據缺陷的嚴重性需要更多的時間， +則可額外延長到14天。推遲發布修復的唯一有效原因是爲了適應QA的邏輯和需要發布 +協調的大規模部署。 + +雖然可能與受信任的個人共享受限信息以開發修復，但未經報告者許可，此類信息不會 +與修復程序一起發布或發布在任何其他披露渠道上。這包括但不限於原始錯誤報告和 +後續討論（如有）、漏洞、CVE信息或報告者的身份。 + +換句話說，我們唯一感興趣的是修復缺陷。提交給安全列表的所有其他資料以及對報告 +的任何後續討論，即使在解除限制之後，也將永久保密。 + +協調 +------ + +對敏感缺陷（例如那些可能導致權限提升的缺陷）的修復可能需要與私有郵件列表 +<linux-distros@vs.openwall.org>進行協調，以便分發供應商做好準備，在公開披露 +上游補丁時發布一個已修復的內核。發行版將需要一些時間來測試建議的補丁，通常 +會要求至少幾天的限制，而供應商更新發布更傾向於周二至周四。若合適，安全團隊 +可以協助這種協調，或者報告者可以從一開始就包括linux發行版。在這種情況下，請 +記住在電子郵件主題行前面加上「[vs]」，如linux發行版wiki中所述： +<http://oss-security.openwall.org/wiki/mailing-lists/distros#how-to-use-the-lists>。 + +CVE分配 +-------- + +安全團隊通常不分配CVE，我們也不需要它們來進行報告或修復，因爲這會使過程不必 +要的複雜化，並可能耽誤缺陷處理。如果報告者希望在公開披露之前分配一個CVE編號， +他們需要聯繫上述的私有linux-distros列表。當在提供補丁之前已有這樣的CVE編號時， +如報告者願意，最好在提交消息中提及它。 + +保密協議 +--------- + +Linux內核安全團隊不是一個正式的機構實體，因此無法簽訂任何保密協議。 + diff --git a/Documentation/translations/zh_TW/admin-guide/tainted-kernels.rst b/Documentation/translations/zh_TW/admin-guide/tainted-kernels.rst new file mode 100644 index 000000000000..d7b3c4276417 --- /dev/null +++ b/Documentation/translations/zh_TW/admin-guide/tainted-kernels.rst @@ -0,0 +1,161 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. include:: ../disclaimer-zh_TW.rst + +:Original: :doc:`../../../admin-guide/tainted-kernels` + +:譯者: + + 吳想成 Wu XiangCheng <bobwxc@email.cn> + 胡皓文 Hu Haowen <src.res@email.cn> + +受汙染的內核 +------------- + +當發生一些在稍後調查問題時可能相關的事件時，內核會將自己標記爲「受汙染 +（tainted）」的。不用太過擔心，大多數情況下運行受汙染的內核沒有問題；這些信息 +主要在有人想調查某個問題時才有意義的，因爲問題的真正原因可能是導致內核受汙染 +的事件。這就是爲什麼來自受汙染內核的缺陷報告常常被開發人員忽略，因此請嘗試用 +未受汙染的內核重現問題。 + +請注意，即使在您消除導致汙染的原因（亦即卸載專有內核模塊）之後，內核仍將保持 +汙染狀態，以表示內核仍然不可信。這也是爲什麼內核在注意到內部問題（「kernel +bug」）、可恢復錯誤（「kernel oops」）或不可恢復錯誤（「kernel panic」）時會列印 +受汙染狀態，並將有關此的調試信息寫入日誌 ``dmesg`` 輸出。也可以通過 +``/proc/`` 中的文件在運行時檢查受汙染的狀態。 + + +BUG、Oops或Panics消息中的汙染標誌 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +在頂部以「CPU:」開頭的一行中可以找到受汙染的狀態；內核是否受到汙染和原因會顯示 +在進程ID（「PID:」）和觸發事件命令的縮寫名稱（「Comm:」）之後:: + + BUG: unable to handle kernel NULL pointer dereference at 0000000000000000 + Oops: 0002 [#1] SMP PTI + CPU: 0 PID: 4424 Comm: insmod Tainted: P W O 4.20.0-0.rc6.fc30 #1 + Hardware name: Red Hat KVM, BIOS 0.5.1 01/01/2011 + RIP: 0010:my_oops_init+0x13/0x1000 [kpanic] + [...] + +如果內核在事件發生時沒有被汙染，您將在那裡看到「Not-tainted:」；如果被汙染，那 +麼它將是「Tainted:」以及字母或空格。在上面的例子中，它看起來是這樣的:: + + Tainted: P W O + +下表解釋了這些字符的含義。在本例中，由於加載了專有模塊（ ``P`` ），出現了 +警告（ ``W`` ），並且加載了外部構建的模塊（ ``O`` ），所以內核早些時候受到 +了汙染。要解碼其他字符，請使用下表。 + + +解碼運行時的汙染狀態 +~~~~~~~~~~~~~~~~~~~~~ + +在運行時，您可以通過讀取 ``cat /proc/sys/kernel/tainted`` 來查詢受汙染狀態。 +如果返回 ``0`` ，則內核沒有受到汙染；任何其他數字都表示受到汙染的原因。解碼 +這個數字的最簡單方法是使用腳本 ``tools/debugging/kernel-chktaint`` ，您的 +發行版可能會將其作爲名爲 ``linux-tools`` 或 ``kernel-tools`` 的包的一部分提 +供；如果沒有，您可以從 +`git.kernel.org <https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/plain/tools/debugging/kernel-chktaint>`_ +網站下載此腳本並用 ``sh kernel-chktaint`` 執行，它會在上面引用的日誌中有類似 +語句的機器上列印這樣的內容:: + + Kernel is Tainted for following reasons: + * Proprietary module was loaded (#0) + * Kernel issued warning (#9) + * Externally-built ('out-of-tree') module was loaded (#12) + See Documentation/admin-guide/tainted-kernels.rst in the Linux kernel or + https://www.kernel.org/doc/html/latest/admin-guide/tainted-kernels.html for + a more details explanation of the various taint flags. + Raw taint value as int/string: 4609/'P W O ' + +你也可以試著自己解碼這個數字。如果內核被汙染的原因只有一個，那麼這很簡單， +在本例中您可以通過下表找到數字。如果你需要解碼有多個原因的數字，因爲它是一 +個位域（bitfield），其中每個位表示一個特定類型的汙染的存在或不存在，最好讓 +前面提到的腳本來處理。但是如果您需要快速看一下，可以使用這個shell命令來檢查 +設置了哪些位:: + + $ for i in $(seq 18); do echo $(($i-1)) $(($(cat /proc/sys/kernel/tainted)>>($i-1)&1));done + +汙染狀態代碼表 +~~~~~~~~~~~~~~~ + +=== ===== ====== ======================================================== + 位 日誌 數字 內核被汙染的原因 +=== ===== ====== ======================================================== + 0 G/P 1 已加載專用模塊 + 1 _/F 2 模塊被強制加載 + 2 _/S 4 內核運行在不合規範的系統上 + 3 _/R 8 模塊被強制卸載 + 4 _/M 16 處理器報告了機器檢測異常（MCE） + 5 _/B 32 引用了錯誤的頁或某些意外的頁標誌 + 6 _/U 64 用戶空間應用程式請求的汙染 + 7 _/D 128 內核最近死機了，即曾出現OOPS或BUG + 8 _/A 256 ACPI表被用戶覆蓋 + 9 _/W 512 內核發出警告 + 10 _/C 1024 已加載staging驅動程序 + 11 _/I 2048 已應用平台固件缺陷的解決方案 + 12 _/O 4096 已加載外部構建（「樹外」）模塊 + 13 _/E 8192 已加載未簽名的模塊 + 14 _/L 16384 發生軟鎖定 + 15 _/K 32768 內核已實時打補丁 + 16 _/X 65536 備用汙染，爲發行版定義並使用 + 17 _/T 131072 內核是用結構隨機化插件構建的 +=== ===== ====== ======================================================== + +註：字符 ``_`` 表示空白，以便於閱讀表。 + +汙染的更詳細解釋 +~~~~~~~~~~~~~~~~~ + + 0) ``G`` 加載的所有模塊都有GPL或兼容許可證， ``P`` 加載了任何專有模塊。 + 沒有MODULE_LICENSE（模塊許可證）或MODULE_LICENSE未被insmod認可爲GPL + 兼容的模塊被認爲是專有的。 + + + 1) ``F`` 任何模塊被 ``insmod -f`` 強制加載， ``' '`` 所有模塊正常加載。 + + 2) ``S`` 內核運行在不合規範的處理器或系統上：硬體已運行在不受支持的配置中， + 因此無法保證正確執行。內核將被汙染，例如： + + - 在x86上：PAE是通過intel CPU（如Pentium M）上的forcepae強制執行的，這些 + CPU不報告PAE，但可能有功能實現，SMP內核在非官方支持的SMP Athlon CPU上 + 運行，MSR被暴露到用戶空間中。 + - 在arm上：在某些CPU（如Keystone 2）上運行的內核，沒有啓用某些內核特性。 + - 在arm64上：CPU之間存在不匹配的硬體特性，引導加載程序以不同的模式引導CPU。 + - 某些驅動程序正在被用在不受支持的體系結構上（例如x86_64以外的其他系統 + 上的scsi/snic，非x86/x86_64/itanium上的scsi/ips，已經損壞了arm64上 + irqchip/irq-gic的固件設置…）。 + + 3) ``R`` 模塊被 ``rmmod -f`` 強制卸載， ``' '`` 所有模塊都正常卸載。 + + 4) ``M`` 任何處理器報告了機器檢測異常， ``' '`` 未發生機器檢測異常。 + + 5) ``B`` 頁面釋放函數發現錯誤的頁面引用或某些意外的頁面標誌。這表示硬體問題 + 或內核錯誤；日誌中應該有其他信息指示發生此汙染的原因。 + + 6) ``U`` 用戶或用戶應用程式特意請求設置受汙染標誌，否則應爲 ``' '`` 。 + + 7) ``D`` 內核最近死機了，即出現了OOPS或BUG。 + + 8) ``A`` ACPI表被重寫。 + + 9) ``W`` 內核之前已發出過警告（儘管有些警告可能會設置更具體的汙染標誌）。 + + 10) ``C`` 已加載staging驅動程序。 + + 11) ``I`` 內核正在處理平台固件（BIOS或類似軟體）中的嚴重錯誤。 + + 12) ``O`` 已加載外部構建（「樹外」）模塊。 + + 13) ``E`` 在支持模塊簽名的內核中加載了未簽名的模塊。 + + 14) ``L`` 系統上先前發生過軟鎖定。 + + 15) ``K`` 內核已經實時打了補丁。 + + 16) ``X`` 備用汙染，由Linux發行版定義和使用。 + + 17) ``T`` 內核構建時使用了randstruct插件，它可以有意生成非常不尋常的內核結構 + 布局（甚至是性能病態的布局），這在調試時非常有用。於構建時設置。 + diff --git a/Documentation/translations/zh_TW/admin-guide/unicode.rst b/Documentation/translations/zh_TW/admin-guide/unicode.rst new file mode 100644 index 000000000000..720875be5ef8 --- /dev/null +++ b/Documentation/translations/zh_TW/admin-guide/unicode.rst @@ -0,0 +1,174 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. include:: ../disclaimer-zh_TW.rst + +:Original: Documentation/admin-guide/unicode.rst + +:譯者: + + 吳想成 Wu XiangCheng <bobwxc@email.cn> + 胡皓文 Hu Haowen <src.res@email.cn> + +Unicode（統一碼）支持 +====================== + + （英文版）上次更新：2005-01-17，版本號 1.4 + +此文檔由H. Peter Anvin <unicode@lanana.org>管理，是Linux註冊名稱與編號管理局 +（Linux Assigned Names And Numbers Authority，LANANA）項目的一部分。 +現行版本請見： + + http://www.lanana.org/docs/unicode/admin-guide/unicode.rst + +簡介 +----- + +Linux內核代碼已被重寫以使用Unicode來將字符映射到字體。下載一個Unicode到字體 +（Unicode-to-font）表，八位字符集與UTF-8模式都將改用此字體來顯示。 + +這微妙地改變了八位字符表的語義。現在的四個字符表是： + +=============== =============================== ================ +映射代號 映射名稱 Escape代碼 (G0) +=============== =============================== ================ +LAT1_MAP Latin-1 (ISO 8859-1) ESC ( B +GRAF_MAP DEC VT100 pseudographics ESC ( 0 +IBMPC_MAP IBM code page 437 ESC ( U +USER_MAP User defined ESC ( K +=============== =============================== ================ + +特別是 ESC ( U 不再是「直通字體」，因爲字體可能與IBM字符集完全不同。 +例如，即使加載了一個Latin-1字體，也允許使用塊圖形（block graphics）。 + +請注意，儘管這些代碼與ISO 2022類似，但這些代碼及其用途都與ISO 2022不匹配； +Linux有兩個八位代碼（G0和G1），而ISO 2022有四個七位代碼（G0-G3）。 + +根據Unicode標準/ISO 10646，U+F000到U+F8FF被保留用於作業系統範圍內的分配 +（Unicode標準將其稱爲「團體區域（Corporate Zone）」，因爲這對於Linux是不準確 +的，所以我們稱之爲「Linux區域」）。選擇U+F000作爲起點，因爲它允許直接映射 +區域以2的大倍數開始（以防需要1024或2048個字符的字體）。這就留下U+E000到 +U+EFFF作爲最終用戶區。 + +[v1.2]：Unicodes範圍從U+F000到U+F7FF已經被硬編碼爲直接映射到加載的字體， +繞過了翻譯表。用戶定義的映射現在默認爲U+F000到U+F0FF，模擬前述行爲。實際上， +此範圍可能較短；例如，vgacon只能處理256字符（U+F000..U+F0FF）或512字符 +（U+F000..U+F1FF）字體。 + +Linux 區域中定義的實際字符 +--------------------------- + +此外，還定義了Unicode 1.1.4中不存在的以下字符；這些字符由DEC VT圖形映射使用。 +[v1.2]此用法已過時，不應再使用；請參見下文。 + +====== ====================================== +U+F800 DEC VT GRAPHICS HORIZONTAL LINE SCAN 1 +U+F801 DEC VT GRAPHICS HORIZONTAL LINE SCAN 3 +U+F803 DEC VT GRAPHICS HORIZONTAL LINE SCAN 7 +U+F804 DEC VT GRAPHICS HORIZONTAL LINE SCAN 9 +====== ====================================== + +DEC VT220使用6x10字符矩陣，這些字符在DEC VT圖形字符集中形成一個平滑的過渡。 +我省略了掃描5行，因爲它也被用作塊圖形字符，因此被編碼爲U+2500 FORMS LIGHT +HORIZONTAL。 + +[v1.3]：這些字符已正式添加到Unicode 3.2.0中；它們在U+23BA、U+23BB、U+23BC、 +U+23BD處添加。Linux現在使用新值。 + +[v1.2]：添加了以下字符來表示常見的鍵盤符號，這些符號不太可能被添加到Unicode +中，因爲它們非常討厭地取決於特定供應商。當然，這是糟糕設計的一個好例子。 + +====== ====================================== +U+F810 KEYBOARD SYMBOL FLYING FLAG +U+F811 KEYBOARD SYMBOL PULLDOWN MENU +U+F812 KEYBOARD SYMBOL OPEN APPLE +U+F813 KEYBOARD SYMBOL SOLID APPLE +====== ====================================== + +克林貢（Klingon）語支持 +------------------------ + +1996年，Linux是世界上第一個添加對人工語言克林貢支持的作業系統，克林貢是由 +Marc Okrand爲《星際迷航》電視連續劇創造的。這種編碼後來被徵募Unicode註冊表 +（ConScript Unicode Registry，CSUR）採用，並建議（但最終被拒絕）納入Unicode +平面一。不過，它仍然是Linux區域中的Linux/CSUR私有分配。 + +這種編碼已經得到克林貢語言研究所（Klingon Language Institute）的認可。 +有關更多信息，請聯繫他們： + + http://www.kli.org/ + +由於Linux CZ開頭部分的字符大多是dingbats/symbols/forms類型，而且這是一種 +語言，因此根據標準Unicode慣例，我將它放置在16單元的邊界上。 + +.. note:: + + 這個範圍現在由徵募Unicode註冊表正式管理。規範性引用文件爲： + + https://www.evertype.com/standards/csur/klingon.html + +克林貢語有一個26個字符的字母表，一個10位數的位置數字書寫系統，從左到右 +，從上到下書寫。 + +克林貢字母的幾種字形已經被提出。但是由於這組符號看起來始終是一致的，只有實際 +的形狀不同，因此按照標準Unicode慣例，這些差異被認爲是字體變體。 + +====== ======================================================= +U+F8D0 KLINGON LETTER A +U+F8D1 KLINGON LETTER B +U+F8D2 KLINGON LETTER CH +U+F8D3 KLINGON LETTER D +U+F8D4 KLINGON LETTER E +U+F8D5 KLINGON LETTER GH +U+F8D6 KLINGON LETTER H +U+F8D7 KLINGON LETTER I +U+F8D8 KLINGON LETTER J +U+F8D9 KLINGON LETTER L +U+F8DA KLINGON LETTER M +U+F8DB KLINGON LETTER N +U+F8DC KLINGON LETTER NG +U+F8DD KLINGON LETTER O +U+F8DE KLINGON LETTER P +U+F8DF KLINGON LETTER Q + - Written <q> in standard Okrand Latin transliteration +U+F8E0 KLINGON LETTER QH + - Written <Q> in standard Okrand Latin transliteration +U+F8E1 KLINGON LETTER R +U+F8E2 KLINGON LETTER S +U+F8E3 KLINGON LETTER T +U+F8E4 KLINGON LETTER TLH +U+F8E5 KLINGON LETTER U +U+F8E6 KLINGON LETTER V +U+F8E7 KLINGON LETTER W +U+F8E8 KLINGON LETTER Y +U+F8E9 KLINGON LETTER GLOTTAL STOP + +U+F8F0 KLINGON DIGIT ZERO +U+F8F1 KLINGON DIGIT ONE +U+F8F2 KLINGON DIGIT TWO +U+F8F3 KLINGON DIGIT THREE +U+F8F4 KLINGON DIGIT FOUR +U+F8F5 KLINGON DIGIT FIVE +U+F8F6 KLINGON DIGIT SIX +U+F8F7 KLINGON DIGIT SEVEN +U+F8F8 KLINGON DIGIT EIGHT +U+F8F9 KLINGON DIGIT NINE + +U+F8FD KLINGON COMMA +U+F8FE KLINGON FULL STOP +U+F8FF KLINGON SYMBOL FOR EMPIRE +====== ======================================================= + +其他虛構和人工字母 +------------------- + +自從分配了克林貢Linux Unicode塊之後，John Cowan <jcowan@reutershealth.com> +和 Michael Everson <everson@evertype.com> 建立了一個虛構和人工字母的註冊表。 +徵募Unicode註冊表請訪問： + + https://www.evertype.com/standards/csur/ + +所使用的範圍位於最終用戶區域的低端，因此無法進行規範化分配，但建議希望對虛構 +字母進行編碼的人員使用這些代碼，以實現互操作性。對於克林貢語，CSUR採用了Linux +編碼。CSUR的人正在推動將Tengwar和Cirth添加到Unicode平面一；將克林貢添加到 +Unicode平面一被拒絕，因此上述編碼仍然是官方的。 + diff --git a/Documentation/translations/zh_TW/disclaimer-zh_TW.rst b/Documentation/translations/zh_TW/disclaimer-zh_TW.rst new file mode 100644 index 000000000000..f4cf87d03dc5 --- /dev/null +++ b/Documentation/translations/zh_TW/disclaimer-zh_TW.rst @@ -0,0 +1,11 @@ +:orphan: + +.. warning:: + 此文件的目的是爲讓中文讀者更容易閱讀和理解，而不是作爲一個分支。因此， + 如果您對此文件有任何意見或改動，請先嘗試更新原始英文文件。如果要更改或 + 修正某處翻譯文件，請將意見或補丁發送給維護者（聯繫方式見下）。 + +.. note:: + 如果您發現本文檔與原始文件有任何不同或者有翻譯問題，請聯繫該文件的譯者， + 或者發送電子郵件給胡皓文以獲取幫助：<src.res@email.cn>。 + diff --git a/Documentation/translations/zh_TW/gpio.txt b/Documentation/translations/zh_TW/gpio.txt new file mode 100644 index 000000000000..e3c076dd75a5 --- /dev/null +++ b/Documentation/translations/zh_TW/gpio.txt @@ -0,0 +1,651 @@ +Chinese translated version of Documentation/admin-guide/gpio + +If you have any comment or update to the content, please contact the +original document maintainer directly. However, if you have a problem +communicating in English you can also ask the Chinese maintainer for +help. Contact the Chinese maintainer if this translation is outdated +or if there is a problem with the translation. + +Maintainer: Grant Likely <grant.likely@secretlab.ca> + Linus Walleij <linus.walleij@linaro.org> +Traditional Chinese maintainer: Hu Haowen <src.res@email.cn> +--------------------------------------------------------------------- +Documentation/admin-guide/gpio 的繁體中文翻譯 + +如果想評論或更新本文的內容，請直接聯繫原文檔的維護者。如果你使用英文 +交流有困難的話，也可以向繁體中文版維護者求助。如果本翻譯更新不及時或 +者翻譯存在問題，請聯繫繁體中文版維護者。 + +英文版維護者： Grant Likely <grant.likely@secretlab.ca> + Linus Walleij <linus.walleij@linaro.org> +繁體中文版維護者： 胡皓文 Hu Haowen <src.res@email.cn> +繁體中文版翻譯者： 胡皓文 Hu Haowen <src.res@email.cn> +繁體中文版校譯者： 胡皓文 Hu Haowen <src.res@email.cn> + +以下爲正文 +--------------------------------------------------------------------- +GPIO 接口 + +本文檔提供了一個在Linux下訪問GPIO的公約概述。 + +這些函數以 gpio_* 作爲前綴。其他的函數不允許使用這樣的前綴或相關的 +__gpio_* 前綴。 + + +什麼是GPIO? +========== +"通用輸入/輸出口"(GPIO)是一個靈活的由軟體控制的數位訊號。他們可 +由多種晶片提供,且對於從事嵌入式和定製硬體的 Linux 開發者來說是 +比較熟悉。每個GPIO 都代表一個連接到特定引腳或球柵陣列(BGA)封裝中 +「球珠」的一個位。電路板原理圖顯示了 GPIO 與外部硬體的連接關係。 +驅動可以編寫成通用代碼，以使板級啓動代碼可傳遞引腳配置數據給驅動。 + +片上系統 (SOC) 處理器對 GPIO 有很大的依賴。在某些情況下,每個 +非專用引腳都可配置爲 GPIO,且大多數晶片都最少有一些 GPIO。 +可編程邏輯器件(類似 FPGA) 可以方便地提供 GPIO。像電源管理和 +音頻編解碼器這樣的多功能晶片經常留有一些這樣的引腳來幫助那些引腳 +匱乏的 SOC。同時還有通過 I2C 或 SPI 串行總線連接的「GPIO擴展器」 +晶片。大多數 PC 的南橋有一些擁有 GPIO 能力的引腳 (只有BIOS +固件才知道如何使用他們)。 + +GPIO 的實際功能因系統而異。通常用法有: + + - 輸出值可寫 (高電平=1，低電平=0)。一些晶片也有如何驅動這些值的選項, + 例如只允許輸出一個值、支持「線與」及其他取值類似的模式(值得注意的是 + 「開漏」信號) + + - 輸入值可讀(1、0)。一些晶片支持引腳在配置爲「輸出」時回讀，這對於類似 + 「線與」的情況(以支持雙向信號)是非常有用的。GPIO 控制器可能有輸入 + 去毛刺/消抖邏輯,這有時需要軟體控制。 + + - 輸入通常可作爲 IRQ 信號,一般是沿觸發,但有時是電平觸發。這樣的 IRQ + 可能配置爲系統喚醒事件,以將系統從低功耗狀態下喚醒。 + + - 通常一個 GPIO 根據不同產品電路板的需求,可以配置爲輸入或輸出,也有僅 + 支持單向的。 + + - 大部分 GPIO 可以在持有自旋鎖時訪問,但是通常由串行總線擴展的 GPIO + 不允許持有自旋鎖。但某些系統也支持這種類型。 + +對於給定的電路板,每個 GPIO 都用於某個特定的目的,如監控 MMC/SD 卡的 +插入/移除、檢測卡的防寫狀態、驅動 LED、配置收發器、模擬串行總線、 +復位硬體看門狗、感知開關狀態等等。 + + +GPIO 公約 +========= +注意,這個叫做「公約」，因爲這不是強制性的，不遵循這個公約是無傷大雅的， +因爲此時可移植性並不重要。GPIO 常用於板級特定的電路邏輯,甚至可能 +隨著電路板的版本而改變，且不可能在不同走線的電路板上使用。僅有在少數 +功能上才具有可移植性，其他功能是平台特定。這也是由於「膠合」的邏輯造成的。 + +此外，這不需要任何的執行框架，只是一個接口。某個平台可能通過一個簡單地 +訪問晶片寄存器的內聯函數來實現它，其他平台可能通過委託一系列不同的GPIO +控制器的抽象函數來實現它。(有一些可選的代碼能支持這種策略的實現,本文檔 +後面會介紹，但作爲 GPIO 接口的客戶端驅動程序必須與它的實現無關。) + +也就是說,如果在他們的平台上支持這個公約，驅動應儘可能的使用它。同時，平台 +必須在 Kconfig 中選擇 ARCH_REQUIRE_GPIOLIB 或者 ARCH_WANT_OPTIONAL_GPIOLIB +選項。那些調用標準 GPIO 函數的驅動應該在 Kconfig 入口中聲明依賴GENERIC_GPIO。 +當驅動包含文件: + + #include <linux/gpio.h> + +則 GPIO 函數是可用,無論是「真實代碼」還是經優化過的語句。如果你遵守 +這個公約，當你的代碼完成後，對其他的開發者來說會更容易看懂和維護。 + +注意，這些操作包含所用平台的 I/O 屏障代碼，驅動無須顯式地調用他們。 + + +標識 GPIO +--------- +GPIO 是通過無符號整型來標識的,範圍是 0 到 MAX_INT。保留「負」數 +用於其他目的,例如標識信號「在這個板子上不可用」或指示錯誤。未接觸底層 +硬體的代碼會忽略這些整數。 + +平台會定義這些整數的用法,且通常使用 #define 來定義 GPIO，這樣 +板級特定的啓動代碼可以直接關聯相應的原理圖。相對來說，驅動應該僅使用 +啓動代碼傳遞過來的 GPIO 編號，使用 platform_data 保存板級特定 +引腳配置數據 (同時還有其他須要的板級特定數據)，避免可能出現的問題。 + +例如一個平台使用編號 32-159 來標識 GPIO,而在另一個平台使用編號0-63 +標識一組 GPIO 控制器,64-79標識另一類 GPIO 控制器,且在一個含有 +FPGA 的特定板子上使用 80-95。編號不一定要連續,那些平台中，也可以 +使用編號2000-2063來標識一個 I2C 接口的 GPIO 擴展器中的 GPIO。 + +如果你要初始化一個帶有無效 GPIO 編號的結構體,可以使用一些負編碼 +(如"-EINVAL")，那將使其永遠不會是有效。來測試這樣一個結構體中的編號 +是否關聯一個 GPIO，你可使用以下斷言: + + int gpio_is_valid(int number); + +如果編號不存在，則請求和釋放 GPIO 的函數將拒絕執行相關操作(見下文)。 +其他編號也可能被拒絕,比如一個編號可能存在，但暫時在給定的電路上不可用。 + +一個平台是否支持多個 GPIO 控制器爲平台特定的實現問題，就像是否可以 +在 GPIO 編號空間中有「空洞」和是否可以在運行時添加新的控制器一樣。 +這些問題會影響其他事情，包括相鄰的 GPIO 編號是否存在等。 + +使用 GPIO +--------- +對於一個 GPIO，系統應該做的第一件事情就是通過 gpio_request() +函數分配它，見下文。 + +接下來是設置I/O方向，這通常是在板級啓動代碼中爲所使用的 GPIO 設置 +platform_device 時完成。 + + /* 設置爲輸入或輸出, 返回 0 或負的錯誤代碼 */ + int gpio_direction_input(unsigned gpio); + int gpio_direction_output(unsigned gpio, int value); + +返回值爲零代表成功，否則返回一個負的錯誤代碼。這個返回值需要檢查，因爲 +get/set(獲取/設置)函數調用沒法返回錯誤,且有可能是配置錯誤。通常， +你應該在進程上下文中調用這些函數。然而,對於自旋鎖安全的 GPIO，在板子 +啓動的早期、進程啓動前使用他們也是可以的。 + +對於作爲輸出的 GPIO，爲其提供初始輸出值，對於避免在系統啓動期間出現 +信號毛刺是很有幫助的。 + +爲了與傳統的 GPIO 接口兼容, 在設置一個 GPIO 方向時，如果它還未被申請， +則隱含了申請那個 GPIO 的操作(見下文)。這種兼容性正在從可選的 gpiolib +框架中移除。 + +如果這個 GPIO 編碼不存在，或者特定的 GPIO 不能用於那種模式，則方向 +設置可能失敗。依賴啓動固件來正確地設置方向通常是一個壞主意，因爲它可能 +除了啓動Linux，並沒有做更多的驗證工作。(同理, 板子的啓動代碼可能需要 +將這個復用的引腳設置爲 GPIO，並正確地配置上拉/下拉電阻。) + + +訪問自旋鎖安全的 GPIO +------------------- +大多數 GPIO 控制器可以通過內存讀/寫指令來訪問。這些指令不會休眠,可以 +安全地在硬(非線程)中斷例程和類似的上下文中完成。 + +對於那些用 gpio_cansleep()測試總是返回失敗的 GPIO(見下文)，使用 +以下的函數訪問: + + /* GPIO 輸入:返回零或非零 */ + int gpio_get_value(unsigned gpio); + + /* GPIO 輸出 */ + void gpio_set_value(unsigned gpio, int value); + +GPIO值是布爾值，零表示低電平，非零表示高電平。當讀取一個輸出引腳的值時， +返回值應該是引腳上的值。這個值不總是和輸出值相符，因爲存在開漏輸出信號和 +輸出延遲問題。 + +以上的 get/set 函數無錯誤返回值，因爲之前 gpio_direction_*()應已檢查過 +其是否爲「無效GPIO」。此外，還需要注意的是並不是所有平台都可以從輸出引腳 +中讀取數據，對於不能讀取的引腳應總返回零。另外，對那些在原子上下文中無法 +安全訪問的 GPIO (譯者註：因爲訪問可能導致休眠)使用這些函數是不合適的 +(見下文)。 + +在 GPIO 編號(還有輸出、值)爲常數的情況下,鼓勵通過平台特定的實現來優化 +這兩個函數來訪問 GPIO 值。這種情況(讀寫一個硬體寄存器)下只需要幾條指令 +是很正常的,且無須自旋鎖。這種優化函數比起那些在子程序上花費許多指令的 +函數可以使得模擬接口(譯者注:例如 GPIO 模擬 I2C、1-wire 或 SPI)的 +應用(在空間和時間上都)更具效率。 + + +訪問可能休眠的 GPIO +----------------- +某些 GPIO 控制器必須通過基於總線(如 I2C 或 SPI)的消息訪問。讀或寫這些 +GPIO 值的命令需要等待其信息排到隊首才發送命令，再獲得其反饋。期間需要 +休眠，這不能在 IRQ 例程(中斷上下文)中執行。 + +支持此類 GPIO 的平台通過以下函數返回非零值來區分出這種 GPIO。(此函數需要 +一個之前通過 gpio_request 分配到的有效 GPIO 編號): + + int gpio_cansleep(unsigned gpio); + +爲了訪問這種 GPIO,內核定義了一套不同的函數: + + /* GPIO 輸入:返回零或非零 ,可能會休眠 */ + int gpio_get_value_cansleep(unsigned gpio); + + /* GPIO 輸出,可能會休眠 */ + void gpio_set_value_cansleep(unsigned gpio, int value); + + +訪問這樣的 GPIO 需要一個允許休眠的上下文，例如線程 IRQ 處理例程，並用以上的 +訪問函數替換那些沒有 cansleep()後綴的自旋鎖安全訪問函數。 + +除了這些訪問函數可能休眠，且它們操作的 GPIO 不能在硬體 IRQ 處理例程中訪問的 +事實，這些處理例程實際上和自旋鎖安全的函數是一樣的。 + +** 除此之外 ** 調用設置和配置此類 GPIO 的函數也必須在允許休眠的上下文中， +因爲它們可能也需要訪問 GPIO 控制器晶片: (這些設置函數通常在板級啓動代碼或者 +驅動探測/斷開代碼中，所以這是一個容易滿足的約束條件。) + + gpio_direction_input() + gpio_direction_output() + gpio_request() + +## gpio_request_one() +## gpio_request_array() +## gpio_free_array() + + gpio_free() + gpio_set_debounce() + + + +聲明和釋放 GPIO +---------------------------- +爲了有助於捕獲系統配置錯誤,定義了兩個函數。 + + /* 申請 GPIO, 返回 0 或負的錯誤代碼. + * 非空標籤可能有助於診斷. + */ + int gpio_request(unsigned gpio, const char *label); + + /* 釋放之前聲明的 GPIO */ + void gpio_free(unsigned gpio); + +將無效的 GPIO 編碼傳遞給 gpio_request()會導致失敗，申請一個已使用這個 +函數聲明過的 GPIO 也會失敗。gpio_request()的返回值必須檢查。你應該在 +進程上下文中調用這些函數。然而,對於自旋鎖安全的 GPIO,在板子啓動的早期、 +進入進程之前是可以申請的。 + +這個函數完成兩個基本的目標。一是標識那些實際上已作爲 GPIO 使用的信號線， +這樣便於更好地診斷;系統可能需要服務幾百個可用的 GPIO，但是對於任何一個 +給定的電路板通常只有一些被使用。另一個目的是捕獲衝突，查明錯誤:如兩個或 +更多驅動錯誤地認爲他們已經獨占了某個信號線,或是錯誤地認爲移除一個管理著 +某個已激活信號的驅動是安全的。也就是說，申請 GPIO 的作用類似一種鎖機制。 + +某些平台可能也使用 GPIO 作爲電源管理激活信號(例如通過關閉未使用晶片區和 +簡單地關閉未使用時鐘)。 + +對於 GPIO 使用 pinctrl 子系統已知的引腳，子系統應該被告知其使用情況； +一個 gpiolib 驅動的 .request()操作應調用 pinctrl_gpio_request()， +而 gpiolib 驅動的 .free()操作應調用 pinctrl_gpio_free()。pinctrl +子系統允許 pinctrl_gpio_request()在某個引腳或引腳組以復用形式「屬於」 +一個設備時都成功返回。 + +任何須將 GPIO 信號導向適當引腳的引腳復用硬體的編程應該發生在 GPIO +驅動的 .direction_input()或 .direction_output()函數中，以及 +任何輸出 GPIO 值的設置之後。這樣可使從引腳特殊功能到 GPIO 的轉換 +不會在引腳產生毛刺波形。有時當用一個 GPIO 實現其信號驅動一個非 GPIO +硬體模塊的解決方案時，就需要這種機制。 + +某些平台允許部分或所有 GPIO 信號使用不同的引腳。類似的，GPIO 或引腳的 +其他方面也需要配置，如上拉/下拉。平台軟體應該在對這些 GPIO 調用 +gpio_request()前將這類細節配置好，例如使用 pinctrl 子系統的映射表， +使得 GPIO 的用戶無須關注這些細節。 + +還有一個值得注意的是在釋放 GPIO 前，你必須停止使用它。 + + +注意:申請一個 GPIO 並沒有以任何方式配置它，只不過標識那個 GPIO 處於使用 +狀態。必須有另外的代碼來處理引腳配置(如控制 GPIO 使用的引腳、上拉/下拉)。 +考慮到大多數情況下聲明 GPIO 之後就會立即配置它們,所以定義了以下三個輔助函數: + + /* 申請一個 GPIO 信號, 同時通過特定的'flags'初始化配置, + * 其他和 gpio_request()的參數和返回值相同 + * + */ + int gpio_request_one(unsigned gpio, unsigned long flags, const char *label); + + /* 在單個函數中申請多個 GPIO + */ + int gpio_request_array(struct gpio *array, size_t num); + + /* 在單個函數中釋放多個 GPIO + */ + void gpio_free_array(struct gpio *array, size_t num); + +這裡 'flags' 當前定義可指定以下屬性: + + * GPIOF_DIR_IN - 配置方向爲輸入 + * GPIOF_DIR_OUT - 配置方向爲輸出 + + * GPIOF_INIT_LOW - 在作爲輸出時,初始值爲低電平 + * GPIOF_INIT_HIGH - 在作爲輸出時,初始值爲高電平 + * GPIOF_OPEN_DRAIN - gpio引腳爲開漏信號 + * GPIOF_OPEN_SOURCE - gpio引腳爲源極開路信號 + + * GPIOF_EXPORT_DIR_FIXED - 將 gpio 導出到 sysfs，並保持方向 + * GPIOF_EXPORT_DIR_CHANGEABLE - 同樣是導出, 但允許改變方向 + +因爲 GPIOF_INIT_* 僅有在配置爲輸出的時候才存在,所以有效的組合爲: + + * GPIOF_IN - 配置爲輸入 + * GPIOF_OUT_INIT_LOW - 配置爲輸出,並初始化爲低電平 + * GPIOF_OUT_INIT_HIGH - 配置爲輸出,並初始化爲高電平 + +當設置 flag 爲 GPIOF_OPEN_DRAIN 時，則假設引腳是開漏信號。這樣的引腳 +將不會在輸出模式下置1。這樣的引腳需要連接上拉電阻。通過使能這個標誌，gpio庫 +將會在被要求輸出模式下置1時將引腳變爲輸入狀態來使引腳置高。引腳在輸出模式下 +通過置0使其輸出低電平。 + +當設置 flag 爲 GPIOF_OPEN_SOURCE 時，則假設引腳爲源極開路信號。這樣的引腳 +將不會在輸出模式下置0。這樣的引腳需要連接下拉電阻。通過使能這個標誌，gpio庫 +將會在被要求輸出模式下置0時將引腳變爲輸入狀態來使引腳置低。引腳在輸出模式下 +通過置1使其輸出高電平。 + +將來這些標誌可能擴展到支持更多的屬性。 + +更進一步,爲了更簡單地聲明/釋放多個 GPIO,'struct gpio'被引進來封裝所有 +這三個領域: + + struct gpio { + unsigned gpio; + unsigned long flags; + const char *label; + }; + +一個典型的用例: + + static struct gpio leds_gpios[] = { + { 32, GPIOF_OUT_INIT_HIGH, "Power LED" }, /* 默認開啓 */ + { 33, GPIOF_OUT_INIT_LOW, "Green LED" }, /* 默認關閉 */ + { 34, GPIOF_OUT_INIT_LOW, "Red LED" }, /* 默認關閉 */ + { 35, GPIOF_OUT_INIT_LOW, "Blue LED" }, /* 默認關閉 */ + { ... }, + }; + + err = gpio_request_one(31, GPIOF_IN, "Reset Button"); + if (err) + ... + + err = gpio_request_array(leds_gpios, ARRAY_SIZE(leds_gpios)); + if (err) + ... + + gpio_free_array(leds_gpios, ARRAY_SIZE(leds_gpios)); + + +GPIO 映射到 IRQ +-------------------- +GPIO 編號是無符號整數;IRQ 編號也是。這些構成了兩個邏輯上不同的命名空間 +(GPIO 0 不一定使用 IRQ 0)。你可以通過以下函數在它們之間實現映射: + + /* 映射 GPIO 編號到 IRQ 編號 */ + int gpio_to_irq(unsigned gpio); + + /* 映射 IRQ 編號到 GPIO 編號 (儘量避免使用) */ + int irq_to_gpio(unsigned irq); + +它們的返回值爲對應命名空間的相關編號，或是負的錯誤代碼(如果無法映射)。 +(例如,某些 GPIO 無法做爲 IRQ 使用。)以下的編號錯誤是未經檢測的:使用一個 +未通過 gpio_direction_input()配置爲輸入的 GPIO 編號，或者使用一個 +並非來源於gpio_to_irq()的 IRQ 編號。 + +這兩個映射函數可能會在信號編號的加減計算過程上花些時間。它們不可休眠。 + +gpio_to_irq()返回的非錯誤值可以傳遞給 request_irq()或者 free_irq()。 +它們通常通過板級特定的初始化代碼存放到平台設備的 IRQ 資源中。注意:IRQ +觸發選項是 IRQ 接口的一部分，如 IRQF_TRIGGER_FALLING，系統喚醒能力 +也是如此。 + +irq_to_gpio()返回的非錯誤值大多數通常可以被 gpio_get_value()所使用， +比如在 IRQ 是沿觸發時初始化或更新驅動狀態。注意某些平台不支持反映射,所以 +你應該儘量避免使用它。 + + +模擬開漏信號 +---------------------------- +有時在只有低電平信號作爲實際驅動結果(譯者注:多個輸出連接於一點，邏輯電平 +結果爲所有輸出的邏輯與)的時候,共享的信號線需要使用「開漏」信號。(該術語 +適用於 CMOS 管；而 TTL 用「集電極開路」。)一個上拉電阻使信號爲高電平。這 +有時被稱爲「線與」。實際上，從負邏輯(低電平爲真)的角度來看，這是一個「線或」。 + +一個開漏信號的常見例子是共享的低電平使能 IRQ 信號線。此外,有時雙向數據總線 +信號也使用漏極開路信號。 + +某些 GPIO 控制器直接支持開漏輸出，還有許多不支持。當你需要開漏信號，但 +硬體又不直接支持的時候，一個常用的方法是用任何即可作輸入也可作輸出的 GPIO +引腳來模擬: + + LOW: gpio_direction_output(gpio, 0) ... 這代碼驅動信號並覆蓋 + 上拉配置。 + + HIGH: gpio_direction_input(gpio) ... 這代碼關閉輸出,所以上拉電阻 + (或其他的一些器件)控制了信號。 + +如果你將信號線「驅動」爲高電平，但是 gpio_get_value(gpio)報告了一個 +低電平(在適當的上升時間後)，你就可以知道是其他的一些組件將共享信號線拉低了。 +這不一定是錯誤的。一個常見的例子就是 I2C 時鐘的延長：一個需要較慢時鐘的 +從設備延遲 SCK 的上升沿，而 I2C 主設備相應地調整其信號傳輸速率。 + + +這些公約忽略了什麼? +================ +這些公約忽略的最大一件事就是引腳復用，因爲這屬於高度晶片特定的屬性且 +沒有可移植性。某個平台可能不需要明確的復用信息；有的對於任意給定的引腳 +可能只有兩個功能選項；有的可能每個引腳有八個功能選項；有的可能可以將 +幾個引腳中的任何一個作爲給定的 GPIO。(是的，這些例子都來自於當前運行 +Linux 的系統。) + +在某些系統中,與引腳復用相關的是配置和使能集成的上、下拉模式。並不是所有 +平台都支持這種模式,或者不會以相同的方式來支持這種模式；且任何給定的電路板 +可能使用外置的上拉(或下拉)電阻,這時晶片上的就不應該使用。(當一個電路需要 +5kOhm 的拉動電阻,晶片上的 100 kOhm 電阻就不能做到。)同樣的，驅動能力 +(2 mA vs 20 mA)和電壓(1.8V vs 3.3V)是平台特定問題,就像模型一樣在 +可配置引腳和 GPIO 之間(沒)有一一對應的關係。 + +還有其他一些系統特定的機制沒有在這裡指出，例如上述的輸入去毛刺和線與輸出 +選項。硬體可能支持批量讀或寫 GPIO，但是那一般是配置相關的：對於處於同一 +塊區(bank)的GPIO。(GPIO 通常以 16 或 32 個組成一個區塊，一個給定的 +片上系統一般有幾個這樣的區塊。)某些系統可以通過輸出 GPIO 觸發 IRQ， +或者從並非以 GPIO 管理的引腳取值。這些機制的相關代碼沒有必要具有可移植性。 + +當前，動態定義 GPIO 並不是標準的，例如作爲配置一個帶有某些 GPIO 擴展器的 +附加電路板的副作用。 + +GPIO 實現者的框架 (可選) +===================== +前面提到了，有一個可選的實現框架，讓平台使用相同的編程接口，更加簡單地支持 +不同種類的 GPIO 控制器。這個框架稱爲"gpiolib"。 + +作爲一個輔助調試功能，如果 debugfs 可用，就會有一個 /sys/kernel/debug/gpio +文件。通過這個框架，它可以列出所有註冊的控制器,以及當前正在使用中的 GPIO +的狀態。 + + +控制器驅動: gpio_chip +------------------- +在框架中每個 GPIO 控制器都包裝爲一個 "struct gpio_chip"，他包含了 +該類型的每個控制器的常用信息: + + - 設置 GPIO 方向的方法 + - 用於訪問 GPIO 值的方法 + - 告知調用其方法是否可能休眠的標誌 + - 可選的 debugfs 信息導出方法 (顯示類似上拉配置一樣的額外狀態) + - 診斷標籤 + +也包含了來自 device.platform_data 的每個實例的數據：它第一個 GPIO 的 +編號和它可用的 GPIO 的數量。 + +實現 gpio_chip 的代碼應支持多控制器實例，這可能使用驅動模型。那些代碼要 +配置每個 gpio_chip，並發起gpiochip_add()。卸載一個 GPIO 控制器很少見， +但在必要的時候可以使用 gpiochip_remove()。 + +大部分 gpio_chip 是一個實例特定結構體的一部分，而並不將 GPIO 接口單獨 +暴露出來,比如編址、電源管理等。類似編解碼器這樣的晶片會有複雜的非 GPIO +狀態。 + +任何一個 debugfs 信息導出方法通常應該忽略還未申請作爲 GPIO 的信號線。 +他們可以使用 gpiochip_is_requested()測試，當這個 GPIO 已經申請過了 +就返回相關的標籤，否則返回 NULL。 + + +平台支持 +------- +爲了支持這個框架，一個平台的 Kconfig 文件將會 "select"(選擇) +ARCH_REQUIRE_GPIOLIB 或 ARCH_WANT_OPTIONAL_GPIOLIB，並讓它的 +<asm/gpio.h> 包含 <asm-generic/gpio.h>，同時定義三個方法: +gpio_get_value()、gpio_set_value()和 gpio_cansleep()。 + +它也應提供一個 ARCH_NR_GPIOS 的定義值，這樣可以更好地反映該平台 GPIO +的實際數量,節省靜態表的空間。(這個定義值應該包含片上系統內建 GPIO 和 +GPIO 擴展器中的數據。) + +ARCH_REQUIRE_GPIOLIB 意味著 gpiolib 核心在這個構架中將總是編譯進內核。 + +ARCH_WANT_OPTIONAL_GPIOLIB 意味著 gpiolib 核心默認關閉,且用戶可以 +使能它,並將其編譯進內核(可選)。 + +如果這些選項都沒被選擇,該平台就不通過 GPIO-lib 支持 GPIO,且代碼不可以 +被用戶使能。 + +以下這些方法的實現可以直接使用框架代碼,並總是通過 gpio_chip 調度: + + #define gpio_get_value __gpio_get_value + #define gpio_set_value __gpio_set_value + #define gpio_cansleep __gpio_cansleep + +這些定義可以用更理想的實現方法替代，那就是使用經過邏輯優化的內聯函數來訪問 +基於特定片上系統的 GPIO。例如,若引用的 GPIO (寄存器位偏移)是常量「12」， +讀取或設置它可能只需少則兩或三個指令，且不會休眠。當這樣的優化無法實現時， +那些函數必須使用框架提供的代碼，那就至少要幾十條指令才可以實現。對於用 GPIO +模擬的 I/O 接口, 如此精簡指令是很有意義的。 + +對於片上系統，平台特定代碼爲片上 GPIO 每個區(bank)定義並註冊 gpio_chip +實例。那些 GPIO 應該根據晶片廠商的文檔進行編碼/標籤,並直接和電路板原理圖 +對應。他們應該開始於零並終止於平台特定的限制。這些 GPIO(代碼)通常從 +arch_initcall()或者更早的地方集成進平台初始化代碼，使這些 GPIO 總是可用， +且他們通常可以作爲 IRQ 使用。 + +板級支持 +------- +對於外部 GPIO 控制器(例如 I2C 或 SPI 擴展器、專用晶片、多功能器件、FPGA +或 CPLD)，大多數常用板級特定代碼都可以註冊控制器設備，並保證他們的驅動知道 +gpiochip_add()所使用的 GPIO 編號。他們的起始編號通常跟在平台特定的 GPIO +編號之後。 + +例如板級啓動代碼應該創建結構體指明晶片公開的 GPIO 範圍，並使用 platform_data +將其傳遞給每個 GPIO 擴展器晶片。然後晶片驅動中的 probe()例程可以將這個 +數據傳遞給 gpiochip_add()。 + +初始化順序很重要。例如，如果一個設備依賴基於 I2C 的(擴展)GPIO，那麼它的 +probe()例程就應該在那個 GPIO 有效以後才可以被調用。這意味著設備應該在 +GPIO 可以工作之後才可被註冊。解決這類依賴的的一種方法是讓這種 gpio_chip +控制器向板級特定代碼提供 setup()和 teardown()回調函數。一旦所有必須的 +資源可用之後，這些板級特定的回調函數將會註冊設備，並可以在這些 GPIO 控制器 +設備變成無效時移除它們。 + + +用戶空間的 Sysfs 接口(可選) +======================== +使用「gpiolib」實現框架的平台可以選擇配置一個 GPIO 的 sysfs 用戶接口。 +這不同於 debugfs 接口，因爲它提供的是對 GPIO方向和值的控制，而不只顯示 +一個GPIO 的狀態摘要。此外,它可以出現在沒有調試支持的產品級系統中。 + +例如，通過適當的系統硬體文檔，用戶空間可以知道 GIOP #23 控制 Flash +存儲器的防寫(用於保護其中 Bootloader 分區)。產品的系統升級可能需要 +臨時解除這個保護：首先導入一個 GPIO，改變其輸出狀態，然後在重新使能防寫 +前升級代碼。通常情況下,GPIO #23 是不會被觸及的，並且內核也不需要知道他。 + +根據適當的硬體文檔，某些系統的用戶空間 GPIO 可以用於確定系統配置數據， +這些數據是標準內核不知道的。在某些任務中，簡單的用戶空間 GPIO 驅動可能是 +系統真正需要的。 + +注意：標準內核驅動中已經存在通用的「LED 和按鍵」GPIO 任務，分別是: +"leds-gpio" 和 "gpio_keys"。請使用這些來替代直接訪問 GPIO，因爲集成在 +內核框架中的這類驅動比你在用戶空間的代碼更好。 + + +Sysfs 中的路徑 +-------------- +在/sys/class/gpio 中有 3 類入口: + + - 用於在用戶空間控制 GPIO 的控制接口; + + - GPIOs 本身;以及 + + - GPIO 控制器 ("gpio_chip" 實例)。 + +除了這些標準的文件,還包含「device」符號連結。 + +控制接口是只寫的: + + /sys/class/gpio/ + + "export" ... 用戶空間可以通過寫其編號到這個文件，要求內核導出 + 一個 GPIO 的控制到用戶空間。 + + 例如: 如果內核代碼沒有申請 GPIO #19,"echo 19 > export" + 將會爲 GPIO #19 創建一個 "gpio19" 節點。 + + "unexport" ... 導出到用戶空間的逆操作。 + + 例如: "echo 19 > unexport" 將會移除使用"export"文件導出的 + "gpio19" 節點。 + +GPIO 信號的路徑類似 /sys/class/gpio/gpio42/ (對於 GPIO #42 來說)， +並有如下的讀/寫屬性: + + /sys/class/gpio/gpioN/ + + "direction" ... 讀取得到 "in" 或 "out"。這個值通常運行寫入。 + 寫入"out" 時,其引腳的默認輸出爲低電平。爲了確保無故障運行， + "low" 或 "high" 的電平值應該寫入 GPIO 的配置，作爲初始輸出值。 + + 注意:如果內核不支持改變 GPIO 的方向，或者在導出時內核代碼沒有 + 明確允許用戶空間可以重新配置 GPIO 方向，那麼這個屬性將不存在。 + + "value" ... 讀取得到 0 (低電平) 或 1 (高電平)。如果 GPIO 配置爲 + 輸出,這個值允許寫操作。任何非零值都以高電平看待。 + + 如果引腳可以配置爲中斷信號，且如果已經配置了產生中斷的模式 + （見"edge"的描述），你可以對這個文件使用輪詢操作(poll(2))， + 且輪詢操作會在任何中斷觸發時返回。如果你使用輪詢操作(poll(2))， + 請在 events 中設置 POLLPRI 和 POLLERR。如果你使用輪詢操作 + (select(2))，請在 exceptfds 設置你期望的文件描述符。在 + 輪詢操作(poll(2))返回之後，既可以通過 lseek(2)操作讀取 + sysfs 文件的開始部分，也可以關閉這個文件並重新打開它來讀取數據。 + + "edge" ... 讀取得到「none」、「rising」、「falling」或者「both」。 + 將這些字符串寫入這個文件可以選擇沿觸發模式，會使得輪詢操作 + (select(2))在"value"文件中返回。 + + 這個文件僅有在這個引腳可以配置爲可產生中斷輸入引腳時，才存在。 + + "active_low" ... 讀取得到 0 (假) 或 1 (真)。寫入任何非零值可以 + 翻轉這個屬性的(讀寫)值。已存在或之後通過"edge"屬性設置了"rising" + 和 "falling" 沿觸發模式的輪詢操作(poll(2))將會遵循這個設置。 + +GPIO 控制器的路徑類似 /sys/class/gpio/gpiochip42/ (對於從#42 GPIO +開始實現控制的控制器),並有著以下只讀屬性: + + /sys/class/gpio/gpiochipN/ + + "base" ... 與以上的 N 相同,代表此晶片管理的第一個 GPIO 的編號 + + "label" ... 用於診斷 (並不總是只有唯一值) + + "ngpio" ... 此控制器所管理的 GPIO 數量(而 GPIO 編號從 N 到 + N + ngpio - 1) + +大多數情況下,電路板的文檔應當標明每個 GPIO 的使用目的。但是那些編號並不總是 +固定的,例如在擴展卡上的 GPIO會根據所使用的主板或所在堆疊架構中其他的板子而 +有所不同。在這種情況下,你可能需要使用 gpiochip 節點(儘可能地結合電路圖)來 +確定給定信號所用的 GPIO 編號。 + + +從內核代碼中導出 +------------- +內核代碼可以明確地管理那些已通過 gpio_request()申請的 GPIO 的導出: + + /* 導出 GPIO 到用戶空間 */ + int gpio_export(unsigned gpio, bool direction_may_change); + + /* gpio_export()的逆操作 */ + void gpio_unexport(); + + /* 創建一個 sysfs 連接到已導出的 GPIO 節點 */ + int gpio_export_link(struct device *dev, const char *name, + unsigned gpio) + +在一個內核驅動申請一個 GPIO 之後，它可以通過 gpio_export()使其在 sysfs +接口中可見。該驅動可以控制信號方向是否可修改。這有助於防止用戶空間代碼無意間 +破壞重要的系統狀態。 + +這個明確的導出有助於(通過使某些實驗更容易來)調試，也可以提供一個始終存在的接口， +與文檔配合作爲板級支持包的一部分。 + +在 GPIO 被導出之後，gpio_export_link()允許在 sysfs 文件系統的任何地方 +創建一個到這個 GPIO sysfs 節點的符號連結。這樣驅動就可以通過一個描述性的 +名字，在 sysfs 中他們所擁有的設備下提供一個(到這個 GPIO sysfs 節點的)接口。 + diff --git a/Documentation/translations/zh_TW/index.rst b/Documentation/translations/zh_TW/index.rst new file mode 100644 index 000000000000..c02c4b5281e6 --- /dev/null +++ b/Documentation/translations/zh_TW/index.rst @@ -0,0 +1,168 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. raw:: latex + + \renewcommand\thesection* + \renewcommand\thesubsection* + \kerneldocCJKon + \kerneldocBeginTC + +.. _linux_doc_zh_tw: + +繁體中文翻譯 +============ + + +.. note:: + 內核文檔繁體中文版的翻譯工作正在進行中。如果您願意並且有時間參與這項工 + 作，歡迎提交補丁給胡皓文 <src.res@email.cn>。 + +許可證文檔 +---------- + +下面的文檔介紹了Linux內核原始碼的許可證（GPLv2）、如何在原始碼樹中正確標記 +單個文件的許可證、以及指向完整許可證文本的連結。 + +Documentation/translations/zh_TW/process/license-rules.rst + +用戶文檔 +-------- + +下面的手冊是爲內核用戶編寫的——即那些試圖讓它在給定系統上以最佳方式工作的 +用戶。 + +.. toctree:: + :maxdepth: 2 + + admin-guide/index + +TODOList: + +* kbuild/index + +固件相關文檔 +------------ + +下列文檔描述了內核需要的平台固件相關信息。 + +TODOList: + +* firmware-guide/index +* devicetree/index + +應用程式開發人員文檔 +-------------------- + +用戶空間API手冊涵蓋了描述應用程式開發人員可見內核接口方面的文檔。 + +TODOlist: + +* userspace-api/index + +內核開發簡介 +------------ + +這些手冊包含有關如何開發內核的整體信息。內核社區非常龐大，一年下來有數千名 +開發人員做出貢獻。與任何大型社區一樣，知道如何完成任務將使得更改合併的過程 +變得更加容易。 + +.. toctree:: + :maxdepth: 2 + + process/index + +TODOList: + +* dev-tools/index +* doc-guide/index +* kernel-hacking/index +* trace/index +* maintainer/index +* fault-injection/index +* livepatch/index +* rust/index + +內核API文檔 +----------- + +以下手冊從內核開發人員的角度詳細介紹了特定的內核子系統是如何工作的。這裡的 +大部分信息都是直接從內核原始碼獲取的，並根據需要添加補充材料（或者至少是在 +我們設法添加的時候——可能不是所有的都是有需要的）。 + +TODOList: + +* driver-api/index +* core-api/index +* locking/index +* accounting/index +* block/index +* cdrom/index +* cpu-freq/index +* ide/index +* fb/index +* fpga/index +* hid/index +* i2c/index +* iio/index +* isdn/index +* infiniband/index +* leds/index +* netlabel/index +* networking/index +* pcmcia/index +* power/index +* target/index +* timers/index +* spi/index +* w1/index +* watchdog/index +* virt/index +* input/index +* hwmon/index +* gpu/index +* security/index +* sound/index +* crypto/index +* filesystems/index +* vm/index +* bpf/index +* usb/index +* PCI/index +* scsi/index +* misc-devices/index +* scheduler/index +* mhi/index + +體系結構無關文檔 +---------------- + +TODOList: + +* asm-annotations + +特定體系結構文檔 +---------------- + +TODOList: + +* arch + +其他文檔 +-------- + +有幾份未排序的文檔似乎不適合放在文檔的其他部分，或者可能需要進行一些調整和/或 +轉換爲reStructureText格式，也有可能太舊。 + +TODOList: + +* staging/index +* watch_queue + +目錄和表格 +---------- + +* :ref:`genindex` + +.. raw:: latex + + \kerneldocEndTC diff --git a/Documentation/translations/zh_TW/io_ordering.txt b/Documentation/translations/zh_TW/io_ordering.txt new file mode 100644 index 000000000000..1e99206c8421 --- /dev/null +++ b/Documentation/translations/zh_TW/io_ordering.txt @@ -0,0 +1,68 @@ +Chinese translated version of Documentation/driver-api/io_ordering.rst + +If you have any comment or update to the content, please contact the +original document maintainer directly. However, if you have a problem +communicating in English you can also ask the Chinese maintainer for +help. Contact the Chinese maintainer if this translation is outdated +or if there is a problem with the translation. + +Traditional Chinese maintainer: Hu Haowen <src.res@email.cn> +--------------------------------------------------------------------- +Documentation/driver-api/io_ordering.rst 的繁體中文翻譯 + +如果想評論或更新本文的內容，請直接聯繫原文檔的維護者。如果你使用英文 +交流有困難的話，也可以向繁體中文版維護者求助。如果本翻譯更新不及時或 +者翻譯存在問題，請聯繫繁體中文版維護者。 + +繁體中文版維護者： 胡皓文 Hu Haowen <src.res@email.cn> +繁體中文版翻譯者： 胡皓文 Hu Haowen <src.res@email.cn> +繁體中文版校譯者： 胡皓文 Hu Haowen <src.res@email.cn> + + +以下爲正文 +--------------------------------------------------------------------- + +在某些平台上，所謂的內存映射I/O是弱順序。在這些平台上，驅動開發者有責任 +保證I/O內存映射地址的寫操作按程序圖意的順序達到設備。通常讀取一個「安全」 +設備寄存器或橋寄存器，觸發IO晶片清刷未處理的寫操作到達設備後才處理讀操作， +而達到保證目的。驅動程序通常在spinlock保護的臨界區退出之前使用這種技術。 +這也可以保證後面的寫操作只在前面的寫操作之後到達設備（這非常類似於內存 +屏障操作，mb()，不過僅適用於I/O）。 + +假設一個設備驅動程的具體例子： + + ... +CPU A: spin_lock_irqsave(&dev_lock, flags) +CPU A: val = readl(my_status); +CPU A: ... +CPU A: writel(newval, ring_ptr); +CPU A: spin_unlock_irqrestore(&dev_lock, flags) + ... +CPU B: spin_lock_irqsave(&dev_lock, flags) +CPU B: val = readl(my_status); +CPU B: ... +CPU B: writel(newval2, ring_ptr); +CPU B: spin_unlock_irqrestore(&dev_lock, flags) + ... + +上述例子中，設備可能會先接收到newval2的值，然後接收到newval的值，問題就 +發生了。不過很容易通過下面方法來修復： + + ... +CPU A: spin_lock_irqsave(&dev_lock, flags) +CPU A: val = readl(my_status); +CPU A: ... +CPU A: writel(newval, ring_ptr); +CPU A: (void)readl(safe_register); /* 配置寄存器？*/ +CPU A: spin_unlock_irqrestore(&dev_lock, flags) + ... +CPU B: spin_lock_irqsave(&dev_lock, flags) +CPU B: val = readl(my_status); +CPU B: ... +CPU B: writel(newval2, ring_ptr); +CPU B: (void)readl(safe_register); /* 配置寄存器？*/ +CPU B: spin_unlock_irqrestore(&dev_lock, flags) + +在解決方案中，讀取safe_register寄存器，觸發IO晶片清刷未處理的寫操作， +再處理後面的讀操作，防止引發數據不一致問題。 + diff --git a/Documentation/translations/zh_TW/oops-tracing.txt b/Documentation/translations/zh_TW/oops-tracing.txt new file mode 100644 index 000000000000..be8e59f2abaf --- /dev/null +++ b/Documentation/translations/zh_TW/oops-tracing.txt @@ -0,0 +1,212 @@ +Chinese translated version of Documentation/admin-guide/bug-hunting.rst + +If you have any comment or update to the content, please contact the +original document maintainer directly. However, if you have a problem +communicating in English you can also ask the Chinese maintainer for +help. Contact the Chinese maintainer if this translation is outdated +or if there is a problem with the translation. + +Traditional Chinese maintainer: Hu Haowen <src.res@email.cn> +--------------------------------------------------------------------- +Documentation/admin-guide/bug-hunting.rst 的繁體中文版翻譯 + +如果想評論或更新本文的內容，請直接聯繫原文檔的維護者。如果你使用英文 +交流有困難的話，也可以向繁體中文版維護者求助。如果本翻譯更新不及時或 +者翻譯存在問題，請聯繫繁體中文版維護者。 + +繁體中文版維護者： 胡皓文 Hu Haowen <src.res@email.cn> +繁體中文版翻譯者： 胡皓文 Hu Haowen <src.res@email.cn> +繁體中文版校譯者： 胡皓文 Hu Haowen <src.res@email.cn> + +以下爲正文 +--------------------------------------------------------------------- + +注意： ksymoops 在2.6中是沒有用的。 請以原有格式使用Oops(來自dmesg，等等)。 +忽略任何這樣那樣關於「解碼Oops」或者「通過ksymoops運行」的文檔。 如果你貼出運行過 +ksymoops的來自2.6的Oops，人們只會讓你重貼一次。 + +快速總結 +------------- + +發現Oops並發送給看似相關的內核領域的維護者。別太擔心對不上號。如果你不確定就發給 +和你所做的事情相關的代碼的負責人。 如果可重現試著描述怎樣重構。 那甚至比oops更有 +價值。 + +如果你對於發送給誰一無所知， 發給linux-kernel@vger.kernel.org。感謝你幫助Linux +儘可能地穩定。 + +Oops在哪裡? +---------------------- + +通常Oops文本由klogd從內核緩衝區里讀取並傳給syslogd，由syslogd寫到syslog文件中， +典型地是/var/log/messages(依賴於/etc/syslog.conf)。有時klogd崩潰了,這種情況下你 +能夠運行dmesg > file來從內核緩衝區中讀取數據並保存下來。 否則你可以 +cat /proc/kmsg > file， 然而你必須介入中止傳輸， kmsg是一個「永不結束的文件」。如 +果機器崩潰壞到你不能輸入命令或者磁碟不可用那麼你有三種選擇:- + +（1） 手抄屏幕上的文本待機器重啓後再輸入計算機。 麻煩但如果沒有針對崩潰的準備， +這是僅有的選擇。 另外，你可以用數位相機把屏幕拍下來-不太好，但比沒有強。 如果信 +息滾動到了終端的上面，你會發現以高分辯率啓動（比如，vga=791）會讓你讀到更多的文 +本。（注意：這需要vesafb，所以對『早期』的oops沒有幫助） + +（2）用串口終端啓動（請參看Documentation/admin-guide/serial-console.rst），運行一個null +modem到另一台機器並用你喜歡的通訊工具獲取輸出。Minicom工作地很好。 + +（3）使用Kdump（請參看Documentation/admin-guide/kdump/kdump.rst）， +使用在Documentation/admin-guide/kdump/gdbmacros.txt中定義的dmesg gdb宏，從舊的內存中提取內核 +環形緩衝區。 + +完整信息 +---------------- + +注意：以下來自於Linus的郵件適用於2.4內核。 我因爲歷史原因保留了它，並且因爲其中 +一些信息仍然適用。 特別注意的是，請忽略任何ksymoops的引用。 + +From: Linus Torvalds <torvalds@osdl.org> + +怎樣跟蹤Oops.. [原發到linux-kernel的一封郵件] + +主要的竅門是有五年和這些煩人的oops消息打交道的經驗;-) + +實際上，你有辦法使它更簡單。我有兩個不同的方法： + + gdb /usr/src/linux/vmlinux + gdb> disassemble <offending_function> + +那是發現問題的簡單辦法，至少如果bug報告做的好的情況下（象這個一樣-運行ksymoops +得到oops發生的函數及函數內的偏移）。 + +哦，如果報告發生的內核以相同的編譯器和相似的配置編譯它會有幫助的。 + +另一件要做的事是反彙編bug報告的「Code」部分：ksymoops也會用正確的工具來做這件事， +但如果沒有那些工具你可以寫一個傻程序： + + char str[] = "\xXX\xXX\xXX..."; + main(){} + +並用gcc -g編譯它然後執行「disassemble str」（XX部分是由Oops報告的值-你可以僅剪切 +粘貼並用「\x」替換空格-我就是這麼做的，因爲我懶得寫程序自動做這一切）。 + +另外，你可以用scripts/decodecode這個shell腳本。它的使用方法是： +decodecode < oops.txt + +「Code」之後的十六進位字節可能（在某些架構上）有一些當前指令之前的指令字節以及 +當前和之後的指令字節 + +Code: f9 0f 8d f9 00 00 00 8d 42 0c e8 dd 26 11 c7 a1 60 ea 2b f9 8b 50 08 a1 +64 ea 2b f9 8d 34 82 8b 1e 85 db 74 6d 8b 15 60 ea 2b f9 <8b> 43 04 39 42 54 +7e 04 40 89 42 54 8b 43 04 3b 05 00 f6 52 c0 + +最後，如果你想知道代碼來自哪裡，你可以： + + cd /usr/src/linux + make fs/buffer.s # 或任何產生BUG的文件 + +然後你會比gdb反彙編更清楚的知道發生了什麼。 + +現在，問題是把你所擁有的所有數據結合起來：C源碼（關於它應該怎樣的一般知識）， +彙編代碼及其反彙編得到的代碼（另外還有從「oops」消息得到的寄存器狀態-對了解毀壞的 +指針有用，而且當你有了彙編代碼你也能拿其它的寄存器和任何它們對應的C表達式做匹配 +）。 + +實際上，你僅需看看哪裡不匹配（這個例子是「Code」反彙編和編譯器生成的代碼不匹配）。 +然後你須要找出爲什麼不匹配。通常很簡單-你看到代碼使用了空指針然後你看代碼想知道 +空指針是怎麼出現的，還有檢查它是否合法.. + +現在，如果明白這是一項耗時的工作而且需要一丁點兒的專心，沒錯。這就是我爲什麼大多 +只是忽略那些沒有符號表信息的崩潰報告的原因：簡單的說太難查找了（我有一些 +程序用於在內核代碼段中搜索特定的模式，而且有時我也已經能找出那些崩潰的地方，但是 +僅僅是找出正確的序列也確實需要相當紮實的內核知識） + +_有時_會發生這種情況，我僅看到崩潰中的反彙編代碼序列， 然後我馬上就明白問題出在 +哪裡。這時我才意識到自己幹這個工作已經太長時間了;-) + + Linus + + +--------------------------------------------------------------------------- +關於Oops跟蹤的註解： + +爲了幫助Linus和其它內核開發者，klogd納入了大量的支持來處理保護錯誤。爲了擁有對 +地址解析的完整支持至少應該使用1.3-pl3的sysklogd包。 + +當保護錯誤發生時，klogd守護進程自動把內核日誌信息中的重要地址翻譯成它們相應的符 +號。 + +klogd執行兩種類型的地址解析。首先是靜態翻譯其次是動態翻譯。靜態翻譯和ksymoops +一樣使用System.map文件。爲了做靜態翻譯klogd守護進程必須在初始化時能找到system +map文件。關於klogd怎樣搜索map文件請參看klogd手冊頁。 + +動態地址翻譯在使用內核可裝載模塊時很重要。 因爲內核模塊的內存是從內核動態內存池 +里分配的，所以不管是模塊開始位置還是模塊中函數和符號的位置都不是固定的。 + +內核支持允許程序決定裝載哪些模塊和它們在內存中位置的系統調用。使用這些系統調用 +klogd守護進程生成一張符號表用於調試發生在可裝載模塊中的保護錯誤。 + +至少klogd會提供產生保護錯誤的模塊名。還可有額外的符號信息供可裝載模塊開發者選擇 +以從模塊中輸出符號信息。 + +因爲內核模塊環境可能是動態的，所以必須有一種機制當模塊環境發生改變時來通知klogd +守護進程。 有一些可用的命令行選項允許klogd向當前執行中的守護進程發送信號，告知符 +號信息應該被刷新了。 更多信息請參看klogd手冊頁。 + +sysklogd發布時包含一個補丁修改了modules-2.0.0包，無論何時一個模塊裝載或者卸載都 +會自動向klogd發送信號。打上這個補丁提供了必要的對調試發生於內核可裝載模塊的保護 +錯誤的無縫支持。 + +以下是被klogd處理過的發生在可裝載模塊中的一個保護錯誤例子： +--------------------------------------------------------------------------- +Aug 29 09:51:01 blizard kernel: Unable to handle kernel paging request at virtual address f15e97cc +Aug 29 09:51:01 blizard kernel: current->tss.cr3 = 0062d000, %cr3 = 0062d000 +Aug 29 09:51:01 blizard kernel: *pde = 00000000 +Aug 29 09:51:01 blizard kernel: Oops: 0002 +Aug 29 09:51:01 blizard kernel: CPU: 0 +Aug 29 09:51:01 blizard kernel: EIP: 0010:[oops:_oops+16/3868] +Aug 29 09:51:01 blizard kernel: EFLAGS: 00010212 +Aug 29 09:51:01 blizard kernel: eax: 315e97cc ebx: 003a6f80 ecx: 001be77b edx: 00237c0c +Aug 29 09:51:01 blizard kernel: esi: 00000000 edi: bffffdb3 ebp: 00589f90 esp: 00589f8c +Aug 29 09:51:01 blizard kernel: ds: 0018 es: 0018 fs: 002b gs: 002b ss: 0018 +Aug 29 09:51:01 blizard kernel: Process oops_test (pid: 3374, process nr: 21, stackpage=00589000) +Aug 29 09:51:01 blizard kernel: Stack: 315e97cc 00589f98 0100b0b4 bffffed4 0012e38e 00240c64 003a6f80 00000001 +Aug 29 09:51:01 blizard kernel: 00000000 00237810 bfffff00 0010a7fa 00000003 00000001 00000000 bfffff00 +Aug 29 09:51:01 blizard kernel: bffffdb3 bffffed4 ffffffda 0000002b 0007002b 0000002b 0000002b 00000036 +Aug 29 09:51:01 blizard kernel: Call Trace: [oops:_oops_ioctl+48/80] [_sys_ioctl+254/272] [_system_call+82/128] +Aug 29 09:51:01 blizard kernel: Code: c7 00 05 00 00 00 eb 08 90 90 90 90 90 90 90 90 89 ec 5d c3 +--------------------------------------------------------------------------- + +Dr. G.W. Wettstein Oncology Research Div. Computing Facility +Roger Maris Cancer Center INTERNET: greg@wind.rmcc.com +820 4th St. N. +Fargo, ND 58122 +Phone: 701-234-7556 + + +--------------------------------------------------------------------------- +受汙染的內核 + +一些oops報告在程序記數器之後包含字符串'Tainted: '。這表明內核已經被一些東西給汙 +染了。 該字符串之後緊跟著一系列的位置敏感的字符，每個代表一個特定的汙染值。 + + 1：'G'如果所有裝載的模塊都有GPL或相容的許可證，'P'如果裝載了任何的專有模塊。 +沒有模塊MODULE_LICENSE或者帶有insmod認爲是與GPL不相容的的MODULE_LICENSE的模塊被 +認定是專有的。 + + 2：'F'如果有任何通過「insmod -f」被強制裝載的模塊，' '如果所有模塊都被正常裝載。 + + 3：'S'如果oops發生在SMP內核中，運行於沒有證明安全運行多處理器的硬體。 當前這種 +情況僅限於幾種不支持SMP的速龍處理器。 + + 4：'R'如果模塊通過「insmod -f」被強制裝載，' '如果所有模塊都被正常裝載。 + + 5：'M'如果任何處理器報告了機器檢查異常，' '如果沒有發生機器檢查異常。 + + 6：'B'如果頁釋放函數發現了一個錯誤的頁引用或者一些非預期的頁標誌。 + + 7：'U'如果用戶或者用戶應用程式特別請求設置汙染標誌，否則' '。 + + 8：'D'如果內核剛剛死掉，比如有OOPS或者BUG。 + +使用'Tainted: '字符串的主要原因是要告訴內核調試者，這是否是一個乾淨的內核亦或發 +生了任何的不正常的事。汙染是永久的：即使出錯的模塊已經被卸載了，汙染值仍然存在， +以表明內核不再值得信任。 + diff --git a/Documentation/translations/zh_TW/process/1.Intro.rst b/Documentation/translations/zh_TW/process/1.Intro.rst new file mode 100644 index 000000000000..ca2b931be6c5 --- /dev/null +++ b/Documentation/translations/zh_TW/process/1.Intro.rst @@ -0,0 +1,199 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. include:: ../disclaimer-zh_TW.rst + +:Original: :ref:`Documentation/process/1.Intro.rst <development_process_intro>` + +:Translator: + + 時奎亮 Alex Shi <alex.shi@linux.alibaba.com> + +:校譯: + + 吳想成 Wu XiangCheng <bobwxc@email.cn> + 胡皓文 Hu Haowen <src.res@email.cn> + +.. _tw_development_process_intro: + +引言 +==== + +內容提要 +-------- + +本節的其餘部分涵蓋了內核開發的過程，以及開發人員及其僱主在這方面可能遇到的 +各種問題。有很多原因使內核代碼應被合併到正式的（「主線」）內核中，包括對用戶 +的自動可用性、多種形式的社區支持以及影響內核開發方向的能力。提供給Linux內核 +的代碼必須在與GPL兼容的許可證下可用。 + +:ref:`tw_development_process` 介紹了開發過程、內核發布周期和合併窗口的機制。 +涵蓋了補丁開發、審查和合併周期中的各個階段。還有一些關於工具和郵件列表的討論？ +鼓勵希望開始內核開發的開發人員跟蹤並修復缺陷以作爲初步練習。 + + +:ref:`tw_development_early_stage` 包括項目的早期規劃，重點是儘快讓開發社區 +參與進來。 + +:ref:`tw_development_coding` 是關於編程過程的；介紹了其他開發人員遇到的幾個 +陷阱。也涵蓋了對補丁的一些要求，並且介紹了一些工具，這些工具有助於確保內核 +補丁是正確的。 + +:ref:`tw_development_posting` 描述發布補丁以供評審的過程。爲了讓開發社區能 +認真對待，補丁必須被正確格式化和描述，並且必須發送到正確的地方。遵循本節中的 +建議有助於確保您的工作能被較好地接納。 + +:ref:`tw_development_followthrough` 介紹了發布補丁之後發生的事情；工作在這時 +還遠遠沒有完成。與審閱者一起工作是開發過程中的一個重要部分；本節提供了一些 +關於如何在這個重要階段避免問題的提示。當補丁被合併到主線中時，開發人員要注意 +不要假定任務已經完成。 + +:ref:`tw_development_advancedtopics` 介紹了兩個「高級」主題：使用Git管理補丁 +和查看其他人發布的補丁。 + +:ref:`tw_development_conclusion` 總結了有關內核開發的更多信息，附帶有相關資源 +連結。 + +這個文檔是關於什麼的 +-------------------- + +Linux內核有超過800萬行代碼，每個版本的貢獻者超過1000人，是現存最大、最活躍的 +免費軟體項目之一。從1991年開始，這個內核已經發展成爲一個最好的作業系統組件， +運行在袖珍數位音樂播放器、桌上型電腦、現存最大的超級計算機以及所有類型的系統上。 +它是一種適用於幾乎任何情況的健壯、高效和可擴展的解決方案。 + +隨著Linux的發展，希望參與其開發的開發人員（和公司）的數量也在增加。硬體供應商 +希望確保Linux能夠很好地支持他們的產品，使這些產品對Linux用戶具有吸引力。嵌入 +式系統供應商使用Linux作爲集成產品的組件，希望Linux能夠儘可能地勝任手頭的任務。 +分銷商和其他基於Linux的軟體供應商切實關心Linux內核的功能、性能和可靠性。最終 +用戶也常常希望修改Linux，使之能更好地滿足他們的需求。 + +Linux最引人注目的特性之一是這些開發人員可以訪問它；任何具備必要技能的人都可以 +改進Linux並影響其開發方向。專有產品不能提供這種開放性，這是自由軟體的一個特點。 +如果有什麼不同的話，那就是內核比大多數其他自由軟體項目更開放。一個典型的三個 +月內核開發周期可以涉及1000多個開發人員，他們爲100多個不同的公司（或者根本不 +隸屬公司）工作。 + +與內核開發社區合作並不是特別困難。但儘管如此，仍有許多潛在的貢獻者在嘗試做 +內核工作時遇到了困難。內核社區已經發展出自己獨特的操作方式，使其能夠在每天 +都要更改數千行代碼的環境中順利運行（並生成高質量的產品）。因此，Linux內核開發 +過程與專有的開發模式有很大的不同也就不足爲奇了。 + +對於新開發人員來說，內核的開發過程可能會讓人感到奇怪和恐懼，但這背後有充分的 +理由和堅實的經驗。一個不了解內核社區工作方式的開發人員（或者更糟的是，他們 +試圖拋棄或規避之）會得到令人沮喪的體驗。開發社區在幫助那些試圖學習的人的同時， +沒有時間幫助那些不願意傾聽或不關心開發過程的人。 + +希望閱讀本文的人能夠避免這種令人沮喪的經歷。這些材料很長，但閱讀它們時所做的 +努力會在短時間內得到回報。開發社區總是需要能讓內核變更好的開發人員；下面的 +文字應該幫助您或爲您工作的人員加入我們的社區。 + +致謝 +---- + +本文檔由Jonathan Corbet <corbet@lwn.net> 撰寫。以下人員的建議使之更爲完善： +Johannes Berg, James Berry, Alex Chiang, Roland Dreier, Randy Dunlap, +Jake Edge, Jiri Kosina, Matt Mackall, Arthur Marsh, Amanda McPherson, +Andrew Morton, Andrew Price, Tsugikazu Shibata 和 Jochen Voß 。 + +這項工作得到了Linux基金會的支持，特別感謝Amanda McPherson，他看到了這項工作 +的價值並將其變成現實。 + +代碼進入主線的重要性 +-------------------- + +有些公司和開發人員偶爾會想，爲什麼他們要費心學習如何與內核社區合作，並將代碼 +放入主線內核（「主線」是由Linus Torvalds維護的內核，Linux發行商將其用作基礎）。 +在短期內，貢獻代碼看起來像是一種可以避免的開銷；維護獨立代碼並直接支持用戶 +似乎更容易。事實上，保持代碼獨立（「樹外」）是在經濟上是錯誤的。 + +爲了說明樹外代碼成本，下面給出內核開發過程的一些相關方面；本文稍後將更詳細地 +討論其中的大部分內容。請考慮： + +- 所有Linux用戶都可以使用合併到主線內核中的代碼。它將自動出現在所有啓用它的 + 發行版上。無需驅動程序磁碟、額外下載，也不需要爲多個發行版的多個版本提供 + 支持；這一切將方便所有開發人員和用戶。併入主線解決了大量的分發和支持問題。 + +- 當內核開發人員努力維護一個穩定的用戶空間接口時，內核內部API處於不斷變化之中。 + 不維持穩定的內部接口是一個慎重的設計決策；它允許在任何時候進行基本的改進， + 並產出更高質量的代碼。但該策略導致結果是，若要使用新的內核，任何樹外代碼都 + 需要持續的維護。維護樹外代碼會需要大量的工作才能使代碼保持正常運行。 + + 相反，位於主線中的代碼不需要這樣做，因爲基本規則要求進行API更改的任何開發 + 人員也必須修復由於該更改而破壞的任何代碼。因此，合併到主線中的代碼大大降低 + 了維護成本。 + +- 除此之外，內核中的代碼通常會被其他開發人員改進。您授權的用戶社區和客戶對您 + 產品的改進可能會令人驚喜。 + +- 內核代碼在合併到主線之前和之後都要經過審查。無論原始開發人員的技能有多強， + 這個審查過程總是能找到改進代碼的方法。審查經常發現嚴重的錯誤和安全問題。 + 對於在封閉環境中開發的代碼尤其如此；這種代碼從外部開發人員的審查中獲益匪淺。 + 樹外代碼是低質量代碼。 + +- 參與開發過程是您影響內核開發方向的方式。旁觀者的抱怨會被聽到，但是活躍的 + 開發人員有更強的聲音——並且能夠實現使內核更好地滿足其需求的更改。 + +- 當單獨維護代碼時，總是存在第三方爲類似功能提供不同實現的可能性。如果發生 + 這種情況，合併代碼將變得更加困難——甚至成爲不可能。之後，您將面臨以下令人 + 不快的選擇：（1）無限期地維護樹外的非標準特性，或（2）放棄代碼並將用戶遷移 + 到樹內版本。 + +- 代碼的貢獻是使整個流程工作的根本。通過貢獻代碼，您可以向內核添加新功能，並 + 提供其他內核開發人員使用的功能和示例。如果您已經爲Linux開發了代碼（或者正在 + 考慮這樣做），那麼您顯然對這個平台的持續成功感興趣；貢獻代碼是確保成功的 + 最好方法之一。 + +上述所有理由都適用於任何樹外內核代碼，包括以專有的、僅二進位形式分發的代碼。 +然而，在考慮任何類型的純二進位內核代碼分布之前，還需要考慮其他因素。包括： + +- 圍繞專有內核模塊分發的法律問題其實較爲模糊；相當多的內核版權所有者認爲， + 大多數僅二進位的模塊是內核的派生產品，因此，它們的分發違反了GNU通用公共 + 許可證（下面將詳細介紹）。本文作者不是律師，本文檔中的任何內容都不可能被 + 視爲法律建議。封閉原始碼模塊的真實法律地位只能由法院決定。但不管怎樣，困擾 + 這些模塊的不確定性仍然存在。 + +- 二進位模塊大大增加了調試內核問題的難度，以至於大多數內核開發人員甚至都不會 + 嘗試。因此，只分發二進位模塊將使您的用戶更難從社區獲得支持。 + +- 對於僅二進位的模塊的發行者來說，支持也更加困難，他們必須爲他們希望支持的 + 每個發行版和每個內核版本提供不同版本的模塊。爲了提供較爲全面的覆蓋範圍， + 可能需要一個模塊的幾十個構建，並且每次升級內核時，您的用戶都必須單獨升級 + 這些模塊。 + +- 上面提到的關於代碼評審的所有問題都更加存在於封閉原始碼中。由於該代碼根本 + 不可得，因此社區無法對其進行審查，毫無疑問，它將存在嚴重問題。 + +尤其是嵌入式系統的製造商，可能會傾向於忽視本節中所說的大部分內容；因爲他們 +相信自己正在商用一種使用凍結內核版本的獨立產品，在發布後不需要再進行開發。 +這個論點忽略了廣泛的代碼審查的價值以及允許用戶向產品添加功能的價值。但這些 +產品的商業壽命有限，之後必須發布新版本的產品。在這一點上，代碼在主線上並得到 +良好維護的供應商將能夠更好地占位，以使新產品快速上市。 + +許可 +---- + +代碼是根據一些許可證提供給Linux內核的，但是所有代碼都必須與GNU通用公共許可 +證（GPLV2）的版本2兼容，該版本是覆蓋整個內核分發的許可證。在實踐中，這意味 +著所有代碼貢獻都由GPLv2（可選地，語言允許在更高版本的GPL下分發）或3子句BSD +許可（New BSD License，譯者注）覆蓋。任何不包含在兼容許可證中的貢獻都不會 +被接受到內核中。 + +貢獻給內核的代碼不需要（或請求）版權分配。合併到主線內核中的所有代碼都保留 +其原始所有權；因此，內核現在擁有數千個所有者。 + +這種所有權結構也暗示著，任何改變內核許可的嘗試都註定會失敗。很少有實際情況 +可以獲得所有版權所有者的同意（或者從內核中刪除他們的代碼）。因此，尤其是在 +可預見的將來，許可證不大可能遷移到GPL的版本3。 + +所有貢獻給內核的代碼都必須是合法的免費軟體。因此，不接受匿名（或化名）貢獻 +者的代碼。所有貢獻者都需要在他們的代碼上「sign off（簽發）」，聲明代碼可以 +在GPL下與內核一起分發。無法提供未被其所有者許可爲免費軟體的代碼，或可能爲 +內核造成版權相關問題的代碼（例如，由缺乏適當保護的反向工程工作派生的代碼） +不能被接受。 + +有關版權問題的提問在Linux開發郵件列表中很常見。這樣的問題通常會得到不少答案， +但請記住，回答這些問題的人不是律師，不能提供法律諮詢。如果您有關於Linux原始碼 +的法律問題，沒有什麼可以代替諮詢了解這一領域的律師。依賴從技術郵件列表中獲得 +的答案是一件冒險的事情。 + + diff --git a/Documentation/translations/zh_TW/process/2.Process.rst b/Documentation/translations/zh_TW/process/2.Process.rst new file mode 100644 index 000000000000..b01cdd3a39ae --- /dev/null +++ b/Documentation/translations/zh_TW/process/2.Process.rst @@ -0,0 +1,369 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. include:: ../disclaimer-zh_TW.rst + +:Original: :ref:`Documentation/process/2.Process.rst <development_process>` + +:Translator: + + 時奎亮 Alex Shi <alex.shi@linux.alibaba.com> + +:校譯: + + 吳想成 Wu XiangCheng <bobwxc@email.cn> + 胡皓文 Hu Haowen <src.res@email.cn> + +.. _tw_development_process: + +開發流程如何進行 +================ + +90年代早期的Linux內核開發是一件相當鬆散的事情，涉及的用戶和開發人員相對較少。 +由於擁有數以百萬計的用戶羣，且每年有大約2000名開發人員參與進來，內核因此必須 +發展出許多既定流程來保證開發的順利進行。要參與到流程中來，需要對此流程的進行 +方式有一個紮實的理解。 + +總覽 +---- + +內核開發人員使用一個鬆散的基於時間的發布過程，每兩到三個月發布一次新的主要 +內核版本。最近的發布歷史記錄如下： + + ====== ================= + 5.0 2019年3月3日 + 5.1 2019年5月5日 + 5.2 2019年7月7日 + 5.3 2019年9月15日 + 5.4 2019年11月24日 + 5.5 2020年1月6日 + ====== ================= + +每個5.x版本都是一個主要的內核版本，具有新特性、內部API更改等等。一個典型的5.x +版本包含大約13000個變更集，變更了幾十萬行代碼。因此，5.x是Linux內核開發的前 +沿；內核使用滾動開發模型，不斷集成重大變化。 + +對於每個版本的補丁合併，遵循一個相對簡單的規則。在每個開發周期的開頭，「合併 +窗口」被打開。這時，被認爲足夠穩定（並且被開發社區接受）的代碼被合併到主線內 +核中。在這段時間內，新開發周期的大部分變更（以及所有主要變更）將以接近每天 +1000次變更（「補丁」或「變更集」）的速度合併。 + +（順便說一句，值得注意的是，合併窗口期間集成的更改並不是憑空產生的；它們是經 +提前收集、測試和分級的。稍後將詳細描述該過程的工作方式。） + +合併窗口持續大約兩周。在這段時間結束時，LinusTorvalds將聲明窗口已關閉，並 +釋放第一個「rc」內核。例如，對於目標爲5.6的內核，在合併窗口結束時發生的釋放 +將被稱爲5.6-rc1。-rc1 版本是一個信號，表示合併新特性的時間已經過去，穩定下一 +個內核的時間已經到來。 + +在接下來的6到10周內，只有修復問題的補丁才應該提交給主線。有時會允許更大的 +更改，但這種情況很少發生；試圖在合併窗口外合併新功能的開發人員往往受不到 +友好的接待。一般來說，如果您錯過了給定特性的合併窗口，最好的做法是等待下一 +個開發周期。（偶爾會對未支持硬體的驅動程序進行例外；如果它們不改變已有代碼， +則不會導致回歸，應該可以隨時被安全地加入）。 + +隨著修復程序進入主線，補丁速度將隨著時間的推移而變慢。Linus大約每周發布一次 +新的-rc內核；在內核被認爲足夠穩定並最終發布前，一般會達到-rc6到-rc9之間。 +然後，整個過程又重新開始了。 + +例如，這裡是5.4的開發周期進行情況（2019年）: + + ============== ============================== + 九月 15 5.3 穩定版發布 + 九月 30 5.4-rc1 合併窗口關閉 + 十月 6 5.4-rc2 + 十月 13 5.4-rc3 + 十月 20 5.4-rc4 + 十月 27 5.4-rc5 + 十一月 3 5.4-rc6 + 十一月 10 5.4-rc7 + 十一月 17 5.4-rc8 + 十一月 24 5.4 穩定版發布 + ============== ============================== + +開發人員如何決定何時結束開發周期並創建穩定版本？最重要的指標是以前版本的 +回歸列表。不歡迎出現任何錯誤，但是那些破壞了以前能工作的系統的錯誤被認爲是 +特別嚴重的。因此，導致回歸的補丁是不受歡迎的，很可能在穩定期內刪除。 + +開發人員的目標是在穩定發布之前修復所有已知的回歸。在現實世界中，這種完美是 +很難實現的；在這種規模的項目中，變數太多了。需要說明的是，延遲最終版本只會 +使問題變得更糟；等待下一個合併窗口的更改將變多，導致下次出現更多的回歸錯誤。 +因此，大多數5.x內核都有一些已知的回歸錯誤，不過，希望沒有一個是嚴重的。 + +一旦一個穩定的版本發布，它的持續維護工作就被移交給「穩定團隊」，目前由 +Greg Kroah-Hartman領導。穩定團隊將使用5.x.y編號方案不定期地發布穩定版本的 +更新。要合入更新版本，補丁必須（1）修復一個重要的缺陷，且（2）已經合併到 +下一個開發版本主線中。內核通常會在其初始版本後的一個以上的開發周期內收到 +穩定版更新。例如，5.2內核的歷史如下（2019年）： + + ============== =============================== + 七月 7 5.2 穩定版發布 + 七月 13 5.2.1 + 七月 21 5.2.2 + 七月 26 5.2.3 + 七月 28 5.2.4 + 七月 31 5.2.5 + ... ... + 十月 11 5.2.21 + ============== =============================== + +5.2.21是5.2版本的最終穩定更新。 + +有些內核被指定爲「長期」內核；它們將得到更長時間的支持。在本文中，當前的長期 +內核及其維護者是： + + ====== ================================ ================ + 3.16 Ben Hutchings （長期穩定內核） + 4.4 Greg Kroah-Hartman & Sasha Levin （長期穩定內核） + 4.9 Greg Kroah-Hartman & Sasha Levin + 4.14 Greg Kroah-Hartman & Sasha Levin + 4.19 Greg Kroah-Hartman & Sasha Levin + 5.4 Greg Kroah-Hartman & Sasha Levin + ====== ================================ ================ + +長期支持內核的選擇純粹是維護人員是否有需求和時間來維護該版本的問題。 +目前還沒有爲即將發布的任何特定版本提供長期支持的已知計劃。 + +補丁的生命周期 +-------------- + +補丁不會直接從開發人員的鍵盤進入主線內核。相反，有一個稍微複雜（如果有些非 +正式）的過程，旨在確保對每個補丁進行質量審查，並確保每個補丁實現了一個在主線 +中需要的更改。對於小的修復，這個過程可能會很快完成，，而對於較大或有爭議的 +變更，可能會持續數年。許多開發人員的沮喪來自於對這個過程缺乏理解或者試圖繞過它。 + +爲了減少這種挫敗，本文將描述補丁如何進入內核。下面的介紹以一種較爲理想化的 +方式描述了這個過程。更詳細的過程將在後面的章節中介紹。 + +補丁通常要經歷以下階段： + +- 設計。這就是補丁的真正需求——以及滿足這些需求的方式——所在。設計工作通常 + 是在不涉及社區的情況下完成的，但是如果可能的話，最好是在公開的情況下完成 + 這項工作；這樣可以節省很多稍後再重新設計的時間。 + +- 早期評審。補丁被發布到相關的郵件列表中，列表中的開發人員會回復他們可能有 + 的任何評論。如果一切順利的話，這個過程應該會發現補丁的任何主要問題。 + +- 更廣泛的評審。當補丁接近準備好納入主線時，它應該被相關的子系統維護人員 + 接受——儘管這種接受並不能保證補丁會一直延伸到主線。補丁將出現在維護人員的 + 子系統樹中，並進入 -next 樹（如下所述）。當流程進行時，此步驟將會對補丁 + 進行更廣泛的審查，並發現由於將此補丁與其他人所做的工作合併而導致的任何 + 問題。 + +- 請注意，大多數維護人員也有日常工作，因此合併補丁可能不是他們的最優先工作。 + 如果您的補丁得到了需要更改的反饋，那麼您應該進行這些更改，或者解釋爲何 + 不應該進行這些更改。如果您的補丁沒有評審意見，也沒有被其相應的子系統或 + 驅動程序維護者接受，那麼您應該堅持不懈地將補丁更新到當前內核使其可被正常 + 應用，並不斷地發送它以供審查和合併。 + +- 合併到主線。最終，一個成功的補丁將被合併到由LinusTorvalds管理的主線存儲庫 + 中。此時可能會出現更多的評論和/或問題；對開發人員來說應對這些問題並解決 + 出現的任何問題仍很重要。 + +- 穩定版發布。大量用戶可能受此補丁影響，因此可能再次出現新的問題。 + +- 長期維護。雖然開發人員在合併代碼後可能會忘記代碼，但這種行爲往往會給開發 + 社區留下不良印象。合併代碼消除了一些維護負擔，因爲其他人將修復由API更改 + 引起的問題。但是，如果代碼要長期保持可用，原始開發人員應該繼續爲代碼負責。 + +內核開發人員（或他們的僱主）犯的最大錯誤之一是試圖將流程簡化爲一個「合併到 +主線」步驟。這種方法總是會讓所有相關人員感到沮喪。 + +補丁如何進入內核 +---------------- + +只有一個人可以將補丁合併到主線內核存儲庫中：LinusTorvalds。但是，在進入 +2.6.38內核的9500多個補丁中，只有112個（大約1.3%）是由Linus自己直接選擇的。 +內核項目已經發展到一個沒有一個開發人員可以在沒有支持的情況下檢查和選擇每個 +補丁的規模。內核開發人員處理這種增長的方式是使用圍繞信任鏈構建的助理系統。 + +內核代碼庫在邏輯上被分解爲一組子系統：網絡、特定體系結構支持、內存管理、視 +頻設備等。大多數子系統都有一個指定的維護人員，其總體負責該子系統中的代碼。 +這些子系統維護者（鬆散地）是他們所管理的內核部分的「守門員」；他們（通常） +會接受一個補丁以包含到主線內核中。 + +子系統維護人員每個人都管理著自己版本的內核原始碼樹，通常（並非總是）使用Git。 +Git等工具（以及Quilt或Mercurial等相關工具）允許維護人員跟蹤補丁列表，包括作者 +信息和其他元數據。在任何給定的時間，維護人員都可以確定他或她的存儲庫中的哪 +些補丁在主線中找不到。 + +當合併窗口打開時，頂級維護人員將要求Linus從存儲庫中「拉出」他們爲合併選擇 +的補丁。如果Linus同意，補丁流將流向他的存儲庫，成爲主線內核的一部分。 +Linus對拉取中接收到的特定補丁的關注程度各不相同。很明顯，有時他看起來很 +關注。但是一般來說，Linus相信子系統維護人員不會向上游發送壞補丁。 + +子系統維護人員反過來也可以從其他維護人員那裡獲取補丁。例如，網絡樹是由首先 +在專用於網絡設備驅動程序、無線網絡等的樹中積累的補丁構建的。此存儲鏈可以 +任意長，但很少超過兩個或三個連結。由於鏈中的每個維護者都信任那些管理較低 +級別樹的維護者，所以這個過程稱爲「信任鏈」。 + +顯然，在這樣的系統中，獲取內核補丁取決於找到正確的維護者。直接向Linus發送 +補丁通常不是正確的方法。 + +Next 樹 +------- + +子系統樹鏈引導補丁流到內核，但它也提出了一個有趣的問題：如果有人想查看爲 +下一個合併窗口準備的所有補丁怎麼辦？開發人員將感興趣的是，還有什麼其他的 +更改有待解決，以了解是否存在需要擔心的衝突；例如，更改核心內核函數原型的 +修補程序將與使用該函數舊形式的任何其他修補程序衝突。審查人員和測試人員希望 +在所有這些變更到達主線內核之前，能夠訪問它們的集成形式的變更。您可以從所有 +相關的子系統樹中提取更改，但這將是一項複雜且容易出錯的工作。 + +解決方案以-next樹的形式出現，在這裡子系統樹被收集以供測試和審查。這些樹中 +由Andrew Morton維護的較老的一個，被稱爲「-mm」（用於內存管理，創建時爲此）。 +-mm 樹集成了一長串子系統樹中的補丁；它還包含一些旨在幫助調試的補丁。 + +除此之外，-mm 還包含大量由Andrew直接選擇的補丁。這些補丁可能已經發布在郵件 +列表上，或者它們可能應用於內核中未指定子系統樹的部分。同時，-mm 作爲最後 +手段的子系統樹；如果沒有其他明顯的路徑可以讓補丁進入主線，那麼它很可能最 +終選擇-mm 樹。累積在-mm 中的各種補丁最終將被轉發到適當的子系統樹，或者直接 +發送到Linus。在典型的開發周期中，大約5-10%的補丁通過-mm 進入主線。 + +當前-mm 補丁可在「mmotm」（-mm of the moment）目錄中找到： + + https://www.ozlabs.org/~akpm/mmotm/ + +然而，使用MMOTM樹可能會十分令人頭疼；它甚至可能無法編譯。 + +下一個周期補丁合併的主要樹是linux-next，由Stephen Rothwell 維護。根據設計 +linux-next 是下一個合併窗口關閉後主線的快照。linux-next樹在Linux-kernel 和 +Linux-next 郵件列表中發布，可從以下位置下載： + + https://www.kernel.org/pub/linux/kernel/next/ + +Linux-next 已經成爲內核開發過程中不可或缺的一部分；在一個給定的合併窗口中合併 +的所有補丁都應該在合併窗口打開之前的一段時間內找到進入Linux-next 的方法。 + +Staging 樹 +---------- + +內核原始碼樹包含drivers/staging/目錄，其中有許多驅動程序或文件系統的子目錄 +正在被添加到內核樹中。它們在仍然需要更多的修正的時候可以保留在driver/staging/ +目錄中；一旦完成，就可以將它們移到內核中。這是一種跟蹤不符合Linux內核編碼或 +質量標準的驅動程序的方法，人們可能希望使用它們並跟蹤開發。 + +Greg Kroah Hartman 目前負責維護staging 樹。仍需要修正的驅動程序將發送給他， +每個驅動程序在drivers/staging/中都有自己的子目錄。除了驅動程序源文件之外， +目錄中還應該有一個TODO文件。TODO文件列出了驅動程序需要接受的暫停的工作， +以及驅動程序的任何補丁都應該抄送的人員列表。當前的規則要求，staging的驅動 +程序必須至少正確編譯。 + +Staging 是一種讓新的驅動程序進入主線的相對容易的方法，它們會幸運地引起其他 +開發人員的注意，並迅速改進。然而，進入staging並不是故事的結尾；staging中 +沒有看到常規進展的代碼最終將被刪除。經銷商也傾向於相對不願意使用staging驅動 +程序。因此，在成爲一個合適的主線驅動的路上，staging 僅是一個中轉站。 + +工具 +---- + +從上面的文本可以看出，內核開發過程在很大程度上依賴於在不同方向上聚集補丁的 +能力。如果沒有適當強大的工具，整個系統將無法在任何地方正常工作。關於如何使用 +這些工具的教程遠遠超出了本文檔的範圍，但還是用一點篇幅介紹一些關鍵點。 + +到目前爲止，內核社區使用的主要原始碼管理系統是git。Git是在自由軟體社區中開發 +的許多分布式版本控制系統之一。它非常適合內核開發，因爲它在處理大型存儲庫和 +大量補丁時性能非常好。它也以難以學習和使用而著稱，儘管隨著時間的推移它變得 +更好了。對於內核開發人員來說，對Git的某種熟悉幾乎是一種要求；即使他們不將它 +用於自己的工作，他們也需要Git來跟上其他開發人員（以及主線）正在做的事情。 + +現在幾乎所有的Linux發行版都打包了Git。Git主頁位於： + + https://git-scm.com/ + +此頁面包含了文檔和教程的連結。 + +在不使用git的內核開發人員中，最流行的選擇幾乎肯定是Mercurial： + + http://www.seleric.com/mercurial/ + +Mercurial與Git共享許多特性，但它提供了一個界面，許多人覺得它更易於使用。 + +另一個值得了解的工具是Quilt: + + https://savannah.nongnu.org/projects/quilt + +Quilt 是一個補丁管理系統，而不是原始碼管理系統。它不會隨著時間的推移跟蹤歷史； +相反，它面向根據不斷發展的代碼庫跟蹤一組特定的更改。一些主要的子系統維護人員 +使用Quilt來管理打算向上游移動的補丁。對於某些樹的管理（例如-mm），quilt 是 +最好的工具。 + +郵件列表 +-------- + +大量的Linux內核開發工作是通過郵件列表完成的。如果不加入至少一個某個列表， +就很難成爲社區中的一個「全功能」成員。但是，Linux郵件列表對開發人員來說也是 +一個潛在的危險，他們可能會被一堆電子郵件淹沒、違反Linux列表上使用的約定， +或者兩者兼而有之。 + +大多數內核郵件列表都在vger.kernel.org上運行；主列表位於： + + http://vger.kernel.org/vger-lists.html + +不過，也有一些列表託管在別處；其中一些列表位於 +redhat.com/mailman/listinfo。 + +當然，內核開發的核心郵件列表是linux-kernel。這個列表是一個令人生畏的地方： +每天的信息量可以達到500條，噪音很高，談話技術性很強，且參與者並不總是表現出 +高度的禮貌。但是，沒有其他地方可以讓內核開發社區作爲一個整體聚集在一起； +不使用此列表的開發人員將錯過重要信息。 + +以下一些提示可以幫助在linux-kernel生存： + +- 將郵件轉移到單獨的文件夾，而不是主郵箱文件夾。我們必須能夠持續地忽略洪流。 + +- 不要試圖跟上每一次談話——沒人會這樣。重要的是要篩選感興趣的主題（但請注意 + 長時間的對話可能會偏離原來的主題，儘管未改變電子郵件的主題）和參與的人。 + +- 不要回復挑事的人。如果有人試圖激起憤怒，請忽略他們。 + +- 當回復Linux內核電子郵件（或其他列表上的電子郵件）時，請爲所有相關人員保留 + Cc: 抄送頭。如果沒有確實的理由（如明確的請求），則不應刪除收件人。一定要 + 確保你要回復的人在抄送列表中。這個慣例也使你不必在回覆郵件時明確要求被抄送。 + +- 在提出問題之前，搜索列表存檔（和整個網絡）。有些開發人員可能會對那些顯然 + 沒有完成家庭作業的人感到不耐煩。 + +- 避免頂部回復（把你的答案放在你要回復的引文上面的做法）。這會讓你的回答更難 + 理解，印象也很差。 + +- 在正確的郵件列表發問。linux-kernel 可能是通用的討論場所，但它不是尋找所有 + 子系統開發人員的最佳場所。 + +最後一點——找到正確的郵件列表——是開發人員常出錯的地方。在linux-kernel上 +提出與網絡相關的問題的人幾乎肯定會收到一個禮貌的建議，轉到netdev列表上提出， +因爲這是大多數網絡開發人員經常出現的列表。還有其他列表可用於scsi、video4linux、 +ide、filesystem等子系統。查找郵件列表的最佳位置是與內核原始碼一起打包的 +MAINTAINERS文件。 + +開始內核開發 +------------ + +關於如何開始內核開發過程的問題很常見——個人和公司皆然。同樣常見的是失誤，這 +使得關係的開始比本應的更困難。 + +公司通常希望聘請知名的開發人員來啓動開發團隊。實際上，這是一種有效的技術。 +但它也往往是昂貴的，而且對增加有經驗的內核開發人員的數量沒有多大幫助。考 +慮到時間投入，可以讓內部開發人員加快Linux內核的開發速度。利用這段時間可以 +讓僱主擁有一批既了解內核又了解公司的開發人員，還可以幫助培訓其他人。從中期 +來看，這通常是更有利可圖的方法。 + +可以理解的是，單個開發人員往往對起步感到茫然。從一個大型項目開始可能會很 +嚇人；人們往往想先用一些較小的東西來試試水。由此，一些開發人員開始創建修補 +拼寫錯誤或輕微編碼風格問題的補丁。不幸的是，這樣的補丁會產生一定程度的噪音， +這會分散整個開發社區的注意力，因此，它們越來越被人不看重。希望向社區介紹 +自己的新開發人員將無法通過這些方式獲得他們期待的反響。 + +Andrew Morton 爲有抱負的內核開發人員提供了如下建議 + +:: + + 所有內核開發者的第一個項目肯定應該是「確保內核在您可以操作的所有 + 機器上始終完美運行」。通常的方法是和其他人一起解決問題（這可能需 + 要堅持！），但就是如此——這是內核開發的一部分。 + +(http://lwn.net/articles/283982/) + +在沒有明顯問題需要解決的情況下，通常建議開發人員查看當前的回歸和開放缺陷 +列表。從來都不缺少需要解決的問題；通過解決這些問題，開發人員將從該過程獲得 +經驗，同時與開發社區的其他成員建立相互尊重。 + diff --git a/Documentation/translations/zh_TW/process/3.Early-stage.rst b/Documentation/translations/zh_TW/process/3.Early-stage.rst new file mode 100644 index 000000000000..ab2a45fd65a4 --- /dev/null +++ b/Documentation/translations/zh_TW/process/3.Early-stage.rst @@ -0,0 +1,172 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. include:: ../disclaimer-zh_TW.rst + +:Original: :ref:`Documentation/process/3.Early-stage.rst <development_early_stage>` + +:Translator: + + 時奎亮 Alex Shi <alex.shi@linux.alibaba.com> + +:校譯: + + 吳想成 Wu XiangCheng <bobwxc@email.cn> + 胡皓文 Hu Haowen <src.res@email.cn> + +.. _tw_development_early_stage: + +早期規劃 +======== + +當考慮一個Linux內核開發項目時，很可能會直接跳進去開始編碼。然而，與任何重要 +的項目一樣，許多成功的基礎最好是在第一行代碼編寫之前就打下。在早期計劃和 +溝通中花費一些時間可以在之後節省更多的時間。 + +搞清問題 +-------- + +與任何工程項目一樣，成功的內核改善從清晰描述要解決的問題開始。在某些情況 +下，這個步驟很容易：例如當某個特定硬體需要驅動程序時。不過，在其他情況下， +很容易將實際問題與建議的解決方案混在一起，這可能會導致麻煩。 + +舉個例子：幾年前，Linux音頻的開發人員尋求一種方法來運行應用程式，而不會因 +系統延遲過大而導致退出或其他問題。他們得到的解決方案是一個連接到Linux安全 +模塊（LSM）框架中的內核模塊；這個模塊可以配置爲允許特定的應用程式訪問實時 +調度程序。這個模塊被實現並發到linux-kernel郵件列表，在那裡它立即遇到了麻煩。 + +對於音頻開發人員來說，這個安全模塊足以解決他們當前的問題。但是，對於更廣泛的 +內核社區來說，這被視爲對LSM框架的濫用（LSM框架並不打算授予他們原本不具備的 +進程特權），並對系統穩定性造成風險。他們首選的解決方案包括短期的通過rlimit +機制進行實時調度訪問，以及長期的減少延遲的工作。 + +然而，音頻社區無法超越他們實施的特定解決方案來看問題；他們不願意接受替代方案。 +由此產生的分歧使這些開發人員對整個內核開發過程感到失望；其中一個開發人員返回 +到audio列表並發布了以下內容： + + 有很多非常好的Linux內核開發人員，但他們往往會被一羣傲慢的傻瓜所壓倒。 + 試圖向這些人傳達用戶需求是浪費時間。他們太「聰明」了，根本聽不到少數 + 人的話。 + +（http://lwn.net/articles/131776/） + +實際情況卻是不同的；與特定模塊相比，內核開發人員更關心系統穩定性、長期維護 +以及找到問題的正確解決方案。這個故事的寓意是把重點放在問題上——而不是具體的 +解決方案上——並在開始編寫代碼之前與開發社區討論這個問題。 + +因此，在考慮一個內核開發項目時，我們應該得到一組簡短問題的答案： + + - 需要解決的問題究竟是什麼？ + + - 受此問題影響的用戶有哪些？解決方案應該解決哪些使用案例？ + + - 內核現在爲何沒能解決這個問題？ + +只有這樣，才能開始考慮可能的解決方案。 + + +早期討論 +-------- + +在計劃內核開發項目時，在開始實施之前與社區進行討論是很有意義的。早期溝通可以 +通過多種方式節省時間和麻煩： + + - 很可能問題是由內核以您不理解的方式解決的。Linux內核很大，具有許多不明顯 + 的特性和功能。並不是所有的內核功能都像人們所希望的那樣有文檔記錄，而且很 + 容易遺漏一些東西。某作者發布了一個完整的驅動程序，重複了一個其不 + 知道的現有驅動程序。重新發明現有輪子的代碼不僅浪費，而且不會被接受到主線 + 內核中。 + + - 建議的解決方案中可能有一些要素不適合併入主線。在編寫代碼之前，最好先了解 + 這樣的問題。 + + - 其他開發人員完全有可能考慮過這個問題；他們可能有更好的解決方案的想法，並且 + 可能願意幫助創建這個解決方案。 + +在內核開發社區的多年經驗給了我們一個明確的教訓：閉門設計和開發的內核代碼總是 +有一些問題，這些問題只有在代碼發布到社區中時才會被發現。有時這些問題很嚴重， +需要數月或數年的努力才能使代碼達到內核社區的標準。例如： + + - 設計並實現了單處理器系統的DeviceScape網絡棧。只有使其適合於多處理器系統， + 才能將其合併到主線中。在代碼中修改鎖等等是一項困難的任務；因此，這段代碼 + （現在稱爲mac80211）的合併被推遲了一年多。 + + - Reiser4文件系統包含許多功能，核心內核開發人員認爲這些功能應該在虛擬文件 + 系統層中實現。它還包括一些特性，這些特性在不將系統暴露於用戶引起的死鎖的 + 情況下是不容易實現的。這些問題過遲發現——以及拒絕處理其中一些問題——已經 + 導致Reiser4置身主線內核之外。 + + - Apparmor安全模塊以被認爲不安全和不可靠的方式使用內部虛擬文件系統數據結構。 + 這種擔心（包括其他）使Apparmor多年來無法進入主線。 + +在這些情況下，與內核開發人員的早期討論，可以避免大量的痛苦和額外的工作。 + +找誰交流？ +---------- + +當開發人員決定公開他們的計劃時，下一個問題是：我們從哪裡開始？答案是找到正確 +的郵件列表和正確的維護者。對於郵件列表，最好的方法是在維護者(MAINTAINERS)文件 +中查找要發布的相關位置。如果有一個合適的子系統列表，那麼其上發布通常比在 +linux-kernel上發布更可取；您更有可能接觸到在相關子系統中具有專業知識的開發 +人員，並且環境可能具支持性。 + +找到維護人員可能會有點困難。同樣，維護者文件是開始的地方。但是，該文件往往不 +是最新的，並且並非所有子系統都在那裡顯示。實際上，維護者文件中列出的人員可能 +不是當前實際擔任該角色的人員。因此，當對聯繫誰有疑問時，一個有用的技巧是使用 +git（尤其是「git-log」）查看感興趣的子系統中當前活動的用戶。看看誰在寫補丁、 +誰會在這些補丁上加上Signed-off-by行簽名（如有）。這些人將是幫助新開發項目的 +最佳人選。 + +找到合適的維護者有時是非常具有挑戰性的，以至於內核開發人員添加了一個腳本來 +簡化這個過程： + +:: + + .../scripts/get_maintainer.pl + +當給定「-f」選項時，此腳本將返回指定文件或目錄的當前維護者。如果在命令行上 +給出了一個補丁，它將列出可能接收補丁副本的維護人員。有許多選項可以調節 +get_maintainer.pl搜索維護者的嚴格程度；請小心使用更激進的選項，因爲最終結果 +可能會包括對您正在修改的代碼沒有真正興趣的開發人員。 + +如果所有其他方法都失敗了，那麼與Andrew Morton交流是跟蹤特定代碼段維護人員 +的一種有效方法。 + +何時郵寄？ +---------- + +如果可能的話，在早期階段發布你的計劃只會更有幫助。描述正在解決的問題以及已經 +制定的關於如何實施的任何計劃。您可以提供的任何信息都可以幫助開發社區爲項目 +提供有用的輸入。 + +在這個階段可能發生的一件令人沮喪的事情不是得到反對意見，而是很少或根本沒有 +反饋。令人傷心的事實是：（1）內核開發人員往往很忙；（2）不缺少有宏偉計劃但 +代碼（甚至代碼設想）很少的人去支持他們；（3）沒有人有義務審查或評論別人發表 +的想法。除此之外，高層級的設計常常隱藏著一些問題，這些問題只有在有人真正嘗試 +實現這些設計時才會被發現；因此，內核開發人員寧願看到代碼。 + +如果發布請求評論（RFC）並沒得到什麼有用的評論，不要以爲這意味著無人對此項目 +有興趣，同時你也不能假設你的想法沒有問題。在這種情況下，最好的做法是繼續進 +行，把你的進展隨時通知社區。 + +獲得官方認可 +----------------------- + +如果您的工作是在公司環境中完成的，就像大多數Linux內核工作一樣；顯然，在您將 +公司的計劃或代碼發布到公共郵件列表之前，必須獲得有適當權利經理的許可。發布 +不確定是否兼容GPL的代碼尤其會帶來問題；公司的管理層和法律人員越早能夠就發布 +內核開發項目達成一致，對參與的每個人都越好。 + +一些讀者可能會認爲他們的核心工作是爲了支持還沒有正式承認存在的產品。將僱主 +的計劃公布在公共郵件列表上可能不是一個可行的選擇。在這種情況下，有必要考慮 +保密是否真的是必要的；通常不需要把開發計劃關在門內。 + +的確，有些情況下一家公司在開發過程的早期無法合法地披露其計劃。擁有經驗豐富 +的內核開發人員的公司可能選擇以開環的方式進行開發，前提是他們以後能夠避免 +嚴重的集成問題。對於沒有這種內部專業知識的公司，最好的選擇往往是聘請外部 +開發者根據保密協議審查計劃。Linux基金會運行了一個NDA程序，旨在幫助解決這種 +情況；更多信息參見： + + http://www.linuxfoundation.org/nda/ + +這種審查通常足以避免以後出現嚴重問題，而無需公開披露項目。 + diff --git a/Documentation/translations/zh_TW/process/4.Coding.rst b/Documentation/translations/zh_TW/process/4.Coding.rst new file mode 100644 index 000000000000..ccc3946227a0 --- /dev/null +++ b/Documentation/translations/zh_TW/process/4.Coding.rst @@ -0,0 +1,297 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. include:: ../disclaimer-zh_TW.rst + +:Original: :ref:`Documentation/process/4.Coding.rst <development_coding>` + +:Translator: + + 時奎亮 Alex Shi <alex.shi@linux.alibaba.com> + +:校譯: + + 吳想成 Wu XiangCheng <bobwxc@email.cn> + 胡皓文 Hu Haowen <src.res@email.cn> + +.. _tw_development_coding: + +使代碼正確 +====================== + +雖然一個堅實的、面向社區的設計過程有很多值得說道的，但是任何內核開發項目工作 +的證明都反映在代碼中。它是將由其他開發人員檢查併合並（或不合併）到主線樹中 +的代碼。所以這段代碼的質量決定了項目的最終成功。 + +本節將檢查編碼過程。我們將從內核開發人員常犯的幾種錯誤開始。然後重點將轉移 +到正確的做法和相關有用的工具上。 + +陷阱 +---- + +代碼風格 +******** + +內核長期以來都有其標準的代碼風格，如 +:ref:`Documentation/translations/zh_TW/process/coding-style.rst <tw_codingstyle>` +中所述。在多數時候，該文檔中描述的準則至多被認爲是建議性的。因此，內核中存在 +大量不符合代碼風格準則的代碼。這種代碼的存在會給內核開發人員帶來兩方面的危害。 + +首先，相信內核代碼標準並不重要，也不強制執行。但事實上，如果沒有按照標準 +編寫代碼，那麼新代碼將很難加入到內核中；許多開發人員甚至會在審查代碼之前要求 +對代碼進行重新格式化。一個像內核這麼大的代碼庫需要一些統一格式的代碼，以使 +開發人員能夠快速理解其中的任何部分。所以再也經不起奇怪格式的代碼的折騰了。 + +內核的代碼風格偶爾會與僱主的強制風格發生衝突。在這種情況下，必須在代碼合併 +之前遵從內核代碼風格。將代碼放入內核意味著以多種方式放棄一定程度的控制權—— +包括控制代碼樣式。 + +另一個危害是認爲已經在內核中的代碼迫切需要修復代碼樣式。開發者可能會開始編寫 +重新格式化補丁，作爲熟悉開發過程的一種方式，或者作爲將其名字寫入內核變更日誌 +的一種方式，或者兩者兼而有之。但是純代碼風格的修復被開發社區視爲噪音，它們往 +往受到冷遇。因此，最好避免編寫這種類型的補丁。在由於其他原因處理一段代碼的 +同時順帶修復其樣式是很自然的，但是不應該僅爲了更改代碼樣式而更改之。 + +代碼風格文檔也不應該被視爲絕對不可違反的規則。如果有一個足夠的理由反對這種 +樣式（例如爲了80列限制拆分行會導致可讀性大大降低），那麼就這樣做吧。 + +注意您還可以使用 ``clang-format`` 工具來幫助您處理這些規則，快速自動重新格式 +化部分代碼，和審閱完整的文件以發現代碼樣式錯誤、拼寫錯誤和可能的改進。它還 +可以方便地排序 ``#includes`` 、對齊變量/宏、重排文本和其他類似任務。有關詳細 +信息，請參閱文檔 :ref:`Documentation/process/clang-format.rst <clangformat>` + +抽象層 +****** + +計算機科學教授教學生以靈活性和信息隱藏的名義廣泛使用抽象層。當然，內核廣泛 +地使用了抽象；任何涉及數百萬行代碼的項目都必須做到這一點以存續下來。但經驗 +表明，過度或過早的抽象可能和過早的優化一樣有害。抽象應用在適當層級， +不要過度。 + +簡單點，先考慮一個調用時始終只有一個參數且總爲零的函數。我們可以保留這個參數， +以在需要使用它時提供的額外靈活性。不過，在那時實現了這個額外參數的代碼很有 +可能以某種從未被注意到的微妙方式被破壞——因爲它從未被使用過。或者當需要額外 +的靈活性時，它並未以符合程式設計師當初期望的方式來實現。內核開發人員通常會提交 +補丁來刪除未使用的參數；一般來說，一開始就不應該添加這些參數。 + +隱藏硬體訪問的抽象層——通常爲了允許大量的驅動程序兼容多個作業系統——尤其不受 +歡迎。這樣的層使代碼變得模糊，可能會造成性能損失；它們不屬於Linux內核。 + +另一方面，如果您發現自己從另一個內核子系統複製了大量的代碼，那麼是時候 +了解一下：是否需要將這些代碼中的部分提取到單獨的庫中，或者在更高的層次上 +實現這些功能。在整個內核中複製相同的代碼沒有價值。 + +#ifdef 和預處理 +*************** + +C預處理器似乎給一些C程式設計師帶來了強大的誘惑，他們認爲它是一種將大量靈活性加入 +原始碼中的方法。但是預處理器不是C，大量使用它會導致代碼對其他人來說更難閱讀， +對編譯器來說更難檢查正確性。使用了大量預處理器幾乎總是代碼需要一些 +清理工作的標誌。 + +使用#ifdef的條件編譯實際上是一個強大的功能，它在內核中使用。但是很少有人希望 +看到代碼被鋪滿#ifdef塊。一般規定，ifdef的使用應儘可能限制在頭文件中。條件 +編譯代碼可以限制函數，如果代碼不存在，這些函數就直接變成空的。然後編譯器將 +悄悄地優化對空函數的調用。使得代碼更加清晰，更容易理解。 + +C預處理器宏存在許多危險性，包括可能對具有副作用且沒有類型安全的表達式進行多 +重評估。如果您試圖定義宏，請考慮創建一個內聯函數替代。結果相同的代碼，內聯 +函數更容易閱讀，不會多次計算其參數，並且允許編譯器對參數和返回值執行類型檢查。 + +內聯函數 +******** + +不過，內聯函數本身也存在風險。程式設計師可以傾心於避免函數調用和用內聯函數填充源 +文件所固有的效率。然而，這些功能實際上會降低性能。因爲它們的代碼在每個調用站 +點都被複製一遍，所以最終會增加編譯內核的大小。此外，這也對處理器的內存緩存 +造成壓力，從而大大降低執行速度。通常內聯函數應該非常小，而且相對較少。畢竟 +函數調用的成本並不高；大量創建內聯函數是過早優化的典型例子。 + +一般來說，內核程式設計師會自冒風險忽略緩存效果。在數據結構課程開頭中的經典 +時間/空間權衡通常不適用於當代硬體。空間 *就是* 時間，因爲一個大的程序比一個 +更緊湊的程序運行得慢。 + +較新的編譯器越來越激進地決定一個給定函數是否應該內聯。因此，隨意放置使用 +「inline」關鍵字可能不僅僅是過度的，也可能是無用的。 + +鎖 +** + +2006年5月，「deviceescape」網絡堆棧在前呼後擁下以GPL發布，並被納入主線內核。 +這是一個受歡迎的消息；Linux中對無線網絡的支持充其量被認爲是不合格的，而 +Deviceescape堆棧承諾修復這種情況。然而直到2007年6月（2.6.22），這段代碼才真 +正進入主線。發生了什麼？ + +這段代碼出現了許多閉門造車的跡象。但一個大麻煩是，它並不是爲多處理器系統而 +設計。在合併這個網絡堆棧（現在稱爲mac80211）之前，需要對其進行一個鎖方案的 +改造。 + +曾經，Linux內核代碼可以在不考慮多處理器系統所帶來的並發性問題的情況下進行 +開發。然而現在，這個文檔就是在雙核筆記本電腦上寫的。即使在單處理器系統上， +爲提高響應能力所做的工作也會提高內核內的並發性水平。編寫內核代碼而不考慮鎖 +的日子早已遠去。 + +可以由多個線程並發訪問的任何資源（數據結構、硬體寄存器等）必須由鎖保護。新 +的代碼應該謹記這一要求；事後修改鎖是一項相當困難的任務。內核開發人員應該花 +時間充分了解可用的鎖原語，以便爲工作選擇正確的工具。對並發性缺乏關注的代碼 +很難進入主線。 + +回歸 +**** + +最後一個值得一提的危險是回歸：它可能會引起導致現有用戶的某些東西中斷的改變 +（這也可能會帶來很大的改進）。這種變化被稱爲「回歸」，回歸已經成爲主線內核 +最不受歡迎的問題。除了少數例外情況，如果回歸不能及時修正，會導致回歸的修改 +將被取消。最好首先避免回歸發生。 + +人們常常爭論，如果回歸帶來的功能遠超過產生的問題，那麼回歸是否爲可接受的。 +如果它破壞了一個系統卻爲十個系統帶來新的功能，爲何不改改態度呢？2007年7月， +Linus對這個問題給出了最佳答案: + +:: + + 所以我們不會通過引入新問題來修復錯誤。這種方式是靠不住的，沒人知道 + 是否真的有進展。是前進兩步、後退一步，還是前進一步、後退兩步？ + +（http://lwn.net/articles/243460/） + +特別不受歡迎的一種回歸類型是用戶空間ABI的任何變化。一旦接口被導出到用戶空間， +就必須無限期地支持它。這一事實使得用戶空間接口的創建特別具有挑戰性：因爲它們 +不能以不兼容的方式進行更改，所以必須一次就對。因此，用戶空間接口總是需要大量 +的思考、清晰的文檔和廣泛的審查。 + + +代碼檢查工具 +------------ + +至少目前，編寫無錯誤代碼仍然是我們中很少人能達到的理想狀態。不過，我們希望做 +的是，在代碼進入主線內核之前，儘可能多地捕獲並修復這些錯誤。爲此，內核開發人 +員已經提供了一系列令人印象深刻的工具，可以自動捕獲各種各樣的隱藏問題。計算機 +發現的任何問題都是一個以後不會困擾用戶的問題，因此，只要有可能，就應該使用 +自動化工具。 + +第一步是注意編譯器產生的警告。當前版本的GCC可以檢測（並警告）大量潛在錯誤。 +通常，這些警告都指向真正的問題。提交以供審閱的代碼一般不會產生任何編譯器警告。 +在消除警告時，注意了解真正的原因，並儘量避免僅「修復」使警告消失而不解決其原因。 + +請注意，並非所有編譯器警告都默認啓用。使用「make KCFLAGS=-W」構建內核以 +獲得完整集合。 + +內核提供了幾個配置選項，可以打開調試功能；大多數配置選項位於「kernel hacking」 +子菜單中。對於任何用於開發或測試目的的內核，都應該啓用其中幾個選項。特別是， +您應該打開： + + - FRAME_WARN 獲取大於給定數量的堆棧幀的警告。 + 這些警告生成的輸出可能比較冗長，但您不必擔心來自內核其他部分的警告。 + + - DEBUG_OBJECTS 將添加代碼以跟蹤內核創建的各種對象的生命周期，並在出現問題 + 時發出警告。如果你要添加創建（和導出）關於其自己的複雜對象的子系統，請 + 考慮打開對象調試基礎結構的支持。 + + - DEBUG_SLAB 可以發現各種內存分配和使用錯誤；它應該用於大多數開發內核。 + + - DEBUG_SPINLOCK, DEBUG_ATOMIC_SLEEP 和 DEBUG_MUTEXES 會發現許多常見的 + 鎖錯誤。 + +還有很多其他調試選項，其中一些將在下面討論。其中一些有顯著的性能影響，不應 +一直使用。在學習可用選項上花費一些時間，可能會在短期內得到許多回報。 + +其中一個較重的調試工具是鎖檢查器或「lockdep」。該工具將跟蹤系統中每個鎖 +（spinlock或mutex）的獲取和釋放、獲取鎖的相對順序、當前中斷環境等等。然後， +它可以確保總是以相同的順序獲取鎖，相同的中斷假設適用於所有情況等等。換句話 +說，lockdep可以找到許多導致系統死鎖的場景。在部署的系統中，這種問題可能會 +很痛苦（對於開發人員和用戶而言）；LockDep允許提前以自動方式發現問題。具有 +任何類型的非普通鎖的代碼在提交合併前應在啓用lockdep的情況下運行測試。 + +作爲一個勤奮的內核程式設計師，毫無疑問，您將檢查任何可能失敗的操作（如內存分配） +的返回狀態。然而，事實上，最終的故障復現路徑可能完全沒有經過測試。未測試的 +代碼往往會出問題；如果所有這些錯誤處理路徑都被執行了幾次，那麼您可能對代碼 +更有信心。 + +內核提供了一個可以做到這一點的錯誤注入框架，特別是在涉及內存分配的情況下。 +啓用故障注入後，內存分配的可配置失敗的百分比；這些失敗可以限定在特定的代碼 +範圍內。在啓用了故障注入的情況下運行，程式設計師可以看到當情況惡化時代碼如何響 +應。有關如何使用此工具的詳細信息，請參閱 +Documentation/fault-injection/fault-injection.rst。 + +「sparse」靜態分析工具可以發現其他類型的錯誤。sparse可以警告程式設計師用戶空間 +和內核空間地址之間的混淆、大端序與小端序的混淆、在需要一組位標誌的地方傳遞 +整數值等等。sparse必須單獨安裝(如果您的分發伺服器沒有將其打包， +可以在 https://sparse.wiki.kernel.org/index.php/Main_page 找到）, +然後可以通過在make命令中添加「C=1」在代碼上運行它。 + +「Coccinelle」工具 :ref:`http://coccinelle.lip6.fr/ <devtools_coccinelle>` +能夠發現各種潛在的編碼問題；它還可以爲這些問題提出修複方案。在 +scripts/coccinelle目錄下已經打包了相當多的內核「語義補丁」；運行 +「make coccicheck」將運行這些語義補丁並報告發現的任何問題。有關詳細信息，請參閱 +:ref:`Documentation/dev-tools/coccinelle.rst <devtools_coccinelle>` + + +其他類型的可移植性錯誤最好通過爲其他體系結構編譯代碼來發現。如果沒有S/390系統 +或Blackfin開發板，您仍然可以執行編譯步驟。可以在以下位置找到一大堆用於x86系統的 +交叉編譯器： + + https://www.kernel.org/pub/tools/crosstool/ + +花一些時間安裝和使用這些編譯器將有助於避免以後的尷尬。 + +文檔 +---- + +文檔通常比內核開發規則更爲例外。即便如此，足夠的文檔將有助於簡化將新代碼合併 +到內核中的過程，使其他開發人員的生活更輕鬆，並對您的用戶有所幫助。在許多情況 +下，添加文檔已基本上是強制性的。 + +任何補丁的第一個文檔是其關聯的變更日誌。日誌條目應該描述正在解決的問題、解決 +方案的形式、處理補丁的人員、對性能的任何相關影響，以及理解補丁可能需要的任何 +其他內容。確保變更日誌說明了*爲什麼*補丁值得應用；大量開發者未能提供這些信息。 + +任何添加新用戶空間接口的代碼——包括新的sysfs或/proc文件——都應該包含該接口 +的文檔，該文檔使用戶空間開發人員能夠知道他們在使用什麼。請參閱 +Documentation/ABI/README，了解如何此文檔格式以及需要提供哪些信息。 + +文檔 :ref:`Documentation/admin-guide/kernel-parameters.rst <kernelparameters>` +描述了內核的所有引導時間參數。任何添加新參數的補丁都應該向該文檔添加適當的 +條目。 + +任何新的配置選項都必須附有幫助文本，幫助文本需清楚地解釋這些選項以及用戶可能 +希望何時使用它們。 + +許多子系統的內部API信息通過專門格式化的注釋進行記錄；這些注釋可以通過 +「kernel-doc」腳本以多種方式提取和格式化。如果您在具有kerneldoc注釋的子系統中 +工作，則應該維護它們，並根據需要爲外部可用的功能添加它們。即使在沒有如此記錄 +的領域中，爲將來添加kerneldoc注釋也沒有壞處；實際上，這對於剛開始開發內核的人 +來說是一個有用的活動。這些注釋的格式以及如何創建kerneldoc模板的一些信息可以在 +:ref:`Documentation/doc-guide/ <doc_guide>` 上找到。 + +任何閱讀大量現有內核代碼的人都會注意到，注釋的缺失往往是最值得注意的。同時， +對新代碼的要求比過去更高；合併未注釋的代碼將更加困難。這就是說，人們並不期望 +詳細注釋的代碼。代碼本身應該是自解釋的，注釋闡釋了更微妙的方面。 + +某些事情應該總是被注釋。使用內存屏障時，應附上一行文字，解釋爲什麼需要設置內存 +屏障。數據結構的鎖規則通常需要在某個地方解釋。一般來說，主要數據結構需要全面 +的文檔。應該指出代碼中分立的位之間不明顯的依賴性。任何可能誘使代碼管理人進行 +錯誤的「清理」的事情都需要一個注釋來說明爲什麼要這樣做。等等。 + + +內部API更改 +----------- + +內核提供給用戶空間的二進位接口不能被破壞，除非逼不得已。而內核的內部編程接口 +是高度流動的，當需要時可以更改。如果你發現自己不得不處理一個內核API，或者僅 +僅因爲它不滿足你的需求導致無法使用特定的功能，這可能是API需要改變的一個標誌。 +作爲內核開發人員，您有權進行此類更改。 + +的確可以進行API更改，但更改必須是合理的。因此任何進行內部API更改的補丁都應該 +附帶關於更改內容和必要原因的描述。這種變化也應該拆分成一個單獨的補丁，而不是 +埋在一個更大的補丁中。 + +另一個要點是，更改內部API的開發人員通常要負責修復內核樹中被更改破壞的任何代碼。 +對於一個廣泛使用的函數，這個責任可以導致成百上千的變化，其中許多變化可能與其他 +開發人員正在做的工作相衝突。不用說，這可能是一項大工程，所以最好確保理由是 +可靠的。請注意，coccinelle工具可以幫助進行廣泛的API更改。 + +在進行不兼容的API更改時，應儘可能確保編譯器捕獲未更新的代碼。這將幫助您確保找 +到該接口的樹內用處。它還將警告開發人員樹外代碼存在他們需要響應的更改。支持樹外 +代碼不是內核開發人員需要擔心的事情，但是我們也不必使樹外開發人員的生活有不必要 +的困難。 + diff --git a/Documentation/translations/zh_TW/process/5.Posting.rst b/Documentation/translations/zh_TW/process/5.Posting.rst new file mode 100644 index 000000000000..5578bca403e6 --- /dev/null +++ b/Documentation/translations/zh_TW/process/5.Posting.rst @@ -0,0 +1,251 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. include:: ../disclaimer-zh_TW.rst + +:Original: :ref:`Documentation/process/5.Posting.rst <development_posting>` + +:Translator: + + 時奎亮 Alex Shi <alex.shi@linux.alibaba.com> + +:校譯: + + 吳想成 Wu XiangCheng <bobwxc@email.cn> + 胡皓文 Hu Haowen <src.res@email.cn> + +.. _tw_development_posting: + +發布補丁 +======== + +您的工作遲早會準備好提交給社區進行審查，並最終包含到主線內核中。毫不稀奇， +內核開發社區已經發展出一套用於發布補丁的約定和過程；遵循這些約定和過程將使 +參與其中的每個人的生活更加輕鬆。本文檔試圖描述這些約定的部分細節；更多信息 +也可在以下文檔中找到 +:ref:`Documentation/translations/zh_TW/process/submitting-patches.rst <tw_submittingpatches>`， +:ref:`Documentation/translations/zh_TW/process/submitting-drivers.rst <tw_submittingdrivers>` +和 :ref:`Documentation/translations/zh_TW/process/submit-checklist.rst <tw_submitchecklist>`。 + +何時郵寄 +-------- + +在補丁完全「準備好」之前，避免發布補丁是一種持續的誘惑。對於簡單的補丁，這 +不是問題。但是如果正在完成的工作很複雜，那麼在工作完成之前從社區獲得反饋就 +可以獲得很多好處。因此，您應該考慮發布正在進行的工作，甚至維護一個可用的Git +樹，以便感興趣的開發人員可以隨時趕上您的工作。 + +當發布中有尚未準備好被包含的代碼，最好在發布中說明。還應提及任何有待完成的 +主要工作和任何已知問題。很少有人會願意看那些被認爲是半生不熟的補丁，但是 +那些願意的人會帶著他們的點子來一起幫助你把工作推向正確的方向。 + +創建補丁之前 +------------ + +在考慮將補丁發送到開發社區之前，有許多事情應該做。包括： + + - 儘可能地測試代碼。利用內核的調試工具，確保內核使用了所有可能的配置選項組合 + 進行構建，使用交叉編譯器爲不同的體系結構進行構建等。 + + - 確保您的代碼符合內核代碼風格指南。 + + - 您的更改是否具有性能影響？如果是這樣，您應該運行基準測試來顯示您的變更的 + 影響（或好處）；結果的摘要應該包含在補丁中。 + + - 確保您有權發布代碼。如果這項工作是爲僱主完成的，僱主對這項工作具有所有權， + 並且必須同意根據GPL對其進行發布。 + +一般來說，在發布代碼之前進行一些額外的思考，幾乎總是能在短時間內得到回報。 + +補丁準備 +-------- + +準備補丁發布的工作量可能很驚人，但在此嘗試節省時間通常是不明智的，即使在短期 +內亦然。 + +必須針對內核的特定版本準備補丁。一般來說，補丁應該基於Linus的Git樹中的當前 +主線。當以主線爲基礎時，請從一個衆所周知的發布點開始——如穩定版本或 -rc +版本發布點——而不是在一個任意的主線分支點。 + +也可能需要針對-mm、linux-next或子系統樹生成版本，以便於更廣泛的測試和審查。 +根據補丁的區域以及其他地方的情況，針對其他樹建立的補丁可能需要大量的工作來 +解決衝突和處理API更改。 + +只有最簡單的更改才應格式化爲單個補丁；其他所有更改都應作爲一系列邏輯更改進行。 +分割補丁是一門藝術；一些開發人員花了很長時間來弄清楚如何按照社區期望的方式來 +分割。不過，這些經驗法則也許有幫助： + + - 您發布的補丁系列幾乎肯定不會是開發過程中版本控制系統中的一系列更改。相反， + 需要對您所做更改的最終形式加以考慮，然後以有意義的方式進行拆分。開發人員對 + 離散的、自包含的更改感興趣，而不是您創造這些更改的原始路徑。 + + - 每個邏輯上獨立的變更都應該格式化爲單獨的補丁。這些更改可以是小的（如「向 + 此結構體添加欄位」）或大的（如添加一個重要的新驅動程序），但它們在概念上 + 應該是小的，並且可以在一行內簡述。每個補丁都應該做一個特定的、可以單獨 + 檢查並驗證它所做的事情的更改。 + + - 換種方式重申上述準則，也就是說：不要在同一補丁中混合不同類型的更改。如果 + 一個補丁修復了一個關鍵的安全漏洞，又重新排列了一些結構，還重新格式化了代 + 碼，那麼它很有可能會被忽略，從而導致重要的修復丟失。 + + - 每個補丁都應該能創建一個可以正確地構建和運行的內核；如果補丁系列在中間被 + 斷開，那麼結果仍應是一個正常工作的內核。部分應用一系列補丁是使用 + 「git bisct」工具查找回歸的一個常見場景；如果結果是一個損壞的內核，那麼將使 + 那些從事追蹤問題的高尚工作的開發人員和用戶的生活更加艱難。 + + - 不要過分分割。一位開發人員曾經將一組針對單個文件的編輯分成500個單獨的補丁 + 發布，這並沒有使他成爲內核郵件列表中最受歡迎的人。一個補丁可以相當大， + 只要它仍然包含一個單一的 *邏輯* 變更。 + + - 用一系列補丁添加一個全新的基礎設施，但是該設施在系列中的最後一個補丁啓用 + 整個變更之前不能使用，這看起來很誘人。如果可能的話，應該避免這種誘惑； + 如果這個系列增加了回歸，那麼二分法將指出最後一個補丁是導致問題的補丁， + 即使真正的bug在其他地方。只要有可能，添加新代碼的補丁程序應該立即激活該 + 代碼。 + +創建完美補丁系列的工作可能是一個令人沮喪的過程，在完成「真正的工作」之後需要 +花費大量的時間和思考。但是如果做得好，花費的時間就是值得的。 + +補丁格式和更改日誌 +------------------ + +所以現在你有了一系列完美的補丁可以發布，但是這項工作還沒有完成。每個補丁都 +需要被格式化成一條消息，以快速而清晰地將其目的傳達到世界其他地方。爲此， +每個補丁將由以下部分組成： + + - 可選的「From」行，表明補丁作者。只有當你通過電子郵件發送別人的補丁時，這一行 + 才是必須的，但是爲防止疑問加上它也不會有什麼壞處。 + + - 一行描述，說明補丁的作用。對於在沒有其他上下文的情況下看到該消息的讀者來說， + 該消息應足以確定修補程序的範圍；此行將顯示在「short form（簡短格式）」變更 + 日誌中。此消息通常需要先加上子系統名稱前綴，然後是補丁的目的。例如： + + :: + + gpio: fix build on CONFIG_GPIO_SYSFS=n + + - 一行空白，後接補丁內容的詳細描述。此描述可以是任意需要的長度；它應該說明補丁 + 的作用以及爲什麼它應該應用於內核。 + + - 一個或多個標記行，至少有一個由補丁作者的 Signed-off-by 簽名。標記將在下面 + 詳細描述。 + +上面的項目一起構成補丁的變更日誌。寫一則好的變更日誌是一門至關重要但常常被 +忽視的藝術；值得花一點時間來討論這個問題。當你編寫變更日誌時，你應該記住有 +很多不同的人會讀你的話。其中包括子系統維護人員和審查人員，他們需要決定是否 +應該合併補丁，分銷商和其他維護人員試圖決定是否應該將補丁反向移植到其他內核， +缺陷搜尋人員想知道補丁是否導致他們正在追查的問題，以及想知道內核如何變化的 +用戶等等。一個好的變更日誌以最直接和最簡潔的方式向所有這些人傳達所需的信息。 + +在結尾，總結行應該描述變更的影響和動機，以及在一行約束條件下可能發生的變化。 +然後，詳細的描述可以詳述這些主題，並提供任何需要的附加信息。如果補丁修復了 +一個缺陷，請引用引入該缺陷的提交（如果可能，請在引用提交時同時提供其 id 和 +標題）。如果某個問題與特定的日誌或編譯器輸出相關聯，請包含該輸出以幫助其他 +人搜索同一問題的解決方案。如果更改是爲了支持以後補丁中的其他更改，那麼應當 +說明。如果更改了內部API，請詳細說明這些更改以及其他開發人員應該如何響應。 +一般來說，你越把自己放在每個閱讀你變更日誌的人的位置上，變更日誌（和內核 +作爲一個整體）就越好。 + +不消說，變更日誌是將變更提交到版本控制系統時使用的文本。接下來將是： + + - 補丁本身，採用統一的（「-u」）補丁格式。使用「-p」選項來diff將使函數名與 + 更改相關聯，從而使結果補丁更容易被其他人讀取。 + +您應該避免在補丁中包括與更改不相關文件（例如，構建過程生成的文件或編輯器 +備份文件）。文檔目錄中的「dontdiff」文件在這方面有幫助；使用「-X」選項將 +其傳遞給diff。 + +上面提到的標籤（tag）用於描述各種開發人員如何與這個補丁的開發相關聯。 +:ref:`Documentation/translations/zh_TW/process/submitting-patches.rst <tw_submittingpatches>` +文檔中對它們進行了詳細描述；下面是一個簡短的總結。每一行的格式如下： + +:: + + tag: Full Name <email address> optional-other-stuff + +常用的標籤有： + + - Signed-off-by: 這是一個開發人員的證明，證明他或她有權提交補丁以包含到內核 + 中。這表明同意開發者來源認證協議，其全文見 + :ref:`Documentation/translations/zh_TW/process/submitting-patches.rst <tw_submittingpatches>` + 如果沒有合適的簽字，則不能合併到主線中。 + + - Co-developed-by: 聲明補丁是由多個開發人員共同創建的；當幾個人在一個補丁上 + 工作時，它用於給出共同作者（除了 From: 所給出的作者之外）。由於 + Co-developed-by: 表示作者身份，所以每個共同開發人，必須緊跟在相關合作作者 + 的Signed-off-by之後。具體內容和示例見以下文件 + :ref:`Documentation/translations/zh_TW/process/submitting-patches.rst <tw_submittingpatches>` + + - Acked-by: 表示另一個開發人員（通常是相關代碼的維護人員）同意補丁適合包含 + 在內核中。 + + - Tested-by: 聲明某人已經測試了補丁並確認它可以工作。 + + - Reviewed-by: 表示某開發人員已經審查了補丁的正確性；有關詳細信息，請參閱 + :ref:`Documentation/translations/zh_TW/process/submitting-patches.rst <tw_submittingpatches>` + + - Reported-by: 指定報告此補丁修復的問題的用戶；此標記用於表示感謝。 + + - Cc：指定某人收到了補丁的副本，並有機會對此發表評論。 + +在補丁中添加標籤時要小心：只有Cc:才適合在沒有指定人員明確許可的情況下添加。 + +發送補丁 +-------- + +在寄出補丁之前，您還需要注意以下幾點： + + - 您確定您的郵件發送程序不會損壞補丁嗎？被郵件客戶端更改空白或修飾了行的補丁 + 無法被另一端接受，並且通常不會進行任何詳細檢查。如果有任何疑問，先把補丁寄 + 給你自己，讓你自己確定它是完好無損的。 + + :ref:`Documentation/translations/zh_TW/process/email-clients.rst <tw_email_clients>` + 提供了一些有用的提示，可以讓特定的郵件客戶端正常發送補丁。 + + - 你確定你的補丁沒有荒唐的錯誤嗎？您應該始終通過scripts/checkpatch.pl檢查 + 補丁程序，並解決它提出的問題。請記住，checkpatch.pl，雖然體現了對內核補丁 + 應該是什麼樣的大量思考，但它並不比您聰明。如果修復checkpatch.pl給的問題會 + 使代碼變得更糟，請不要這樣做。 + +補丁應始終以純文本形式發送。請不要將它們作爲附件發送；這使得審閱者在答覆中更難 +引用補丁的部分。相反，只需將補丁直接放到您的消息中。 + +寄出補丁時，重要的是將副本發送給任何可能感興趣的人。與其他一些項目不同，內核 +鼓勵人們甚至錯誤地發送過多的副本；不要假定相關人員會看到您在郵件列表中的發布。 +尤其是，副本應發送至： + + - 受影響子系統的維護人員。如前所述，維護人員文件是查找這些人員的首選地方。 + + - 其他在同一領域工作的開發人員，尤其是那些現在可能在那裡工作的開發人員。使用 + git查看還有誰修改了您正在處理的文件，這很有幫助。 + + - 如果您對某錯誤報告或功能請求做出響應，也可以抄送原始發送人。 + + - 將副本發送到相關郵件列表，或者若無相關列表，則發送到linux-kernel列表。 + + - 如果您正在修復一個缺陷，請考慮該修復是否應進入下一個穩定更新。如果是這樣， + 補丁副本也應發到stable@vger.kernel.org 。另外，在補丁本身的標籤中添加一個 + 「Cc: stable@vger.kernel.org」；這將使穩定版團隊在修復進入主線時收到通知。 + +當爲一個補丁選擇接收者時，最好清楚你認爲誰最終會接受這個補丁並將其合併。雖然 +可以將補丁直接發給Linus Torvalds並讓他合併，但通常情況下不會這樣做。Linus很 +忙，並且有子系統維護人員負責監視內核的特定部分。通常您會希望維護人員合併您的 +補丁。如果沒有明顯的維護人員，Andrew Morton通常是最後的補丁接收者。 + +補丁需要好的主題行。補丁主題行的規範格式如下： + +:: + + [PATCH nn/mm] subsys: one-line description of the patch + +其中「nn」是補丁的序號，「mm」是系列中補丁的總數，「subsys」是受影響子系統的 +名稱。當然，一個單獨的補丁可以省略nn/mm。 + +如果您有一系列重要的補丁，那麼通常發送一個簡介作爲第〇部分。不過，這個約定 +並沒有得到普遍遵循；如果您使用它，請記住簡介中的信息不會進入內核變更日誌。 +因此，請確保補丁本身具有完整的變更日誌信息。 + +一般來說，多部分補丁的第二部分和後續部分應作爲對第一部分的回覆發送，以便它們 +在接收端都連接在一起。像git和coilt這樣的工具有命令，可以通過適當的線程發送 +一組補丁。但是，如果您有一長串補丁，並正使用git，請不要使用–-chain-reply-to +選項，以避免創建過深的嵌套。 + diff --git a/Documentation/translations/zh_TW/process/6.Followthrough.rst b/Documentation/translations/zh_TW/process/6.Followthrough.rst new file mode 100644 index 000000000000..4af782742db3 --- /dev/null +++ b/Documentation/translations/zh_TW/process/6.Followthrough.rst @@ -0,0 +1,156 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. include:: ../disclaimer-zh_TW.rst + +:Original: :ref:`Documentation/process/6.Followthrough.rst <development_followthrough>` + +:Translator: + + 時奎亮 Alex Shi <alex.shi@linux.alibaba.com> + +:校譯: + + 吳想成 Wu XiangCheng <bobwxc@email.cn> + 胡皓文 Hu Haowen <src.res@email.cn> + +.. _tw_development_followthrough: + +跟進 +==== + +此時，您已經遵循了到目前爲止給出的指導方針，並且，隨著您自己的工程技能的增加， +已經發布了一系列完美的補丁。即使是經驗豐富的內核開發人員也能犯的最大錯誤之一 +是，認爲他們的工作現在已經完成了。事實上，發布補丁意味著進入流程的下一個階段， +可能還需要做很多工作。 + +一個補丁在首次發布時就非常出色、沒有改進的餘地，這是很罕見的。內核開發流程已 +認識到這一事實，因此它非常注重對已發布代碼的改進。作爲代碼的作者，您應該與 +內核社區合作，以確保您的代碼符合內核的質量標準。如果不參與這個過程，很可能會 +無法將補丁合併到主線中。 + +與審閱者合作 +------------ + +任何意義上的補丁都會導致其他開發人員在審查代碼時發表大量評論。對於許多開發 +人員來說，與審閱人員合作可能是內核開發過程中最令人生畏的部分。但是如果你 +記住一些事情，生活會變得容易得多： + + - 如果你已經很好地解釋了你的補丁，審閱人員會理解它的價值，以及爲什麼你會 + 費盡心思去寫它。但是這個並不能阻止他們提出一個基本的問題：在五年或十年後 + 維護含有此代碼的內核會怎麼樣？你可能被要求做出的許多改變——從編碼風格的 + 調整到大量的重寫——都來自於對Linux的理解，即從現在起十年後，Linux仍將 + 在開發中。 + + - 代碼審查是一項艱苦的工作，這是一項相對吃力不討好的工作；人們記得誰編寫了 + 內核代碼，但對於那些審查它的人來說，幾乎沒有什麼長久的名聲。因此，審閱 + 人員可能會變得暴躁，尤其是當他們看到同樣的錯誤被一遍又一遍地犯下時。如果 + 你得到了一個看起來憤怒、侮辱或完全冒犯你的評論，請抑制以同樣方式回應的衝動。 + 代碼審查是關於代碼的，而不是關於人的，代碼審閱人員不會親自攻擊您。 + + - 同樣，代碼審閱人員也不想以犧牲你僱主的利益爲代價來宣傳他們僱主的議程。 + 內核開發人員通常希望今後幾年能在內核上工作，但他們明白他們的僱主可能會改 + 變。他們真的，幾乎毫無例外地，致力於創造他們所能做到的最好的內核；他們並 + 沒有試圖給僱主的競爭對手造成不適。 + +所有這些歸根結底就是，當審閱者向您發送評論時，您需要注意他們正在進行的技術 +評論。不要讓他們的表達方式或你自己的驕傲阻止此事。當你在一個補丁上得到評論 +時，花點時間去理解評論人想說什麼。如果可能的話，請修覆審閱者要求您修復的內 +容。然後回覆審閱者：謝謝他們，並描述你將如何回答他們的問題。 + +請注意，您不必同意審閱者建議的每個更改。如果您認爲審閱者誤解了您的代碼，請 +解釋到底發生了什麼。如果您對建議的更改有技術上的異議，請描述它並證明您對該 +問題的解決方案是正確的。如果你的解釋有道理，審閱者會接受的。不過，如果你的 +解釋證明缺乏說服力，尤其是當其他人開始同意審稿人的觀點時，請花些時間重新考慮 +一下。你很容易對自己解決問題的方法視而不見，以至於你沒有意識到某些東西完全 +是錯誤的，或者你甚至沒有解決正確的問題。 + +Andrew Morton建議，每一個不會導致代碼更改的審閱評論都應該產生一個額外的代碼 +注釋；這可以幫助未來的審閱人員避免第一次出現的問題。 + +一個致命的錯誤是忽視評論，希望它們會消失。它們不會走的。如果您在沒有對之前 +收到的評論做出響應的情況下重新發布代碼，那麼很可能會發現補丁毫無用處。 + +說到重新發布代碼：請記住，審閱者不會記住您上次發布的代碼的所有細節。因此， +提醒審閱人員以前提出的問題以及您如何處理這些問題總是一個好主意；補丁變更 +日誌是提供此類信息的好地方。審閱者不必搜索列表檔案來熟悉上次所說的內容； +如果您幫助他們直接開始，當他們重新查看您的代碼時，心情會更好。 + +如果你已經試著做正確的事情，但事情仍然沒有進展呢？大多數技術上的分歧都可以 +通過討論來解決，但有時人們仍需要做出決定。如果你真的認爲這個決定對你不利， +你可以試著向有更高權力的人上訴。對於本文，更高權力的人是 Andrew Morton 。 +Andrew 在內核開發社區中非常受尊敬；他經常爲似乎被絕望阻塞的事情清障。儘管 +如此，不應輕易就直接找 Andrew ，也不應在所有其他替代方案都被嘗試之前找他。 +當然，記住，他也可能不同意你的意見。 + +接下來會發生什麼 +---------------- + +如果一個補丁被認爲適合添加到內核中，並且大多數審查問題得到解決，下一步通常 +是進入子系統維護人員的樹中。工作方式因子系統而異；每個維護人員都有自己的 +工作方式。特別是可能有不止一棵樹——也許一棵樹專門用於計劃下一個合併窗口的 +補丁，另一棵樹用於長期工作。 + +對於應用到不屬於明顯子系統樹（例如內存管理修補程序）的區域的修補程序，默認樹 +通常上溯到-mm。影響多個子系統的補丁也可以最終進入-mm樹。 + +包含在子系統樹中可以提高補丁的可見性。現在，使用該樹的其他開發人員將默認獲 +得補丁。子系統樹通常也爲Linux提供支持，使其內容對整個開發社區可見。在這一點 +上，您很可能會從一組新的審閱者那裡得到更多的評論；這些評論需要像上一輪那樣 +得到回應。 + +在這時也會發生點什麼，這取決於你的補丁的性質，是否與其他人正在做的工作發生 +衝突。在最壞的情況下，嚴重的補丁衝突可能會導致一些工作被擱置，以便剩餘的補丁 +可以成形併合並。另一些時候，衝突解決將涉及到與其他開發人員合作，可能還會 +在樹之間移動一些補丁，以確保所有的應用都是乾淨的。這項工作可能是一件痛苦的 +事情，但也需慶幸現在的幸福：在linux-next樹出現之前，這些衝突通常只在合併窗口 +中出現，必須迅速解決。現在可以在合併窗口打開之前的空閒時間解決這些問題。 + +有朝一日，如果一切順利，您將登錄並看到您的補丁已經合併到主線內核中。祝賀你！ +然而，一旦慶祝完了（並且您已經將自己添加到維護人員文件中），就一定要記住 +一個重要的小事實：工作仍然沒有完成。併入主線也帶來了它的挑戰。 + +首先，補丁的可見性再次提高。可能會有以前不知道這個補丁的開發者的新一輪評論。 +忽略它們可能很有誘惑力，因爲您的代碼不再存在任何被合併的問題。但是，要抵制 +這種誘惑，您仍然需要對有問題或建議的開發人員作出響應。 + +不過，更重要的是：將代碼包含在主線中會將代碼交給更多的一些測試人員。即使您 +爲尚未可用的硬體提供了驅動程序，您也會驚訝於有多少人會將您的代碼構建到內核 +中。當然，如果有測試人員，也可能會有錯誤報告。 + +最糟糕的錯誤報告是回歸。如果你的補丁導致回歸，你會發現多到讓你不舒服的眼睛盯 +著你；回歸需要儘快修復。如果您不願意或無法修復回歸（其他人都不會爲您修復）， +那麼在穩定期內，您的補丁幾乎肯定會被移除。除了否定您爲使補丁進入主線所做的 +所有工作之外，如果由於未能修復回歸而取消補丁，很可能會使將來的工作更難被合併。 + +在處理完任何回歸之後，可能還有其他普通缺陷需要處理。穩定期是修復這些錯誤並 +確保代碼在主線內核版本中的首次發布儘可能可靠的最好機會。所以，請回應錯誤 +報告，並儘可能解決問題。這就是穩定期的目的；一旦解決了舊補丁的任何問題，就 +可以開始盡情創建新補丁。 + +別忘了，還有其他節點也可能會創建缺陷報告：下一個主線穩定版本，當著名的發行 +商選擇包含您補丁的內核版本時等等。繼續響應這些報告是您工作的基本素養。但是 +如果這不能提供足夠的動機，那麼也需要考慮：開發社區會記住那些在合併後對代碼 +失去興趣的開發人員。下一次你發布補丁時，他們會以你以後不會持續維護它爲前提 +來評估它。 + +其他可能發生的事情 +------------------ + +某天，當你打開你的郵件客戶端時，看到有人給你寄了一個代碼補丁。畢竟，這是 +讓您的代碼公開存在的好處之一。如果您同意這個補丁，您可以將它轉發給子系統 +維護人員（確保包含一個正確的From:行，這樣屬性是正確的，並添加一個您自己的 +signoff ），或者回復一個 Acked-by: 讓原始發送者向上發送它。 + +如果您不同意補丁，請禮貌地回復，解釋原因。如果可能的話，告訴作者需要做哪些 +更改才能讓您接受補丁。合併代碼的編寫者和維護者所反對的補丁的確存在著一定的 +阻力，但僅此而已。如果你被認爲不必要的阻礙了好的工作，那麼這些補丁最終會 +繞過你並進入主線。在Linux內核中，沒有人對任何代碼擁有絕對的否決權。可能除 +了Linus。 + +在非常罕見的情況下，您可能會看到完全不同的東西：另一個開發人員發布了針對您 +的問題的不同解決方案。在這時，兩個補丁之一可能不會被合併，「我的補丁首先 +發布」不被認爲是一個令人信服的技術論據。如果有別人的補丁取代了你的補丁而進 +入了主線，那麼只有一種方法可以回應你：很高興你的問題解決了，請繼續工作吧。 +以這種方式把某人的工作推到一邊可能導致傷心和氣餒，但是社區會記住你的反應， +即使很久以後他們已經忘記了誰的補丁真正被合併。 + diff --git a/Documentation/translations/zh_TW/process/7.AdvancedTopics.rst b/Documentation/translations/zh_TW/process/7.AdvancedTopics.rst new file mode 100644 index 000000000000..3de093d0f170 --- /dev/null +++ b/Documentation/translations/zh_TW/process/7.AdvancedTopics.rst @@ -0,0 +1,137 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. include:: ../disclaimer-zh_TW.rst + +:Original: :ref:`Documentation/process/7.AdvancedTopics.rst <development_advancedtopics>` + +:Translator: + + 時奎亮 Alex Shi <alex.shi@linux.alibaba.com> + +:校譯: + + 吳想成 Wu XiangCheng <bobwxc@email.cn> + 胡皓文 Hu Haowen <src.res@email.cn> + +.. _tw_development_advancedtopics: + +高級主題 +======== + +現在，希望您能夠掌握開發流程的工作方式。然而，還有更多的東西要學！本節將介紹 +一些主題，這些主題對希望成爲Linux內核開發過程常規部分的開發人員有幫助。 + +使用Git管理補丁 +--------------- + +內核使用分布式版本控制始於2002年初，當時Linus首次開始使用專有的Bitkeeper應用 +程序。雖然BitKeeper存在爭議，但它所體現的軟體版本管理方法卻肯定不是。分布式 +版本控制可以立即加速內核開發項目。現在有好幾種免費的BitKeeper替代品。 +但無論好壞，內核項目都已經選擇了Git作爲其工具。 + +使用Git管理補丁可以使開發人員的生活更加輕鬆，尤其是隨著補丁數量的增長。Git也 +有其粗糙的邊角和一定的危險性，它是一個年輕和強大的工具，仍然在其開發人員完善 +中。本文檔不會試圖教會讀者如何使用git；這會是個巨長的文檔。相反，這裡的重點 +將是Git如何特別適合內核開發過程。想要加快用Git速度的開發人員可以在以下網站上 +找到更多信息： + + https://git-scm.com/ + + https://www.kernel.org/pub/software/scm/git/docs/user-manual.html + +同時網上也能找到各種各樣的教程。 + +在嘗試使用它生成補丁供他人使用之前，第一要務是閱讀上述網頁，對Git的工作方式 +有一個紮實的了解。使用Git的開發人員應能進行拉取主線存儲庫的副本，查詢修訂 +歷史，提交對樹的更改，使用分支等操作。了解Git用於重寫歷史的工具（如rebase） +也很有用。Git有自己的術語和概念；Git的新用戶應該了解引用、遠程分支、索引、 +快進合併、推拉、游離頭等。一開始可能有點嚇人，但這些概念不難通過一點學習來 +理解。 + +使用git生成通過電子郵件提交的補丁是提高速度的一個很好的練習。 + +當您準備好開始建立Git樹供其他人查看時，無疑需要一個可以從中拉取的伺服器。 +如果您有一個可以訪問網際網路的系統，那麼使用git-daemon設置這樣的伺服器相對 +簡單。同時，免費的公共託管網站（例如github）也開始出現在網絡上。成熟的開發 +人員可以在kernel.org上獲得一個帳戶，但這些帳戶並不容易得到；更多有關信息， +請參閱 https://kernel.org/faq/ 。 + +正常的Git工作流程涉及到許多分支的使用。每一條開發線都可以分爲單獨的「主題 +分支」，並獨立維護。Git的分支很容易使用，沒有理由不使用它們。而且，在任何 +情況下，您都不應該在任何您打算讓其他人從中拉取的分支中進行開發。應該小心地 +創建公開可用的分支；當開發分支處於完整狀態並已準備好時(而不是之前）才合併 +開發分支的補丁。 + +Git提供了一些強大的工具，可以讓您重寫開發歷史。一個不方便的補丁（比如說， +一個打破二分法的補丁，或者有其他一些明顯的缺陷）可以在適當的位置修復，或者 +完全從歷史中消失。一個補丁系列可以被重寫，就好像它是在今天的主線上寫的一樣， +即使你已經花了幾個月的時間在寫它。可以透明地將更改從一個分支轉移到另一個 +分支。等等。明智地使用git修改歷史的能力可以幫助創建問題更少的乾淨補丁集。 + +然而，過度使用這種功能可能會導致其他問題，而不僅僅是對創建完美項目歷史的 +簡單癡迷。重寫歷史將重寫該歷史中包含的更改，將經過測試（希望如此）的內核樹 +變爲未經測試的內核樹。除此之外，如果開發人員沒有共享項目歷史，他們就無法 +輕鬆地協作；如果您重寫了其他開發人員拉入他們存儲庫的歷史，您將使這些開發 +人員的生活更加困難。因此，這裡有一個簡單的經驗法則：被導出到其他地方的歷史 +在此後通常被認爲是不可變的。 + +因此，一旦將一組更改推送到公開可用的伺服器上，就不應該重寫這些更改。如果您 +嘗試強制進行無法快進合併的更改（即不共享同一歷史記錄的更改），Git將嘗試強制 +執行此規則。這可能覆蓋檢查，有時甚至需要重寫導出的樹。在樹之間移動變更集以 +避免linux-next中的衝突就是一個例子。但這種行爲應該是罕見的。這就是爲什麼 +開發應該在私有分支中進行（必要時可以重寫）並且只有在公共分支處於合理的較新 +狀態時才轉移到公共分支中的原因之一。 + +當主線（或其他一組變更所基於的樹）前進時，很容易與該樹合併以保持領先地位。 +對於一個私有的分支，rebasing 可能是一個很容易跟上另一棵樹的方法，但是一旦 +一棵樹被導出到外界，rebasing就不可取了。一旦發生這種情況，就必須進行完全 +合併（merge）。合併有時是很有意義的，但是過於頻繁的合併會不必要地擾亂歷史。 +在這種情況下建議的做法是不要頻繁合併，通常只在特定的發布點（如主線-rc發布） +合併。如果您對特定的更改感到緊張，則可以始終在私有分支中執行測試合併。在 +這種情況下，git「rerere」工具很有用；它能記住合併衝突是如何解決的，這樣您 +就不必重複相同的工作。 + +關於Git這樣的工具的一個最大的反覆抱怨是：補丁從一個存儲庫到另一個存儲庫的 +大量移動使得很容易陷入錯誤建議的變更中，這些變更避開審查雷達進入主線。當內 +核開發人員看到這種情況發生時，他們往往會感到不高興；在Git樹上放置未審閱或 +主題外的補丁可能會影響您將來讓樹被拉取的能力。引用Linus的話: + +:: + + 你可以給我發補丁，但當我從你那裡拉取一個Git補丁時，我需要知道你清楚 + 自己在做什麼，我需要能夠相信事情而 *無需* 手動檢查每個單獨的更改。 + +（http://lwn.net/articles/224135/）。 + +爲了避免這種情況，請確保給定分支中的所有補丁都與相關主題緊密相關；「驅動程序 +修復」分支不應更改核心內存管理代碼。而且，最重要的是，不要使用Git樹來繞過 +審查過程。不時的將樹的摘要發布到相關的列表中，在合適時候請求linux-next中 +包含該樹。 + +如果其他人開始發送補丁以包含到您的樹中，不要忘記審閱它們。還要確保您維護正確 +的作者信息； git 「am」工具在這方面做得最好，但是如果補丁通過第三方轉發給您， +您可能需要在補丁中添加「From:」行。 + +請求拉取時，請務必提供所有相關信息：樹的位置、要拉取的分支以及拉取將導致的 +更改。在這方面 git request-pull 命令非常有用；它將按照其他開發人員所期望的 +格式化請求，並檢查以確保您已記得將這些更改推送到公共伺服器。 + +審閱補丁 +-------- + +一些讀者顯然會反對將本節與「高級主題」放在一起，因爲即使是剛開始的內核開發人員 +也應該審閱補丁。當然，沒有比查看其他人發布的代碼更好的方法來學習如何在內核環境 +中編程了。此外，審閱者永遠供不應求；通過審閱代碼，您可以對整個流程做出重大貢獻。 + +審查代碼可能是一副令人生畏的圖景，特別是對一個新的內核開發人員來說，他們 +可能會對公開詢問代碼感到緊張，而這些代碼是由那些有更多經驗的人發布的。不過， +即使是最有經驗的開發人員編寫的代碼也可以得到改進。也許對（所有）審閱者最好 +的建議是：把審閱評論當成問題而不是批評。詢問「在這條路徑中如何釋放鎖？」 +總是比說「這裡的鎖是錯誤的」更好。 + +不同的開發人員將從不同的角度審查代碼。部分人會主要關注代碼風格以及代碼行是 +否有尾隨空格。其他人會主要關注補丁作爲一個整體實現的變更是否對內核有好處。 +同時也有人會檢查是否存在鎖問題、堆棧使用過度、可能的安全問題、在其他地方 +發現的代碼重複、足夠的文檔、對性能的不利影響、用戶空間ABI更改等。所有類型 +的檢查，只要它們能引導更好的代碼進入內核，都是受歡迎和值得的。 + diff --git a/Documentation/translations/zh_TW/process/8.Conclusion.rst b/Documentation/translations/zh_TW/process/8.Conclusion.rst new file mode 100644 index 000000000000..7572b17667d9 --- /dev/null +++ b/Documentation/translations/zh_TW/process/8.Conclusion.rst @@ -0,0 +1,74 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. include:: ../disclaimer-zh_TW.rst + +:Original: :ref:`Documentation/process/8.Conclusion.rst <development_conclusion>` +:Translator: + + 時奎亮 Alex Shi <alex.shi@linux.alibaba.com> + +:校譯: + + 吳想成 Wu XiangCheng <bobwxc@email.cn> + 胡皓文 Hu Haowen <src.res@email.cn> + +.. _tw_development_conclusion: + +更多信息 +======== + +關於Linux內核開發和相關主題的信息來源很多。首先是在內核原始碼分發中找到的 +文檔目錄。頂級 +:ref:`Documentation/translations/zh_TW/process/howto.rst <tw_process_howto>` +文件是一個重要的起點； +:ref:`Documentation/translations/zh_TW/process/submitting-patches.rst <tw_submittingpatches>` +和 :ref:`Documentation/translations/zh_TW/process/submitting-drivers.rst <tw_submittingdrivers>` +也是所有內核開發人員都應該閱讀的內容。許多內部內核API都是使用kerneldoc機制 +記錄的；「make htmldocs」或「make pdfdocs」可用於以HTML或PDF格式生成這些文檔 +（儘管某些發行版提供的tex版本會遇到內部限制，無法正確處理文檔）。 + +不同的網站在各個細節層次上討論內核開發。本文作者想謙虛地建議用 https://lwn.net/ +作爲來源；有關許多特定內核主題的信息可以通過以下網址的 LWN 內核索引找到： + + http://lwn.net/kernel/index/ + +除此之外，內核開發人員的一個寶貴資源是： + + https://kernelnewbies.org/ + +當然，也不應該忘記 https://kernel.org/ ，這是內核發布信息的最終位置。 + +關於內核開發有很多書： + + 《Linux設備驅動程序》第三版（Jonathan Corbet、Alessandro Rubini和Greg Kroah Hartman） + 線上版本在 http://lwn.net/kernel/ldd3/ + + 《Linux內核設計與實現》（Robert Love） + + 《深入理解Linux內核》(Daniel Bovet和Marco Cesati） + +然而，所有這些書都有一個共同的缺點：它們上架時就往往有些過時，而且已經上架 +一段時間了。不過，在那裡還是可以找到相當多的好信息。 + +有關git的文檔，請訪問： + + https://www.kernel.org/pub/software/scm/git/docs/ + + https://www.kernel.org/pub/software/scm/git/docs/user-manual.html + +結論 +==== + +祝賀所有通過這篇冗長的文檔的人。希望它能夠幫助您理解Linux內核是如何開發的， +以及您如何參與這個過程。 + +最後，重要的是參與。任何開源軟體項目都不會超過其貢獻者投入其中的總和。Linux +內核的發展速度和以前一樣快，因爲它得到了大量開發人員的幫助，他們都在努力使它 +變得更好。內核是一個最成功的例子，說明了當成千上萬的人爲了一個共同的目標一起 +工作時，可以做出什麼。 + +不過，內核總是可以從更大的開發人員基礎中獲益。總有更多的工作要做。但是同樣 +重要的是，Linux生態系統中的大多數其他參與者可以通過爲內核做出貢獻而受益。使 +代碼進入主線是提高代碼質量、降低維護和分發成本、提高對內核開發方向的影響程度 +等的關鍵。這是一種共贏的局面。啓動你的編輯器，來加入我們吧；你會非常受歡迎的。 + diff --git a/Documentation/translations/zh_TW/process/code-of-conduct-interpretation.rst b/Documentation/translations/zh_TW/process/code-of-conduct-interpretation.rst new file mode 100644 index 000000000000..949d831aaf6c --- /dev/null +++ b/Documentation/translations/zh_TW/process/code-of-conduct-interpretation.rst @@ -0,0 +1,112 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. include:: ../disclaimer-zh_TW.rst + +:Original: :ref:`Documentation/process/code-of-conduct-interpretation.rst <code_of_conduct_interpretation>` +:Translator: Alex Shi <alex.shi@linux.alibaba.com> + Hu Haowen <src.res@email.cn> + +.. _tw_code_of_conduct_interpretation: + +Linux內核貢獻者契約行為準則解釋 +=============================== + +:ref:`tw_code_of_conduct` 準則是一個通用文檔，旨在爲幾乎所有開源社區提供一套規則。 +每個開源社區都是獨一無二的，Linux內核也不例外。因此，本文描述了Linux內核社區中 +如何解釋它。我們也不希望這種解釋隨著時間的推移是靜態的，並將根據需要進行調整。 + +與開發軟體的「傳統」方法相比，Linux內核開發工作是一個非常個人化的過程。你的貢獻 +和背後的想法將被仔細審查，往往導致批判和批評。審查將幾乎總是需要改進，材料才 +能包括在內核中。要知道這是因爲所有相關人員都希望看到Linux整體成功的最佳解決方 +案。這個開發過程已經被證明可以創建有史以來最健壯的作業系統內核，我們不想做任何 +事情來導致提交質量和最終結果的下降。 + +維護者 +------ + +行為準則多次使用「維護者」一詞。在內核社區中，「維護者」是負責子系統、驅動程序或 +文件的任何人，並在內核原始碼樹的維護者文件中列出。 + +責任 +---- + +《行為準則》提到了維護人員的權利和責任，這需要進一步澄清。 + +首先，最重要的是，有一個合理的期望是由維護人員通過實例來領導。 + +也就是說，我們的社區是廣闊的，對維護者沒有新的要求，他們單方面處理其他人在 +他們活躍的社區的行爲。這一責任由我們所有人承擔，最終《行為準則》記錄了最終的 +上訴路徑，以防有關行爲問題的問題懸而未決。 + +維護人員應該願意在出現問題時提供幫助，並在需要時與社區中的其他人合作。如果您 +不確定如何處理出現的情況，請不要害怕聯繫技術諮詢委員會（TAB）或其他維護人員。 +除非您願意，否則不會將其視爲違規報告。如果您不確定是否該聯繫TAB 或任何其他維 +護人員，請聯繫我們的衝突調解人 Mishi Choudhary <mishi@linux.com>。 + +最後，「善待對方」才是每個人的最終目標。我們知道每個人都是人，有時我們都會失敗， +但我們所有人的首要目標應該是努力友好地解決問題。執行行為準則將是最後的選擇。 + +我們的目標是創建一個強大的、技術先進的作業系統，以及所涉及的技術複雜性，這自 +然需要專業知識和決策。 + +所需的專業知識因貢獻領域而異。它主要由上下文和技術複雜性決定，其次由貢獻者和 +維護者的期望決定。 + +專家的期望和決策都要經過討論，但在最後，爲了取得進展，必須能夠做出決策。這一 +特權掌握在維護人員和項目領導的手中，預計將善意使用。 + +因此，設定專業知識期望、作出決定和拒絕不適當的貢獻不被視爲違反行為準則。 + +雖然維護人員一般都歡迎新來者，但他們幫助（新）貢獻者克服障礙的能力有限，因此 +他們必須確定優先事項。這也不應被視爲違反了行為準則。內核社區意識到這一點，並 +以各種形式提供入門級節目，如 kernelnewbies.org 。 + +範圍 +---- + +Linux內核社區主要在一組公共電子郵件列表上進行交互，這些列表分布在由多個不同 +公司或個人控制的多個不同伺服器上。所有這些列表都在內核原始碼樹中的 +MAINTAINERS 文件中定義。發送到這些郵件列表的任何電子郵件都被視爲包含在行爲 +準則中。 + +使用 kernel.org bugzilla和其他子系統bugzilla 或bug跟蹤工具的開發人員應該遵循 +行為準則的指導原則。Linux內核社區沒有「官方」項目電子郵件地址或「官方」社交媒體 +地址。使用kernel.org電子郵件帳戶執行的任何活動必須遵循爲kernel.org發布的行爲 +準則，就像任何使用公司電子郵件帳戶的個人必須遵循該公司的特定規則一樣。 + +行為準則並不禁止在郵件列表消息、內核更改日誌消息或代碼注釋中繼續包含名稱、 +電子郵件地址和相關注釋。 + +其他論壇中的互動包括在適用於上述論壇的任何規則中，通常不包括在行為準則中。 +除了在極端情況下可考慮的例外情況。 + +提交給內核的貢獻應該使用適當的語言。在行為準則之前已經存在的內容現在不會被 +視爲違反。然而，不適當的語言可以被視爲一個bug；如果任何相關方提交補丁， +這樣的bug將被更快地修復。當前屬於用戶/內核API的一部分的表達式，或者反映已 +發布標準或規範中使用的術語的表達式，不被視爲bug。 + +執行 +---- + +行為準則中列出的地址屬於行為準則委員會。https://kernel.org/code-of-conduct.html +列出了在任何給定時間接收這些電子郵件的確切成員。成員不能訪問在加入委員會之前 +或離開委員會之後所做的報告。 + +最初的行為準則委員會由TAB的志願者以及作爲中立第三方的專業調解人組成。委員會 +的首要任務是建立文件化的流程，並將其公開。 + +如果報告人不希望將整個委員會納入投訴或關切，可直接聯繫委員會的任何成員，包括 +調解人。 + +行為準則委員會根據流程審查案例（見上文），並根據需要和適當與TAB協商，例如請求 +和接收有關內核社區的信息。 + +委員會做出的任何決定都將提交到表中，以便在必要時與相關維護人員一起執行。行爲 +準則委員會的決定可以通過三分之二的投票推翻。 + +每季度，行為準則委員會和標籤將提供一份報告，概述行為準則委員會收到的匿名報告 +及其狀態，以及任何否決決定的細節，包括完整和可識別的投票細節。 + +我們希望在啓動期之後爲行為準則委員會人員配備建立一個不同的流程。發生此情況時， +將使用該信息更新此文檔。 + diff --git a/Documentation/translations/zh_TW/process/code-of-conduct.rst b/Documentation/translations/zh_TW/process/code-of-conduct.rst new file mode 100644 index 000000000000..716e5843b6e9 --- /dev/null +++ b/Documentation/translations/zh_TW/process/code-of-conduct.rst @@ -0,0 +1,76 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. include:: ../disclaimer-zh_TW.rst + +:Original: :ref:`Documentation/process/code-of-conduct.rst <code_of_conduct>` +:Translator: Alex Shi <alex.shi@linux.alibaba.com> + Hu Haowen <src.res@email.cn> + +.. _tw_code_of_conduct: + +貢獻者契約行為準則 +++++++++++++++++++ + +我們的誓言 +========== + +爲了營造一個開放、友好的環境，我們作爲貢獻者和維護人承諾，讓我們的社區和參 +與者，擁有一個無騷擾的體驗，無論年齡、體型、殘疾、種族、性別特徵、性別認同 +和表達、經驗水平、教育程度、社會狀況，經濟地位、國籍、個人外貌、種族、宗教 +或性身份和取向。 + +我們的標準 +========== + +有助於創造積極環境的行爲包括： + +* 使用歡迎和包容的語言 +* 尊重不同的觀點和經驗 +* 優雅地接受建設性的批評 +* 關注什麼對社區最有利 +* 對其他社區成員表示同情 + +參與者的不可接受行爲包括： + +* 使用性意味的語言或意象以及不受歡迎的性注意或者更過分的行爲 +* 煽動、侮辱/貶損評論以及個人或政治攻擊 +* 公開或私下騷擾 +* 未經明確許可，發布他人的私人信息，如物理或電子地址。 +* 在專業場合被合理認爲不適當的其他行爲 + +我們的責任 +========== + +維護人員負責澄清可接受行爲的標準，並應針對任何不可接受行爲採取適當和公平的 +糾正措施。 + +維護人員有權和責任刪除、編輯或拒絕與本行為準則不一致的評論、承諾、代碼、 +wiki編輯、問題和其他貢獻，或暫時或永久禁止任何貢獻者從事他們認爲不適當、 +威脅、冒犯或有害的其他行爲。 + +範圍 +==== + +當個人代表項目或其社區時，本行為準則既適用於項目空間，也適用於公共空間。 +代表一個項目或社區的例子包括使用一個正式的項目電子郵件地址，通過一個正式 +的社交媒體帳戶發布，或者在在線或離線事件中擔任指定的代表。項目維護人員可以 +進一步定義和澄清項目的表示。 + +執行 +==== + +如有濫用、騷擾或其他不可接受的行爲，可聯繫行為準則委員會<conduct@kernel.org>。 +所有投訴都將接受審查和調查，並將得到必要和適當的答覆。行為準則委員會有義務 +對事件報告人保密。具體執行政策的進一步細節可單獨公布。 + +歸屬 +==== + +本行為準則改編自《貢獻者契約》，版本1.4，可從 +https://www.contributor-covenant.org/version/1/4/code-of-conduct.html 獲取。 + +解釋 +==== + +有關Linux內核社區如何解釋此文檔，請參閱 :ref:`tw_code_of_conduct_interpretation` + diff --git a/Documentation/translations/zh_TW/process/coding-style.rst b/Documentation/translations/zh_TW/process/coding-style.rst new file mode 100644 index 000000000000..61e614aad6a7 --- /dev/null +++ b/Documentation/translations/zh_TW/process/coding-style.rst @@ -0,0 +1,958 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. include:: ../disclaimer-zh_TW.rst + +:Original: :ref:`Documentation/process/coding-style.rst <codingstyle>` + +.. _tw_codingstyle: + +譯者:: + + 中文版維護者： 張樂 Zhang Le <r0bertz@gentoo.org> + 中文版翻譯者： 張樂 Zhang Le <r0bertz@gentoo.org> + 中文版校譯者： 王聰 Wang Cong <xiyou.wangcong@gmail.com> + wheelz <kernel.zeng@gmail.com> + 管旭東 Xudong Guan <xudong.guan@gmail.com> + Li Zefan <lizf@cn.fujitsu.com> + Wang Chen <wangchen@cn.fujitsu.com> + Hu Haowen <src.res@email.cn> + +Linux 內核代碼風格 +========================= + +這是一個簡短的文檔，描述了 linux 內核的首選代碼風格。代碼風格是因人而異的， +而且我不願意把自己的觀點強加給任何人，但這就像我去做任何事情都必須遵循的原則 +那樣，我也希望在絕大多數事上保持這種的態度。請 (在寫代碼時) 至少考慮一下這裡 +的代碼風格。 + +首先，我建議你列印一份 GNU 代碼規範，然後不要讀。燒了它，這是一個具有重大象徵 +性意義的動作。 + +不管怎樣，現在我們開始： + + +1) 縮進 +-------------- + +制表符是 8 個字符，所以縮進也是 8 個字符。有些異端運動試圖將縮進變爲 4 (甚至 +2！) 字符深，這幾乎相當於嘗試將圓周率的值定義爲 3。 + +理由：縮進的全部意義就在於清楚的定義一個控制塊起止於何處。尤其是當你盯著你的 +屏幕連續看了 20 小時之後，你將會發現大一點的縮進會使你更容易分辨縮進。 + +現在，有些人會抱怨 8 個字符的縮進會使代碼向右邊移動的太遠，在 80 個字符的終端 +屏幕上就很難讀這樣的代碼。這個問題的答案是，如果你需要 3 級以上的縮進，不管用 +何種方式你的代碼已經有問題了，應該修正你的程序。 + +簡而言之，8 個字符的縮進可以讓代碼更容易閱讀，還有一個好處是當你的函數嵌套太 +深的時候可以給你警告。留心這個警告。 + +在 switch 語句中消除多級縮進的首選的方式是讓 ``switch`` 和從屬於它的 ``case`` +標籤對齊於同一列，而不要 ``兩次縮進`` ``case`` 標籤。比如： + +.. code-block:: c + + switch (suffix) { + case 'G': + case 'g': + mem <<= 30; + break; + case 'M': + case 'm': + mem <<= 20; + break; + case 'K': + case 'k': + mem <<= 10; + fallthrough; + default: + break; + } + +不要把多個語句放在一行里，除非你有什麼東西要隱藏： + +.. code-block:: c + + if (condition) do_this; + do_something_everytime; + +也不要在一行里放多個賦值語句。內核代碼風格超級簡單。就是避免可能導致別人誤讀 +的表達式。 + +除了注釋、文檔和 Kconfig 之外，不要使用空格來縮進，前面的例子是例外，是有意爲 +之。 + +選用一個好的編輯器，不要在行尾留空格。 + + +2) 把長的行和字符串打散 +------------------------------ + +代碼風格的意義就在於使用平常使用的工具來維持代碼的可讀性和可維護性。 + +每一行的長度的限制是 80 列，我們強烈建議您遵守這個慣例。 + +長於 80 列的語句要打散成有意義的片段。除非超過 80 列能顯著增加可讀性，並且不 +會隱藏信息。子片段要明顯短於母片段，並明顯靠右。這同樣適用於有著很長參數列表 +的函數頭。然而，絕對不要打散對用戶可見的字符串，例如 printk 信息，因爲這樣就 +很難對它們 grep。 + + +3) 大括號和空格的放置 +------------------------------ + +C 語言風格中另外一個常見問題是大括號的放置。和縮進大小不同，選擇或棄用某种放 +置策略並沒有多少技術上的原因，不過首選的方式，就像 Kernighan 和 Ritchie 展示 +給我們的，是把起始大括號放在行尾，而把結束大括號放在行首，所以： + +.. code-block:: c + + if (x is true) { + we do y + } + +這適用於所有的非函數語句塊 (if, switch, for, while, do)。比如： + +.. code-block:: c + + switch (action) { + case KOBJ_ADD: + return "add"; + case KOBJ_REMOVE: + return "remove"; + case KOBJ_CHANGE: + return "change"; + default: + return NULL; + } + +不過，有一個例外，那就是函數：函數的起始大括號放置於下一行的開頭，所以： + +.. code-block:: c + + int function(int x) + { + body of function + } + +全世界的異端可能會抱怨這個不一致性是... 呃... 不一致的，不過所有思維健全的人 +都知道 (a) K&R 是 **正確的** 並且 (b) K&R 是正確的。此外，不管怎樣函數都是特 +殊的 (C 函數是不能嵌套的)。 + +注意結束大括號獨自占據一行，除非它後面跟著同一個語句的剩餘部分，也就是 do 語 +句中的 "while" 或者 if 語句中的 "else"，像這樣： + +.. code-block:: c + + do { + body of do-loop + } while (condition); + +和 + +.. code-block:: c + + if (x == y) { + .. + } else if (x > y) { + ... + } else { + .... + } + +理由：K&R。 + +也請注意這種大括號的放置方式也能使空 (或者差不多空的) 行的數量最小化，同時不 +失可讀性。因此，由於你的屏幕上的新行是不可再生資源 (想想 25 行的終端屏幕)，你 +將會有更多的空行來放置注釋。 + +當只有一個單獨的語句的時候，不用加不必要的大括號。 + +.. code-block:: c + + if (condition) + action(); + +和 + +.. code-block:: c + + if (condition) + do_this(); + else + do_that(); + +這並不適用於只有一個條件分支是單語句的情況；這時所有分支都要使用大括號： + +.. code-block:: c + + if (condition) { + do_this(); + do_that(); + } else { + otherwise(); + } + +3.1) 空格 +******************** + +Linux 內核的空格使用方式 (主要) 取決於它是用於函數還是關鍵字。(大多數) 關鍵字 +後要加一個空格。值得注意的例外是 sizeof, typeof, alignof 和 __attribute__，這 +些關鍵字某些程度上看起來更像函數 (它們在 Linux 里也常常伴隨小括號而使用，儘管 +在 C 里這樣的小括號不是必需的，就像 ``struct fileinfo info;`` 聲明過後的 +``sizeof info``)。 + +所以在這些關鍵字之後放一個空格:: + + if, switch, case, for, do, while + +但是不要在 sizeof, typeof, alignof 或者 __attribute__ 這些關鍵字之後放空格。 +例如， + +.. code-block:: c + + s = sizeof(struct file); + +不要在小括號里的表達式兩側加空格。這是一個 **反例** ： + +.. code-block:: c + + s = sizeof( struct file ); + +當聲明指針類型或者返回指針類型的函數時， ``*`` 的首選使用方式是使之靠近變量名 +或者函數名，而不是靠近類型名。例子： + +.. code-block:: c + + char *linux_banner; + unsigned long long memparse(char *ptr, char **retptr); + char *match_strdup(substring_t *s); + +在大多數二元和三元操作符兩側使用一個空格，例如下面所有這些操作符:: + + = + - < > * / % | & ^ <= >= == != ? : + +但是一元操作符後不要加空格:: + + & * + - ~ ! sizeof typeof alignof __attribute__ defined + +後綴自加和自減一元操作符前不加空格:: + + ++ -- + +前綴自加和自減一元操作符後不加空格:: + + ++ -- + +``.`` 和 ``->`` 結構體成員操作符前後不加空格。 + +不要在行尾留空白。有些可以自動縮進的編輯器會在新行的行首加入適量的空白，然後 +你就可以直接在那一行輸入代碼。不過假如你最後沒有在那一行輸入代碼，有些編輯器 +就不會移除已經加入的空白，就像你故意留下一個只有空白的行。包含行尾空白的行就 +這樣產生了。 + +當 git 發現補丁包含了行尾空白的時候會警告你，並且可以應你的要求去掉行尾空白； +不過如果你是正在打一系列補丁，這樣做會導致後面的補丁失敗，因爲你改變了補丁的 +上下文。 + + +4) 命名 +------------------------------ + +C 是一個簡樸的語言，你的命名也應該這樣。和 Modula-2 和 Pascal 程式設計師不同， +C 程式設計師不使用類似 ThisVariableIsATemporaryCounter 這樣華麗的名字。C 程式設計師會 +稱那個變量爲 ``tmp`` ，這樣寫起來會更容易，而且至少不會令其難於理解。 + +不過，雖然混用大小寫的名字是不提倡使用的，但是全局變量還是需要一個具描述性的 +名字。稱一個全局函數爲 ``foo`` 是一個難以饒恕的錯誤。 + +全局變量 (只有當你 **真正** 需要它們的時候再用它) 需要有一個具描述性的名字，就 +像全局函數。如果你有一個可以計算活動用戶數量的函數，你應該叫它 +``count_active_users()`` 或者類似的名字，你不應該叫它 ``cntuser()`` 。 + +在函數名中包含函數類型 (所謂的匈牙利命名法) 是腦子出了問題——編譯器知道那些類 +型而且能夠檢查那些類型，這樣做只能把程式設計師弄糊塗了。難怪微軟總是製造出有問題 +的程序。 + +本地變量名應該簡短，而且能夠表達相關的含義。如果你有一些隨機的整數型的循環計 +數器，它應該被稱爲 ``i`` 。叫它 ``loop_counter`` 並無益處，如果它沒有被誤解的 +可能的話。類似的， ``tmp`` 可以用來稱呼任意類型的臨時變量。 + +如果你怕混淆了你的本地變量名，你就遇到另一個問題了，叫做函數增長荷爾蒙失衡綜 +合症。請看第六章 (函數)。 + + +5) Typedef +----------- + +不要使用類似 ``vps_t`` 之類的東西。 + +對結構體和指針使用 typedef 是一個 **錯誤** 。當你在代碼里看到： + +.. code-block:: c + + vps_t a; + +這代表什麼意思呢？ + +相反，如果是這樣 + +.. code-block:: c + + struct virtual_container *a; + +你就知道 ``a`` 是什麼了。 + +很多人認爲 typedef ``能提高可讀性`` 。實際不是這樣的。它們只在下列情況下有用： + + (a) 完全不透明的對象 (這種情況下要主動使用 typedef 來 **隱藏** 這個對象實際上 + 是什麼)。 + + 例如： ``pte_t`` 等不透明對象，你只能用合適的訪問函數來訪問它們。 + + .. note:: + + 不透明性和 "訪問函數" 本身是不好的。我們使用 pte_t 等類型的原因在於真 + 的是完全沒有任何共用的可訪問信息。 + + (b) 清楚的整數類型，如此，這層抽象就可以 **幫助** 消除到底是 ``int`` 還是 + ``long`` 的混淆。 + + u8/u16/u32 是完全沒有問題的 typedef，不過它們更符合類別 (d) 而不是這裡。 + + .. note:: + + 要這樣做，必須事出有因。如果某個變量是 ``unsigned long`` ，那麼沒有必要 + + typedef unsigned long myflags_t; + + 不過如果有一個明確的原因，比如它在某種情況下可能會是一個 ``unsigned int`` + 而在其他情況下可能爲 ``unsigned long`` ，那麼就不要猶豫，請務必使用 + typedef。 + + (c) 當你使用 sparse 按字面的創建一個 **新** 類型來做類型檢查的時候。 + + (d) 和標準 C99 類型相同的類型，在某些例外的情況下。 + + 雖然讓眼睛和腦筋來適應新的標準類型比如 ``uint32_t`` 不需要花很多時間，可 + 是有些人仍然拒絕使用它們。 + + 因此，Linux 特有的等同於標準類型的 ``u8/u16/u32/u64`` 類型和它們的有符號 + 類型是被允許的——儘管在你自己的新代碼中，它們不是強制要求要使用的。 + + 當編輯已經使用了某個類型集的已有代碼時，你應該遵循那些代碼中已經做出的選 + 擇。 + + (e) 可以在用戶空間安全使用的類型。 + + 在某些用戶空間可見的結構體裡，我們不能要求 C99 類型而且不能用上面提到的 + ``u32`` 類型。因此，我們在與用戶空間共享的所有結構體中使用 __u32 和類似 + 的類型。 + +可能還有其他的情況，不過基本的規則是 **永遠不要** 使用 typedef，除非你可以明 +確的應用上述某個規則中的一個。 + +總的來說，如果一個指針或者一個結構體裡的元素可以合理的被直接訪問到，那麼它們 +就不應該是一個 typedef。 + + +6) 函數 +------------------------------ + +函數應該簡短而漂亮，並且只完成一件事情。函數應該可以一屏或者兩屏顯示完 (我們 +都知道 ISO/ANSI 屏幕大小是 80x24)，只做一件事情，而且把它做好。 + +一個函數的最大長度是和該函數的複雜度和縮進級數成反比的。所以，如果你有一個理 +論上很簡單的只有一個很長 (但是簡單) 的 case 語句的函數，而且你需要在每個 case +里做很多很小的事情，這樣的函數儘管很長，但也是可以的。 + +不過，如果你有一個複雜的函數，而且你懷疑一個天分不是很高的高中一年級學生可能 +甚至搞不清楚這個函數的目的，你應該嚴格遵守前面提到的長度限制。使用輔助函數， +並爲之取個具描述性的名字 (如果你覺得它們的性能很重要的話，可以讓編譯器內聯它 +們，這樣的效果往往會比你寫一個複雜函數的效果要好。) + +函數的另外一個衡量標準是本地變量的數量。此數量不應超過 5－10 個，否則你的函數 +就有問題了。重新考慮一下你的函數，把它分拆成更小的函數。人的大腦一般可以輕鬆 +的同時跟蹤 7 個不同的事物，如果再增多的話，就會糊塗了。即便你聰穎過人，你也可 +能會記不清你 2 個星期前做過的事情。 + +在源文件里，使用空行隔開不同的函數。如果該函數需要被導出，它的 **EXPORT** 宏 +應該緊貼在它的結束大括號之下。比如： + +.. code-block:: c + + int system_is_up(void) + { + return system_state == SYSTEM_RUNNING; + } + EXPORT_SYMBOL(system_is_up); + +在函數原型中，包含函數名和它們的數據類型。雖然 C 語言裡沒有這樣的要求，在 +Linux 里這是提倡的做法，因爲這樣可以很簡單的給讀者提供更多的有價值的信息。 + + +7) 集中的函數退出途徑 +------------------------------ + +雖然被某些人聲稱已經過時，但是 goto 語句的等價物還是經常被編譯器所使用，具體 +形式是無條件跳轉指令。 + +當一個函數從多個位置退出，並且需要做一些類似清理的常見操作時，goto 語句就很方 +便了。如果並不需要清理操作，那麼直接 return 即可。 + +選擇一個能夠說明 goto 行爲或它爲何存在的標籤名。如果 goto 要釋放 ``buffer``, +一個不錯的名字可以是 ``out_free_buffer:`` 。別去使用像 ``err1:`` 和 ``err2:`` +這樣的GW_BASIC 名稱，因爲一旦你添加或刪除了 (函數的) 退出路徑，你就必須對它們 +重新編號，這樣會難以去檢驗正確性。 + +使用 goto 的理由是： + +- 無條件語句容易理解和跟蹤 +- 嵌套程度減小 +- 可以避免由於修改時忘記更新個別的退出點而導致錯誤 +- 讓編譯器省去刪除冗餘代碼的工作 ;) + +.. code-block:: c + + int fun(int a) + { + int result = 0; + char *buffer; + + buffer = kmalloc(SIZE, GFP_KERNEL); + if (!buffer) + return -ENOMEM; + + if (condition1) { + while (loop1) { + ... + } + result = 1; + goto out_free_buffer; + } + ... + out_free_buffer: + kfree(buffer); + return result; + } + +一個需要注意的常見錯誤是 ``一個 err 錯誤`` ，就像這樣： + +.. code-block:: c + + err: + kfree(foo->bar); + kfree(foo); + return ret; + +這段代碼的錯誤是，在某些退出路徑上 ``foo`` 是 NULL。通常情況下，通過把它分離 +成兩個錯誤標籤 ``err_free_bar:`` 和 ``err_free_foo:`` 來修復這個錯誤： + +.. code-block:: c + + err_free_bar: + kfree(foo->bar); + err_free_foo: + kfree(foo); + return ret; + +理想情況下，你應該模擬錯誤來測試所有退出路徑。 + + +8) 注釋 +------------------------------ + +注釋是好的，不過有過度注釋的危險。永遠不要在注釋里解釋你的代碼是如何運作的： +更好的做法是讓別人一看你的代碼就可以明白，解釋寫的很差的代碼是浪費時間。 + +一般的，你想要你的注釋告訴別人你的代碼做了什麼，而不是怎麼做的。也請你不要把 +注釋放在一個函數體內部：如果函數複雜到你需要獨立的注釋其中的一部分，你很可能 +需要回到第六章看一看。你可以做一些小注釋來註明或警告某些很聰明 (或者槽糕) 的 +做法，但不要加太多。你應該做的，是把注釋放在函數的頭部，告訴人們它做了什麼， +也可以加上它做這些事情的原因。 + +當注釋內核 API 函數時，請使用 kernel-doc 格式。請看 +Documentation/doc-guide/ 和 scripts/kernel-doc 以獲得詳細信息。 + +長 (多行) 注釋的首選風格是： + +.. code-block:: c + + /* + * This is the preferred style for multi-line + * comments in the Linux kernel source code. + * Please use it consistently. + * + * Description: A column of asterisks on the left side, + * with beginning and ending almost-blank lines. + */ + +對於在 net/ 和 drivers/net/ 的文件，首選的長 (多行) 注釋風格有些不同。 + +.. code-block:: c + + /* The preferred comment style for files in net/ and drivers/net + * looks like this. + * + * It is nearly the same as the generally preferred comment style, + * but there is no initial almost-blank line. + */ + +注釋數據也是很重要的，不管是基本類型還是衍生類型。爲了方便實現這一點，每一行 +應只聲明一個數據 (不要使用逗號來一次聲明多個數據)。這樣你就有空間來爲每個數據 +寫一段小注釋來解釋它們的用途了。 + + +9) 你已經把事情弄糟了 +------------------------------ + +這沒什麼，我們都是這樣。可能你的使用了很長時間 Unix 的朋友已經告訴你 +``GNU emacs`` 能自動幫你格式化 C 原始碼，而且你也注意到了，確實是這樣，不過它 +所使用的默認值和我們想要的相去甚遠 (實際上，甚至比隨機打的還要差——無數個猴子 +在 GNU emacs 里打字永遠不會創造出一個好程序) (譯註：Infinite Monkey Theorem) + +所以你要麼放棄 GNU emacs，要麼改變它讓它使用更合理的設定。要採用後一個方案， +你可以把下面這段粘貼到你的 .emacs 文件里。 + +.. code-block:: none + + (defun c-lineup-arglist-tabs-only (ignored) + "Line up argument lists by tabs, not spaces" + (let* ((anchor (c-langelem-pos c-syntactic-element)) + (column (c-langelem-2nd-pos c-syntactic-element)) + (offset (- (1+ column) anchor)) + (steps (floor offset c-basic-offset))) + (* (max steps 1) + c-basic-offset))) + + (dir-locals-set-class-variables + 'linux-kernel + '((c-mode . ( + (c-basic-offset . 8) + (c-label-minimum-indentation . 0) + (c-offsets-alist . ( + (arglist-close . c-lineup-arglist-tabs-only) + (arglist-cont-nonempty . + (c-lineup-gcc-asm-reg c-lineup-arglist-tabs-only)) + (arglist-intro . +) + (brace-list-intro . +) + (c . c-lineup-C-comments) + (case-label . 0) + (comment-intro . c-lineup-comment) + (cpp-define-intro . +) + (cpp-macro . -1000) + (cpp-macro-cont . +) + (defun-block-intro . +) + (else-clause . 0) + (func-decl-cont . +) + (inclass . +) + (inher-cont . c-lineup-multi-inher) + (knr-argdecl-intro . 0) + (label . -1000) + (statement . 0) + (statement-block-intro . +) + (statement-case-intro . +) + (statement-cont . +) + (substatement . +) + )) + (indent-tabs-mode . t) + (show-trailing-whitespace . t) + )))) + + (dir-locals-set-directory-class + (expand-file-name "~/src/linux-trees") + 'linux-kernel) + +這會讓 emacs 在 ``~/src/linux-trees`` 下的 C 源文件獲得更好的內核代碼風格。 + +不過就算你嘗試讓 emacs 正確的格式化代碼失敗了，也並不意味著你失去了一切：還可 +以用 ``indent`` 。 + +不過，GNU indent 也有和 GNU emacs 一樣有問題的設定，所以你需要給它一些命令選 +項。不過，這還不算太糟糕，因爲就算是 GNU indent 的作者也認同 K&R 的權威性 +(GNU 的人並不是壞人，他們只是在這個問題上被嚴重的誤導了)，所以你只要給 indent +指定選項 ``-kr -i8`` (代表 ``K&R，8 字符縮進``)，或使用 ``scripts/Lindent`` +這樣就可以以最時髦的方式縮進原始碼。 + +``indent`` 有很多選項，特別是重新格式化注釋的時候，你可能需要看一下它的手冊。 +不過記住： ``indent`` 不能修正壞的編程習慣。 + + +10) Kconfig 配置文件 +------------------------------ + +對於遍布源碼樹的所有 Kconfig* 配置文件來說，它們縮進方式有所不同。緊挨著 +``config`` 定義的行，用一個制表符縮進，然而 help 信息的縮進則額外增加 2 個空 +格。舉個例子:: + + config AUDIT + bool "Auditing support" + depends on NET + help + Enable auditing infrastructure that can be used with another + kernel subsystem, such as SELinux (which requires this for + logging of avc messages output). Does not do system-call + auditing without CONFIG_AUDITSYSCALL. + +而那些危險的功能 (比如某些文件系統的寫支持) 應該在它們的提示字符串里顯著的聲 +明這一點:: + + config ADFS_FS_RW + bool "ADFS write support (DANGEROUS)" + depends on ADFS_FS + ... + +要查看配置文件的完整文檔，請看 Documentation/kbuild/kconfig-language.rst。 + + +11) 數據結構 +------------------------------ + +如果一個數據結構，在創建和銷毀它的單線執行環境之外可見，那麼它必須要有一個引 +用計數器。內核里沒有垃圾收集 (並且內核之外的垃圾收集慢且效率低下)，這意味著你 +絕對需要記錄你對這種數據結構的使用情況。 + +引用計數意味著你能夠避免上鎖，並且允許多個用戶並行訪問這個數據結構——而不需要 +擔心這個數據結構僅僅因爲暫時不被使用就消失了，那些用戶可能不過是沉睡了一陣或 +者做了一些其他事情而已。 + +注意上鎖 **不能** 取代引用計數。上鎖是爲了保持數據結構的一致性，而引用計數是一 +個內存管理技巧。通常二者都需要，不要把兩個搞混了。 + +很多數據結構實際上有 2 級引用計數，它們通常有不同 ``類`` 的用戶。子類計數器統 +計子類用戶的數量，每當子類計數器減至零時，全局計數器減一。 + +這種 ``多級引用計數`` 的例子可以在內存管理 (``struct mm_struct``: mm_users 和 +mm_count)，和文件系統 (``struct super_block``: s_count 和 s_active) 中找到。 + +記住：如果另一個執行線索可以找到你的數據結構，但這個數據結構沒有引用計數器， +這裡幾乎肯定是一個 bug。 + + +12) 宏，枚舉和RTL +------------------------------ + +用於定義常量的宏的名字及枚舉里的標籤需要大寫。 + +.. code-block:: c + + #define CONSTANT 0x12345 + +在定義幾個相關的常量時，最好用枚舉。 + +宏的名字請用大寫字母，不過形如函數的宏的名字可以用小寫字母。 + +一般的，如果能寫成內聯函數就不要寫成像函數的宏。 + +含有多個語句的宏應該被包含在一個 do-while 代碼塊里： + +.. code-block:: c + + #define macrofun(a, b, c) \ + do { \ + if (a == 5) \ + do_this(b, c); \ + } while (0) + +使用宏的時候應避免的事情： + +1) 影響控制流程的宏： + +.. code-block:: c + + #define FOO(x) \ + do { \ + if (blah(x) < 0) \ + return -EBUGGERED; \ + } while (0) + +**非常** 不好。它看起來像一個函數，不過卻能導致 ``調用`` 它的函數退出；不要打 +亂讀者大腦里的語法分析器。 + +2) 依賴於一個固定名字的本地變量的宏： + +.. code-block:: c + + #define FOO(val) bar(index, val) + +可能看起來像是個不錯的東西，不過它非常容易把讀代碼的人搞糊塗，而且容易導致看起 +來不相關的改動帶來錯誤。 + +3) 作爲左值的帶參數的宏： FOO(x) = y；如果有人把 FOO 變成一個內聯函數的話，這 + 種用法就會出錯了。 + +4) 忘記了優先級：使用表達式定義常量的宏必須將表達式置於一對小括號之內。帶參數 + 的宏也要注意此類問題。 + +.. code-block:: c + + #define CONSTANT 0x4000 + #define CONSTEXP (CONSTANT | 3) + +5) 在宏里定義類似函數的本地變量時命名衝突： + +.. code-block:: c + + #define FOO(x) \ + ({ \ + typeof(x) ret; \ + ret = calc_ret(x); \ + (ret); \ + }) + +ret 是本地變量的通用名字 - __foo_ret 更不容易與一個已存在的變量衝突。 + +cpp 手冊對宏的講解很詳細。gcc internals 手冊也詳細講解了 RTL，內核里的彙編語 +言經常用到它。 + + +13) 列印內核消息 +------------------------------ + +內核開發者應該是受過良好教育的。請一定注意內核信息的拼寫，以給人以好的印象。 +不要用不規範的單詞比如 ``dont``，而要用 ``do not`` 或者 ``don't`` 。保證這些信 +息簡單明了,無歧義。 + +內核信息不必以英文句號結束。 + +在小括號里列印數字 (%d) 沒有任何價值，應該避免這樣做。 + +<linux/device.h> 里有一些驅動模型診斷宏，你應該使用它們，以確保信息對應於正確 +的設備和驅動，並且被標記了正確的消息級別。這些宏有：dev_err(), dev_warn(), +dev_info() 等等。對於那些不和某個特定設備相關連的信息，<linux/printk.h> 定義 +了 pr_notice(), pr_info(), pr_warn(), pr_err() 和其他。 + +寫出好的調試信息可以是一個很大的挑戰；一旦你寫出後，這些信息在遠程除錯時能提 +供極大的幫助。然而列印調試信息的處理方式同列印非調試信息不同。其他 pr_XXX() +函數能無條件地列印，pr_debug() 卻不；默認情況下它不會被編譯，除非定義了 DEBUG +或設定了 CONFIG_DYNAMIC_DEBUG。實際這同樣是爲了 dev_dbg()，一個相關約定是在一 +個已經開啓了 DEBUG 時，使用 VERBOSE_DEBUG 來添加 dev_vdbg()。 + +許多子系統擁有 Kconfig 調試選項來開啓 -DDEBUG 在對應的 Makefile 裡面；在其他 +情況下，特殊文件使用 #define DEBUG。當一條調試信息需要被無條件列印時，例如， +如果已經包含一個調試相關的 #ifdef 條件，printk(KERN_DEBUG ...) 就可被使用。 + + +14) 分配內存 +------------------------------ + +內核提供了下面的一般用途的內存分配函數： +kmalloc(), kzalloc(), kmalloc_array(), kcalloc(), vmalloc() 和 vzalloc()。 +請參考 API 文檔以獲取有關它們的詳細信息。 + +傳遞結構體大小的首選形式是這樣的： + +.. code-block:: c + + p = kmalloc(sizeof(*p), ...); + +另外一種傳遞方式中，sizeof 的操作數是結構體的名字，這樣會降低可讀性，並且可能 +會引入 bug。有可能指針變量類型被改變時，而對應的傳遞給內存分配函數的 sizeof +的結果不變。 + +強制轉換一個 void 指針返回值是多餘的。C 語言本身保證了從 void 指針到其他任何 +指針類型的轉換是沒有問題的。 + +分配一個數組的首選形式是這樣的： + +.. code-block:: c + + p = kmalloc_array(n, sizeof(...), ...); + +分配一個零長數組的首選形式是這樣的： + +.. code-block:: c + + p = kcalloc(n, sizeof(...), ...); + +兩種形式檢查分配大小 n * sizeof(...) 的溢出，如果溢出返回 NULL。 + + +15) 內聯弊病 +------------------------------ + +有一個常見的誤解是 ``內聯`` 是 gcc 提供的可以讓代碼運行更快的一個選項。雖然使 +用內聯函數有時候是恰當的 (比如作爲一種替代宏的方式，請看第十二章)，不過很多情 +況下不是這樣。inline 的過度使用會使內核變大，從而使整個系統運行速度變慢。 +因爲體積大內核會占用更多的指令高速緩存，而且會導致 pagecache 的可用內存減少。 +想像一下，一次 pagecache 未命中就會導致一次磁碟尋址，將耗時 5 毫秒。5 毫秒的 +時間內 CPU 能執行很多很多指令。 + +一個基本的原則是如果一個函數有 3 行以上，就不要把它變成內聯函數。這個原則的一 +個例外是，如果你知道某個參數是一個編譯時常量，而且因爲這個常量你確定編譯器在 +編譯時能優化掉你的函數的大部分代碼，那仍然可以給它加上 inline 關鍵字。 +kmalloc() 內聯函數就是一個很好的例子。 + +人們經常主張給 static 的而且只用了一次的函數加上 inline，如此不會有任何損失， +因爲沒有什麼好權衡的。雖然從技術上說這是正確的，但是實際上這種情況下即使不加 +inline gcc 也可以自動使其內聯。而且其他用戶可能會要求移除 inline，由此而來的 +爭論會抵消 inline 自身的潛在價值，得不償失。 + + +16) 函數返回值及命名 +------------------------------ + +函數可以返回多種不同類型的值，最常見的一種是表明函數執行成功或者失敗的值。這樣 +的一個值可以表示爲一個錯誤代碼整數 (-Exxx＝失敗，0＝成功) 或者一個 ``成功`` +布爾值 (0＝失敗，非0＝成功)。 + +混合使用這兩種表達方式是難於發現的 bug 的來源。如果 C 語言本身嚴格區分整形和 +布爾型變量，那麼編譯器就能夠幫我們發現這些錯誤... 不過 C 語言不區分。爲了避免 +產生這種 bug，請遵循下面的慣例:: + + 如果函數的名字是一個動作或者強制性的命令，那麼這個函數應該返回錯誤代 + 碼整數。如果是一個判斷，那麼函數應該返回一個 "成功" 布爾值。 + +比如， ``add work`` 是一個命令，所以 add_work() 在成功時返回 0，在失敗時返回 +-EBUSY。類似的，因爲 ``PCI device present`` 是一個判斷，所以 pci_dev_present() +在成功找到一個匹配的設備時應該返回 1，如果找不到時應該返回 0。 + +所有 EXPORTed 函數都必須遵守這個慣例，所有的公共函數也都應該如此。私有 +(static) 函數不需要如此，但是我們也推薦這樣做。 + +返回值是實際計算結果而不是計算是否成功的標誌的函數不受此慣例的限制。一般的， +他們通過返回一些正常值範圍之外的結果來表示出錯。典型的例子是返回指針的函數， +他們使用 NULL 或者 ERR_PTR 機制來報告錯誤。 + + +17) 不要重新發明內核宏 +------------------------------ + +頭文件 include/linux/kernel.h 包含了一些宏，你應該使用它們，而不要自己寫一些 +它們的變種。比如，如果你需要計算一個數組的長度，使用這個宏 + +.. code-block:: c + + #define ARRAY_SIZE(x) (sizeof(x) / sizeof((x)[0])) + +類似的，如果你要計算某結構體成員的大小，使用 + +.. code-block:: c + + #define sizeof_field(t, f) (sizeof(((t*)0)->f)) + +還有可以做嚴格的類型檢查的 min() 和 max() 宏，如果你需要可以使用它們。你可以 +自己看看那個頭文件里還定義了什麼你可以拿來用的東西，如果有定義的話，你就不應 +在你的代碼里自己重新定義。 + + +18) 編輯器模式行和其他需要羅嗦的事情 +-------------------------------------------------- + +有一些編輯器可以解釋嵌入在源文件里的由一些特殊標記標明的配置信息。比如，emacs +能夠解釋被標記成這樣的行： + +.. code-block:: c + + -*- mode: c -*- + +或者這樣的： + +.. code-block:: c + + /* + Local Variables: + compile-command: "gcc -DMAGIC_DEBUG_FLAG foo.c" + End: + */ + +Vim 能夠解釋這樣的標記： + +.. code-block:: c + + /* vim:set sw=8 noet */ + +不要在原始碼中包含任何這樣的內容。每個人都有他自己的編輯器配置，你的源文件不 +應該覆蓋別人的配置。這包括有關縮進和模式配置的標記。人們可以使用他們自己定製 +的模式，或者使用其他可以產生正確的縮進的巧妙方法。 + + +19) 內聯彙編 +------------------------------ + +在特定架構的代碼中，你可能需要內聯彙編與 CPU 和平台相關功能連接。需要這麼做時 +就不要猶豫。然而，當 C 可以完成工作時，不要平白無故地使用內聯彙編。在可能的情 +況下，你可以並且應該用 C 和硬體溝通。 + +請考慮去寫捆綁通用位元 (wrap common bits) 的內聯彙編的簡單輔助函數，別去重複 +地寫下只有細微差異內聯彙編。記住內聯彙編可以使用 C 參數。 + +大型，有一定複雜度的彙編函數應該放在 .S 文件內，用相應的 C 原型定義在 C 頭文 +件中。彙編函數的 C 原型應該使用 ``asmlinkage`` 。 + +你可能需要把彙編語句標記爲 volatile，用來阻止 GCC 在沒發現任何副作用後就把它 +移除了。你不必總是這樣做，儘管，這不必要的舉動會限制優化。 + +在寫一個包含多條指令的單個內聯彙編語句時，把每條指令用引號分割而且各占一行， +除了最後一條指令外，在每個指令結尾加上 \n\t，讓彙編輸出時可以正確地縮進下一條 +指令： + +.. code-block:: c + + asm ("magic %reg1, #42\n\t" + "more_magic %reg2, %reg3" + : /* outputs */ : /* inputs */ : /* clobbers */); + + +20) 條件編譯 +------------------------------ + +只要可能，就不要在 .c 文件裡面使用預處理條件 (#if, #ifdef)；這樣做讓代碼更難 +閱讀並且更難去跟蹤邏輯。替代方案是，在頭文件中用預處理條件提供給那些 .c 文件 +使用，再給 #else 提供一個空樁 (no-op stub) 版本，然後在 .c 文件內無條件地調用 +那些 (定義在頭文件內的) 函數。這樣做，編譯器會避免爲樁函數 (stub) 的調用生成 +任何代碼，產生的結果是相同的，但邏輯將更加清晰。 + +最好傾向於編譯整個函數，而不是函數的一部分或表達式的一部分。與其放一個 ifdef +在表達式內，不如分解出部分或全部表達式，放進一個單獨的輔助函數，並應用預處理 +條件到這個輔助函數內。 + +如果你有一個在特定配置中，可能變成未使用的函數或變量，編譯器會警告它定義了但 +未使用，把它標記爲 __maybe_unused 而不是將它包含在一個預處理條件中。(然而，如 +果一個函數或變量總是未使用，就直接刪除它。) + +在代碼中，儘可能地使用 IS_ENABLED 宏來轉化某個 Kconfig 標記爲 C 的布爾 +表達式，並在一般的 C 條件中使用它： + +.. code-block:: c + + if (IS_ENABLED(CONFIG_SOMETHING)) { + ... + } + +編譯器會做常量摺疊，然後就像使用 #ifdef 那樣去包含或排除代碼塊，所以這不會帶 +來任何運行時開銷。然而，這種方法依舊允許 C 編譯器查看塊內的代碼，並檢查它的正 +確性 (語法，類型，符號引用，等等)。因此，如果條件不滿足，代碼塊內的引用符號就 +不存在時，你還是必須去用 #ifdef。 + +在任何有意義的 #if 或 #ifdef 塊的末尾 (超過幾行的)，在 #endif 同一行的後面寫下 +註解，注釋這個條件表達式。例如： + +.. code-block:: c + + #ifdef CONFIG_SOMETHING + ... + #endif /* CONFIG_SOMETHING */ + + +附錄 I) 參考 +------------------- + +The C Programming Language, 第二版 +作者：Brian W. Kernighan 和 Denni M. Ritchie. +Prentice Hall, Inc., 1988. +ISBN 0-13-110362-8 (軟皮), 0-13-110370-9 (硬皮). + +The Practice of Programming +作者：Brian W. Kernighan 和 Rob Pike. +Addison-Wesley, Inc., 1999. +ISBN 0-201-61586-X. + +GNU 手冊 - 遵循 K&R 標準和此文本 - cpp, gcc, gcc internals and indent, +都可以從 https://www.gnu.org/manual/ 找到 + +WG14 是 C 語言的國際標準化工作組，URL: http://www.open-std.org/JTC1/SC22/WG14/ + +Kernel process/coding-style.rst，作者 greg@kroah.com 發表於 OLS 2002： +http://www.kroah.com/linux/talks/ols_2002_kernel_codingstyle_talk/html/ + diff --git a/Documentation/translations/zh_TW/process/development-process.rst b/Documentation/translations/zh_TW/process/development-process.rst new file mode 100644 index 000000000000..45e6385647cd --- /dev/null +++ b/Documentation/translations/zh_TW/process/development-process.rst @@ -0,0 +1,30 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. include:: ../disclaimer-zh_TW.rst + +:Original: :ref:`Documentation/process/development-process.rst <development_process_main>` +:Translator: Alex Shi <alex.shi@linux.alibaba.com> + Hu Haowen <src.res@email.cn> + +.. _tw_development_process_main: + +內核開發過程指南 +================ + +內容: + +.. toctree:: + :numbered: + :maxdepth: 2 + + 1.Intro + 2.Process + 3.Early-stage + 4.Coding + 5.Posting + 6.Followthrough + 7.AdvancedTopics + 8.Conclusion + +本文檔的目的是幫助開發人員（及其經理）以最小的挫折感與開發社區合作。它試圖記錄這個社區如何以一種不熟悉Linux內核開發（或者實際上是自由軟體開發）的人可以訪問的方式工作。雖然這裡有一些技術資料，但這是一個面向過程的討論，不需要深入了解內核編程就可以理解。 + diff --git a/Documentation/translations/zh_TW/process/email-clients.rst b/Documentation/translations/zh_TW/process/email-clients.rst new file mode 100644 index 000000000000..4ba543d06f3b --- /dev/null +++ b/Documentation/translations/zh_TW/process/email-clients.rst @@ -0,0 +1,252 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. _tw_email_clients: + +.. include:: ../disclaimer-zh_TW.rst + +:Original: :ref:`Documentation/process/email-clients.rst <email_clients>` + +譯者:: + + 中文版維護者： 賈威威 Harry Wei <harryxiyou@gmail.com> + 中文版翻譯者： 賈威威 Harry Wei <harryxiyou@gmail.com> + 時奎亮 Alex Shi <alex.shi@linux.alibaba.com> + 中文版校譯者： Yinglin Luan <synmyth@gmail.com> + Xiaochen Wang <wangxiaochen0@gmail.com> + yaxinsn <yaxinsn@163.com> + Hu Haowen <src.res@email.cn> + +Linux郵件客戶端配置信息 +======================= + +Git +--- + +現在大多數開發人員使用 ``git send-email`` 而不是常規的電子郵件客戶端。這方面 +的手冊非常好。在接收端，維護人員使用 ``git am`` 加載補丁。 + +如果你是 ``git`` 新手，那麼把你的第一個補丁發送給你自己。將其保存爲包含所有 +標題的原始文本。運行 ``git am raw_email.txt`` ，然後使用 ``git log`` 查看更 +改日誌。如果工作正常，再將補丁發送到相應的郵件列表。 + + +普通配置 +-------- +Linux內核補丁是通過郵件被提交的，最好把補丁作爲郵件體的內嵌文本。有些維護者 +接收附件，但是附件的內容格式應該是"text/plain"。然而，附件一般是不贊成的， +因爲這會使補丁的引用部分在評論過程中變的很困難。 + +用來發送Linux內核補丁的郵件客戶端在發送補丁時應該處於文本的原始狀態。例如， +他們不能改變或者刪除制表符或者空格，甚至是在每一行的開頭或者結尾。 + +不要通過"format=flowed"模式發送補丁。這樣會引起不可預期以及有害的斷行。 + +不要讓你的郵件客戶端進行自動換行。這樣也會破壞你的補丁。 + +郵件客戶端不能改變文本的字符集編碼方式。要發送的補丁只能是ASCII或者UTF-8編碼方式， +如果你使用UTF-8編碼方式發送郵件，那麼你將會避免一些可能發生的字符集問題。 + +郵件客戶端應該形成並且保持 References: 或者 In-Reply-To: 標題，那麼 +郵件話題就不會中斷。 + +複製粘帖(或者剪貼粘帖)通常不能用於補丁，因爲制表符會轉換爲空格。使用xclipboard, xclip +或者xcutsel也許可以，但是最好測試一下或者避免使用複製粘帖。 + +不要在使用PGP/GPG署名的郵件中包含補丁。這樣會使得很多腳本不能讀取和適用於你的補丁。 +（這個問題應該是可以修復的） + +在給內核郵件列表發送補丁之前，給自己發送一個補丁是個不錯的主意，保存接收到的 +郵件，將補丁用'patch'命令打上，如果成功了，再給內核郵件列表發送。 + + +一些郵件客戶端提示 +------------------ +這裡給出一些詳細的MUA配置提示，可以用於給Linux內核發送補丁。這些並不意味是 +所有的軟體包配置總結。 + +說明： +TUI = 以文本爲基礎的用戶接口 +GUI = 圖形界面用戶接口 + +Alpine (TUI) +~~~~~~~~~~~~ + +配置選項： +在"Sending Preferences"部分： + +- "Do Not Send Flowed Text"必須開啓 +- "Strip Whitespace Before Sending"必須關閉 + +當寫郵件時，光標應該放在補丁會出現的地方，然後按下CTRL-R組合鍵，使指定的 +補丁文件嵌入到郵件中。 + +Evolution (GUI) +~~~~~~~~~~~~~~~ + +一些開發者成功的使用它發送補丁 + +當選擇郵件選項：Preformat + 從Format->Heading->Preformatted (Ctrl-7)或者工具欄 + +然後使用： + Insert->Text File... (Alt-n x)插入補丁文件。 + +你還可以"diff -Nru old.c new.c | xclip"，選擇Preformat，然後使用中間鍵進行粘帖。 + +Kmail (GUI) +~~~~~~~~~~~ + +一些開發者成功的使用它發送補丁。 + +默認設置不爲HTML格式是合適的；不要啓用它。 + +當書寫一封郵件的時候，在選項下面不要選擇自動換行。唯一的缺點就是你在郵件中輸入的任何文本 +都不會被自動換行，因此你必須在發送補丁之前手動換行。最簡單的方法就是啓用自動換行來書寫郵件， +然後把它保存爲草稿。一旦你在草稿中再次打開它，它已經全部自動換行了，那麼你的郵件雖然沒有 +選擇自動換行，但是還不會失去已有的自動換行。 + +在郵件的底部，插入補丁之前，放上常用的補丁定界符：三個連字號(---)。 + +然後在"Message"菜單條目，選擇插入文件，接著選取你的補丁文件。還有一個額外的選項，你可以 +通過它配置你的郵件建立工具欄菜單，還可以帶上"insert file"圖標。 + +你可以安全地通過GPG標記附件，但是內嵌補丁最好不要使用GPG標記它們。作爲內嵌文本的簽發補丁， +當從GPG中提取7位編碼時會使他們變的更加複雜。 + +如果你非要以附件的形式發送補丁，那麼就右鍵點擊附件，然後選中屬性，突出"Suggest automatic +display"，這樣內嵌附件更容易讓讀者看到。 + +當你要保存將要發送的內嵌文本補丁，你可以從消息列表窗格選擇包含補丁的郵件，然後右擊選擇 +"save as"。你可以使用一個沒有更改的包含補丁的郵件，如果它是以正確的形式組成。當你正真在它 +自己的窗口之下察看，那時沒有選項可以保存郵件--已經有一個這樣的bug被匯報到了kmail的bugzilla +並且希望這將會被處理。郵件是以只針對某個用戶可讀寫的權限被保存的，所以如果你想把郵件複製到其他地方， +你不得不把他們的權限改爲組或者整體可讀。 + +Lotus Notes (GUI) +~~~~~~~~~~~~~~~~~ + +不要使用它。 + +Mutt (TUI) +~~~~~~~~~~ + +很多Linux開發人員使用mutt客戶端，所以證明它肯定工作的非常漂亮。 + +Mutt不自帶編輯器，所以不管你使用什麼編輯器都不應該帶有自動斷行。大多數編輯器都帶有 +一個"insert file"選項，它可以通過不改變文件內容的方式插入文件。 + +'vim'作爲mutt的編輯器： + set editor="vi" + + 如果使用xclip，敲入以下命令 + :set paste + 按中鍵之前或者shift-insert或者使用 + :r filename + +如果想要把補丁作爲內嵌文本。 +(a)ttach工作的很好，不帶有"set paste"。 + +你可以通過 ``git format-patch`` 生成補丁，然後用 Mutt發送它們:: + + $ mutt -H 0001-some-bug-fix.patch + +配置選項： +它應該以默認設置的形式工作。 +然而，把"send_charset"設置爲"us-ascii::utf-8"也是一個不錯的主意。 + +Mutt 是高度可配置的。 這裡是個使用mutt通過 Gmail 發送的補丁的最小配置:: + + # .muttrc + # ================ IMAP ==================== + set imap_user = 'yourusername@gmail.com' + set imap_pass = 'yourpassword' + set spoolfile = imaps://imap.gmail.com/INBOX + set folder = imaps://imap.gmail.com/ + set record="imaps://imap.gmail.com/[Gmail]/Sent Mail" + set postponed="imaps://imap.gmail.com/[Gmail]/Drafts" + set mbox="imaps://imap.gmail.com/[Gmail]/All Mail" + + # ================ SMTP ==================== + set smtp_url = "smtp://username@smtp.gmail.com:587/" + set smtp_pass = $imap_pass + set ssl_force_tls = yes # Require encrypted connection + + # ================ Composition ==================== + set editor = `echo \$EDITOR` + set edit_headers = yes # See the headers when editing + set charset = UTF-8 # value of $LANG; also fallback for send_charset + # Sender, email address, and sign-off line must match + unset use_domain # because joe@localhost is just embarrassing + set realname = "YOUR NAME" + set from = "username@gmail.com" + set use_from = yes + +Mutt文檔含有更多信息: + + http://dev.mutt.org/trac/wiki/UseCases/Gmail + + http://dev.mutt.org/doc/manual.html + +Pine (TUI) +~~~~~~~~~~ + +Pine過去有一些空格刪減問題，但是這些現在應該都被修復了。 + +如果可以，請使用alpine(pine的繼承者) + +配置選項： +- 最近的版本需要消除流程文本 +- "no-strip-whitespace-before-send"選項也是需要的。 + + +Sylpheed (GUI) +~~~~~~~~~~~~~~ + +- 內嵌文本可以很好的工作（或者使用附件）。 +- 允許使用外部的編輯器。 +- 對於目錄較多時非常慢。 +- 如果通過non-SSL連接，無法使用TLS SMTP授權。 +- 在組成窗口中有一個很有用的ruler bar。 +- 給地址本中添加地址就不會正確的了解顯示名。 + +Thunderbird (GUI) +~~~~~~~~~~~~~~~~~ + +默認情況下，thunderbird很容易損壞文本，但是還有一些方法可以強制它變得更好。 + +- 在用戶帳號設置里，組成和尋址，不要選擇"Compose messages in HTML format"。 + +- 編輯你的Thunderbird配置設置來使它不要拆行使用：user_pref("mailnews.wraplength", 0); + +- 編輯你的Thunderbird配置設置，使它不要使用"format=flowed"格式：user_pref("mailnews. + send_plaintext_flowed", false); + +- 你需要使Thunderbird變爲預先格式方式： + 如果默認情況下你書寫的是HTML格式，那不是很難。僅僅從標題欄的下拉框中選擇"Preformat"格式。 + 如果默認情況下你書寫的是文本格式，你不得把它改爲HTML格式（僅僅作爲一次性的）來書寫新的消息， + 然後強制使它回到文本格式，否則它就會拆行。要實現它，在寫信的圖標上使用shift鍵來使它變爲HTML + 格式，然後標題欄的下拉框中選擇"Preformat"格式。 + +- 允許使用外部的編輯器： + 針對Thunderbird打補丁最簡單的方法就是使用一個"external editor"擴展，然後使用你最喜歡的 + $EDITOR來讀取或者合併補丁到文本中。要實現它，可以下載並且安裝這個擴展，然後添加一個使用它的 + 按鍵View->Toolbars->Customize...最後當你書寫信息的時候僅僅點擊它就可以了。 + +TkRat (GUI) +~~~~~~~~~~~ + +可以使用它。使用"Insert file..."或者外部的編輯器。 + +Gmail (Web GUI) +~~~~~~~~~~~~~~~ + +不要使用它發送補丁。 + +Gmail網頁客戶端自動地把制表符轉換爲空格。 + +雖然制表符轉換爲空格問題可以被外部編輯器解決，同時它還會使用回車換行把每行拆分爲78個字符。 + +另一個問題是Gmail還會把任何不是ASCII的字符的信息改爲base64編碼。它把東西變的像歐洲人的名字。 + + ### + diff --git a/Documentation/translations/zh_TW/process/embargoed-hardware-issues.rst b/Documentation/translations/zh_TW/process/embargoed-hardware-issues.rst new file mode 100644 index 000000000000..6c76fc96131a --- /dev/null +++ b/Documentation/translations/zh_TW/process/embargoed-hardware-issues.rst @@ -0,0 +1,232 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. include:: ../disclaimer-zh_TW.rst + +:Original: :ref:`Documentation/process/embargoed-hardware-issues.rst <embargoed_hardware_issues>` +:Translator: Alex Shi <alex.shi@linux.alibaba.com> + Hu Haowen <src.res@email.cn> + +被限制的硬體問題 +================ + +範圍 +---- + +導致安全問題的硬體問題與只影響Linux內核的純軟體錯誤是不同的安全錯誤類別。 + +必須區別對待諸如熔毀(Meltdown)、Spectre、L1TF等硬體問題，因爲它們通常會影響 +所有作業系統（「OS」），因此需要在不同的OS供應商、發行版、硬體供應商和其他各方 +之間進行協調。對於某些問題，軟體緩解可能依賴於微碼或固件更新，這需要進一步的 +協調。 + +.. _tw_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:`tw_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_TW/process/howto.rst b/Documentation/translations/zh_TW/process/howto.rst new file mode 100644 index 000000000000..2043691b92e3 --- /dev/null +++ b/Documentation/translations/zh_TW/process/howto.rst @@ -0,0 +1,500 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. _tw_process_howto: + +.. include:: ../disclaimer-zh_TW.rst + +:Original: :ref:`Documentation/process/howto.rst <process_howto>` + +譯者:: + + 英文版維護者： Greg Kroah-Hartman <greg@kroah.com> + 中文版維護者： 李陽 Li Yang <leoyang.li@nxp.com> + 中文版翻譯者： 李陽 Li Yang <leoyang.li@nxp.com> + 時奎亮 Alex Shi <alex.shi@linux.alibaba.com> + 中文版校譯者: + 鍾宇 TripleX Chung <xxx.phy@gmail.com> + 陳琦 Maggie Chen <chenqi@beyondsoft.com> + 王聰 Wang Cong <xiyou.wangcong@gmail.com> + 胡皓文 Hu Haowen <src.res@email.cn> + +如何參與Linux內核開發 +===================== + +這是一篇將如何參與Linux內核開發的相關問題一網打盡的終極祕笈。它將指導你 +成爲一名Linux內核開發者，並且學會如何同Linux內核開發社區合作。它儘可能不 +包括任何關於內核編程的技術細節，但會給你指引一條獲得這些知識的正確途徑。 + +如果這篇文章中的任何內容不再適用，請給文末列出的文件維護者發送補丁。 + + +入門 +---- + +你想了解如何成爲一名Linux內核開發者？或者老闆吩咐你「給這個設備寫個Linux +驅動程序」？這篇文章的目的就是教會你達成這些目標的全部訣竅，它將描述你需 +要經過的流程以及給出如何同內核社區合作的一些提示。它還將試圖解釋內核社區 +爲何這樣運作。 + +Linux內核大部分是由C語言寫成的，一些體系結構相關的代碼用到了彙編語言。要 +參與內核開發，你必須精通C語言。除非你想爲某個架構開發底層代碼，否則你並 +不需要了解（任何體系結構的）彙編語言。下面列舉的書籍雖然不能替代紮實的C +語言教育和多年的開發經驗，但如果需要的話，做爲參考還是不錯的： + + - "The C Programming Language" by Kernighan and Ritchie [Prentice Hall] + 《C程序設計語言（第2版·新版）》（徐寶文 李志 譯）[機械工業出版社] + - "Practical C Programming" by Steve Oualline [O'Reilly] + 《實用C語言編程（第三版）》（郭大海 譯）[中國電力出版社] + - "C: A Reference Manual" by Harbison and Steele [Prentice Hall] + 《C語言參考手冊（原書第5版）》（邱仲潘 等譯）[機械工業出版社] + +Linux內核使用GNU C和GNU工具鏈開發。雖然它遵循ISO C89標準，但也用到了一些 +標準中沒有定義的擴展。內核是自給自足的C環境，不依賴於標準C庫的支持，所以 +並不支持C標準中的部分定義。比如long long類型的大數除法和浮點運算就不允許 +使用。有時候確實很難弄清楚內核對工具鏈的要求和它所使用的擴展，不幸的是目 +前還沒有明確的參考資料可以解釋它們。請查閱gcc信息頁（使用「info gcc」命令 +顯示）獲得一些這方面信息。 + +請記住你是在學習怎麼和已經存在的開發社區打交道。它由一羣形形色色的人組成， +他們對代碼、風格和過程有著很高的標準。這些標準是在長期實踐中總結出來的， +適應於地理上分散的大型開發團隊。它們已經被很好得整理成檔，建議你在開發 +之前儘可能多的學習這些標準，而不要期望別人來適應你或者你公司的行爲方式。 + + +法律問題 +-------- + +Linux內核原始碼都是在GPL（通用公共許可證）的保護下發布的。要了解這種許可 +的細節請查看原始碼主目錄下的COPYING文件。Linux內核許可準則和如何使用 +`SPDX <https://spdx.org/>` 標誌符說明在這個文件中 +:ref:`Documentation/translations/zh_TW/process/license-rules.rst <tw_kernel_licensing>` +如果你對它還有更深入問題請聯繫律師，而不要在Linux內核郵件組上提問。因爲 +郵件組裡的人並不是律師，不要期望他們的話有法律效力。 + +對於GPL的常見問題和解答，請訪問以下連結： + https://www.gnu.org/licenses/gpl-faq.html + + +文檔 +---- + +Linux內核代碼中包含有大量的文檔。這些文檔對於學習如何與內核社區互動有著 +不可估量的價值。當一個新的功能被加入內核，最好把解釋如何使用這個功能的文 +檔也放進內核。當內核的改動導致面向用戶空間的接口發生變化時，最好將相關信 +息或手冊頁(manpages)的補丁發到mtk.manpages@gmail.com，以向手冊頁(manpages) +的維護者解釋這些變化。 + +以下是內核代碼中需要閱讀的文檔： + :ref:`Documentation/admin-guide/README.rst <readme>` + 文件簡要介紹了Linux內核的背景，並且描述了如何配置和編譯內核。內核的 + 新用戶應該從這裡開始。 + + + :ref:`Documentation/process/changes.rst <changes>` + 文件給出了用來編譯和使用內核所需要的最小軟體包列表。 + + :ref:`Documentation/translations/zh_TW/process/coding-style.rst <tw_codingstyle>` + 描述Linux內核的代碼風格和理由。所有新代碼需要遵守這篇文檔中定義的規 + 范。大多數維護者只會接收符合規定的補丁，很多人也只會幫忙檢查符合風格 + 的代碼。 + + :ref:`Documentation/translations/zh_TW/process/submitting-patches.rst <tw_submittingpatches>` + :ref:`Documentation/process/submitting-drivers.rst <submittingdrivers>` + + 這兩份文檔明確描述如何創建和發送補丁，其中包括（但不僅限於)： + - 郵件內容 + - 郵件格式 + - 選擇收件人 + + 遵守這些規定並不能保證提交成功（因爲所有補丁需要通過嚴格的內容和風格 + 審查），但是忽視他們幾乎就意味著失敗。 + + 其他關於如何正確地生成補丁的優秀文檔包括： + "The Perfect Patch" + + https://www.ozlabs.org/~akpm/stuff/tpp.txt + + "Linux kernel patch submission format" + + https://web.archive.org/web/20180829112450/http://linux.yyz.us/patch-format.html + + :ref:`Documentation/translations/zh_TW/process/stable-api-nonsense.rst <tw_stable_api_nonsense>` + 論證內核爲什麼特意不包括穩定的內核內部API，也就是說不包括像這樣的特 + 性： + + - 子系統中間層（爲了兼容性？） + - 在不同作業系統間易於移植的驅動程序 + - 減緩（甚至阻止）內核代碼的快速變化 + + 這篇文檔對於理解Linux的開發哲學至關重要。對於將開發平台從其他操作系 + 統轉移到Linux的人來說也很重要。 + + :ref:`Documentation/admin-guide/security-bugs.rst <securitybugs>` + 如果你認爲自己發現了Linux內核的安全性問題，請根據這篇文檔中的步驟來 + 提醒其他內核開發者並幫助解決這個問題。 + + :ref:`Documentation/translations/zh_TW/process/management-style.rst <tw_managementstyle>` + + 描述內核維護者的工作方法及其共有特點。這對於剛剛接觸內核開發（或者對 + 它感到好奇）的人來說很重要，因爲它解釋了很多對於內核維護者獨特行爲的 + 普遍誤解與迷惑。 + + :ref:`Documentation/process/stable-kernel-rules.rst <stable_kernel_rules>` + 解釋了穩定版內核發布的規則，以及如何將改動放入這些版本的步驟。 + + :ref:`Documentation/process/kernel-docs.rst <kernel_docs>` + 有助於內核開發的外部文檔列表。如果你在內核自帶的文檔中沒有找到你想找 + 的內容，可以查看這些文檔。 + + :ref:`Documentation/process/applying-patches.rst <applying_patches>` + 關於補丁是什麼以及如何將它打在不同內核開發分支上的好介紹 + +內核還擁有大量從代碼自動生成或者從 ReStructuredText(ReST) 標記生成的文檔， +比如這個文檔，它包含內核內部API的全面介紹以及如何妥善處理加鎖的規則。所有 +這些文檔都可以通過運行以下命令從內核代碼中生成爲PDF或HTML文檔:: + + make pdfdocs + make htmldocs + +ReST格式的文檔會生成在 Documentation/output. 目錄中。 +它們也可以用下列命令生成 LaTeX 和 ePub 格式文檔:: + + make latexdocs + make epubdocs + +如何成爲內核開發者 +------------------ +如果你對Linux內核開發一無所知，你應該訪問「Linux內核新手」計劃： + + https://kernelnewbies.org + +它擁有一個可以問各種最基本的內核開發問題的郵件列表（在提問之前一定要記得 +查找已往的郵件，確認是否有人已經回答過相同的問題）。它還擁有一個可以獲得 +實時反饋的IRC聊天頻道，以及大量對於學習Linux內核開發相當有幫助的文檔。 + +網站簡要介紹了原始碼組織結構、子系統劃分以及目前正在進行的項目（包括內核 +中的和單獨維護的）。它還提供了一些基本的幫助信息，比如如何編譯內核和打補 +丁。 + +如果你想加入內核開發社區並協助完成一些任務，卻找不到從哪裡開始，可以訪問 +「Linux內核房管員」計劃： + + https://kernelnewbies.org/KernelJanitors + +這是極佳的起點。它提供一個相對簡單的任務列表，列出內核代碼中需要被重新 +整理或者改正的地方。通過和負責這個計劃的開發者們一同工作，你會學到將補丁 +集成進內核的基本原理。如果還沒有決定下一步要做什麼的話，你還可能會得到方 +向性的指點。 + +在真正動手修改內核代碼之前，理解要修改的代碼如何運作是必需的。要達到這個 +目的，沒什麼辦法比直接讀代碼更有效了（大多數花招都會有相應的注釋），而且 +一些特製的工具還可以提供幫助。例如，「Linux代碼交叉引用」項目就是一個值得 +特別推薦的幫助工具，它將原始碼顯示在有編目和索引的網頁上。其中一個更新及 +時的內核源碼庫，可以通過以下地址訪問： + + https://elixir.bootlin.com/ + + +開發流程 +-------- + +目前Linux內核開發流程包括幾個「主內核分支」和很多子系統相關的內核分支。這 +些分支包括： + + - Linus 的內核源碼樹 + - 多個主要版本的穩定版內核樹 + - 子系統相關的內核樹 + - linux-next 集成測試樹 + + +主線樹 +------ +主線樹是由Linus Torvalds 維護的。你可以在https://kernel.org 網站或者代碼 +庫中下找到它。它的開發遵循以下步驟： + + - 每當一個新版本的內核被發布，爲期兩周的集成窗口將被打開。在這段時間裡 + 維護者可以向Linus提交大段的修改，通常這些修改已經被放到-mm內核中幾個 + 星期了。提交大量修改的首選方式是使用git工具（內核的代碼版本管理工具 + ，更多的信息可以在 https://git-scm.com/ 獲取），不過使用普通補丁也是 + 可以的。 + - 兩個星期以後-rc1版本內核發布。之後只有不包含可能影響整個內核穩定性的 + 新功能的補丁才可能被接受。請注意一個全新的驅動程序（或者文件系統）有 + 可能在-rc1後被接受是因爲這樣的修改完全獨立，不會影響其他的代碼，所以 + 沒有造成內核退步的風險。在-rc1以後也可以用git向Linus提交補丁，不過所 + 有的補丁需要同時被發送到相應的公衆郵件列表以徵詢意見。 + - 當Linus認爲當前的git源碼樹已經達到一個合理健全的狀態足以發布供人測試 + 時，一個新的-rc版本就會被發布。計劃是每周都發布新的-rc版本。 + - 這個過程一直持續下去直到內核被認爲達到足夠穩定的狀態，持續時間大概是 + 6個星期。 + +關於內核發布，值得一提的是Andrew Morton在linux-kernel郵件列表中如是說： + 「沒有人知道新內核何時會被發布，因爲發布是根據已知bug的情況來決定 + 的，而不是根據一個事先制定好的時間表。」 + +子系統特定樹 +------------ + +各種內核子系統的維護者——以及許多內核子系統開發人員——在原始碼庫中公開了他們 +當前的開發狀態。這樣，其他人就可以看到內核的不同區域發生了什麼。在開發速度 +很快的領域，可能會要求開發人員將提交的內容建立在這樣的子系統內核樹上，這樣 +就避免了提交與其他已經進行的工作之間的衝突。 + +這些存儲庫中的大多數都是Git樹，但是也有其他的scm在使用，或者補丁隊列被發布 +爲Quilt系列。這些子系統存儲庫的地址列在MAINTAINERS文件中。其中許多可以在 +https://git.kernel.org/上瀏覽。 + +在將一個建議的補丁提交到這樣的子系統樹之前，需要對它進行審查，審查主要發生 +在郵件列表上（請參見下面相應的部分）。對於幾個內核子系統，這個審查過程是通 +過工具補丁跟蹤的。Patchwork提供了一個Web界面，顯示補丁發布、對補丁的任何評 +論或修訂，維護人員可以將補丁標記爲正在審查、接受或拒絕。大多數補丁網站都列 +在 https://patchwork.kernel.org/ + +Linux-next 集成測試樹 +--------------------- + +在將子系統樹的更新合併到主線樹之前，需要對它們進行集成測試。爲此，存在一個 +特殊的測試存儲庫，其中幾乎每天都會提取所有子系統樹： + + https://git.kernel.org/？p=linux/kernel/git/next/linux-next.git + +通過這種方式，Linux-next 對下一個合併階段將進入主線內核的內容給出了一個概要 +展望。非常歡冒險的測試者運行測試Linux-next。 + +多個主要版本的穩定版內核樹 +----------------------------------- +由3個數字組成的內核版本號說明此內核是-stable版本。它們包含內核的相對較小且 +至關重要的修補，這些修補針對安全性問題或者嚴重的內核退步。 + +這種版本的內核適用於那些期望獲得最新的穩定版內核並且不想參與測試開發版或 +者實驗版的用戶。 + +穩定版內核樹版本由「穩定版」小組（郵件地址<stable@vger.kernel.org>）維護，一般 +隔周發布新版本。 + +內核源碼中的 :ref:`Documentation/process/stable-kernel-rules.rst <stable_kernel_rules>` +文件具體描述了可被穩定版內核接受的修改類型以及發布的流程。 + + +報告bug +------- + +bugzilla.kernel.org是Linux內核開發者們用來跟蹤內核Bug的網站。我們鼓勵用 +戶在這個工具中報告找到的所有bug。如何使用內核bugzilla的細節請訪問： + + http://test.kernel.org/bugzilla/faq.html + +內核源碼主目錄中的:ref:`admin-guide/reporting-bugs.rst <reportingbugs>` +文件里有一個很好的模板。它指導用戶如何報告可能的內核bug以及需要提供哪些信息 +來幫助內核開發者們找到問題的根源。 + + +利用bug報告 +----------- + +練習內核開發技能的最好辦法就是修改其他人報告的bug。你不光可以幫助內核變 +得更加穩定，還可以學會如何解決實際問題從而提高自己的技能，並且讓其他開發 +者感受到你的存在。修改bug是贏得其他開發者讚譽的最好辦法，因爲並不是很多 +人都喜歡浪費時間去修改別人報告的bug。 + +要嘗試修改已知的bug，請訪問 http://bugzilla.kernel.org 網址。 + + +郵件列表 +-------- + +正如上面的文檔所描述，大多數的骨幹內核開發者都加入了Linux Kernel郵件列 +表。如何訂閱和退訂列表的細節可以在這裡找到： + + http://vger.kernel.org/vger-lists.html#linux-kernel + +網上很多地方都有這個郵件列表的存檔(archive)。可以使用搜尋引擎來找到這些 +存檔。比如： + + http://dir.gmane.org/gmane.linux.kernel + +在發信之前，我們強烈建議你先在存檔中搜索你想要討論的問題。很多已經被詳細 +討論過的問題只在郵件列表的存檔中可以找到。 + +大多數內核子系統也有自己獨立的郵件列表來協調各自的開發工作。從 +MAINTAINERS文件中可以找到不同話題對應的郵件列表。 + +很多郵件列表架設在kernel.org伺服器上。這些列表的信息可以在這裡找到： + + http://vger.kernel.org/vger-lists.html + +在使用這些郵件列表時，請記住保持良好的行爲習慣。下面的連結提供了與這些列 +表（或任何其它郵件列表）交流的一些簡單規則，雖然內容有點濫竽充數。 + + http://www.albion.com/netiquette/ + +當有很多人回覆你的郵件時，郵件的抄送列表會變得很長。請不要將任何人從抄送 +列表中刪除，除非你有足夠的理由這麼做。也不要只回復到郵件列表。請習慣於同 +一封郵件接收兩次（一封來自發送者一封來自郵件列表），而不要試圖通過添加一 +些奇特的郵件頭來解決這個問題，人們不會喜歡的。 + +記住保留你所回復內容的上下文和源頭。在你回覆郵件的頂部保留「某某某說到……」 +這幾行。將你的評論加在被引用的段落之間而不要放在郵件的頂部。 + +如果你在郵件中附帶補丁，請確認它們是可以直接閱讀的純文本（如 +:ref:`Documentation/translations/zh_TW/process/submitting-patches.rst <tw_submittingpatches>` +文檔中所述）。內核開發者們不希望遇到附件或者被壓縮了的補丁。只有這樣才能 +保證他們可以直接評論你的每行代碼。請確保你使用的郵件發送程序不會修改空格 +和制表符。一個防範性的測試方法是先將郵件發送給自己，然後自己嘗試是否可以 +順利地打上收到的補丁。如果測試不成功，請調整或者更換你的郵件發送程序直到 +它正確工作爲止。 + +總而言之，請尊重其他的郵件列表訂閱者。 + + +同內核社區合作 +---------------- + +內核社區的目標就是提供盡善盡美的內核。所以當你提交補丁期望被接受進內核的 +時候，它的技術價值以及其他方面都將被評審。那麼你可能會得到什麼呢？ + + - 批評 + - 評論 + - 要求修改 + - 要求證明修改的必要性 + - 沉默 + +要記住，這些是把補丁放進內核的正常情況。你必須學會聽取對補丁的批評和評論， +從技術層面評估它們，然後要麼重寫你的補丁要麼簡明扼要地論證修改是不必要 +的。如果你發的郵件沒有得到任何回應，請過幾天後再試一次，因爲有時信件會湮 +沒在茫茫信海中。 + +你不應該做的事情： + + - 期望自己的補丁不受任何質疑就直接被接受 + - 翻臉 + - 忽略別人的評論 + - 沒有按照別人的要求做任何修改就重新提交 + +在一個努力追尋最好技術方案的社區里，對於一個補丁有多少好處總會有不同的見 +解。你必須要抱著合作的態度，願意改變自己的觀點來適應內核的風格。或者至少 +願意去證明你的想法是有價值的。記住，犯錯誤是允許的，只要你願意朝著正確的 +方案去努力。 + +如果你的第一個補丁換來的是一堆修改建議，這是很正常的。這並不代表你的補丁 +不會被接受，也不意味著有人和你作對。你只需要改正所有提出的問題然後重新發 +送你的補丁。 + +內核社區和公司文化的差異 +------------------------ + +內核社區的工作模式同大多數傳統公司開發隊伍的工作模式並不相同。下面這些例 +子，可以幫助你避免某些可能發生問題： +用這些話介紹你的修改提案會有好處： + + - 它同時解決了多個問題 + - 它刪除了2000行代碼 + - 這是補丁，它已經解釋了我想要說明的 + - 我在5種不同的體系結構上測試過它…… + - 這是一系列小補丁用來…… + - 這個修改提高了普通機器的性能…… + +應該避免如下的說法： + + - 我們在AIX/ptx/Solaris就是這麼做的，所以這麼做肯定是好的…… + - 我做這行已經20年了，所以…… + - 爲了我們公司賺錢考慮必須這麼做 + - 這是我們的企業產品線所需要的 + - 這裡是描述我觀點的1000頁設計文檔 + - 這是一個5000行的補丁用來…… + - 我重寫了現在亂七八糟的代碼，這就是…… + - 我被規定了最後期限，所以這個補丁需要立刻被接受 + +另外一個內核社區與大部分傳統公司的軟體開發隊伍不同的地方是無法面對面地交 +流。使用電子郵件和IRC聊天工具做爲主要溝通工具的一個好處是性別和種族歧視 +將會更少。Linux內核的工作環境更能接受婦女和少數族羣，因爲每個人在別人眼 +里只是一個郵件地址。國際化也幫助了公平的實現，因爲你無法通過姓名來判斷人 +的性別。男人有可能叫李麗，女人也有可能叫王剛。大多數在Linux內核上工作過 +並表達過看法的女性對在linux上工作的經歷都給出了正面的評價。 + +對於一些不習慣使用英語的人來說，語言可能是一個引起問題的障礙。在郵件列表 +中要正確地表達想法必需良好地掌握語言，所以建議你在發送郵件之前最好檢查一 +下英文寫得是否正確。 + + +拆分修改 +-------- + +Linux內核社區並不喜歡一下接收大段的代碼。修改需要被恰當地介紹、討論並且 +拆分成獨立的小段。這幾乎完全和公司中的習慣背道而馳。你的想法應該在開發最 +開始的階段就讓大家知道，這樣你就可以及時獲得對你正在進行的開發的反饋。這 +樣也會讓社區覺得你是在和他們協作，而不是僅僅把他們當作傾銷新功能的對象。 +無論如何，你不要一次性地向郵件列表發送50封信，你的補丁序列應該永遠用不到 +這麼多。 + +將補丁拆開的原因如下： + +1) 小的補丁更有可能被接受，因爲它們不需要太多的時間和精力去驗證其正確性。 + 一個5行的補丁，可能在維護者看了一眼以後就會被接受。而500行的補丁則 + 需要數個小時來審查其正確性（所需時間隨補丁大小增加大約呈指數級增長）。 + + 當出了問題的時候，小的補丁也會讓調試變得非常容易。一個一個補丁地回溯 + 將會比仔細剖析一個被打上的大補丁（這個補丁破壞了其他東西）容易得多。 + +2）不光發送小的補丁很重要，在提交之前重新編排、化簡（或者僅僅重新排列） + 補丁也是很重要的。 + +這裡有內核開發者Al Viro打的一個比方： + 「想像一個老師正在給學生批改數學作業。老師並不希望看到學生爲了得 + 到正確解法所進行的嘗試和產生的錯誤。他希望看到的是最乾淨最優雅的 + 解答。好學生了解這點，絕不會把最終解決之前的中間方案提交上去。」 + + 內核開發也是這樣。維護者和評審者不希望看到一個人在解決問題時的思 + 考過程。他們只希望看到簡單和優雅的解決方案。 + +直接給出一流的解決方案，和社區一起協作討論尚未完成的工作，這兩者之間似乎 +很難找到一個平衡點。所以最好儘早開始收集有利於你進行改進的反饋；同時也要 +保證修改分成很多小塊，這樣在整個項目都準備好被包含進內核之前，其中的一部 +分可能會先被接收。 + +必須了解這樣做是不可接受的：試圖將未完成的工作提交進內核，然後再找時間修 +復。 + + +證明修改的必要性 +---------------- +除了將補丁拆成小塊，很重要的一點是讓Linux社區了解他們爲什麼需要這樣修改。 +你必須證明新功能是有人需要的並且是有用的。 + + +記錄修改 +-------- + +當你發送補丁的時候，需要特別留意郵件正文的內容。因爲這裡的信息將會做爲補 +丁的修改記錄(ChangeLog)，會被一直保留以備大家查閱。它需要完全地描述補丁， +包括： + + - 爲什麼需要這個修改 + - 補丁的總體設計 + - 實現細節 + - 測試結果 + +想了解它具體應該看起來像什麼，請查閱以下文檔中的「ChangeLog」章節： + 「The Perfect Patch」 + https://www.ozlabs.org/~akpm/stuff/tpp.txt + + +這些事情有時候做起來很難。要在任何方面都做到完美可能需要好幾年時間。這是 +一個持續提高的過程，它需要大量的耐心和決心。只要不放棄，你一定可以做到。 +很多人已經做到了，而他們都曾經和現在的你站在同樣的起點上。 + + +感謝 +---- +感謝Paolo Ciarrocchi允許「開發流程」部分基於他所寫的文章 +(http://www.kerneltravel.net/newbie/2.6-development_process)，感謝Randy +Dunlap和Gerrit Huizenga完善了應該說和不該說的列表。感謝Pat Mochel, Hanna +Linder, Randy Dunlap, Kay Sievers, Vojtech Pavlik, Jan Kara, Josh Boyer, +Kees Cook, Andrew Morton, Andi Kleen, Vadim Lobanov, Jesper Juhl, Adrian +Bunk, Keri Harris, Frans Pop, David A. Wheeler, Junio Hamano, Michael +Kerrisk和Alex Shepard的評審、建議和貢獻。沒有他們的幫助，這篇文檔是不可 +能完成的。 + + + +英文版維護者： Greg Kroah-Hartman <greg@kroah.com> + diff --git a/Documentation/translations/zh_TW/process/index.rst b/Documentation/translations/zh_TW/process/index.rst new file mode 100644 index 000000000000..ec7ad14bfd13 --- /dev/null +++ b/Documentation/translations/zh_TW/process/index.rst @@ -0,0 +1,67 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. raw:: latex + + \renewcommand\thesection* + \renewcommand\thesubsection* + +.. include:: ../disclaimer-zh_TW.rst + +:Original: :ref:`Documentation/process/index.rst <process_index>` +:Translator: Alex Shi <alex.shi@linux.alibaba.com> + Hu Haowen <src.res@email.cn> + +.. _tw_process_index: + +與Linux 內核社區一起工作 +======================== + +你想成爲Linux內核開發人員嗎？歡迎之至！在學習許多關於內核的技術知識的同時， +了解我們社區的工作方式也很重要。閱讀這些文檔可以讓您以更輕鬆的、麻煩更少的 +方式將更改合併到內核。 + +以下是每位開發人員都應閱讀的基本指南： + +.. toctree:: + :maxdepth: 1 + + howto + code-of-conduct + code-of-conduct-interpretation + submitting-patches + programming-language + coding-style + development-process + email-clients + license-rules + kernel-enforcement-statement + kernel-driver-statement + +其它大多數開發人員感興趣的社區指南： + + +.. toctree:: + :maxdepth: 1 + + submitting-drivers + submit-checklist + stable-api-nonsense + stable-kernel-rules + management-style + embargoed-hardware-issues + +這些是一些總體性技術指南，由於不大好分類而放在這裡： + +.. toctree:: + :maxdepth: 1 + + magic-number + volatile-considered-harmful + +.. only:: subproject and html + + 目錄 + ==== + + * :ref:`genindex` + diff --git a/Documentation/translations/zh_TW/process/kernel-driver-statement.rst b/Documentation/translations/zh_TW/process/kernel-driver-statement.rst new file mode 100644 index 000000000000..8f225379b12c --- /dev/null +++ b/Documentation/translations/zh_TW/process/kernel-driver-statement.rst @@ -0,0 +1,203 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. _zh_process_statement_driver: + +.. include:: ../disclaimer-zh_TW.rst + +:Original: :ref:`Documentation/process/kernel-driver-statement.rst <process_statement_driver>` +:Translator: Alex Shi <alex.shi@linux.alibaba.com> + Hu Haowen <src.res@email.cn> + +內核驅動聲明 +------------ + +關於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_TW/process/kernel-enforcement-statement.rst b/Documentation/translations/zh_TW/process/kernel-enforcement-statement.rst new file mode 100644 index 000000000000..99e21d22800d --- /dev/null +++ b/Documentation/translations/zh_TW/process/kernel-enforcement-statement.rst @@ -0,0 +1,155 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. _tw_process_statement_kernel: + +.. include:: ../disclaimer-zh_TW.rst + +:Original: :ref:`Documentation/process/kernel-enforcement-statement.rst <process_statement_kernel>` +:Translator: Alex Shi <alex.shi@linux.alibaba.com> + Hu Haowen <src.res@email.cn> + +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/translations/zh_TW/process/license-rules.rst b/Documentation/translations/zh_TW/process/license-rules.rst new file mode 100644 index 000000000000..ad2b80f97123 --- /dev/null +++ b/Documentation/translations/zh_TW/process/license-rules.rst @@ -0,0 +1,374 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. SPDX-License-Identifier: GPL-2.0 + +.. include:: ../disclaimer-zh_TW.rst + +:Original: :ref:`Documentation/process/license-rules.rst <kernel_licensing>` +:Translator: Alex Shi <alex.shi@linux.alibaba.com> + Hu Haowen <src.res@email.cn> + +.. _tw_kernel_licensing: + +Linux內核許可規則 +================= + +Linux內核根據LICENSES/preferred/GPL-2.0中提供的GNU通用公共許可證版本2 +（GPL-2.0）的條款提供，並在LICENSES/exceptions/Linux-syscall-note中顯式 +描述了例外的系統調用，如COPYING文件中所述。 + +此文檔文件提供了如何對每個源文件進行注釋以使其許可證清晰明確的說明。 +它不會取代內核的許可證。 + +內核原始碼作爲一個整體適用於COPYING文件中描述的許可證，但是單個源文件可以 +具有不同的與GPL-20兼容的許可證:: + + GPL-1.0+ : GNU通用公共許可證v1.0或更高版本 + GPL-2.0+ : GNU通用公共許可證v2.0或更高版本 + LGPL-2.0 : 僅限GNU庫通用公共許可證v2 + LGPL-2.0+: GNU 庫通用公共許可證v2或更高版本 + LGPL-2.1 : 僅限GNU寬通用公共許可證v2.1 + LGPL-2.1+: GNU寬通用公共許可證v2.1或更高版本 + +除此之外，個人文件可以在雙重許可下提供，例如一個兼容的GPL變體，或者BSD， +MIT等許可。 + +用戶空間API（UAPI）頭文件描述了用戶空間程序與內核的接口，這是一種特殊情況。 +根據內核COPYING文件中的注釋，syscall接口是一個明確的邊界，它不會將GPL要求 +擴展到任何使用它與內核通信的軟體。由於UAPI頭文件必須包含在創建在Linux內核 +上運行的可執行文件的任何源文件中，因此此例外必須記錄在特別的許可證表述中。 + +表達源文件許可證的常用方法是將匹配的樣板文本添加到文件的頂部注釋中。由於 +格式，拼寫錯誤等，這些「樣板」很難通過那些在上下文中使用的驗證許可證合規性 +的工具。 + +樣板文本的替代方法是在每個源文件中使用軟體包數據交換（SPDX）許可證標識符。 +SPDX許可證標識符是機器可解析的，並且是用於提供文件內容的許可證的精確縮寫。 +SPDX許可證標識符由Linux 基金會的SPDX 工作組管理，並得到了整個行業，工具 +供應商和法律團隊的合作夥伴的一致同意。有關詳細信息，請參閱 +https://spdx.org/ + +Linux內核需要所有源文件中的精確SPDX標識符。內核中使用的有效標識符在 +`許可標識符`_ 一節中進行了解釋，並且已可以在 +https://spdx.org/licenses/ 上的官方SPDX許可證列表中檢索，並附帶許可證 +文本。 + +許可標識符語法 +-------------- + +1.安置: + + 內核文件中的SPDX許可證標識符應添加到可包含注釋的文件中的第一行。對於大多 + 數文件，這是第一行，除了那些在第一行中需要'#!PATH_TO_INTERPRETER'的腳本。 + 對於這些腳本，SPDX標識符進入第二行。 + +| + +2. 風格: + + SPDX許可證標識符以注釋的形式添加。注釋樣式取決於文件類型:: + + C source: // SPDX-License-Identifier: <SPDX License Expression> + C header: /* SPDX-License-Identifier: <SPDX License Expression> */ + ASM: /* SPDX-License-Identifier: <SPDX License Expression> */ + scripts: # SPDX-License-Identifier: <SPDX License Expression> + .rst: .. SPDX-License-Identifier: <SPDX License Expression> + .dts{i}: // SPDX-License-Identifier: <SPDX License Expression> + + 如果特定工具無法處理標準注釋樣式，則應使用工具接受的相應注釋機制。這是在 + C 頭文件中使用「/\*\*/」樣式注釋的原因。過去在使用生成的.lds文件中觀察到 + 構建被破壞，其中'ld'無法解析C++注釋。現在已經解決了這個問題，但仍然有較 + 舊的彙編程序工具無法處理C++樣式的注釋。 + +| + +3. 句法: + + <SPDX許可證表達式>是SPDX許可證列表中的SPDX短格式許可證標識符，或者在許可 + 證例外適用時由「WITH」分隔的兩個SPDX短格式許可證標識符的組合。當應用多個許 + 可證時，表達式由分隔子表達式的關鍵字「AND」，「OR」組成，並由「（」，「）」包圍。 + + 帶有「或更高」選項的[L]GPL等許可證的許可證標識符通過使用「+」來表示「或更高」 + 選項來構建。:: + + // SPDX-License-Identifier: GPL-2.0+ + // SPDX-License-Identifier: LGPL-2.1+ + + 當需要修正的許可證時，應使用WITH。 例如，linux內核UAPI文件使用表達式:: + + // SPDX-License-Identifier: GPL-2.0 WITH Linux-syscall-note + // SPDX-License-Identifier: GPL-2.0+ WITH Linux-syscall-note + + 其它在內核中使用WITH例外的事例如下:: + + // SPDX-License-Identifier: GPL-2.0 WITH mif-exception + // SPDX-License-Identifier: GPL-2.0+ WITH GCC-exception-2.0 + + 例外只能與特定的許可證標識符一起使用。有效的許可證標識符列在異常文本文件 + 的標記中。有關詳細信息，請參閱 `許可標識符`_ 一章中的 `例外`_ 。 + + 如果文件是雙重許可且只選擇一個許可證，則應使用OR。例如，一些dtsi文件在雙 + 許可下可用:: + + // SPDX-License-Identifier: GPL-2.0 OR BSD-3-Clause + + 內核中雙許可文件中許可表達式的示例:: + + // SPDX-License-Identifier: GPL-2.0 OR MIT + // SPDX-License-Identifier: GPL-2.0 OR BSD-2-Clause + // SPDX-License-Identifier: GPL-2.0 OR Apache-2.0 + // SPDX-License-Identifier: GPL-2.0 OR MPL-1.1 + // SPDX-License-Identifier: (GPL-2.0 WITH Linux-syscall-note) OR MIT + // SPDX-License-Identifier: GPL-1.0+ OR BSD-3-Clause OR OpenSSL + + 如果文件具有多個許可證，其條款全部適用於使用該文件，則應使用AND。例如， + 如果代碼是從另一個項目繼承的，並且已經授予了將其放入內核的權限，但原始 + 許可條款需要保持有效:: + + // SPDX-License-Identifier: (GPL-2.0 WITH Linux-syscall-note) AND MIT + + 另一個需要遵守兩套許可條款的例子是:: + + // SPDX-License-Identifier: GPL-1.0+ AND LGPL-2.1+ + +許可標識符 +---------- + +當前使用的許可證以及添加到內核的代碼許可證可以分解爲： + +1. _`優先許可`: + + 應儘可能使用這些許可證，因爲它們已知完全兼容並廣泛使用。這些許可證在內核 + 目錄:: + + LICENSES/preferred/ + + 此目錄中的文件包含完整的許可證文本和 `元標記`_ 。文件名與SPDX許可證標識 + 符相同，後者應用於源文件中的許可證。 + + 例如:: + + LICENSES/preferred/GPL-2.0 + + 包含GPLv2許可證文本和所需的元標籤:: + + LICENSES/preferred/MIT + + 包含MIT許可證文本和所需的元標記 + + _`元標記`: + + 許可證文件中必須包含以下元標記： + + - Valid-License-Identifier: + + 一行或多行, 聲明那些許可標識符在項目內有效, 以引用此特定許可的文本。通 + 常這是一個有效的標識符，但是例如對於帶有'或更高'選項的許可證，兩個標識 + 符都有效。 + + - SPDX-URL: + + SPDX頁面的URL，其中包含與許可證相關的其他信息. + + - Usage-Guidance: + + 使用建議的自由格式文本。該文本必須包含SPDX許可證標識符的正確示例，因爲 + 它們應根據 `許可標識符語法`_ 指南放入源文件中。 + + - License-Text: + + 此標記之後的所有文本都被視爲原始許可文本 + + 文件格式示例:: + + Valid-License-Identifier: GPL-2.0 + Valid-License-Identifier: GPL-2.0+ + SPDX-URL: https://spdx.org/licenses/GPL-2.0.html + Usage-Guide: + To use this license in source code, put one of the following SPDX + tag/value pairs into a comment according to the placement + guidelines in the licensing rules documentation. + For 'GNU General Public License (GPL) version 2 only' use: + SPDX-License-Identifier: GPL-2.0 + For 'GNU General Public License (GPL) version 2 or any later version' use: + SPDX-License-Identifier: GPL-2.0+ + License-Text: + Full license text + + :: + + SPDX-License-Identifier: MIT + SPDX-URL: https://spdx.org/licenses/MIT.html + Usage-Guide: + To use this license in source code, put the following SPDX + tag/value pair into a comment according to the placement + guidelines in the licensing rules documentation. + SPDX-License-Identifier: MIT + License-Text: + Full license text + +| + +2. 不推薦的許可證: + + 這些許可證只應用於現有代碼或從其他項目導入代碼。這些許可證在內核目錄:: + + LICENSES/other/ + + 此目錄中的文件包含完整的許可證文本和 `元標記`_ 。文件名與SPDX許可證標識 + 符相同，後者應用於源文件中的許可證。 + + 例如:: + + LICENSES/other/ISC + + 包含國際系統聯合許可文本和所需的元標籤:: + + LICENSES/other/ZLib + + 包含ZLIB許可文本和所需的元標籤. + + 元標籤: + + 「其他」許可證的元標籤要求與 `優先許可`_ 的要求相同。 + + 文件格式示例:: + + Valid-License-Identifier: ISC + SPDX-URL: https://spdx.org/licenses/ISC.html + Usage-Guide: + Usage of this license in the kernel for new code is discouraged + and it should solely be used for importing code from an already + existing project. + To use this license in source code, put the following SPDX + tag/value pair into a comment according to the placement + guidelines in the licensing rules documentation. + SPDX-License-Identifier: ISC + License-Text: + Full license text + +| + +3. _`例外`: + + 某些許可證可以修改，並允許原始許可證不具有的某些例外權利。這些例外在 + 內核目錄:: + + LICENSES/exceptions/ + + 此目錄中的文件包含完整的例外文本和所需的 `例外元標記`_ 。 + + 例如:: + + LICENSES/exceptions/Linux-syscall-note + + 包含Linux內核的COPYING文件中記錄的Linux系統調用例外，該文件用於UAPI + 頭文件。例如:: + + LICENSES/exceptions/GCC-exception-2.0 + + 包含GCC'連結例外'，它允許獨立於其許可證的任何二進位文件與標記有此例外的 + 文件的編譯版本連結。這是從GPL不兼容原始碼創建可運行的可執行文件所必需的。 + + _`例外元標記`: + + 以下元標記必須在例外文件中可用： + + - SPDX-Exception-Identifier: + + 一個可與SPDX許可證標識符一起使用的例外標識符。 + + - SPDX-URL: + + SPDX頁面的URL，其中包含與例外相關的其他信息。 + + - SPDX-Licenses: + + 以逗號分隔的例外可用的SPDX許可證標識符列表。 + + - Usage-Guidance: + + 使用建議的自由格式文本。必須在文本後面加上SPDX許可證標識符的正確示例， + 因爲它們應根據 `許可標識符語法`_ 指南放入源文件中。 + + - Exception-Text: + + 此標記之後的所有文本都被視爲原始異常文本 + + 文件格式示例:: + + SPDX-Exception-Identifier: Linux-syscall-note + SPDX-URL: https://spdx.org/licenses/Linux-syscall-note.html + SPDX-Licenses: GPL-2.0, GPL-2.0+, GPL-1.0+, LGPL-2.0, LGPL-2.0+, LGPL-2.1, LGPL-2.1+ + Usage-Guidance: + This exception is used together with one of the above SPDX-Licenses + to mark user-space API (uapi) header files so they can be included + into non GPL compliant user-space application code. + To use this exception add it with the keyword WITH to one of the + identifiers in the SPDX-Licenses tag: + SPDX-License-Identifier: <SPDX-License> WITH Linux-syscall-note + Exception-Text: + Full exception text + + :: + + SPDX-Exception-Identifier: GCC-exception-2.0 + SPDX-URL: https://spdx.org/licenses/GCC-exception-2.0.html + SPDX-Licenses: GPL-2.0, GPL-2.0+ + Usage-Guidance: + The "GCC Runtime Library exception 2.0" is used together with one + of the above SPDX-Licenses for code imported from the GCC runtime + library. + To use this exception add it with the keyword WITH to one of the + identifiers in the SPDX-Licenses tag: + SPDX-License-Identifier: <SPDX-License> WITH GCC-exception-2.0 + Exception-Text: + Full exception text + + +所有SPDX許可證標識符和例外都必須在LICENSES子目錄中具有相應的文件。這是允許 +工具驗證（例如checkpatch.pl）以及準備好從源讀取和提取許可證所必需的, 這是 +各種FOSS組織推薦的，例如 `FSFE REUSE initiative <https://reuse.software/>`_. + +_`模塊許可` +----------------- + + 可加載內核模塊還需要MODULE_LICENSE（）標記。此標記既不替代正確的原始碼 + 許可證信息（SPDX-License-Identifier），也不以任何方式表示或確定提供模塊 + 原始碼的確切許可證。 + + 此標記的唯一目的是提供足夠的信息，該模塊是否是自由軟體或者是內核模塊加 + 載器和用戶空間工具的專有模塊。 + + MODULE_LICENSE（）的有效許可證字符串是: + + ============================= ============================================= + "GPL" 模塊是根據GPL版本2許可的。這並不表示僅限於 + GPL-2.0或GPL-2.0或更高版本之間的任何區別。 + 最正確許可證信息只能通過相應源文件中的許可證 + 信息來確定 + + "GPL v2" 和"GPL"相同，它的存在是因爲歷史原因。 + + "GPL and additional rights" 表示模塊源在GPL v2變體和MIT許可下雙重許可的 + 歷史變體。請不要在新代碼中使用。 + + "Dual MIT/GPL" 表達該模塊在GPL v2變體或MIT許可證選擇下雙重 + 許可的正確方式。 + + "Dual BSD/GPL" 該模塊根據GPL v2變體或BSD許可證選擇進行雙重 + 許可。 BSD許可證的確切變體只能通過相應源文件 + 中的許可證信息來確定。 + + "Dual MPL/GPL" 該模塊根據GPL v2變體或Mozilla Public License + （MPL）選項進行雙重許可。 MPL許可證的確切變體 + 只能通過相應的源文件中的許可證信息來確定。 + + "Proprietary" 該模塊屬於專有許可。此字符串僅用於專有的第三 + 方模塊，不能用於在內核樹中具有原始碼的模塊。 + 以這種方式標記的模塊在加載時會使用'P'標記汙 + 染內核，並且內核模塊加載器拒絕將這些模塊連結 + 到使用EXPORT_SYMBOL_GPL（）導出的符號。 + ============================= ============================================= + + diff --git a/Documentation/translations/zh_TW/process/magic-number.rst b/Documentation/translations/zh_TW/process/magic-number.rst new file mode 100644 index 000000000000..ae321a9aaece --- /dev/null +++ b/Documentation/translations/zh_TW/process/magic-number.rst @@ -0,0 +1,148 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. _tw_magicnumbers: + +.. include:: ../disclaimer-zh_TW.rst + +:Original: :ref:`Documentation/process/magic-number.rst <magicnumbers>` + +如果想評論或更新本文的內容，請直接發信到LKML。如果你使用英文交流有困難的話，也可 +以向中文版維護者求助。如果本翻譯更新不及時或者翻譯存在問題，請聯繫中文版維護者:: + + 中文版維護者： 賈威威 Jia Wei Wei <harryxiyou@gmail.com> + 中文版翻譯者： 賈威威 Jia Wei Wei <harryxiyou@gmail.com> + 中文版校譯者： 賈威威 Jia Wei Wei <harryxiyou@gmail.com> + 胡皓文 Hu Haowen <src.res@email.cn> + +Linux 魔術數 +============ + +這個文件是有關當前使用的魔術值註冊表。當你給一個結構添加了一個魔術值，你也應該把這個魔術值添加到這個文件，因爲我們最好把用於各種結構的魔術值統一起來。 + +使用魔術值來保護內核數據結構是一個非常好的主意。這就允許你在運行期檢查(a)一個結構是否已經被攻擊，或者(b)你已經給一個例行程序通過了一個錯誤的結構。後一種情況特別地有用---特別是當你通過一個空指針指向結構體的時候。tty源碼，例如，經常通過特定驅動使用這種方法並且反覆地排列特定方面的結構。 + +使用魔術值的方法是在結構的開始處聲明的，如下:: + + struct tty_ldisc { + int magic; + ... + }; + +當你以後給內核添加增強功能的時候，請遵守這條規則！這樣就會節省數不清的調試時間，特別是一些古怪的情況，例如，數組超出範圍並且重新寫了超出部分。遵守這個規則，這些情況可以被快速地，安全地避免。 + + Theodore Ts'o + 31 Mar 94 + +給當前的Linux 2.1.55添加魔術表。 + + Michael Chastain + <mailto:mec@shout.net> + 22 Sep 1997 + +現在應該最新的Linux 2.1.112.因爲在特性凍結期間，不能在2.2.x前改變任何東西。這些條目被數域所排序。 + + Krzysztof G.Baranowski + <mailto: kgb@knm.org.pl> + 29 Jul 1998 + +更新魔術表到Linux 2.5.45。剛好越過特性凍結，但是有可能還會有一些新的魔術值在2.6.x之前融入到內核中。 + + Petr Baudis + <pasky@ucw.cz> + 03 Nov 2002 + +更新魔術表到Linux 2.5.74。 + + Fabian Frederick + <ffrederick@users.sourceforge.net> + 09 Jul 2003 + +===================== ================ ======================== ========================================== +魔術數名 數字 結構 文件 +===================== ================ ======================== ========================================== +PG_MAGIC 'P' pg_{read,write}_hdr ``include/linux/pg.h`` +CMAGIC 0x0111 user ``include/linux/a.out.h`` +MKISS_DRIVER_MAGIC 0x04bf mkiss_channel ``drivers/net/mkiss.h`` +HDLC_MAGIC 0x239e n_hdlc ``drivers/char/n_hdlc.c`` +APM_BIOS_MAGIC 0x4101 apm_user ``arch/x86/kernel/apm_32.c`` +DB_MAGIC 0x4442 fc_info ``drivers/net/iph5526_novram.c`` +DL_MAGIC 0x444d fc_info ``drivers/net/iph5526_novram.c`` +FASYNC_MAGIC 0x4601 fasync_struct ``include/linux/fs.h`` +FF_MAGIC 0x4646 fc_info ``drivers/net/iph5526_novram.c`` +PTY_MAGIC 0x5001 ``drivers/char/pty.c`` +PPP_MAGIC 0x5002 ppp ``include/linux/if_pppvar.h`` +SSTATE_MAGIC 0x5302 serial_state ``include/linux/serial.h`` +SLIP_MAGIC 0x5302 slip ``drivers/net/slip.h`` +STRIP_MAGIC 0x5303 strip ``drivers/net/strip.c`` +SIXPACK_MAGIC 0x5304 sixpack ``drivers/net/hamradio/6pack.h`` +AX25_MAGIC 0x5316 ax_disp ``drivers/net/mkiss.h`` +TTY_MAGIC 0x5401 tty_struct ``include/linux/tty.h`` +MGSL_MAGIC 0x5401 mgsl_info ``drivers/char/synclink.c`` +TTY_DRIVER_MAGIC 0x5402 tty_driver ``include/linux/tty_driver.h`` +MGSLPC_MAGIC 0x5402 mgslpc_info ``drivers/char/pcmcia/synclink_cs.c`` +USB_SERIAL_MAGIC 0x6702 usb_serial ``drivers/usb/serial/usb-serial.h`` +FULL_DUPLEX_MAGIC 0x6969 ``drivers/net/ethernet/dec/tulip/de2104x.c`` +USB_BLUETOOTH_MAGIC 0x6d02 usb_bluetooth ``drivers/usb/class/bluetty.c`` +RFCOMM_TTY_MAGIC 0x6d02 ``net/bluetooth/rfcomm/tty.c`` +USB_SERIAL_PORT_MAGIC 0x7301 usb_serial_port ``drivers/usb/serial/usb-serial.h`` +CG_MAGIC 0x00090255 ufs_cylinder_group ``include/linux/ufs_fs.h`` +LSEMAGIC 0x05091998 lse ``drivers/fc4/fc.c`` +GDTIOCTL_MAGIC 0x06030f07 gdth_iowr_str ``drivers/scsi/gdth_ioctl.h`` +RIEBL_MAGIC 0x09051990 ``drivers/net/atarilance.c`` +NBD_REQUEST_MAGIC 0x12560953 nbd_request ``include/linux/nbd.h`` +RED_MAGIC2 0x170fc2a5 (any) ``mm/slab.c`` +BAYCOM_MAGIC 0x19730510 baycom_state ``drivers/net/baycom_epp.c`` +ISDN_X25IFACE_MAGIC 0x1e75a2b9 isdn_x25iface_proto_data ``drivers/isdn/isdn_x25iface.h`` +ECP_MAGIC 0x21504345 cdkecpsig ``include/linux/cdk.h`` +LSOMAGIC 0x27091997 lso ``drivers/fc4/fc.c`` +LSMAGIC 0x2a3b4d2a ls ``drivers/fc4/fc.c`` +WANPIPE_MAGIC 0x414C4453 sdla_{dump,exec} ``include/linux/wanpipe.h`` +CS_CARD_MAGIC 0x43525553 cs_card ``sound/oss/cs46xx.c`` +LABELCL_MAGIC 0x4857434c labelcl_info_s ``include/asm/ia64/sn/labelcl.h`` +ISDN_ASYNC_MAGIC 0x49344C01 modem_info ``include/linux/isdn.h`` +CTC_ASYNC_MAGIC 0x49344C01 ctc_tty_info ``drivers/s390/net/ctctty.c`` +ISDN_NET_MAGIC 0x49344C02 isdn_net_local_s ``drivers/isdn/i4l/isdn_net_lib.h`` +SAVEKMSG_MAGIC2 0x4B4D5347 savekmsg ``arch/*/amiga/config.c`` +CS_STATE_MAGIC 0x4c4f4749 cs_state ``sound/oss/cs46xx.c`` +SLAB_C_MAGIC 0x4f17a36d kmem_cache ``mm/slab.c`` +COW_MAGIC 0x4f4f4f4d cow_header_v1 ``arch/um/drivers/ubd_user.c`` +I810_CARD_MAGIC 0x5072696E i810_card ``sound/oss/i810_audio.c`` +TRIDENT_CARD_MAGIC 0x5072696E trident_card ``sound/oss/trident.c`` +ROUTER_MAGIC 0x524d4157 wan_device [in ``wanrouter.h`` pre 3.9] +SAVEKMSG_MAGIC1 0x53415645 savekmsg ``arch/*/amiga/config.c`` +GDA_MAGIC 0x58464552 gda ``arch/mips/include/asm/sn/gda.h`` +RED_MAGIC1 0x5a2cf071 (any) ``mm/slab.c`` +EEPROM_MAGIC_VALUE 0x5ab478d2 lanai_dev ``drivers/atm/lanai.c`` +HDLCDRV_MAGIC 0x5ac6e778 hdlcdrv_state ``include/linux/hdlcdrv.h`` +PCXX_MAGIC 0x5c6df104 channel ``drivers/char/pcxx.h`` +KV_MAGIC 0x5f4b565f kernel_vars_s ``arch/mips/include/asm/sn/klkernvars.h`` +I810_STATE_MAGIC 0x63657373 i810_state ``sound/oss/i810_audio.c`` +TRIDENT_STATE_MAGIC 0x63657373 trient_state ``sound/oss/trident.c`` +M3_CARD_MAGIC 0x646e6f50 m3_card ``sound/oss/maestro3.c`` +FW_HEADER_MAGIC 0x65726F66 fw_header ``drivers/atm/fore200e.h`` +SLOT_MAGIC 0x67267321 slot ``drivers/hotplug/cpqphp.h`` +SLOT_MAGIC 0x67267322 slot ``drivers/hotplug/acpiphp.h`` +LO_MAGIC 0x68797548 nbd_device ``include/linux/nbd.h`` +M3_STATE_MAGIC 0x734d724d m3_state ``sound/oss/maestro3.c`` +VMALLOC_MAGIC 0x87654320 snd_alloc_track ``sound/core/memory.c`` +KMALLOC_MAGIC 0x87654321 snd_alloc_track ``sound/core/memory.c`` +PWC_MAGIC 0x89DC10AB pwc_device ``drivers/usb/media/pwc.h`` +NBD_REPLY_MAGIC 0x96744668 nbd_reply ``include/linux/nbd.h`` +ENI155_MAGIC 0xa54b872d midway_eprom ``drivers/atm/eni.h`` +CODA_MAGIC 0xC0DAC0DA coda_file_info ``fs/coda/coda_fs_i.h`` +DPMEM_MAGIC 0xc0ffee11 gdt_pci_sram ``drivers/scsi/gdth.h`` +YAM_MAGIC 0xF10A7654 yam_port ``drivers/net/hamradio/yam.c`` +CCB_MAGIC 0xf2691ad2 ccb ``drivers/scsi/ncr53c8xx.c`` +QUEUE_MAGIC_FREE 0xf7e1c9a3 queue_entry ``drivers/scsi/arm/queue.c`` +QUEUE_MAGIC_USED 0xf7e1cc33 queue_entry ``drivers/scsi/arm/queue.c`` +HTB_CMAGIC 0xFEFAFEF1 htb_class ``net/sched/sch_htb.c`` +NMI_MAGIC 0x48414d4d455201 nmi_s ``arch/mips/include/asm/sn/nmi.h`` +===================== ================ ======================== ========================================== + + +請注意，在聲音記憶管理中仍然有一些特殊的爲每個驅動定義的魔術值。查看include/sound/sndmagic.h來獲取他們完整的列表信息。很多OSS聲音驅動擁有自己從音效卡PCI ID構建的魔術值-他們也沒有被列在這裡。 + +IrDA子系統也使用了大量的自己的魔術值，查看include/net/irda/irda.h來獲取他們完整的信息。 + +HFS是另外一個比較大的使用魔術值的文件系統-你可以在fs/hfs/hfs.h中找到他們。 + diff --git a/Documentation/translations/zh_TW/process/management-style.rst b/Documentation/translations/zh_TW/process/management-style.rst new file mode 100644 index 000000000000..dce248470063 --- /dev/null +++ b/Documentation/translations/zh_TW/process/management-style.rst @@ -0,0 +1,211 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. include:: ../disclaimer-zh_TW.rst + +:Original: :ref:`Documentation/process/management-style.rst <managementstyle>` +:Translator: Alex Shi <alex.shi@linux.alibaba.com> + Hu Haowen <src.res@email.cn> + +.. _tw_managementstyle: + +Linux內核管理風格 +================= + +這是一個簡短的文檔，描述了Linux內核首選的（或胡編的，取決於您問誰）管理風格。 +它的目的是在某種程度上參照 :ref:`process/coding-style.rst <codingstyle>` +主要是爲了避免反覆回答 [#cnf1]_ 相同（或類似）的問題。 + +管理風格是非常個人化的，比簡單的編碼風格規則更難以量化，因此本文檔可能與實 +際情況有關，也可能與實際情況無關。起初它是一個玩笑，但這並不意味著它可能不 +是真的。你得自己決定。 + +順便說一句，在談到「核心管理者」時，主要是技術負責人，而不是在公司內部進行傳 +統管理的人。如果你簽署了採購訂單或者對你的團隊的預算有任何了解，你幾乎肯定 +不是一個核心管理者。這些建議可能適用於您，也可能不適用於您。 + +首先，我建議你購買「高效人的七個習慣」，而不是閱讀它。燒了它，這是一個偉大的 +象徵性姿態。 + +.. [#cnf1] 本文件並不是通過回答問題，而是通過讓提問者痛苦地明白，我們不知道 + 答案是什麼。 + +不管怎樣，這裡是： + +.. _tw_decisions: + +1）決策 +------- + +每個人都認爲管理者做決定，而且決策很重要。決定越大越痛苦，管理者就必須越高級。 +這很明顯，但事實並非如此。 + +遊戲的名字是 **避免** 做出決定。尤其是，如果有人告訴你「選擇（a）或（b）， +我們真的需要你來做決定」，你就是陷入麻煩的管理者。你管理的人比你更了解細節， +所以如果他們來找你做技術決策，你完蛋了。你顯然沒有能力爲他們做這個決定。 + +（推論：如果你管理的人不比你更了解細節，你也會被搞砸，儘管原因完全不同。 +也就是說，你的工作是錯的，他們應該管理你的才智） + +所以遊戲的名字是 **避免** 做出決定，至少是那些大而痛苦的決定。做一些小的 +和非結果性的決定是很好的，並且使您看起來好像知道自己在做什麼，所以內核管理者 +需要做的是將那些大的和痛苦的決定變成那些沒有人真正關心的小事情。 + +這有助於認識到一個大的決定和一個小的決定之間的關鍵區別是你是否可以在事後修正 +你的決定。任何決定都可以通過始終確保如果你錯了（而且你一定會錯），你以後總是 +可以通過回溯來彌補損失。突然間，你就要做兩個無關緊要的決定，一個是錯誤的，另 +一個是正確的。 + +人們甚至會認爲這是真正的領導能力（咳，胡說，咳）。 + +因此，避免重大決策的關鍵在於避免做那些無法挽回的事情。不要被引導到一個你無法 +逃離的角落。走投無路的老鼠可能很危險——走投無路的管理者真可憐。 + +事實證明，由於沒有人會愚蠢到讓內核管理者承擔巨大的財政責任，所以通常很容易 +回溯。既然你不可能浪費掉你無法償還的巨額資金，你唯一可以回溯的就是技術決策， +而回溯很容易：只要告訴大家你是個不稱職的傻瓜，說對不起，然後撤銷你去年讓別 +人所做的毫無價值的工作。突然間，你一年前做的決定不在是一個重大的決定，因爲 +它很容易被推翻。 + +事實證明，有些人對接受這種方法有困難，原因有兩個： + + - 承認你是個白癡比看起來更難。我們都喜歡保持形象，在公共場合說你錯了有時 + 確實很難。 + - 如果有人告訴你，你去年所做的工作終究是不值得的，那麼對那些可憐的低級工 + 程師來說也是很困難的，雖然實際的 **工作** 很容易刪除，但你可能已經不可 + 挽回地失去了工程師的信任。記住：「不可撤銷」是我們一開始就試圖避免的， + 而你的決定終究是一個重大的決定。 + +令人欣慰的是，這兩個原因都可以通過預先承認你沒有任何線索，提前告訴人們你的 +決定完全是初步的，而且可能是錯誤的事情來有效地緩解。你應該始終保留改變主意 +的權利，並讓人們 **意識** 到這一點。當你 **還沒有** 做過真正愚蠢的事情的時 +候，承認自己是愚蠢的要容易得多。 + +然後，當它真的被證明是愚蠢的時候，人們就轉動他們的眼珠說「哎呀，下次不要了」。 + +這種對不稱職的先發制人的承認，也可能使真正做這項工作的人也會三思是否值得做。 +畢竟，如果他們不確定這是否是一個好主意，你肯定不應該通過向他們保證他們所做 +的工作將會進入（內核）鼓勵他們。在他們開始一項巨大的努力之前，至少讓他們三 +思而後行。 + +記住：他們最好比你更了解細節，而且他們通常認爲他們對每件事都有答案。作爲一 +個管理者，你能做的最好的事情不是灌輸自信，而是對他們所做的事情進行健康的批 +判性思考。 + +順便說一句，另一種避免做出決定的方法是看起來很可憐的抱怨 「我們不能兩者兼 +得嗎？」 相信我，它是有效的。如果不清楚哪種方法更好，他們最終會弄清楚的。 +最終的答案可能是兩個團隊都會因爲這種情況而感到沮喪，以至於他們放棄了。 + +這聽起來像是一個失敗，但這通常是一個跡象，表明兩個項目都有問題，而參與其中 +的人不能做決定的原因是他們都是錯誤的。你最終會聞到玫瑰的味道，你避免了另一 +個你本可以搞砸的決定。 + +2）人 +----- + +大多數人都是白癡，做一名管理者意味著你必須處理好這件事，也許更重要的是, +**他們** 必須處理好你。 + +事實證明，雖然很容易糾正技術錯誤，但不容易糾正人格障礙。你只能和他們的和 +你的（人格障礙）共處。 + +但是，爲了做好作爲內核管理者的準備，最好記住不要燒掉任何橋樑，不要轟炸任何 +無辜的村民，也不要疏遠太多的內核開發人員。事實證明，疏遠人是相當容易的，而 +親近一個疏遠的人是很難的。因此，「疏遠」立即屬於「不可逆」的範疇，並根據 +:ref:`tw_decisions` 成爲絕不可以做的事情。 + +這裡只有幾個簡單的規則： + + (1) 不要叫人笨蛋（至少不要在公共場合） + (2) 學習如何在忘記規則(1)時道歉 + +問題在於 #1 很容易去做，因爲你可以用數百萬種不同的方式說「你是一個笨蛋」 [#cnf2]_ +有時甚至沒有意識到，而且幾乎總是帶著一種白熱化的信念，認爲你是對的。 + +你越確信自己是對的（讓我們面對現實吧，你可以把幾乎所有人都稱爲壞人，而且你 +經常是對的），事後道歉就越難。 + +要解決此問題，您實際上只有兩個選項： + + - 非常擅長道歉 + - 把「愛」均勻地散開，沒有人會真正感覺到自己被不公平地瞄準了。讓它有足夠的 + 創造性，他們甚至可能會覺得好笑。 + +選擇永遠保持禮貌是不存在的。沒有人會相信一個如此明顯地隱藏了他們真實性格的人。 + +.. [#cnf2] 保羅·西蒙演唱了「離開愛人的50種方法」，因爲坦率地說，「告訴開發者 + 他們是D*CKHEAD" 的100萬種方法都無法確認。但我確信他已經這麼想了。 + +3）人2 - 好人 +------------- + +雖然大多數人都是白癡，但不幸的是，據此推論你也是白癡，儘管我們都自我感覺良 +好，我們比普通人更好（讓我們面對現實吧，沒有人相信他們是普通人或低於普通人）， +我們也應該承認我們不是最鋒利的刀，而且會有其他人比你更不像白癡。 + +有些人對聰明人反應不好。其他人利用它們。 + +作爲內核維護人員，確保您在第二組中。接受他們，因爲他們會讓你的工作更容易。 +特別是，他們能夠爲你做決定，這就是遊戲的全部內容。 + +所以當你發現一個比你聰明的人時，就順其自然吧。你的管理職責在很大程度上變成 +了「聽起來像是個好主意——去嘗試吧」，或者「聽起來不錯，但是XXX呢？」「。第二個版 +本尤其是一個很好的方法，要麼學習一些關於「XXX」的新東西，要麼通過指出一些聰明 +人沒有想到的東西來顯得更具管理性。無論哪種情況，你都會贏。 + +要注意的一件事是認識到一個領域的偉大不一定會轉化爲其他領域。所以你可能會向 +特定的方向刺激人們，但讓我們面對現實吧，他們可能擅長他們所做的事情，而且對 +其他事情都很差勁。好消息是，人們往往會自然而然地重拾他們擅長的東西，所以當 +你向某個方向刺激他們時，你並不是在做不可逆轉的事情，只是不要用力推。 + +4）責備 +------- + +事情會出問題的，人們希望去責備人。貼標籤，你就是受責備的人。 + +事實上，接受責備並不難，尤其是當人們意識到這不 **全是** 你的過錯時。這讓我 +們找到了承擔責任的最佳方式：爲別人承擔這件事。你會感覺很好，他們會感覺很好， +沒有受到指責. 那誰，失去了他們的全部36GB色情收藏的人，因爲你的無能將勉強承 +認，你至少沒有試圖逃避責任。 + +然後讓真正搞砸了的開發人員（如果你能找到他們）私下知道他們搞砸了。不僅是爲 +了將來可以避免，而且爲了讓他們知道他們欠你一個人情。而且，也許更重要的是， +他們也可能是能夠解決問題的人。因爲，讓我們面對現實吧，肯定不是你。 + +承擔責任也是你首先成爲管理者的原因。這是讓人們信任你，讓你獲得潛在的榮耀的 +一部分，因爲你就是那個會說「我搞砸了」的人。如果你已經遵循了以前的規則，你現 +在已經很擅長說了。 + +5）應避免的事情 +--------------- + +有一件事人們甚至比被稱爲「笨蛋」更討厭，那就是在一個神聖的聲音中被稱爲「笨蛋」。 +第一個你可以道歉，第二個你不會真正得到機會。即使你做得很好，他們也可能不再 +傾聽。 + +我們都認爲自己比別人強，這意味著當別人裝腔作勢時，這會讓我們很惱火。你也許 +在道德和智力上比你周圍的每個人都優越，但不要試圖太明顯，除非你真的打算激怒 +某人 [#cnf3]_ + +同樣，不要對事情太客氣或太微妙。禮貌很容易落得落花流水，把問題隱藏起來， +正如他們所說，「在網際網路上，沒人能聽到你的含蓄。」用一個鈍器把這一點錘進去， +因爲你不能真的依靠別人來獲得你的觀點。 + +一些幽默可以幫助緩和直率和道德化。過度到荒謬的地步，可以灌輸一個觀點，而不 +會讓接受者感到痛苦，他們只是認爲你是愚蠢的。因此，它可以幫助我們擺脫對批評 +的個人心理障礙。 + +.. [#cnf3] 提示：與你的工作沒有直接關係的網絡新聞組是消除你對他人不滿的好 + 方法。偶爾寫些侮辱性的帖子，打個噴嚏，讓你的情緒得到淨化。別把牢騷帶回家 + +6）爲什麼是我？ +--------------- + +既然你的主要責任似乎是爲別人的錯誤承擔責任，並且讓別人痛苦地明白你是不稱職 +的，那麼顯而易見的問題之一就變成了爲什麼首先要這樣做。 + +首先，雖然你可能會或可能不會聽到十幾歲女孩（或男孩，讓我們不要在這裡評判或 +性別歧視）敲你的更衣室門，你會得到一個巨大的個人成就感爲「負責」。別介意你真 +的在領導別人，你要跟上別人，儘可能快地追趕他們。每個人都會認爲你是負責人。 + +如果你可以做到這個， 這是個偉大的工作！ + diff --git a/Documentation/translations/zh_TW/process/programming-language.rst b/Documentation/translations/zh_TW/process/programming-language.rst new file mode 100644 index 000000000000..54e3699eadf8 --- /dev/null +++ b/Documentation/translations/zh_TW/process/programming-language.rst @@ -0,0 +1,76 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. include:: ../disclaimer-zh_TW.rst + +:Original: :ref:`Documentation/process/programming-language.rst <programming_language>` +:Translator: Alex Shi <alex.shi@linux.alibaba.com> + Hu Haowen <src.res@email.cn> + +.. _tw_programming_language: + +程序設計語言 +============ + +內核是用C語言 :ref:`c-language <tw_c-language>` 編寫的。更準確地說，內核通常是用 :ref:`gcc <tw_gcc>` +在 ``-std=gnu89`` :ref:`gcc-c-dialect-options <tw_gcc-c-dialect-options>` 下編譯的：ISO C90的 GNU 方言（ +包括一些C99特性） + +這種方言包含對語言 :ref:`gnu-extensions <tw_gnu-extensions>` 的許多擴展，當然，它們許多都在內核中使用。 + +對於一些體系結構，有一些使用 :ref:`clang <tw_clang>` 和 :ref:`icc <tw_icc>` 編譯內核 +的支持，儘管在編寫此文檔時還沒有完成，仍需要第三方補丁。 + +屬性 +---- + +在整個內核中使用的一個常見擴展是屬性（attributes） :ref:`gcc-attribute-syntax <tw_gcc-attribute-syntax>` +屬性允許將實現定義的語義引入語言實體（如變量、函數或類型），而無需對語言進行 +重大的語法更改（例如添加新關鍵字） :ref:`n2049 <tw_n2049>` + +在某些情況下，屬性是可選的（即不支持這些屬性的編譯器仍然應該生成正確的代碼， +即使其速度較慢或執行的編譯時檢查/診斷次數不夠） + +內核定義了僞關鍵字（例如， ``pure`` ），而不是直接使用GNU屬性語法（例如, +``__attribute__((__pure__))`` ），以檢測可以使用哪些關鍵字和/或縮短代碼, 具體 +請參閱 ``include/linux/compiler_attributes.h`` + +.. _tw_c-language: + +c-language + http://www.open-std.org/jtc1/sc22/wg14/www/standards + +.. _tw_gcc: + +gcc + https://gcc.gnu.org + +.. _tw_clang: + +clang + https://clang.llvm.org + +.. _tw_icc: + +icc + https://software.intel.com/en-us/c-compilers + +.. _tw_gcc-c-dialect-options: + +c-dialect-options + https://gcc.gnu.org/onlinedocs/gcc/C-Dialect-Options.html + +.. _tw_gnu-extensions: + +gnu-extensions + https://gcc.gnu.org/onlinedocs/gcc/C-Extensions.html + +.. _tw_gcc-attribute-syntax: + +gcc-attribute-syntax + https://gcc.gnu.org/onlinedocs/gcc/Attribute-Syntax.html + +.. _tw_n2049: + +n2049 + http://www.open-std.org/jtc1/sc22/wg14/www/docs/n2049.pdf + diff --git a/Documentation/translations/zh_TW/process/stable-api-nonsense.rst b/Documentation/translations/zh_TW/process/stable-api-nonsense.rst new file mode 100644 index 000000000000..22caa5b8d422 --- /dev/null +++ b/Documentation/translations/zh_TW/process/stable-api-nonsense.rst @@ -0,0 +1,159 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. _tw_stable_api_nonsense: + +.. include:: ../disclaimer-zh_TW.rst + +:Original: :ref:`Documentation/process/stable-api-nonsense.rst + <stable_api_nonsense>` + +譯者:: + + 中文版維護者： 鍾宇 TripleX Chung <xxx.phy@gmail.com> + 中文版翻譯者： 鍾宇 TripleX Chung <xxx.phy@gmail.com> + 中文版校譯者： 李陽 Li Yang <leoyang.li@nxp.com> + 胡皓文 Hu Haowen <src.res@email.cn> + +Linux 內核驅動接口 +================== + +寫作本文檔的目的，是爲了解釋爲什麼Linux既沒有二進位內核接口，也沒有穩定 +的內核接口。這裡所說的內核接口，是指內核里的接口，而不是內核和用戶空間 +的接口。內核到用戶空間的接口，是提供給應用程式使用的系統調用，系統調用 +在歷史上幾乎沒有過變化，將來也不會有變化。我有一些老應用程式是在0.9版本 +或者更早版本的內核上編譯的，在使用2.6版本內核的Linux發布上依然用得很好 +。用戶和應用程式作者可以將這個接口看成是穩定的。 + + +執行綱要 +-------- + +你也許以爲自己想要穩定的內核接口，但是你不清楚你要的實際上不是它。你需 +要的其實是穩定的驅動程序，而你只有將驅動程序放到公版內核的原始碼樹里， +才有可能達到這個目的。而且這樣做還有很多其它好處，正是因爲這些好處使得 +Linux能成爲強壯，穩定，成熟的作業系統，這也是你最開始選擇Linux的原因。 + + +入門 +----- + +只有那些寫驅動程序的「怪人」才會擔心內核接口的改變，對廣大用戶來說，既 +看不到內核接口，也不需要去關心它。 + +首先，我不打算討論關於任何非GPL許可的內核驅動的法律問題，這些非GPL許可 +的驅動程序包括不公開原始碼，隱藏原始碼，二進位或者是用原始碼包裝，或者 +是其它任何形式的不能以GPL許可公開原始碼的驅動程序。如果有法律問題，請咨 +詢律師，我只是一個程式設計師，所以我只打算探討技術問題（不是小看法律問題， +法律問題很實際，並且需要一直關注）。 + +既然只談技術問題，我們就有了下面兩個主題：二進位內核接口和穩定的內核源 +代碼接口。這兩個問題是互相關聯的，讓我們先解決掉二進位接口的問題。 + + +二進位內核接口 +-------------- +假如我們有一個穩定的內核原始碼接口，那麼自然而然的，我們就擁有了穩定的 +二進位接口，是這樣的嗎？錯。讓我們看看關於Linux內核的幾點事實： + + - 取決於所用的C編譯器的版本，不同的內核數據結構里的結構體的對齊方 + 式會有差別，代碼中不同函數的表現形式也不一樣（函數是不是被inline + 編譯取決於編譯器行爲）。不同的函數的表現形式並不重要，但是數據 + 結構內部的對齊方式很關鍵。 + + - 取決於內核的配置選項，不同的選項會讓內核的很多東西發生改變： + + - 同一個結構體可能包含不同的成員變量 + - 有的函數可能根本不會被實現（比如編譯的時候沒有選擇SMP支持 + 一些鎖函數就會被定義成空函數）。 + - 內核使用的內存會以不同的方式對齊，這取決於不同的內核配置選 + 項。 + + - Linux可以在很多的不同體系結構的處理器上運行。在某個體系結構上編 + 譯好的二進位驅動程序，不可能在另外一個體系結構上正確的運行。 + +對於一個特定的內核，滿足這些條件並不難，使用同一個C編譯器和同樣的內核配 +置選項來編譯驅動程序模塊就可以了。這對於給一個特定Linux發布的特定版本提 +供驅動程序，是完全可以滿足需求的。但是如果你要給不同發布的不同版本都發 +布一個驅動程序，就需要在每個發布上用不同的內核設置參數都編譯一次內核， +這簡直跟噩夢一樣。而且還要注意到，每個Linux發布還提供不同的Linux內核， +這些內核都針對不同的硬體類型進行了優化（有很多種不同的處理器，還有不同 +的內核設置選項）。所以每發布一次驅動程序，都需要提供很多不同版本的內核 +模塊。 + +相信我，如果你真的要採取這種發布方式，一定會慢慢瘋掉，我很久以前就有過 +深刻的教訓... + + +穩定的內核原始碼接口 +-------------------- + +如果有人不將他的內核驅動程序，放入公版內核的原始碼樹，而又想讓驅動程序 +一直保持在最新的內核中可用，那麼這個話題將會變得沒完沒了。 +內核開發是持續而且快節奏的，從來都不會慢下來。內核開發人員在當前接口中 +找到bug，或者找到更好的實現方式。一旦發現這些，他們就很快會去修改當前的 +接口。修改接口意味著，函數名可能會改變，結構體可能被擴充或者刪減，函數 +的參數也可能發生改變。一旦接口被修改，內核中使用這些接口的地方需要同時 +修正，這樣才能保證所有的東西繼續工作。 + +舉一個例子，內核的USB驅動程序接口在USB子系統的整個生命周期中，至少經歷 +了三次重寫。這些重寫解決以下問題： + + - 把數據流從同步模式改成非同步模式，這個改動減少了一些驅動程序的 + 複雜度，提高了所有USB驅動程序的吞吐率，這樣幾乎所有的USB設備都 + 能以最大速率工作了。 + - 修改了USB核心代碼中爲USB驅動分配數據包內存的方式，所有的驅動都 + 需要提供更多的參數給USB核心，以修正了很多已經被記錄在案的死鎖。 + +這和一些封閉原始碼的作業系統形成鮮明的對比，在那些作業系統上，不得不額 +外的維護舊的USB接口。這導致了一個可能性，新的開發者依然會不小心使用舊的 +接口，以不恰當的方式編寫代碼，進而影響到作業系統的穩定性。 +在上面的例子中，所有的開發者都同意這些重要的改動，在這樣的情況下修改代 +價很低。如果Linux保持一個穩定的內核原始碼接口，那麼就得創建一個新的接口 +；舊的，有問題的接口必須一直維護，給Linux USB開發者帶來額外的工作。既然 +所有的Linux USB驅動的作者都是利用自己的時間工作，那麼要求他們去做毫無意 +義的免費額外工作，是不可能的。 +安全問題對Linux來說十分重要。一個安全問題被發現，就會在短時間內得到修 +正。在很多情況下，這將導致Linux內核中的一些接口被重寫，以從根本上避免安 +全問題。一旦接口被重寫，所有使用這些接口的驅動程序，必須同時得到修正， +以確定安全問題已經得到修復並且不可能在未來還有同樣的安全問題。如果內核 +內部接口不允許改變，那麼就不可能修復這樣的安全問題，也不可能確認這樣的 +安全問題以後不會發生。 +開發者一直在清理內核接口。如果一個接口沒有人在使用了，它就會被刪除。這 +樣可以確保內核儘可能的小，而且所有潛在的接口都會得到儘可能完整的測試 +（沒有人使用的接口是不可能得到良好的測試的）。 + + +要做什麼 +-------- + +如果你寫了一個Linux內核驅動，但是它還不在Linux原始碼樹里，作爲一個開發 +者，你應該怎麼做？爲每個發布的每個版本提供一個二進位驅動，那簡直是一個 +噩夢，要跟上永遠處於變化之中的內核接口，也是一件辛苦活。 +很簡單，讓你的驅動進入內核原始碼樹（要記得我們在談論的是以GPL許可發行 +的驅動，如果你的代碼不符合GPL，那麼祝你好運，你只能自己解決這個問題了， +你這個吸血鬼<把Andrew和Linus對吸血鬼的定義連結到這裡>）。當你的代碼加入 +公版內核原始碼樹之後，如果一個內核接口改變，你的驅動會直接被修改接口的 +那個人修改。保證你的驅動永遠都可以編譯通過，並且一直工作，你幾乎不需要 +做什麼事情。 + +把驅動放到內核原始碼樹里會有很多的好處： + + - 驅動的質量會提升，而維護成本（對原始作者來說）會下降。 + - 其他人會給驅動添加新特性。 + - 其他人會找到驅動中的bug並修復。 + - 其他人會在驅動中找到性能優化的機會。 + - 當外部的接口的改變需要修改驅動程序的時候，其他人會修改驅動程序 + - 不需要聯繫任何發行商，這個驅動會自動的隨著所有的Linux發布一起發 + 布。 + +和別的作業系統相比，Linux爲更多不同的設備提供現成的驅動，而且能在更多不 +同體系結構的處理器上支持這些設備。這個經過考驗的開發模式，必然是錯不了 +的 :) + +感謝 +---- +感謝 Randy Dunlap, Andrew Morton, David Brownell, Hanna Linder, +Robert Love, and Nishanth Aravamudan 對於本文檔早期版本的評審和建議。 + +英文版維護者： Greg Kroah-Hartman <greg@kroah.com> + diff --git a/Documentation/translations/zh_TW/process/stable-kernel-rules.rst b/Documentation/translations/zh_TW/process/stable-kernel-rules.rst new file mode 100644 index 000000000000..9bb0d9b4f3ac --- /dev/null +++ b/Documentation/translations/zh_TW/process/stable-kernel-rules.rst @@ -0,0 +1,68 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. _tw_stable_kernel_rules: + +.. include:: ../disclaimer-zh_TW.rst + +:Original: :ref:`Documentation/process/stable-kernel-rules.rst <stable_kernel_rules>` + +如果想評論或更新本文的內容，請直接聯繫原文檔的維護者。如果你使用英文 +交流有困難的話，也可以向中文版維護者求助。如果本翻譯更新不及時或者翻 +譯存在問題，請聯繫中文版維護者:: + + 中文版維護者： 鍾宇 TripleX Chung <xxx.phy@gmail.com> + 中文版翻譯者： 鍾宇 TripleX Chung <xxx.phy@gmail.com> + 中文版校譯者： + - 李陽 Li Yang <leoyang.li@nxp.com> + - Kangkai Yin <e12051@motorola.com> + - 胡皓文 Hu Haowen <src.res@email.cn> + +所有你想知道的事情 - 關於linux穩定版發布 +======================================== + +關於Linux 2.6穩定版發布，所有你想知道的事情。 + +關於哪些類型的補丁可以被接收進入穩定版代碼樹，哪些不可以的規則： +---------------------------------------------------------------- + + - 必須是顯而易見的正確，並且經過測試的。 + - 連同上下文，不能大於100行。 + - 必須只修正一件事情。 + - 必須修正了一個給大家帶來麻煩的真正的bug（不是「這也許是一個問題...」 + 那樣的東西）。 + - 必須修正帶來如下後果的問題：編譯錯誤（對被標記爲CONFIG_BROKEN的例外）， + 內核崩潰，掛起，數據損壞，真正的安全問題，或者一些類似「哦，這不 + 好」的問題。簡短的說，就是一些致命的問題。 + - 沒有「理論上的競爭條件」，除非能給出競爭條件如何被利用的解釋。 + - 不能存在任何的「瑣碎的」修正（拼寫修正，去掉多餘空格之類的）。 + - 必須被相關子系統的維護者接受。 + - 必須遵循Documentation/translations/zh_TW/process/submitting-patches.rst里的規則。 + +向穩定版代碼樹提交補丁的過程： +------------------------------ + + - 在確認了補丁符合以上的規則後，將補丁發送到stable@vger.kernel.org。 + - 如果補丁被接受到隊列里，發送者會收到一個ACK回復，如果沒有被接受，收 + 到的是NAK回復。回復需要幾天的時間，這取決於開發者的時間安排。 + - 被接受的補丁會被加到穩定版本隊列里，等待其他開發者的審查。 + - 安全方面的補丁不要發到這個列表，應該發送到security@kernel.org。 + +審查周期： +---------- + + - 當穩定版的維護者決定開始一個審查周期，補丁將被發送到審查委員會，以 + 及被補丁影響的領域的維護者（除非提交者就是該領域的維護者）並且抄送 + 到linux-kernel郵件列表。 + - 審查委員會有48小時的時間，用來決定給該補丁回復ACK還是NAK。 + - 如果委員會中有成員拒絕這個補丁，或者linux-kernel列表上有人反對這個 + 補丁，並提出維護者和審查委員會之前沒有意識到的問題，補丁會從隊列中 + 丟棄。 + - 在審查周期結束的時候，那些得到ACK回應的補丁將會被加入到最新的穩定版 + 發布中，一個新的穩定版發布就此產生。 + - 安全性補丁將從內核安全小組那裡直接接收到穩定版代碼樹中，而不是通過 + 通常的審查周期。請聯繫內核安全小組以獲得關於這個過程的更多細節。 + +審查委員會： +------------ + - 由一些自願承擔這項任務的內核開發者，和幾個非志願的組成。 + diff --git a/Documentation/translations/zh_TW/process/submit-checklist.rst b/Documentation/translations/zh_TW/process/submit-checklist.rst new file mode 100644 index 000000000000..ff2f89cba83f --- /dev/null +++ b/Documentation/translations/zh_TW/process/submit-checklist.rst @@ -0,0 +1,109 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. include:: ../disclaimer-zh_TW.rst + +:Original: :ref:`Documentation/process/submit-checklist.rst <submitchecklist>` +:Translator: Alex Shi <alex.shi@linux.alibaba.com> + Hu Haowen <src.res@email.cn> + +.. _tw_submitchecklist: + +Linux內核補丁提交清單 +~~~~~~~~~~~~~~~~~~~~~ + +如果開發人員希望看到他們的內核補丁提交更快地被接受，那麼他們應該做一些基本 +的事情。 + +這些都是在 +:ref:`Documentation/translations/zh_TW/process/submitting-patches.rst <tw_submittingpatches>` +和其他有關提交Linux內核補丁的文檔中提供的。 + +1) 如果使用工具，則包括定義/聲明該工具的文件。不要依賴於其他頭文件拉入您使用 + 的頭文件。 + +2) 乾淨的編譯： + + a) 使用適用或修改的 ``CONFIG`` 選項 ``=y``、``=m`` 和 ``=n`` 。沒有GCC + 警告/錯誤，沒有連結器警告/錯誤。 + + b) 通過allnoconfig、allmodconfig + + c) 使用 ``O=builddir`` 時可以成功編譯 + +3) 通過使用本地交叉編譯工具或其他一些構建場在多個CPU體系結構上構建。 + +4) PPC64是一種很好的交叉編譯檢查體系結構，因爲它傾向於對64位的數使用無符號 + 長整型。 + +5) 如下所述 :ref:`Documentation/translations/zh_TW/process/coding-style.rst <tw_codingstyle>`. + 檢查您的補丁是否爲常規樣式。在提交（ ``scripts/check patch.pl`` ）之前， + 使用補丁樣式檢查器檢查是否有輕微的衝突。您應該能夠處理您的補丁中存在的所有 + 違規行爲。 + +6) 任何新的或修改過的 ``CONFIG`` 選項都不會弄髒配置菜單，並默認爲關閉，除非 + 它們符合 ``Documentation/kbuild/kconfig-language.rst`` 中記錄的異常條件, + 菜單屬性：默認值. + +7) 所有新的 ``kconfig`` 選項都有幫助文本。 + +8) 已仔細審查了相關的 ``Kconfig`` 組合。這很難用測試來糾正——腦力在這裡是有 + 回報的。 + +9) 用 sparse 檢查乾淨。 + +10) 使用 ``make checkstack`` 和 ``make namespacecheck`` 並修復他們發現的任何 + 問題。 + + .. note:: + + ``checkstack`` 並沒有明確指出問題，但是任何一個在堆棧上使用超過512 + 字節的函數都可以進行更改。 + +11) 包括 :ref:`kernel-doc <kernel_doc>` 內核文檔以記錄全局內核API。（靜態函數 + 不需要，但也可以。）使用 ``make htmldocs`` 或 ``make pdfdocs`` 檢查 + :ref:`kernel-doc <kernel_doc>` 並修復任何問題。 + +12) 通過以下選項同時啓用的測試 ``CONFIG_PREEMPT``, ``CONFIG_DEBUG_PREEMPT``, + ``CONFIG_DEBUG_SLAB``, ``CONFIG_DEBUG_PAGEALLOC``, ``CONFIG_DEBUG_MUTEXES``, + ``CONFIG_DEBUG_SPINLOCK``, ``CONFIG_DEBUG_ATOMIC_SLEEP``, + ``CONFIG_PROVE_RCU`` and ``CONFIG_DEBUG_OBJECTS_RCU_HEAD`` + +13) 已經過構建和運行時測試，包括有或沒有 ``CONFIG_SMP``, ``CONFIG_PREEMPT``. + +14) 如果補丁程序影響IO/磁碟等：使用或不使用 ``CONFIG_LBDAF`` 進行測試。 + +15) 所有代碼路徑都已在啓用所有lockdep功能的情況下運行。 + +16) 所有新的/proc條目都記錄在 ``Documentation/`` + +17) 所有新的內核引導參數都記錄在 + Documentation/admin-guide/kernel-parameters.rst 中。 + +18) 所有新的模塊參數都記錄在 ``MODULE_PARM_DESC()`` + +19) 所有新的用戶空間接口都記錄在 ``Documentation/ABI/`` 中。有關詳細信息， + 請參閱 ``Documentation/ABI/README`` 。更改用戶空間接口的補丁應該抄送 + linux-api@vger.kernel.org。 + +20) 已通過至少注入slab和page分配失敗進行檢查。請參閱 ``Documentation/fault-injection/`` + 如果新代碼是實質性的，那麼添加子系統特定的故障注入可能是合適的。 + +21) 新添加的代碼已經用 ``gcc -W`` 編譯（使用 ``make EXTRA-CFLAGS=-W`` ）。這 + 將產生大量噪聲，但對於查找諸如「警告：有符號和無符號之間的比較」之類的錯誤 + 很有用。 + +22) 在它被合併到-mm補丁集中之後進行測試，以確保它仍然與所有其他排隊的補丁以 + 及VM、VFS和其他子系統中的各種更改一起工作。 + +23) 所有內存屏障例如 ``barrier()``, ``rmb()``, ``wmb()`` 都需要原始碼中的注 + 釋來解釋它們正在執行的操作及其原因的邏輯。 + +24) 如果補丁添加了任何ioctl，那麼也要更新 ``Documentation/userspace-api/ioctl/ioctl-number.rst`` + +25) 如果修改後的原始碼依賴或使用與以下 ``Kconfig`` 符號相關的任何內核API或 + 功能，則在禁用相關 ``Kconfig`` 符號和/或 ``=m`` （如果該選項可用）的情況 + 下測試以下多個構建[並非所有這些都同時存在，只是它們的各種/隨機組合]： + + ``CONFIG_SMP``, ``CONFIG_SYSFS``, ``CONFIG_PROC_FS``, ``CONFIG_INPUT``, ``CONFIG_PCI``, ``CONFIG_BLOCK``, ``CONFIG_PM``, ``CONFIG_MAGIC_SYSRQ``, + ``CONFIG_NET``, ``CONFIG_INET=n`` (但是後者伴隨 ``CONFIG_NET=y``). + diff --git a/Documentation/translations/zh_TW/process/submitting-drivers.rst b/Documentation/translations/zh_TW/process/submitting-drivers.rst new file mode 100644 index 000000000000..2fdd742318ba --- /dev/null +++ b/Documentation/translations/zh_TW/process/submitting-drivers.rst @@ -0,0 +1,164 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. _tw_submittingdrivers: + +.. include:: ../disclaimer-zh_TW.rst + +:Original: :ref:`Documentation/process/submitting-drivers.rst + <submittingdrivers>` + +如果想評論或更新本文的內容，請直接聯繫原文檔的維護者。如果你使用英文 +交流有困難的話，也可以向中文版維護者求助。如果本翻譯更新不及時或者翻 +譯存在問題，請聯繫中文版維護者:: + + 中文版維護者： 李陽 Li Yang <leoyang.li@nxp.com> + 中文版翻譯者： 李陽 Li Yang <leoyang.li@nxp.com> + 中文版校譯者： 陳琦 Maggie Chen <chenqi@beyondsoft.com> + 王聰 Wang Cong <xiyou.wangcong@gmail.com> + 張巍 Zhang Wei <wezhang@outlook.com> + 胡皓文 Hu Haowen <src.res@email.cn> + +如何向 Linux 內核提交驅動程序 +============================= + +這篇文檔將會解釋如何向不同的內核源碼樹提交設備驅動程序。請注意，如果你感 +興趣的是顯卡驅動程序，你也許應該訪問 XFree86 項目(https://www.xfree86.org/) +和／或 X.org 項目 (https://x.org)。 + +另請參閱 Documentation/translations/zh_TW/process/submitting-patches.rst 文檔。 + + +分配設備號 +---------- + +塊設備和字符設備的主設備號與從設備號是由 Linux 命名編號分配權威 LANANA（ +現在是 Torben Mathiasen）負責分配。申請的網址是 https://www.lanana.org/。 +即使不準備提交到主流內核的設備驅動也需要在這裡分配設備號。有關詳細信息， +請參閱 Documentation/admin-guide/devices.rst。 + +如果你使用的不是已經分配的設備號，那麼當你提交設備驅動的時候，它將會被強 +制分配一個新的設備號，即便這個設備號和你之前發給客戶的截然不同。 + +設備驅動的提交對象 +------------------ + +Linux 2.0: + 此內核源碼樹不接受新的驅動程序。 + +Linux 2.2: + 此內核源碼樹不接受新的驅動程序。 + +Linux 2.4: + 如果所屬的代碼領域在內核的 MAINTAINERS 文件中列有一個總維護者， + 那麼請將驅動程序提交給他。如果此維護者沒有回應或者你找不到恰當的 + 維護者，那麼請聯繫 Willy Tarreau <w@1wt.eu>。 + +Linux 2.6: + 除了遵循和 2.4 版內核同樣的規則外，你還需要在 linux-kernel 郵件 + 列表上跟蹤最新的 API 變化。向 Linux 2.6 內核提交驅動的頂級聯繫人 + 是 Andrew Morton <akpm@linux-foundation.org>。 + +決定設備驅動能否被接受的條件 +---------------------------- + +許可： 代碼必須使用 GNU 通用公開許可證 (GPL) 提交給 Linux，但是 + 我們並不要求 GPL 是唯一的許可。你或許會希望同時使用多種 + 許可證發布，如果希望驅動程序可以被其他開源社區（比如BSD） + 使用。請參考 include/linux/module.h 文件中所列出的可被 + 接受共存的許可。 + +版權： 版權所有者必須同意使用 GPL 許可。最好提交者和版權所有者 + 是相同個人或實體。否則，必需列出授權使用 GPL 的版權所有 + 人或實體，以備驗證之需。 + +接口： 如果你的驅動程序使用現成的接口並且和其他同類的驅動程序行 + 爲相似，而不是去發明無謂的新接口，那麼它將會更容易被接受。 + 如果你需要一個 Linux 和 NT 的通用驅動接口，那麼請在用 + 戶空間實現它。 + +代碼： 請使用 Documentation/process/coding-style.rst 中所描述的 Linux 代碼風 + 格。如果你的某些代碼段（例如那些與 Windows 驅動程序包共 + 享的代碼段）需要使用其他格式，而你卻只希望維護一份代碼， + 那麼請將它們很好地區分出來，並且註明原因。 + +可移植性： 請注意，指針並不永遠是 32 位的，不是所有的計算機都使用小 + 尾模式 (little endian) 存儲數據，不是所有的人都擁有浮點 + 單元，不要隨便在你的驅動程序里嵌入 x86 彙編指令。只能在 + x86 上運行的驅動程序一般是不受歡迎的。雖然你可能只有 x86 + 硬體，很難測試驅動程序在其他平台上是否可用，但是確保代碼 + 可以被輕鬆地移植卻是很簡單的。 + +清晰度： 做到所有人都能修補這個驅動程序將會很有好處，因爲這樣你將 + 會直接收到修復的補丁而不是 bug 報告。如果你提交一個試圖 + 隱藏硬體工作機理的驅動程序，那麼它將會被扔進廢紙簍。 + +電源管理： 因爲 Linux 正在被很多行動裝置和桌面系統使用，所以你的驅 + 動程序也很有可能被使用在這些設備上。它應該支持最基本的電 + 源管理，即在需要的情況下實現系統級休眠和喚醒要用到的 + .suspend 和 .resume 函數。你應該檢查你的驅動程序是否能正 + 確地處理休眠與喚醒，如果實在無法確認，請至少把 .suspend + 函數定義成返回 -ENOSYS（功能未實現）錯誤。你還應該嘗試確 + 保你的驅動在什麼都不乾的情況下將耗電降到最低。要獲得驅動 + 程序測試的指導，請參閱 + Documentation/power/drivers-testing.rst。有關驅動程序電 + 源管理問題相對全面的概述，請參閱 + Documentation/driver-api/pm/devices.rst。 + +管理： 如果一個驅動程序的作者還在進行有效的維護，那麼通常除了那 + 些明顯正確且不需要任何檢查的補丁以外，其他所有的補丁都會 + 被轉發給作者。如果你希望成爲驅動程序的聯繫人和更新者，最 + 好在代碼注釋中寫明並且在 MAINTAINERS 文件中加入這個驅動 + 程序的條目。 + +不影響設備驅動能否被接受的條件 +------------------------------ + +供應商： 由硬體供應商來維護驅動程序通常是一件好事。不過，如果源碼 + 樹里已經有其他人提供了可穩定工作的驅動程序，那麼請不要期 + 望「我是供應商」會成爲內核改用你的驅動程序的理由。理想的情 + 況是：供應商與現有驅動程序的作者合作，構建一個統一完美的 + 驅動程序。 + +作者： 驅動程序是由大的 Linux 公司研發還是由你個人編寫，並不影 + 響其是否能被內核接受。沒有人對內核源碼樹享有特權。只要你 + 充分了解內核社區，你就會發現這一點。 + + +資源列表 +-------- + +Linux 內核主源碼樹： + ftp.??.kernel.org:/pub/linux/kernel/... + ?? == 你的國家代碼，例如 "cn"、"us"、"uk"、"fr" 等等 + +Linux 內核郵件列表： + linux-kernel@vger.kernel.org + [可通過向majordomo@vger.kernel.org發郵件來訂閱] + +Linux 設備驅動程序，第三版（探討 2.6.10 版內核）： + https://lwn.net/Kernel/LDD3/ （免費版） + +LWN.net: + 每周內核開發活動摘要 - https://lwn.net/ + + 2.6 版中 API 的變更： + + https://lwn.net/Articles/2.6-kernel-api/ + + 將舊版內核的驅動程序移植到 2.6 版： + + https://lwn.net/Articles/driver-porting/ + +內核新手(KernelNewbies): + 爲新的內核開發者提供文檔和幫助 + https://kernelnewbies.org/ + +Linux USB項目： + http://www.linux-usb.org/ + +寫內核驅動的「不要」（Arjan van de Ven著）: + http://www.fenrus.org/how-to-not-write-a-device-driver-paper.pdf + +內核清潔工 (Kernel Janitor): + https://kernelnewbies.org/KernelJanitors + diff --git a/Documentation/translations/zh_TW/process/submitting-patches.rst b/Documentation/translations/zh_TW/process/submitting-patches.rst new file mode 100644 index 000000000000..cdf0b52e4a98 --- /dev/null +++ b/Documentation/translations/zh_TW/process/submitting-patches.rst @@ -0,0 +1,686 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. _tw_submittingpatches: + +.. include:: ../disclaimer-zh_TW.rst + +:Original: :ref:`Documentation/process/submitting-patches.rst <submittingpatches>` + +譯者:: + + 中文版維護者： 鍾宇 TripleX Chung <xxx.phy@gmail.com> + 中文版翻譯者： 鍾宇 TripleX Chung <xxx.phy@gmail.com> + 時奎亮 Alex Shi <alex.shi@linux.alibaba.com> + 中文版校譯者： 李陽 Li Yang <leoyang.li@nxp.com> + 王聰 Wang Cong <xiyou.wangcong@gmail.com> + 胡皓文 Hu Haowen <src.res@email.cn> + + +如何讓你的改動進入內核 +====================== + +對於想要將改動提交到 Linux 內核的個人或者公司來說，如果不熟悉「規矩」， +提交的流程會讓人畏懼。本文檔收集了一系列建議，這些建議可以大大的提高你 +的改動被接受的機會. + +以下文檔含有大量簡潔的建議， 具體請見： +:ref:`Documentation/process <development_process_main>` +同樣，:ref:`Documentation/translations/zh_TW/process/submit-checklist.rst <tw_submitchecklist>` +給出在提交代碼前需要檢查的項目的列表。如果你在提交一個驅動程序，那麼 +同時閱讀一下: +:ref:`Documentation/process/submitting-drivers.rst <submittingdrivers>` + +其中許多步驟描述了Git版本控制系統的默認行爲；如果您使用Git來準備補丁， +您將發現它爲您完成的大部分機械工作，儘管您仍然需要準備和記錄一組合理的 +補丁。一般來說，使用git將使您作爲內核開發人員的生活更輕鬆。 + + +0) 獲取當前源碼樹 +----------------- + +如果您沒有一個可以使用當前內核原始碼的存儲庫，請使用git獲取一個。您將要 +從主線存儲庫開始，它可以通過以下方式獲取:: + + git clone git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git + +但是，請注意，您可能不希望直接針對主線樹進行開發。大多數子系統維護人員運 +行自己的樹，並希望看到針對這些樹準備的補丁。請參見MAINTAINERS文件中子系 +統的 **T:** 項以查找該樹，或者簡單地詢問維護者該樹是否未在其中列出。 + +仍然可以通過tarballs下載內核版本（如下一節所述），但這是進行內核開發的 +一種困難的方式。 + +1) "diff -up" +------------- + +使用 "diff -up" 或者 "diff -uprN" 來創建補丁。 + +所有內核的改動，都是以補丁的形式呈現的，補丁由 diff(1) 生成。創建補丁的 +時候，要確認它是以 "unified diff" 格式創建的，這種格式由 diff(1) 的 '-u' +參數生成。而且，請使用 '-p' 參數，那樣會顯示每個改動所在的C函數，使得 +產生的補丁容易讀得多。補丁應該基於內核原始碼樹的根目錄，而不是裡邊的任 +何子目錄。 + +爲一個單獨的文件創建補丁，一般來說這樣做就夠了:: + + SRCTREE=linux + MYFILE=drivers/net/mydriver.c + + cd $SRCTREE + cp $MYFILE $MYFILE.orig + vi $MYFILE # make your change + cd .. + diff -up $SRCTREE/$MYFILE{.orig,} > /tmp/patch + +爲多個文件創建補丁，你可以解開一個沒有修改過的內核原始碼樹，然後和你自 +己的代碼樹之間做 diff 。例如:: + + MYSRC=/devel/linux + + tar xvfz linux-3.19.tar.gz + mv linux-3.19 linux-3.19-vanilla + diff -uprN -X linux-3.19-vanilla/Documentation/dontdiff \ + linux-3.19-vanilla $MYSRC > /tmp/patch + +"dontdiff" 是內核在編譯的時候產生的文件的列表，列表中的文件在 diff(1) +產生的補丁里會被跳過。 + +確定你的補丁里沒有包含任何不屬於這次補丁提交的額外文件。記得在用diff(1) +生成補丁之後，審閱一次補丁，以確保準確。 + +如果你的改動很散亂，你應該研究一下如何將補丁分割成獨立的部分，將改動分 +割成一系列合乎邏輯的步驟。這樣更容易讓其他內核開發者審核，如果你想你的 +補丁被接受，這是很重要的。請參閱： +:ref:`tw_split_changes` + +如果你用 ``git`` , ``git rebase -i`` 可以幫助你這一點。如果你不用 ``git``, +``quilt`` <https://savannah.nongnu.org/projects/quilt> 另外一個流行的選擇。 + +.. _tw_describe_changes: + +2) 描述你的改動 +--------------- + +描述你的問題。無論您的補丁是一行錯誤修復還是5000行新功能，都必須有一個潛在 +的問題激勵您完成這項工作。讓審稿人相信有一個問題值得解決，讓他們讀完第一段 +是有意義的。 + +描述用戶可見的影響。直接崩潰和鎖定是相當有說服力的，但並不是所有的錯誤都那麼 +明目張胆。即使在代碼審查期間發現了這個問題，也要描述一下您認爲它可能對用戶產 +生的影響。請記住，大多數Linux安裝運行的內核來自二級穩定樹或特定於供應商/產品 +的樹，只從上游精選特定的補丁，因此請包含任何可以幫助您將更改定位到下游的內容： +觸發的場景、DMESG的摘錄、崩潰描述、性能回歸、延遲尖峯、鎖定等。 + +量化優化和權衡。如果您聲稱在性能、內存消耗、堆棧占用空間或二進位大小方面有所 +改進，請包括支持它們的數字。但也要描述不明顯的成本。優化通常不是免費的，而是 +在CPU、內存和可讀性之間進行權衡；或者，探索性的工作，在不同的工作負載之間進 +行權衡。請描述優化的預期缺點，以便審閱者可以權衡成本和收益。 + +一旦問題建立起來，就要詳細地描述一下您實際在做什麼。對於審閱者來說，用簡單的 +英語描述代碼的變化是很重要的，以驗證代碼的行爲是否符合您的意願。 + +如果您將補丁描述寫在一個表單中，這個表單可以很容易地作爲「提交日誌」放入Linux +的原始碼管理系統git中，那麼維護人員將非常感謝您。見 :ref:`tw_explicit_in_reply_to`. + +每個補丁只解決一個問題。如果你的描述開始變長，這就表明你可能需要拆分你的補丁。 +請見 :ref:`tw_split_changes` + +提交或重新提交修補程序或修補程序系列時，請包括完整的修補程序說明和理由。不要 +只說這是補丁（系列）的第幾版。不要期望子系統維護人員引用更早的補丁版本或引用 +URL來查找補丁描述並將其放入補丁中。也就是說，補丁（系列）及其描述應該是獨立的。 +這對維護人員和審查人員都有好處。一些評審者可能甚至沒有收到補丁的早期版本。 + +描述你在命令語氣中的變化，例如「make xyzzy do frotz」而不是「[這個補丁]make +xyzzy do frotz」或「[我]changed xyzzy to do frotz」，就好像你在命令代碼庫改變 +它的行爲一樣。 + +如果修補程序修復了一個記錄的bug條目，請按編號和URL引用該bug條目。如果補丁來 +自郵件列表討論，請給出郵件列表存檔的URL；使用帶有 ``Message-ID`` 的 +https://lkml.kernel.org/ 重定向，以確保連結不會過時。 + +但是，在沒有外部資源的情況下，儘量讓你的解釋可理解。除了提供郵件列表存檔或 +bug的URL之外，還要總結需要提交補丁的相關討論要點。 + +如果您想要引用一個特定的提交，不要只引用提交的 SHA-1 ID。還請包括提交的一行 +摘要，以便於審閱者了解它是關於什麼的。例如:: + + Commit e21d2170f36602ae2708 ("video: remove unnecessary + platform_set_drvdata()") removed the unnecessary + platform_set_drvdata(), but left the variable "dev" unused, + delete it. + +您還應該確保至少使用前12位 SHA-1 ID. 內核存儲庫包含*許多*對象，使與較短的ID +發生衝突的可能性很大。記住，即使現在不會與您的六個字符ID發生衝突，這種情況 +可能五年後改變。 + +如果修補程序修復了特定提交中的錯誤，例如，使用 ``git bisct`` ，請使用帶有前 +12個字符SHA-1 ID 的"Fixes:"標記和單行摘要。爲了簡化不要將標記拆分爲多個， +行、標記不受分析腳本「75列換行」規則的限制。例如:: + + Fixes: 54a4f0239f2e ("KVM: MMU: make kvm_mmu_zap_page() return the number of pages it actually freed") + +下列 ``git config`` 設置可以添加讓 ``git log``, ``git show`` 漂亮的顯示格式:: + + [core] + abbrev = 12 + [pretty] + fixes = Fixes: %h (\"%s\") + +.. _tw_split_changes: + +3) 拆分你的改動 +--------------- + +將每個邏輯更改分隔成一個單獨的補丁。 + +例如，如果你的改動里同時有bug修正和性能優化，那麼把這些改動拆分到兩個或 +者更多的補丁文件中。如果你的改動包含對API的修改，並且修改了驅動程序來適 +應這些新的API，那麼把這些修改分成兩個補丁。 + +另一方面，如果你將一個單獨的改動做成多個補丁文件，那麼將它們合併成一個 +單獨的補丁文件。這樣一個邏輯上單獨的改動只被包含在一個補丁文件里。 + +如果有一個補丁依賴另外一個補丁來完成它的改動，那沒問題。簡單的在你的補 +丁描述里指出「這個補丁依賴某補丁」就好了。 + +在將您的更改劃分爲一系列補丁時，要特別注意確保內核在系列中的每個補丁之後 +都能正常構建和運行。使用 ``git bisect`` 來追蹤問題的開發者可能會在任何時 +候分割你的補丁系列；如果你在中間引入錯誤，他們不會感謝你。 + +如果你不能將補丁濃縮成更少的文件，那麼每次大約發送出15個，然後等待審查 +和集成。 + +4) 檢查你的更改風格 +------------------- + +檢查您的補丁是否存在基本樣式衝突，詳細信息可在 +:ref:`Documentation/translations/zh_TW/process/coding-style.rst <tw_codingstyle>` +中找到。如果不這樣做，只會浪費審稿人的時間，並且會導致你的補丁被拒絕，甚至 +可能沒有被閱讀。 + +一個重要的例外是在將代碼從一個文件移動到另一個文件時——在這種情況下，您不應 +該在移動代碼的同一個補丁中修改移動的代碼。這清楚地描述了移動代碼和您的更改 +的行爲。這大大有助於審查實際差異，並允許工具更好地跟蹤代碼本身的歷史。 + +在提交之前，使用補丁樣式檢查程序檢查補丁（scripts/check patch.pl）。不過， +請注意，樣式檢查程序應該被視爲一個指南，而不是作爲人類判斷的替代品。如果您 +的代碼看起來更好，但有違規行爲，那麼最好不要使用它。 + +檢查者報告三個級別： + + - ERROR：很可能出錯的事情 + - WARNING：需要仔細審查的事項 + - CHECK：需要思考的事情 + +您應該能夠判斷您的補丁中存在的所有違規行爲。 + +5) 選擇補丁收件人 +----------------- + +您應該總是在任何補丁上複製相應的子系統維護人員，以獲得他們維護的代碼；查看 +維護人員文件和原始碼修訂歷史記錄，以了解這些維護人員是誰。腳本 +scripts/get_Maintainer.pl在這個步驟中非常有用。如果您找不到正在工作的子系統 +的維護人員，那麼Andrew Morton（akpm@linux-foundation.org）將充當最後的維護 +人員。 + +您通常還應該選擇至少一個郵件列表來接收補丁集的。linux-kernel@vger.kernel.org +作爲最後一個解決辦法的列表，但是這個列表上的體積已經引起了許多開發人員的拒絕。 +在MAINTAINERS文件中查找子系統特定的列表；您的補丁可能會在那裡得到更多的關注。 +不過，請不要發送垃圾郵件到無關的列表。 + +許多與內核相關的列表託管在vger.kernel.org上；您可以在 +http://vger.kernel.org/vger-lists.html 上找到它們的列表。不過，也有與內核相關 +的列表託管在其他地方。 + +不要一次發送超過15個補丁到vger郵件列表！！！！ + +Linus Torvalds 是決定改動能否進入 Linux 內核的最終裁決者。他的 e-mail +地址是 <torvalds@linux-foundation.org> 。他收到的 e-mail 很多，所以一般 +的說，最好別給他發 e-mail。 + +如果您有修復可利用安全漏洞的補丁，請將該補丁發送到 security@kernel.org。對於 +嚴重的bug，可以考慮短期暫停以允許分銷商向用戶發布補丁；在這種情況下，顯然不應 +將補丁發送到任何公共列表。 + +修復已發布內核中嚴重錯誤的補丁程序應該指向穩定版維護人員，方法是放這樣的一行:: + + Cc: stable@vger.kernel.org + +進入補丁的簽准區（注意，不是電子郵件收件人）。除了這個文件之外，您還應該閱讀 +:ref:`Documentation/process/stable-kernel-rules.rst <stable_kernel_rules>` + +但是，請注意，一些子系統維護人員希望得出他們自己的結論，即哪些補丁應該被放到 +穩定的樹上。尤其是網絡維護人員，不希望看到單個開發人員在補丁中添加像上面這樣 +的行。 + +如果更改影響到用戶和內核接口，請向手冊頁維護人員（如維護人員文件中所列）發送 +手冊頁補丁，或至少發送更改通知，以便一些信息進入手冊頁。還應將用戶空間API +更改複製到 linux-api@vger.kernel.org。 + +對於小的補丁，你也許會CC到搜集瑣碎補丁的郵件列表(Trivial Patch Monkey) +trivial@kernel.org，那裡專門收集瑣碎的補丁。下面這樣的補丁會被看作「瑣碎的」 +補丁： + + - 文檔的拼寫修正。 + - 修正會影響到 grep(1) 的拼寫。 + - 警告信息修正(頻繁的列印無用的警告是不好的。) + - 編譯錯誤修正（代碼邏輯的確是對的，只是編譯有問題。） + - 運行時修正（只要真的修正了錯誤。） + - 移除使用了被廢棄的函數/宏的代碼(例如 check_region。) + - 聯繫方式和文檔修正。 + - 用可移植的代碼替換不可移植的代碼（即使在體系結構相關的代碼中，既然有 + - 人拷貝，只要它是瑣碎的） + - 任何文件的作者/維護者對該文件的改動（例如 patch monkey 在重傳模式下） + +(譯註，關於「瑣碎補丁」的一些說明：因爲原文的這一部分寫得比較簡單，所以不得不 +違例寫一下譯註。"trivial"這個英文單詞的本意是「瑣碎的，不重要的。」但是在這裡 +有稍微有一些變化，例如對一些明顯的NULL指針的修正，屬於運行時修正，會被歸類 +到瑣碎補丁里。雖然NULL指針的修正很重要，但是這樣的修正往往很小而且很容易得到 +檢驗，所以也被歸入瑣碎補丁。瑣碎補丁更精確的歸類應該是 +「simple, localized & easy to verify」，也就是說簡單的，局部的和易於檢驗的。 +trivial@kernel.org郵件列表的目的是針對這樣的補丁，爲提交者提供一個中心，來 +降低提交的門檻。) + +6) 沒有 MIME 編碼，沒有連結，沒有壓縮，沒有附件，只有純文本 +----------------------------------------------------------- + +Linus 和其他的內核開發者需要閱讀和評論你提交的改動。對於內核開發者來說 +，可以「引用」你的改動很重要，使用一般的 e-mail 工具，他們就可以在你的 +代碼的任何位置添加評論。 + +因爲這個原因，所有的提交的補丁都是 e-mail 中「內嵌」的。 + +.. warning:: + 如果你使用剪切-粘貼你的補丁，小心你的編輯器的自動換行功能破壞你的補丁 + +不要將補丁作爲 MIME 編碼的附件，不管是否壓縮。很多流行的 e-mail 軟體不 +是任何時候都將 MIME 編碼的附件當作純文本發送的，這會使得別人無法在你的 +代碼中加評論。另外，MIME 編碼的附件會讓 Linus 多花一點時間來處理，這就 +降低了你的改動被接受的可能性。 + +例外：如果你的郵遞員弄壞了補丁，那麼有人可能會要求你使用mime重新發送補丁 + +請參閱 :ref:`Documentation/translations/zh_TW/process/email-clients.rst <tw_email_clients>` +以獲取有關配置電子郵件客戶端以使其不受影響地發送修補程序的提示。 + +7) e-mail 的大小 +---------------- + +大的改動對郵件列表不合適，對某些維護者也不合適。如果你的補丁，在不壓縮 +的情況下，超過了300kB，那麼你最好將補丁放在一個能通過 internet 訪問的服 +務器上，然後用指向你的補丁的 URL 替代。但是請注意，如果您的補丁超過了 +300kb，那麼它幾乎肯定需要被破壞。 + +8）回複評審意見 +--------------- + +你的補丁幾乎肯定會得到評審者對補丁改進方法的評論。您必須對這些評論作出 +回應；讓補丁被忽略的一個好辦法就是忽略審閱者的意見。不會導致代碼更改的 +意見或問題幾乎肯定會帶來注釋或變更日誌的改變，以便下一個評審者更好地了解 +正在發生的事情。 + +一定要告訴審稿人你在做什麼改變，並感謝他們的時間。代碼審查是一個累人且 +耗時的過程，審查人員有時會變得暴躁。即使在這種情況下，也要禮貌地回應並 +解決他們指出的問題。 + +9）不要洩氣或不耐煩 +------------------- + +提交更改後，請耐心等待。審閱者是忙碌的人，可能無法立即訪問您的修補程序。 + +曾幾何時，補丁曾在沒有評論的情況下消失在空白中，但開發過程比現在更加順利。 +您應該在一周左右的時間內收到評論；如果沒有收到評論，請確保您已將補丁發送 +到正確的位置。在重新提交或聯繫審閱者之前至少等待一周-在諸如合併窗口之類的 +繁忙時間可能更長。 + +10）主題中包含 PATCH +-------------------- + +由於到linus和linux內核的電子郵件流量很高，通常會在主題行前面加上[PATCH] +前綴. 這使Linus和其他內核開發人員更容易將補丁與其他電子郵件討論區分開。 + +11）簽署你的作品-開發者原始認證 +------------------------------- + +爲了加強對誰做了何事的追蹤，尤其是對那些透過好幾層的維護者的補丁，我們 +建議在發送出去的補丁上加一個 「sign-off」 的過程。 + +"sign-off" 是在補丁的注釋的最後的簡單的一行文字，認證你編寫了它或者其他 +人有權力將它作爲開放原始碼的補丁傳遞。規則很簡單：如果你能認證如下信息: + +開發者來源證書 1.1 +^^^^^^^^^^^^^^^^^^ + +對於本項目的貢獻，我認證如下信息： + + （a）這些貢獻是完全或者部分的由我創建，我有權利以文件中指出 + 的開放原始碼許可證提交它；或者 + （b）這些貢獻基於以前的工作，據我所知，這些以前的工作受恰當的開放 + 原始碼許可證保護，而且，根據許可證，我有權提交修改後的貢獻， + 無論是完全還是部分由我創造，這些貢獻都使用同一個開放原始碼許可證 + （除非我被允許用其它的許可證），正如文件中指出的；或者 + （c）這些貢獻由認證（a），（b）或者（c）的人直接提供給我，而 + 且我沒有修改它。 + （d）我理解並同意這個項目和貢獻是公開的，貢獻的記錄（包括我 + 一起提交的個人記錄，包括 sign-off ）被永久維護並且可以和這個項目 + 或者開放原始碼的許可證同步地再發行。 + +那麼加入這樣一行:: + + Signed-off-by: Random J Developer <random@developer.example.org> + +使用你的真名（抱歉，不能使用假名或者匿名。） + +有人在最後加上標籤。現在這些東西會被忽略，但是你可以這樣做，來標記公司 +內部的過程，或者只是指出關於 sign-off 的一些特殊細節。 + +如果您是子系統或分支維護人員，有時需要稍微修改收到的補丁，以便合併它們， +因爲樹和提交者中的代碼不完全相同。如果你嚴格遵守規則（c），你應該要求提交者 +重新發布，但這完全是在浪費時間和精力。規則（b）允許您調整代碼，但是更改一個 +提交者的代碼並讓他認可您的錯誤是非常不禮貌的。要解決此問題，建議在最後一個 +由簽名行和您的行之間添加一行，指示更改的性質。雖然這並不是強制性的，但似乎 +在描述前加上您的郵件和/或姓名（全部用方括號括起來），這足以讓人注意到您對最 +後一分鐘的更改負有責任。例如:: + + Signed-off-by: Random J Developer <random@developer.example.org> + [lucky@maintainer.example.org: struct foo moved from foo.c to foo.h] + Signed-off-by: Lucky K Maintainer <lucky@maintainer.example.org> + +如果您維護一個穩定的分支機構，同時希望對作者進行致謝、跟蹤更改、合併修復並 +保護提交者不受投訴，那麼這種做法尤其有用。請注意，在任何情況下都不能更改作者 +的ID（From 頭），因爲它是出現在更改日誌中的標識。 + +對回合（back-porters）的特別說明：在提交消息的頂部（主題行之後）插入一個補丁 +的起源指示似乎是一種常見且有用的實踐，以便於跟蹤。例如，下面是我們在3.x穩定 +版本中看到的內容:: + + Date: Tue Oct 7 07:26:38 2014 -0400 + + libata: Un-break ATA blacklist + + commit 1c40279960bcd7d52dbdf1d466b20d24b99176c8 upstream. + +還有， 這裡是一個舊版內核中的一個回合補丁:: + + Date: Tue May 13 22:12:27 2008 +0200 + + wireless, airo: waitbusy() won't delay + + [backport of 2.6 commit b7acbdfbd1f277c1eb23f344f899cfa4cd0bf36a] + +12）何時使用Acked-by:，CC:，和Co-Developed by: +---------------------------------------------- + +Singed-off-by: 標記表示簽名者參與了補丁的開發，或者他/她在補丁的傳遞路徑中。 + +如果一個人沒有直接參與補丁的準備或處理，但希望表示並記錄他們對補丁的批准， +那麼他們可以要求在補丁的變更日誌中添加一個 Acked-by: + +Acked-by：通常由受影響代碼的維護者使用，當該維護者既沒有貢獻也沒有轉發補丁時。 + +Acked-by: 不像簽字人那樣正式。這是一個記錄，確認人至少審查了補丁，並表示接受。 +因此，補丁合併有時會手動將Acker的「Yep，looks good to me」轉換爲 Acked-By：（但 +請注意，通常最好要求一個明確的Ack）。 + +Acked-by：不一定表示對整個補丁的確認。例如，如果一個補丁影響多個子系統，並且 +有一個：來自一個子系統維護者，那麼這通常表示只確認影響維護者代碼的部分。這裡 +應該仔細判斷。如有疑問，應參考郵件列表檔案中的原始討論。 + +如果某人有機會對補丁進行評論，但沒有提供此類評論，您可以選擇在補丁中添加 ``Cc:`` +這是唯一一個標籤，它可以在沒有被它命名的人顯式操作的情況下添加，但它應該表明 +這個人是在補丁上抄送的。討論中包含了潛在利益相關方。 + +Co-developed-by: 聲明補丁是由多個開發人員共同創建的；當幾個人在一個補丁上工 +作時，它用於將屬性賦予共同作者（除了 From: 所賦予的作者之外）。因爲 +Co-developed-by: 表示作者身份，所以每個共同開發人：必須緊跟在相關合作作者的 +簽名之後。標準的簽核程序要求：標記的簽核順序應儘可能反映補丁的時間歷史，而不 +管作者是通過 From ：還是由 Co-developed-by: 共同開發的。值得注意的是，最後一 +個簽字人：必須始終是提交補丁的開發人員。 + +注意，當作者也是電子郵件標題「發件人：」行中列出的人時，「From: 」 標記是可選的。 + +作者提交的補丁程序示例:: + + <changelog> + + Co-developed-by: First Co-Author <first@coauthor.example.org> + Signed-off-by: First Co-Author <first@coauthor.example.org> + Co-developed-by: Second Co-Author <second@coauthor.example.org> + Signed-off-by: Second Co-Author <second@coauthor.example.org> + Signed-off-by: From Author <from@author.example.org> + +合作開發者提交的補丁示例:: + + From: From Author <from@author.example.org> + + <changelog> + + Co-developed-by: Random Co-Author <random@coauthor.example.org> + Signed-off-by: Random Co-Author <random@coauthor.example.org> + Signed-off-by: From Author <from@author.example.org> + Co-developed-by: Submitting Co-Author <sub@coauthor.example.org> + Signed-off-by: Submitting Co-Author <sub@coauthor.example.org> + + +13）使用報告人：、測試人：、審核人：、建議人：、修復人： +-------------------------------------------------------- + +Reported-by: 給那些發現錯誤並報告錯誤的人致謝，它希望激勵他們在將來再次幫助 +我們。請注意，如果bug是以私有方式報告的，那麼在使用Reported-by標記之前，請 +先請求權限。 + +Tested-by: 標記表示補丁已由指定的人（在某些環境中）成功測試。這個標籤通知 +維護人員已經執行了一些測試，爲將來的補丁提供了一種定位測試人員的方法，並確 +保測試人員的信譽。 + +Reviewed-by：相反，根據審查人的聲明，表明該補丁已被審查並被認爲是可接受的： + + +審查人的監督聲明 +^^^^^^^^^^^^^^^^ + +通過提供我的 Reviewed-by，我聲明： + + (a) 我已經對這個補丁進行了一次技術審查，以評估它是否適合被包含到 + 主線內核中。 + + (b) 與補丁相關的任何問題、顧慮或問題都已反饋給提交者。我對提交者對 + 我的評論的回應感到滿意。 + + (c) 雖然這一提交可能會改進一些東西，但我相信，此時，（1）對內核 + 進行了有價值的修改，（2）沒有包含爭論中涉及的已知問題。 + + (d) 雖然我已經審查了補丁並認爲它是健全的，但我不會（除非另有明確 + 說明）作出任何保證或保證它將在任何給定情況下實現其規定的目的 + 或正常運行。 + +Reviewed-by 是一種觀點聲明，即補丁是對內核的適當修改，沒有任何遺留的嚴重技術 +問題。任何感興趣的審閱者（完成工作的人）都可以爲一個補丁提供一個 Review-by +標籤。此標籤用於向審閱者提供致謝，並通知維護者已在修補程序上完成的審閱程度。 +Reviewed-by: 當由已知了解主題區域並執行徹底檢查的審閱者提供時，通常會增加 +補丁進入內核的可能性。 + +Suggested-by: 表示補丁的想法是由指定的人提出的，並確保將此想法歸功於指定的 +人。請注意，未經許可，不得添加此標籤，特別是如果該想法未在公共論壇上發布。 +這就是說，如果我們勤快地致謝我們的創意者，他們很有希望在未來得到鼓舞，再次 +幫助我們。 + +Fixes: 指示補丁在以前的提交中修復了一個問題。它可以很容易地確定錯誤的來源， +這有助於檢查錯誤修復。這個標記還幫助穩定內核團隊確定應該接收修復的穩定內核 +版本。這是指示補丁修復的錯誤的首選方法。請參閱 :ref:`tw_describe_changes` +描述您的更改以了解更多詳細信息。 + +.. _tw_the_canonical_patch_format: + +12）標準補丁格式 +---------------- + +本節描述如何格式化補丁本身。請注意，如果您的補丁存儲在 ``Git`` 存儲庫中，則 +可以使用 ``git format-patch`` 進行正確的補丁格式設置。但是，這些工具無法創建 +必要的文本，因此請務必閱讀下面的說明。 + +標準的補丁，標題行是:: + + Subject: [PATCH 001/123] 子系統:一句話概述 + +標準補丁的信體存在如下部分： + + - 一個 "from" 行指出補丁作者。後跟空行（僅當發送修補程序的人不是作者時才需要）。 + + - 解釋的正文，行以75列包裝，這將被複製到永久變更日誌來描述這個補丁。 + + - 一個空行 + + - 上面描述的「Signed-off-by」 行，也將出現在更改日誌中。 + + - 只包含 ``---`` 的標記線。 + + - 任何其他不適合放在變更日誌的注釋。 + + - 實際補丁（ ``diff`` 輸出）。 + +標題行的格式，使得對標題行按字母序排序非常的容易 - 很多 e-mail 客戶端都 +可以支持 - 因爲序列號是用零填充的，所以按數字排序和按字母排序是一樣的。 + +e-mail 標題中的「子系統」標識哪個內核子系統將被打補丁。 + +e-mail 標題中的「一句話概述」扼要的描述 e-mail 中的補丁。「一句話概述」 +不應該是一個文件名。對於一個補丁系列（「補丁系列」指一系列的多個相關補 +丁），不要對每個補丁都使用同樣的「一句話概述」。 + +記住 e-mail 的「一句話概述」會成爲該補丁的全局唯一標識。它會蔓延到 git +的改動記錄里。然後「一句話概述」會被用在開發者的討論里，用來指代這個補 +丁。用戶將希望通過 google 來搜索"一句話概述"來找到那些討論這個補丁的文 +章。當人們在兩三個月後使用諸如 ``gitk`` 或 ``git log --oneline`` 之類 +的工具查看數千個補丁時，也會很快看到它。 + +出於這些原因，概述必須不超過70-75個字符，並且必須描述補丁的更改以及爲 +什麼需要補丁。既要簡潔又要描述性很有挑戰性，但寫得好的概述應該這樣做。 + +概述的前綴可以用方括號括起來：「Subject: [PATCH <tag>...] <概述>」。標記 +不被視爲概述的一部分，而是描述應該如何處理補丁。如果補丁的多個版本已發 +送出來以響應評審（即「v1，v2，v3」）或「rfc」，以指示評審請求，那麼通用標記 +可能包括版本描述符。如果一個補丁系列中有四個補丁，那麼各個補丁可以這樣 +編號：1/4、2/4、3/4、4/4。這可以確保開發人員了解補丁應用的順序，並且他們 +已經查看或應用了補丁系列中的所有補丁。 + +一些標題的例子:: + + Subject: [patch 2/5] ext2: improve scalability of bitmap searching + Subject: [PATCHv2 001/207] x86: fix eflags tracking + +"From" 行是信體裡的最上面一行，具有如下格式： + From: Patch Author <author@example.com> + +"From" 行指明在永久改動日誌里，誰會被確認爲作者。如果沒有 "From" 行，那 +麼郵件頭裡的 "From: " 行會被用來決定改動日誌中的作者。 + +說明的主題將會被提交到永久的原始碼改動日誌里，因此對那些早已經不記得和 +這個補丁相關的討論細節的有能力的讀者來說，是有意義的。包括補丁程序定位 +錯誤的（內核日誌消息、OOPS消息等）症狀，對於搜索提交日誌以尋找適用補丁的人 +尤其有用。如果一個補丁修復了一個編譯失敗，那麼可能不需要包含所有編譯失敗； +只要足夠讓搜索補丁的人能夠找到它就行了。與概述一樣，既要簡潔又要描述性。 + +"---" 標記行對於補丁處理工具要找到哪裡是改動日誌信息的結束，是不可缺少 +的。 + +對於 "---" 標記之後的額外註解，一個好的用途就是用來寫 diffstat，用來顯 +示修改了什麼文件和每個文件都增加和刪除了多少行。diffstat 對於比較大的補 +丁特別有用。其餘那些只是和時刻或者開發者相關的註解，不合適放到永久的改 +動日誌里的，也應該放這裡。 +使用 diffstat的選項 "-p 1 -w 70" 這樣文件名就會從內核原始碼樹的目錄開始 +，不會占用太寬的空間（很容易適合80列的寬度，也許會有一些縮進。） + +在後面的參考資料中能看到適當的補丁格式的更多細節。 + +.. _tw_explicit_in_reply_to: + +15) 明確回覆郵件頭(In-Reply-To) +------------------------------- + +手動添加回復補丁的的標題頭(In-Reply_To:) 是有幫助的（例如，使用 ``git send-email`` ） +將補丁與以前的相關討論關聯起來，例如，將bug修復程序連結到電子郵件和bug報告。 +但是，對於多補丁系列，最好避免在回復時使用連結到該系列的舊版本。這樣， +補丁的多個版本就不會成爲電子郵件客戶端中無法管理的引用序列。如果連結有用， +可以使用 https://lkml.kernel.org/ 重定向器（例如，在封面電子郵件文本中） +連結到補丁系列的早期版本。 + +16) 發送git pull請求 +-------------------- + +如果您有一系列補丁，那麼讓維護人員通過git pull操作將它們直接拉入子系統存儲 +庫可能是最方便的。但是，請注意，從開發人員那裡獲取補丁比從郵件列表中獲取補 +丁需要更高的信任度。因此，許多子系統維護人員不願意接受請求，特別是來自新的 +未知開發人員的請求。如果有疑問，您可以在封面郵件中使用pull 請求作爲補丁系列 +正常發布的一個選項，讓維護人員可以選擇使用其中之一。 + +pull 請求的主題行中應該有[Git Pull]。請求本身應該在一行中包含存儲庫名稱和 +感興趣的分支；它應該看起來像:: + + Please pull from + + git://jdelvare.pck.nerim.net/jdelvare-2.6 i2c-for-linus + + to get these changes: + + +pull 請求還應該包含一條整體消息，說明請求中將包含什麼，一個補丁本身的 ``Git shortlog`` +以及一個顯示補丁系列整體效果的 ``diffstat`` 。當然，將所有這些信息收集在一起 +的最簡單方法是讓 ``git`` 使用 ``git request-pull`` 命令爲您完成這些工作。 + +一些維護人員（包括Linus）希望看到來自已簽名提交的請求；這增加了他們對你的 +請求信心。特別是，在沒有簽名標籤的情況下，Linus 不會從像 Github 這樣的公共 +託管站點拉請求。 + +創建此類簽名的第一步是生成一個 GNRPG 密鑰，並由一個或多個核心內核開發人員對 +其進行簽名。這一步對新開發人員來說可能很困難，但沒有辦法繞過它。參加會議是 +找到可以簽署您的密鑰的開發人員的好方法。 + +一旦您在Git 中準備了一個您希望有人拉的補丁系列，就用 ``git tag -s`` 創建一 +個簽名標記。這將創建一個新標記，標識該系列中的最後一次提交，並包含用您的私 +鑰創建的簽名。您還可以將changelog樣式的消息添加到標記中；這是一個描述拉請求 +整體效果的理想位置。 + +如果維護人員將要從中提取的樹不是您正在使用的存儲庫，請不要忘記將已簽名的標記 +顯式推送到公共樹。 + +生成拉請求時，請使用已簽名的標記作爲目標。這樣的命令可以實現:: + + git request-pull master git://my.public.tree/linux.git my-signed-tag + +參考文獻 +-------- + +Andrew Morton, "The perfect patch" (tpp). + <https://www.ozlabs.org/~akpm/stuff/tpp.txt> + +Jeff Garzik, "Linux kernel patch submission format". + <https://web.archive.org/web/20180829112450/http://linux.yyz.us/patch-format.html> + +Greg Kroah-Hartman, "How to piss off a kernel subsystem maintainer". + <http://www.kroah.com/log/linux/maintainer.html> + + <http://www.kroah.com/log/linux/maintainer-02.html> + + <http://www.kroah.com/log/linux/maintainer-03.html> + + <http://www.kroah.com/log/linux/maintainer-04.html> + + <http://www.kroah.com/log/linux/maintainer-05.html> + + <http://www.kroah.com/log/linux/maintainer-06.html> + +NO!!!! No more huge patch bombs to linux-kernel@vger.kernel.org people! + <https://lore.kernel.org/r/20050711.125305.08322243.davem@davemloft.net> + +Kernel Documentation/process/coding-style.rst: + :ref:`Documentation/translations/zh_TW/process/coding-style.rst <tw_codingstyle>` + +Linus Torvalds's mail on the canonical patch format: + <https://lore.kernel.org/r/Pine.LNX.4.58.0504071023190.28951@ppc970.osdl.org> + +Andi Kleen, "On submitting kernel patches" + Some strategies to get difficult or controversial changes in. + + http://halobates.de/on-submitting-patches.pdf + diff --git a/Documentation/translations/zh_TW/process/volatile-considered-harmful.rst b/Documentation/translations/zh_TW/process/volatile-considered-harmful.rst new file mode 100644 index 000000000000..097fe80352cb --- /dev/null +++ b/Documentation/translations/zh_TW/process/volatile-considered-harmful.rst @@ -0,0 +1,110 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. _tw_volatile_considered_harmful: + +.. include:: ../disclaimer-zh_TW.rst + +:Original: :ref:`Documentation/process/volatile-considered-harmful.rst + <volatile_considered_harmful>` + +如果想評論或更新本文的內容，請直接聯繫原文檔的維護者。如果你使用英文 +交流有困難的話，也可以向中文版維護者求助。如果本翻譯更新不及時或者翻 +譯存在問題，請聯繫中文版維護者:: + + 英文版維護者： Jonathan Corbet <corbet@lwn.net> + 中文版維護者： 伍鵬 Bryan Wu <bryan.wu@analog.com> + 中文版翻譯者： 伍鵬 Bryan Wu <bryan.wu@analog.com> + 中文版校譯者： 張漢輝 Eugene Teo <eugeneteo@kernel.sg> + 楊瑞 Dave Young <hidave.darkstar@gmail.com> + 時奎亮 Alex Shi <alex.shi@linux.alibaba.com> + 胡皓文 Hu Haowen <src.res@email.cn> + +爲什麼不應該使用「volatile」類型 +================================ + +C程式設計師通常認爲volatile表示某個變量可以在當前執行的線程之外被改變；因此，在內核 +中用到共享數據結構時，常常會有C程式設計師喜歡使用volatile這類變量。換句話說，他們經 +常會把volatile類型看成某種簡易的原子變量，當然它們不是。在內核中使用volatile幾 +乎總是錯誤的；本文檔將解釋爲什麼這樣。 + +理解volatile的關鍵是知道它的目的是用來消除優化，實際上很少有人真正需要這樣的應 +用。在內核中，程式設計師必須防止意外的並發訪問破壞共享的數據結構，這其實是一個完全 +不同的任務。用來防止意外並發訪問的保護措施，可以更加高效的避免大多數優化相關的 +問題。 + +像volatile一樣，內核提供了很多原語來保證並發訪問時的數據安全（自旋鎖, 互斥量,內 +存屏障等等），同樣可以防止意外的優化。如果可以正確使用這些內核原語，那麼就沒有 +必要再使用volatile。如果仍然必須使用volatile，那麼幾乎可以肯定在代碼的某處有一 +個bug。在正確設計的內核代碼中，volatile能帶來的僅僅是使事情變慢。 + +思考一下這段典型的內核代碼:: + + spin_lock(&the_lock); + do_something_on(&shared_data); + do_something_else_with(&shared_data); + spin_unlock(&the_lock); + +如果所有的代碼都遵循加鎖規則，當持有the_lock的時候，不可能意外的改變shared_data的 +值。任何可能訪問該數據的其他代碼都會在這個鎖上等待。自旋鎖原語跟內存屏障一樣—— 它 +們顯式的用來書寫成這樣 —— 意味著數據訪問不會跨越它們而被優化。所以本來編譯器認爲 +它知道在shared_data裡面將有什麼，但是因爲spin_lock()調用跟內存屏障一樣，會強制編 +譯器忘記它所知道的一切。那麼在訪問這些數據時不會有優化的問題。 + +如果shared_data被聲名爲volatile，鎖操作將仍然是必須的。就算我們知道沒有其他人正在 +使用它，編譯器也將被阻止優化對臨界區內shared_data的訪問。在鎖有效的同時， +shared_data不是volatile的。在處理共享數據的時候，適當的鎖操作可以不再需要 +volatile —— 並且是有潛在危害的。 + +volatile的存儲類型最初是爲那些內存映射的I/O寄存器而定義。在內核里，寄存器訪問也應 +該被鎖保護，但是人們也不希望編譯器「優化」臨界區內的寄存器訪問。內核里I/O的內存訪問 +是通過訪問函數完成的；不贊成通過指針對I/O內存的直接訪問，並且不是在所有體系架構上 +都能工作。那些訪問函數正是爲了防止意外優化而寫的，因此，再說一次，volatile類型不 +是必需的。 + +另一種引起用戶可能使用volatile的情況是當處理器正忙著等待一個變量的值。正確執行一 +個忙等待的方法是:: + + while (my_variable != what_i_want) + cpu_relax(); + +cpu_relax()調用會降低CPU的能量消耗或者讓位於超線程雙處理器；它也作爲內存屏障一樣出 +現，所以，再一次，volatile不是必需的。當然，忙等待一開始就是一種反常規的做法。 + +在內核中，一些稀少的情況下volatile仍然是有意義的： + + - 在一些體系架構的系統上，允許直接的I/0內存訪問，那麼前面提到的訪問函數可以使用 + volatile。基本上，每一個訪問函數調用它自己都是一個小的臨界區域並且保證了按照 + 程式設計師期望的那樣發生訪問操作。 + + - 某些會改變內存的內聯彙編代碼雖然沒有什麼其他明顯的附作用，但是有被GCC刪除的可 + 能性。在彙編聲明中加上volatile關鍵字可以防止這種刪除操作。 + + - Jiffies變量是一種特殊情況，雖然每次引用它的時候都可以有不同的值，但讀jiffies + 變量時不需要任何特殊的加鎖保護。所以jiffies變量可以使用volatile，但是不贊成 + 其他跟jiffies相同類型變量使用volatile。Jiffies被認爲是一種「愚蠢的遺留物" + （Linus的話）因爲解決這個問題比保持現狀要麻煩的多。 + + - 由於某些I/0設備可能會修改連續一致的內存,所以有時,指向連續一致內存的數據結構 + 的指針需要正確的使用volatile。網絡適配器使用的環狀緩存區正是這類情形的一個例 + 子，其中適配器用改變指針來表示哪些描述符已經處理過了。 + +對於大多代碼，上述幾種可以使用volatile的情況都不適用。所以，使用volatile是一種 +bug並且需要對這樣的代碼額外仔細檢查。那些試圖使用volatile的開發人員需要退一步想想 +他們真正想實現的是什麼。 + +非常歡迎刪除volatile變量的補丁 － 只要證明這些補丁完整的考慮了並發問題。 + +注釋 +---- + +[1] https://lwn.net/Articles/233481/ +[2] https://lwn.net/Articles/233482/ + +致謝 +---- + +最初由Randy Dunlap推動並作初步研究 +由Jonathan Corbet撰寫 +參考Satyam Sharma，Johannes Stezenbach，Jesper Juhl，Heikki Orsila， +H. Peter Anvin，Philipp Hahn和Stefan Richter的意見改善了本檔。 + diff --git a/Documentation/translations/zh_TW/sparse.txt b/Documentation/translations/zh_TW/sparse.txt new file mode 100644 index 000000000000..c9acb2c926cb --- /dev/null +++ b/Documentation/translations/zh_TW/sparse.txt @@ -0,0 +1,91 @@ +Chinese translated version of Documentation/dev-tools/sparse.rst + +If you have any comment or update to the content, please contact the +original document maintainer directly. However, if you have a problem +communicating in English you can also ask the Chinese maintainer for +help. Contact the Chinese maintainer if this translation is outdated +or if there is a problem with the translation. + +Traditional Chinese maintainer: Hu Haowen <src.res@email.cn> +--------------------------------------------------------------------- +Documentation/dev-tools/sparse.rst 的繁體中文翻譯 + +如果想評論或更新本文的內容，請直接聯繫原文檔的維護者。如果你使用英文 +交流有困難的話，也可以向繁體中文版維護者求助。如果本翻譯更新不及時或 +者翻譯存在問題，請聯繫繁體中文版維護者。 + +繁體中文版維護者： 胡皓文 Hu Haowen <src.res@email.cn> +繁體中文版翻譯者： 胡皓文 Hu Haowen <src.res@email.cn> + +以下爲正文 +--------------------------------------------------------------------- + +Copyright 2004 Linus Torvalds +Copyright 2004 Pavel Machek <pavel@ucw.cz> +Copyright 2006 Bob Copeland <me@bobcopeland.com> + +使用 sparse 工具做類型檢查 +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +"__bitwise" 是一種類型屬性，所以你應該這樣使用它： + + typedef int __bitwise pm_request_t; + + enum pm_request { + PM_SUSPEND = (__force pm_request_t) 1, + PM_RESUME = (__force pm_request_t) 2 + }; + +這樣會使 PM_SUSPEND 和 PM_RESUME 成爲位方式(bitwise)整數（使用"__force" +是因爲 sparse 會抱怨改變位方式的類型轉換，但是這裡我們確實需要強制進行轉 +換）。而且因爲所有枚舉值都使用了相同的類型，這裡的"enum pm_request"也將 +會使用那個類型做爲底層實現。 + +而且使用 gcc 編譯的時候，所有的 __bitwise/__force 都會消失，最後在 gcc +看來它們只不過是普通的整數。 + +坦白來說，你並不需要使用枚舉類型。上面那些實際都可以濃縮成一個特殊的"int +__bitwise"類型。 + +所以更簡單的辦法只要這樣做： + + typedef int __bitwise pm_request_t; + + #define PM_SUSPEND ((__force pm_request_t) 1) + #define PM_RESUME ((__force pm_request_t) 2) + +現在你就有了嚴格的類型檢查所需要的所有基礎架構。 + +一個小提醒：常數整數"0"是特殊的。你可以直接把常數零當作位方式整數使用而 +不用擔心 sparse 會抱怨。這是因爲"bitwise"（恰如其名）是用來確保不同位方 +式類型不會被弄混（小尾模式，大尾模式，cpu尾模式，或者其他），對他們來說 +常數"0"確實是特殊的。 + +獲取 sparse 工具 +~~~~~~~~~~~~~~~~ + +你可以從 Sparse 的主頁獲取最新的發布版本： + + http://www.kernel.org/pub/linux/kernel/people/josh/sparse/ + +或者，你也可以使用 git 克隆最新的 sparse 開發版本： + + git://git.kernel.org/pub/scm/linux/kernel/git/josh/sparse.git + +一旦你下載了源碼，只要以普通用戶身份運行： + + make + make install + +它將會被自動安裝到你的 ~/bin 目錄下。 + +使用 sparse 工具 +~~~~~~~~~~~~~~~~ + +用"make C=1"命令來編譯內核，會對所有重新編譯的 C 文件使用 sparse 工具。 +或者使用"make C=2"命令，無論文件是否被重新編譯都會對其使用 sparse 工具。 +如果你已經編譯了內核，用後一種方式可以很快地檢查整個源碼樹。 + +make 的可選變量 CHECKFLAGS 可以用來向 sparse 工具傳遞參數。編譯系統會自 +動向 sparse 工具傳遞 -Wbitwise 參數。 + diff --git a/Documentation/usb/gadget-testing.rst b/Documentation/usb/gadget-testing.rst index 9d6276f82774..c18113077889 100644 --- a/Documentation/usb/gadget-testing.rst +++ b/Documentation/usb/gadget-testing.rst @@ -724,18 +724,28 @@ Function-specific configfs interface The function name to use when creating the function directory is "uac2". The uac2 function provides these attributes in its function directory: - =============== ==================================================== - c_chmask capture channel mask - c_srate capture sampling rate - c_ssize capture sample size (bytes) - c_sync capture synchronization type (async/adaptive) - fb_max maximum extra bandwidth in async mode - p_chmask playback channel mask - p_srate playback sampling rate - p_ssize playback sample size (bytes) - req_number the number of pre-allocated request for both capture - and playback - =============== ==================================================== + ================ ==================================================== + c_chmask capture channel mask + c_srate capture sampling rate + c_ssize capture sample size (bytes) + c_sync capture synchronization type (async/adaptive) + c_mute_present capture mute control enable + c_volume_present capture volume control enable + c_volume_min capture volume control min value (in 1/256 dB) + c_volume_max capture volume control max value (in 1/256 dB) + c_volume_res capture volume control resolution (in 1/256 dB) + fb_max maximum extra bandwidth in async mode + p_chmask playback channel mask + p_srate playback sampling rate + p_ssize playback sample size (bytes) + p_mute_present playback mute control enable + p_volume_present playback volume control enable + p_volume_min playback volume control min value (in 1/256 dB) + p_volume_max playback volume control max value (in 1/256 dB) + p_volume_res playback volume control resolution (in 1/256 dB) + req_number the number of pre-allocated request for both capture + and playback + ================ ==================================================== The attributes have sane default values. @@ -904,16 +914,26 @@ Function-specific configfs interface The function name to use when creating the function directory is "uac1". The uac1 function provides these attributes in its function directory: - ========== ==================================================== - c_chmask capture channel mask - c_srate capture sampling rate - c_ssize capture sample size (bytes) - p_chmask playback channel mask - p_srate playback sampling rate - p_ssize playback sample size (bytes) - req_number the number of pre-allocated request for both capture - and playback - ========== ==================================================== + ================ ==================================================== + c_chmask capture channel mask + c_srate capture sampling rate + c_ssize capture sample size (bytes) + c_mute_present capture mute control enable + c_volume_present capture volume control enable + c_volume_min capture volume control min value (in 1/256 dB) + c_volume_max capture volume control max value (in 1/256 dB) + c_volume_res capture volume control resolution (in 1/256 dB) + p_chmask playback channel mask + p_srate playback sampling rate + p_ssize playback sample size (bytes) + p_mute_present playback mute control enable + p_volume_present playback volume control enable + p_volume_min playback volume control min value (in 1/256 dB) + p_volume_max playback volume control max value (in 1/256 dB) + p_volume_res playback volume control resolution (in 1/256 dB) + req_number the number of pre-allocated request for both capture + and playback + ================ ==================================================== The attributes have sane default values. diff --git a/Documentation/userspace-api/ioctl/ioctl-number.rst b/Documentation/userspace-api/ioctl/ioctl-number.rst index 1409e40e6345..b7070d76f076 100644 --- a/Documentation/userspace-api/ioctl/ioctl-number.rst +++ b/Documentation/userspace-api/ioctl/ioctl-number.rst @@ -160,7 +160,6 @@ Code Seq# Include File Comments 'K' all linux/kd.h 'L' 00-1F linux/loop.h conflict! 'L' 10-1F drivers/scsi/mpt3sas/mpt3sas_ctl.h conflict! -'L' 20-2F linux/lightnvm.h 'L' E0-FF linux/ppdd.h encrypted disk device driver <http://linux01.gwdg.de/~alatham/ppdd.html> 'M' all linux/soundcard.h conflict! diff --git a/Documentation/userspace-api/media/cec.h.rst.exceptions b/Documentation/userspace-api/media/cec.h.rst.exceptions index d83790ccac8e..13de01d9555e 100644 --- a/Documentation/userspace-api/media/cec.h.rst.exceptions +++ b/Documentation/userspace-api/media/cec.h.rst.exceptions @@ -140,7 +140,7 @@ ignore define CEC_OP_REC_SEQ_TUESDAY ignore define CEC_OP_REC_SEQ_WEDNESDAY ignore define CEC_OP_REC_SEQ_THURSDAY ignore define CEC_OP_REC_SEQ_FRIDAY -ignore define CEC_OP_REC_SEQ_SATERDAY +ignore define CEC_OP_REC_SEQ_SATURDAY ignore define CEC_OP_REC_SEQ_ONCE_ONLY ignore define CEC_MSG_CLEAR_DIGITAL_TIMER diff --git a/Documentation/userspace-api/media/v4l/ext-ctrls-codec.rst b/Documentation/userspace-api/media/v4l/ext-ctrls-codec.rst index 8c6e2a11ed95..976d34445a24 100644 --- a/Documentation/userspace-api/media/v4l/ext-ctrls-codec.rst +++ b/Documentation/userspace-api/media/v4l/ext-ctrls-codec.rst @@ -1174,7 +1174,24 @@ enum v4l2_mpeg_video_h264_entropy_mode - Cyclic intra macroblock refresh. This is the number of continuous macroblocks refreshed every frame. Each frame a successive set of macroblocks is refreshed until the cycle completes and starts from - the top of the frame. Applicable to H264, H263 and MPEG4 encoder. + the top of the frame. Setting this control to zero means that + macroblocks will not be refreshed. Note that this control will not + take effect when ``V4L2_CID_MPEG_VIDEO_INTRA_REFRESH_PERIOD`` control + is set to non zero value. + Applicable to H264, H263 and MPEG4 encoder. + +``V4L2_CID_MPEG_VIDEO_INTRA_REFRESH_PERIOD (integer)`` + Intra macroblock refresh period. This sets the period to refresh + the whole frame. In other words, this defines the number of frames + for which the whole frame will be intra-refreshed. An example: + setting period to 1 means that the whole frame will be refreshed, + setting period to 2 means that the half of macroblocks will be + intra-refreshed on frameX and the other half of macroblocks + will be refreshed in frameX + 1 and so on. Setting the period to + zero means no period is specified. + Note that if the client sets this control to non zero value the + ``V4L2_CID_MPEG_VIDEO_CYCLIC_INTRA_REFRESH_MB`` control shall be + ignored. Applicable to H264 and HEVC encoders. ``V4L2_CID_MPEG_VIDEO_FRAME_RC_ENABLE (boolean)`` Frame level rate control enable. If this control is disabled then @@ -3000,6 +3017,9 @@ enum v4l2_mpeg_video_hevc_size_of_length_field - * - __u8 - ``pic_struct`` - + * - __u32 + - ``slice_segment_addr`` + - * - __u8 - ``ref_idx_l0[V4L2_HEVC_DPB_ENTRIES_NUM_MAX]`` - The list of L0 reference elements as indices in the DPB. diff --git a/Documentation/userspace-api/media/v4l/ext-ctrls-image-process.rst b/Documentation/userspace-api/media/v4l/ext-ctrls-image-process.rst index 87698c15c027..b1c2ab2854af 100644 --- a/Documentation/userspace-api/media/v4l/ext-ctrls-image-process.rst +++ b/Documentation/userspace-api/media/v4l/ext-ctrls-image-process.rst @@ -20,25 +20,26 @@ Image Process Control IDs ``V4L2_CID_IMAGE_PROC_CLASS (class)`` The IMAGE_PROC class descriptor. +.. _v4l2-cid-link-freq: + ``V4L2_CID_LINK_FREQ (integer menu)`` - Data bus frequency. Together with the media bus pixel code, bus type - (clock cycles per sample), the data bus frequency defines the pixel - rate (``V4L2_CID_PIXEL_RATE``) in the pixel array (or possibly - elsewhere, if the device is not an image sensor). The frame rate can - be calculated from the pixel clock, image width and height and - horizontal and vertical blanking. While the pixel rate control may - be defined elsewhere than in the subdev containing the pixel array, - the frame rate cannot be obtained from that information. This is - because only on the pixel array it can be assumed that the vertical - and horizontal blanking information is exact: no other blanking is - allowed in the pixel array. The selection of frame rate is performed - by selecting the desired horizontal and vertical blanking. The unit - of this control is Hz. + The frequency of the data bus (e.g. parallel or CSI-2). + +.. _v4l2-cid-pixel-rate: ``V4L2_CID_PIXEL_RATE (64-bit integer)`` - Pixel rate in the source pads of the subdev. This control is + Pixel sampling rate in the device's pixel array. This control is read-only and its unit is pixels / second. + Some devices use horizontal and vertical balanking to configure the frame + rate. The frame rate can be calculated from the pixel rate, analogue crop + rectangle as well as horizontal and vertical blanking. The pixel rate + control may be present in a different sub-device than the blanking controls + and the analogue crop rectangle configuration. + + The configuration of the frame rate is performed by selecting the desired + horizontal and vertical blanking. The unit of this control is Hz. + ``V4L2_CID_TEST_PATTERN (menu)`` Some capture/display/sensor devices have the capability to generate test pattern images. These hardware specific test patterns can be diff --git a/Documentation/userspace-api/seccomp_filter.rst b/Documentation/userspace-api/seccomp_filter.rst index d61219889e49..539e9d4a4860 100644 --- a/Documentation/userspace-api/seccomp_filter.rst +++ b/Documentation/userspace-api/seccomp_filter.rst @@ -263,7 +263,7 @@ Userspace can also add file descriptors to the notifying process via ``ioctl(SECCOMP_IOCTL_NOTIF_ADDFD)``. The ``id`` member of ``struct seccomp_notif_addfd`` should be the same ``id`` as in ``struct seccomp_notif``. The ``newfd_flags`` flag may be used to set flags -like O_EXEC on the file descriptor in the notifying process. If the supervisor +like O_CLOEXEC on the file descriptor in the notifying process. If the supervisor wants to inject the file descriptor with a specific number, the ``SECCOMP_ADDFD_FLAG_SETFD`` flag can be used, and set the ``newfd`` member to the specific number to use. If that file descriptor is already open in the diff --git a/Documentation/userspace-api/spec_ctrl.rst b/Documentation/userspace-api/spec_ctrl.rst index 7ddd8f667459..5e8ed9eef9aa 100644 --- a/Documentation/userspace-api/spec_ctrl.rst +++ b/Documentation/userspace-api/spec_ctrl.rst @@ -106,3 +106,11 @@ Speculation misfeature controls * prctl(PR_SET_SPECULATION_CTRL, PR_SPEC_INDIRECT_BRANCH, PR_SPEC_ENABLE, 0, 0); * prctl(PR_SET_SPECULATION_CTRL, PR_SPEC_INDIRECT_BRANCH, PR_SPEC_DISABLE, 0, 0); * prctl(PR_SET_SPECULATION_CTRL, PR_SPEC_INDIRECT_BRANCH, PR_SPEC_FORCE_DISABLE, 0, 0); + +- PR_SPEC_L1D_FLUSH: Flush L1D Cache on context switch out of the task + (works only when tasks run on non SMT cores) + + Invocations: + * prctl(PR_GET_SPECULATION_CTRL, PR_SPEC_L1D_FLUSH, 0, 0, 0); + * prctl(PR_SET_SPECULATION_CTRL, PR_SPEC_L1D_FLUSH, PR_SPEC_ENABLE, 0, 0); + * prctl(PR_SET_SPECULATION_CTRL, PR_SPEC_L1D_FLUSH, PR_SPEC_DISABLE, 0, 0); diff --git a/Documentation/virt/kvm/api.rst b/Documentation/virt/kvm/api.rst index c7b165ca70b6..c6212c2d5fe3 100644 --- a/Documentation/virt/kvm/api.rst +++ b/Documentation/virt/kvm/api.rst @@ -855,7 +855,7 @@ 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:: - bits: | 31 ... 28 | 27 ... 24 | 23 ... 16 | 15 ... 0 | + 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: @@ -2149,10 +2149,10 @@ prior to calling the KVM_RUN ioctl. Errors: ====== ============================================================ - ENOENT no such register - EINVAL invalid register ID, or no such register or used with VMs in + ENOENT no such register + EINVAL invalid register ID, or no such register or used with VMs in protected virtualization mode on s390 - EPERM (arm64) register access not allowed before vcpu finalization + EPERM (arm64) register access not allowed before vcpu finalization ====== ============================================================ (These error codes are indicative only: do not rely on a specific error @@ -2590,10 +2590,10 @@ following id bit patterns:: Errors include: ======== ============================================================ - ENOENT no such register - EINVAL invalid register ID, or no such register or used with VMs in + ENOENT no such register + EINVAL invalid register ID, or no such register or used with VMs in protected virtualization mode on s390 - EPERM (arm64) register access not allowed before vcpu finalization + EPERM (arm64) register access not allowed before vcpu finalization ======== ============================================================ (These error codes are indicative only: do not rely on a specific error @@ -3112,13 +3112,13 @@ current state. "addr" is ignored. 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 -registers to their initial values. If this is not called, KVM_RUN will +optional features it should have. This will cause a reset of the cpu +registers to their initial values. If this is not called, KVM_RUN will return ENOEXEC for that vcpu. The initial values are defined as: @@ -3239,8 +3239,8 @@ VCPU matching underlying host. Errors: ===== ============================================================== - 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). + 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). ===== ============================================================== :: @@ -3288,7 +3288,7 @@ specific device. ARM/arm64 divides the id field into two parts, a device id and an address type id specific to the individual device:: - bits: | 63 ... 32 | 31 ... 16 | 15 ... 0 | + bits: | 63 ... 32 | 31 ... 16 | 15 ... 0 | field: | 0x00000000 | device id | addr type id | ARM/arm64 currently only require this when using the in-kernel GIC @@ -5077,7 +5077,7 @@ of bytes successfully copied is returned. If the call completes successfully then ``length`` is returned. 4.131 KVM_GET_SREGS2 ------------------- +-------------------- :Capability: KVM_CAP_SREGS2 :Architectures: x86 @@ -5090,17 +5090,17 @@ This ioctl (when supported) replaces the KVM_GET_SREGS. :: -struct kvm_sregs2 { - /* out (KVM_GET_SREGS2) / in (KVM_SET_SREGS2) */ - struct kvm_segment cs, ds, es, fs, gs, ss; - struct kvm_segment tr, ldt; - struct kvm_dtable gdt, idt; - __u64 cr0, cr2, cr3, cr4, cr8; - __u64 efer; - __u64 apic_base; - __u64 flags; - __u64 pdptrs[4]; -}; + struct kvm_sregs2 { + /* out (KVM_GET_SREGS2) / in (KVM_SET_SREGS2) */ + struct kvm_segment cs, ds, es, fs, gs, ss; + struct kvm_segment tr, ldt; + struct kvm_dtable gdt, idt; + __u64 cr0, cr2, cr3, cr4, cr8; + __u64 efer; + __u64 apic_base; + __u64 flags; + __u64 pdptrs[4]; + }; flags values for ``kvm_sregs2``: @@ -5110,7 +5110,7 @@ flags values for ``kvm_sregs2``: 4.132 KVM_SET_SREGS2 ------------------- +-------------------- :Capability: KVM_CAP_SREGS2 :Architectures: x86 @@ -5201,6 +5201,7 @@ trailing ``'\0'``, is indicated by the ``name_size`` field in the header. The descriptors block is only needed to be read once for the lifetime of the file descriptor contains a sequence of ``struct kvm_stats_desc``, each followed by a string of size ``name_size``. +:: #define KVM_STATS_TYPE_SHIFT 0 #define KVM_STATS_TYPE_MASK (0xF << KVM_STATS_TYPE_SHIFT) @@ -5234,6 +5235,7 @@ by this descriptor. Its endianness is CPU native. The following flags are supported: Bits 0-3 of ``flags`` encode the type: + * ``KVM_STATS_TYPE_CUMULATIVE`` The statistics data is cumulative. The value of data can only be increased. Most of the counters used in KVM are of this type. @@ -5252,6 +5254,7 @@ Bits 0-3 of ``flags`` encode the type: The corresponding ``size`` field for this type is always 1. Bits 4-7 of ``flags`` encode the unit: + * ``KVM_STATS_UNIT_NONE`` There is no unit for the value of statistics data. This usually means that the value is a simple counter of an event. @@ -5266,6 +5269,7 @@ Bits 4-7 of ``flags`` encode the unit: Bits 8-11 of ``flags``, together with ``exponent``, encode the scale of the unit: + * ``KVM_STATS_BASE_POW10`` The scale is based on power of 10. It is used for measurement of time and CPU clock cycles. For example, an exponent of -9 can be used with @@ -7049,7 +7053,7 @@ In combination with KVM_CAP_X86_USER_SPACE_MSR, this allows user space to trap and emulate MSRs that are outside of the scope of KVM as well as limit the attack surface on KVM's MSR emulation code. -8.28 KVM_CAP_ENFORCE_PV_CPUID +8.28 KVM_CAP_ENFORCE_PV_FEATURE_CPUID ----------------------------- Architectures: x86 @@ -7213,7 +7217,7 @@ supported in the host. A VMM can check whether the service is available to the guest on migration. 8.33 KVM_CAP_HYPERV_ENFORCE_CPUID ------------------------------ +--------------------------------- Architectures: x86 diff --git a/Documentation/virt/kvm/locking.rst b/Documentation/virt/kvm/locking.rst index 35eca377543d..88fa495abbac 100644 --- a/Documentation/virt/kvm/locking.rst +++ b/Documentation/virt/kvm/locking.rst @@ -25,10 +25,10 @@ On x86: - vcpu->mutex is taken outside kvm->arch.hyperv.hv_lock -- kvm->arch.mmu_lock is an rwlock. kvm->arch.tdp_mmu_pages_lock is - taken inside kvm->arch.mmu_lock, and cannot be taken without already - holding kvm->arch.mmu_lock (typically with ``read_lock``, otherwise - there's no need to take kvm->arch.tdp_mmu_pages_lock at all). +- kvm->arch.mmu_lock is an rwlock. kvm->arch.tdp_mmu_pages_lock and + kvm->arch.mmu_unsync_pages_lock are taken inside kvm->arch.mmu_lock, and + cannot be taken without already holding kvm->arch.mmu_lock (typically with + ``read_lock`` for the TDP MMU, thus the need for additional spinlocks). Everything else is a leaf: no other lock is taken inside the critical sections. diff --git a/Documentation/vm/hwpoison.rst b/Documentation/vm/hwpoison.rst index a5c884293dac..89b5f7a52077 100644 --- a/Documentation/vm/hwpoison.rst +++ b/Documentation/vm/hwpoison.rst @@ -180,7 +180,6 @@ Limitations =========== - Not all page types are supported and never will. Most kernel internal objects cannot be recovered, only LRU pages for now. -- Right now hugepage support is missing. --- Andi Kleen, Oct 2009 diff --git a/Documentation/x86/x86_64/boot-options.rst b/Documentation/x86/x86_64/boot-options.rst index 5f62b3b86357..ccb7e86bf8d9 100644 --- a/Documentation/x86/x86_64/boot-options.rst +++ b/Documentation/x86/x86_64/boot-options.rst @@ -126,7 +126,7 @@ Idle loop Rebooting ========= - reboot=b[ios] | t[riple] | k[bd] | a[cpi] | e[fi] [, [w]arm | [c]old] + reboot=b[ios] | t[riple] | k[bd] | a[cpi] | e[fi] | p[ci] [, [w]arm | [c]old] bios Use the CPU reboot vector for warm reset warm @@ -145,6 +145,8 @@ Rebooting Use efi reset_system runtime service. If EFI is not configured or the EFI reset does not work, the reboot path attempts the reset using the keyboard controller. + pci + Use a write to the PCI config space register 0xcf9 to trigger reboot. Using warm reset will be much faster especially on big memory systems because the BIOS will not go through the memory check. @@ -155,6 +157,13 @@ Rebooting Don't stop other CPUs on reboot. This can make reboot more reliable in some cases. + reboot=default + There are some built-in platform specific "quirks" - you may see: + "reboot: <name> series board detected. Selecting <type> for reboots." + In the case where you think the quirk is in error (e.g. you have + newer BIOS, or newer board) using this option will ignore the built-in + quirk table, and use the generic default reboot actions. + Non Executable Mappings ======================= |