diff options
Diffstat (limited to 'Documentation')
412 files changed, 14327 insertions, 2494 deletions
diff --git a/Documentation/ABI/testing/debugfs-driver-qat_telemetry b/Documentation/ABI/testing/debugfs-driver-qat_telemetry new file mode 100644 index 000000000000..eacee2072088 --- /dev/null +++ b/Documentation/ABI/testing/debugfs-driver-qat_telemetry @@ -0,0 +1,228 @@ +What: /sys/kernel/debug/qat_<device>_<BDF>/telemetry/control +Date: March 2024 +KernelVersion: 6.8 +Contact: qat-linux@intel.com +Description: (RW) Enables/disables the reporting of telemetry metrics. + + Allowed values to write: + ======================== + * 0: disable telemetry + * 1: enable telemetry + * 2, 3, 4: enable telemetry and calculate minimum, maximum + and average for each counter over 2, 3 or 4 samples + + Returned values: + ================ + * 1-4: telemetry is enabled and running + * 0: telemetry is disabled + + Example. + + Writing '3' to this file starts the collection of + telemetry metrics. Samples are collected every second and + stored in a circular buffer of size 3. These values are then + used to calculate the minimum, maximum and average for each + counter. After enabling, counters can be retrieved through + the ``device_data`` file:: + + echo 3 > /sys/kernel/debug/qat_4xxx_0000:6b:00.0/telemetry/control + + Writing '0' to this file stops the collection of telemetry + metrics:: + + echo 0 > /sys/kernel/debug/qat_4xxx_0000:6b:00.0/telemetry/control + + This attribute is only available for qat_4xxx devices. + +What: /sys/kernel/debug/qat_<device>_<BDF>/telemetry/device_data +Date: March 2024 +KernelVersion: 6.8 +Contact: qat-linux@intel.com +Description: (RO) Reports device telemetry counters. + Reads report metrics about performance and utilization of + a QAT device: + + ======================= ======================================== + Field Description + ======================= ======================================== + sample_cnt number of acquisitions of telemetry data + from the device. Reads are performed + every 1000 ms. + pci_trans_cnt number of PCIe partial transactions + max_rd_lat maximum logged read latency [ns] (could + be any read operation) + rd_lat_acc_avg average read latency [ns] + max_gp_lat max get to put latency [ns] (only takes + samples for AE0) + gp_lat_acc_avg average get to put latency [ns] + bw_in PCIe, write bandwidth [Mbps] + bw_out PCIe, read bandwidth [Mbps] + at_page_req_lat_avg Address Translator(AT), average page + request latency [ns] + at_trans_lat_avg AT, average page translation latency [ns] + at_max_tlb_used AT, maximum uTLB used + util_cpr<N> utilization of Compression slice N [%] + exec_cpr<N> execution count of Compression slice N + util_xlt<N> utilization of Translator slice N [%] + exec_xlt<N> execution count of Translator slice N + util_dcpr<N> utilization of Decompression slice N [%] + exec_dcpr<N> execution count of Decompression slice N + util_pke<N> utilization of PKE N [%] + exec_pke<N> execution count of PKE N + util_ucs<N> utilization of UCS slice N [%] + exec_ucs<N> execution count of UCS slice N + util_wat<N> utilization of Wireless Authentication + slice N [%] + exec_wat<N> execution count of Wireless Authentication + slice N + util_wcp<N> utilization of Wireless Cipher slice N [%] + exec_wcp<N> execution count of Wireless Cipher slice N + util_cph<N> utilization of Cipher slice N [%] + exec_cph<N> execution count of Cipher slice N + util_ath<N> utilization of Authentication slice N [%] + exec_ath<N> execution count of Authentication slice N + ======================= ======================================== + + The telemetry report file can be read with the following command:: + + cat /sys/kernel/debug/qat_4xxx_0000:6b:00.0/telemetry/device_data + + If ``control`` is set to 1, only the current values of the + counters are displayed:: + + <counter_name> <current> + + If ``control`` is 2, 3 or 4, counters are displayed in the + following format:: + + <counter_name> <current> <min> <max> <avg> + + If a device lacks of a specific accelerator, the corresponding + attribute is not reported. + + This attribute is only available for qat_4xxx devices. + +What: /sys/kernel/debug/qat_<device>_<BDF>/telemetry/rp_<A/B/C/D>_data +Date: March 2024 +KernelVersion: 6.8 +Contact: qat-linux@intel.com +Description: (RW) Selects up to 4 Ring Pairs (RP) to monitor, one per file, + and report telemetry counters related to each. + + Allowed values to write: + ======================== + * 0 to ``<num_rps - 1>``: + Ring pair to be monitored. The value of ``num_rps`` can be + retrieved through ``/sys/bus/pci/devices/<BDF>/qat/num_rps``. + See Documentation/ABI/testing/sysfs-driver-qat. + + Reads report metrics about performance and utilization of + the selected RP: + + ======================= ======================================== + Field Description + ======================= ======================================== + sample_cnt number of acquisitions of telemetry data + from the device. Reads are performed + every 1000 ms + rp_num RP number associated with slot <A/B/C/D> + service_type service associated to the RP + pci_trans_cnt number of PCIe partial transactions + gp_lat_acc_avg average get to put latency [ns] + bw_in PCIe, write bandwidth [Mbps] + bw_out PCIe, read bandwidth [Mbps] + at_glob_devtlb_hit Message descriptor DevTLB hit rate + at_glob_devtlb_miss Message descriptor DevTLB miss rate + tl_at_payld_devtlb_hit Payload DevTLB hit rate + tl_at_payld_devtlb_miss Payload DevTLB miss rate + ======================= ======================================== + + Example. + + Writing the value '32' to the file ``rp_C_data`` starts the + collection of telemetry metrics for ring pair 32:: + + echo 32 > /sys/kernel/debug/qat_4xxx_0000:6b:00.0/telemetry/rp_C_data + + Once a ring pair is selected, statistics can be read accessing + the file:: + + cat /sys/kernel/debug/qat_4xxx_0000:6b:00.0/telemetry/rp_C_data + + If ``control`` is set to 1, only the current values of the + counters are displayed:: + + <counter_name> <current> + + If ``control`` is 2, 3 or 4, counters are displayed in the + following format:: + + <counter_name> <current> <min> <max> <avg> + + + On QAT GEN4 devices there are 64 RPs on a PF, so the allowed + values are 0..63. This number is absolute to the device. + If Virtual Functions (VF) are used, the ring pair number can + be derived from the Bus, Device, Function of the VF: + + ============ ====== ====== ====== ====== + PCI BDF/VF RP0 RP1 RP2 RP3 + ============ ====== ====== ====== ====== + 0000:6b:0.1 RP 0 RP 1 RP 2 RP 3 + 0000:6b:0.2 RP 4 RP 5 RP 6 RP 7 + 0000:6b:0.3 RP 8 RP 9 RP 10 RP 11 + 0000:6b:0.4 RP 12 RP 13 RP 14 RP 15 + 0000:6b:0.5 RP 16 RP 17 RP 18 RP 19 + 0000:6b:0.6 RP 20 RP 21 RP 22 RP 23 + 0000:6b:0.7 RP 24 RP 25 RP 26 RP 27 + 0000:6b:1.0 RP 28 RP 29 RP 30 RP 31 + 0000:6b:1.1 RP 32 RP 33 RP 34 RP 35 + 0000:6b:1.2 RP 36 RP 37 RP 38 RP 39 + 0000:6b:1.3 RP 40 RP 41 RP 42 RP 43 + 0000:6b:1.4 RP 44 RP 45 RP 46 RP 47 + 0000:6b:1.5 RP 48 RP 49 RP 50 RP 51 + 0000:6b:1.6 RP 52 RP 53 RP 54 RP 55 + 0000:6b:1.7 RP 56 RP 57 RP 58 RP 59 + 0000:6b:2.0 RP 60 RP 61 RP 62 RP 63 + ============ ====== ====== ====== ====== + + The mapping is only valid for the BDFs of VFs on the host. + + + The service provided on a ring-pair varies depending on the + configuration. The configuration for a given device can be + queried and set using ``cfg_services``. + See Documentation/ABI/testing/sysfs-driver-qat for details. + + The following table reports how ring pairs are mapped to VFs + on the PF 0000:6b:0.0 configured for `sym;asym` or `asym;sym`: + + =========== ============ =========== ============ =========== + PCI BDF/VF RP0/service RP1/service RP2/service RP3/service + =========== ============ =========== ============ =========== + 0000:6b:0.1 RP 0 asym RP 1 sym RP 2 asym RP 3 sym + 0000:6b:0.2 RP 4 asym RP 5 sym RP 6 asym RP 7 sym + 0000:6b:0.3 RP 8 asym RP 9 sym RP10 asym RP11 sym + ... ... ... ... ... + =========== ============ =========== ============ =========== + + All VFs follow the same pattern. + + + The following table reports how ring pairs are mapped to VFs on + the PF 0000:6b:0.0 configured for `dc`: + + =========== ============ =========== ============ =========== + PCI BDF/VF RP0/service RP1/service RP2/service RP3/service + =========== ============ =========== ============ =========== + 0000:6b:0.1 RP 0 dc RP 1 dc RP 2 dc RP 3 dc + 0000:6b:0.2 RP 4 dc RP 5 dc RP 6 dc RP 7 dc + 0000:6b:0.3 RP 8 dc RP 9 dc RP10 dc RP11 dc + ... ... ... ... ... + =========== ============ =========== ============ =========== + + The mapping of a RP to a service can be retrieved using + ``rp2srv`` from sysfs. + See Documentation/ABI/testing/sysfs-driver-qat for details. + + This attribute is only available for qat_4xxx devices. diff --git a/Documentation/ABI/testing/debugfs-hisi-hpre b/Documentation/ABI/testing/debugfs-hisi-hpre index 82abf92df429..8e8de49c5cc6 100644 --- a/Documentation/ABI/testing/debugfs-hisi-hpre +++ b/Documentation/ABI/testing/debugfs-hisi-hpre @@ -101,7 +101,7 @@ What: /sys/kernel/debug/hisi_hpre/<bdf>/qm/status Date: Apr 2020 Contact: linux-crypto@vger.kernel.org Description: Dump the status of the QM. - Four states: initiated, started, stopped and closed. + Two states: work, stop. Available for both PF and VF, and take no other effect on HPRE. What: /sys/kernel/debug/hisi_hpre/<bdf>/qm/diff_regs diff --git a/Documentation/ABI/testing/debugfs-hisi-sec b/Documentation/ABI/testing/debugfs-hisi-sec index 93c530d1bf0f..deeefe2c735e 100644 --- a/Documentation/ABI/testing/debugfs-hisi-sec +++ b/Documentation/ABI/testing/debugfs-hisi-sec @@ -81,7 +81,7 @@ What: /sys/kernel/debug/hisi_sec2/<bdf>/qm/status Date: Apr 2020 Contact: linux-crypto@vger.kernel.org Description: Dump the status of the QM. - Four states: initiated, started, stopped and closed. + Two states: work, stop. Available for both PF and VF, and take no other effect on SEC. What: /sys/kernel/debug/hisi_sec2/<bdf>/qm/diff_regs diff --git a/Documentation/ABI/testing/debugfs-hisi-zip b/Documentation/ABI/testing/debugfs-hisi-zip index fd3f314cf8d1..593714afaed2 100644 --- a/Documentation/ABI/testing/debugfs-hisi-zip +++ b/Documentation/ABI/testing/debugfs-hisi-zip @@ -94,7 +94,7 @@ What: /sys/kernel/debug/hisi_zip/<bdf>/qm/status Date: Apr 2020 Contact: linux-crypto@vger.kernel.org Description: Dump the status of the QM. - Four states: initiated, started, stopped and closed. + Two states: work, stop. Available for both PF and VF, and take no other effect on ZIP. What: /sys/kernel/debug/hisi_zip/<bdf>/qm/diff_regs diff --git a/Documentation/ABI/testing/sysfs-bus-event_source-devices-caps b/Documentation/ABI/testing/sysfs-bus-event_source-devices-caps index 8757dcf41c08..a5f506f7d481 100644 --- a/Documentation/ABI/testing/sysfs-bus-event_source-devices-caps +++ b/Documentation/ABI/testing/sysfs-bus-event_source-devices-caps @@ -16,3 +16,9 @@ Description: Example output in powerpc: grep . /sys/bus/event_source/devices/cpu/caps/* /sys/bus/event_source/devices/cpu/caps/pmu_name:POWER9 + + The "branch_counter_nr" in the supported platform exposes the + maximum number of counters which can be shown in the u64 counters + of PERF_SAMPLE_BRANCH_COUNTERS, while the "branch_counter_width" + exposes the width of each counter. Both of them can be used by + the perf tool to parse the logged counters in each branch. diff --git a/Documentation/ABI/testing/sysfs-bus-spi-devices-spi-nor b/Documentation/ABI/testing/sysfs-bus-spi-devices-spi-nor index c800621eff95..9ed5582ddea2 100644 --- a/Documentation/ABI/testing/sysfs-bus-spi-devices-spi-nor +++ b/Documentation/ABI/testing/sysfs-bus-spi-devices-spi-nor @@ -25,6 +25,9 @@ KernelVersion: 5.14 Contact: linux-mtd@lists.infradead.org Description: (RO) Part name of the SPI NOR flash. + The attribute is optional. User space should not rely on + it to be present or even correct. Instead, user space + should read the jedec_id attribute. What: /sys/bus/spi/devices/.../spi-nor/sfdp Date: April 2021 diff --git a/Documentation/ABI/testing/sysfs-class-devfreq b/Documentation/ABI/testing/sysfs-class-devfreq index 5e6b74f30406..1e7e0bb4c14e 100644 --- a/Documentation/ABI/testing/sysfs-class-devfreq +++ b/Documentation/ABI/testing/sysfs-class-devfreq @@ -52,6 +52,9 @@ Description: echo 0 > /sys/class/devfreq/.../trans_stat + If the transition table is bigger than PAGE_SIZE, reading + this will return an -EFBIG error. + What: /sys/class/devfreq/.../available_frequencies Date: October 2012 Contact: Nishanth Menon <nm@ti.com> diff --git a/Documentation/ABI/testing/sysfs-devices-platform-kunpeng_hccs b/Documentation/ABI/testing/sysfs-devices-platform-kunpeng_hccs index fdb4e36310fb..1666340820f7 100644 --- a/Documentation/ABI/testing/sysfs-devices-platform-kunpeng_hccs +++ b/Documentation/ABI/testing/sysfs-devices-platform-kunpeng_hccs @@ -3,7 +3,7 @@ What: /sys/devices/platform/HISI04Bx:00/chipX/linked_full_lane What: /sys/devices/platform/HISI04Bx:00/chipX/crc_err_cnt Date: November 2023 KernelVersion: 6.6 -Contact: Huisong Li <lihuisong@huawei.org> +Contact: Huisong Li <lihuisong@huawei.com> Description: The /sys/devices/platform/HISI04Bx:00/chipX/ directory contains read-only attributes exposing some summarization @@ -26,7 +26,7 @@ What: /sys/devices/platform/HISI04Bx:00/chipX/dieY/linked_full_lane What: /sys/devices/platform/HISI04Bx:00/chipX/dieY/crc_err_cnt Date: November 2023 KernelVersion: 6.6 -Contact: Huisong Li <lihuisong@huawei.org> +Contact: Huisong Li <lihuisong@huawei.com> Description: The /sys/devices/platform/HISI04Bx:00/chipX/dieY/ directory contains read-only attributes exposing some summarization @@ -54,7 +54,7 @@ What: /sys/devices/platform/HISI04Bx:00/chipX/dieY/hccsN/lane_mask What: /sys/devices/platform/HISI04Bx:00/chipX/dieY/hccsN/crc_err_cnt Date: November 2023 KernelVersion: 6.6 -Contact: Huisong Li <lihuisong@huawei.org> +Contact: Huisong Li <lihuisong@huawei.com> Description: The /sys/devices/platform/HISI04Bx/chipX/dieX/hccsN/ directory contains read-only attributes exposing information about diff --git a/Documentation/ABI/testing/sysfs-driver-ufs b/Documentation/ABI/testing/sysfs-driver-ufs index 0c7efaf62de0..5bf7073b4f75 100644 --- a/Documentation/ABI/testing/sysfs-driver-ufs +++ b/Documentation/ABI/testing/sysfs-driver-ufs @@ -1223,6 +1223,55 @@ Description: This file shows the total latency (in micro seconds) of write The file is read only. +What: /sys/bus/platform/drivers/ufshcd/*/power_info/lane +What: /sys/bus/platform/devices/*.ufs/power_info/lane +Date: September 2023 +Contact: Can Guo <quic_cang@quicinc.com> +Description: This file shows how many lanes are enabled on the UFS link, + i.e., an output 2 means UFS link is operating with 2 lanes. + + The file is read only. + +What: /sys/bus/platform/drivers/ufshcd/*/power_info/mode +What: /sys/bus/platform/devices/*.ufs/power_info/mode +Date: September 2023 +Contact: Can Guo <quic_cang@quicinc.com> +Description: This file shows the PA power mode of UFS. + + The file is read only. + +What: /sys/bus/platform/drivers/ufshcd/*/power_info/rate +What: /sys/bus/platform/devices/*.ufs/power_info/rate +Date: September 2023 +Contact: Can Guo <quic_cang@quicinc.com> +Description: This file shows the speed rate of UFS link. + + The file is read only. + +What: /sys/bus/platform/drivers/ufshcd/*/power_info/gear +What: /sys/bus/platform/devices/*.ufs/power_info/gear +Date: September 2023 +Contact: Can Guo <quic_cang@quicinc.com> +Description: This file shows the gear of UFS link. + + The file is read only. + +What: /sys/bus/platform/drivers/ufshcd/*/power_info/dev_pm +What: /sys/bus/platform/devices/*.ufs/power_info/dev_pm +Date: September 2023 +Contact: Can Guo <quic_cang@quicinc.com> +Description: This file shows the UFS device power mode. + + The file is read only. + +What: /sys/bus/platform/drivers/ufshcd/*/power_info/link_state +What: /sys/bus/platform/devices/*.ufs/power_info/link_state +Date: September 2023 +Contact: Can Guo <quic_cang@quicinc.com> +Description: This file shows the state of UFS link. + + The file is read only. + What: /sys/bus/platform/drivers/ufshcd/*/device_descriptor/wb_presv_us_en What: /sys/bus/platform/devices/*.ufs/device_descriptor/wb_presv_us_en Date: June 2020 @@ -1474,3 +1523,10 @@ Description: Indicates status of Write Booster. The file is read only. +What: /sys/bus/platform/drivers/ufshcd/*/rtc_update_ms +What: /sys/bus/platform/devices/*.ufs/rtc_update_ms +Date: November 2023 +Contact: Bean Huo <beanhuo@micron.com> +Description: + rtc_update_ms indicates how often the host should synchronize or update the + UFS RTC. If set to 0, this will disable UFS RTC periodic update. diff --git a/Documentation/ABI/testing/sysfs-fs-f2fs b/Documentation/ABI/testing/sysfs-fs-f2fs index 36c3cb547901..99fa87a43926 100644 --- a/Documentation/ABI/testing/sysfs-fs-f2fs +++ b/Documentation/ABI/testing/sysfs-fs-f2fs @@ -498,6 +498,21 @@ Description: Show status of f2fs checkpoint in real time. CP_RESIZEFS_FLAG 0x00004000 =============================== ============================== +What: /sys/fs/f2fs/<disk>/stat/issued_discard +Date: December 2023 +Contact: "Zhiguo Niu" <zhiguo.niu@unisoc.com> +Description: Shows the number of issued discard. + +What: /sys/fs/f2fs/<disk>/stat/queued_discard +Date: December 2023 +Contact: "Zhiguo Niu" <zhiguo.niu@unisoc.com> +Description: Shows the number of queued discard. + +What: /sys/fs/f2fs/<disk>/stat/undiscard_blks +Date: December 2023 +Contact: "Zhiguo Niu" <zhiguo.niu@unisoc.com> +Description: Shows the total number of undiscard blocks. + What: /sys/fs/f2fs/<disk>/ckpt_thread_ioprio Date: January 2021 Contact: "Daeho Jeong" <daehojeong@google.com> @@ -740,3 +755,9 @@ Description: When compress cache is on, it controls cached page If cached page percent exceed threshold, then deny caching compress page. The value should be in range of (0, 100], by default it was initialized as 20(%). + +What: /sys/fs/f2fs/<disk>/discard_io_aware +Date: November 2023 +Contact: "Chao Yu" <chao@kernel.org> +Description: It controls to enable/disable IO aware feature for background discard. + By default, the value is 1 which indicates IO aware is on. diff --git a/Documentation/ABI/testing/sysfs-kernel-mm-damon b/Documentation/ABI/testing/sysfs-kernel-mm-damon index b35649a46a2f..bfa5b8288d8d 100644 --- a/Documentation/ABI/testing/sysfs-kernel-mm-damon +++ b/Documentation/ABI/testing/sysfs-kernel-mm-damon @@ -25,12 +25,14 @@ Description: Writing 'on' or 'off' to this file makes the kdamond starts or stops, respectively. Reading the file returns the keywords based on the current status. Writing 'commit' to this file makes the kdamond reads the user inputs in the sysfs files - except 'state' again. Writing 'update_schemes_stats' to the - file updates contents of schemes stats files of the kdamond. - Writing 'update_schemes_tried_regions' to the file updates - contents of 'tried_regions' directory of every scheme directory - of this kdamond. Writing 'update_schemes_tried_bytes' to the - file updates only '.../tried_regions/total_bytes' files of this + except 'state' again. Writing 'commit_schemes_quota_goals' to + this file makes the kdamond reads the quota goal files again. + Writing 'update_schemes_stats' to the file updates contents of + schemes stats files of the kdamond. Writing + 'update_schemes_tried_regions' to the file updates contents of + 'tried_regions' directory of every scheme directory of this + kdamond. Writing 'update_schemes_tried_bytes' to the file + updates only '.../tried_regions/total_bytes' files of this kdamond. Writing 'clear_schemes_tried_regions' to the file removes contents of the 'tried_regions' directory. @@ -212,6 +214,25 @@ Contact: SeongJae Park <sj@kernel.org> Description: Writing to and reading from this file sets and gets the quotas charge reset interval of the scheme in milliseconds. +What: /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/quotas/goals/nr_goals +Date: Nov 2023 +Contact: SeongJae Park <sj@kernel.org> +Description: Writing a number 'N' to this file creates the number of + directories for setting automatic tuning of the scheme's + aggressiveness named '0' to 'N-1' under the goals/ directory. + +What: /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/quotas/goals/<G>/target_value +Date: Nov 2023 +Contact: SeongJae Park <sj@kernel.org> +Description: Writing to and reading from this file sets and gets the target + value of the goal metric. + +What: /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/quotas/goals/<G>/current_value +Date: Nov 2023 +Contact: SeongJae Park <sj@kernel.org> +Description: Writing to and reading from this file sets and gets the current + value of the goal metric. + What: /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/quotas/weights/sz_permil Date: Mar 2022 Contact: SeongJae Park <sj@kernel.org> diff --git a/Documentation/ABI/testing/sysfs-platform-silicom b/Documentation/ABI/testing/sysfs-platform-silicom new file mode 100644 index 000000000000..2288b3665d16 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-platform-silicom @@ -0,0 +1,29 @@ +What: /sys/devices/platform/silicom-platform/uc_version +Date: November 2023 +KernelVersion: 6.7 +Contact: Henry Shi <henrys@silicom-usa.com> +Description: + This file allows to read microcontroller firmware + version of current platform. + +What: /sys/devices/platform/silicom-platform/power_cycle +Date: November 2023 +KernelVersion: 6.7 +Contact: Henry Shi <henrys@silicom-usa.com> + This file allow user to power cycle the platform. + Default value is 0; when set to 1, it powers down + the platform, waits 5 seconds, then powers on the + device. It returns to default value after power cycle. + + 0 - default value. + +What: /sys/devices/platform/silicom-platform/efuse_status +Date: November 2023 +KernelVersion: 6.7 +Contact: Henry Shi <henrys@silicom-usa.com> +Description: + This file is read only. It returns the current + OTP status: + + 0 - not programmed. + 1 - programmed. diff --git a/Documentation/Makefile b/Documentation/Makefile index 2f35793acd2a..3885bbe260eb 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -97,7 +97,21 @@ quiet_cmd_sphinx = SPHINX $@ --> file://$(abspath $(BUILDDIR)/$3/$4) cp $(if $(patsubst /%,,$(DOCS_CSS)),$(abspath $(srctree)/$(DOCS_CSS)),$(DOCS_CSS)) $(BUILDDIR)/$3/_static/; \ fi -htmldocs: +YNL_INDEX:=$(srctree)/Documentation/networking/netlink_spec/index.rst +YNL_RST_DIR:=$(srctree)/Documentation/networking/netlink_spec +YNL_YAML_DIR:=$(srctree)/Documentation/netlink/specs +YNL_TOOL:=$(srctree)/tools/net/ynl/ynl-gen-rst.py + +YNL_RST_FILES_TMP := $(patsubst %.yaml,%.rst,$(wildcard $(YNL_YAML_DIR)/*.yaml)) +YNL_RST_FILES := $(patsubst $(YNL_YAML_DIR)%,$(YNL_RST_DIR)%, $(YNL_RST_FILES_TMP)) + +$(YNL_INDEX): $(YNL_RST_FILES) + $(Q)$(YNL_TOOL) -o $@ -x + +$(YNL_RST_DIR)/%.rst: $(YNL_YAML_DIR)/%.yaml $(YNL_TOOL) + $(Q)$(YNL_TOOL) -i $< -o $@ + +htmldocs: $(YNL_INDEX) @$(srctree)/scripts/sphinx-pre-install --version-check @+$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,html,$(var),,$(var))) diff --git a/Documentation/RAS/ras.rst b/Documentation/RAS/ras.rst new file mode 100644 index 000000000000..2556b397cd27 --- /dev/null +++ b/Documentation/RAS/ras.rst @@ -0,0 +1,26 @@ +.. SPDX-License-Identifier: GPL-2.0 + +Reliability, Availability and Serviceability features +===================================================== + +This documents different aspects of the RAS functionality present in the +kernel. + +Error decoding +--------------- + +* x86 + +Error decoding on AMD systems should be done using the rasdaemon tool: +https://github.com/mchehab/rasdaemon/ + +While the daemon is running, it would automatically log and decode +errors. If not, one can still decode such errors by supplying the +hardware information from the error:: + + $ rasdaemon -p --status <STATUS> --ipid <IPID> --smca + +Also, the user can pass particular family and model to decode the error +string:: + + $ rasdaemon -p --status <STATUS> --ipid <IPID> --smca --family <CPU Family> --model <CPU Model> --bank <BANK_NUM> diff --git a/Documentation/admin-guide/abi-obsolete.rst b/Documentation/admin-guide/abi-obsolete.rst index d095867899c5..594e697aa1b2 100644 --- a/Documentation/admin-guide/abi-obsolete.rst +++ b/Documentation/admin-guide/abi-obsolete.rst @@ -7,5 +7,5 @@ marked to be removed at some later point in time. The description of the interface will document the reason why it is obsolete and when it can be expected to be removed. -.. kernel-abi:: $srctree/Documentation/ABI/obsolete +.. kernel-abi:: ABI/obsolete :rst: diff --git a/Documentation/admin-guide/abi-removed.rst b/Documentation/admin-guide/abi-removed.rst index f7e9e43023c1..f9e000c81828 100644 --- a/Documentation/admin-guide/abi-removed.rst +++ b/Documentation/admin-guide/abi-removed.rst @@ -1,5 +1,5 @@ ABI removed symbols =================== -.. kernel-abi:: $srctree/Documentation/ABI/removed +.. kernel-abi:: ABI/removed :rst: diff --git a/Documentation/admin-guide/abi-stable.rst b/Documentation/admin-guide/abi-stable.rst index 70490736e0d3..fc3361d847b1 100644 --- a/Documentation/admin-guide/abi-stable.rst +++ b/Documentation/admin-guide/abi-stable.rst @@ -10,5 +10,5 @@ for at least 2 years. Most interfaces (like syscalls) are expected to never change and always be available. -.. kernel-abi:: $srctree/Documentation/ABI/stable +.. kernel-abi:: ABI/stable :rst: diff --git a/Documentation/admin-guide/abi-testing.rst b/Documentation/admin-guide/abi-testing.rst index b205b16a72d0..19767926b344 100644 --- a/Documentation/admin-guide/abi-testing.rst +++ b/Documentation/admin-guide/abi-testing.rst @@ -16,5 +16,5 @@ Programs that use these interfaces are strongly encouraged to add their name to the description of these interfaces, so that the kernel developers can easily notify them if any changes occur. -.. kernel-abi:: $srctree/Documentation/ABI/testing +.. kernel-abi:: ABI/testing :rst: diff --git a/Documentation/admin-guide/blockdev/zram.rst b/Documentation/admin-guide/blockdev/zram.rst index e4551579cb12..ee2b0030d416 100644 --- a/Documentation/admin-guide/blockdev/zram.rst +++ b/Documentation/admin-guide/blockdev/zram.rst @@ -328,7 +328,7 @@ as idle:: From now on, any pages on zram are idle pages. The idle mark will be removed until someone requests access of the block. IOW, unless there is access request, those pages are still idle pages. -Additionally, when CONFIG_ZRAM_MEMORY_TRACKING is enabled pages can be +Additionally, when CONFIG_ZRAM_TRACK_ENTRY_ACTIME is enabled pages can be marked as idle based on how long (in seconds) it's been since they were last accessed:: diff --git a/Documentation/admin-guide/cgroup-v2.rst b/Documentation/admin-guide/cgroup-v2.rst index 3f85254f3cef..17e6e9565156 100644 --- a/Documentation/admin-guide/cgroup-v2.rst +++ b/Documentation/admin-guide/cgroup-v2.rst @@ -1093,7 +1093,11 @@ All time durations are in microseconds. A read-write single value file which exists on non-root cgroups. The default is "100". - The weight in the range [1, 10000]. + For non idle groups (cpu.idle = 0), the weight is in the + range [1, 10000]. + + If the cgroup has been configured to be SCHED_IDLE (cpu.idle = 1), + then the weight will show as a 0. cpu.weight.nice A read-write single value file which exists on non-root @@ -1157,6 +1161,16 @@ All time durations are in microseconds. values similar to the sched_setattr(2). This maximum utilization value is used to clamp the task specific maximum utilization clamp. + cpu.idle + A read-write single value file which exists on non-root cgroups. + The default is 0. + + This is the cgroup analog of the per-task SCHED_IDLE sched policy. + Setting this value to a 1 will make the scheduling policy of the + cgroup SCHED_IDLE. The threads inside the cgroup will retain their + own relative priorities, but the cgroup itself will be treated as + very low priority relative to its peers. + Memory @@ -1679,6 +1693,21 @@ PAGE_SIZE multiple when read back. limit, it will refuse to take any more stores before existing entries fault back in or are written out to disk. + memory.zswap.writeback + A read-write single value file. The default value is "1". The + initial value of the root cgroup is 1, and when a new cgroup is + created, it inherits the current value of its parent. + + When this is set to 0, all swapping attempts to swapping devices + are disabled. This included both zswap writebacks, and swapping due + to zswap store failures. If the zswap store failures are recurring + (for e.g if the pages are incompressible), users can observe + reclaim inefficiency after disabling writeback (because the same + pages might be rejected again and again). + + Note that this is subtly different from setting memory.swap.max to + 0, as it still allows for pages to be written to the zswap pool. + memory.pressure A read-only nested-keyed file. @@ -2316,6 +2345,13 @@ Cpuset Interface Files treated to have an implicit value of "cpuset.cpus" in the formation of local partition. + cpuset.cpus.isolated + A read-only and root cgroup only multiple values file. + + This file shows the set of all isolated CPUs used in existing + isolated partitions. It will be empty if no isolated partition + is created. + cpuset.cpus.partition A read-write single value file which exists on non-root cpuset-enabled cgroups. This flag is owned by the parent cgroup @@ -2358,11 +2394,11 @@ Cpuset Interface Files partition or scheduling domain. The set of exclusive CPUs is determined by the value of its "cpuset.cpus.exclusive.effective". - When set to "isolated", the CPUs in that partition will - be in an isolated state without any load balancing from the - scheduler. Tasks placed in such a partition with multiple - CPUs should be carefully distributed and bound to each of the - individual CPUs for optimal performance. + When set to "isolated", the CPUs in that partition will be in + an isolated state without any load balancing from the scheduler + and excluded from the unbound workqueues. Tasks placed in such + a partition with multiple CPUs should be carefully distributed + and bound to each of the individual CPUs for optimal performance. A partition root ("root" or "isolated") can be in one of the two possible states - valid or invalid. An invalid partition diff --git a/Documentation/admin-guide/dynamic-debug-howto.rst b/Documentation/admin-guide/dynamic-debug-howto.rst index 0c526dac8428..0e9b48daf690 100644 --- a/Documentation/admin-guide/dynamic-debug-howto.rst +++ b/Documentation/admin-guide/dynamic-debug-howto.rst @@ -321,13 +321,13 @@ Examples :#> ddcmd 'format "nfsd: READ" +p' // enable messages in files of which the paths include string "usb" - :#> ddcmd 'file *usb* +p' > /proc/dynamic_debug/control + :#> ddcmd 'file *usb* +p' // enable all messages - :#> ddcmd '+p' > /proc/dynamic_debug/control + :#> ddcmd '+p' // add module, function to all enabled messages - :#> ddcmd '+mf' > /proc/dynamic_debug/control + :#> ddcmd '+mf' // boot-args example, with newlines and comments for readability Kernel command line: ... diff --git a/Documentation/admin-guide/index.rst b/Documentation/admin-guide/index.rst index 43ea35613dfc..fb40a1f6f79e 100644 --- a/Documentation/admin-guide/index.rst +++ b/Documentation/admin-guide/index.rst @@ -119,6 +119,7 @@ configure specific aspects of kernel behavior to your liking. parport perf-security pm/index + pmf pnp rapidio ras diff --git a/Documentation/admin-guide/kdump/vmcoreinfo.rst b/Documentation/admin-guide/kdump/vmcoreinfo.rst index 78e4d2e7ba14..bced9e4b6e08 100644 --- a/Documentation/admin-guide/kdump/vmcoreinfo.rst +++ b/Documentation/admin-guide/kdump/vmcoreinfo.rst @@ -172,7 +172,7 @@ variables. Offset of the free_list's member. This value is used to compute the number of free pages. -Each zone has a free_area structure array called free_area[MAX_ORDER + 1]. +Each zone has a free_area structure array called free_area[NR_PAGE_ORDERS]. The free_list represents a linked list of free page blocks. (list_head, next|prev) @@ -189,11 +189,11 @@ Offsets of the vmap_area's members. They carry vmalloc-specific information. Makedumpfile gets the start address of the vmalloc region from this. -(zone.free_area, MAX_ORDER + 1) -------------------------------- +(zone.free_area, NR_PAGE_ORDERS) +-------------------------------- Free areas descriptor. User-space tools use this value to iterate the -free_area ranges. MAX_ORDER is used by the zone buddy allocator. +free_area ranges. NR_PAGE_ORDERS is used by the zone buddy allocator. prb --- diff --git a/Documentation/admin-guide/kernel-parameters.txt b/Documentation/admin-guide/kernel-parameters.txt index 65731b060e3f..505af40e97bc 100644 --- a/Documentation/admin-guide/kernel-parameters.txt +++ b/Documentation/admin-guide/kernel-parameters.txt @@ -1,3 +1,14 @@ + accept_memory= [MM] + Format: { eager | lazy } + default: lazy + By default, unaccepted memory is accepted lazily to + avoid prolonged boot times. The lazy option will add + some runtime overhead until all memory is eventually + accepted. In most cases the overhead is negligible. + For some workloads or for debugging purposes + accept_memory=eager can be used to accept all memory + at once during boot. + acpi= [HW,ACPI,X86,ARM64,RISCV64] Advanced Configuration and Power Interface Format: { force | on | off | strict | noirq | rsdt | @@ -970,17 +981,17 @@ buddy allocator. Bigger value increase the probability of catching random memory corruption, but reduce the amount of memory for normal system use. The maximum - possible value is MAX_ORDER/2. Setting this parameter - to 1 or 2 should be enough to identify most random - memory corruption problems caused by bugs in kernel or - driver code when a CPU writes to (or reads from) a - random memory location. Note that there exists a class - of memory corruptions problems caused by buggy H/W or - F/W or by drivers badly programming DMA (basically when - memory is written at bus level and the CPU MMU is - bypassed) which are not detectable by - CONFIG_DEBUG_PAGEALLOC, hence this option will not help - tracking down these problems. + possible value is MAX_PAGE_ORDER/2. Setting this + parameter to 1 or 2 should be enough to identify most + random memory corruption problems caused by bugs in + kernel or driver code when a CPU writes to (or reads + from) a random memory location. Note that there exists + a class of memory corruptions problems caused by buggy + H/W or F/W or by drivers badly programming DMA + (basically when memory is written at bus level and the + CPU MMU is bypassed) which are not detectable by + CONFIG_DEBUG_PAGEALLOC, hence this option will not + help tracking down these problems. debug_pagealloc= [KNL] When CONFIG_DEBUG_PAGEALLOC is set, this parameter @@ -4136,7 +4147,7 @@ [KNL] Minimal page reporting order Format: <integer> Adjust the minimal page reporting order. The page - reporting is disabled when it exceeds MAX_ORDER. + reporting is disabled when it exceeds MAX_PAGE_ORDER. panic= [KNL] Kernel behaviour on panic: delay <timeout> timeout > 0: seconds before rebooting @@ -5544,6 +5555,13 @@ print every Nth verbose statement, where N is the value specified. + regulator_ignore_unused + [REGULATOR] + Prevents regulator framework from disabling regulators + that are unused, due no driver claiming them. This may + be useful for debug and development, but should not be + needed on a platform with proper driver support. + relax_domain_level= [KNL, SMP] Set scheduler's default relax_domain_level. See Documentation/admin-guide/cgroup-v1/cpusets.rst. diff --git a/Documentation/admin-guide/media/index.rst b/Documentation/admin-guide/media/index.rst index 43f4a292b245..be7e0e4482ca 100644 --- a/Documentation/admin-guide/media/index.rst +++ b/Documentation/admin-guide/media/index.rst @@ -20,16 +20,8 @@ Documentation/driver-api/media/index.rst - for driver development information and Kernel APIs used by media devices; -The media subsystem -=================== - -.. only:: html - - .. class:: toc-title - - Table of Contents - .. toctree:: + :caption: Table of Contents :maxdepth: 2 :numbered: diff --git a/Documentation/admin-guide/mm/damon/usage.rst b/Documentation/admin-guide/mm/damon/usage.rst index da94feb97ed1..9d23144bf985 100644 --- a/Documentation/admin-guide/mm/damon/usage.rst +++ b/Documentation/admin-guide/mm/damon/usage.rst @@ -59,41 +59,47 @@ Files Hierarchy The files hierarchy of DAMON sysfs interface is shown below. In the below figure, parents-children relations are represented with indentations, each directory is having ``/`` suffix, and files in each directory are separated by -comma (","). :: - - /sys/kernel/mm/damon/admin - │ kdamonds/nr_kdamonds - │ │ 0/state,pid - │ │ │ contexts/nr_contexts - │ │ │ │ 0/avail_operations,operations - │ │ │ │ │ monitoring_attrs/ +comma (","). + +.. parsed-literal:: + + :ref:`/sys/kernel/mm/damon <sysfs_root>`/admin + │ :ref:`kdamonds <sysfs_kdamonds>`/nr_kdamonds + │ │ :ref:`0 <sysfs_kdamond>`/state,pid + │ │ │ :ref:`contexts <sysfs_contexts>`/nr_contexts + │ │ │ │ :ref:`0 <sysfs_context>`/avail_operations,operations + │ │ │ │ │ :ref:`monitoring_attrs <sysfs_monitoring_attrs>`/ │ │ │ │ │ │ intervals/sample_us,aggr_us,update_us │ │ │ │ │ │ nr_regions/min,max - │ │ │ │ │ targets/nr_targets - │ │ │ │ │ │ 0/pid_target - │ │ │ │ │ │ │ regions/nr_regions - │ │ │ │ │ │ │ │ 0/start,end + │ │ │ │ │ :ref:`targets <sysfs_targets>`/nr_targets + │ │ │ │ │ │ :ref:`0 <sysfs_target>`/pid_target + │ │ │ │ │ │ │ :ref:`regions <sysfs_regions>`/nr_regions + │ │ │ │ │ │ │ │ :ref:`0 <sysfs_region>`/start,end │ │ │ │ │ │ │ │ ... │ │ │ │ │ │ ... - │ │ │ │ │ schemes/nr_schemes - │ │ │ │ │ │ 0/action,apply_interval_us - │ │ │ │ │ │ │ access_pattern/ + │ │ │ │ │ :ref:`schemes <sysfs_schemes>`/nr_schemes + │ │ │ │ │ │ :ref:`0 <sysfs_scheme>`/action,apply_interval_us + │ │ │ │ │ │ │ :ref:`access_pattern <sysfs_access_pattern>`/ │ │ │ │ │ │ │ │ sz/min,max │ │ │ │ │ │ │ │ nr_accesses/min,max │ │ │ │ │ │ │ │ age/min,max - │ │ │ │ │ │ │ quotas/ms,bytes,reset_interval_ms + │ │ │ │ │ │ │ :ref:`quotas <sysfs_quotas>`/ms,bytes,reset_interval_ms │ │ │ │ │ │ │ │ weights/sz_permil,nr_accesses_permil,age_permil - │ │ │ │ │ │ │ watermarks/metric,interval_us,high,mid,low - │ │ │ │ │ │ │ filters/nr_filters + │ │ │ │ │ │ │ │ :ref:`goals <sysfs_schemes_quota_goals>`/nr_goals + │ │ │ │ │ │ │ │ │ 0/target_value,current_value + │ │ │ │ │ │ │ :ref:`watermarks <sysfs_watermarks>`/metric,interval_us,high,mid,low + │ │ │ │ │ │ │ :ref:`filters <sysfs_filters>`/nr_filters │ │ │ │ │ │ │ │ 0/type,matching,memcg_id - │ │ │ │ │ │ │ stats/nr_tried,sz_tried,nr_applied,sz_applied,qt_exceeds - │ │ │ │ │ │ │ tried_regions/total_bytes + │ │ │ │ │ │ │ :ref:`stats <sysfs_schemes_stats>`/nr_tried,sz_tried,nr_applied,sz_applied,qt_exceeds + │ │ │ │ │ │ │ :ref:`tried_regions <sysfs_schemes_tried_regions>`/total_bytes │ │ │ │ │ │ │ │ 0/start,end,nr_accesses,age │ │ │ │ │ │ │ │ ... │ │ │ │ │ │ ... │ │ │ │ ... │ │ ... +.. _sysfs_root: + Root ---- @@ -102,6 +108,8 @@ has one directory named ``admin``. The directory contains the files for privileged user space programs' control of DAMON. User space tools or daemons having the root permission could use this directory. +.. _sysfs_kdamonds: + kdamonds/ --------- @@ -113,6 +121,8 @@ details) exists. In the beginning, this directory has only one file, child directories named ``0`` to ``N-1``. Each directory represents each kdamond. +.. _sysfs_kdamond: + kdamonds/<N>/ ------------- @@ -120,29 +130,37 @@ In each kdamond directory, two files (``state`` and ``pid``) and one directory (``contexts``) exist. Reading ``state`` returns ``on`` if the kdamond is currently running, or -``off`` if it is not running. Writing ``on`` or ``off`` makes the kdamond be -in the state. Writing ``commit`` to the ``state`` file makes kdamond reads the -user inputs in the sysfs files except ``state`` file again. Writing -``update_schemes_stats`` to ``state`` file updates the contents of stats files -for each DAMON-based operation scheme of the kdamond. For details of the -stats, please refer to :ref:`stats section <sysfs_schemes_stats>`. - -Writing ``update_schemes_tried_regions`` to ``state`` file updates the -DAMON-based operation scheme action tried regions directory for each -DAMON-based operation scheme of the kdamond. Writing -``update_schemes_tried_bytes`` to ``state`` file updates only -``.../tried_regions/total_bytes`` files. Writing -``clear_schemes_tried_regions`` to ``state`` file clears the DAMON-based -operating scheme action tried regions directory for each DAMON-based operation -scheme of the kdamond. For details of the DAMON-based operation scheme action -tried regions directory, please refer to :ref:`tried_regions section -<sysfs_schemes_tried_regions>`. +``off`` if it is not running. + +Users can write below commands for the kdamond to the ``state`` file. + +- ``on``: Start running. +- ``off``: Stop running. +- ``commit``: Read the user inputs in the sysfs files except ``state`` file + again. +- ``commit_schemes_quota_goals``: Read the DAMON-based operation schemes' + :ref:`quota goals <sysfs_schemes_quota_goals>`. +- ``update_schemes_stats``: Update the contents of stats files for each + DAMON-based operation scheme of the kdamond. For details of the stats, + please refer to :ref:`stats section <sysfs_schemes_stats>`. +- ``update_schemes_tried_regions``: Update the DAMON-based operation scheme + action tried regions directory for each DAMON-based operation scheme of the + kdamond. For details of the DAMON-based operation scheme action tried + regions directory, please refer to + :ref:`tried_regions section <sysfs_schemes_tried_regions>`. +- ``update_schemes_tried_bytes``: Update only ``.../tried_regions/total_bytes`` + files. +- ``clear_schemes_tried_regions``: Clear the DAMON-based operating scheme + action tried regions directory for each DAMON-based operation scheme of the + kdamond. If the state is ``on``, reading ``pid`` shows the pid of the kdamond thread. ``contexts`` directory contains files for controlling the monitoring contexts that this kdamond will execute. +.. _sysfs_contexts: + kdamonds/<N>/contexts/ ---------------------- @@ -153,7 +171,7 @@ number (``N``) to the file creates the number of child directories named as details). At the moment, only one context per kdamond is supported, so only ``0`` or ``1`` can be written to the file. -.. _sysfs_contexts: +.. _sysfs_context: contexts/<N>/ ------------- @@ -203,6 +221,8 @@ writing to and rading from the files. For more details about the intervals and monitoring regions range, please refer to the Design document (:doc:`/mm/damon/design`). +.. _sysfs_targets: + contexts/<N>/targets/ --------------------- @@ -210,6 +230,8 @@ In the beginning, this directory has only one file, ``nr_targets``. Writing a number (``N``) to the file creates the number of child directories named ``0`` to ``N-1``. Each directory represents each monitoring target. +.. _sysfs_target: + targets/<N>/ ------------ @@ -244,6 +266,8 @@ In the beginning, this directory has only one file, ``nr_regions``. Writing a number (``N``) to the file creates the number of child directories named ``0`` to ``N-1``. Each directory represents each initial monitoring target region. +.. _sysfs_region: + regions/<N>/ ------------ @@ -254,6 +278,8 @@ region by writing to and reading from the files, respectively. Each region should not overlap with others. ``end`` of directory ``N`` should be equal or smaller than ``start`` of directory ``N+1``. +.. _sysfs_schemes: + contexts/<N>/schemes/ --------------------- @@ -265,6 +291,8 @@ In the beginning, this directory has only one file, ``nr_schemes``. Writing a number (``N``) to the file creates the number of child directories named ``0`` to ``N-1``. Each directory represents each DAMON-based operation scheme. +.. _sysfs_scheme: + schemes/<N>/ ------------ @@ -277,7 +305,7 @@ The ``action`` file is for setting and getting the scheme's :ref:`action from the file and their meaning are as below. Note that support of each action depends on the running DAMON operations set -:ref:`implementation <sysfs_contexts>`. +:ref:`implementation <sysfs_context>`. - ``willneed``: Call ``madvise()`` for the region with ``MADV_WILLNEED``. Supported by ``vaddr`` and ``fvaddr`` operations set. @@ -299,6 +327,8 @@ Note that support of each action depends on the running DAMON operations set The ``apply_interval_us`` file is for setting and getting the scheme's :ref:`apply_interval <damon_design_damos>` in microseconds. +.. _sysfs_access_pattern: + schemes/<N>/access_pattern/ --------------------------- @@ -312,6 +342,8 @@ to and reading from the ``min`` and ``max`` files under ``sz``, ``nr_accesses``, and ``age`` directories, respectively. Note that the ``min`` and the ``max`` form a closed interval. +.. _sysfs_quotas: + schemes/<N>/quotas/ ------------------- @@ -319,8 +351,7 @@ The directory for the :ref:`quotas <damon_design_damos_quotas>` of the given DAMON-based operation scheme. Under ``quotas`` directory, three files (``ms``, ``bytes``, -``reset_interval_ms``) and one directory (``weights``) having three files -(``sz_permil``, ``nr_accesses_permil``, and ``age_permil``) in it exist. +``reset_interval_ms``) and two directores (``weights`` and ``goals``) exist. You can set the ``time quota`` in milliseconds, ``size quota`` in bytes, and ``reset interval`` in milliseconds by writing the values to the three files, @@ -330,11 +361,37 @@ apply the action to only up to ``bytes`` bytes of memory regions within the ``reset_interval_ms``. Setting both ``ms`` and ``bytes`` zero disables the quota limits. -You can also set the :ref:`prioritization weights +Under ``weights`` directory, three files (``sz_permil``, +``nr_accesses_permil``, and ``age_permil``) exist. +You can set the :ref:`prioritization weights <damon_design_damos_quotas_prioritization>` for size, access frequency, and age in per-thousand unit by writing the values to the three files under the ``weights`` directory. +.. _sysfs_schemes_quota_goals: + +schemes/<N>/quotas/goals/ +------------------------- + +The directory for the :ref:`automatic quota tuning goals +<damon_design_damos_quotas_auto_tuning>` of the given DAMON-based operation +scheme. + +In the beginning, this directory has only one file, ``nr_goals``. Writing a +number (``N``) to the file creates the number of child directories named ``0`` +to ``N-1``. Each directory represents each goal and current achievement. +Among the multiple feedback, the best one is used. + +Each goal directory contains two files, namely ``target_value`` and +``current_value``. Users can set and get any number to those files to set the +feedback. User space main workload's latency or throughput, system metrics +like free memory ratio or memory pressure stall time (PSI) could be example +metrics for the values. Note that users should write +``commit_schemes_quota_goals`` to the ``state`` file of the :ref:`kdamond +directory <sysfs_kdamond>` to pass the feedback to DAMON. + +.. _sysfs_watermarks: + schemes/<N>/watermarks/ ----------------------- @@ -354,6 +411,8 @@ as below. The ``interval`` should written in microseconds unit. +.. _sysfs_filters: + schemes/<N>/filters/ -------------------- @@ -394,7 +453,7 @@ pages of all memory cgroups except ``/having_care_already``.:: echo N > 1/matching Note that ``anon`` and ``memcg`` filters are currently supported only when -``paddr`` :ref:`implementation <sysfs_contexts>` is being used. +``paddr`` :ref:`implementation <sysfs_context>` is being used. Also, memory regions that are filtered out by ``addr`` or ``target`` filters are not counted as the scheme has tried to those, while regions that filtered @@ -449,6 +508,8 @@ and query-like efficient data access monitoring results retrievals. For the latter use case, in particular, users can set the ``action`` as ``stat`` and set the ``access pattern`` as their interested pattern that they want to query. +.. _sysfs_schemes_tried_region: + tried_regions/<N>/ ------------------ diff --git a/Documentation/admin-guide/mm/ksm.rst b/Documentation/admin-guide/mm/ksm.rst index e59231ac6bb7..a639cac12477 100644 --- a/Documentation/admin-guide/mm/ksm.rst +++ b/Documentation/admin-guide/mm/ksm.rst @@ -80,6 +80,9 @@ pages_to_scan how many pages to scan before ksmd goes to sleep e.g. ``echo 100 > /sys/kernel/mm/ksm/pages_to_scan``. + The pages_to_scan value cannot be changed if ``advisor_mode`` has + been set to scan-time. + Default: 100 (chosen for demonstration purposes) sleep_millisecs @@ -164,6 +167,29 @@ smart_scan optimization is enabled. The ``pages_skipped`` metric shows how effective the setting is. +advisor_mode + The ``advisor_mode`` selects the current advisor. Two modes are + supported: none and scan-time. The default is none. By setting + ``advisor_mode`` to scan-time, the scan time advisor is enabled. + The section about ``advisor`` explains in detail how the scan time + advisor works. + +adivsor_max_cpu + specifies the upper limit of the cpu percent usage of the ksmd + background thread. The default is 70. + +advisor_target_scan_time + specifies the target scan time in seconds to scan all the candidate + pages. The default value is 200 seconds. + +advisor_min_pages_to_scan + specifies the lower limit of the ``pages_to_scan`` parameter of the + scan time advisor. The default is 500. + +adivsor_max_pages_to_scan + specifies the upper limit of the ``pages_to_scan`` parameter of the + scan time advisor. The default is 30000. + The effectiveness of KSM and MADV_MERGEABLE is shown in ``/sys/kernel/mm/ksm/``: general_profit @@ -263,6 +289,35 @@ ksm_swpin_copy note that KSM page might be copied when swapping in because do_swap_page() cannot do all the locking needed to reconstitute a cross-anon_vma KSM page. +Advisor +======= + +The number of candidate pages for KSM is dynamic. It can be often observed +that during the startup of an application more candidate pages need to be +processed. Without an advisor the ``pages_to_scan`` parameter needs to be +sized for the maximum number of candidate pages. The scan time advisor can +changes the ``pages_to_scan`` parameter based on demand. + +The advisor can be enabled, so KSM can automatically adapt to changes in the +number of candidate pages to scan. Two advisors are implemented: none and +scan-time. With none, no advisor is enabled. The default is none. + +The scan time advisor changes the ``pages_to_scan`` parameter based on the +observed scan times. The possible values for the ``pages_to_scan`` parameter is +limited by the ``advisor_max_cpu`` parameter. In addition there is also the +``advisor_target_scan_time`` parameter. This parameter sets the target time to +scan all the KSM candidate pages. The parameter ``advisor_target_scan_time`` +decides how aggressive the scan time advisor scans candidate pages. Lower +values make the scan time advisor to scan more aggresively. This is the most +important parameter for the configuration of the scan time advisor. + +The initial value and the maximum value can be changed with +``advisor_min_pages_to_scan`` and ``advisor_max_pages_to_scan``. The default +values are sufficient for most workloads and use cases. + +The ``pages_to_scan`` parameter is re-calculated after a scan has been completed. + + -- Izik Eidus, Hugh Dickins, 17 Nov 2009 diff --git a/Documentation/admin-guide/mm/pagemap.rst b/Documentation/admin-guide/mm/pagemap.rst index fe17cf210426..f5f065c67615 100644 --- a/Documentation/admin-guide/mm/pagemap.rst +++ b/Documentation/admin-guide/mm/pagemap.rst @@ -253,6 +253,7 @@ Following flags about pages are currently supported: - ``PAGE_IS_SWAPPED`` - Page is in swapped - ``PAGE_IS_PFNZERO`` - Page has zero PFN - ``PAGE_IS_HUGE`` - Page is THP or Hugetlb backed +- ``PAGE_IS_SOFT_DIRTY`` - Page is soft-dirty The ``struct pm_scan_arg`` is used as the argument of the IOCTL. diff --git a/Documentation/admin-guide/mm/transhuge.rst b/Documentation/admin-guide/mm/transhuge.rst index b0cc8243e093..04eb45a2f940 100644 --- a/Documentation/admin-guide/mm/transhuge.rst +++ b/Documentation/admin-guide/mm/transhuge.rst @@ -45,10 +45,25 @@ components: the two is using hugepages just because of the fact the TLB miss is going to run faster. +Modern kernels support "multi-size THP" (mTHP), which introduces the +ability to allocate memory in blocks that are bigger than a base page +but smaller than traditional PMD-size (as described above), in +increments of a power-of-2 number of pages. mTHP can back anonymous +memory (for example 16K, 32K, 64K, etc). These THPs continue to be +PTE-mapped, but in many cases can still provide similar benefits to +those outlined above: Page faults are significantly reduced (by a +factor of e.g. 4, 8, 16, etc), but latency spikes are much less +prominent because the size of each page isn't as huge as the PMD-sized +variant and there is less memory to clear in each page fault. Some +architectures also employ TLB compression mechanisms to squeeze more +entries in when a set of PTEs are virtually and physically contiguous +and approporiately aligned. In this case, TLB misses will occur less +often. + THP can be enabled system wide or restricted to certain tasks or even memory ranges inside task's address space. Unless THP is completely disabled, there is ``khugepaged`` daemon that scans memory and -collapses sequences of basic pages into huge pages. +collapses sequences of basic pages into PMD-sized huge pages. The THP behaviour is controlled via :ref:`sysfs <thp_sysfs>` interface and using madvise(2) and prctl(2) system calls. @@ -95,12 +110,40 @@ Global THP controls Transparent Hugepage Support for anonymous memory can be entirely disabled (mostly for debugging purposes) or only enabled inside MADV_HUGEPAGE regions (to avoid the risk of consuming more memory resources) or enabled -system wide. This can be achieved with one of:: +system wide. This can be achieved per-supported-THP-size with one of:: + + echo always >/sys/kernel/mm/transparent_hugepage/hugepages-<size>kB/enabled + echo madvise >/sys/kernel/mm/transparent_hugepage/hugepages-<size>kB/enabled + echo never >/sys/kernel/mm/transparent_hugepage/hugepages-<size>kB/enabled + +where <size> is the hugepage size being addressed, the available sizes +for which vary by system. + +For example:: + + echo always >/sys/kernel/mm/transparent_hugepage/hugepages-2048kB/enabled + +Alternatively it is possible to specify that a given hugepage size +will inherit the top-level "enabled" value:: + + echo inherit >/sys/kernel/mm/transparent_hugepage/hugepages-<size>kB/enabled + +For example:: + + echo inherit >/sys/kernel/mm/transparent_hugepage/hugepages-2048kB/enabled + +The top-level setting (for use with "inherit") can be set by issuing +one of the following commands:: echo always >/sys/kernel/mm/transparent_hugepage/enabled echo madvise >/sys/kernel/mm/transparent_hugepage/enabled echo never >/sys/kernel/mm/transparent_hugepage/enabled +By default, PMD-sized hugepages have enabled="inherit" and all other +hugepage sizes have enabled="never". If enabling multiple hugepage +sizes, the kernel will select the most appropriate enabled size for a +given allocation. + It's also possible to limit defrag efforts in the VM to generate anonymous hugepages in case they're not immediately free to madvise regions or to never try to defrag memory and simply fallback to regular @@ -146,25 +189,34 @@ madvise never should be self-explanatory. -By default kernel tries to use huge zero page on read page fault to -anonymous mapping. It's possible to disable huge zero page by writing 0 -or enable it back by writing 1:: +By default kernel tries to use huge, PMD-mappable zero page on read +page fault to anonymous mapping. It's possible to disable huge zero +page by writing 0 or enable it back by writing 1:: echo 0 >/sys/kernel/mm/transparent_hugepage/use_zero_page echo 1 >/sys/kernel/mm/transparent_hugepage/use_zero_page -Some userspace (such as a test program, or an optimized memory allocation -library) may want to know the size (in bytes) of a transparent hugepage:: +Some userspace (such as a test program, or an optimized memory +allocation library) may want to know the size (in bytes) of a +PMD-mappable transparent hugepage:: cat /sys/kernel/mm/transparent_hugepage/hpage_pmd_size -khugepaged will be automatically started when -transparent_hugepage/enabled is set to "always" or "madvise, and it'll -be automatically shutdown if it's set to "never". +khugepaged will be automatically started when one or more hugepage +sizes are enabled (either by directly setting "always" or "madvise", +or by setting "inherit" while the top-level enabled is set to "always" +or "madvise"), and it'll be automatically shutdown when the last +hugepage size is disabled (either by directly setting "never", or by +setting "inherit" while the top-level enabled is set to "never"). Khugepaged controls ------------------- +.. note:: + khugepaged currently only searches for opportunities to collapse to + PMD-sized THP and no attempt is made to collapse to other THP + sizes. + khugepaged runs usually at low frequency so while one may not want to invoke defrag algorithms synchronously during the page faults, it should be worth invoking defrag at least in khugepaged. However it's @@ -282,19 +334,26 @@ force Need of application restart =========================== -The transparent_hugepage/enabled values and tmpfs mount option only affect -future behavior. So to make them effective you need to restart any -application that could have been using hugepages. This also applies to the -regions registered in khugepaged. +The transparent_hugepage/enabled and +transparent_hugepage/hugepages-<size>kB/enabled values and tmpfs mount +option only affect future behavior. So to make them effective you need +to restart any application that could have been using hugepages. This +also applies to the regions registered in khugepaged. Monitoring usage ================ -The number of anonymous transparent huge pages currently used by the +.. note:: + Currently the below counters only record events relating to + PMD-sized THP. Events relating to other THP sizes are not included. + +The number of PMD-sized anonymous transparent huge pages currently used by the system is available by reading the AnonHugePages field in ``/proc/meminfo``. -To identify what applications are using anonymous transparent huge pages, -it is necessary to read ``/proc/PID/smaps`` and count the AnonHugePages fields -for each mapping. +To identify what applications are using PMD-sized anonymous transparent huge +pages, it is necessary to read ``/proc/PID/smaps`` and count the AnonHugePages +fields for each mapping. (Note that AnonHugePages only applies to traditional +PMD-sized THP for historical reasons and should have been called +AnonHugePmdMapped). The number of file transparent huge pages mapped to userspace is available by reading ShmemPmdMapped and ShmemHugePages fields in ``/proc/meminfo``. @@ -413,7 +472,7 @@ for huge pages. Optimizing the applications =========================== -To be guaranteed that the kernel will map a 2M page immediately in any +To be guaranteed that the kernel will map a THP immediately in any memory region, the mmap region has to be hugepage naturally aligned. posix_memalign() can provide that guarantee. diff --git a/Documentation/admin-guide/mm/userfaultfd.rst b/Documentation/admin-guide/mm/userfaultfd.rst index 203e26da5f92..e5cc8848dcb3 100644 --- a/Documentation/admin-guide/mm/userfaultfd.rst +++ b/Documentation/admin-guide/mm/userfaultfd.rst @@ -113,6 +113,9 @@ events, except page fault notifications, may be generated: areas. ``UFFD_FEATURE_MINOR_SHMEM`` is the analogous feature indicating support for shmem virtual memory areas. +- ``UFFD_FEATURE_MOVE`` indicates that the kernel supports moving an + existing page contents from userspace. + The userland application should set the feature flags it intends to use when invoking the ``UFFDIO_API`` ioctl, to request that those features be enabled if supported. diff --git a/Documentation/admin-guide/mm/zswap.rst b/Documentation/admin-guide/mm/zswap.rst index 45b98390e938..b42132969e31 100644 --- a/Documentation/admin-guide/mm/zswap.rst +++ b/Documentation/admin-guide/mm/zswap.rst @@ -153,6 +153,26 @@ attribute, e. g.:: Setting this parameter to 100 will disable the hysteresis. +Some users cannot tolerate the swapping that comes with zswap store failures +and zswap writebacks. Swapping can be disabled entirely (without disabling +zswap itself) on a cgroup-basis as follows: + + echo 0 > /sys/fs/cgroup/<cgroup-name>/memory.zswap.writeback + +Note that if the store failures are recurring (for e.g if the pages are +incompressible), users can observe reclaim inefficiency after disabling +writeback (because the same pages might be rejected again and again). + +When there is a sizable amount of cold memory residing in the zswap pool, it +can be advantageous to proactively write these cold pages to swap and reclaim +the memory for other use cases. By default, the zswap shrinker is disabled. +User can enable it as follows: + + echo Y > /sys/module/zswap/parameters/shrinker_enabled + +This can be enabled at the boot time if ``CONFIG_ZSWAP_SHRINKER_DEFAULT_ON`` is +selected. + A debugfs interface is provided for various statistic about pool size, number of pages stored, same-value filled pages and various counters for the reasons pages are rejected. diff --git a/Documentation/admin-guide/perf/dwc_pcie_pmu.rst b/Documentation/admin-guide/perf/dwc_pcie_pmu.rst new file mode 100644 index 000000000000..d47cd229d710 --- /dev/null +++ b/Documentation/admin-guide/perf/dwc_pcie_pmu.rst @@ -0,0 +1,94 @@ +====================================================================== +Synopsys DesignWare Cores (DWC) PCIe Performance Monitoring Unit (PMU) +====================================================================== + +DesignWare Cores (DWC) PCIe PMU +=============================== + +The PMU is a PCIe configuration space register block provided by each PCIe Root +Port in a Vendor-Specific Extended Capability named RAS D.E.S (Debug, Error +injection, and Statistics). + +As the name indicates, the RAS DES capability supports system level +debugging, AER error injection, and collection of statistics. To facilitate +collection of statistics, Synopsys DesignWare Cores PCIe controller +provides the following two features: + +- one 64-bit counter for Time Based Analysis (RX/TX data throughput and + time spent in each low-power LTSSM state) and +- one 32-bit counter for Event Counting (error and non-error events for + a specified lane) + +Note: There is no interrupt for counter overflow. + +Time Based Analysis +------------------- + +Using this feature you can obtain information regarding RX/TX data +throughput and time spent in each low-power LTSSM state by the controller. +The PMU measures data in two categories: + +- Group#0: Percentage of time the controller stays in LTSSM states. +- Group#1: Amount of data processed (Units of 16 bytes). + +Lane Event counters +------------------- + +Using this feature you can obtain Error and Non-Error information in +specific lane by the controller. The PMU event is selected by all of: + +- Group i +- Event j within the Group i +- Lane k + +Some of the events only exist for specific configurations. + +DesignWare Cores (DWC) PCIe PMU Driver +======================================= + +This driver adds PMU devices for each PCIe Root Port named based on the BDF of +the Root Port. For example, + + 30:03.0 PCI bridge: Device 1ded:8000 (rev 01) + +the PMU device name for this Root Port is dwc_rootport_3018. + +The DWC PCIe PMU driver registers a perf PMU driver, which provides +description of available events and configuration options in sysfs, see +/sys/bus/event_source/devices/dwc_rootport_{bdf}. + +The "format" directory describes format of the config fields of the +perf_event_attr structure. The "events" directory provides configuration +templates for all documented events. For example, +"Rx_PCIe_TLP_Data_Payload" is an equivalent of "eventid=0x22,type=0x1". + +The "perf list" command shall list the available events from sysfs, e.g.:: + + $# perf list | grep dwc_rootport + <...> + dwc_rootport_3018/Rx_PCIe_TLP_Data_Payload/ [Kernel PMU event] + <...> + dwc_rootport_3018/rx_memory_read,lane=?/ [Kernel PMU event] + +Time Based Analysis Event Usage +------------------------------- + +Example usage of counting PCIe RX TLP data payload (Units of bytes):: + + $# perf stat -a -e dwc_rootport_3018/Rx_PCIe_TLP_Data_Payload/ + +The average RX/TX bandwidth can be calculated using the following formula: + + PCIe RX Bandwidth = Rx_PCIe_TLP_Data_Payload / Measure_Time_Window + PCIe TX Bandwidth = Tx_PCIe_TLP_Data_Payload / Measure_Time_Window + +Lane Event Usage +------------------------------- + +Each lane has the same event set and to avoid generating a list of hundreds +of events, the user need to specify the lane ID explicitly, e.g.:: + + $# perf stat -a -e dwc_rootport_3018/rx_memory_read,lane=4/ + +The driver does not support sampling, therefore "perf record" will not +work. Per-task (without "-a") perf sessions are not supported. diff --git a/Documentation/admin-guide/perf/imx-ddr.rst b/Documentation/admin-guide/perf/imx-ddr.rst index 90926d0fb8ec..77418ae5a290 100644 --- a/Documentation/admin-guide/perf/imx-ddr.rst +++ b/Documentation/admin-guide/perf/imx-ddr.rst @@ -13,8 +13,8 @@ is one register for each counter. Counter 0 is special in that it always counts interrupt is raised. If any other counter overflows, it continues counting, and no interrupt is raised. -The "format" directory describes format of the config (event ID) and config1 -(AXI filtering) fields of the perf_event_attr structure, see /sys/bus/event_source/ +The "format" directory describes format of the config (event ID) and config1/2 +(AXI filter setting) fields of the perf_event_attr structure, see /sys/bus/event_source/ devices/imx8_ddr0/format/. The "events" directory describes the events types hardware supported that can be used with perf tool, see /sys/bus/event_source/ devices/imx8_ddr0/events/. The "caps" directory describes filter features implemented @@ -28,12 +28,11 @@ in DDR PMU, see /sys/bus/events_source/devices/imx8_ddr0/caps/. AXI filtering is only used by CSV modes 0x41 (axid-read) and 0x42 (axid-write) to count reading or writing matches filter setting. Filter setting is various from different DRAM controller implementations, which is distinguished by quirks -in the driver. You also can dump info from userspace, filter in "caps" directory -indicates whether PMU supports AXI ID filter or not; enhanced_filter indicates -whether PMU supports enhanced AXI ID filter or not. Value 0 for un-supported, and -value 1 for supported. +in the driver. You also can dump info from userspace, "caps" directory show the +type of AXI filter (filter, enhanced_filter and super_filter). Value 0 for +un-supported, and value 1 for supported. -* With DDR_CAP_AXI_ID_FILTER quirk(filter: 1, enhanced_filter: 0). +* With DDR_CAP_AXI_ID_FILTER quirk(filter: 1, enhanced_filter: 0, super_filter: 0). Filter is defined with two configuration parts: --AXI_ID defines AxID matching value. --AXI_MASKING defines which bits of AxID are meaningful for the matching. @@ -65,7 +64,37 @@ value 1 for supported. perf stat -a -e imx8_ddr0/axid-read,axi_id=0x12/ cmd, which will monitor ARID=0x12 -* With DDR_CAP_AXI_ID_FILTER_ENHANCED quirk(filter: 1, enhanced_filter: 1). +* With DDR_CAP_AXI_ID_FILTER_ENHANCED quirk(filter: 1, enhanced_filter: 1, super_filter: 0). This is an extension to the DDR_CAP_AXI_ID_FILTER quirk which permits counting the number of bytes (as opposed to the number of bursts) from DDR read and write transactions concurrently with another set of data counters. + +* With DDR_CAP_AXI_ID_PORT_CHANNEL_FILTER quirk(filter: 0, enhanced_filter: 0, super_filter: 1). + There is a limitation in previous AXI filter, it cannot filter different IDs + at the same time as the filter is shared between counters. This quirk is the + extension of AXI ID filter. One improvement is that counter 1-3 has their own + filter, means that it supports concurrently filter various IDs. Another + improvement is that counter 1-3 supports AXI PORT and CHANNEL selection. Support + selecting address channel or data channel. + + Filter is defined with 2 configuration registers per counter 1-3. + --Counter N MASK COMP register - including AXI_ID and AXI_MASKING. + --Counter N MUX CNTL register - including AXI CHANNEL and AXI PORT. + + - 0: address channel + - 1: data channel + + PMU in DDR subsystem, only one single port0 exists, so axi_port is reserved + which should be 0. + + .. code-block:: bash + + perf stat -a -e imx8_ddr0/axid-read,axi_mask=0xMMMM,axi_id=0xDDDD,axi_channel=0xH/ cmd + perf stat -a -e imx8_ddr0/axid-write,axi_mask=0xMMMM,axi_id=0xDDDD,axi_channel=0xH/ cmd + + .. note:: + + axi_channel is inverted in userspace, and it will be reverted in driver + automatically. So that users do not need specify axi_channel if want to + monitor data channel from DDR transactions, since data channel is more + meaningful. diff --git a/Documentation/admin-guide/perf/index.rst b/Documentation/admin-guide/perf/index.rst index a2e6f2c81146..f4a4513c526f 100644 --- a/Documentation/admin-guide/perf/index.rst +++ b/Documentation/admin-guide/perf/index.rst @@ -19,6 +19,7 @@ Performance monitor support arm_dsu_pmu thunderx2-pmu alibaba_pmu + dwc_pcie_pmu nvidia-pmu meson-ddr-pmu cxl diff --git a/Documentation/admin-guide/pmf.rst b/Documentation/admin-guide/pmf.rst new file mode 100644 index 000000000000..9ee729ffc19b --- /dev/null +++ b/Documentation/admin-guide/pmf.rst @@ -0,0 +1,24 @@ +.. SPDX-License-Identifier: GPL-2.0 + +Set udev rules for PMF Smart PC Builder +--------------------------------------- + +AMD PMF(Platform Management Framework) Smart PC Solution builder has to set the system states +like S0i3, Screen lock, hibernate etc, based on the output actions provided by the PMF +TA (Trusted Application). + +In order for this to work the PMF driver generates a uevent for userspace to react to. Below are +sample udev rules that can facilitate this experience when a machine has PMF Smart PC solution builder +enabled. + +Please add the following line(s) to +``/etc/udev/rules.d/99-local.rules``:: + + DRIVERS=="amd-pmf", ACTION=="change", ENV{EVENT_ID}=="0", RUN+="/usr/bin/systemctl suspend" + DRIVERS=="amd-pmf", ACTION=="change", ENV{EVENT_ID}=="1", RUN+="/usr/bin/systemctl hibernate" + DRIVERS=="amd-pmf", ACTION=="change", ENV{EVENT_ID}=="2", RUN+="/bin/loginctl lock-sessions" + +EVENT_ID values: +0= Put the system to S0i3/S2Idle +1= Put the system to hibernate +2= Lock the screen diff --git a/Documentation/admin-guide/sysctl/net.rst b/Documentation/admin-guide/sysctl/net.rst index c7525942f12c..396091651955 100644 --- a/Documentation/admin-guide/sysctl/net.rst +++ b/Documentation/admin-guide/sysctl/net.rst @@ -345,7 +345,10 @@ optmem_max ---------- Maximum ancillary buffer size allowed per socket. Ancillary data is a sequence -of struct cmsghdr structures with appended data. +of struct cmsghdr structures with appended data. TCP tx zerocopy also uses +optmem_max as a limit for its internal structures. + +Default : 128 KB fb_tunnels_only_for_init_net ---------------------------- diff --git a/Documentation/arch/arm64/arm-acpi.rst b/Documentation/arch/arm64/arm-acpi.rst index a46c34fa9604..e59e4505d0d9 100644 --- a/Documentation/arch/arm64/arm-acpi.rst +++ b/Documentation/arch/arm64/arm-acpi.rst @@ -130,7 +130,7 @@ When an Arm system boots, it can either have DT information, ACPI tables, or in some very unusual cases, both. If no command line parameters are used, the kernel will try to use DT for device enumeration; if there is no DT present, the kernel will try to use ACPI tables, but only if they are present. -In neither is available, the kernel will not boot. If acpi=force is used +If neither is available, the kernel will not boot. If acpi=force is used on the command line, the kernel will attempt to use ACPI tables first, but fall back to DT if there are no ACPI tables present. The basic idea is that the kernel will not fail to boot unless it absolutely has no other choice. diff --git a/Documentation/arch/arm64/perf.rst b/Documentation/arch/arm64/perf.rst index 1f87b57c2332..997fd716b82f 100644 --- a/Documentation/arch/arm64/perf.rst +++ b/Documentation/arch/arm64/perf.rst @@ -164,3 +164,75 @@ and should be used to mask the upper bits as needed. https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/tools/perf/arch/arm64/tests/user-events.c .. _tools/lib/perf/tests/test-evsel.c: https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/tools/lib/perf/tests/test-evsel.c + +Event Counting Threshold +========================================== + +Overview +-------- + +FEAT_PMUv3_TH (Armv8.8) permits a PMU counter to increment only on +events whose count meets a specified threshold condition. For example if +threshold_compare is set to 2 ('Greater than or equal'), and the +threshold is set to 2, then the PMU counter will now only increment by +when an event would have previously incremented the PMU counter by 2 or +more on a single processor cycle. + +To increment by 1 after passing the threshold condition instead of the +number of events on that cycle, add the 'threshold_count' option to the +commandline. + +How-to +------ + +These are the parameters for controlling the feature: + +.. list-table:: + :header-rows: 1 + + * - Parameter + - Description + * - threshold + - Value to threshold the event by. A value of 0 means that + thresholding is disabled and the other parameters have no effect. + * - threshold_compare + - | Comparison function to use, with the following values supported: + | + | 0: Not-equal + | 1: Equals + | 2: Greater-than-or-equal + | 3: Less-than + * - threshold_count + - If this is set, count by 1 after passing the threshold condition + instead of the value of the event on this cycle. + +The threshold, threshold_compare and threshold_count values can be +provided per event, for example: + +.. code-block:: sh + + perf stat -e stall_slot/threshold=2,threshold_compare=2/ \ + -e dtlb_walk/threshold=10,threshold_compare=3,threshold_count/ + +In this example the stall_slot event will count by 2 or more on every +cycle where 2 or more stalls happen. And dtlb_walk will count by 1 on +every cycle where the number of dtlb walks were less than 10. + +The maximum supported threshold value can be read from the caps of each +PMU, for example: + +.. code-block:: sh + + cat /sys/bus/event_source/devices/armv8_pmuv3/caps/threshold_max + + 0x000000ff + +If a value higher than this is given, then opening the event will result +in an error. The highest possible maximum is 4095, as the config field +for threshold is limited to 12 bits, and the Perf tool will refuse to +parse higher values. + +If the PMU doesn't support FEAT_PMUv3_TH, then threshold_max will read +0, and attempting to set a threshold value will also result in an error. +threshold_max will also read as 0 on aarch32 guests, even if the host +is running on hardware with the feature. diff --git a/Documentation/arch/x86/boot.rst b/Documentation/arch/x86/boot.rst index 22cc7a040dae..c513855a54bb 100644 --- a/Documentation/arch/x86/boot.rst +++ b/Documentation/arch/x86/boot.rst @@ -71,7 +71,7 @@ Protocol 2.13 (Kernel 3.14) Support 32- and 64-bit flags being set in Protocol 2.14 BURNT BY INCORRECT COMMIT ae7e1238e68f2a472a125673ab506d49158c1889 - (x86/boot: Add ACPI RSDP address to setup_header) + ("x86/boot: Add ACPI RSDP address to setup_header") DO NOT USE!!! ASSUME SAME AS 2.13. Protocol 2.15 (Kernel 5.5) Added the kernel_info and kernel_info.setup_type_max. diff --git a/Documentation/arch/x86/cpuinfo.rst b/Documentation/arch/x86/cpuinfo.rst index 08246e8ac835..8895784d4784 100644 --- a/Documentation/arch/x86/cpuinfo.rst +++ b/Documentation/arch/x86/cpuinfo.rst @@ -7,27 +7,74 @@ x86 Feature Flags Introduction ============ -On x86, flags appearing in /proc/cpuinfo have an X86_FEATURE definition -in arch/x86/include/asm/cpufeatures.h. If the kernel cares about a feature -or KVM want to expose the feature to a KVM guest, it can and should have -an X86_FEATURE_* defined. These flags represent hardware features as -well as software features. - -If users want to know if a feature is available on a given system, they -try to find the flag in /proc/cpuinfo. If a given flag is present, it -means that the kernel supports it and is currently making it available. -If such flag represents a hardware feature, it also means that the -hardware supports it. - -If the expected flag does not appear in /proc/cpuinfo, things are murkier. -Users need to find out the reason why the flag is missing and find the way -how to enable it, which is not always easy. There are several factors that -can explain missing flags: the expected feature failed to enable, the feature -is missing in hardware, platform firmware did not enable it, the feature is -disabled at build or run time, an old kernel is in use, or the kernel does -not support the feature and thus has not enabled it. In general, /proc/cpuinfo -shows features which the kernel supports. For a full list of CPUID flags -which the CPU supports, use tools/arch/x86/kcpuid. +The list of feature flags in /proc/cpuinfo is not complete and +represents an ill-fated attempt from long time ago to put feature flags +in an easy to find place for userspace. + +However, the amount of feature flags is growing by the CPU generation, +leading to unparseable and unwieldy /proc/cpuinfo. + +What is more, those feature flags do not even need to be in that file +because userspace doesn't care about them - glibc et al already use +CPUID to find out what the target machine supports and what not. + +And even if it doesn't show a particular feature flag - although the CPU +still does have support for the respective hardware functionality and +said CPU supports CPUID faulting - userspace can simply probe for the +feature and figure out if it is supported or not, regardless of whether +it is being advertised somewhere. + +Furthermore, those flag strings become an ABI the moment they appear +there and maintaining them forever when nothing even uses them is a lot +of wasted effort. + +So, the current use of /proc/cpuinfo is to show features which the +kernel has *enabled* and *supports*. As in: the CPUID feature flag is +there, there's an additional setup which the kernel has done while +booting and the functionality is ready to use. A perfect example for +that is "user_shstk" where additional code enablement is present in the +kernel to support shadow stack for user programs. + +So, if users want to know if a feature is available on a given system, +they try to find the flag in /proc/cpuinfo. If a given flag is present, +it means that + +* the kernel knows about the feature enough to have an X86_FEATURE bit + +* the kernel supports it and is currently making it available either to + userspace or some other part of the kernel + +* if the flag represents a hardware feature the hardware supports it. + +The absence of a flag in /proc/cpuinfo by itself means almost nothing to +an end user. + +On the one hand, a feature like "vaes" might be fully available to user +applications on a kernel that has not defined X86_FEATURE_VAES and thus +there is no "vaes" in /proc/cpuinfo. + +On the other hand, a new kernel running on non-VAES hardware would also +have no "vaes" in /proc/cpuinfo. There's no way for an application or +user to tell the difference. + +The end result is that the flags field in /proc/cpuinfo is marginally +useful for kernel debugging, but not really for anything else. +Applications should instead use things like the glibc facilities for +querying CPU support. Users should rely on tools like +tools/arch/x86/kcpuid and cpuid(1). + +Regarding implementation, flags appearing in /proc/cpuinfo have an +X86_FEATURE definition in arch/x86/include/asm/cpufeatures.h. These flags +represent hardware features as well as software features. + +If the kernel cares about a feature or KVM want to expose the feature to +a KVM guest, it should only then expose it to the guest when the guest +needs to parse /proc/cpuinfo. Which, as mentioned above, is highly +unlikely. KVM can synthesize the CPUID bit and the KVM guest can simply +query CPUID and figure out what the hypervisor supports and what not. As +already stated, /proc/cpuinfo is not a dumping ground for useless +feature flags. + How are feature flags created? ============================== diff --git a/Documentation/arch/x86/pti.rst b/Documentation/arch/x86/pti.rst index 4b858a9bad8d..e08d35177bc0 100644 --- a/Documentation/arch/x86/pti.rst +++ b/Documentation/arch/x86/pti.rst @@ -81,11 +81,9 @@ this protection comes at a cost: and exit (it can be skipped when the kernel is interrupted, though.) Moves to CR3 are on the order of a hundred cycles, and are required at every entry and exit. - b. A "trampoline" must be used for SYSCALL entry. This - trampoline depends on a smaller set of resources than the - non-PTI SYSCALL entry code, so requires mapping fewer - things into the userspace page tables. The downside is - that stacks must be switched at entry time. + b. Percpu TSS is mapped into the user page tables to allow SYSCALL64 path + to work under PTI. This doesn't have a direct runtime cost but it can + be argued it opens certain timing attack scenarios. c. Global pages are disabled for all kernel structures not mapped into both kernel and userspace page tables. This feature of the MMU allows different processes to share TLB @@ -167,7 +165,7 @@ that are worth noting here. * Failures of the selftests/x86 code. Usually a bug in one of the more obscure corners of entry_64.S * Crashes in early boot, especially around CPU bringup. Bugs - in the trampoline code or mappings cause these. + in the mappings cause these. * Crashes at the first interrupt. Caused by bugs in entry_64.S, like screwing up a page table switch. Also caused by incorrectly mapping the IRQ handler entry code. diff --git a/Documentation/bpf/btf.rst b/Documentation/bpf/btf.rst index e43c2fdafcd7..257a7e1cdf5d 100644 --- a/Documentation/bpf/btf.rst +++ b/Documentation/bpf/btf.rst @@ -272,10 +272,8 @@ In this case, if the base type is an int type, it must be a regular int type: * ``BTF_INT_OFFSET()`` must be 0. * ``BTF_INT_BITS()`` must be equal to ``{1,2,4,8,16} * 8``. -The following kernel patch introduced ``kind_flag`` and explained why both -modes exist: - - https://github.com/torvalds/linux/commit/9d5f9f701b1891466fb3dbb1806ad97716f95cc3#diff-fa650a64fdd3968396883d2fe8215ff3 +Commit 9d5f9f701b18 introduced ``kind_flag`` and explains why both modes +exist. 2.2.6 BTF_KIND_ENUM ~~~~~~~~~~~~~~~~~~~ diff --git a/Documentation/bpf/cpumasks.rst b/Documentation/bpf/cpumasks.rst index a22b6ad105fb..b5d47a04da5d 100644 --- a/Documentation/bpf/cpumasks.rst +++ b/Documentation/bpf/cpumasks.rst @@ -352,7 +352,7 @@ can be used to query the contents of cpumasks. .. kernel-doc:: kernel/bpf/cpumask.c :identifiers: bpf_cpumask_first bpf_cpumask_first_zero bpf_cpumask_first_and - bpf_cpumask_test_cpu + bpf_cpumask_test_cpu bpf_cpumask_weight .. kernel-doc:: kernel/bpf/cpumask.c :identifiers: bpf_cpumask_equal bpf_cpumask_intersects bpf_cpumask_subset diff --git a/Documentation/bpf/fs_kfuncs.rst b/Documentation/bpf/fs_kfuncs.rst new file mode 100644 index 000000000000..8762c3233a3d --- /dev/null +++ b/Documentation/bpf/fs_kfuncs.rst @@ -0,0 +1,21 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. _fs_kfuncs-header-label: + +===================== +BPF filesystem kfuncs +===================== + +BPF LSM programs need to access filesystem data from LSM hooks. The following +BPF kfuncs can be used to get these data. + + * ``bpf_get_file_xattr()`` + + * ``bpf_get_fsverity_digest()`` + +To avoid recursions, these kfuncs follow the following rules: + +1. These kfuncs are only permitted from BPF LSM function. +2. These kfuncs should not call into other LSM hooks, i.e. security_*(). For + example, ``bpf_get_file_xattr()`` does not use ``vfs_getxattr()``, because + the latter calls LSM hook ``security_inode_getxattr``. diff --git a/Documentation/bpf/index.rst b/Documentation/bpf/index.rst index aeaeb35e6d4a..0bb5cb8157f1 100644 --- a/Documentation/bpf/index.rst +++ b/Documentation/bpf/index.rst @@ -21,6 +21,7 @@ that goes into great technical depth about the BPF Architecture. helpers kfuncs cpumasks + fs_kfuncs programs maps bpf_prog_run diff --git a/Documentation/bpf/kfuncs.rst b/Documentation/bpf/kfuncs.rst index 723408e399ab..7985c6615f3c 100644 --- a/Documentation/bpf/kfuncs.rst +++ b/Documentation/bpf/kfuncs.rst @@ -135,6 +135,30 @@ Either way, the returned buffer is either NULL, or of size buffer_szk. Without t annotation, the verifier will reject the program if a null pointer is passed in with a nonzero size. +2.2.5 __str Annotation +---------------------------- +This annotation is used to indicate that the argument is a constant string. + +An example is given below:: + + __bpf_kfunc bpf_get_file_xattr(..., const char *name__str, ...) + { + ... + } + +In this case, ``bpf_get_file_xattr()`` can be called as:: + + bpf_get_file_xattr(..., "xattr_name", ...); + +Or:: + + const char name[] = "xattr_name"; /* This need to be global */ + int BPF_PROG(...) + { + ... + bpf_get_file_xattr(..., name, ...); + ... + } .. _BPF_kfunc_nodef: diff --git a/Documentation/conf.py b/Documentation/conf.py index d4fdf6a3875a..5830b01c5642 100644 --- a/Documentation/conf.py +++ b/Documentation/conf.py @@ -47,7 +47,7 @@ from load_config import loadConfig # -- General configuration ------------------------------------------------ # If your documentation needs a minimal Sphinx version, state it here. -needs_sphinx = '1.7' +needs_sphinx = '2.4.4' # Add any Sphinx extension module names here, as strings. They can be # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom @@ -55,7 +55,7 @@ needs_sphinx = '1.7' extensions = ['kerneldoc', 'rstFlatTable', 'kernel_include', 'kfigure', 'sphinx.ext.ifconfig', 'automarkup', 'maintainers_include', 'sphinx.ext.autosectionlabel', - 'kernel_abi', 'kernel_feat'] + 'kernel_abi', 'kernel_feat', 'translations'] if major >= 3: if (major > 3) or (minor > 0 or patch >= 2): @@ -106,6 +106,7 @@ if major >= 3: "__weak", "noinline", "__fix_address", + "__counted_by", # include/linux/memblock.h: "__init_memblock", @@ -357,6 +358,10 @@ html_sidebars = { '**': ['searchbox.html', 'kernel-toc.html', 'sourcelink.html'] if html_theme == 'alabaster': html_sidebars['**'].insert(0, 'about.html') +# The name of an image file (relative to this directory) to place at the top +# of the sidebar. +html_logo = 'images/logo.svg' + # Output file base name for HTML help builder. htmlhelp_basename = 'TheLinuxKerneldoc' diff --git a/Documentation/core-api/dma-api-howto.rst b/Documentation/core-api/dma-api-howto.rst index 72f6cdb6be1c..e8a55f9d61db 100644 --- a/Documentation/core-api/dma-api-howto.rst +++ b/Documentation/core-api/dma-api-howto.rst @@ -8,7 +8,7 @@ Dynamic DMA mapping Guide This is a guide to device driver writers on how to use the DMA API with example pseudo-code. For a concise description of the API, see -DMA-API.txt. +Documentation/core-api/dma-api.rst. CPU and DMA addresses ===================== diff --git a/Documentation/core-api/dma-api.rst b/Documentation/core-api/dma-api.rst index 829f20a193ca..8e3cce3d0a23 100644 --- a/Documentation/core-api/dma-api.rst +++ b/Documentation/core-api/dma-api.rst @@ -448,7 +448,7 @@ DMA address entries returned. Synchronise a single contiguous or scatter/gather mapping for the CPU and device. With the sync_sg API, all the parameters must be the same -as those passed into the single mapping API. With the sync_single API, +as those passed into the sg mapping API. With the sync_single API, you can use dma_handle and size parameters that aren't identical to those passed into the single mapping API to do a partial sync. diff --git a/Documentation/core-api/maple_tree.rst b/Documentation/core-api/maple_tree.rst index 96f3d5f076b5..ccdd1615cf97 100644 --- a/Documentation/core-api/maple_tree.rst +++ b/Documentation/core-api/maple_tree.rst @@ -81,6 +81,9 @@ section. Sometimes it is necessary to ensure the next call to store to a maple tree does not allocate memory, please see :ref:`maple-tree-advanced-api` for this use case. +You can use mtree_dup() to duplicate an entire maple tree. It is a more +efficient way than inserting all elements one by one into a new tree. + Finally, you can remove all entries from a maple tree by calling mtree_destroy(). If the maple tree entries are pointers, you may wish to free the entries first. @@ -112,6 +115,7 @@ Takes ma_lock internally: * mtree_insert() * mtree_insert_range() * mtree_erase() + * mtree_dup() * mtree_destroy() * mt_set_in_rcu() * mt_clear_in_rcu() diff --git a/Documentation/core-api/mm-api.rst b/Documentation/core-api/mm-api.rst index 2d091c873d1e..af8151db88b2 100644 --- a/Documentation/core-api/mm-api.rst +++ b/Documentation/core-api/mm-api.rst @@ -37,7 +37,7 @@ The Slab Cache .. kernel-doc:: include/linux/slab.h :internal: -.. kernel-doc:: mm/slab.c +.. kernel-doc:: mm/slub.c :export: .. kernel-doc:: mm/slab_common.c diff --git a/Documentation/core-api/workqueue.rst b/Documentation/core-api/workqueue.rst index 0046af06531a..33c4539155d9 100644 --- a/Documentation/core-api/workqueue.rst +++ b/Documentation/core-api/workqueue.rst @@ -379,7 +379,7 @@ Workqueue currently supports the following affinity scopes. cases. This is the default affinity scope. ``numa`` - CPUs are grouped according to NUMA bounaries. + CPUs are grouped according to NUMA boundaries. ``system`` All CPUs are put in the same group. Workqueue makes no effort to process a diff --git a/Documentation/crypto/api.rst b/Documentation/crypto/api.rst index b91b31736df8..ff31c30561d4 100644 --- a/Documentation/crypto/api.rst +++ b/Documentation/crypto/api.rst @@ -1,11 +1,8 @@ Programming Interface ===================== -.. class:: toc-title - - Table of contents - .. toctree:: + :caption: Table of contents :maxdepth: 2 api-skcipher diff --git a/Documentation/crypto/device_drivers/index.rst b/Documentation/crypto/device_drivers/index.rst new file mode 100644 index 000000000000..c81d311ac61b --- /dev/null +++ b/Documentation/crypto/device_drivers/index.rst @@ -0,0 +1,9 @@ +.. SPDX-License-Identifier: GPL-2.0 + +Hardware Device Driver Specific Documentation +--------------------------------------------- + +.. toctree:: + :maxdepth: 1 + + octeontx2 diff --git a/Documentation/crypto/device_drivers/octeontx2.rst b/Documentation/crypto/device_drivers/octeontx2.rst new file mode 100644 index 000000000000..7e469b173ac8 --- /dev/null +++ b/Documentation/crypto/device_drivers/octeontx2.rst @@ -0,0 +1,25 @@ +.. SPDX-License-Identifier: GPL-2.0 + +========================= +octeontx2 devlink support +========================= + +This document describes the devlink features implemented by the ``octeontx2 CPT`` +device drivers. + +Parameters +========== + +The ``octeontx2`` driver implements the following driver-specific parameters. + +.. list-table:: Driver-specific parameters implemented + :widths: 5 5 5 85 + + * - Name + - Type + - Mode + - Description + * - ``t106_mode`` + - u8 + - runtime + - Used to configure CN10KA B0/CN10KB CPT to work as CN10KA A0/A1. diff --git a/Documentation/crypto/index.rst b/Documentation/crypto/index.rst index da5d5ad2bdf3..92eec78b5713 100644 --- a/Documentation/crypto/index.rst +++ b/Documentation/crypto/index.rst @@ -9,11 +9,8 @@ This documentation outlines the Linux kernel crypto API with its concepts, details about developing cipher implementations, employment of the API for cryptographic use cases, as well as programming examples. -.. class:: toc-title - - Table of contents - .. toctree:: + :caption: Table of contents :maxdepth: 2 intro @@ -28,3 +25,4 @@ for cryptographic use cases, as well as programming examples. api api-samples descore-readme + device_drivers/index diff --git a/Documentation/dev-tools/index.rst b/Documentation/dev-tools/index.rst index 6b0663075dc0..3d2286c683bc 100644 --- a/Documentation/dev-tools/index.rst +++ b/Documentation/dev-tools/index.rst @@ -10,11 +10,8 @@ whole; patches welcome! A brief overview of testing-specific tools can be found in Documentation/dev-tools/testing-overview.rst -.. class:: toc-title - - Table of contents - .. toctree:: + :caption: Table of contents :maxdepth: 2 testing-overview diff --git a/Documentation/dev-tools/kunit/api/resource.rst b/Documentation/dev-tools/kunit/api/resource.rst index 0a94f831259e..ec6002a6b0db 100644 --- a/Documentation/dev-tools/kunit/api/resource.rst +++ b/Documentation/dev-tools/kunit/api/resource.rst @@ -11,3 +11,12 @@ state on a per-test basis, register custom cleanup actions, and more. .. kernel-doc:: include/kunit/resource.h :internal: + +Managed Devices +--------------- + +Functions for using KUnit-managed struct device and struct device_driver. +Include ``kunit/device.h`` to use these. + +.. kernel-doc:: include/kunit/device.h + :internal: diff --git a/Documentation/dev-tools/kunit/run_manual.rst b/Documentation/dev-tools/kunit/run_manual.rst index e7b46421f247..699d92885075 100644 --- a/Documentation/dev-tools/kunit/run_manual.rst +++ b/Documentation/dev-tools/kunit/run_manual.rst @@ -49,9 +49,52 @@ loaded. The results will appear in TAP format in ``dmesg``. +debugfs +======= + +KUnit can be accessed from userspace via the debugfs filesystem (See more +information about debugfs at Documentation/filesystems/debugfs.rst). + +If ``CONFIG_KUNIT_DEBUGFS`` is enabled, the KUnit debugfs filesystem is +mounted at /sys/kernel/debug/kunit. You can use this filesystem to perform +the following actions. + +Retrieve Test Results +===================== + +You can use debugfs to retrieve KUnit test results. The test results are +accessible from the debugfs filesystem in the following read-only file: + +.. code-block :: bash + + /sys/kernel/debug/kunit/<test_suite>/results + +The test results are printed in a KTAP document. Note this document is separate +to the kernel log and thus, may have different test suite numbering. + +Run Tests After Kernel Has Booted +================================= + +You can use the debugfs filesystem to trigger built-in tests to run after +boot. To run the test suite, you can use the following command to write to +the ``/sys/kernel/debug/kunit/<test_suite>/run`` file: + +.. code-block :: bash + + echo "any string" > /sys/kernel/debugfs/kunit/<test_suite>/run + +As a result, the test suite runs and the results are printed to the kernel +log. + +However, this feature is not available with KUnit suites that use init data, +because init data may have been discarded after the kernel boots. KUnit +suites that use init data should be defined using the +kunit_test_init_section_suites() macro. + +Also, you cannot use this feature to run tests concurrently. Instead a test +will wait to run until other tests have completed or failed. + .. note :: - If ``CONFIG_KUNIT_DEBUGFS`` is enabled, KUnit test results will - be accessible from the ``debugfs`` filesystem (if mounted). - They will be in ``/sys/kernel/debug/kunit/<test_suite>/results``, in - TAP format. + For test authors, to use this feature, tests will need to correctly initialise + and/or clean up any data, so the test runs correctly a second time. diff --git a/Documentation/dev-tools/kunit/running_tips.rst b/Documentation/dev-tools/kunit/running_tips.rst index 766f9cdea0fa..024e9ad1d1e9 100644 --- a/Documentation/dev-tools/kunit/running_tips.rst +++ b/Documentation/dev-tools/kunit/running_tips.rst @@ -428,3 +428,10 @@ This attribute indicates the name of the module associated with the test. This attribute is automatically saved as a string and is printed for each suite. Tests can also be filtered using this attribute. + +``is_init`` + +This attribute indicates whether the test uses init data or functions. + +This attribute is automatically saved as a boolean and tests can also be +filtered using this attribute. diff --git a/Documentation/dev-tools/kunit/usage.rst b/Documentation/dev-tools/kunit/usage.rst index c27e1646ecd9..a9efab50eed8 100644 --- a/Documentation/dev-tools/kunit/usage.rst +++ b/Documentation/dev-tools/kunit/usage.rst @@ -566,13 +566,9 @@ By reusing the same ``cases`` array from above, we can write the test as a }, }; - // Need a helper function to generate a name for each test case. - static void case_to_desc(const struct sha1_test_case *t, char *desc) - { - strcpy(desc, t->str); - } - // Creates `sha1_gen_params()` to iterate over `cases`. - KUNIT_ARRAY_PARAM(sha1, cases, case_to_desc); + // Creates `sha1_gen_params()` to iterate over `cases` while using + // the struct member `str` for the case description. + KUNIT_ARRAY_PARAM_DESC(sha1, cases, str); // Looks no different from a normal test. static void sha1_test(struct kunit *test) @@ -588,7 +584,7 @@ By reusing the same ``cases`` array from above, we can write the test as a } // Instead of KUNIT_CASE, we use KUNIT_CASE_PARAM and pass in the - // function declared by KUNIT_ARRAY_PARAM. + // function declared by KUNIT_ARRAY_PARAM or KUNIT_ARRAY_PARAM_DESC. static struct kunit_case sha1_test_cases[] = { KUNIT_CASE_PARAM(sha1_test, sha1_gen_params), {} @@ -651,12 +647,16 @@ For example: } Note that, for functions like device_unregister which only accept a single -pointer-sized argument, it's possible to directly cast that function to -a ``kunit_action_t`` rather than writing a wrapper function, for example: +pointer-sized argument, it's possible to automatically generate a wrapper +with the ``KUNIT_DEFINE_ACTION_WRAPPER()`` macro, for example: .. code-block:: C - kunit_add_action(test, (kunit_action_t *)&device_unregister, &dev); + KUNIT_DEFINE_ACTION_WRAPPER(device_unregister, device_unregister_wrapper, struct device *); + kunit_add_action(test, &device_unregister_wrapper, &dev); + +You should do this in preference to manually casting to the ``kunit_action_t`` type, +as casting function pointers will break Control Flow Integrity (CFI). ``kunit_add_action`` can fail if, for example, the system is out of memory. You can use ``kunit_add_action_or_reset`` instead which runs the action @@ -793,3 +793,53 @@ structures as shown below: KUnit is not enabled, or if no test is running in the current task, it will do nothing. This compiles down to either a no-op or a static key check, so will have a negligible performance impact when no test is running. + +Managing Fake Devices and Drivers +--------------------------------- + +When testing drivers or code which interacts with drivers, many functions will +require a ``struct device`` or ``struct device_driver``. In many cases, setting +up a real device is not required to test any given function, so a fake device +can be used instead. + +KUnit provides helper functions to create and manage these fake devices, which +are internally of type ``struct kunit_device``, and are attached to a special +``kunit_bus``. These devices support managed device resources (devres), as +described in Documentation/driver-api/driver-model/devres.rst + +To create a KUnit-managed ``struct device_driver``, use ``kunit_driver_create()``, +which will create a driver with the given name, on the ``kunit_bus``. This driver +will automatically be destroyed when the corresponding test finishes, but can also +be manually destroyed with ``driver_unregister()``. + +To create a fake device, use the ``kunit_device_register()``, which will create +and register a device, using a new KUnit-managed driver created with ``kunit_driver_create()``. +To provide a specific, non-KUnit-managed driver, use ``kunit_device_register_with_driver()`` +instead. Like with managed drivers, KUnit-managed fake devices are automatically +cleaned up when the test finishes, but can be manually cleaned up early with +``kunit_device_unregister()``. + +The KUnit devices should be used in preference to ``root_device_register()``, and +instead of ``platform_device_register()`` in cases where the device is not otherwise +a platform device. + +For example: + +.. code-block:: c + + #include <kunit/device.h> + + static void test_my_device(struct kunit *test) + { + struct device *fake_device; + const char *dev_managed_string; + + // Create a fake device. + fake_device = kunit_device_register(test, "my_device"); + KUNIT_ASSERT_NOT_ERR_OR_NULL(test, fake_device) + + // Pass it to functions which need a device. + dev_managed_string = devm_kstrdup(fake_device, "Hello, World!"); + + // Everything is cleaned up automatically when the test ends. + }
\ No newline at end of file diff --git a/Documentation/devicetree/bindings/arm/cpus.yaml b/Documentation/devicetree/bindings/arm/cpus.yaml index ffd526363fda..cc5a21b47e26 100644 --- a/Documentation/devicetree/bindings/arm/cpus.yaml +++ b/Documentation/devicetree/bindings/arm/cpus.yaml @@ -198,6 +198,7 @@ properties: - qcom,kryo660 - qcom,kryo685 - qcom,kryo780 + - qcom,oryon - qcom,scorpion enable-method: diff --git a/Documentation/devicetree/bindings/arm/fsl.yaml b/Documentation/devicetree/bindings/arm/fsl.yaml index 32b195852a75..228dcc5c7d6f 100644 --- a/Documentation/devicetree/bindings/arm/fsl.yaml +++ b/Documentation/devicetree/bindings/arm/fsl.yaml @@ -967,6 +967,7 @@ properties: - menlo,mx8menlo # Verdin iMX8M Mini Module on i.MX8MM Menlo board - toradex,verdin-imx8mm-nonwifi-dahlia # Verdin iMX8M Mini Module on Dahlia - toradex,verdin-imx8mm-nonwifi-dev # Verdin iMX8M Mini Module on Verdin Development Board + - toradex,verdin-imx8mm-nonwifi-mallow # Verdin iMX8M Mini Module on Mallow - toradex,verdin-imx8mm-nonwifi-yavia # Verdin iMX8M Mini Module on Yavia - const: toradex,verdin-imx8mm-nonwifi # Verdin iMX8M Mini Module without Wi-Fi / BT - const: toradex,verdin-imx8mm # Verdin iMX8M Mini Module @@ -977,6 +978,7 @@ properties: - enum: - toradex,verdin-imx8mm-wifi-dahlia # Verdin iMX8M Mini Wi-Fi / BT Module on Dahlia - toradex,verdin-imx8mm-wifi-dev # Verdin iMX8M Mini Wi-Fi / BT M. on Verdin Development B. + - toradex,verdin-imx8mm-wifi-mallow # Verdin iMX8M Mini Wi-Fi / BT Module on Mallow - toradex,verdin-imx8mm-wifi-yavia # Verdin iMX8M Mini Wi-Fi / BT Module on Yavia - const: toradex,verdin-imx8mm-wifi # Verdin iMX8M Mini Wi-Fi / BT Module - const: toradex,verdin-imx8mm # Verdin iMX8M Mini Module @@ -1022,7 +1024,10 @@ properties: - description: Variscite VAR-SOM-MX8MN based boards items: - - const: variscite,var-som-mx8mn-symphony + - enum: + - dimonoff,gateway-evk # i.MX8MN Dimonoff Gateway EVK Board + - rve,rve-gateway # i.MX8MN RVE Gateway Board + - variscite,var-som-mx8mn-symphony - const: variscite,var-som-mx8mn - const: fsl,imx8mn @@ -1048,6 +1053,9 @@ properties: - gateworks,imx8mp-gw73xx-2x # i.MX8MP Gateworks Board - gateworks,imx8mp-gw74xx # i.MX8MP Gateworks Board - gateworks,imx8mp-gw7905-2x # i.MX8MP Gateworks Board + - skov,imx8mp-skov-revb-hdmi # SKOV i.MX8MP climate control without panel + - skov,imx8mp-skov-revb-lt6 # SKOV i.MX8MP climate control with 7†panel + - skov,imx8mp-skov-revb-mi1010ait-1cp1 # SKOV i.MX8MP climate control with 10.1" panel - toradex,verdin-imx8mp # Verdin iMX8M Plus Modules - toradex,verdin-imx8mp-nonwifi # Verdin iMX8M Plus Modules without Wi-Fi / BT - toradex,verdin-imx8mp-wifi # Verdin iMX8M Plus Wi-Fi / BT Modules @@ -1100,6 +1108,7 @@ properties: - enum: - toradex,verdin-imx8mp-nonwifi-dahlia # Verdin iMX8M Plus Module on Dahlia - toradex,verdin-imx8mp-nonwifi-dev # Verdin iMX8M Plus Module on Verdin Development Board + - toradex,verdin-imx8mp-nonwifi-mallow # Verdin iMX8M Plus Module on Mallow - toradex,verdin-imx8mp-nonwifi-yavia # Verdin iMX8M Plus Module on Yavia - const: toradex,verdin-imx8mp-nonwifi # Verdin iMX8M Plus Module without Wi-Fi / BT - const: toradex,verdin-imx8mp # Verdin iMX8M Plus Module @@ -1110,6 +1119,7 @@ properties: - enum: - toradex,verdin-imx8mp-wifi-dahlia # Verdin iMX8M Plus Wi-Fi / BT Module on Dahlia - toradex,verdin-imx8mp-wifi-dev # Verdin iMX8M Plus Wi-Fi / BT M. on Verdin Development B. + - toradex,verdin-imx8mp-wifi-mallow # Verdin iMX8M Plus Wi-Fi / BT Module on Mallow - toradex,verdin-imx8mp-wifi-yavia # Verdin iMX8M Plus Wi-Fi / BT Module on Yavia - const: toradex,verdin-imx8mp-wifi # Verdin iMX8M Plus Wi-Fi / BT Module - const: toradex,verdin-imx8mp # Verdin iMX8M Plus Module @@ -1476,6 +1486,16 @@ properties: - const: solidrun,lx2162a-som - const: fsl,lx2160a + - description: + TQ-Systems TQMLX2160A is a series of socketable SOM featuring + LX2160A system-on-chip variants. MBLX2160A mainboard can be used a + starterkit. + items: + - enum: + - tq,lx2160a-tqmlx2160a-mblx2160a + - const: tq,lx2160a-tqmlx2160a + - const: fsl,lx2160a + - description: S32G2 based Boards items: - enum: diff --git a/Documentation/devicetree/bindings/arm/google.yaml b/Documentation/devicetree/bindings/arm/google.yaml new file mode 100644 index 000000000000..e20b5c9b16bc --- /dev/null +++ b/Documentation/devicetree/bindings/arm/google.yaml @@ -0,0 +1,53 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/arm/google.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Google Tensor platforms + +maintainers: + - Peter Griffin <peter.griffin@linaro.org> + +description: | + ARM platforms using SoCs designed by Google branded "Tensor" used in Pixel + devices. + + Currently upstream this is devices using "gs101" SoC which is found in Pixel + 6, Pixel 6 Pro and Pixel 6a. + + Google have a few different names for the SoC: + - Marketing name ("Tensor") + - Codename ("Whitechapel") + - SoC ID ("gs101") + - Die ID ("S5P9845") + + Likewise there are a couple of names for the actual device + - Marketing name ("Pixel 6") + - Codename ("Oriole") + + Devicetrees should use the lowercased SoC ID and lowercased board codename, + e.g. gs101 and gs101-oriole. + +properties: + $nodename: + const: '/' + compatible: + oneOf: + - description: Google Pixel 6 / Oriole + items: + - enum: + - google,gs101-oriole + - const: google,gs101 + + # Bootloader requires empty ect node to be present + ect: + type: object + additionalProperties: false + +required: + - ect + +additionalProperties: true + +... diff --git a/Documentation/devicetree/bindings/arm/hisilicon/controller/sysctrl.yaml b/Documentation/devicetree/bindings/arm/hisilicon/controller/sysctrl.yaml index 5a53d433b6f0..7a221e1c09df 100644 --- a/Documentation/devicetree/bindings/arm/hisilicon/controller/sysctrl.yaml +++ b/Documentation/devicetree/bindings/arm/hisilicon/controller/sysctrl.yaml @@ -82,6 +82,23 @@ properties: ranges: true +patternProperties: + '^clock@': + type: object + additionalProperties: false + + properties: + compatible: + enum: + - hisilicon,hi3620-clock + - hisilicon,hi3620-mmc-clock + + reg: + maxItems: 1 + + '#clock-cells': + const: 1 + required: - compatible - reg diff --git a/Documentation/devicetree/bindings/arm/marvell/armada-7k-8k.yaml b/Documentation/devicetree/bindings/arm/marvell/armada-7k-8k.yaml index 52d78521e412..16d2e132d3d1 100644 --- a/Documentation/devicetree/bindings/arm/marvell/armada-7k-8k.yaml +++ b/Documentation/devicetree/bindings/arm/marvell/armada-7k-8k.yaml @@ -60,4 +60,26 @@ properties: - const: marvell,armada-ap807-quad - const: marvell,armada-ap807 + - description: + Alleycat5X (98DX35xx) Reference Design as COM Express Carrier plus + Armada CN9130 COM Express CPU module + items: + - const: marvell,cn9130-ac5x-carrier + - const: marvell,rd-ac5x-carrier + - const: marvell,cn9130-cpu-module + - const: marvell,cn9130 + - const: marvell,armada-ap807-quad + - const: marvell,armada-ap807 + + - description: + Alleycat5X (98DX35xx) Reference Design as COM Express Carrier plus + Armada CN9131 COM Express CPU module + items: + - const: marvell,cn9131-ac5x-carrier + - const: marvell,rd-ac5x-carrier + - const: marvell,cn9131-cpu-module + - const: marvell,cn9131 + - const: marvell,armada-ap807-quad + - const: marvell,armada-ap807 + additionalProperties: true diff --git a/Documentation/devicetree/bindings/arm/mediatek.yaml b/Documentation/devicetree/bindings/arm/mediatek.yaml index a5999b3afc35..6f2f64ae76fc 100644 --- a/Documentation/devicetree/bindings/arm/mediatek.yaml +++ b/Documentation/devicetree/bindings/arm/mediatek.yaml @@ -176,6 +176,10 @@ properties: - const: mediatek,mt8186 - items: - enum: + - mediatek,mt8188-evb + - const: mediatek,mt8188 + - items: + - enum: - mediatek,mt8192-evb - const: mediatek,mt8192 - items: @@ -235,6 +239,13 @@ properties: items: - const: google,kappa - const: mediatek,mt8183 + - description: Google Katsu (ASUS Chromebook Detachable CZ1) + items: + - enum: + - google,katsu-sku32 + - google,katsu-sku38 + - const: google,katsu + - const: mediatek,mt8183 - description: Google Kodama (Lenovo 10e Chromebook Tablet) items: - enum: @@ -244,6 +255,20 @@ properties: - google,kodama-sku32 - const: google,kodama - const: mediatek,mt8183 + - description: Google Makomo (Lenovo 100e Chromebook 2nd Gen MTK 2) + items: + - enum: + - google,makomo-sku0 + - google,makomo-sku1 + - const: google,makomo + - const: mediatek,mt8183 + - description: Google Pico (Acer Chromebook Spin 311) + items: + - enum: + - google,pico-sku1 + - google,pico-sku2 + - const: google,pico + - const: mediatek,mt8183 - description: Google Willow (Acer Chromebook 311 C722/C722T) items: - enum: diff --git a/Documentation/devicetree/bindings/arm/mediatek/mediatek,audsys.txt b/Documentation/devicetree/bindings/arm/mediatek/mediatek,audsys.txt deleted file mode 100644 index 699776be1dd3..000000000000 --- a/Documentation/devicetree/bindings/arm/mediatek/mediatek,audsys.txt +++ /dev/null @@ -1,39 +0,0 @@ -MediaTek AUDSYS controller -============================ - -The MediaTek AUDSYS controller provides various clocks to the system. - -Required Properties: - -- compatible: Should be one of: - - "mediatek,mt2701-audsys", "syscon" - - "mediatek,mt6765-audsys", "syscon" - - "mediatek,mt6779-audio", "syscon" - - "mediatek,mt7622-audsys", "syscon" - - "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 - -The AUDSYS 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. - -Required sub-nodes: -------- -For common binding part and usage, refer to -../sonud/mt2701-afe-pcm.txt. - -Example: - - audsys: clock-controller@11220000 { - compatible = "mediatek,mt7622-audsys", "syscon"; - reg = <0 0x11220000 0 0x2000>; - #clock-cells = <1>; - - afe: audio-controller { - ... - }; - }; diff --git a/Documentation/devicetree/bindings/arm/mediatek/mediatek,audsys.yaml b/Documentation/devicetree/bindings/arm/mediatek/mediatek,audsys.yaml new file mode 100644 index 000000000000..45d4a6620041 --- /dev/null +++ b/Documentation/devicetree/bindings/arm/mediatek/mediatek,audsys.yaml @@ -0,0 +1,153 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/arm/mediatek/mediatek,audsys.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: MediaTek AUDSYS controller + +maintainers: + - Eugen Hristev <eugen.hristev@collabora.com> + +description: + The MediaTek AUDSYS controller provides various clocks to the system. + +properties: + compatible: + oneOf: + - items: + - enum: + - mediatek,mt2701-audsys + - mediatek,mt6765-audsys + - mediatek,mt6779-audsys + - mediatek,mt7622-audsys + - mediatek,mt8167-audsys + - mediatek,mt8173-audsys + - mediatek,mt8183-audsys + - mediatek,mt8186-audsys + - mediatek,mt8192-audsys + - mediatek,mt8516-audsys + - const: syscon + - items: + # Special case for mt7623 for backward compatibility + - const: mediatek,mt7623-audsys + - const: mediatek,mt2701-audsys + - const: syscon + + reg: + maxItems: 1 + + '#clock-cells': + const: 1 + + audio-controller: + $ref: /schemas/sound/mediatek,mt2701-audio.yaml# + type: object + +required: + - compatible + - '#clock-cells' + +additionalProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/arm-gic.h> + #include <dt-bindings/interrupt-controller/irq.h> + #include <dt-bindings/power/mt2701-power.h> + #include <dt-bindings/clock/mt2701-clk.h> + soc { + #address-cells = <2>; + #size-cells = <2>; + audsys: clock-controller@11220000 { + compatible = "mediatek,mt7622-audsys", "syscon"; + reg = <0 0x11220000 0 0x2000>; + #clock-cells = <1>; + + afe: audio-controller { + compatible = "mediatek,mt2701-audio"; + interrupts = <GIC_SPI 104 IRQ_TYPE_LEVEL_LOW>, + <GIC_SPI 132 IRQ_TYPE_LEVEL_LOW>; + interrupt-names = "afe", "asys"; + power-domains = <&scpsys MT2701_POWER_DOMAIN_IFR_MSC>; + + clocks = <&infracfg CLK_INFRA_AUDIO>, + <&topckgen CLK_TOP_AUD_MUX1_SEL>, + <&topckgen CLK_TOP_AUD_MUX2_SEL>, + <&topckgen CLK_TOP_AUD_48K_TIMING>, + <&topckgen CLK_TOP_AUD_44K_TIMING>, + <&topckgen CLK_TOP_AUD_K1_SRC_SEL>, + <&topckgen CLK_TOP_AUD_K2_SRC_SEL>, + <&topckgen CLK_TOP_AUD_K3_SRC_SEL>, + <&topckgen CLK_TOP_AUD_K4_SRC_SEL>, + <&topckgen CLK_TOP_AUD_K1_SRC_DIV>, + <&topckgen CLK_TOP_AUD_K2_SRC_DIV>, + <&topckgen CLK_TOP_AUD_K3_SRC_DIV>, + <&topckgen CLK_TOP_AUD_K4_SRC_DIV>, + <&topckgen CLK_TOP_AUD_I2S1_MCLK>, + <&topckgen CLK_TOP_AUD_I2S2_MCLK>, + <&topckgen CLK_TOP_AUD_I2S3_MCLK>, + <&topckgen CLK_TOP_AUD_I2S4_MCLK>, + <&audsys CLK_AUD_I2SO1>, + <&audsys CLK_AUD_I2SO2>, + <&audsys CLK_AUD_I2SO3>, + <&audsys CLK_AUD_I2SO4>, + <&audsys CLK_AUD_I2SIN1>, + <&audsys CLK_AUD_I2SIN2>, + <&audsys CLK_AUD_I2SIN3>, + <&audsys CLK_AUD_I2SIN4>, + <&audsys CLK_AUD_ASRCO1>, + <&audsys CLK_AUD_ASRCO2>, + <&audsys CLK_AUD_ASRCO3>, + <&audsys CLK_AUD_ASRCO4>, + <&audsys CLK_AUD_AFE>, + <&audsys CLK_AUD_AFE_CONN>, + <&audsys CLK_AUD_A1SYS>, + <&audsys CLK_AUD_A2SYS>, + <&audsys CLK_AUD_AFE_MRGIF>; + + clock-names = "infra_sys_audio_clk", + "top_audio_mux1_sel", + "top_audio_mux2_sel", + "top_audio_a1sys_hp", + "top_audio_a2sys_hp", + "i2s0_src_sel", + "i2s1_src_sel", + "i2s2_src_sel", + "i2s3_src_sel", + "i2s0_src_div", + "i2s1_src_div", + "i2s2_src_div", + "i2s3_src_div", + "i2s0_mclk_en", + "i2s1_mclk_en", + "i2s2_mclk_en", + "i2s3_mclk_en", + "i2so0_hop_ck", + "i2so1_hop_ck", + "i2so2_hop_ck", + "i2so3_hop_ck", + "i2si0_hop_ck", + "i2si1_hop_ck", + "i2si2_hop_ck", + "i2si3_hop_ck", + "asrc0_out_ck", + "asrc1_out_ck", + "asrc2_out_ck", + "asrc3_out_ck", + "audio_afe_pd", + "audio_afe_conn_pd", + "audio_a1sys_pd", + "audio_a2sys_pd", + "audio_mrgif_pd"; + + assigned-clocks = <&topckgen CLK_TOP_AUD_MUX1_SEL>, + <&topckgen CLK_TOP_AUD_MUX2_SEL>, + <&topckgen CLK_TOP_AUD_MUX1_DIV>, + <&topckgen CLK_TOP_AUD_MUX2_DIV>; + assigned-clock-parents = <&topckgen CLK_TOP_AUD1PLL_98M>, + <&topckgen CLK_TOP_AUD2PLL_90M>; + assigned-clock-rates = <0>, <0>, <49152000>, <45158400>; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/arm/mediatek/mediatek,mmsys.yaml b/Documentation/devicetree/bindings/arm/mediatek/mediatek,mmsys.yaml index 536f5a5ebd24..b3c6888c1457 100644 --- a/Documentation/devicetree/bindings/arm/mediatek/mediatek,mmsys.yaml +++ b/Documentation/devicetree/bindings/arm/mediatek/mediatek,mmsys.yaml @@ -32,6 +32,9 @@ properties: - mediatek,mt8183-mmsys - mediatek,mt8186-mmsys - mediatek,mt8188-vdosys0 + - mediatek,mt8188-vdosys1 + - mediatek,mt8188-vppsys0 + - mediatek,mt8188-vppsys1 - mediatek,mt8192-mmsys - mediatek,mt8195-vdosys1 - mediatek,mt8195-vppsys0 diff --git a/Documentation/devicetree/bindings/arm/mediatek/mediatek,pericfg.yaml b/Documentation/devicetree/bindings/arm/mediatek/mediatek,pericfg.yaml index 26158d0d72f3..33c94c491828 100644 --- a/Documentation/devicetree/bindings/arm/mediatek/mediatek,pericfg.yaml +++ b/Documentation/devicetree/bindings/arm/mediatek/mediatek,pericfg.yaml @@ -28,6 +28,7 @@ properties: - mediatek,mt8173-pericfg - mediatek,mt8183-pericfg - mediatek,mt8186-pericfg + - mediatek,mt8188-pericfg - mediatek,mt8195-pericfg - mediatek,mt8516-pericfg - const: syscon diff --git a/Documentation/devicetree/bindings/arm/qcom-soc.yaml b/Documentation/devicetree/bindings/arm/qcom-soc.yaml index 97621c92a1ab..d0751a572af3 100644 --- a/Documentation/devicetree/bindings/arm/qcom-soc.yaml +++ b/Documentation/devicetree/bindings/arm/qcom-soc.yaml @@ -23,7 +23,7 @@ description: | select: properties: compatible: - pattern: "^qcom,.*(apq|ipq|mdm|msm|qcm|qcs|sa|sc|sdm|sdx|sm)[0-9]+.*$" + pattern: "^qcom,.*(apq|ipq|mdm|msm|qcm|qcs|q[dr]u|sa|sc|sd[amx]|sm|x1e)[0-9]+.*$" required: - compatible @@ -31,17 +31,17 @@ properties: compatible: oneOf: # Preferred naming style for compatibles of SoC components: - - pattern: "^qcom,(apq|ipq|mdm|msm|qcm|qcs|sa|sc|sdm|sdx|sm)[0-9]+(pro)?-.*$" + - pattern: "^qcom,(apq|ipq|mdm|msm|qcm|qcs|q[dr]u|sa|sc|sd[amx]|sm|x1e)[0-9]+(pro)?-.*$" - pattern: "^qcom,(sa|sc)8[0-9]+[a-z][a-z]?-.*$" # Legacy namings - variations of existing patterns/compatibles are OK, # but do not add completely new entries to these: - - pattern: "^qcom,[ak]pss-wdt-(apq|ipq|mdm|msm|qcm|qcs|sa|sc|sdm|sdx|sm)[0-9]+.*$" - - pattern: "^qcom,gcc-(apq|ipq|mdm|msm|qcm|qcs|sa|sc|sdm|sdx|sm)[0-9]+.*$" - - pattern: "^qcom,mmcc-(apq|ipq|mdm|msm|qcm|qcs|sa|sc|sdm|sdx|sm)[0-9]+.*$" - - pattern: "^qcom,pcie-(apq|ipq|mdm|msm|qcm|qcs|sa|sc|sdm|sdx|sm)[0-9]+.*$" - - pattern: "^qcom,rpm-(apq|ipq|mdm|msm|qcm|qcs|sa|sc|sdm|sdx|sm)[0-9]+.*$" - - pattern: "^qcom,scm-(apq|ipq|mdm|msm|qcm|qcs|sa|sc|sdm|sdx|sm)[0-9]+.*$" + - pattern: "^qcom,[ak]pss-wdt-(apq|ipq|mdm|msm|qcm|qcs|q[dr]u|sa|sc|sd[amx]|sm)[0-9]+.*$" + - pattern: "^qcom,gcc-(apq|ipq|mdm|msm|qcm|qcs|q[dr]u|sa|sc|sd[amx]|sm)[0-9]+.*$" + - pattern: "^qcom,mmcc-(apq|ipq|mdm|msm|qcm|qcs|q[dr]u|sa|sc|sd[amx]|sm)[0-9]+.*$" + - pattern: "^qcom,pcie-(apq|ipq|mdm|msm|qcm|qcs|q[dr]u|sa|sc|sd[amx]|sm|x1e)[0-9]+.*$" + - pattern: "^qcom,rpm-(apq|ipq|mdm|msm|qcm|qcs|q[dr]u|sa|sc|sd[amx]|sm)[0-9]+.*$" + - pattern: "^qcom,scm-(apq|ipq|mdm|msm|qcm|qcs|q[dr]u|sa|sc|sd[amx]|sm|x1e)[0-9]+.*$" - enum: - qcom,dsi-ctrl-6g-qcm2290 - qcom,gpucc-sdm630 diff --git a/Documentation/devicetree/bindings/arm/qcom.yaml b/Documentation/devicetree/bindings/arm/qcom.yaml index 7f80f48a0954..1a5fb889a444 100644 --- a/Documentation/devicetree/bindings/arm/qcom.yaml +++ b/Documentation/devicetree/bindings/arm/qcom.yaml @@ -87,29 +87,18 @@ description: | sm8350 sm8450 sm8550 + sm8650 + x1e80100 The 'board' element must be one of the following strings: adp - ap-al02-c2 - ap-al02-c6 - ap-al02-c7 - ap-al02-c8 - ap-al02-c9 - ap-mi01.2 - ap-mi01.3 - ap-mi01.6 - ap-mi01.9 cdp - cp01-c1 dragonboard - hk01 - hk10-c1 - hk10-c2 idp liquid - rdp432-c2 mtp + qcp qrd rb2 ride @@ -138,7 +127,7 @@ description: | There are many devices in the list below that run the standard ChromeOS bootloader setup and use the open source depthcharge bootloader to boot the OS. These devices do not use the scheme described above. For details, see: - https://docs.kernel.org/arm/google/chromebook-boot-flow.html + https://docs.kernel.org/arch/arm/google/chromebook-boot-flow.html properties: $nodename: @@ -186,11 +175,24 @@ properties: - items: - enum: + - microsoft,dempsey + - microsoft,makepeace + - microsoft,moneypenny - samsung,s3ve3g - const: qcom,msm8226 - items: - enum: + - htc,memul + - microsoft,superman-lte + - microsoft,tesla + - motorola,peregrine + - const: qcom,msm8926 + - const: qcom,msm8226 + + - items: + - enum: + - huawei,kiwi - longcheer,l9100 - samsung,a7 - sony,kanuti-tulip @@ -397,6 +399,8 @@ properties: - items: - enum: - fairphone,fp5 + - qcom,qcm6490-idp + - qcom,qcs6490-rb3gen2 - const: qcom,qcm6490 - description: Qualcomm Technologies, Inc. Distributed Unit 1000 platform @@ -1009,6 +1013,7 @@ properties: - sony,pdx203-generic - sony,pdx206-generic - xiaomi,elish + - xiaomi,pipa - const: qcom,sm8250 - items: @@ -1034,6 +1039,18 @@ properties: - qcom,sm8550-qrd - const: qcom,sm8550 + - items: + - enum: + - qcom,sm8650-mtp + - qcom,sm8650-qrd + - const: qcom,sm8650 + + - items: + - enum: + - qcom,x1e80100-crd + - qcom,x1e80100-qcp + - const: qcom,x1e80100 + # Board compatibles go above qcom,msm-id: diff --git a/Documentation/devicetree/bindings/arm/rockchip.yaml b/Documentation/devicetree/bindings/arm/rockchip.yaml index 5f7c6c4aad8f..5cf5cbef2cf5 100644 --- a/Documentation/devicetree/bindings/arm/rockchip.yaml +++ b/Documentation/devicetree/bindings/arm/rockchip.yaml @@ -30,9 +30,11 @@ properties: - const: amarula,vyasa-rk3288 - const: rockchip,rk3288 - - description: Anbernic RG351M + - description: Anbernic RK3326 Handheld Gaming Console items: - - const: anbernic,rg351m + - enum: + - anbernic,rg351m + - anbernic,rg351v - const: rockchip,rk3326 - description: Anbernic RG353P @@ -95,22 +97,30 @@ properties: - const: chipspark,rayeager-px2 - const: rockchip,rk3066a + - description: Cool Pi Compute Module 5(CM5) EVB + items: + - enum: + - coolpi,pi-cm5-evb + - const: coolpi,pi-cm5 + - const: rockchip,rk3588 + + - description: Cool Pi 4 Model B + items: + - const: coolpi,pi-4b + - const: rockchip,rk3588s + - description: Edgeble Neural Compute Module 2(Neu2) SoM based boards items: - const: edgeble,neural-compute-module-2-io # Edgeble Neural Compute Module 2 IO Board - const: edgeble,neural-compute-module-2 # Edgeble Neural Compute Module 2 SoM - const: rockchip,rv1126 - - description: Edgeble Neural Compute Module 6(Neu6) Model A SoM based boards - items: - - const: edgeble,neural-compute-module-6a-io # Edgeble Neural Compute Module 6A IO Board - - const: edgeble,neural-compute-module-6a # Edgeble Neural Compute Module 6A SoM - - const: rockchip,rk3588 - - - description: Edgeble Neural Compute Module 6(Neu6) Model B SoM based boards + - description: Edgeble Neural Compute Module 6(Neu6) SoM based boards items: - - const: edgeble,neural-compute-module-6b-io # Edgeble Neural Compute Module 6B IO Board - - const: edgeble,neural-compute-module-6b # Edgeble Neural Compute Module 6B SoM + - const: edgeble,neural-compute-module-6a-io # Edgeble NCM6A-IO Board + - enum: + - edgeble,neural-compute-module-6a # Edgeble Neural Compute Module 6A SoM + - edgeble,neural-compute-module-6b # Edgeble Neural Compute Module 6B SoM - const: rockchip,rk3588 - description: Elgin RV1108 R1 @@ -237,6 +247,11 @@ properties: - const: geekbuying,geekbox - const: rockchip,rk3368 + - description: Geniatech XPI-3128 + items: + - const: geniatech,xpi-3128 + - const: rockchip,rk3128 + - description: Google Bob (Asus Chromebook Flip C101PA) items: - const: google,bob-rev13 @@ -674,9 +689,12 @@ properties: - const: pine64,soquartz - const: rockchip,rk3566 - - description: Powkiddy RGB30 + - description: Powkiddy RK3566 Handheld Gaming Console items: - - const: powkiddy,rgb30 + - enum: + - powkiddy,rgb30 + - powkiddy,rk2023 + - powkiddy,x55 - const: rockchip,rk3566 - description: Radxa Compute Module 3(CM3) @@ -875,6 +893,11 @@ properties: - const: tsd,rk3399-puma-haikou - const: rockchip,rk3399 + - description: Theobroma Systems RK3588-SBC Jaguar + items: + - const: tsd,rk3588-jaguar + - const: rockchip,rk3588 + - description: Tronsmart Orion R68 Meta items: - const: tronsmart,orion-r68-meta @@ -922,6 +945,13 @@ properties: - const: rockchip,rk3568-bpi-r2pro - const: rockchip,rk3568 + - description: Sonoff iHost Smart Home Hub + items: + - const: itead,sonoff-ihost + - enum: + - rockchip,rv1126 + - rockchip,rv1109 + additionalProperties: true ... diff --git a/Documentation/devicetree/bindings/arm/samsung/samsung-boards.yaml b/Documentation/devicetree/bindings/arm/samsung/samsung-boards.yaml index e3ffd8159ab6..01dcbd8aa703 100644 --- a/Documentation/devicetree/bindings/arm/samsung/samsung-boards.yaml +++ b/Documentation/devicetree/bindings/arm/samsung/samsung-boards.yaml @@ -230,6 +230,12 @@ properties: - samsung,exynosautov9-sadk # Samsung Exynos Auto v9 SADK - const: samsung,exynosautov9 + - description: Exynos Auto v920 based boards + items: + - enum: + - samsung,exynosautov920-sadk # Samsung Exynos Auto v920 SADK + - const: samsung,exynosautov920 + required: - compatible diff --git a/Documentation/devicetree/bindings/arm/sprd/sprd.yaml b/Documentation/devicetree/bindings/arm/sprd/sprd.yaml index eaa67b8e0d6c..40fc3c8b9dce 100644 --- a/Documentation/devicetree/bindings/arm/sprd/sprd.yaml +++ b/Documentation/devicetree/bindings/arm/sprd/sprd.yaml @@ -35,6 +35,11 @@ properties: - sprd,ums512-1h10 - const: sprd,ums512 + - items: + - enum: + - sprd,ums9620-2h10 + - const: sprd,ums9620 + additionalProperties: true ... diff --git a/Documentation/devicetree/bindings/arm/stm32/stm32.yaml b/Documentation/devicetree/bindings/arm/stm32/stm32.yaml index df087c81c69e..bc2f43330ae4 100644 --- a/Documentation/devicetree/bindings/arm/stm32/stm32.yaml +++ b/Documentation/devicetree/bindings/arm/stm32/stm32.yaml @@ -82,29 +82,19 @@ properties: - shiratech,stm32mp157a-iot-box # IoT Box - shiratech,stm32mp157a-stinger96 # Stinger96 - st,stm32mp157c-ed1 + - st,stm32mp157c-ed1-scmi - st,stm32mp157a-dk1 + - st,stm32mp157a-dk1-scmi - st,stm32mp157c-dk2 + - st,stm32mp157c-dk2-scmi - const: st,stm32mp157 - items: - - const: st,stm32mp157a-dk1-scmi - - const: st,stm32mp157a-dk1 - - const: st,stm32mp157 - - items: - - const: st,stm32mp157c-dk2-scmi - - const: st,stm32mp157c-dk2 - - const: st,stm32mp157 - - items: - - const: st,stm32mp157c-ed1-scmi - - const: st,stm32mp157c-ed1 - - const: st,stm32mp157 - - items: - const: st,stm32mp157c-ev1 - const: st,stm32mp157c-ed1 - const: st,stm32mp157 - items: - const: st,stm32mp157c-ev1-scmi - - const: st,stm32mp157c-ev1 - const: st,stm32mp157c-ed1 - const: st,stm32mp157 diff --git a/Documentation/devicetree/bindings/arm/sunxi.yaml b/Documentation/devicetree/bindings/arm/sunxi.yaml index 11c5ce941dd7..a9d8e85565b8 100644 --- a/Documentation/devicetree/bindings/arm/sunxi.yaml +++ b/Documentation/devicetree/bindings/arm/sunxi.yaml @@ -868,6 +868,11 @@ properties: - const: topwise,a721 - const: allwinner,sun4i-a10 + - description: Transpeed 8K618-T + items: + - const: transpeed,8k618-t + - const: allwinner,sun50i-h618 + - description: Utoo P66 items: - const: utoo,p66 @@ -1013,6 +1018,11 @@ properties: - const: xunlong,orangepi-zero2 - const: allwinner,sun50i-h616 + - description: Xunlong OrangePi Zero 2W + items: + - const: xunlong,orangepi-zero2w + - const: allwinner,sun50i-h618 + - description: Xunlong OrangePi Zero 3 items: - const: xunlong,orangepi-zero3 diff --git a/Documentation/devicetree/bindings/arm/ti/k3.yaml b/Documentation/devicetree/bindings/arm/ti/k3.yaml index 03d2a0d79fb0..c6506bccfe88 100644 --- a/Documentation/devicetree/bindings/arm/ti/k3.yaml +++ b/Documentation/devicetree/bindings/arm/ti/k3.yaml @@ -50,6 +50,7 @@ properties: - enum: - toradex,verdin-am62-nonwifi-dahlia # Verdin AM62 Module on Dahlia - toradex,verdin-am62-nonwifi-dev # Verdin AM62 Module on Verdin Development Board + - toradex,verdin-am62-nonwifi-mallow # Verdin AM62 Module on Mallow - toradex,verdin-am62-nonwifi-yavia # Verdin AM62 Module on Yavia - const: toradex,verdin-am62-nonwifi # Verdin AM62 Module without Wi-Fi / BT - const: toradex,verdin-am62 # Verdin AM62 Module @@ -60,6 +61,7 @@ properties: - enum: - toradex,verdin-am62-wifi-dahlia # Verdin AM62 Wi-Fi / BT Module on Dahlia - toradex,verdin-am62-wifi-dev # Verdin AM62 Wi-Fi / BT M. on Verdin Development B. + - toradex,verdin-am62-wifi-mallow # Verdin AM62 Wi-Fi / BT Module on Mallow - toradex,verdin-am62-wifi-yavia # Verdin AM62 Wi-Fi / BT Module on Yavia - const: toradex,verdin-am62-wifi # Verdin AM62 Wi-Fi / BT Module - const: toradex,verdin-am62 # Verdin AM62 Module diff --git a/Documentation/devicetree/bindings/arm/ti/omap.yaml b/Documentation/devicetree/bindings/arm/ti/omap.yaml index b18fc046390a..93e04a109a12 100644 --- a/Documentation/devicetree/bindings/arm/ti/omap.yaml +++ b/Documentation/devicetree/bindings/arm/ti/omap.yaml @@ -134,6 +134,8 @@ properties: - amazon,omap4-kc1 # Amazon Kindle Fire (first generation) - motorola,droid4 # Motorola Droid 4 XT894 - motorola,droid-bionic # Motorola Droid Bionic XT875 + - motorola,xyboard-mz609 + - motorola,xyboard-mz617 - ti,omap4-panda - ti,omap4-sdp - const: ti,omap4430 diff --git a/Documentation/devicetree/bindings/cache/qcom,llcc.yaml b/Documentation/devicetree/bindings/cache/qcom,llcc.yaml index 580f9a97ddf7..b9a9f2cf32a1 100644 --- a/Documentation/devicetree/bindings/cache/qcom,llcc.yaml +++ b/Documentation/devicetree/bindings/cache/qcom,llcc.yaml @@ -33,6 +33,8 @@ properties: - qcom,sm8350-llcc - qcom,sm8450-llcc - qcom,sm8550-llcc + - qcom,sm8650-llcc + - qcom,x1e80100-llcc reg: minItems: 2 @@ -104,6 +106,7 @@ allOf: - qcom,qdu1000-llcc - qcom,sc8180x-llcc - qcom,sc8280xp-llcc + - qcom,x1e80100-llcc then: properties: reg: diff --git a/Documentation/devicetree/bindings/cache/sifive,ccache0.yaml b/Documentation/devicetree/bindings/cache/sifive,ccache0.yaml index 8a6a78e1a7ab..7e8cebe21584 100644 --- a/Documentation/devicetree/bindings/cache/sifive,ccache0.yaml +++ b/Documentation/devicetree/bindings/cache/sifive,ccache0.yaml @@ -38,7 +38,9 @@ properties: - sifive,fu740-c000-ccache - const: cache - items: - - const: starfive,jh7110-ccache + - enum: + - starfive,jh7100-ccache + - starfive,jh7110-ccache - const: sifive,ccache0 - const: cache - items: @@ -88,6 +90,7 @@ allOf: contains: enum: - sifive,fu740-c000-ccache + - starfive,jh7100-ccache - starfive,jh7110-ccache - microchip,mpfs-ccache @@ -111,6 +114,7 @@ allOf: contains: enum: - sifive,fu740-c000-ccache + - starfive,jh7100-ccache - starfive,jh7110-ccache then: diff --git a/Documentation/devicetree/bindings/clock/google,gs101-clock.yaml b/Documentation/devicetree/bindings/clock/google,gs101-clock.yaml new file mode 100644 index 000000000000..3eebc03a309b --- /dev/null +++ b/Documentation/devicetree/bindings/clock/google,gs101-clock.yaml @@ -0,0 +1,106 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/clock/google,gs101-clock.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Google GS101 SoC clock controller + +maintainers: + - Peter Griffin <peter.griffin@linaro.org> + +description: | + Google GS101 clock controller is comprised of several CMU units, generating + clocks for different domains. Those CMU units are modeled as separate device + tree nodes, and might depend on each other. The root clock in that clock tree + is OSCCLK (24.576 MHz). That external clock must be defined as a fixed-rate + clock in dts. + + CMU_TOP is a top-level CMU, where all base clocks are prepared using PLLs and + dividers; all other leaf clocks (other CMUs) are usually derived from CMU_TOP. + + Each clock is assigned an identifier and client nodes can use this identifier + to specify the clock which they consume. All clocks available for usage + in clock consumer nodes are defined as preprocessor macros in + 'dt-bindings/clock/gs101.h' header. + +properties: + compatible: + enum: + - google,gs101-cmu-top + - google,gs101-cmu-apm + - google,gs101-cmu-misc + + clocks: + minItems: 1 + maxItems: 2 + + clock-names: + minItems: 1 + maxItems: 2 + + "#clock-cells": + const: 1 + + reg: + maxItems: 1 + +required: + - compatible + - "#clock-cells" + - clocks + - clock-names + - reg + +allOf: + - if: + properties: + compatible: + contains: + enum: + - google,gs101-cmu-top + - google,gs101-cmu-apm + then: + properties: + clocks: + items: + - description: External reference clock (24.576 MHz) + + clock-names: + items: + - const: oscclk + + - if: + properties: + compatible: + contains: + const: google,gs101-cmu-misc + + then: + properties: + clocks: + items: + - description: Misc bus clock (from CMU_TOP) + - description: Misc sss clock (from CMU_TOP) + + clock-names: + items: + - const: dout_cmu_misc_bus + - const: dout_cmu_misc_sss + +additionalProperties: false + +examples: + # Clock controller node for CMU_TOP + - | + #include <dt-bindings/clock/google,gs101.h> + + cmu_top: clock-controller@1e080000 { + compatible = "google,gs101-cmu-top"; + reg = <0x1e080000 0x8000>; + #clock-cells = <1>; + clocks = <&ext_24_5m>; + clock-names = "oscclk"; + }; + +... diff --git a/Documentation/devicetree/bindings/clock/hi3620-clock.txt b/Documentation/devicetree/bindings/clock/hi3620-clock.txt deleted file mode 100644 index dad6269f52c5..000000000000 --- a/Documentation/devicetree/bindings/clock/hi3620-clock.txt +++ /dev/null @@ -1,20 +0,0 @@ -* Hisilicon Hi3620 Clock Controller - -The Hi3620 clock controller generates and supplies clock to various -controllers within the Hi3620 SoC. - -Required Properties: - -- compatible: should be one of the following. - - "hisilicon,hi3620-clock" - controller compatible with Hi3620 SoC. - - "hisilicon,hi3620-mmc-clock" - controller specific for Hi3620 mmc. - -- 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 use this identifier -to specify the clock which they consume. - -All these identifier could be found in <dt-bindings/clock/hi3620-clock.h>. diff --git a/Documentation/devicetree/bindings/clock/mediatek,mt8188-clock.yaml b/Documentation/devicetree/bindings/clock/mediatek,mt8188-clock.yaml index d7214d97b2ba..860570320545 100644 --- a/Documentation/devicetree/bindings/clock/mediatek,mt8188-clock.yaml +++ b/Documentation/devicetree/bindings/clock/mediatek,mt8188-clock.yaml @@ -43,8 +43,6 @@ properties: - mediatek,mt8188-vdecsys - mediatek,mt8188-vdecsys-soc - mediatek,mt8188-vencsys - - mediatek,mt8188-vppsys0 - - mediatek,mt8188-vppsys1 - mediatek,mt8188-wpesys - mediatek,mt8188-wpesys-vpp0 diff --git a/Documentation/devicetree/bindings/clock/qcom,camcc-sm8250.yaml b/Documentation/devicetree/bindings/clock/qcom,camcc-sm8250.yaml index 426335a2841c..3fd3dc1069fb 100644 --- a/Documentation/devicetree/bindings/clock/qcom,camcc-sm8250.yaml +++ b/Documentation/devicetree/bindings/clock/qcom,camcc-sm8250.yaml @@ -15,6 +15,9 @@ description: | See also:: include/dt-bindings/clock/qcom,camcc-sm8250.h +allOf: + - $ref: qcom,gcc.yaml# + properties: compatible: const: qcom,sm8250-camcc @@ -33,15 +36,6 @@ properties: - const: bi_tcxo_ao - const: sleep_clk - '#clock-cells': - const: 1 - - '#reset-cells': - const: 1 - - '#power-domain-cells': - const: 1 - power-domains: items: - description: MMCX power domain @@ -56,14 +50,10 @@ properties: required: - compatible - - reg - clocks - clock-names - - '#clock-cells' - - '#reset-cells' - - '#power-domain-cells' -additionalProperties: false +unevaluatedProperties: false examples: - | diff --git a/Documentation/devicetree/bindings/clock/qcom,gcc-ipq8074.yaml b/Documentation/devicetree/bindings/clock/qcom,gcc-ipq8074.yaml index 52e7831a8d6d..2d44ddc45aab 100644 --- a/Documentation/devicetree/bindings/clock/qcom,gcc-ipq8074.yaml +++ b/Documentation/devicetree/bindings/clock/qcom,gcc-ipq8074.yaml @@ -27,11 +27,15 @@ properties: items: - description: board XO clock - description: sleep clock + - description: Gen3 QMP PCIe PHY PIPE clock + - description: Gen2 QMP PCIe PHY PIPE clock clock-names: items: - const: xo - const: sleep_clk + - const: pcie0_pipe + - const: pcie1_pipe required: - compatible diff --git a/Documentation/devicetree/bindings/clock/qcom,rpmhcc.yaml b/Documentation/devicetree/bindings/clock/qcom,rpmhcc.yaml index 4eb5e59f6772..ca857942ed6c 100644 --- a/Documentation/devicetree/bindings/clock/qcom,rpmhcc.yaml +++ b/Documentation/devicetree/bindings/clock/qcom,rpmhcc.yaml @@ -35,6 +35,8 @@ properties: - qcom,sm8350-rpmh-clk - qcom,sm8450-rpmh-clk - qcom,sm8550-rpmh-clk + - qcom,sm8650-rpmh-clk + - qcom,x1e80100-rpmh-clk clocks: maxItems: 1 diff --git a/Documentation/devicetree/bindings/clock/qcom,sc7180-camcc.yaml b/Documentation/devicetree/bindings/clock/qcom,sc7180-camcc.yaml index 2dfc2a4f1918..c7fe6400ea13 100644 --- a/Documentation/devicetree/bindings/clock/qcom,sc7180-camcc.yaml +++ b/Documentation/devicetree/bindings/clock/qcom,sc7180-camcc.yaml @@ -15,6 +15,9 @@ description: | See also:: include/dt-bindings/clock/qcom,camcc-sc7180.h +allOf: + - $ref: qcom,gcc.yaml# + properties: compatible: const: qcom,sc7180-camcc @@ -31,28 +34,15 @@ properties: - const: iface - const: xo - '#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 +unevaluatedProperties: false examples: - | diff --git a/Documentation/devicetree/bindings/clock/qcom,sc7280-camcc.yaml b/Documentation/devicetree/bindings/clock/qcom,sc7280-camcc.yaml index 01feef1cab0a..dcef8de3a905 100644 --- a/Documentation/devicetree/bindings/clock/qcom,sc7280-camcc.yaml +++ b/Documentation/devicetree/bindings/clock/qcom,sc7280-camcc.yaml @@ -15,6 +15,9 @@ description: | See also:: include/dt-bindings/clock/qcom,camcc-sc7280.h +allOf: + - $ref: qcom,gcc.yaml# + properties: compatible: const: qcom,sc7280-camcc @@ -31,28 +34,15 @@ properties: - const: bi_tcxo_ao - const: sleep_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 +unevaluatedProperties: false examples: - | diff --git a/Documentation/devicetree/bindings/clock/qcom,sdm845-camcc.yaml b/Documentation/devicetree/bindings/clock/qcom,sdm845-camcc.yaml index 91d1f7918037..810b852ae371 100644 --- a/Documentation/devicetree/bindings/clock/qcom,sdm845-camcc.yaml +++ b/Documentation/devicetree/bindings/clock/qcom,sdm845-camcc.yaml @@ -15,6 +15,9 @@ description: | See also:: include/dt-bindings/clock/qcom,camcc-sm845.h +allOf: + - $ref: qcom,gcc.yaml# + properties: compatible: const: qcom,sdm845-camcc @@ -27,28 +30,15 @@ properties: items: - const: bi_tcxo - '#clock-cells': - const: 1 - - '#reset-cells': - const: 1 - - '#power-domain-cells': - const: 1 - reg: maxItems: 1 required: - compatible - - reg - clocks - clock-names - - '#clock-cells' - - '#reset-cells' - - '#power-domain-cells' -additionalProperties: false +unevaluatedProperties: false examples: - | diff --git a/Documentation/devicetree/bindings/clock/qcom,sm8450-camcc.yaml b/Documentation/devicetree/bindings/clock/qcom,sm8450-camcc.yaml index dc3c18e4ead7..48986460f994 100644 --- a/Documentation/devicetree/bindings/clock/qcom,sm8450-camcc.yaml +++ b/Documentation/devicetree/bindings/clock/qcom,sm8450-camcc.yaml @@ -16,10 +16,15 @@ description: | See also:: include/dt-bindings/clock/qcom,sm8450-camcc.h include/dt-bindings/clock/qcom,sm8550-camcc.h + include/dt-bindings/clock/qcom,sc8280xp-camcc.h + +allOf: + - $ref: qcom,gcc.yaml# properties: compatible: enum: + - qcom,sc8280xp-camcc - qcom,sm8450-camcc - qcom,sm8550-camcc @@ -40,29 +45,16 @@ properties: description: A phandle to an OPP node describing required MMCX performance point. - '#clock-cells': - const: 1 - - '#reset-cells': - const: 1 - - '#power-domain-cells': - const: 1 - reg: maxItems: 1 required: - compatible - - reg - clocks - power-domains - required-opps - - '#clock-cells' - - '#reset-cells' - - '#power-domain-cells' -additionalProperties: false +unevaluatedProperties: false examples: - | diff --git a/Documentation/devicetree/bindings/clock/qcom,sm8450-gpucc.yaml b/Documentation/devicetree/bindings/clock/qcom,sm8450-gpucc.yaml index 2320be920a5f..1a384e8532a5 100644 --- a/Documentation/devicetree/bindings/clock/qcom,sm8450-gpucc.yaml +++ b/Documentation/devicetree/bindings/clock/qcom,sm8450-gpucc.yaml @@ -17,12 +17,14 @@ description: | include/dt-bindings/clock/qcom,sm8450-gpucc.h include/dt-bindings/clock/qcom,sm8550-gpucc.h include/dt-bindings/reset/qcom,sm8450-gpucc.h + include/dt-bindings/reset/qcom,sm8650-gpucc.h properties: compatible: enum: - qcom,sm8450-gpucc - qcom,sm8550-gpucc + - qcom,sm8650-gpucc clocks: items: diff --git a/Documentation/devicetree/bindings/clock/qcom,sm8550-tcsr.yaml b/Documentation/devicetree/bindings/clock/qcom,sm8550-tcsr.yaml index 1bf1a41fd89c..af16b05eac96 100644 --- a/Documentation/devicetree/bindings/clock/qcom,sm8550-tcsr.yaml +++ b/Documentation/devicetree/bindings/clock/qcom,sm8550-tcsr.yaml @@ -13,12 +13,16 @@ description: | Qualcomm TCSR clock control module provides the clocks, resets and power domains on SM8550 - See also:: include/dt-bindings/clock/qcom,sm8550-tcsr.h + See also: + - include/dt-bindings/clock/qcom,sm8550-tcsr.h + - include/dt-bindings/clock/qcom,sm8650-tcsr.h properties: compatible: items: - - const: qcom,sm8550-tcsr + - enum: + - qcom,sm8550-tcsr + - qcom,sm8650-tcsr - const: syscon clocks: diff --git a/Documentation/devicetree/bindings/clock/qcom,sm8650-dispcc.yaml b/Documentation/devicetree/bindings/clock/qcom,sm8650-dispcc.yaml new file mode 100644 index 000000000000..5e0c45c380f5 --- /dev/null +++ b/Documentation/devicetree/bindings/clock/qcom,sm8650-dispcc.yaml @@ -0,0 +1,106 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/clock/qcom,sm8650-dispcc.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Qualcomm Display Clock & Reset Controller for SM8650 + +maintainers: + - Bjorn Andersson <andersson@kernel.org> + - Neil Armstrong <neil.armstrong@linaro.org> + +description: | + Qualcomm display clock control module provides the clocks, resets and power + domains on SM8650. + + See also:: include/dt-bindings/clock/qcom,sm8650-dispcc.h + +properties: + compatible: + enum: + - qcom,sm8650-dispcc + + clocks: + items: + - description: Board XO source + - description: Board Always On XO source + - description: Display's AHB clock + - description: sleep clock + - description: Byte clock from DSI PHY0 + - description: Pixel clock from DSI PHY0 + - description: Byte clock from DSI PHY1 + - description: Pixel clock from DSI PHY1 + - description: Link clock from DP PHY0 + - description: VCO DIV clock from DP PHY0 + - description: Link clock from DP PHY1 + - description: VCO DIV clock from DP PHY1 + - description: Link clock from DP PHY2 + - description: VCO DIV clock from DP PHY2 + - description: Link clock from DP PHY3 + - description: VCO DIV clock from DP PHY3 + + '#clock-cells': + const: 1 + + '#reset-cells': + const: 1 + + '#power-domain-cells': + const: 1 + + reg: + maxItems: 1 + + power-domains: + description: + A phandle and PM domain specifier for the MMCX power domain. + maxItems: 1 + + required-opps: + description: + A phandle to an OPP node describing required MMCX performance point. + maxItems: 1 + +required: + - compatible + - reg + - clocks + - '#clock-cells' + - '#reset-cells' + - '#power-domain-cells' + +additionalProperties: false + +examples: + - | + #include <dt-bindings/clock/qcom,sm8650-gcc.h> + #include <dt-bindings/clock/qcom,rpmh.h> + #include <dt-bindings/power/qcom-rpmpd.h> + #include <dt-bindings/power/qcom,rpmhpd.h> + clock-controller@af00000 { + compatible = "qcom,sm8650-dispcc"; + reg = <0x0af00000 0x10000>; + clocks = <&rpmhcc RPMH_CXO_CLK>, + <&rpmhcc RPMH_CXO_CLK_A>, + <&gcc GCC_DISP_AHB_CLK>, + <&sleep_clk>, + <&dsi0_phy 0>, + <&dsi0_phy 1>, + <&dsi1_phy 0>, + <&dsi1_phy 1>, + <&dp0_phy 0>, + <&dp0_phy 1>, + <&dp1_phy 0>, + <&dp1_phy 1>, + <&dp2_phy 0>, + <&dp2_phy 1>, + <&dp3_phy 0>, + <&dp3_phy 1>; + #clock-cells = <1>; + #reset-cells = <1>; + #power-domain-cells = <1>; + power-domains = <&rpmhpd RPMHPD_MMCX>; + required-opps = <&rpmhpd_opp_low_svs>; + }; +... diff --git a/Documentation/devicetree/bindings/clock/qcom,sm8650-gcc.yaml b/Documentation/devicetree/bindings/clock/qcom,sm8650-gcc.yaml new file mode 100644 index 000000000000..b54761cc8674 --- /dev/null +++ b/Documentation/devicetree/bindings/clock/qcom,sm8650-gcc.yaml @@ -0,0 +1,65 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/clock/qcom,sm8650-gcc.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Qualcomm Global Clock & Reset Controller on SM8650 + +maintainers: + - Bjorn Andersson <andersson@kernel.org> + +description: | + Qualcomm global clock control module provides the clocks, resets and power + domains on SM8650 + + See also:: include/dt-bindings/clock/qcom,sm8650-gcc.h + +properties: + compatible: + const: qcom,sm8650-gcc + + clocks: + items: + - description: Board XO source + - description: Board Always On XO source + - description: Sleep clock source + - description: PCIE 0 Pipe clock source + - description: PCIE 1 Pipe clock source + - description: PCIE 1 Phy Auxiliary clock source + - description: UFS Phy Rx symbol 0 clock source + - description: UFS Phy Rx symbol 1 clock source + - description: UFS Phy Tx symbol 0 clock source + - description: USB3 Phy wrapper pipe clock source + +required: + - compatible + - clocks + +allOf: + - $ref: qcom,gcc.yaml# + +unevaluatedProperties: false + +examples: + - | + #include <dt-bindings/clock/qcom,rpmh.h> + clock-controller@100000 { + compatible = "qcom,sm8650-gcc"; + reg = <0x00100000 0x001f4200>; + clocks = <&rpmhcc RPMH_CXO_CLK>, + <&rpmhcc RPMH_CXO_CLK_A>, + <&sleep_clk>, + <&pcie0_phy>, + <&pcie1_phy>, + <&pcie_1_phy_aux_clk>, + <&ufs_mem_phy 0>, + <&ufs_mem_phy 1>, + <&ufs_mem_phy 2>, + <&usb_1_qmpphy>; + #clock-cells = <1>; + #reset-cells = <1>; + #power-domain-cells = <1>; + }; + +... diff --git a/Documentation/devicetree/bindings/clock/qcom,x1e80100-gcc.yaml b/Documentation/devicetree/bindings/clock/qcom,x1e80100-gcc.yaml new file mode 100644 index 000000000000..14a796dbf8bc --- /dev/null +++ b/Documentation/devicetree/bindings/clock/qcom,x1e80100-gcc.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,x1e80100-gcc.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Qualcomm Global Clock & Reset Controller on X1E80100 + +maintainers: + - Rajendra Nayak <quic_rjendra@quicinc.com> + +description: | + Qualcomm global clock control module provides the clocks, resets and power + domains on X1E80100 + + See also:: include/dt-bindings/clock/qcom,x1e80100-gcc.h + +properties: + compatible: + const: qcom,x1e80100-gcc + + clocks: + items: + - description: Board XO source + - description: Sleep clock source + - description: PCIe 3 pipe clock + - description: PCIe 4 pipe clock + - description: PCIe 5 pipe clock + - description: PCIe 6a pipe clock + - description: PCIe 6b pipe clock + - description: USB QMP Phy 0 clock source + - description: USB QMP Phy 1 clock source + - description: USB QMP Phy 2 clock source + + power-domains: + description: + A phandle and PM domain specifier for the CX power domain. + maxItems: 1 + +required: + - compatible + - clocks + - power-domains + +allOf: + - $ref: qcom,gcc.yaml# + +unevaluatedProperties: false + +examples: + - | + #include <dt-bindings/power/qcom,rpmhpd.h> + clock-controller@100000 { + compatible = "qcom,x1e80100-gcc"; + reg = <0x00100000 0x200000>; + clocks = <&bi_tcxo_div2>, + <&sleep_clk>, + <&pcie3_phy>, + <&pcie4_phy>, + <&pcie5_phy>, + <&pcie6a_phy>, + <&pcie6b_phy>, + <&usb_1_ss0_qmpphy 0>, + <&usb_1_ss1_qmpphy 1>, + <&usb_1_ss2_qmpphy 2>; + power-domains = <&rpmhpd RPMHPD_CX>; + #clock-cells = <1>; + #reset-cells = <1>; + #power-domain-cells = <1>; + }; + +... diff --git a/Documentation/devicetree/bindings/crypto/inside-secure,safexcel.yaml b/Documentation/devicetree/bindings/crypto/inside-secure,safexcel.yaml new file mode 100644 index 000000000000..ef07258d16c1 --- /dev/null +++ b/Documentation/devicetree/bindings/crypto/inside-secure,safexcel.yaml @@ -0,0 +1,86 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/crypto/inside-secure,safexcel.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Inside Secure SafeXcel cryptographic engine + +maintainers: + - Antoine Tenart <atenart@kernel.org> + +properties: + compatible: + oneOf: + - const: inside-secure,safexcel-eip197b + - const: inside-secure,safexcel-eip197d + - const: inside-secure,safexcel-eip97ies + - const: inside-secure,safexcel-eip197 + description: Equivalent of inside-secure,safexcel-eip197b + deprecated: true + - const: inside-secure,safexcel-eip97 + description: Equivalent of inside-secure,safexcel-eip97ies + deprecated: true + + reg: + maxItems: 1 + + interrupts: + maxItems: 6 + + interrupt-names: + items: + - const: ring0 + - const: ring1 + - const: ring2 + - const: ring3 + - const: eip + - const: mem + + clocks: + minItems: 1 + maxItems: 2 + + clock-names: + minItems: 1 + items: + - const: core + - const: reg + +required: + - reg + - interrupts + - interrupt-names + +allOf: + - if: + properties: + clocks: + minItems: 2 + then: + properties: + clock-names: + minItems: 2 + required: + - clock-names + +additionalProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/arm-gic.h> + #include <dt-bindings/interrupt-controller/irq.h> + + crypto@800000 { + compatible = "inside-secure,safexcel-eip197b"; + reg = <0x800000 0x200000>; + interrupts = <GIC_SPI 54 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 55 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 56 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 57 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 58 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 34 IRQ_TYPE_LEVEL_HIGH>; + interrupt-names = "ring0", "ring1", "ring2", "ring3", "eip", "mem"; + clocks = <&cpm_syscon0 1 26>; + clock-names = "core"; + }; diff --git a/Documentation/devicetree/bindings/crypto/inside-secure-safexcel.txt b/Documentation/devicetree/bindings/crypto/inside-secure-safexcel.txt deleted file mode 100644 index 3bbf144c9988..000000000000 --- a/Documentation/devicetree/bindings/crypto/inside-secure-safexcel.txt +++ /dev/null @@ -1,40 +0,0 @@ -Inside Secure SafeXcel cryptographic engine - -Required properties: -- compatible: Should be "inside-secure,safexcel-eip197b", - "inside-secure,safexcel-eip197d" or - "inside-secure,safexcel-eip97ies". -- reg: Base physical address of the engine and length of memory mapped region. -- interrupts: Interrupt numbers for the rings and engine. -- interrupt-names: Should be "ring0", "ring1", "ring2", "ring3", "eip", "mem". - -Optional properties: -- clocks: Reference to the crypto engine clocks, the second clock is - needed for the Armada 7K/8K SoCs. -- clock-names: mandatory if there is a second clock, in this case the - name must be "core" for the first clock and "reg" for - the second one. - -Backward compatibility: -Two compatibles are kept for backward compatibility, but shouldn't be used for -new submissions: -- "inside-secure,safexcel-eip197" is equivalent to - "inside-secure,safexcel-eip197b". -- "inside-secure,safexcel-eip97" is equivalent to - "inside-secure,safexcel-eip97ies". - -Example: - - crypto: crypto@800000 { - compatible = "inside-secure,safexcel-eip197b"; - reg = <0x800000 0x200000>; - interrupts = <GIC_SPI 34 IRQ_TYPE_LEVEL_HIGH>, - <GIC_SPI 54 IRQ_TYPE_LEVEL_HIGH>, - <GIC_SPI 55 IRQ_TYPE_LEVEL_HIGH>, - <GIC_SPI 56 IRQ_TYPE_LEVEL_HIGH>, - <GIC_SPI 57 IRQ_TYPE_LEVEL_HIGH>, - <GIC_SPI 58 IRQ_TYPE_LEVEL_HIGH>; - interrupt-names = "mem", "ring0", "ring1", "ring2", "ring3", - "eip"; - clocks = <&cpm_syscon0 1 26>; - }; diff --git a/Documentation/devicetree/bindings/crypto/qcom,inline-crypto-engine.yaml b/Documentation/devicetree/bindings/crypto/qcom,inline-crypto-engine.yaml index ca4f7d1cefaa..09e43157cc71 100644 --- a/Documentation/devicetree/bindings/crypto/qcom,inline-crypto-engine.yaml +++ b/Documentation/devicetree/bindings/crypto/qcom,inline-crypto-engine.yaml @@ -16,6 +16,7 @@ properties: - qcom,sa8775p-inline-crypto-engine - qcom,sm8450-inline-crypto-engine - qcom,sm8550-inline-crypto-engine + - qcom,sm8650-inline-crypto-engine - const: qcom,inline-crypto-engine reg: diff --git a/Documentation/devicetree/bindings/crypto/qcom,prng.yaml b/Documentation/devicetree/bindings/crypto/qcom,prng.yaml index 13070db0f70c..89c88004b41b 100644 --- a/Documentation/devicetree/bindings/crypto/qcom,prng.yaml +++ b/Documentation/devicetree/bindings/crypto/qcom,prng.yaml @@ -21,6 +21,7 @@ properties: - qcom,sc7280-trng - qcom,sm8450-trng - qcom,sm8550-trng + - qcom,sm8650-trng - const: qcom,trng reg: diff --git a/Documentation/devicetree/bindings/crypto/qcom-qce.yaml b/Documentation/devicetree/bindings/crypto/qcom-qce.yaml index 8e665d910e6e..a48bd381063a 100644 --- a/Documentation/devicetree/bindings/crypto/qcom-qce.yaml +++ b/Documentation/devicetree/bindings/crypto/qcom-qce.yaml @@ -44,10 +44,12 @@ properties: - items: - enum: + - qcom,sc7280-qce - qcom,sm8250-qce - qcom,sm8350-qce - qcom,sm8450-qce - qcom,sm8550-qce + - qcom,sm8650-qce - const: qcom,sm8150-qce - const: qcom,qce @@ -96,6 +98,7 @@ allOf: - qcom,crypto-v5.4 - qcom,ipq6018-qce - qcom,ipq8074-qce + - qcom,ipq9574-qce - qcom,msm8996-qce - qcom,sdm845-qce then: @@ -129,6 +132,17 @@ allOf: - clocks - clock-names + - if: + properties: + compatible: + contains: + enum: + - qcom,sm8150-qce + then: + properties: + clocks: false + clock-names: false + required: - compatible - reg diff --git a/Documentation/devicetree/bindings/display/mediatek/mediatek,aal.yaml b/Documentation/devicetree/bindings/display/mediatek/mediatek,aal.yaml index 7fd42c8fdc32..b4c28e96dd55 100644 --- a/Documentation/devicetree/bindings/display/mediatek/mediatek,aal.yaml +++ b/Documentation/devicetree/bindings/display/mediatek/mediatek,aal.yaml @@ -24,6 +24,7 @@ properties: - enum: - mediatek,mt8173-disp-aal - mediatek,mt8183-disp-aal + - mediatek,mt8195-mdp3-aal - items: - enum: - mediatek,mt2712-disp-aal diff --git a/Documentation/devicetree/bindings/display/mediatek/mediatek,color.yaml b/Documentation/devicetree/bindings/display/mediatek/mediatek,color.yaml index f21e44092043..b886ca0d89ea 100644 --- a/Documentation/devicetree/bindings/display/mediatek/mediatek,color.yaml +++ b/Documentation/devicetree/bindings/display/mediatek/mediatek,color.yaml @@ -26,6 +26,7 @@ properties: - mediatek,mt2701-disp-color - mediatek,mt8167-disp-color - mediatek,mt8173-disp-color + - mediatek,mt8195-mdp3-color - items: - enum: - mediatek,mt7623-disp-color diff --git a/Documentation/devicetree/bindings/display/mediatek/mediatek,dsi.yaml b/Documentation/devicetree/bindings/display/mediatek/mediatek,dsi.yaml index ed24b617090b..8611319bed2e 100644 --- a/Documentation/devicetree/bindings/display/mediatek/mediatek,dsi.yaml +++ b/Documentation/devicetree/bindings/display/mediatek/mediatek,dsi.yaml @@ -34,6 +34,10 @@ properties: - enum: - mediatek,mt6795-dsi - const: mediatek,mt8173-dsi + - items: + - enum: + - mediatek,mt8195-dsi + - const: mediatek,mt8183-dsi reg: maxItems: 1 diff --git a/Documentation/devicetree/bindings/display/mediatek/mediatek,mdp-rdma.yaml b/Documentation/devicetree/bindings/display/mediatek/mediatek,mdp-rdma.yaml deleted file mode 100644 index 7570a0684967..000000000000 --- a/Documentation/devicetree/bindings/display/mediatek/mediatek,mdp-rdma.yaml +++ /dev/null @@ -1,92 +0,0 @@ -# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) -%YAML 1.2 ---- -$id: http://devicetree.org/schemas/display/mediatek/mediatek,mdp-rdma.yaml# -$schema: http://devicetree.org/meta-schemas/core.yaml# - -title: MediaTek MDP RDMA - -maintainers: - - Chun-Kuang Hu <chunkuang.hu@kernel.org> - - Philipp Zabel <p.zabel@pengutronix.de> - -description: - The MediaTek MDP RDMA stands for Read Direct Memory Access. - It provides real time data to the back-end panel driver, such as DSI, - DPI and DP_INTF. - It contains one line buffer to store the sufficient pixel data. - RDMA device node must be siblings to the central MMSYS_CONFIG node. - For a description of the MMSYS_CONFIG binding, see - Documentation/devicetree/bindings/arm/mediatek/mediatek,mmsys.yaml for details. - -properties: - compatible: - oneOf: - - const: mediatek,mt8195-vdo1-rdma - - items: - - const: mediatek,mt8188-vdo1-rdma - - const: mediatek,mt8195-vdo1-rdma - - reg: - maxItems: 1 - - interrupts: - maxItems: 1 - - power-domains: - maxItems: 1 - - clocks: - items: - - description: RDMA Clock - - iommus: - maxItems: 1 - - mediatek,gce-client-reg: - description: - The register of display function block to be set by gce. There are 4 arguments, - such as gce node, subsys id, offset and register size. The subsys id that is - mapping to the register of display function blocks is defined in the gce header - include/dt-bindings/gce/<chip>-gce.h of each chips. - $ref: /schemas/types.yaml#/definitions/phandle-array - items: - items: - - description: phandle of GCE - - description: GCE subsys id - - description: register offset - - description: register size - maxItems: 1 - -required: - - compatible - - reg - - power-domains - - clocks - - iommus - - mediatek,gce-client-reg - -additionalProperties: false - -examples: - - | - #include <dt-bindings/interrupt-controller/arm-gic.h> - #include <dt-bindings/clock/mt8195-clk.h> - #include <dt-bindings/power/mt8195-power.h> - #include <dt-bindings/gce/mt8195-gce.h> - #include <dt-bindings/memory/mt8195-memory-port.h> - - soc { - #address-cells = <2>; - #size-cells = <2>; - - rdma@1c104000 { - compatible = "mediatek,mt8195-vdo1-rdma"; - reg = <0 0x1c104000 0 0x1000>; - interrupts = <GIC_SPI 495 IRQ_TYPE_LEVEL_HIGH 0>; - clocks = <&vdosys1 CLK_VDO1_MDP_RDMA0>; - power-domains = <&spm MT8195_POWER_DOMAIN_VDOSYS1>; - iommus = <&iommu_vdo M4U_PORT_L2_MDP_RDMA0>; - mediatek,gce-client-reg = <&gce0 SUBSYS_1c10XXXX 0x4000 0x1000>; - }; - }; diff --git a/Documentation/devicetree/bindings/display/mediatek/mediatek,merge.yaml b/Documentation/devicetree/bindings/display/mediatek/mediatek,merge.yaml index 5c678695162e..dae839279950 100644 --- a/Documentation/devicetree/bindings/display/mediatek/mediatek,merge.yaml +++ b/Documentation/devicetree/bindings/display/mediatek/mediatek,merge.yaml @@ -24,6 +24,7 @@ properties: - enum: - mediatek,mt8173-disp-merge - mediatek,mt8195-disp-merge + - mediatek,mt8195-mdp3-merge - items: - const: mediatek,mt6795-disp-merge - const: mediatek,mt8173-disp-merge diff --git a/Documentation/devicetree/bindings/display/mediatek/mediatek,ovl.yaml b/Documentation/devicetree/bindings/display/mediatek/mediatek,ovl.yaml index 3e1069b00b56..c471a181d125 100644 --- a/Documentation/devicetree/bindings/display/mediatek/mediatek,ovl.yaml +++ b/Documentation/devicetree/bindings/display/mediatek/mediatek,ovl.yaml @@ -26,6 +26,7 @@ properties: - mediatek,mt8173-disp-ovl - mediatek,mt8183-disp-ovl - mediatek,mt8192-disp-ovl + - mediatek,mt8195-mdp3-ovl - items: - enum: - mediatek,mt7623-disp-ovl diff --git a/Documentation/devicetree/bindings/display/mediatek/mediatek,padding.yaml b/Documentation/devicetree/bindings/display/mediatek/mediatek,padding.yaml index 6bad7dc2d69f..be07bbdc54e3 100644 --- a/Documentation/devicetree/bindings/display/mediatek/mediatek,padding.yaml +++ b/Documentation/devicetree/bindings/display/mediatek/mediatek,padding.yaml @@ -20,7 +20,9 @@ description: properties: compatible: - const: mediatek,mt8188-disp-padding + enum: + - mediatek,mt8188-disp-padding + - mediatek,mt8195-mdp3-padding reg: maxItems: 1 diff --git a/Documentation/devicetree/bindings/display/mediatek/mediatek,split.yaml b/Documentation/devicetree/bindings/display/mediatek/mediatek,split.yaml index a8a5c9608598..e4affc854f3d 100644 --- a/Documentation/devicetree/bindings/display/mediatek/mediatek,split.yaml +++ b/Documentation/devicetree/bindings/display/mediatek/mediatek,split.yaml @@ -23,6 +23,7 @@ properties: oneOf: - enum: - mediatek,mt8173-disp-split + - mediatek,mt8195-mdp3-split - items: - const: mediatek,mt6795-disp-split - const: mediatek,mt8173-disp-split @@ -38,6 +39,21 @@ properties: the power controller specified by phandle. See Documentation/devicetree/bindings/power/power-domain.yaml for details. + mediatek,gce-client-reg: + description: + The register of display function block to be set by gce. There are 4 arguments, + such as gce node, subsys id, offset and register size. The subsys id that is + mapping to the register of display function blocks is defined in the gce header + include/dt-bindings/gce/<chip>-gce.h of each chips. + $ref: /schemas/types.yaml#/definitions/phandle-array + items: + items: + - description: phandle of GCE + - description: GCE subsys id + - description: register offset + - description: register size + maxItems: 1 + clocks: items: - description: SPLIT Clock @@ -48,6 +64,17 @@ required: - power-domains - clocks +allOf: + - if: + properties: + compatible: + contains: + const: mediatek,mt8195-mdp3-split + + then: + required: + - mediatek,gce-client-reg + additionalProperties: false examples: diff --git a/Documentation/devicetree/bindings/display/panel/panel-simple-dsi.yaml b/Documentation/devicetree/bindings/display/panel/panel-simple-dsi.yaml index 73674baea75d..f9160d7bac3c 100644 --- a/Documentation/devicetree/bindings/display/panel/panel-simple-dsi.yaml +++ b/Documentation/devicetree/bindings/display/panel/panel-simple-dsi.yaml @@ -42,6 +42,8 @@ properties: - lg,acx467akm-7 # LG Corporation 7" WXGA TFT LCD panel - lg,ld070wx3-sl01 + # LG Corporation 5" HD TFT LCD panel + - lg,lh500wx1-sd03 # One Stop Displays OSD101T2587-53TS 10.1" 1920x1200 panel - osddisplays,osd101t2587-53ts # Panasonic 10" WUXGA TFT LCD panel diff --git a/Documentation/devicetree/bindings/display/panel/panel-simple.yaml b/Documentation/devicetree/bindings/display/panel/panel-simple.yaml index 2021aa82871a..634a10c6f2dd 100644 --- a/Documentation/devicetree/bindings/display/panel/panel-simple.yaml +++ b/Documentation/devicetree/bindings/display/panel/panel-simple.yaml @@ -212,8 +212,6 @@ properties: - lemaker,bl035-rgb-002 # LG 7" (800x480 pixels) TFT LCD panel - lg,lb070wv8 - # LG Corporation 5" HD TFT LCD panel - - lg,lh500wx1-sd03 # LG LP079QX1-SP0V 7.9" (1536x2048 pixels) TFT LCD panel - lg,lp079qx1-sp0v # LG 9.7" (2048x1536 pixels) TFT LCD panel diff --git a/Documentation/devicetree/bindings/firmware/qcom,scm.yaml b/Documentation/devicetree/bindings/firmware/qcom,scm.yaml index 0613a37a851a..47d3d2d52acd 100644 --- a/Documentation/devicetree/bindings/firmware/qcom,scm.yaml +++ b/Documentation/devicetree/bindings/firmware/qcom,scm.yaml @@ -63,7 +63,9 @@ properties: - qcom,scm-sm8350 - qcom,scm-sm8450 - qcom,scm-sm8550 + - qcom,scm-sm8650 - qcom,scm-qcs404 + - qcom,scm-x1e80100 - const: qcom,scm clocks: @@ -178,21 +180,6 @@ allOf: minItems: 3 maxItems: 3 - # Interconnects - - if: - not: - properties: - compatible: - contains: - enum: - - qcom,scm-qdu1000 - - qcom,scm-sc8280xp - - qcom,scm-sm8450 - - qcom,scm-sm8550 - then: - properties: - interconnects: false - # Interrupts - if: not: @@ -202,6 +189,7 @@ allOf: enum: - qcom,scm-sm8450 - qcom,scm-sm8550 + - qcom,scm-sm8650 then: properties: interrupts: false diff --git a/Documentation/devicetree/bindings/gpu/arm,mali-midgard.yaml b/Documentation/devicetree/bindings/gpu/arm,mali-midgard.yaml index ca02baba5526..0801da33a385 100644 --- a/Documentation/devicetree/bindings/gpu/arm,mali-midgard.yaml +++ b/Documentation/devicetree/bindings/gpu/arm,mali-midgard.yaml @@ -42,6 +42,11 @@ properties: - const: arm,mali-t760 - items: - enum: + - samsung,exynos7-mali + - const: samsung,exynos5433-mali + - const: arm,mali-t760 + - items: + - enum: - rockchip,rk3399-mali - const: arm,mali-t860 diff --git a/Documentation/devicetree/bindings/hwinfo/samsung,exynos-chipid.yaml b/Documentation/devicetree/bindings/hwinfo/samsung,exynos-chipid.yaml index 95cbdcb56efe..780ccb5ee9b4 100644 --- a/Documentation/devicetree/bindings/hwinfo/samsung,exynos-chipid.yaml +++ b/Documentation/devicetree/bindings/hwinfo/samsung,exynos-chipid.yaml @@ -11,9 +11,21 @@ maintainers: properties: compatible: - enum: - - samsung,exynos4210-chipid - - samsung,exynos850-chipid + oneOf: + - enum: + - samsung,exynos4210-chipid + - samsung,exynos850-chipid + - items: + - enum: + - samsung,exynos5433-chipid + - samsung,exynos7-chipid + - const: samsung,exynos4210-chipid + - items: + - enum: + - samsung,exynos7885-chipid + - samsung,exynosautov9-chipid + - samsung,exynosautov920-chipid + - const: samsung,exynos850-chipid reg: maxItems: 1 diff --git a/Documentation/devicetree/bindings/i2c/i2c-exynos5.yaml b/Documentation/devicetree/bindings/i2c/i2c-exynos5.yaml index 3e52a0db6c41..df9c57bca2a8 100644 --- a/Documentation/devicetree/bindings/i2c/i2c-exynos5.yaml +++ b/Documentation/devicetree/bindings/i2c/i2c-exynos5.yaml @@ -25,7 +25,16 @@ properties: - samsung,exynos5250-hsi2c # Exynos5250 and Exynos5420 - samsung,exynos5260-hsi2c # Exynos5260 - samsung,exynos7-hsi2c # Exynos7 - - samsung,exynosautov9-hsi2c # ExynosAutoV9 and Exynos850 + - samsung,exynosautov9-hsi2c + - items: + - enum: + - samsung,exynos5433-hsi2c + - tesla,fsd-hsi2c + - const: samsung,exynos7-hsi2c + - items: + - enum: + - samsung,exynos850-hsi2c + - const: samsung,exynosautov9-hsi2c - const: samsung,exynos5-hsi2c # Exynos5250 and Exynos5420 deprecated: true diff --git a/Documentation/devicetree/bindings/i2c/samsung,s3c2410-i2c.yaml b/Documentation/devicetree/bindings/i2c/samsung,s3c2410-i2c.yaml index b204e35e4f8d..1303502cf265 100644 --- a/Documentation/devicetree/bindings/i2c/samsung,s3c2410-i2c.yaml +++ b/Documentation/devicetree/bindings/i2c/samsung,s3c2410-i2c.yaml @@ -11,14 +11,20 @@ maintainers: properties: compatible: - enum: - - samsung,s3c2410-i2c - - samsung,s3c2440-i2c - # For s3c2440-like I2C used inside HDMIPHY block found on several SoCs: - - samsung,s3c2440-hdmiphy-i2c - # For s3c2440-like I2C used as a host to SATA PHY controller on an - # internal bus: - - samsung,exynos5-sata-phy-i2c + oneOf: + - enum: + - samsung,s3c2410-i2c + - samsung,s3c2440-i2c + # For s3c2440-like I2C used inside HDMIPHY block found on several SoCs: + - samsung,s3c2440-hdmiphy-i2c + # For s3c2440-like I2C used as a host to SATA PHY controller on an + # internal bus: + - samsung,exynos5-sata-phy-i2c + - items: + - enum: + - samsung,exynos7885-i2c + - samsung,exynos850-i2c + - const: samsung,s3c2440-i2c '#address-cells': const: 1 diff --git a/Documentation/devicetree/bindings/iio/adc/samsung,exynos-adc.yaml b/Documentation/devicetree/bindings/iio/adc/samsung,exynos-adc.yaml index 582d0a03b814..4e40f6bed5db 100644 --- a/Documentation/devicetree/bindings/iio/adc/samsung,exynos-adc.yaml +++ b/Documentation/devicetree/bindings/iio/adc/samsung,exynos-adc.yaml @@ -11,18 +11,23 @@ maintainers: properties: compatible: - enum: - - samsung,exynos-adc-v1 # Exynos5250 - - samsung,exynos-adc-v2 - - samsung,exynos3250-adc - - samsung,exynos4212-adc # Exynos4212 and Exynos4412 - - samsung,exynos7-adc - - samsung,s3c2410-adc - - samsung,s3c2416-adc - - samsung,s3c2440-adc - - samsung,s3c2443-adc - - samsung,s3c6410-adc - - samsung,s5pv210-adc + oneOf: + - enum: + - samsung,exynos-adc-v1 # Exynos5250 + - samsung,exynos-adc-v2 + - samsung,exynos3250-adc + - samsung,exynos4212-adc # Exynos4212 and Exynos4412 + - samsung,exynos7-adc + - samsung,s3c2410-adc + - samsung,s3c2416-adc + - samsung,s3c2440-adc + - samsung,s3c2443-adc + - samsung,s3c6410-adc + - samsung,s5pv210-adc + - items: + - enum: + - samsung,exynos5433-adc + - const: samsung,exynos7-adc reg: maxItems: 1 diff --git a/Documentation/devicetree/bindings/interconnect/qcom,sm6115.yaml b/Documentation/devicetree/bindings/interconnect/qcom,sm6115.yaml new file mode 100644 index 000000000000..14b1a0b08e73 --- /dev/null +++ b/Documentation/devicetree/bindings/interconnect/qcom,sm6115.yaml @@ -0,0 +1,152 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/interconnect/qcom,sm6115.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Qualcomm SM6115 Network-On-Chip interconnect + +maintainers: + - Konrad Dybcio <konradybcio@kernel.org> + +description: + The Qualcomm SM6115 interconnect providers support adjusting the + bandwidth requirements between the various NoC fabrics. + +properties: + compatible: + enum: + - qcom,sm6115-bimc + - qcom,sm6115-cnoc + - qcom,sm6115-snoc + + reg: + maxItems: 1 + + clocks: + minItems: 1 + maxItems: 4 + + clock-names: + minItems: 1 + maxItems: 4 + +# Child node's properties +patternProperties: + '^interconnect-[a-z0-9]+$': + type: object + description: + The interconnect providers do not have a separate QoS register space, + but share parent's space. + + $ref: qcom,rpm-common.yaml# + + properties: + compatible: + enum: + - qcom,sm6115-clk-virt + - qcom,sm6115-mmrt-virt + - qcom,sm6115-mmnrt-virt + + required: + - compatible + + unevaluatedProperties: false + +required: + - compatible + - reg + +allOf: + - $ref: qcom,rpm-common.yaml# + - if: + properties: + compatible: + const: qcom,sm6115-cnoc + + then: + properties: + clocks: + items: + - description: USB-NoC AXI clock + + clock-names: + items: + - const: usb_axi + + - if: + properties: + compatible: + const: qcom,sm6115-snoc + + then: + properties: + clocks: + items: + - description: CPU-NoC AXI clock. + - description: UFS-NoC AXI clock. + - description: USB-NoC AXI clock. + - description: IPA clock. + + clock-names: + items: + - const: cpu_axi + - const: ufs_axi + - const: usb_axi + - const: ipa + + - if: + properties: + compatible: + enum: + - qcom,sm6115-bimc + - qcom,sm6115-clk-virt + - qcom,sm6115-mmrt-virt + - qcom,sm6115-mmnrt-virt + + then: + properties: + clocks: false + clock-names: false + +unevaluatedProperties: false + +examples: + - | + #include <dt-bindings/clock/qcom,gcc-sm6115.h> + #include <dt-bindings/clock/qcom,rpmcc.h> + + snoc: interconnect@1880000 { + compatible = "qcom,sm6115-snoc"; + reg = <0x01880000 0x60200>; + clocks = <&gcc GCC_SYS_NOC_CPUSS_AHB_CLK>, + <&gcc GCC_SYS_NOC_UFS_PHY_AXI_CLK>, + <&gcc GCC_SYS_NOC_USB3_PRIM_AXI_CLK>, + <&rpmcc RPM_SMD_IPA_CLK>; + clock-names = "cpu_axi", + "ufs_axi", + "usb_axi", + "ipa"; + #interconnect-cells = <1>; + + qup_virt: interconnect-clk { + compatible = "qcom,sm6115-clk-virt"; + #interconnect-cells = <1>; + }; + + mmnrt_virt: interconnect-mmnrt { + compatible = "qcom,sm6115-mmnrt-virt"; + #interconnect-cells = <1>; + }; + + mmrt_virt: interconnect-mmrt { + compatible = "qcom,sm6115-mmrt-virt"; + #interconnect-cells = <1>; + }; + }; + + cnoc: interconnect@1900000 { + compatible = "qcom,sm6115-cnoc"; + reg = <0x01900000 0x8200>; + #interconnect-cells = <1>; + }; diff --git a/Documentation/devicetree/bindings/interconnect/qcom,sm8650-rpmh.yaml b/Documentation/devicetree/bindings/interconnect/qcom,sm8650-rpmh.yaml new file mode 100644 index 000000000000..f9322de7cd61 --- /dev/null +++ b/Documentation/devicetree/bindings/interconnect/qcom,sm8650-rpmh.yaml @@ -0,0 +1,136 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/interconnect/qcom,sm8650-rpmh.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Qualcomm RPMh Network-On-Chip Interconnect on SM8650 + +maintainers: + - Abel Vesa <abel.vesa@linaro.org> + - Neil Armstrong <neil.armstrong@linaro.org> + +description: | + RPMh interconnect providers support system bandwidth requirements through + RPMh hardware accelerators known as Bus Clock Manager (BCM). The provider is + able to communicate with the BCM through the Resource State Coordinator (RSC) + associated with each execution environment. Provider nodes must point to at + least one RPMh device child node pertaining to their RSC and each provider + can map to multiple RPMh resources. + + See also:: include/dt-bindings/interconnect/qcom,sm8650-rpmh.h + +properties: + compatible: + enum: + - qcom,sm8650-aggre1-noc + - qcom,sm8650-aggre2-noc + - qcom,sm8650-clk-virt + - qcom,sm8650-cnoc-main + - qcom,sm8650-config-noc + - qcom,sm8650-gem-noc + - qcom,sm8650-lpass-ag-noc + - qcom,sm8650-lpass-lpiaon-noc + - qcom,sm8650-lpass-lpicx-noc + - qcom,sm8650-mc-virt + - qcom,sm8650-mmss-noc + - qcom,sm8650-nsp-noc + - qcom,sm8650-pcie-anoc + - qcom,sm8650-system-noc + + reg: + maxItems: 1 + + clocks: + minItems: 1 + maxItems: 2 + +required: + - compatible + +allOf: + - $ref: qcom,rpmh-common.yaml# + - if: + properties: + compatible: + contains: + enum: + - qcom,sm8650-clk-virt + - qcom,sm8650-mc-virt + then: + properties: + reg: false + else: + required: + - reg + + - if: + properties: + compatible: + contains: + enum: + - qcom,sm8650-pcie-anoc + then: + properties: + clocks: + items: + - description: aggre-NOC PCIe AXI clock + - description: cfg-NOC PCIe a-NOC AHB clock + + - if: + properties: + compatible: + contains: + enum: + - qcom,sm8650-aggre1-noc + then: + properties: + clocks: + items: + - description: aggre UFS PHY AXI clock + - description: aggre USB3 PRIM AXI clock + + - if: + properties: + compatible: + contains: + enum: + - qcom,sm8650-aggre2-noc + then: + properties: + clocks: + items: + - description: RPMH CC IPA clock + + - if: + properties: + compatible: + contains: + enum: + - qcom,sm8650-aggre1-noc + - qcom,sm8650-aggre2-noc + - qcom,sm8650-pcie-anoc + then: + required: + - clocks + else: + properties: + clocks: false + +unevaluatedProperties: false + +examples: + - | + clk_virt: interconnect-0 { + compatible = "qcom,sm8650-clk-virt"; + #interconnect-cells = <2>; + qcom,bcm-voters = <&apps_bcm_voter>; + }; + + aggre1_noc: interconnect@16e0000 { + compatible = "qcom,sm8650-aggre1-noc"; + reg = <0x016e0000 0x14400>; + #interconnect-cells = <2>; + clocks = <&gcc_phy_axi_clk>, <&gcc_prim_axi_clk>; + qcom,bcm-voters = <&apps_bcm_voter>; + }; diff --git a/Documentation/devicetree/bindings/interconnect/qcom,x1e80100-rpmh.yaml b/Documentation/devicetree/bindings/interconnect/qcom,x1e80100-rpmh.yaml new file mode 100644 index 000000000000..08b0210e0e59 --- /dev/null +++ b/Documentation/devicetree/bindings/interconnect/qcom,x1e80100-rpmh.yaml @@ -0,0 +1,83 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/interconnect/qcom,x1e80100-rpmh.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Qualcomm RPMh Network-On-Chip Interconnect on X1E80100 + +maintainers: + - Rajendra Nayak <quic_rjendra@quicinc.com> + - Abel Vesa <abel.vesa@linaro.org> + +description: | + RPMh interconnect providers support system bandwidth requirements through + RPMh hardware accelerators known as Bus Clock Manager (BCM). The provider is + able to communicate with the BCM through the Resource State Coordinator (RSC) + associated with each execution environment. Provider nodes must point to at + least one RPMh device child node pertaining to their RSC and each provider + can map to multiple RPMh resources. + + See also:: include/dt-bindings/interconnect/qcom,x1e80100-rpmh.h + +properties: + compatible: + enum: + - qcom,x1e80100-aggre1-noc + - qcom,x1e80100-aggre2-noc + - qcom,x1e80100-clk-virt + - qcom,x1e80100-cnoc-cfg + - qcom,x1e80100-cnoc-main + - qcom,x1e80100-gem-noc + - qcom,x1e80100-lpass-ag-noc + - qcom,x1e80100-lpass-lpiaon-noc + - qcom,x1e80100-lpass-lpicx-noc + - qcom,x1e80100-mc-virt + - qcom,x1e80100-mmss-noc + - qcom,x1e80100-nsp-noc + - qcom,x1e80100-pcie-center-anoc + - qcom,x1e80100-pcie-north-anoc + - qcom,x1e80100-pcie-south-anoc + - qcom,x1e80100-system-noc + - qcom,x1e80100-usb-center-anoc + - qcom,x1e80100-usb-north-anoc + - qcom,x1e80100-usb-south-anoc + + reg: + maxItems: 1 + +required: + - compatible + +allOf: + - $ref: qcom,rpmh-common.yaml# + - if: + properties: + compatible: + contains: + enum: + - qcom,x1e80100-clk-virt + - qcom,x1e80100-mc-virt + then: + properties: + reg: false + else: + required: + - reg + +unevaluatedProperties: false + +examples: + - | + clk_virt: interconnect-0 { + compatible = "qcom,x1e80100-clk-virt"; + #interconnect-cells = <2>; + qcom,bcm-voters = <&apps_bcm_voter>; + }; + + aggre1_noc: interconnect@16e0000 { + compatible = "qcom,x1e80100-aggre1-noc"; + reg = <0x016e0000 0x14400>; + #interconnect-cells = <2>; + qcom,bcm-voters = <&apps_bcm_voter>; + }; diff --git a/Documentation/devicetree/bindings/interrupt-controller/qcom,mpm.yaml b/Documentation/devicetree/bindings/interrupt-controller/qcom,mpm.yaml index 6a206111d4e0..ebb40c48950a 100644 --- a/Documentation/devicetree/bindings/interrupt-controller/qcom,mpm.yaml +++ b/Documentation/devicetree/bindings/interrupt-controller/qcom,mpm.yaml @@ -29,6 +29,12 @@ properties: maxItems: 1 description: Specifies the base address and size of vMPM registers in RPM MSG RAM. + deprecated: true + + qcom,rpm-msg-ram: + $ref: /schemas/types.yaml#/definitions/phandle + description: + Phandle to the APSS MPM slice of the RPM Message RAM interrupts: maxItems: 1 @@ -67,34 +73,46 @@ properties: required: - compatible - - reg - interrupts - mboxes - interrupt-controller - '#interrupt-cells' - qcom,mpm-pin-count - qcom,mpm-pin-map + - qcom,rpm-msg-ram additionalProperties: false examples: - | #include <dt-bindings/interrupt-controller/arm-gic.h> - mpm: interrupt-controller@45f01b8 { - compatible = "qcom,mpm"; - interrupts = <GIC_SPI 197 IRQ_TYPE_EDGE_RISING>; - reg = <0x45f01b8 0x1000>; - mboxes = <&apcs_glb 1>; - interrupt-controller; - #interrupt-cells = <2>; - interrupt-parent = <&intc>; - qcom,mpm-pin-count = <96>; - qcom,mpm-pin-map = <2 275>, - <5 296>, - <12 422>, - <24 79>, - <86 183>, - <90 260>, - <91 260>; - #power-domain-cells = <0>; + + remoteproc-rpm { + compatible = "qcom,msm8998-rpm-proc", "qcom,rpm-proc"; + + glink-edge { + compatible = "qcom,glink-rpm"; + + interrupts = <GIC_SPI 168 IRQ_TYPE_EDGE_RISING>; + qcom,rpm-msg-ram = <&rpm_msg_ram>; + mboxes = <&apcs_glb 0>; + }; + + mpm: interrupt-controller { + compatible = "qcom,mpm"; + qcom,rpm-msg-ram = <&apss_mpm>; + interrupts = <GIC_SPI 197 IRQ_TYPE_EDGE_RISING>; + mboxes = <&apcs_glb 1>; + interrupt-controller; + #interrupt-cells = <2>; + interrupt-parent = <&intc>; + qcom,mpm-pin-count = <96>; + qcom,mpm-pin-map = <2 275>, + <5 296>, + <12 422>, + <24 79>, + <86 183>, + <91 260>; + #power-domain-cells = <0>; + }; }; diff --git a/Documentation/devicetree/bindings/interrupt-controller/renesas,rzg2l-irqc.yaml b/Documentation/devicetree/bindings/interrupt-controller/renesas,rzg2l-irqc.yaml index 2ef3081eaaf3..d3b5aec0a3f7 100644 --- a/Documentation/devicetree/bindings/interrupt-controller/renesas,rzg2l-irqc.yaml +++ b/Documentation/devicetree/bindings/interrupt-controller/renesas,rzg2l-irqc.yaml @@ -26,6 +26,7 @@ properties: - renesas,r9a07g043u-irqc # RZ/G2UL - renesas,r9a07g044-irqc # RZ/G2{L,LC} - renesas,r9a07g054-irqc # RZ/V2L + - renesas,r9a08g045-irqc # RZ/G3S - const: renesas,rzg2l-irqc '#interrupt-cells': @@ -167,7 +168,9 @@ allOf: properties: compatible: contains: - const: renesas,r9a07g043u-irqc + enum: + - renesas,r9a07g043u-irqc + - renesas,r9a08g045-irqc then: properties: interrupts: diff --git a/Documentation/devicetree/bindings/interrupt-controller/sifive,plic-1.0.0.yaml b/Documentation/devicetree/bindings/interrupt-controller/sifive,plic-1.0.0.yaml index 0c07e8dda445..709b2211276b 100644 --- a/Documentation/devicetree/bindings/interrupt-controller/sifive,plic-1.0.0.yaml +++ b/Documentation/devicetree/bindings/interrupt-controller/sifive,plic-1.0.0.yaml @@ -66,6 +66,7 @@ properties: - enum: - allwinner,sun20i-d1-plic - sophgo,cv1800b-plic + - sophgo,cv1812h-plic - sophgo,sg2042-plic - thead,th1520-plic - const: thead,c900-plic diff --git a/Documentation/devicetree/bindings/media/mediatek,mdp3-fg.yaml b/Documentation/devicetree/bindings/media/mediatek,mdp3-fg.yaml new file mode 100644 index 000000000000..03f31b009085 --- /dev/null +++ b/Documentation/devicetree/bindings/media/mediatek,mdp3-fg.yaml @@ -0,0 +1,61 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/media/mediatek,mdp3-fg.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: MediaTek Media Data Path 3 Film Grain + +maintainers: + - Matthias Brugger <matthias.bgg@gmail.com> + - Moudy Ho <moudy.ho@mediatek.com> + +description: + Film Grain (FG) is a Media Data Path 3 (MDP3) component used to add + the film grain according to the AOMedia Video 1 (AV1) standard. + +properties: + compatible: + enum: + - mediatek,mt8195-mdp3-fg + + reg: + maxItems: 1 + + mediatek,gce-client-reg: + description: + The register of display function block to be set by gce. There are 4 arguments, + such as gce node, subsys id, offset and register size. The subsys id that is + mapping to the register of display function blocks is defined in the gce header + include/dt-bindings/gce/<chip>-gce.h of each chips. + $ref: /schemas/types.yaml#/definitions/phandle-array + items: + items: + - description: phandle of GCE + - description: GCE subsys id + - description: register offset + - description: register size + maxItems: 1 + + clocks: + maxItems: 1 + +required: + - compatible + - reg + - mediatek,gce-client-reg + - clocks + +additionalProperties: false + +examples: + - | + #include <dt-bindings/clock/mt8195-clk.h> + #include <dt-bindings/gce/mt8195-gce.h> + + display@14002000 { + compatible = "mediatek,mt8195-mdp3-fg"; + reg = <0x14002000 0x1000>; + mediatek,gce-client-reg = <&gce1 SUBSYS_1400XXXX 0x2000 0x1000>; + clocks = <&vppsys0 CLK_VPP0_MDP_FG>; + }; diff --git a/Documentation/devicetree/bindings/media/mediatek,mdp3-hdr.yaml b/Documentation/devicetree/bindings/media/mediatek,mdp3-hdr.yaml new file mode 100644 index 000000000000..d4609bba6578 --- /dev/null +++ b/Documentation/devicetree/bindings/media/mediatek,mdp3-hdr.yaml @@ -0,0 +1,61 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/media/mediatek,mdp3-hdr.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: MediaTek Media Data Path 3 HDR + +maintainers: + - Matthias Brugger <matthias.bgg@gmail.com> + - Moudy Ho <moudy.ho@mediatek.com> + +description: + A Media Data Path 3 (MDP3) component used to perform conversion from + High Dynamic Range (HDR) to Standard Dynamic Range (SDR). + +properties: + compatible: + enum: + - mediatek,mt8195-mdp3-hdr + + reg: + maxItems: 1 + + mediatek,gce-client-reg: + description: + The register of display function block to be set by gce. There are 4 arguments, + such as gce node, subsys id, offset and register size. The subsys id that is + mapping to the register of display function blocks is defined in the gce header + include/dt-bindings/gce/<chip>-gce.h of each chips. + $ref: /schemas/types.yaml#/definitions/phandle-array + items: + items: + - description: phandle of GCE + - description: GCE subsys id + - description: register offset + - description: register size + maxItems: 1 + + clocks: + maxItems: 1 + +required: + - compatible + - reg + - mediatek,gce-client-reg + - clocks + +additionalProperties: false + +examples: + - | + #include <dt-bindings/clock/mt8195-clk.h> + #include <dt-bindings/gce/mt8195-gce.h> + + display@14004000 { + compatible = "mediatek,mt8195-mdp3-hdr"; + reg = <0x14004000 0x1000>; + mediatek,gce-client-reg = <&gce1 SUBSYS_1400XXXX 0x4000 0x1000>; + clocks = <&vppsys0 CLK_VPP0_MDP_HDR>; + }; diff --git a/Documentation/devicetree/bindings/media/mediatek,mdp3-rdma.yaml b/Documentation/devicetree/bindings/media/mediatek,mdp3-rdma.yaml index 7032c7e15039..59db8306485b 100644 --- a/Documentation/devicetree/bindings/media/mediatek,mdp3-rdma.yaml +++ b/Documentation/devicetree/bindings/media/mediatek,mdp3-rdma.yaml @@ -20,8 +20,14 @@ description: | properties: compatible: - items: - - const: mediatek,mt8183-mdp3-rdma + oneOf: + - enum: + - mediatek,mt8183-mdp3-rdma + - mediatek,mt8195-mdp3-rdma + - mediatek,mt8195-vdo1-rdma + - items: + - const: mediatek,mt8188-vdo1-rdma + - const: mediatek,mt8195-vdo1-rdma reg: maxItems: 1 @@ -45,6 +51,14 @@ properties: include/dt-bindings/gce/<chip>-gce.h of each chips. $ref: /schemas/types.yaml#/definitions/uint32-array + mediatek,scp: + $ref: /schemas/types.yaml#/definitions/phandle + description: + Phandle to the System Control Processor (SCP) used for initializing + and stopping the MDP3, for sending frame data locations to the MDP3's + VPU and to install Inter-Processor Interrupt handlers to control + processing states. + power-domains: maxItems: 1 @@ -52,6 +66,7 @@ properties: items: - description: RDMA clock - description: RSZ clock + minItems: 1 iommus: maxItems: 1 @@ -60,16 +75,72 @@ properties: items: - description: used for 1st data pipe from RDMA - description: used for 2nd data pipe from RDMA + - description: used for 3rd data pipe from RDMA + - description: used for 4th data pipe from RDMA + - description: used for the data pipe from SPLIT + minItems: 1 + + interrupts: + maxItems: 1 + + '#dma-cells': + const: 1 required: - compatible - reg - mediatek,gce-client-reg - - mediatek,gce-events - power-domains - clocks - iommus - - mboxes + - '#dma-cells' + +allOf: + - if: + properties: + compatible: + contains: + const: mediatek,mt8183-mdp3-rdma + + then: + properties: + clocks: + minItems: 2 + + mboxes: + minItems: 2 + + required: + - mboxes + - mediatek,gce-events + + - if: + properties: + compatible: + contains: + const: mediatek,mt8195-mdp3-rdma + + then: + properties: + clocks: + maxItems: 1 + + mboxes: + minItems: 5 + + required: + - mediatek,gce-events + + - if: + properties: + compatible: + contains: + const: mediatek,mt8195-vdo1-rdma + + then: + properties: + clocks: + maxItems: 1 additionalProperties: false @@ -80,16 +151,17 @@ examples: #include <dt-bindings/power/mt8183-power.h> #include <dt-bindings/memory/mt8183-larb-port.h> - mdp3_rdma0: mdp3-rdma0@14001000 { - compatible = "mediatek,mt8183-mdp3-rdma"; - reg = <0x14001000 0x1000>; - mediatek,gce-client-reg = <&gce SUBSYS_1400XXXX 0x1000 0x1000>; - mediatek,gce-events = <CMDQ_EVENT_MDP_RDMA0_SOF>, - <CMDQ_EVENT_MDP_RDMA0_EOF>; - power-domains = <&spm MT8183_POWER_DOMAIN_DISP>; - clocks = <&mmsys CLK_MM_MDP_RDMA0>, - <&mmsys CLK_MM_MDP_RSZ1>; - iommus = <&iommu>; - mboxes = <&gce 20 CMDQ_THR_PRIO_LOWEST>, - <&gce 21 CMDQ_THR_PRIO_LOWEST>; + dma-controller@14001000 { + compatible = "mediatek,mt8183-mdp3-rdma"; + reg = <0x14001000 0x1000>; + mediatek,gce-client-reg = <&gce SUBSYS_1400XXXX 0x1000 0x1000>; + mediatek,gce-events = <CMDQ_EVENT_MDP_RDMA0_SOF>, + <CMDQ_EVENT_MDP_RDMA0_EOF>; + power-domains = <&spm MT8183_POWER_DOMAIN_DISP>; + clocks = <&mmsys CLK_MM_MDP_RDMA0>, + <&mmsys CLK_MM_MDP_RSZ1>; + iommus = <&iommu>; + mboxes = <&gce 20 CMDQ_THR_PRIO_LOWEST>, + <&gce 21 CMDQ_THR_PRIO_LOWEST>; + #dma-cells = <1>; }; diff --git a/Documentation/devicetree/bindings/media/mediatek,mdp3-rsz.yaml b/Documentation/devicetree/bindings/media/mediatek,mdp3-rsz.yaml index 78f9de6192ef..f5676bec4326 100644 --- a/Documentation/devicetree/bindings/media/mediatek,mdp3-rsz.yaml +++ b/Documentation/devicetree/bindings/media/mediatek,mdp3-rsz.yaml @@ -15,9 +15,13 @@ description: | properties: compatible: - items: + oneOf: - enum: - mediatek,mt8183-mdp3-rsz + - items: + - enum: + - mediatek,mt8195-mdp3-rsz + - const: mediatek,mt8183-mdp3-rsz reg: maxItems: 1 diff --git a/Documentation/devicetree/bindings/media/mediatek,mdp3-stitch.yaml b/Documentation/devicetree/bindings/media/mediatek,mdp3-stitch.yaml new file mode 100644 index 000000000000..d815bea29154 --- /dev/null +++ b/Documentation/devicetree/bindings/media/mediatek,mdp3-stitch.yaml @@ -0,0 +1,61 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/media/mediatek,mdp3-stitch.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: MediaTek Media Data Path 3 STITCH + +maintainers: + - Matthias Brugger <matthias.bgg@gmail.com> + - Moudy Ho <moudy.ho@mediatek.com> + +description: + One of Media Data Path 3 (MDP3) components used to combine multiple video frame + with overlapping fields of view to produce a segmented panorame. + +properties: + compatible: + enum: + - mediatek,mt8195-mdp3-stitch + + reg: + maxItems: 1 + + mediatek,gce-client-reg: + description: + The register of display function block to be set by gce. There are 4 arguments, + such as gce node, subsys id, offset and register size. The subsys id that is + mapping to the register of display function blocks is defined in the gce header + include/dt-bindings/gce/<chip>-gce.h of each chips. + $ref: /schemas/types.yaml#/definitions/phandle-array + items: + items: + - description: phandle of GCE + - description: GCE subsys id + - description: register offset + - description: register size + maxItems: 1 + + clocks: + maxItems: 1 + +required: + - compatible + - reg + - mediatek,gce-client-reg + - clocks + +additionalProperties: false + +examples: + - | + #include <dt-bindings/clock/mt8195-clk.h> + #include <dt-bindings/gce/mt8195-gce.h> + + display@14003000 { + compatible = "mediatek,mt8195-mdp3-stitch"; + reg = <0x14003000 0x1000>; + mediatek,gce-client-reg = <&gce1 SUBSYS_1400XXXX 0x3000 0x1000>; + clocks = <&vppsys0 CLK_VPP0_STITCH>; + }; diff --git a/Documentation/devicetree/bindings/media/mediatek,mdp3-tcc.yaml b/Documentation/devicetree/bindings/media/mediatek,mdp3-tcc.yaml new file mode 100644 index 000000000000..14ea556d4f82 --- /dev/null +++ b/Documentation/devicetree/bindings/media/mediatek,mdp3-tcc.yaml @@ -0,0 +1,62 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/media/mediatek,mdp3-tcc.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: MediaTek Media Data Path 3 Tone Curve Conversion + +maintainers: + - Matthias Brugger <matthias.bgg@gmail.com> + +description: + Tone Curve Conversion (TCC) is one of Media Profile Path 3 (MDP3) components. + It is used to handle the tone mapping of various gamma curves in order to + achieve HDR10 effects. This helps adapt the content to the color and + brightness range that standard display devices typically support. + +properties: + compatible: + enum: + - mediatek,mt8195-mdp3-tcc + + reg: + maxItems: 1 + + mediatek,gce-client-reg: + description: + The register of display function block to be set by gce. There are 4 arguments, + such as gce node, subsys id, offset and register size. The subsys id that is + mapping to the register of display function blocks is defined in the gce header + include/dt-bindings/gce/<chip>-gce.h of each chips. + $ref: /schemas/types.yaml#/definitions/phandle-array + items: + items: + - description: phandle of GCE + - description: GCE subsys id + - description: register offset + - description: register size + maxItems: 1 + + clocks: + maxItems: 1 + +required: + - compatible + - reg + - mediatek,gce-client-reg + - clocks + +additionalProperties: false + +examples: + - | + #include <dt-bindings/clock/mt8195-clk.h> + #include <dt-bindings/gce/mt8195-gce.h> + + display@1400b000 { + compatible = "mediatek,mt8195-mdp3-tcc"; + reg = <0x1400b000 0x1000>; + mediatek,gce-client-reg = <&gce1 SUBSYS_1400XXXX 0xb000 0x1000>; + clocks = <&vppsys0 CLK_VPP0_MDP_TCC>; + }; diff --git a/Documentation/devicetree/bindings/media/mediatek,mdp3-tdshp.yaml b/Documentation/devicetree/bindings/media/mediatek,mdp3-tdshp.yaml new file mode 100644 index 000000000000..8ab7f2d8e148 --- /dev/null +++ b/Documentation/devicetree/bindings/media/mediatek,mdp3-tdshp.yaml @@ -0,0 +1,61 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/media/mediatek,mdp3-tdshp.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: MediaTek Media Data Path 3 Two-Dimensional Sharpness + +maintainers: + - Matthias Brugger <matthias.bgg@gmail.com> + - Moudy Ho <moudy.ho@mediatek.com> + +description: + Two-Dimensional Sharpness (TDSHP) is a Media Profile Path 3 (MDP3) component + used to perform image edge sharpening and enhance vividness and contrast. + +properties: + compatible: + enum: + - mediatek,mt8195-mdp3-tdshp + + reg: + maxItems: 1 + + mediatek,gce-client-reg: + description: + The register of display function block to be set by gce. There are 4 arguments, + such as gce node, subsys id, offset and register size. The subsys id that is + mapping to the register of display function blocks is defined in the gce header + include/dt-bindings/gce/<chip>-gce.h of each chips. + $ref: /schemas/types.yaml#/definitions/phandle-array + items: + items: + - description: phandle of GCE + - description: GCE subsys id + - description: register offset + - description: register size + maxItems: 1 + + clocks: + maxItems: 1 + +required: + - compatible + - reg + - mediatek,gce-client-reg + - clocks + +additionalProperties: false + +examples: + - | + #include <dt-bindings/clock/mt8195-clk.h> + #include <dt-bindings/gce/mt8195-gce.h> + + display@14007000 { + compatible = "mediatek,mt8195-mdp3-tdshp"; + reg = <0x14007000 0x1000>; + mediatek,gce-client-reg = <&gce1 SUBSYS_1400XXXX 0x7000 0x1000>; + clocks = <&vppsys0 CLK_VPP0_MDP_TDSHP>; + }; diff --git a/Documentation/devicetree/bindings/media/mediatek,mdp3-wrot.yaml b/Documentation/devicetree/bindings/media/mediatek,mdp3-wrot.yaml index 0baa77198fa2..53a679338402 100644 --- a/Documentation/devicetree/bindings/media/mediatek,mdp3-wrot.yaml +++ b/Documentation/devicetree/bindings/media/mediatek,mdp3-wrot.yaml @@ -15,9 +15,13 @@ description: | properties: compatible: - items: + oneOf: - enum: - mediatek,mt8183-mdp3-wrot + - items: + - enum: + - mediatek,mt8195-mdp3-wrot + - const: mediatek,mt8183-mdp3-wrot reg: maxItems: 1 @@ -50,6 +54,9 @@ properties: iommus: maxItems: 1 + '#dma-cells': + const: 1 + required: - compatible - reg @@ -58,6 +65,7 @@ required: - power-domains - clocks - iommus + - '#dma-cells' additionalProperties: false @@ -68,13 +76,14 @@ examples: #include <dt-bindings/power/mt8183-power.h> #include <dt-bindings/memory/mt8183-larb-port.h> - mdp3_wrot0: mdp3-wrot0@14005000 { - compatible = "mediatek,mt8183-mdp3-wrot"; - reg = <0x14005000 0x1000>; - mediatek,gce-client-reg = <&gce SUBSYS_1400XXXX 0x5000 0x1000>; - mediatek,gce-events = <CMDQ_EVENT_MDP_WROT0_SOF>, - <CMDQ_EVENT_MDP_WROT0_EOF>; - power-domains = <&spm MT8183_POWER_DOMAIN_DISP>; - clocks = <&mmsys CLK_MM_MDP_WROT0>; - iommus = <&iommu>; + dma-controller@14005000 { + compatible = "mediatek,mt8183-mdp3-wrot"; + reg = <0x14005000 0x1000>; + mediatek,gce-client-reg = <&gce SUBSYS_1400XXXX 0x5000 0x1000>; + mediatek,gce-events = <CMDQ_EVENT_MDP_WROT0_SOF>, + <CMDQ_EVENT_MDP_WROT0_EOF>; + power-domains = <&spm MT8183_POWER_DOMAIN_DISP>; + clocks = <&mmsys CLK_MM_MDP_WROT0>; + iommus = <&iommu>; + #dma-cells = <1>; }; diff --git a/Documentation/devicetree/bindings/mfd/samsung,exynos5433-lpass.yaml b/Documentation/devicetree/bindings/mfd/samsung,exynos5433-lpass.yaml index b97b06848729..f154103f32cc 100644 --- a/Documentation/devicetree/bindings/mfd/samsung,exynos5433-lpass.yaml +++ b/Documentation/devicetree/bindings/mfd/samsung,exynos5433-lpass.yaml @@ -85,7 +85,7 @@ examples: }; i2s@11440000 { - compatible = "samsung,exynos7-i2s"; + compatible = "samsung,exynos5433-i2s", "samsung,exynos7-i2s"; reg = <0x11440000 0x100>; dmas = <&adma 0>, <&adma 2>; dma-names = "tx", "rx"; diff --git a/Documentation/devicetree/bindings/mmc/samsung,exynos-dw-mshc.yaml b/Documentation/devicetree/bindings/mmc/samsung,exynos-dw-mshc.yaml index 6ee78a38bd74..5fe65795f796 100644 --- a/Documentation/devicetree/bindings/mmc/samsung,exynos-dw-mshc.yaml +++ b/Documentation/devicetree/bindings/mmc/samsung,exynos-dw-mshc.yaml @@ -14,15 +14,22 @@ maintainers: properties: compatible: - enum: - - samsung,exynos4210-dw-mshc - - samsung,exynos4412-dw-mshc - - samsung,exynos5250-dw-mshc - - samsung,exynos5420-dw-mshc - - samsung,exynos5420-dw-mshc-smu - - samsung,exynos7-dw-mshc - - samsung,exynos7-dw-mshc-smu - - axis,artpec8-dw-mshc + oneOf: + - enum: + - axis,artpec8-dw-mshc + - samsung,exynos4210-dw-mshc + - samsung,exynos4412-dw-mshc + - samsung,exynos5250-dw-mshc + - samsung,exynos5420-dw-mshc + - samsung,exynos5420-dw-mshc-smu + - samsung,exynos7-dw-mshc + - samsung,exynos7-dw-mshc-smu + - items: + - enum: + - samsung,exynos5433-dw-mshc-smu + - samsung,exynos7885-dw-mshc-smu + - samsung,exynos850-dw-mshc-smu + - const: samsung,exynos7-dw-mshc-smu reg: maxItems: 1 diff --git a/Documentation/devicetree/bindings/mtd/partitions/u-boot.yaml b/Documentation/devicetree/bindings/mtd/partitions/u-boot.yaml index 3c56efe48efd..327fa872c001 100644 --- a/Documentation/devicetree/bindings/mtd/partitions/u-boot.yaml +++ b/Documentation/devicetree/bindings/mtd/partitions/u-boot.yaml @@ -7,7 +7,7 @@ $schema: http://devicetree.org/meta-schemas/core.yaml# title: U-Boot bootloader partition description: | - U-Boot is a bootlodaer commonly used in embedded devices. It's almost always + U-Boot is a bootloader commonly used in embedded devices. It's almost always located on some kind of flash device. Device configuration is stored as a set of environment variables that are diff --git a/Documentation/devicetree/bindings/net/dsa/dsa.yaml b/Documentation/devicetree/bindings/net/dsa/dsa.yaml index 6107189d276a..2abd036578d1 100644 --- a/Documentation/devicetree/bindings/net/dsa/dsa.yaml +++ b/Documentation/devicetree/bindings/net/dsa/dsa.yaml @@ -46,4 +46,10 @@ $defs: $ref: dsa-port.yaml# unevaluatedProperties: false +oneOf: + - required: + - ports + - required: + - ethernet-ports + ... diff --git a/Documentation/devicetree/bindings/net/dsa/marvell,mv88e6060.yaml b/Documentation/devicetree/bindings/net/dsa/marvell,mv88e6060.yaml new file mode 100644 index 000000000000..4f1adf00431a --- /dev/null +++ b/Documentation/devicetree/bindings/net/dsa/marvell,mv88e6060.yaml @@ -0,0 +1,88 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/net/dsa/marvell,mv88e6060.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Marvell MV88E6060 DSA switch + +maintainers: + - Andrew Lunn <andrew@lunn.ch> + +description: + The Marvell MV88E6060 switch has been produced and sold by Marvell + since at least 2008. The switch has one pin ADDR4 that controls the + MDIO address of the switch to be 0x10 or 0x00, and on the MDIO bus + connected to the switch, the PHYs inside the switch appear as + independent devices on address 0x00-0x04 or 0x10-0x14, so in difference + from many other DSA switches this switch does not have an internal + MDIO bus for the PHY devices. + +properties: + compatible: + const: marvell,mv88e6060 + description: + The MV88E6060 is the oldest Marvell DSA switch product, and + as such a bit limited in features compared to later hardware. + + reg: + maxItems: 1 + + reset-gpios: + description: + GPIO to be used to reset the whole device + maxItems: 1 + +allOf: + - $ref: dsa.yaml#/$defs/ethernet-ports + +required: + - compatible + - reg + +unevaluatedProperties: false + +examples: + - | + #include <dt-bindings/gpio/gpio.h> + #include <dt-bindings/interrupt-controller/irq.h> + mdio { + #address-cells = <1>; + #size-cells = <0>; + + ethernet-switch@16 { + compatible = "marvell,mv88e6060"; + reg = <16>; + + ethernet-ports { + #address-cells = <1>; + #size-cells = <0>; + + ethernet-port@0 { + reg = <0>; + label = "lan1"; + }; + ethernet-port@1 { + reg = <1>; + label = "lan2"; + }; + ethernet-port@2 { + reg = <2>; + label = "lan3"; + }; + ethernet-port@3 { + reg = <3>; + label = "lan4"; + }; + ethernet-port@5 { + reg = <5>; + phy-mode = "rev-mii"; + ethernet = <ðc>; + fixed-link { + speed = <100>; + full-duplex; + }; + }; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/net/dsa/marvell,mv88e6xxx.yaml b/Documentation/devicetree/bindings/net/dsa/marvell,mv88e6xxx.yaml new file mode 100644 index 000000000000..19f15bdd1c97 --- /dev/null +++ b/Documentation/devicetree/bindings/net/dsa/marvell,mv88e6xxx.yaml @@ -0,0 +1,337 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/net/dsa/marvell,mv88e6xxx.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Marvell MV88E6xxx DSA switch family + +maintainers: + - Andrew Lunn <andrew@lunn.ch> + +description: + The Marvell MV88E6xxx switch series has been produced and sold + by Marvell since at least 2008. The switch has a few compatibles which + just indicate the base address of the switch, then operating systems + can investigate switch ID registers to find out which actual version + of the switch it is dealing with. + +properties: + compatible: + oneOf: + - enum: + - marvell,mv88e6085 + - marvell,mv88e6190 + - marvell,mv88e6250 + description: | + marvell,mv88e6085: This switch uses base address 0x10. + This switch and its siblings will be autodetected from + ID registers found in the switch, so only "marvell,mv88e6085" should be + specified. This includes the following list of MV88Exxxx switches: + 6085, 6095, 6097, 6123, 6131, 6141, 6161, 6165, 6171, 6172, 6175, 6176, + 6185, 6240, 6320, 6321, 6341, 6350, 6351, 6352 + marvell,mv88e6190: This switch uses base address 0x00. + This switch and its siblings will be autodetected from + ID registers found in the switch, so only "marvell,mv88e6190" should be + specified. This includes the following list of MV88Exxxx switches: + 6190, 6190X, 6191, 6290, 6361, 6390, 6390X + marvell,mv88e6250: This switch uses base address 0x08 or 0x18. + This switch and its siblings will be autodetected from + ID registers found in the switch, so only "marvell,mv88e6250" should be + specified. This includes the following list of MV88Exxxx switches: + 6220, 6250 + - items: + - const: marvell,turris-mox-mv88e6085 + - const: marvell,mv88e6085 + - items: + - const: marvell,turris-mox-mv88e6190 + - const: marvell,mv88e6190 + + reg: + maxItems: 1 + + eeprom-length: + $ref: /schemas/types.yaml#/definitions/uint32 + description: Set to the length of an EEPROM connected to the switch. Must be + set if the switch can not detect the presence and/or size of a connected + EEPROM, otherwise optional. + + reset-gpios: + description: + GPIO to be used to reset the whole device + maxItems: 1 + + interrupts: + description: The switch provides an external interrupt line, but it is + not always used by target systems. + maxItems: 1 + + interrupt-controller: + description: The switch has an internal interrupt controller used by + the different sub-blocks. + + '#interrupt-cells': + description: The internal interrupt controller only supports triggering + on active high level interrupts so the second cell must alway be set to + IRQ_TYPE_LEVEL_HIGH. + const: 2 + + mdio: + $ref: /schemas/net/mdio.yaml# + unevaluatedProperties: false + description: Marvell MV88E6xxx switches have an varying combination of + internal and external MDIO buses, in some cases a combined bus that + can be used both internally and externally. This node is for the + primary bus, used internally and sometimes also externally. + + mdio-external: + $ref: /schemas/net/mdio.yaml# + unevaluatedProperties: false + description: Marvell MV88E6xxx switches that have a separate external + MDIO bus use this port to access external components on the MDIO bus. + + properties: + compatible: + const: marvell,mv88e6xxx-mdio-external + + required: + - compatible + +allOf: + - $ref: dsa.yaml#/$defs/ethernet-ports + +required: + - compatible + - reg + +unevaluatedProperties: false + +examples: + - | + #include <dt-bindings/gpio/gpio.h> + mdio { + #address-cells = <1>; + #size-cells = <0>; + + ethernet-switch@0 { + compatible = "marvell,mv88e6085"; + reg = <0>; + reset-gpios = <&gpio5 1 GPIO_ACTIVE_LOW>; + + mdio { + #address-cells = <1>; + #size-cells = <0>; + + sw_phy0: ethernet-phy@0 { + reg = <0x0>; + }; + + sw_phy1: ethernet-phy@1 { + reg = <0x1>; + }; + + sw_phy2: ethernet-phy@2 { + reg = <0x2>; + }; + + sw_phy3: ethernet-phy@3 { + reg = <0x3>; + }; + }; + + ethernet-ports { + #address-cells = <1>; + #size-cells = <0>; + + ethernet-port@0 { + reg = <0>; + label = "lan4"; + phy-handle = <&sw_phy0>; + phy-mode = "internal"; + }; + + ethernet-port@1 { + reg = <1>; + label = "lan3"; + phy-handle = <&sw_phy1>; + phy-mode = "internal"; + }; + + ethernet-port@2 { + reg = <2>; + label = "lan2"; + phy-handle = <&sw_phy2>; + phy-mode = "internal"; + }; + + ethernet-port@3 { + reg = <3>; + label = "lan1"; + phy-handle = <&sw_phy3>; + phy-mode = "internal"; + }; + + ethernet-port@5 { + reg = <5>; + ethernet = <&fec>; + phy-mode = "rgmii-id"; + + fixed-link { + speed = <1000>; + full-duplex; + }; + }; + }; + }; + }; + - | + #include <dt-bindings/interrupt-controller/irq.h> + mdio { + #address-cells = <1>; + #size-cells = <0>; + + ethernet-switch@0 { + compatible = "marvell,mv88e6190"; + #interrupt-cells = <2>; + interrupt-controller; + interrupt-parent = <&gpio1>; + interrupts = <7 IRQ_TYPE_LEVEL_LOW>; + pinctrl-0 = <&switch_interrupt_pins>; + pinctrl-names = "default"; + reg = <0>; + + mdio { + #address-cells = <1>; + #size-cells = <0>; + + switch0phy1: ethernet-phy@1 { + reg = <0x1>; + }; + + switch0phy2: ethernet-phy@2 { + reg = <0x2>; + }; + + switch0phy3: ethernet-phy@3 { + reg = <0x3>; + }; + + switch0phy4: ethernet-phy@4 { + reg = <0x4>; + }; + + switch0phy5: ethernet-phy@5 { + reg = <0x5>; + }; + + switch0phy6: ethernet-phy@6 { + reg = <0x6>; + }; + + switch0phy7: ethernet-phy@7 { + reg = <0x7>; + }; + + switch0phy8: ethernet-phy@8 { + reg = <0x8>; + }; + }; + + mdio-external { + compatible = "marvell,mv88e6xxx-mdio-external"; + #address-cells = <1>; + #size-cells = <0>; + + phy1: ethernet-phy@b { + reg = <0xb>; + compatible = "ethernet-phy-ieee802.3-c45"; + }; + + phy2: ethernet-phy@c { + reg = <0xc>; + compatible = "ethernet-phy-ieee802.3-c45"; + }; + }; + + ethernet-ports { + #address-cells = <1>; + #size-cells = <0>; + + ethernet-port@0 { + ethernet = <ð0>; + phy-mode = "rgmii"; + reg = <0>; + + fixed-link { + full-duplex; + pause; + speed = <1000>; + }; + }; + + ethernet-port@1 { + label = "lan1"; + phy-handle = <&switch0phy1>; + reg = <1>; + }; + + ethernet-port@2 { + label = "lan2"; + phy-handle = <&switch0phy2>; + reg = <2>; + }; + + ethernet-port@3 { + label = "lan3"; + phy-handle = <&switch0phy3>; + reg = <3>; + }; + + ethernet-port@4 { + label = "lan4"; + phy-handle = <&switch0phy4>; + reg = <4>; + }; + + ethernet-port@5 { + label = "lan5"; + phy-handle = <&switch0phy5>; + reg = <5>; + }; + + ethernet-port@6 { + label = "lan6"; + phy-handle = <&switch0phy6>; + reg = <6>; + }; + + ethernet-port@7 { + label = "lan7"; + phy-handle = <&switch0phy7>; + reg = <7>; + }; + + ethernet-port@8 { + label = "lan8"; + phy-handle = <&switch0phy8>; + reg = <8>; + }; + + ethernet-port@9 { + /* 88X3310P external phy */ + label = "lan9"; + phy-handle = <&phy1>; + phy-mode = "xaui"; + reg = <9>; + }; + + ethernet-port@a { + /* 88X3310P external phy */ + label = "lan10"; + phy-handle = <&phy2>; + phy-mode = "xaui"; + reg = <0xa>; + }; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/net/dsa/marvell.txt b/Documentation/devicetree/bindings/net/dsa/marvell.txt deleted file mode 100644 index 6ec0c181b6db..000000000000 --- a/Documentation/devicetree/bindings/net/dsa/marvell.txt +++ /dev/null @@ -1,109 +0,0 @@ -Marvell DSA Switch Device Tree Bindings ---------------------------------------- - -WARNING: This binding is currently unstable. Do not program it into a -FLASH never to be changed again. Once this binding is stable, this -warning will be removed. - -If you need a stable binding, use the old dsa.txt binding. - -Marvell Switches are MDIO devices. The following properties should be -placed as a child node of an mdio device. - -The properties described here are those specific to Marvell devices. -Additional required and optional properties can be found in dsa.txt. - -The compatibility string is used only to find an identification register, -which is at a different MDIO base address in different switch families. -- "marvell,mv88e6085" : Switch has base address 0x10. Use with models: - 6085, 6095, 6097, 6123, 6131, 6141, 6161, 6165, - 6171, 6172, 6175, 6176, 6185, 6240, 6320, 6321, - 6341, 6350, 6351, 6352 -- "marvell,mv88e6190" : Switch has base address 0x00. Use with models: - 6190, 6190X, 6191, 6290, 6361, 6390, 6390X -- "marvell,mv88e6250" : Switch has base address 0x08 or 0x18. Use with model: - 6220, 6250 - -Required properties: -- compatible : Should be one of "marvell,mv88e6085", - "marvell,mv88e6190" or "marvell,mv88e6250" as - indicated above -- reg : Address on the MII bus for the switch. - -Optional properties: - -- reset-gpios : Should be a gpio specifier for a reset line -- interrupts : Interrupt from the switch -- interrupt-controller : Indicates the switch is itself an interrupt - controller. This is used for the PHY interrupts. -#interrupt-cells = <2> : Controller uses two cells, number and flag -- eeprom-length : Set to the length of an EEPROM connected to the - switch. Must be set if the switch can not detect - the presence and/or size of a connected EEPROM, - otherwise optional. -- mdio : Container of PHY and devices on the switches MDIO - bus. -- mdio? : Container of PHYs and devices on the external MDIO - bus. The node must contains a compatible string of - "marvell,mv88e6xxx-mdio-external" - -Example: - - mdio { - #address-cells = <1>; - #size-cells = <0>; - interrupt-parent = <&gpio0>; - interrupts = <27 IRQ_TYPE_LEVEL_LOW>; - interrupt-controller; - #interrupt-cells = <2>; - - switch0: switch@0 { - compatible = "marvell,mv88e6085"; - reg = <0>; - reset-gpios = <&gpio5 1 GPIO_ACTIVE_LOW>; - - mdio { - #address-cells = <1>; - #size-cells = <0>; - switch1phy0: switch1phy0@0 { - reg = <0>; - interrupt-parent = <&switch0>; - interrupts = <0 IRQ_TYPE_LEVEL_HIGH>; - }; - }; - }; - }; - - mdio { - #address-cells = <1>; - #size-cells = <0>; - interrupt-parent = <&gpio0>; - interrupts = <27 IRQ_TYPE_LEVEL_LOW>; - interrupt-controller; - #interrupt-cells = <2>; - - switch0: switch@0 { - compatible = "marvell,mv88e6190"; - reg = <0>; - reset-gpios = <&gpio5 1 GPIO_ACTIVE_LOW>; - - mdio { - #address-cells = <1>; - #size-cells = <0>; - switch1phy0: switch1phy0@0 { - reg = <0>; - interrupt-parent = <&switch0>; - interrupts = <0 IRQ_TYPE_LEVEL_HIGH>; - }; - }; - - mdio1 { - compatible = "marvell,mv88e6xxx-mdio-external"; - #address-cells = <1>; - #size-cells = <0>; - switch1phy9: switch1phy0@9 { - reg = <9>; - }; - }; - }; - }; diff --git a/Documentation/devicetree/bindings/net/dsa/microchip,ksz.yaml b/Documentation/devicetree/bindings/net/dsa/microchip,ksz.yaml index b3029c64d0d5..c963dc09e8e1 100644 --- a/Documentation/devicetree/bindings/net/dsa/microchip,ksz.yaml +++ b/Documentation/devicetree/bindings/net/dsa/microchip,ksz.yaml @@ -11,7 +11,6 @@ maintainers: - Woojung Huh <Woojung.Huh@microchip.com> allOf: - - $ref: dsa.yaml#/$defs/ethernet-ports - $ref: /schemas/spi/spi-peripheral-props.yaml# properties: @@ -78,6 +77,39 @@ required: - compatible - reg +if: + not: + properties: + compatible: + enum: + - microchip,ksz8863 + - microchip,ksz8873 +then: + $ref: dsa.yaml#/$defs/ethernet-ports +else: + patternProperties: + "^(ethernet-)?ports$": + patternProperties: + "^(ethernet-)?port@[0-2]$": + $ref: dsa-port.yaml# + unevaluatedProperties: false + properties: + microchip,rmii-clk-internal: + $ref: /schemas/types.yaml#/definitions/flag + description: + When ksz88x3 is acting as clock provier (via REFCLKO) it + can select between internal and external RMII reference + clock. Internal reference clock means that the clock for + the RMII of ksz88x3 is provided by the ksz88x3 internally + and the REFCLKI pin is unconnected. For the external + reference clock, the clock needs to be fed back to ksz88x3 + via REFCLKI. + If microchip,rmii-clk-internal is set, ksz88x3 will provide + rmii reference clock internally, otherwise reference clock + should be provided externally. + dependencies: + microchip,rmii-clk-internal: [ethernet] + unevaluatedProperties: false examples: diff --git a/Documentation/devicetree/bindings/net/ethernet-switch.yaml b/Documentation/devicetree/bindings/net/ethernet-switch.yaml index 72ac67ca3415..b3b7e1a1b127 100644 --- a/Documentation/devicetree/bindings/net/ethernet-switch.yaml +++ b/Documentation/devicetree/bindings/net/ethernet-switch.yaml @@ -20,9 +20,26 @@ description: select: false -properties: - $nodename: - pattern: "^(ethernet-)?switch(@.*)?$" +allOf: + # This condition is here to satisfy the case where certain device + # nodes have to preserve non-standard names because of + # backward-compatibility with boot loaders inspecting certain + # node names. + - if: + properties: + compatible: + contains: + enum: + - marvell,turris-mox-mv88e6085 + - marvell,turris-mox-mv88e6190 + then: + properties: + $nodename: + pattern: "switch[0-3]@[0-3]+$" + else: + properties: + $nodename: + pattern: "^(ethernet-)?switch(@.*)?$" patternProperties: "^(ethernet-)?ports$": diff --git a/Documentation/devicetree/bindings/net/lantiq,pef2256.yaml b/Documentation/devicetree/bindings/net/lantiq,pef2256.yaml new file mode 100644 index 000000000000..7da8370e2468 --- /dev/null +++ b/Documentation/devicetree/bindings/net/lantiq,pef2256.yaml @@ -0,0 +1,213 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/net/lantiq,pef2256.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Lantiq PEF2256 + +maintainers: + - Herve Codina <herve.codina@bootlin.com> + +description: + The Lantiq PEF2256, also known as Infineon PEF2256 or FALC56, is a framer and + line interface component designed to fulfill all required interfacing between + an analog E1/T1/J1 line and the digital PCM system highway/H.100 bus. + +properties: + compatible: + items: + - const: lantiq,pef2256 + + reg: + maxItems: 1 + + clocks: + items: + - description: Master Clock + - description: System Clock Receive + - description: System Clock Transmit + + clock-names: + items: + - const: mclk + - const: sclkr + - const: sclkx + + interrupts: + maxItems: 1 + + reset-gpios: + description: + GPIO used to reset the device. + maxItems: 1 + + pinctrl: + $ref: /schemas/pinctrl/pinctrl.yaml# + additionalProperties: false + + patternProperties: + '-pins$': + type: object + $ref: /schemas/pinctrl/pinmux-node.yaml# + additionalProperties: false + + properties: + pins: + enum: [ RPA, RPB, RPC, RPD, XPA, XPB, XPC, XPD ] + + function: + enum: [ SYPR, RFM, RFMB, RSIGM, RSIG, DLR, FREEZE, RFSP, LOS, + SYPX, XFMS, XSIG, TCLK, XMFB, XSIGM, DLX, XCLK, XLT, + GPI, GPOH, GPOL ] + + required: + - pins + - function + + lantiq,data-rate-bps: + enum: [2048000, 4096000, 8192000, 16384000] + default: 2048000 + description: + Data rate (bit per seconds) on the system highway. + + lantiq,clock-falling-edge: + $ref: /schemas/types.yaml#/definitions/flag + description: + Data is sent on falling edge of the clock (and received on the rising + edge). If 'clock-falling-edge' is not present, data is sent on the + rising edge (and received on the falling edge). + + lantiq,channel-phase: + $ref: /schemas/types.yaml#/definitions/uint32 + enum: [0, 1, 2, 3, 4, 5, 6, 7] + default: 0 + description: | + The pef2256 delivers a full frame (32 8-bit time-slots in E1 and 24 8-bit + time-slots 8 8-bit signaling in E1/J1) every 125us. This lead to a data + rate of 2048000 bit/s. When lantiq,data-rate-bps is more than 2048000 + bit/s, the data (all 32 8-bit) present in the frame are interleave with + unused time-slots. The lantiq,channel-phase property allows to set the + correct alignment of the interleave mechanism. + For instance, suppose lantiq,data-rate-bps = 8192000 (ie 4*2048000), and + lantiq,channel-phase = 2, the interleave schema with unused time-slots + (nu) and used time-slots (XX) for TSi is + nu nu XX nu nu nu XX nu nu nu XX nu + <-- TSi --> <- TSi+1 -> <- TSi+2 -> + With lantiq,data-rate-bps = 8192000, and lantiq,channel-phase = 1, the + interleave schema is + nu XX nu nu nu XX nu nu nu XX nu nu + <-- TSi --> <- TSi+1 -> <- TSi+2 -> + With lantiq,data-rate-bps = 4096000 (ie 2*2048000), and + lantiq,channel-phase = 1, the interleave schema is + nu XX nu XX nu XX + <-- TSi --> <- TSi+1 -> <- TSi+2 -> + +patternProperties: + '^codec(-([0-9]|[1-2][0-9]|3[0-1]))?$': + type: object + $ref: /schemas/sound/dai-common.yaml + unevaluatedProperties: false + description: + Codec provided by the pef2256. This codec allows to use some of the PCM + system highway time-slots as audio channels to transport audio data over + the E1/T1/J1 lines. + The time-slots used by the codec must be set and so, the properties + 'dai-tdm-slot-num', 'dai-tdm-slot-width', 'dai-tdm-slot-tx-mask' and + 'dai-tdm-slot-rx-mask' must be present in the sound card node for + sub-nodes that involve the codec. The codec uses 8-bit time-slots. + 'dai-tdm-tdm-slot-with' must be set to 8. + The tx and rx masks define the pef2256 time-slots assigned to the codec. + + properties: + compatible: + const: lantiq,pef2256-codec + + '#sound-dai-cells': + const: 0 + + required: + - compatible + - '#sound-dai-cells' + +required: + - compatible + - reg + - clocks + - clock-names + - interrupts + +additionalProperties: false + +examples: + - | + #include <dt-bindings/gpio/gpio.h> + #include <dt-bindings/interrupt-controller/irq.h> + + pef2256: framer@2000000 { + compatible = "lantiq,pef2256"; + reg = <0x2000000 0x100>; + interrupts = <8 IRQ_TYPE_LEVEL_LOW>; + interrupt-parent = <&intc>; + clocks = <&clk_mclk>, <&clk_sclkr>, <&clk_sclkx>; + clock-names = "mclk", "sclkr", "sclkx"; + reset-gpios = <&gpio 11 GPIO_ACTIVE_LOW>; + lantiq,data-rate-bps = <4096000>; + + pinctrl { + pef2256_rpa_sypr: rpa-pins { + pins = "RPA"; + function = "SYPR"; + }; + pef2256_xpa_sypx: xpa-pins { + pins = "XPA"; + function = "SYPX"; + }; + }; + + pef2256_codec0: codec-0 { + compatible = "lantiq,pef2256-codec"; + #sound-dai-cells = <0>; + sound-name-prefix = "PEF2256_0"; + }; + + pef2256_codec1: codec-1 { + compatible = "lantiq,pef2256-codec"; + #sound-dai-cells = <0>; + sound-name-prefix = "PEF2256_1"; + }; + }; + + sound { + compatible = "simple-audio-card"; + #address-cells = <1>; + #size-cells = <0>; + simple-audio-card,dai-link@0 { /* CPU DAI1 - pef2256 codec 1 */ + reg = <0>; + cpu { + sound-dai = <&cpu_dai1>; + }; + codec { + sound-dai = <&pef2256_codec0>; + dai-tdm-slot-num = <4>; + dai-tdm-slot-width = <8>; + /* TS 1, 2, 3, 4 */ + dai-tdm-slot-tx-mask = <0 1 1 1 1>; + dai-tdm-slot-rx-mask = <0 1 1 1 1>; + }; + }; + simple-audio-card,dai-link@1 { /* CPU DAI2 - pef2256 codec 2 */ + reg = <1>; + cpu { + sound-dai = <&cpu_dai2>; + }; + codec { + sound-dai = <&pef2256_codec1>; + dai-tdm-slot-num = <4>; + dai-tdm-slot-width = <8>; + /* TS 5, 6, 7, 8 */ + dai-tdm-slot-tx-mask = <0 0 0 0 0 1 1 1 1>; + dai-tdm-slot-rx-mask = <0 0 0 0 0 1 1 1 1>; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/net/marvell,aquantia.yaml b/Documentation/devicetree/bindings/net/marvell,aquantia.yaml new file mode 100644 index 000000000000..9854fab4c4db --- /dev/null +++ b/Documentation/devicetree/bindings/net/marvell,aquantia.yaml @@ -0,0 +1,116 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/net/marvell,aquantia.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Marvell Aquantia Ethernet PHY + +maintainers: + - Christian Marangi <ansuelsmth@gmail.com> + +description: | + Marvell Aquantia Ethernet PHY require a firmware to be loaded to actually + work. + + This can be done and is implemented by OEM in 3 different way: + - Attached SPI flash directly to the PHY with the firmware. The PHY + will self load the firmware in the presence of this configuration. + - Read from a dedicated partition on system NAND declared in an + NVMEM cell, and loaded to the PHY using its mailbox interface. + - Manually provided firmware loaded from a file in the filesystem. + +allOf: + - $ref: ethernet-phy.yaml# + +select: + properties: + compatible: + contains: + enum: + - ethernet-phy-id03a1.b445 + - ethernet-phy-id03a1.b460 + - ethernet-phy-id03a1.b4a2 + - ethernet-phy-id03a1.b4d0 + - ethernet-phy-id03a1.b4e0 + - ethernet-phy-id03a1.b5c2 + - ethernet-phy-id03a1.b4b0 + - ethernet-phy-id03a1.b662 + - ethernet-phy-id03a1.b712 + - ethernet-phy-id31c3.1c12 + required: + - compatible + +properties: + reg: + maxItems: 1 + + firmware-name: + description: specify the name of PHY firmware to load + + nvmem-cells: + description: phandle to the firmware nvmem cell + maxItems: 1 + + nvmem-cell-names: + const: firmware + +required: + - compatible + - reg + +unevaluatedProperties: false + +examples: + - | + mdio { + #address-cells = <1>; + #size-cells = <0>; + + ethernet-phy@0 { + compatible = "ethernet-phy-id31c3.1c12", + "ethernet-phy-ieee802.3-c45"; + + reg = <0>; + firmware-name = "AQR-G4_v5.4.C-AQR_CIG_WF-1945_0x8_ID44776_VER1630.cld"; + }; + + ethernet-phy@1 { + compatible = "ethernet-phy-id31c3.1c12", + "ethernet-phy-ieee802.3-c45"; + + reg = <1>; + nvmem-cells = <&aqr_fw>; + nvmem-cell-names = "firmware"; + }; + }; + + flash { + compatible = "jedec,spi-nor"; + #address-cells = <1>; + #size-cells = <1>; + + partitions { + compatible = "fixed-partitions"; + #address-cells = <1>; + #size-cells = <1>; + + /* ... */ + + partition@650000 { + compatible = "nvmem-cells"; + label = "0:ethphyfw"; + reg = <0x650000 0x80000>; + read-only; + #address-cells = <1>; + #size-cells = <1>; + + aqr_fw: aqr_fw@0 { + reg = <0x0 0x5f42a>; + }; + }; + + /* ... */ + + }; + }; diff --git a/Documentation/devicetree/bindings/net/marvell,mvusb.yaml b/Documentation/devicetree/bindings/net/marvell,mvusb.yaml index 3a3325168048..ab838c1ffeed 100644 --- a/Documentation/devicetree/bindings/net/marvell,mvusb.yaml +++ b/Documentation/devicetree/bindings/net/marvell,mvusb.yaml @@ -50,11 +50,14 @@ examples: #address-cells = <1>; #size-cells = <0>; - switch@0 { + ethernet-switch@0 { compatible = "marvell,mv88e6190"; reg = <0x0>; - ports { + ethernet-ports { + #address-cells = <1>; + #size-cells = <0>; + /* Port definitions */ }; diff --git a/Documentation/devicetree/bindings/net/marvell,orion-mdio.yaml b/Documentation/devicetree/bindings/net/marvell,orion-mdio.yaml index e35da8b01dc2..73429855d584 100644 --- a/Documentation/devicetree/bindings/net/marvell,orion-mdio.yaml +++ b/Documentation/devicetree/bindings/net/marvell,orion-mdio.yaml @@ -39,28 +39,6 @@ required: allOf: - $ref: mdio.yaml# - - if: - required: - - interrupts - - then: - properties: - reg: - items: - - items: - - $ref: /schemas/types.yaml#/definitions/cell - - const: 0x84 - - else: - properties: - reg: - items: - - items: - - $ref: /schemas/types.yaml#/definitions/cell - - enum: - - 0x4 - - 0x10 - unevaluatedProperties: false examples: diff --git a/Documentation/devicetree/bindings/net/qcom,ipa.yaml b/Documentation/devicetree/bindings/net/qcom,ipa.yaml index 2d5e4ffb2f9e..c30218684cfe 100644 --- a/Documentation/devicetree/bindings/net/qcom,ipa.yaml +++ b/Documentation/devicetree/bindings/net/qcom,ipa.yaml @@ -43,15 +43,21 @@ description: properties: compatible: - enum: - - qcom,msm8998-ipa - - qcom,sc7180-ipa - - qcom,sc7280-ipa - - qcom,sdm845-ipa - - qcom,sdx55-ipa - - qcom,sdx65-ipa - - qcom,sm6350-ipa - - qcom,sm8350-ipa + oneOf: + - enum: + - qcom,msm8998-ipa + - qcom,sc7180-ipa + - qcom,sc7280-ipa + - qcom,sdm845-ipa + - qcom,sdx55-ipa + - qcom,sdx65-ipa + - qcom,sm6350-ipa + - qcom,sm8350-ipa + - qcom,sm8550-ipa + - items: + - enum: + - qcom,sm8650-ipa + - const: qcom,sm8550-ipa reg: items: diff --git a/Documentation/devicetree/bindings/net/renesas,etheravb.yaml b/Documentation/devicetree/bindings/net/renesas,etheravb.yaml index 5d074f27d462..890f7858d0dc 100644 --- a/Documentation/devicetree/bindings/net/renesas,etheravb.yaml +++ b/Documentation/devicetree/bindings/net/renesas,etheravb.yaml @@ -55,9 +55,10 @@ properties: - items: - enum: - - renesas,r9a07g043-gbeth # RZ/G2UL + - renesas,r9a07g043-gbeth # RZ/G2UL and RZ/Five - renesas,r9a07g044-gbeth # RZ/G2{L,LC} - renesas,r9a07g054-gbeth # RZ/V2L + - renesas,r9a08g045-gbeth # RZ/G3S - const: renesas,rzg2l-gbeth # RZ/{G2L,G2UL,V2L} family reg: true diff --git a/Documentation/devicetree/bindings/net/renesas,ethertsn.yaml b/Documentation/devicetree/bindings/net/renesas,ethertsn.yaml new file mode 100644 index 000000000000..475aff7714d6 --- /dev/null +++ b/Documentation/devicetree/bindings/net/renesas,ethertsn.yaml @@ -0,0 +1,133 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/net/renesas,ethertsn.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Renesas Ethernet TSN End-station + +maintainers: + - Niklas Söderlund <niklas.soderlund@ragnatech.se> + +description: + The RTSN device provides Ethernet network using a 10 Mbps, 100 Mbps, or 1 + Gbps full-duplex link via MII/GMII/RMII/RGMII. Depending on the connected PHY. + +allOf: + - $ref: ethernet-controller.yaml# + +properties: + compatible: + items: + - enum: + - renesas,r8a779g0-ethertsn # R-Car V4H + - const: renesas,rcar-gen4-ethertsn + + reg: + items: + - description: TSN End Station target + - description: generalized Precision Time Protocol target + + reg-names: + items: + - const: tsnes + - const: gptp + + interrupts: + items: + - description: TX data interrupt + - description: RX data interrupt + + interrupt-names: + items: + - const: tx + - const: rx + + clocks: + maxItems: 1 + + power-domains: + maxItems: 1 + + resets: + maxItems: 1 + + phy-mode: + contains: + enum: + - mii + - rgmii + + phy-handle: + $ref: /schemas/types.yaml#/definitions/phandle + description: + Specifies a reference to a node representing a PHY device. + + rx-internal-delay-ps: + enum: [0, 1800] + + tx-internal-delay-ps: + enum: [0, 2000] + + '#address-cells': + const: 1 + + '#size-cells': + const: 0 + +patternProperties: + "^ethernet-phy@[0-9a-f]$": + type: object + $ref: ethernet-phy.yaml# + unevaluatedProperties: false + +required: + - compatible + - reg + - reg-names + - interrupts + - interrupt-names + - clocks + - power-domains + - resets + - phy-mode + - phy-handle + - '#address-cells' + - '#size-cells' + +additionalProperties: false + +examples: + - | + #include <dt-bindings/clock/r8a779g0-cpg-mssr.h> + #include <dt-bindings/interrupt-controller/arm-gic.h> + #include <dt-bindings/power/r8a779g0-sysc.h> + #include <dt-bindings/gpio/gpio.h> + + tsn0: ethernet@e6460000 { + compatible = "renesas,r8a779g0-ethertsn", "renesas,rcar-gen4-ethertsn"; + reg = <0xe6460000 0x7000>, + <0xe6449000 0x500>; + reg-names = "tsnes", "gptp"; + interrupts = <GIC_SPI 429 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 430 IRQ_TYPE_LEVEL_HIGH>; + interrupt-names = "tx", "rx"; + clocks = <&cpg CPG_MOD 2723>; + power-domains = <&sysc R8A779G0_PD_ALWAYS_ON>; + resets = <&cpg 2723>; + + phy-mode = "rgmii"; + tx-internal-delay-ps = <2000>; + phy-handle = <&phy3>; + + #address-cells = <1>; + #size-cells = <0>; + + phy3: ethernet-phy@3 { + compatible = "ethernet-phy-ieee802.3-c45"; + reg = <0>; + interrupt-parent = <&gpio4>; + interrupts = <3 IRQ_TYPE_LEVEL_LOW>; + reset-gpios = <&gpio1 23 GPIO_ACTIVE_LOW>; + }; + }; diff --git a/Documentation/devicetree/bindings/net/xlnx,axi-ethernet.yaml b/Documentation/devicetree/bindings/net/xlnx,axi-ethernet.yaml index 1d33d80af11c..bbe89ea9590c 100644 --- a/Documentation/devicetree/bindings/net/xlnx,axi-ethernet.yaml +++ b/Documentation/devicetree/bindings/net/xlnx,axi-ethernet.yaml @@ -122,6 +122,20 @@ properties: and "phy-handle" should point to an external PHY if exists. maxItems: 1 + dmas: + minItems: 2 + maxItems: 32 + description: TX and RX DMA channel phandle + + dma-names: + items: + pattern: "^[tr]x_chan([0-9]|1[0-5])$" + description: + Should be "tx_chan0", "tx_chan1" ... "tx_chan15" for DMA Tx channel + Should be "rx_chan0", "rx_chan1" ... "rx_chan15" for DMA Rx channel + minItems: 2 + maxItems: 32 + required: - compatible - interrupts @@ -143,6 +157,8 @@ examples: clocks = <&axi_clk>, <&axi_clk>, <&pl_enet_ref_clk>, <&mgt_clk>; phy-mode = "mii"; reg = <0x40c00000 0x40000>,<0x50c00000 0x40000>; + dmas = <&xilinx_dma 0>, <&xilinx_dma 1>; + dma-names = "tx_chan0", "rx_chan0"; xlnx,rxcsum = <0x2>; xlnx,rxmem = <0x800>; xlnx,txcsum = <0x2>; diff --git a/Documentation/devicetree/bindings/nvmem/mxs-ocotp.yaml b/Documentation/devicetree/bindings/nvmem/mxs-ocotp.yaml index f43186f98607..d9287be89877 100644 --- a/Documentation/devicetree/bindings/nvmem/mxs-ocotp.yaml +++ b/Documentation/devicetree/bindings/nvmem/mxs-ocotp.yaml @@ -15,9 +15,11 @@ allOf: properties: compatible: - enum: - - fsl,imx23-ocotp - - fsl,imx28-ocotp + items: + - enum: + - fsl,imx23-ocotp + - fsl,imx28-ocotp + - const: fsl,ocotp reg: maxItems: 1 @@ -35,7 +37,7 @@ unevaluatedProperties: false examples: - | ocotp: efuse@8002c000 { - compatible = "fsl,imx28-ocotp"; + compatible = "fsl,imx28-ocotp", "fsl,ocotp"; #address-cells = <1>; #size-cells = <1>; reg = <0x8002c000 0x2000>; diff --git a/Documentation/devicetree/bindings/perf/fsl-imx-ddr.yaml b/Documentation/devicetree/bindings/perf/fsl-imx-ddr.yaml index e9fad4b3de68..6c96a4204e5d 100644 --- a/Documentation/devicetree/bindings/perf/fsl-imx-ddr.yaml +++ b/Documentation/devicetree/bindings/perf/fsl-imx-ddr.yaml @@ -27,6 +27,9 @@ properties: - fsl,imx8mq-ddr-pmu - fsl,imx8mp-ddr-pmu - const: fsl,imx8m-ddr-pmu + - items: + - const: fsl,imx8dxl-ddr-pmu + - const: fsl,imx8-ddr-pmu reg: maxItems: 1 diff --git a/Documentation/devicetree/bindings/pwm/pwm-samsung.yaml b/Documentation/devicetree/bindings/pwm/pwm-samsung.yaml index 2162f661ed5a..17a2b927af33 100644 --- a/Documentation/devicetree/bindings/pwm/pwm-samsung.yaml +++ b/Documentation/devicetree/bindings/pwm/pwm-samsung.yaml @@ -29,7 +29,11 @@ properties: - samsung,exynos4210-pwm # 32-bit, Exynos - items: - enum: + - samsung,exynos5433-pwm + - samsung,exynos7-pwm - samsung,exynosautov9-pwm + - samsung,exynosautov920-pwm + - tesla,fsd-pwm - const: samsung,exynos4210-pwm reg: diff --git a/Documentation/devicetree/bindings/regulator/fixed-regulator.yaml b/Documentation/devicetree/bindings/regulator/fixed-regulator.yaml index ce7751b9129c..9ff9abf2691a 100644 --- a/Documentation/devicetree/bindings/regulator/fixed-regulator.yaml +++ b/Documentation/devicetree/bindings/regulator/fixed-regulator.yaml @@ -105,6 +105,8 @@ properties: description: Interrupt signaling a critical under-voltage event. + system-critical-regulator: true + required: - compatible - regulator-name diff --git a/Documentation/devicetree/bindings/regulator/qcom,rpmh-regulator.yaml b/Documentation/devicetree/bindings/regulator/qcom,rpmh-regulator.yaml index acd37f28ef53..27c6d5152413 100644 --- a/Documentation/devicetree/bindings/regulator/qcom,rpmh-regulator.yaml +++ b/Documentation/devicetree/bindings/regulator/qcom,rpmh-regulator.yaml @@ -42,6 +42,7 @@ description: | For PM7325, smps1 - smps8, ldo1 - ldo19 For PM8005, smps1 - smps4 For PM8009, smps1 - smps2, ldo1 - ldo7 + For PM8010, ldo1 - ldo7 For PM8150, smps1 - smps10, ldo1 - ldo18 For PM8150L, smps1 - smps8, ldo1 - ldo11, bob, flash, rgb For PM8350, smps1 - smps12, ldo1 - ldo10 @@ -68,6 +69,7 @@ properties: - qcom,pm8005-rpmh-regulators - qcom,pm8009-rpmh-regulators - qcom,pm8009-1-rpmh-regulators + - qcom,pm8010-rpmh-regulators - qcom,pm8150-rpmh-regulators - qcom,pm8150l-rpmh-regulators - qcom,pm8350-rpmh-regulators @@ -242,6 +244,18 @@ allOf: properties: compatible: enum: + - qcom,pm8010-rpmh-regulators + then: + properties: + vdd-l1-l2-supply: true + vdd-l3-l4-supply: true + patternProperties: + "^vdd-l[5-7]-supply$": true + + - if: + properties: + compatible: + enum: - qcom,pm8150-rpmh-regulators - qcom,pmc8180-rpmh-regulators - qcom,pmm8155au-rpmh-regulators diff --git a/Documentation/devicetree/bindings/regulator/qcom,smd-rpm-regulator.yaml b/Documentation/devicetree/bindings/regulator/qcom,smd-rpm-regulator.yaml index 9ea8ac0786ac..f2fd2df68a9e 100644 --- a/Documentation/devicetree/bindings/regulator/qcom,smd-rpm-regulator.yaml +++ b/Documentation/devicetree/bindings/regulator/qcom,smd-rpm-regulator.yaml @@ -47,6 +47,9 @@ description: For pm8916, s1, s2, s3, s4, l1, l2, l3, l4, l5, l6, l7, l8, l9, l10, l11, l12, l13, l14, l15, l16, l17, l18 + For pm8937, s1, s2, s3, s4, l1, l2, l3, l4, l5, l6, l7, l8, l9, l10, + l11, l12, l13, l14, l15, l16, l17, l18, l19, l20, l21, l22, l23 + For pm8941, s1, s2, s3, s4, l1, l2, l3, l4, l5, l6, l7, l8, l9, l10, l11, l12, l13, l14, l15, l16, l17, l18, l19, l20, l21, l22, l23, l24, lvs1, lvs2, lvs3, 5vs1, 5vs2 @@ -92,6 +95,7 @@ properties: - qcom,rpm-pm8841-regulators - qcom,rpm-pm8909-regulators - qcom,rpm-pm8916-regulators + - qcom,rpm-pm8937-regulators - qcom,rpm-pm8941-regulators - qcom,rpm-pm8950-regulators - qcom,rpm-pm8953-regulators diff --git a/Documentation/devicetree/bindings/regulator/qcom,spmi-regulator.yaml b/Documentation/devicetree/bindings/regulator/qcom,spmi-regulator.yaml index 7a1b7d2abbd4..aea849e8eadf 100644 --- a/Documentation/devicetree/bindings/regulator/qcom,spmi-regulator.yaml +++ b/Documentation/devicetree/bindings/regulator/qcom,spmi-regulator.yaml @@ -22,6 +22,7 @@ properties: - qcom,pm8841-regulators - qcom,pm8909-regulators - qcom,pm8916-regulators + - qcom,pm8937-regulators - qcom,pm8941-regulators - qcom,pm8950-regulators - qcom,pm8994-regulators @@ -296,6 +297,24 @@ allOf: compatible: contains: enum: + - qcom,pm8937-regulators + then: + properties: + vdd_l1_l19-supply: true + vdd_l20_l21-supply: true + vdd_l2_l23-supply: true + vdd_l3-supply: true + vdd_l4_l5_l6_l7_l16-supply: true + vdd_l8_l11_l12_l17_l22-supply: true + vdd_l9_l10_l13_l14_l15_l18-supply: true + patternProperties: + "^vdd_s[1-6]-supply$": true + + - if: + properties: + compatible: + contains: + enum: - qcom,pm8950-regulators then: properties: diff --git a/Documentation/devicetree/bindings/regulator/qcom,usb-vbus-regulator.yaml b/Documentation/devicetree/bindings/regulator/qcom,usb-vbus-regulator.yaml index 89c564dfa5db..534f87e98716 100644 --- a/Documentation/devicetree/bindings/regulator/qcom,usb-vbus-regulator.yaml +++ b/Documentation/devicetree/bindings/regulator/qcom,usb-vbus-regulator.yaml @@ -36,10 +36,11 @@ unevaluatedProperties: false examples: - | - pm8150b { + pmic { #address-cells = <1>; #size-cells = <0>; - pm8150b_vbus: usb-vbus-regulator@1100 { + + usb-vbus-regulator@1100 { compatible = "qcom,pm8150b-vbus-reg"; reg = <0x1100>; regulator-min-microamp = <500000>; diff --git a/Documentation/devicetree/bindings/regulator/regulator.yaml b/Documentation/devicetree/bindings/regulator/regulator.yaml index 9daf0fc2465f..1ef380d1515e 100644 --- a/Documentation/devicetree/bindings/regulator/regulator.yaml +++ b/Documentation/devicetree/bindings/regulator/regulator.yaml @@ -114,6 +114,11 @@ properties: description: Enable pull down resistor when the regulator is disabled. type: boolean + system-critical-regulator: + description: Set if the regulator is critical to system stability or + functionality. + type: boolean + regulator-over-current-protection: description: Enable over current protection. type: boolean @@ -181,6 +186,14 @@ properties: be enabled but limit setting can be omitted. Limit is given as microvolt offset from voltage set to regulator. + regulator-uv-less-critical-window-ms: + description: Specifies the time window (in milliseconds) following a + critical under-voltage event during which the system can continue to + operate safely while performing less critical operations. This property + provides a defined duration before a more severe reaction to the + under-voltage event is needed, allowing for certain non-urgent actions to + be carried out in preparation for potential power loss. + regulator-temp-protection-kelvin: description: Set over temperature protection limit. This is a limit where hardware performs emergency shutdown. Zero can be passed to disable diff --git a/Documentation/devicetree/bindings/reset/amlogic,meson-reset.yaml b/Documentation/devicetree/bindings/reset/amlogic,meson-reset.yaml index d3fdee89d4f8..f0c6c0df0ce3 100644 --- a/Documentation/devicetree/bindings/reset/amlogic,meson-reset.yaml +++ b/Documentation/devicetree/bindings/reset/amlogic,meson-reset.yaml @@ -18,6 +18,7 @@ properties: - amlogic,meson-axg-reset # Reset Controller on AXG and compatible SoCs - amlogic,meson-a1-reset # Reset Controller on A1 and compatible SoCs - amlogic,meson-s4-reset # Reset Controller on S4 and compatible SoCs + - amlogic,c3-reset # Reset Controller on C3 and compatible SoCs reg: maxItems: 1 diff --git a/Documentation/devicetree/bindings/reset/fsl,imx-src.yaml b/Documentation/devicetree/bindings/reset/fsl,imx-src.yaml index b11ac533f914..f5ec1d54aa51 100644 --- a/Documentation/devicetree/bindings/reset/fsl,imx-src.yaml +++ b/Documentation/devicetree/bindings/reset/fsl,imx-src.yaml @@ -28,28 +28,17 @@ description: | properties: compatible: oneOf: - - const: "fsl,imx51-src" + - const: fsl,imx51-src - items: - - const: "fsl,imx50-src" - - const: "fsl,imx51-src" - - items: - - const: "fsl,imx53-src" - - const: "fsl,imx51-src" - - items: - - const: "fsl,imx6q-src" - - const: "fsl,imx51-src" - - items: - - const: "fsl,imx6sx-src" - - const: "fsl,imx51-src" - - items: - - const: "fsl,imx6sl-src" - - const: "fsl,imx51-src" - - items: - - const: "fsl,imx6ul-src" - - const: "fsl,imx51-src" - - items: - - const: "fsl,imx6sll-src" - - const: "fsl,imx51-src" + - enum: + - fsl,imx50-src + - fsl,imx53-src + - fsl,imx6q-src + - fsl,imx6sx-src + - fsl,imx6sl-src + - fsl,imx6ul-src + - fsl,imx6sll-src + - const: fsl,imx51-src reg: maxItems: 1 diff --git a/Documentation/devicetree/bindings/reset/hisilicon,hi3660-reset.yaml b/Documentation/devicetree/bindings/reset/hisilicon,hi3660-reset.yaml index cdfcf32c53fa..e4de002d6903 100644 --- a/Documentation/devicetree/bindings/reset/hisilicon,hi3660-reset.yaml +++ b/Documentation/devicetree/bindings/reset/hisilicon,hi3660-reset.yaml @@ -50,32 +50,9 @@ additionalProperties: false examples: - | - #include <dt-bindings/interrupt-controller/irq.h> - #include <dt-bindings/interrupt-controller/arm-gic.h> - #include <dt-bindings/clock/hi3660-clock.h> - - iomcu: iomcu@ffd7e000 { - compatible = "hisilicon,hi3660-iomcu", "syscon"; - reg = <0xffd7e000 0x1000>; - }; - - iomcu_rst: iomcu_rst_controller { + iomcu_rst_controller { compatible = "hisilicon,hi3660-reset"; hisilicon,rst-syscon = <&iomcu>; #reset-cells = <2>; }; - - /* Specifying reset lines connected to IP modules */ - i2c@ffd71000 { - compatible = "snps,designware-i2c"; - reg = <0xffd71000 0x1000>; - interrupts = <GIC_SPI 118 IRQ_TYPE_LEVEL_HIGH>; - #address-cells = <1>; - #size-cells = <0>; - clock-frequency = <400000>; - clocks = <&crg_ctrl HI3660_CLK_GATE_I2C0>; - resets = <&iomcu_rst 0x20 3>; - pinctrl-names = "default"; - pinctrl-0 = <&i2c0_pmx_func &i2c0_cfg_func>; - }; ... diff --git a/Documentation/devicetree/bindings/reset/qcom,aoss-reset.yaml b/Documentation/devicetree/bindings/reset/qcom,aoss-reset.yaml index d92e2b3cc83f..24beb712b56d 100644 --- a/Documentation/devicetree/bindings/reset/qcom,aoss-reset.yaml +++ b/Documentation/devicetree/bindings/reset/qcom,aoss-reset.yaml @@ -18,17 +18,17 @@ properties: oneOf: - description: on SC7180 SoCs the following compatibles must be specified items: - - const: "qcom,sc7180-aoss-cc" - - const: "qcom,sdm845-aoss-cc" + - 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" + - 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" + - const: qcom,sdm845-aoss-cc reg: maxItems: 1 diff --git a/Documentation/devicetree/bindings/reset/qcom,pdc-global.yaml b/Documentation/devicetree/bindings/reset/qcom,pdc-global.yaml index ca5d79332189..f514363aa474 100644 --- a/Documentation/devicetree/bindings/reset/qcom,pdc-global.yaml +++ b/Documentation/devicetree/bindings/reset/qcom,pdc-global.yaml @@ -18,16 +18,16 @@ properties: oneOf: - description: on SC7180 SoCs the following compatibles must be specified items: - - const: "qcom,sc7180-pdc-global" - - const: "qcom,sdm845-pdc-global" + - 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" + - const: qcom,sc7280-pdc-global - description: on SDM845 SoCs the following compatibles must be specified items: - - const: "qcom,sdm845-pdc-global" + - const: qcom,sdm845-pdc-global reg: maxItems: 1 diff --git a/Documentation/devicetree/bindings/reset/renesas,rzg2l-usbphy-ctrl.yaml b/Documentation/devicetree/bindings/reset/renesas,rzg2l-usbphy-ctrl.yaml index 731b8ce01525..03c18611e42d 100644 --- a/Documentation/devicetree/bindings/reset/renesas,rzg2l-usbphy-ctrl.yaml +++ b/Documentation/devicetree/bindings/reset/renesas,rzg2l-usbphy-ctrl.yaml @@ -17,7 +17,7 @@ properties: compatible: items: - enum: - - renesas,r9a07g043-usbphy-ctrl # RZ/G2UL + - renesas,r9a07g043-usbphy-ctrl # RZ/G2UL and RZ/Five - renesas,r9a07g044-usbphy-ctrl # RZ/G2{L,LC} - renesas,r9a07g054-usbphy-ctrl # RZ/V2L - const: renesas,rzg2l-usbphy-ctrl diff --git a/Documentation/devicetree/bindings/riscv/sophgo.yaml b/Documentation/devicetree/bindings/riscv/sophgo.yaml index 86748c5390be..9bc813dad098 100644 --- a/Documentation/devicetree/bindings/riscv/sophgo.yaml +++ b/Documentation/devicetree/bindings/riscv/sophgo.yaml @@ -24,6 +24,10 @@ properties: - const: sophgo,cv1800b - items: - enum: + - sophgo,huashan-pi + - const: sophgo,cv1812h + - items: + - enum: - milkv,pioneer - const: sophgo,sg2042 diff --git a/Documentation/devicetree/bindings/rng/starfive,jh7110-trng.yaml b/Documentation/devicetree/bindings/rng/starfive,jh7110-trng.yaml index 2b76ce25acc4..4639247e9e51 100644 --- a/Documentation/devicetree/bindings/rng/starfive,jh7110-trng.yaml +++ b/Documentation/devicetree/bindings/rng/starfive,jh7110-trng.yaml @@ -11,7 +11,11 @@ maintainers: properties: compatible: - const: starfive,jh7110-trng + oneOf: + - items: + - const: starfive,jh8100-trng + - const: starfive,jh7110-trng + - const: starfive,jh7110-trng reg: maxItems: 1 diff --git a/Documentation/devicetree/bindings/rtc/s3c-rtc.yaml b/Documentation/devicetree/bindings/rtc/s3c-rtc.yaml index d51b236939bf..bf4e11d6dffb 100644 --- a/Documentation/devicetree/bindings/rtc/s3c-rtc.yaml +++ b/Documentation/devicetree/bindings/rtc/s3c-rtc.yaml @@ -17,6 +17,11 @@ properties: - samsung,s3c2416-rtc - samsung,s3c2443-rtc - samsung,s3c6410-rtc + - items: + - enum: + - samsung,exynos7-rtc + - samsung,exynos850-rtc + - const: samsung,s3c6410-rtc - const: samsung,exynos3250-rtc deprecated: true diff --git a/Documentation/devicetree/bindings/serial/samsung_uart.yaml b/Documentation/devicetree/bindings/serial/samsung_uart.yaml index ac60ab1e35e3..133259ed3a34 100644 --- a/Documentation/devicetree/bindings/serial/samsung_uart.yaml +++ b/Documentation/devicetree/bindings/serial/samsung_uart.yaml @@ -18,17 +18,29 @@ description: |+ properties: compatible: oneOf: - - items: - - const: samsung,exynosautov9-uart - - const: samsung,exynos850-uart - enum: - apple,s5l-uart - axis,artpec8-uart + - google,gs101-uart - samsung,s3c6400-uart - samsung,s5pv210-uart - samsung,exynos4210-uart - samsung,exynos5433-uart - samsung,exynos850-uart + - items: + - enum: + - samsung,exynos7-uart + - tesla,fsd-uart + - const: samsung,exynos4210-uart + - items: + - enum: + - samsung,exynos7885-uart + - const: samsung,exynos5433-uart + - items: + - enum: + - samsung,exynosautov9-uart + - samsung,exynosautov920-uart + - const: samsung,exynos850-uart reg: maxItems: 1 @@ -122,6 +134,16 @@ allOf: - const: uart - const: clk_uart_baud0 + - if: + properties: + compatible: + contains: + enum: + - google,gs101-uart + then: + required: + - samsung,uart-fifosize + unevaluatedProperties: false examples: diff --git a/Documentation/devicetree/bindings/soc/amlogic/amlogic,meson-gx-hhi-sysctrl.yaml b/Documentation/devicetree/bindings/soc/amlogic/amlogic,meson-gx-hhi-sysctrl.yaml index 16977e4e4357..c6bce40946d4 100644 --- a/Documentation/devicetree/bindings/soc/amlogic/amlogic,meson-gx-hhi-sysctrl.yaml +++ b/Documentation/devicetree/bindings/soc/amlogic/amlogic,meson-gx-hhi-sysctrl.yaml @@ -158,3 +158,36 @@ examples: }; }; }; + + - | + system-controller@ff63c000 { + compatible = "amlogic,meson-axg-hhi-sysctrl", "simple-mfd", "syscon"; + reg = <0xff63c000 0x400>; + + clock-controller { + compatible = "amlogic,axg-clkc"; + #clock-cells = <1>; + clocks = <&xtal>; + clock-names = "xtal"; + }; + + power-controller { + compatible = "amlogic,meson-axg-pwrc"; + #power-domain-cells = <1>; + amlogic,ao-sysctrl = <&sysctrl_AO>; + + resets = <&reset_viu>, + <&reset_venc>, + <&reset_vcbus>, + <&reset_vencl>, + <&reset_vid_lock>; + reset-names = "viu", "venc", "vcbus", "vencl", "vid_lock"; + clocks = <&clk_vpu>, <&clk_vapb>; + clock-names = "vpu", "vapb"; + }; + + phy { + compatible = "amlogic,axg-mipi-pcie-analog-phy"; + #phy-cells = <0>; + }; + }; diff --git a/Documentation/devicetree/bindings/soc/mediatek/mediatek,pwrap.yaml b/Documentation/devicetree/bindings/soc/mediatek/mediatek,pwrap.yaml index a06ac2177444..4737e5f45d54 100644 --- a/Documentation/devicetree/bindings/soc/mediatek/mediatek,pwrap.yaml +++ b/Documentation/devicetree/bindings/soc/mediatek/mediatek,pwrap.yaml @@ -41,7 +41,6 @@ properties: - mediatek,mt8173-pwrap - mediatek,mt8183-pwrap - mediatek,mt8186-pwrap - - mediatek,mt8188-pwrap - mediatek,mt8195-pwrap - mediatek,mt8365-pwrap - mediatek,mt8516-pwrap @@ -50,6 +49,11 @@ properties: - mediatek,mt8186-pwrap - mediatek,mt8195-pwrap - const: syscon + - items: + - enum: + - mediatek,mt8188-pwrap + - const: mediatek,mt8195-pwrap + - const: syscon reg: minItems: 1 diff --git a/Documentation/devicetree/bindings/soc/mediatek/mtk-svs.yaml b/Documentation/devicetree/bindings/soc/mediatek/mtk-svs.yaml index 7eda63d5682f..742b91d1d28e 100644 --- a/Documentation/devicetree/bindings/soc/mediatek/mtk-svs.yaml +++ b/Documentation/devicetree/bindings/soc/mediatek/mtk-svs.yaml @@ -22,8 +22,10 @@ properties: compatible: enum: - mediatek,mt8183-svs + - mediatek,mt8186-svs - mediatek,mt8188-svs - mediatek,mt8192-svs + - mediatek,mt8195-svs reg: maxItems: 1 diff --git a/Documentation/devicetree/bindings/soc/microchip/microchip,mpfs-sys-controller.yaml b/Documentation/devicetree/bindings/soc/microchip/microchip,mpfs-sys-controller.yaml index 365a9fed5914..a3fa04f3a1bd 100644 --- a/Documentation/devicetree/bindings/soc/microchip/microchip,mpfs-sys-controller.yaml +++ b/Documentation/devicetree/bindings/soc/microchip/microchip,mpfs-sys-controller.yaml @@ -26,6 +26,16 @@ properties: compatible: const: microchip,mpfs-sys-controller + microchip,bitstream-flash: + $ref: /schemas/types.yaml#/definitions/phandle + description: + The SPI flash connected to the system controller's QSPI controller. + The system controller may retrieve FPGA bitstreams from this flash to + perform In-Application Programming (IAP) or during device initialisation + for Auto Update. The MSS and system controller have separate QSPI + controllers and this flash is connected to both. Software running in the + MSS can write bitstreams to the flash. + required: - compatible - mboxes diff --git a/Documentation/devicetree/bindings/soc/qcom/qcom,aoss-qmp.yaml b/Documentation/devicetree/bindings/soc/qcom/qcom,aoss-qmp.yaml index d1c7c2be865f..b4478f417edc 100644 --- a/Documentation/devicetree/bindings/soc/qcom/qcom,aoss-qmp.yaml +++ b/Documentation/devicetree/bindings/soc/qcom/qcom,aoss-qmp.yaml @@ -38,6 +38,8 @@ properties: - qcom,sm8350-aoss-qmp - qcom,sm8450-aoss-qmp - qcom,sm8550-aoss-qmp + - qcom,sm8650-aoss-qmp + - qcom,x1e80100-aoss-qmp - const: qcom,aoss-qmp reg: diff --git a/Documentation/devicetree/bindings/soc/qcom/qcom,pmic-glink.yaml b/Documentation/devicetree/bindings/soc/qcom/qcom,pmic-glink.yaml index 422921cf1f82..61df97ffe1e4 100644 --- a/Documentation/devicetree/bindings/soc/qcom/qcom,pmic-glink.yaml +++ b/Documentation/devicetree/bindings/soc/qcom/qcom,pmic-glink.yaml @@ -20,14 +20,20 @@ description: properties: compatible: - items: - - enum: - - qcom,sc8180x-pmic-glink - - qcom,sc8280xp-pmic-glink - - qcom,sm8350-pmic-glink - - qcom,sm8450-pmic-glink - - qcom,sm8550-pmic-glink - - const: qcom,pmic-glink + oneOf: + - items: + - enum: + - qcom,sc8180x-pmic-glink + - qcom,sc8280xp-pmic-glink + - qcom,sm8350-pmic-glink + - qcom,sm8450-pmic-glink + - qcom,sm8550-pmic-glink + - const: qcom,pmic-glink + - items: + - enum: + - qcom,sm8650-pmic-glink + - const: qcom,sm8550-pmic-glink + - const: qcom,pmic-glink '#address-cells': const: 1 diff --git a/Documentation/devicetree/bindings/soc/qcom/qcom-stats.yaml b/Documentation/devicetree/bindings/soc/qcom/qcom-stats.yaml index 96a7f1822022..686a7ef2f48a 100644 --- a/Documentation/devicetree/bindings/soc/qcom/qcom-stats.yaml +++ b/Documentation/devicetree/bindings/soc/qcom/qcom-stats.yaml @@ -31,10 +31,24 @@ properties: reg: maxItems: 1 + qcom,qmp: + $ref: /schemas/types.yaml#/definitions/phandle + description: Reference to the AOSS side-channel message RAM + required: - compatible - reg +allOf: + - if: + not: + properties: + compatible: + const: qcom,rpmh-stats + then: + properties: + qcom,qmp: false + additionalProperties: false examples: diff --git a/Documentation/devicetree/bindings/soc/rockchip/grf.yaml b/Documentation/devicetree/bindings/soc/rockchip/grf.yaml index 1309bf5ae0cd..9793ea6f0fe6 100644 --- a/Documentation/devicetree/bindings/soc/rockchip/grf.yaml +++ b/Documentation/devicetree/bindings/soc/rockchip/grf.yaml @@ -28,6 +28,8 @@ properties: - rockchip,rk3588-sys-grf - rockchip,rk3588-pcie3-phy-grf - rockchip,rk3588-pcie3-pipe-grf + - rockchip,rk3588-vo-grf + - rockchip,rk3588-vop-grf - rockchip,rv1108-usbgrf - const: syscon - items: diff --git a/Documentation/devicetree/bindings/soc/samsung/exynos-pmu.yaml b/Documentation/devicetree/bindings/soc/samsung/exynos-pmu.yaml index e1d716df5dfa..15fcd8f1d8bc 100644 --- a/Documentation/devicetree/bindings/soc/samsung/exynos-pmu.yaml +++ b/Documentation/devicetree/bindings/soc/samsung/exynos-pmu.yaml @@ -15,6 +15,7 @@ select: compatible: contains: enum: + - google,gs101-pmu - samsung,exynos3250-pmu - samsung,exynos4210-pmu - samsung,exynos4212-pmu @@ -35,6 +36,7 @@ properties: oneOf: - items: - enum: + - google,gs101-pmu - samsung,exynos3250-pmu - samsung,exynos4210-pmu - samsung,exynos4212-pmu @@ -50,6 +52,14 @@ properties: - const: syscon - items: - enum: + - samsung,exynos7885-pmu + - samsung,exynosautov9-pmu + - samsung,exynosautov920-pmu + - tesla,fsd-pmu + - const: samsung,exynos7-pmu + - const: syscon + - items: + - enum: - samsung,exynos3250-pmu - samsung,exynos4210-pmu - samsung,exynos4212-pmu diff --git a/Documentation/devicetree/bindings/soc/samsung/exynos-usi.yaml b/Documentation/devicetree/bindings/soc/samsung/exynos-usi.yaml index a6836904a4f8..8b478d6cdc30 100644 --- a/Documentation/devicetree/bindings/soc/samsung/exynos-usi.yaml +++ b/Documentation/devicetree/bindings/soc/samsung/exynos-usi.yaml @@ -24,7 +24,10 @@ properties: compatible: oneOf: - items: - - const: samsung,exynosautov9-usi + - enum: + - google,gs101-usi + - samsung,exynosautov9-usi + - samsung,exynosautov920-usi - const: samsung,exynos850-usi - enum: - samsung,exynos850-usi @@ -155,7 +158,7 @@ examples: }; hsi2c_0: i2c@13820000 { - compatible = "samsung,exynosautov9-hsi2c"; + compatible = "samsung,exynos850-hsi2c", "samsung,exynosautov9-hsi2c"; reg = <0x13820000 0xc0>; interrupts = <GIC_SPI 227 IRQ_TYPE_LEVEL_HIGH>; #address-cells = <1>; diff --git a/Documentation/devicetree/bindings/soc/samsung/samsung,exynos-sysreg.yaml b/Documentation/devicetree/bindings/soc/samsung/samsung,exynos-sysreg.yaml index 163e912e9cad..1794e3799f21 100644 --- a/Documentation/devicetree/bindings/soc/samsung/samsung,exynos-sysreg.yaml +++ b/Documentation/devicetree/bindings/soc/samsung/samsung,exynos-sysreg.yaml @@ -14,9 +14,14 @@ properties: oneOf: - items: - enum: + - google,gs101-apm-sysreg + - google,gs101-peric0-sysreg + - google,gs101-peric1-sysreg - samsung,exynos3-sysreg - samsung,exynos4-sysreg - samsung,exynos5-sysreg + - samsung,exynosautov920-peric0-sysreg + - samsung,exynosautov920-peric1-sysreg - tesla,fsd-cam-sysreg - tesla,fsd-fsys0-sysreg - tesla,fsd-fsys1-sysreg diff --git a/Documentation/devicetree/bindings/arm/xilinx.yaml b/Documentation/devicetree/bindings/soc/xilinx/xilinx.yaml index f57ed0347894..d4c0fe1fe435 100644 --- a/Documentation/devicetree/bindings/arm/xilinx.yaml +++ b/Documentation/devicetree/bindings/soc/xilinx/xilinx.yaml @@ -1,7 +1,7 @@ # SPDX-License-Identifier: GPL-2.0 %YAML 1.2 --- -$id: http://devicetree.org/schemas/arm/xilinx.yaml# +$id: http://devicetree.org/schemas/soc/xilinx/xilinx.yaml# $schema: http://devicetree.org/meta-schemas/core.yaml# title: Xilinx Zynq Platforms @@ -132,6 +132,11 @@ properties: - const: xlnx,zynqmp-smk-k26 - const: xlnx,zynqmp + - description: AMD MicroBlaze V (QEMU) + items: + - const: qemu,mbv + - const: amd,mbv + additionalProperties: true ... diff --git a/Documentation/devicetree/bindings/sound/mediatek,mt2701-audio.yaml b/Documentation/devicetree/bindings/sound/mediatek,mt2701-audio.yaml new file mode 100644 index 000000000000..45382c4d86aa --- /dev/null +++ b/Documentation/devicetree/bindings/sound/mediatek,mt2701-audio.yaml @@ -0,0 +1,116 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/sound/mediatek,mt2701-audio.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: MediaTek Audio Front End (AFE) PCM controller for mt2701 + +description: + The AFE PCM node must be a subnode of the MediaTek audsys device tree node. + +maintainers: + - Eugen Hristev <eugen.hristev@collabora.com> + +properties: + compatible: + enum: + - mediatek,mt2701-audio + - mediatek,mt7622-audio + + interrupts: + items: + - description: AFE interrupt + - description: ASYS interrupt + + interrupt-names: + items: + - const: afe + - const: asys + + power-domains: + maxItems: 1 + + clocks: + items: + - description: audio infra sys clock + - description: top audio mux 1 + - description: top audio mux 2 + - description: top audio sys a1 clock + - description: top audio sys a2 clock + - description: i2s0 source selection + - description: i2s1 source selection + - description: i2s2 source selection + - description: i2s3 source selection + - description: i2s0 source divider + - description: i2s1 source divider + - description: i2s2 source divider + - description: i2s3 source divider + - description: i2s0 master clock + - description: i2s1 master clock + - description: i2s2 master clock + - description: i2s3 master clock + - description: i2so0 hopping clock + - description: i2so1 hopping clock + - description: i2so2 hopping clock + - description: i2so3 hopping clock + - description: i2si0 hopping clock + - description: i2si1 hopping clock + - description: i2si2 hopping clock + - description: i2si3 hopping clock + - description: asrc0 output clock + - description: asrc1 output clock + - description: asrc2 output clock + - description: asrc3 output clock + - description: audio front end pd clock + - description: audio front end conn pd clock + - description: top audio a1 sys pd + - description: top audio a2 sys pd + - description: audio merge interface pd + + clock-names: + items: + - const: infra_sys_audio_clk + - const: top_audio_mux1_sel + - const: top_audio_mux2_sel + - const: top_audio_a1sys_hp + - const: top_audio_a2sys_hp + - const: i2s0_src_sel + - const: i2s1_src_sel + - const: i2s2_src_sel + - const: i2s3_src_sel + - const: i2s0_src_div + - const: i2s1_src_div + - const: i2s2_src_div + - const: i2s3_src_div + - const: i2s0_mclk_en + - const: i2s1_mclk_en + - const: i2s2_mclk_en + - const: i2s3_mclk_en + - const: i2so0_hop_ck + - const: i2so1_hop_ck + - const: i2so2_hop_ck + - const: i2so3_hop_ck + - const: i2si0_hop_ck + - const: i2si1_hop_ck + - const: i2si2_hop_ck + - const: i2si3_hop_ck + - const: asrc0_out_ck + - const: asrc1_out_ck + - const: asrc2_out_ck + - const: asrc3_out_ck + - const: audio_afe_pd + - const: audio_afe_conn_pd + - const: audio_a1sys_pd + - const: audio_a2sys_pd + - const: audio_mrgif_pd + +required: + - compatible + - interrupts + - interrupt-names + - power-domains + - clocks + - clock-names + +additionalProperties: false diff --git a/Documentation/devicetree/bindings/sound/mt2701-afe-pcm.txt b/Documentation/devicetree/bindings/sound/mt2701-afe-pcm.txt deleted file mode 100644 index f548e6a58240..000000000000 --- a/Documentation/devicetree/bindings/sound/mt2701-afe-pcm.txt +++ /dev/null @@ -1,146 +0,0 @@ -Mediatek AFE PCM controller for mt2701 - -Required properties: -- compatible: should be one of the following. - - "mediatek,mt2701-audio" - - "mediatek,mt7622-audio" -- interrupts: should contain AFE and ASYS interrupts -- interrupt-names: should be "afe" and "asys" -- power-domains: should define the power domain -- clocks: Must contain an entry for each entry in clock-names - See ../clocks/clock-bindings.txt for details -- clock-names: should have these clock names: - "infra_sys_audio_clk", - "top_audio_mux1_sel", - "top_audio_mux2_sel", - "top_audio_a1sys_hp", - "top_audio_a2sys_hp", - "i2s0_src_sel", - "i2s1_src_sel", - "i2s2_src_sel", - "i2s3_src_sel", - "i2s0_src_div", - "i2s1_src_div", - "i2s2_src_div", - "i2s3_src_div", - "i2s0_mclk_en", - "i2s1_mclk_en", - "i2s2_mclk_en", - "i2s3_mclk_en", - "i2so0_hop_ck", - "i2so1_hop_ck", - "i2so2_hop_ck", - "i2so3_hop_ck", - "i2si0_hop_ck", - "i2si1_hop_ck", - "i2si2_hop_ck", - "i2si3_hop_ck", - "asrc0_out_ck", - "asrc1_out_ck", - "asrc2_out_ck", - "asrc3_out_ck", - "audio_afe_pd", - "audio_afe_conn_pd", - "audio_a1sys_pd", - "audio_a2sys_pd", - "audio_mrgif_pd"; -- assigned-clocks: list of input clocks and dividers for the audio system. - See ../clocks/clock-bindings.txt for details. -- assigned-clocks-parents: parent of input clocks of assigned clocks. -- assigned-clock-rates: list of clock frequencies of assigned clocks. - -Must be a subnode of MediaTek audsys device tree node. -See ../arm/mediatek/mediatek,audsys.txt for details about the parent node. - -Example: - - audsys: audio-subsystem@11220000 { - compatible = "mediatek,mt2701-audsys", "syscon"; - ... - - afe: audio-controller { - compatible = "mediatek,mt2701-audio"; - interrupts = <GIC_SPI 104 IRQ_TYPE_LEVEL_LOW>, - <GIC_SPI 132 IRQ_TYPE_LEVEL_LOW>; - interrupt-names = "afe", "asys"; - power-domains = <&scpsys MT2701_POWER_DOMAIN_IFR_MSC>; - - clocks = <&infracfg CLK_INFRA_AUDIO>, - <&topckgen CLK_TOP_AUD_MUX1_SEL>, - <&topckgen CLK_TOP_AUD_MUX2_SEL>, - <&topckgen CLK_TOP_AUD_48K_TIMING>, - <&topckgen CLK_TOP_AUD_44K_TIMING>, - <&topckgen CLK_TOP_AUD_K1_SRC_SEL>, - <&topckgen CLK_TOP_AUD_K2_SRC_SEL>, - <&topckgen CLK_TOP_AUD_K3_SRC_SEL>, - <&topckgen CLK_TOP_AUD_K4_SRC_SEL>, - <&topckgen CLK_TOP_AUD_K1_SRC_DIV>, - <&topckgen CLK_TOP_AUD_K2_SRC_DIV>, - <&topckgen CLK_TOP_AUD_K3_SRC_DIV>, - <&topckgen CLK_TOP_AUD_K4_SRC_DIV>, - <&topckgen CLK_TOP_AUD_I2S1_MCLK>, - <&topckgen CLK_TOP_AUD_I2S2_MCLK>, - <&topckgen CLK_TOP_AUD_I2S3_MCLK>, - <&topckgen CLK_TOP_AUD_I2S4_MCLK>, - <&audsys CLK_AUD_I2SO1>, - <&audsys CLK_AUD_I2SO2>, - <&audsys CLK_AUD_I2SO3>, - <&audsys CLK_AUD_I2SO4>, - <&audsys CLK_AUD_I2SIN1>, - <&audsys CLK_AUD_I2SIN2>, - <&audsys CLK_AUD_I2SIN3>, - <&audsys CLK_AUD_I2SIN4>, - <&audsys CLK_AUD_ASRCO1>, - <&audsys CLK_AUD_ASRCO2>, - <&audsys CLK_AUD_ASRCO3>, - <&audsys CLK_AUD_ASRCO4>, - <&audsys CLK_AUD_AFE>, - <&audsys CLK_AUD_AFE_CONN>, - <&audsys CLK_AUD_A1SYS>, - <&audsys CLK_AUD_A2SYS>, - <&audsys CLK_AUD_AFE_MRGIF>; - - clock-names = "infra_sys_audio_clk", - "top_audio_mux1_sel", - "top_audio_mux2_sel", - "top_audio_a1sys_hp", - "top_audio_a2sys_hp", - "i2s0_src_sel", - "i2s1_src_sel", - "i2s2_src_sel", - "i2s3_src_sel", - "i2s0_src_div", - "i2s1_src_div", - "i2s2_src_div", - "i2s3_src_div", - "i2s0_mclk_en", - "i2s1_mclk_en", - "i2s2_mclk_en", - "i2s3_mclk_en", - "i2so0_hop_ck", - "i2so1_hop_ck", - "i2so2_hop_ck", - "i2so3_hop_ck", - "i2si0_hop_ck", - "i2si1_hop_ck", - "i2si2_hop_ck", - "i2si3_hop_ck", - "asrc0_out_ck", - "asrc1_out_ck", - "asrc2_out_ck", - "asrc3_out_ck", - "audio_afe_pd", - "audio_afe_conn_pd", - "audio_a1sys_pd", - "audio_a2sys_pd", - "audio_mrgif_pd"; - - assigned-clocks = <&topckgen CLK_TOP_AUD_MUX1_SEL>, - <&topckgen CLK_TOP_AUD_MUX2_SEL>, - <&topckgen CLK_TOP_AUD_MUX1_DIV>, - <&topckgen CLK_TOP_AUD_MUX2_DIV>; - assigned-clock-parents = <&topckgen CLK_TOP_AUD1PLL_98M>, - <&topckgen CLK_TOP_AUD2PLL_90M>; - assigned-clock-rates = <0>, <0>, <49152000>, <45158400>; - }; - }; diff --git a/Documentation/devicetree/bindings/sound/samsung-i2s.yaml b/Documentation/devicetree/bindings/sound/samsung-i2s.yaml index 30b3b6e9824b..f45f73b5056d 100644 --- a/Documentation/devicetree/bindings/sound/samsung-i2s.yaml +++ b/Documentation/devicetree/bindings/sound/samsung-i2s.yaml @@ -44,13 +44,18 @@ properties: frequencies supported by Exynos7 I2S and 7.1 channel TDM support for playback and capture TDM (Time division multiplexing) to allow transfer of multiple channel audio data on single data line. - enum: - - samsung,s3c6410-i2s - - samsung,s5pv210-i2s - - samsung,exynos5420-i2s - - samsung,exynos7-i2s - - samsung,exynos7-i2s1 - - tesla,fsd-i2s + oneOf: + - enum: + - samsung,s3c6410-i2s + - samsung,s5pv210-i2s + - samsung,exynos5420-i2s + - samsung,exynos7-i2s + - samsung,exynos7-i2s1 + - tesla,fsd-i2s + - items: + - enum: + - samsung,exynos5433-i2s + - const: samsung,exynos7-i2s '#address-cells': const: 1 diff --git a/Documentation/devicetree/bindings/spi/adi,axi-spi-engine.txt b/Documentation/devicetree/bindings/spi/adi,axi-spi-engine.txt deleted file mode 100644 index 8a18d71e6879..000000000000 --- a/Documentation/devicetree/bindings/spi/adi,axi-spi-engine.txt +++ /dev/null @@ -1,31 +0,0 @@ -Analog Devices AXI SPI Engine controller Device Tree Bindings - -Required properties: -- compatible : Must be "adi,axi-spi-engine-1.00.a"" -- reg : Physical base address and size of the register map. -- interrupts : Property with a value describing the interrupt - number. -- clock-names : List of input clock names - "s_axi_aclk", "spi_clk" -- clocks : Clock phandles and specifiers (See clock bindings for - details on clock-names and clocks). -- #address-cells : Must be <1> -- #size-cells : Must be <0> - -Optional subnodes: - Subnodes are use to represent the SPI slave devices connected to the SPI - master. They follow the generic SPI bindings as outlined in spi-bus.txt. - -Example: - - spi@@44a00000 { - compatible = "adi,axi-spi-engine-1.00.a"; - reg = <0x44a00000 0x1000>; - interrupts = <0 56 4>; - clocks = <&clkc 15 &clkc 15>; - clock-names = "s_axi_aclk", "spi_clk"; - - #address-cells = <1>; - #size-cells = <0>; - - /* SPI devices */ - }; diff --git a/Documentation/devicetree/bindings/spi/adi,axi-spi-engine.yaml b/Documentation/devicetree/bindings/spi/adi,axi-spi-engine.yaml new file mode 100644 index 000000000000..d48faa42d025 --- /dev/null +++ b/Documentation/devicetree/bindings/spi/adi,axi-spi-engine.yaml @@ -0,0 +1,66 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/spi/adi,axi-spi-engine.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Analog Devices AXI SPI Engine Controller + +description: | + The AXI SPI Engine controller is part of the SPI Engine framework[1] and + allows memory mapped access to the SPI Engine control bus. This allows it + to be used as a general purpose software driven SPI controller as well as + some optional advanced acceleration and offloading capabilities. + + [1] https://wiki.analog.com/resources/fpga/peripherals/spi_engine + +maintainers: + - Michael Hennerich <Michael.Hennerich@analog.com> + - Nuno Sá <nuno.sa@analog.com> + +allOf: + - $ref: /schemas/spi/spi-controller.yaml# + +properties: + compatible: + const: adi,axi-spi-engine-1.00.a + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + clocks: + items: + - description: The AXI interconnect clock. + - description: The SPI controller clock. + + clock-names: + items: + - const: s_axi_aclk + - const: spi_clk + +required: + - compatible + - reg + - interrupts + - clocks + - clock-names + +unevaluatedProperties: false + +examples: + - | + spi@44a00000 { + compatible = "adi,axi-spi-engine-1.00.a"; + reg = <0x44a00000 0x1000>; + interrupts = <0 56 4>; + clocks = <&clkc 15>, <&clkc 15>; + clock-names = "s_axi_aclk", "spi_clk"; + + #address-cells = <1>; + #size-cells = <0>; + + /* SPI devices */ + }; diff --git a/Documentation/devicetree/bindings/spi/renesas,rspi.yaml b/Documentation/devicetree/bindings/spi/renesas,rspi.yaml index 4d8ec69214c9..0ef3f8421986 100644 --- a/Documentation/devicetree/bindings/spi/renesas,rspi.yaml +++ b/Documentation/devicetree/bindings/spi/renesas,rspi.yaml @@ -21,7 +21,7 @@ properties: - enum: - renesas,rspi-r7s72100 # RZ/A1H - renesas,rspi-r7s9210 # RZ/A2 - - renesas,r9a07g043-rspi # RZ/G2UL + - renesas,r9a07g043-rspi # RZ/G2UL and RZ/Five - renesas,r9a07g044-rspi # RZ/G2{L,LC} - renesas,r9a07g054-rspi # RZ/V2L - const: renesas,rspi-rz diff --git a/Documentation/devicetree/bindings/spi/snps,dw-apb-ssi.yaml b/Documentation/devicetree/bindings/spi/snps,dw-apb-ssi.yaml index 6348a387a21c..fde3776a558b 100644 --- a/Documentation/devicetree/bindings/spi/snps,dw-apb-ssi.yaml +++ b/Documentation/devicetree/bindings/spi/snps,dw-apb-ssi.yaml @@ -72,8 +72,6 @@ properties: - const: snps,dw-apb-ssi - description: Intel Keem Bay SPI Controller const: intel,keembay-ssi - - description: Intel Thunder Bay SPI Controller - const: intel,thunderbay-ssi - description: Intel Mount Evans Integrated Management Complex SPI Controller const: intel,mountevans-imc-ssi - description: AMD Pensando Elba SoC SPI Controller diff --git a/Documentation/devicetree/bindings/spi/st,stm32-spi.yaml b/Documentation/devicetree/bindings/spi/st,stm32-spi.yaml index ae0f082bd377..4bd9aeb81208 100644 --- a/Documentation/devicetree/bindings/spi/st,stm32-spi.yaml +++ b/Documentation/devicetree/bindings/spi/st,stm32-spi.yaml @@ -23,7 +23,9 @@ properties: compatible: enum: - st,stm32f4-spi + - st,stm32f7-spi - st,stm32h7-spi + - st,stm32mp25-spi reg: maxItems: 1 diff --git a/Documentation/devicetree/bindings/thermal/allwinner,sun8i-a83t-ths.yaml b/Documentation/devicetree/bindings/thermal/allwinner,sun8i-a83t-ths.yaml index fbd4212285e2..9b2272a9ec15 100644 --- a/Documentation/devicetree/bindings/thermal/allwinner,sun8i-a83t-ths.yaml +++ b/Documentation/devicetree/bindings/thermal/allwinner,sun8i-a83t-ths.yaml @@ -16,6 +16,7 @@ properties: - allwinner,sun8i-a83t-ths - allwinner,sun8i-h3-ths - allwinner,sun8i-r40-ths + - allwinner,sun20i-d1-ths - allwinner,sun50i-a64-ths - allwinner,sun50i-a100-ths - allwinner,sun50i-h5-ths @@ -61,6 +62,7 @@ allOf: compatible: contains: enum: + - allwinner,sun20i-d1-ths - allwinner,sun50i-a100-ths - allwinner,sun50i-h6-ths @@ -84,7 +86,9 @@ allOf: properties: compatible: contains: - const: allwinner,sun8i-h3-ths + enum: + - allwinner,sun8i-h3-ths + - allwinner,sun20i-d1-ths then: properties: @@ -103,6 +107,7 @@ allOf: enum: - allwinner,sun8i-h3-ths - allwinner,sun8i-r40-ths + - allwinner,sun20i-d1-ths - allwinner,sun50i-a64-ths - allwinner,sun50i-a100-ths - allwinner,sun50i-h5-ths diff --git a/Documentation/devicetree/bindings/thermal/loongson,ls2k-thermal.yaml b/Documentation/devicetree/bindings/thermal/loongson,ls2k-thermal.yaml index 7538469997f9..b634f57cd011 100644 --- a/Documentation/devicetree/bindings/thermal/loongson,ls2k-thermal.yaml +++ b/Documentation/devicetree/bindings/thermal/loongson,ls2k-thermal.yaml @@ -10,6 +10,9 @@ maintainers: - zhanghongchen <zhanghongchen@loongson.cn> - Yinbo Zhu <zhuyinbo@loongson.cn> +allOf: + - $ref: /schemas/thermal/thermal-sensor.yaml# + properties: compatible: oneOf: @@ -26,12 +29,16 @@ properties: interrupts: maxItems: 1 + '#thermal-sensor-cells': + const: 1 + required: - compatible - reg - interrupts + - '#thermal-sensor-cells' -additionalProperties: false +unevaluatedProperties: false examples: - | @@ -41,4 +48,5 @@ examples: reg = <0x1fe01500 0x30>; interrupt-parent = <&liointc0>; interrupts = <7 IRQ_TYPE_LEVEL_LOW>; + #thermal-sensor-cells = <1>; }; diff --git a/Documentation/devicetree/bindings/thermal/mediatek,thermal.yaml b/Documentation/devicetree/bindings/thermal/mediatek,thermal.yaml new file mode 100644 index 000000000000..d96a2e32bd8f --- /dev/null +++ b/Documentation/devicetree/bindings/thermal/mediatek,thermal.yaml @@ -0,0 +1,99 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/thermal/mediatek,thermal.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Mediatek thermal controller for on-SoC temperatures + +maintainers: + - Sascha Hauer <s.hauer@pengutronix.de> + +description: + This device does not have its own ADC, instead it directly controls the AUXADC + via AHB bus accesses. For this reason it needs phandles to the AUXADC. Also it + controls a mux in the apmixedsys register space via AHB bus accesses, so a + phandle to the APMIXEDSYS is also needed. + +allOf: + - $ref: thermal-sensor.yaml# + +properties: + compatible: + enum: + - mediatek,mt2701-thermal + - mediatek,mt2712-thermal + - mediatek,mt7622-thermal + - mediatek,mt7981-thermal + - mediatek,mt7986-thermal + - mediatek,mt8173-thermal + - mediatek,mt8183-thermal + - mediatek,mt8365-thermal + - mediatek,mt8516-thermal + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + clocks: + items: + - description: Main clock needed for register access + - description: The AUXADC clock + + clock-names: + items: + - const: therm + - const: auxadc + + mediatek,auxadc: + $ref: /schemas/types.yaml#/definitions/phandle + description: A phandle to the AUXADC which the thermal controller uses + + mediatek,apmixedsys: + $ref: /schemas/types.yaml#/definitions/phandle + description: A phandle to the APMIXEDSYS controller + + resets: + description: Reset controller controlling the thermal controller + + nvmem-cells: + items: + - description: + NVMEM cell with EEPROMA phandle to the calibration data provided by an + NVMEM device. If unspecified default values shall be used. + + nvmem-cell-names: + items: + - const: calibration-data + +required: + - reg + - interrupts + - clocks + - clock-names + - mediatek,auxadc + - mediatek,apmixedsys + +unevaluatedProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/irq.h> + #include <dt-bindings/clock/mt8173-clk.h> + #include <dt-bindings/reset/mt8173-resets.h> + + thermal@1100b000 { + compatible = "mediatek,mt8173-thermal"; + reg = <0x1100b000 0x1000>; + interrupts = <0 70 IRQ_TYPE_LEVEL_LOW>; + clocks = <&pericfg CLK_PERI_THERM>, <&pericfg CLK_PERI_AUXADC>; + clock-names = "therm", "auxadc"; + resets = <&pericfg MT8173_PERI_THERM_SW_RST>; + mediatek,auxadc = <&auxadc>; + mediatek,apmixedsys = <&apmixedsys>; + nvmem-cells = <&thermal_calibration_data>; + nvmem-cell-names = "calibration-data"; + #thermal-sensor-cells = <1>; + }; diff --git a/Documentation/devicetree/bindings/thermal/mediatek-thermal.txt b/Documentation/devicetree/bindings/thermal/mediatek-thermal.txt deleted file mode 100644 index ac39c7156fde..000000000000 --- a/Documentation/devicetree/bindings/thermal/mediatek-thermal.txt +++ /dev/null @@ -1,52 +0,0 @@ -* Mediatek Thermal - -This describes the device tree binding for the Mediatek thermal controller -which measures the on-SoC temperatures. This device does not have its own ADC, -instead it directly controls the AUXADC via AHB bus accesses. For this reason -this device needs phandles to the AUXADC. Also it controls a mux in the -apmixedsys register space via AHB bus accesses, so a phandle to the APMIXEDSYS -is also needed. - -Required properties: -- compatible: - - "mediatek,mt8173-thermal" : For MT8173 family of SoCs - - "mediatek,mt2701-thermal" : For MT2701 family of SoCs - - "mediatek,mt2712-thermal" : For MT2712 family of SoCs - - "mediatek,mt7622-thermal" : For MT7622 SoC - - "mediatek,mt7981-thermal", "mediatek,mt7986-thermal" : For MT7981 SoC - - "mediatek,mt7986-thermal" : For MT7986 SoC - - "mediatek,mt8183-thermal" : For MT8183 family of SoCs - - "mediatek,mt8365-thermal" : For MT8365 family of SoCs - - "mediatek,mt8516-thermal", "mediatek,mt2701-thermal : For MT8516 family of SoCs -- reg: Address range of the thermal controller -- interrupts: IRQ for the thermal controller -- clocks, clock-names: Clocks needed for the thermal controller. required - clocks are: - "therm": Main clock needed for register access - "auxadc": The AUXADC clock -- mediatek,auxadc: A phandle to the AUXADC which the thermal controller uses -- mediatek,apmixedsys: A phandle to the APMIXEDSYS controller. -- #thermal-sensor-cells : Should be 0. See Documentation/devicetree/bindings/thermal/thermal-sensor.yaml for a description. - -Optional properties: -- resets: Reference to the reset controller controlling the thermal controller. -- nvmem-cells: A phandle to the calibration data provided by a nvmem device. If - unspecified default values shall be used. -- nvmem-cell-names: Should be "calibration-data" - -Example: - - thermal: thermal@1100b000 { - #thermal-sensor-cells = <1>; - compatible = "mediatek,mt8173-thermal"; - reg = <0 0x1100b000 0 0x1000>; - interrupts = <0 70 IRQ_TYPE_LEVEL_LOW>; - clocks = <&pericfg CLK_PERI_THERM>, <&pericfg CLK_PERI_AUXADC>; - clock-names = "therm", "auxadc"; - resets = <&pericfg MT8173_PERI_THERM_SW_RST>; - reset-names = "therm"; - mediatek,auxadc = <&auxadc>; - mediatek,apmixedsys = <&apmixedsys>; - nvmem-cells = <&thermal_calibration_data>; - nvmem-cell-names = "calibration-data"; - }; diff --git a/Documentation/devicetree/bindings/thermal/qcom-spmi-adc-tm-hc.yaml b/Documentation/devicetree/bindings/thermal/qcom-spmi-adc-tm-hc.yaml index 01253d58bf9f..7541e27704ca 100644 --- a/Documentation/devicetree/bindings/thermal/qcom-spmi-adc-tm-hc.yaml +++ b/Documentation/devicetree/bindings/thermal/qcom-spmi-adc-tm-hc.yaml @@ -114,12 +114,14 @@ examples: - | #include <dt-bindings/iio/qcom,spmi-vadc.h> #include <dt-bindings/interrupt-controller/irq.h> - spmi_bus { + + pmic { #address-cells = <1>; #size-cells = <0>; + pm8998_adc: adc@3100 { - reg = <0x3100>; compatible = "qcom,spmi-adc-rev2"; + reg = <0x3100>; #address-cells = <1>; #size-cells = <0>; #io-channel-cells = <1>; @@ -130,7 +132,7 @@ examples: }; }; - pm8998_adc_tm: adc-tm@3400 { + adc-tm@3400 { compatible = "qcom,spmi-adc-tm-hc"; reg = <0x3400>; interrupts = <0x2 0x34 0x0 IRQ_TYPE_EDGE_RISING>; diff --git a/Documentation/devicetree/bindings/thermal/qcom-spmi-adc-tm5.yaml b/Documentation/devicetree/bindings/thermal/qcom-spmi-adc-tm5.yaml index 3c81def03c84..d9d2657287cb 100644 --- a/Documentation/devicetree/bindings/thermal/qcom-spmi-adc-tm5.yaml +++ b/Documentation/devicetree/bindings/thermal/qcom-spmi-adc-tm5.yaml @@ -167,12 +167,14 @@ examples: - | #include <dt-bindings/iio/qcom,spmi-vadc.h> #include <dt-bindings/interrupt-controller/irq.h> - spmi_bus { + + pmic { #address-cells = <1>; #size-cells = <0>; + pm8150b_adc: adc@3100 { - reg = <0x3100>; compatible = "qcom,spmi-adc5"; + reg = <0x3100>; #address-cells = <1>; #size-cells = <0>; #io-channel-cells = <1>; @@ -186,7 +188,7 @@ examples: }; }; - pm8150b_adc_tm: adc-tm@3500 { + adc-tm@3500 { compatible = "qcom,spmi-adc-tm5"; reg = <0x3500>; interrupts = <0x2 0x35 0x0 IRQ_TYPE_EDGE_RISING>; @@ -207,12 +209,14 @@ examples: #include <dt-bindings/iio/qcom,spmi-adc7-pmk8350.h> #include <dt-bindings/iio/qcom,spmi-adc7-pm8350.h> #include <dt-bindings/interrupt-controller/irq.h> - spmi_bus { + + pmic { #address-cells = <1>; #size-cells = <0>; + pmk8350_vadc: adc@3100 { - reg = <0x3100>; compatible = "qcom,spmi-adc7"; + reg = <0x3100>; #address-cells = <1>; #size-cells = <0>; #io-channel-cells = <1>; @@ -233,7 +237,7 @@ examples: }; }; - pmk8350_adc_tm: adc-tm@3400 { + adc-tm@3400 { compatible = "qcom,spmi-adc-tm5-gen2"; reg = <0x3400>; interrupts = <0x0 0x34 0x0 IRQ_TYPE_EDGE_RISING>; diff --git a/Documentation/devicetree/bindings/thermal/qcom-tsens.yaml b/Documentation/devicetree/bindings/thermal/qcom-tsens.yaml index 437b74732886..99d9c526c0b6 100644 --- a/Documentation/devicetree/bindings/thermal/qcom-tsens.yaml +++ b/Documentation/devicetree/bindings/thermal/qcom-tsens.yaml @@ -66,6 +66,7 @@ properties: - qcom,sm8350-tsens - qcom,sm8450-tsens - qcom,sm8550-tsens + - qcom,sm8650-tsens - const: qcom,tsens-v2 - description: v2 of TSENS with combined interrupt diff --git a/Documentation/devicetree/bindings/thermal/thermal-zones.yaml b/Documentation/devicetree/bindings/thermal/thermal-zones.yaml index 4a8dabc48170..dbd52620d293 100644 --- a/Documentation/devicetree/bindings/thermal/thermal-zones.yaml +++ b/Documentation/devicetree/bindings/thermal/thermal-zones.yaml @@ -75,6 +75,22 @@ patternProperties: framework and assumes that the thermal sensors in this zone support interrupts. + critical-action: + $ref: /schemas/types.yaml#/definitions/string + description: | + The action the OS should perform after the critical temperature is reached. + By default the system will shutdown as a safe action to prevent damage + to the hardware, if the property is not set. + The shutdown action should be always the default and preferred one. + Choose 'reboot' with care, as the hardware may be in thermal stress, + thus leading to infinite reboots that may cause damage to the hardware. + Make sure the firmware/bootloader will act as the last resort and take + over the thermal control. + + enum: + - shutdown + - reboot + thermal-sensors: $ref: /schemas/types.yaml#/definitions/phandle-array maxItems: 1 diff --git a/Documentation/devicetree/bindings/timer/sifive,clint.yaml b/Documentation/devicetree/bindings/timer/sifive,clint.yaml index e8be6c470364..4b6c20fc8194 100644 --- a/Documentation/devicetree/bindings/timer/sifive,clint.yaml +++ b/Documentation/devicetree/bindings/timer/sifive,clint.yaml @@ -38,6 +38,7 @@ properties: - enum: - allwinner,sun20i-d1-clint - sophgo,cv1800b-clint + - sophgo,cv1812h-clint - thead,th1520-clint - const: thead,c900-clint - items: diff --git a/Documentation/devicetree/bindings/ufs/qcom,ufs.yaml b/Documentation/devicetree/bindings/ufs/qcom,ufs.yaml index 2cf3d016db42..10c146424baa 100644 --- a/Documentation/devicetree/bindings/ufs/qcom,ufs.yaml +++ b/Documentation/devicetree/bindings/ufs/qcom,ufs.yaml @@ -27,6 +27,7 @@ properties: - qcom,msm8996-ufshc - qcom,msm8998-ufshc - qcom,sa8775p-ufshc + - qcom,sc7280-ufshc - qcom,sc8280xp-ufshc - qcom,sdm845-ufshc - qcom,sm6115-ufshc @@ -118,6 +119,7 @@ allOf: enum: - qcom,msm8998-ufshc - qcom,sa8775p-ufshc + - qcom,sc7280-ufshc - qcom,sc8280xp-ufshc - qcom,sm8250-ufshc - qcom,sm8350-ufshc diff --git a/Documentation/devicetree/bindings/ufs/ufs-common.yaml b/Documentation/devicetree/bindings/ufs/ufs-common.yaml index 985ea8f64de8..31fe7f30ff5b 100644 --- a/Documentation/devicetree/bindings/ufs/ufs-common.yaml +++ b/Documentation/devicetree/bindings/ufs/ufs-common.yaml @@ -87,6 +87,8 @@ properties: description: Specifies max. load that can be drawn from VCCQ2 supply. + msi-parent: true + dependencies: freq-table-hz: [ clocks ] operating-points-v2: [ clocks, clock-names ] diff --git a/Documentation/devicetree/bindings/vendor-prefixes.yaml b/Documentation/devicetree/bindings/vendor-prefixes.yaml index 08ba7aad0d76..100fbf9826dc 100644 --- a/Documentation/devicetree/bindings/vendor-prefixes.yaml +++ b/Documentation/devicetree/bindings/vendor-prefixes.yaml @@ -294,6 +294,8 @@ patternProperties: description: CompuLab Ltd. "^congatec,.*": description: congatec GmbH + "^coolpi,.*": + description: cool-pi.com "^coreriver,.*": description: CORERIVER Semiconductor Co.,Ltd. "^corpro,.*": @@ -352,6 +354,8 @@ patternProperties: description: Digi International Inc. "^digilent,.*": description: Diglent, Inc. + "^dimonoff,.*": + description: Dimonoff inc. "^diodes,.*": description: Diodes, Inc. "^dioo,.*": @@ -599,6 +603,8 @@ patternProperties: description: Hewlett Packard Enterprise "^hsg,.*": description: HannStar Display Co. + "^htc,.*": + description: HTC Corporation "^huawei,.*": description: Huawei Technologies Co., Ltd. "^hugsun,.*": @@ -1181,6 +1187,8 @@ patternProperties: description: Shenzhen Roofull Technology Co, Ltd "^roseapplepi,.*": description: RoseapplePi.org + "^rve,.*": + description: Recharge Véhicule Électrique (RVE) inc. "^saef,.*": description: Saef Technology Limited "^samsung,.*": @@ -1436,6 +1444,8 @@ patternProperties: description: TPO "^tq,.*": description: TQ-Systems GmbH + "^transpeed,.*": + description: Transpeed "^traverse,.*": description: Traverse Technologies Australia Pty Ltd "^tronfy,.*": diff --git a/Documentation/devicetree/bindings/watchdog/samsung-wdt.yaml b/Documentation/devicetree/bindings/watchdog/samsung-wdt.yaml index 8fb6656ba0c2..77a5ddd0426e 100644 --- a/Documentation/devicetree/bindings/watchdog/samsung-wdt.yaml +++ b/Documentation/devicetree/bindings/watchdog/samsung-wdt.yaml @@ -16,14 +16,20 @@ description: |+ properties: compatible: - enum: - - samsung,s3c2410-wdt # for S3C2410 - - samsung,s3c6410-wdt # for S3C6410, S5PV210 and Exynos4 - - samsung,exynos5250-wdt # for Exynos5250 - - samsung,exynos5420-wdt # for Exynos5420 - - samsung,exynos7-wdt # for Exynos7 - - samsung,exynos850-wdt # for Exynos850 - - samsung,exynosautov9-wdt # for Exynosautov9 + oneOf: + - enum: + - google,gs101-wdt # for Google gs101 + - samsung,s3c2410-wdt # for S3C2410 + - samsung,s3c6410-wdt # for S3C6410, S5PV210 and Exynos4 + - samsung,exynos5250-wdt # for Exynos5250 + - samsung,exynos5420-wdt # for Exynos5420 + - samsung,exynos7-wdt # for Exynos7 + - samsung,exynos850-wdt # for Exynos850 + - samsung,exynosautov9-wdt # for Exynosautov9 + - items: + - enum: + - tesla,fsd-wdt + - const: samsung,exynos7-wdt reg: maxItems: 1 @@ -42,13 +48,14 @@ properties: samsung,cluster-index: $ref: /schemas/types.yaml#/definitions/uint32 description: - Index of CPU cluster on which watchdog is running (in case of Exynos850) + Index of CPU cluster on which watchdog is running (in case of Exynos850 + or Google gs101). samsung,syscon-phandle: $ref: /schemas/types.yaml#/definitions/phandle description: Phandle to the PMU system controller node (in case of Exynos5250, - Exynos5420, Exynos7 and Exynos850). + Exynos5420, Exynos7, Exynos850 and gs101). required: - compatible @@ -64,6 +71,7 @@ allOf: compatible: contains: enum: + - google,gs101-wdt - samsung,exynos5250-wdt - samsung,exynos5420-wdt - samsung,exynos7-wdt @@ -77,6 +85,7 @@ allOf: compatible: contains: enum: + - google,gs101-wdt - samsung,exynos850-wdt - samsung,exynosautov9-wdt then: diff --git a/Documentation/doc-guide/sphinx.rst b/Documentation/doc-guide/sphinx.rst index cd8ad7904491..3d125fb4139d 100644 --- a/Documentation/doc-guide/sphinx.rst +++ b/Documentation/doc-guide/sphinx.rst @@ -28,7 +28,7 @@ Sphinx Install ============== The ReST markups currently used by the Documentation/ files are meant to be -built with ``Sphinx`` version 1.7 or higher. +built with ``Sphinx`` version 2.4.4 or higher. There's a script that checks for the Sphinx requirements. Please see :ref:`sphinx-pre-install` for further details. @@ -435,6 +435,15 @@ path. For information on cross-referencing to kernel-doc functions or types, see Documentation/doc-guide/kernel-doc.rst. +Referencing commits +~~~~~~~~~~~~~~~~~~~ + +References to git commits are automatically hyperlinked given that they are +written in one of these formats:: + + commit 72bf4f1767f0 + commit 72bf4f1767f0 ("net: do not leave an empty skb in write queue") + .. _sphinx_kfigure: Figures & Images diff --git a/Documentation/driver-api/crypto/iaa/iaa-crypto.rst b/Documentation/driver-api/crypto/iaa/iaa-crypto.rst new file mode 100644 index 000000000000..de587cf9cbed --- /dev/null +++ b/Documentation/driver-api/crypto/iaa/iaa-crypto.rst @@ -0,0 +1,824 @@ +.. SPDX-License-Identifier: GPL-2.0 + +========================================= +IAA Compression Accelerator Crypto Driver +========================================= + +Tom Zanussi <tom.zanussi@linux.intel.com> + +The IAA crypto driver supports compression/decompression compatible +with the DEFLATE compression standard described in RFC 1951, which is +the compression/decompression algorithm exported by this module. + +The IAA hardware spec can be found here: + + https://cdrdv2.intel.com/v1/dl/getContent/721858 + +The iaa_crypto driver is designed to work as a layer underneath +higher-level compression devices such as zswap. + +Users can select IAA compress/decompress acceleration by specifying +one of the supported IAA compression algorithms in whatever facility +allows compression algorithms to be selected. + +For example, a zswap device can select the IAA 'fixed' mode +represented by selecting the 'deflate-iaa' crypto compression +algorithm:: + + # echo deflate-iaa > /sys/module/zswap/parameters/compressor + +This will tell zswap to use the IAA 'fixed' compression mode for all +compresses and decompresses. + +Currently, there is only one compression modes available, 'fixed' +mode. + +The 'fixed' compression mode implements the compression scheme +specified by RFC 1951 and is given the crypto algorithm name +'deflate-iaa'. (Because the IAA hardware has a 4k history-window +limitation, only buffers <= 4k, or that have been compressed using a +<= 4k history window, are technically compliant with the deflate spec, +which allows for a window of up to 32k. Because of this limitation, +the IAA fixed mode deflate algorithm is given its own algorithm name +rather than simply 'deflate'). + + +Config options and other setup +============================== + +The IAA crypto driver is available via menuconfig using the following +path:: + + Cryptographic API -> Hardware crypto devices -> Support for Intel(R) IAA Compression Accelerator + +In the configuration file the option called CONFIG_CRYPTO_DEV_IAA_CRYPTO. + +The IAA crypto driver also supports statistics, which are available +via menuconfig using the following path:: + + Cryptographic API -> Hardware crypto devices -> Support for Intel(R) IAA Compression -> Enable Intel(R) IAA Compression Accelerator Statistics + +In the configuration file the option called CONFIG_CRYPTO_DEV_IAA_CRYPTO_STATS. + +The following config options should also be enabled:: + + CONFIG_IRQ_REMAP=y + CONFIG_INTEL_IOMMU=y + CONFIG_INTEL_IOMMU_SVM=y + CONFIG_PCI_ATS=y + CONFIG_PCI_PRI=y + CONFIG_PCI_PASID=y + CONFIG_INTEL_IDXD=m + CONFIG_INTEL_IDXD_SVM=y + +IAA is one of the first Intel accelerator IPs that can work in +conjunction with the Intel IOMMU. There are multiple modes that exist +for testing. Based on IOMMU configuration, there are 3 modes:: + + - Scalable + - Legacy + - No IOMMU + + +Scalable mode +------------- + +Scalable mode supports Shared Virtual Memory (SVM or SVA). It is +entered when using the kernel boot commandline:: + + intel_iommu=on,sm_on + +with VT-d turned on in BIOS. + +With scalable mode, both shared and dedicated workqueues are available +for use. + +For scalable mode, the following BIOS settings should be enabled:: + + Socket Configuration > IIO Configuration > Intel VT for Directed I/O (VT-d) > Intel VT for Directed I/O + + Socket Configuration > IIO Configuration > PCIe ENQCMD > ENQCMDS + + +Legacy mode +----------- + +Legacy mode is entered when using the kernel boot commandline:: + + intel_iommu=off + +or VT-d is not turned on in BIOS. + +If you have booted into Linux and not sure if VT-d is on, do a "dmesg +| grep -i dmar". If you don't see a number of DMAR devices enumerated, +most likely VT-d is not on. + +With legacy mode, only dedicated workqueues are available for use. + + +No IOMMU mode +------------- + +No IOMMU mode is entered when using the kernel boot commandline:: + + iommu=off. + +With no IOMMU mode, only dedicated workqueues are available for use. + + +Usage +===== + +accel-config +------------ + +When loaded, the iaa_crypto driver automatically creates a default +configuration and enables it, and assigns default driver attributes. +If a different configuration or set of driver attributes is required, +the user must first disable the IAA devices and workqueues, reset the +configuration, and then re-register the deflate-iaa algorithm with the +crypto subsystem by removing and reinserting the iaa_crypto module. + +The :ref:`iaa_disable_script` in the 'Use Cases' +section below can be used to disable the default configuration. + +See :ref:`iaa_default_config` below for details of the default +configuration. + +More likely than not, however, and because of the complexity and +configurability of the accelerator devices, the user will want to +configure the device and manually enable the desired devices and +workqueues. + +The userspace tool to help doing that is called accel-config. Using +accel-config to configure device or loading a previously saved config +is highly recommended. The device can be controlled via sysfs +directly but comes with the warning that you should do this ONLY if +you know exactly what you are doing. The following sections will not +cover the sysfs interface but assumes you will be using accel-config. + +The :ref:`iaa_sysfs_config` section in the appendix below can be +consulted for the sysfs interface details if interested. + +The accel-config tool along with instructions for building it can be +found here: + + https://github.com/intel/idxd-config/#readme + +Typical usage +------------- + +In order for the iaa_crypto module to actually do any +compression/decompression work on behalf of a facility, one or more +IAA workqueues need to be bound to the iaa_crypto driver. + +For instance, here's an example of configuring an IAA workqueue and +binding it to the iaa_crypto driver (note that device names are +specified as 'iax' rather than 'iaa' - this is because upstream still +has the old 'iax' device naming in place) :: + + # configure wq1.0 + + accel-config config-wq --group-id=0 --mode=dedicated --type=kernel --name="iaa_crypto" --device_name="crypto" iax1/wq1.0 + + # enable IAA device iax1 + + accel-config enable-device iax1 + + # enable wq1.0 on IAX device iax1 + + accel-config enable-wq iax1/wq1.0 + +Whenever a new workqueue is bound to or unbound from the iaa_crypto +driver, the available workqueues are 'rebalanced' such that work +submitted from a particular CPU is given to the most appropriate +workqueue available. Current best practice is to configure and bind +at least one workqueue for each IAA device, but as long as there is at +least one workqueue configured and bound to any IAA device in the +system, the iaa_crypto driver will work, albeit most likely not as +efficiently. + +The IAA crypto algorigthms is operational and compression and +decompression operations are fully enabled following the successful +binding of the first IAA workqueue to the iaa_crypto driver. + +Similarly, the IAA crypto algorithm is not operational and compression +and decompression operations are disabled following the unbinding of +the last IAA worqueue to the iaa_crypto driver. + +As a result, the IAA crypto algorithms and thus the IAA hardware are +only available when one or more workques are bound to the iaa_crypto +driver. + +When there are no IAA workqueues bound to the driver, the IAA crypto +algorithms can be unregistered by removing the module. + + +Driver attributes +----------------- + +There are a couple user-configurable driver attributes that can be +used to configure various modes of operation. They're listed below, +along with their default values. To set any of these attributes, echo +the appropriate values to the attribute file located under +/sys/bus/dsa/drivers/crypto/ + +The attribute settings at the time the IAA algorithms are registered +are captured in each algorithm's crypto_ctx and used for all compresses +and decompresses when using that algorithm. + +The available attributes are: + + - verify_compress + + Toggle compression verification. If set, each compress will be + internally decompressed and the contents verified, returning error + codes if unsuccessful. This can be toggled with 0/1:: + + echo 0 > /sys/bus/dsa/drivers/crypto/verify_compress + + The default setting is '1' - verify all compresses. + + - sync_mode + + Select mode to be used to wait for completion of each compresses + and decompress operation. + + The crypto async interface support implemented by iaa_crypto + provides an implementation that satisfies the interface but does + so in a synchronous manner - it fills and submits the IDXD + descriptor and then loops around waiting for it to complete before + returning. This isn't a problem at the moment, since all existing + callers (e.g. zswap) wrap any asynchronous callees in a + synchronous wrapper anyway. + + The iaa_crypto driver does however provide true asynchronous + support for callers that can make use of it. In this mode, it + fills and submits the IDXD descriptor, then returns immediately + with -EINPROGRESS. The caller can then either poll for completion + itself, which requires specific code in the caller which currently + nothing in the upstream kernel implements, or go to sleep and wait + for an interrupt signaling completion. This latter mode is + supported by current users in the kernel such as zswap via + synchronous wrappers. Although it is supported this mode is + significantly slower than the synchronous mode that does the + polling in the iaa_crypto driver previously mentioned. + + This mode can be enabled by writing 'async_irq' to the sync_mode + iaa_crypto driver attribute:: + + echo async_irq > /sys/bus/dsa/drivers/crypto/sync_mode + + Async mode without interrupts (caller must poll) can be enabled by + writing 'async' to it:: + + echo async > /sys/bus/dsa/drivers/crypto/sync_mode + + The mode that does the polling in the iaa_crypto driver can be + enabled by writing 'sync' to it:: + + echo sync > /sys/bus/dsa/drivers/crypto/sync_mode + + The default mode is 'sync'. + +.. _iaa_default_config: + +IAA Default Configuration +------------------------- + +When the iaa_crypto driver is loaded, each IAA device has a single +work queue configured for it, with the following attributes:: + + mode "dedicated" + threshold 0 + size Total WQ Size from WQCAP + priority 10 + type IDXD_WQT_KERNEL + group 0 + name "iaa_crypto" + driver_name "crypto" + +The devices and workqueues are also enabled and therefore the driver +is ready to be used without any additional configuration. + +The default driver attributes in effect when the driver is loaded are:: + + sync_mode "sync" + verify_compress 1 + +In order to change either the device/work queue or driver attributes, +the enabled devices and workqueues must first be disabled. In order +to have the new configuration applied to the deflate-iaa crypto +algorithm, it needs to be re-registered by removing and reinserting +the iaa_crypto module. The :ref:`iaa_disable_script` in the 'Use +Cases' section below can be used to disable the default configuration. + +Statistics +========== + +If the optional debugfs statistics support is enabled, the IAA crypto +driver will generate statistics which can be accessed in debugfs at:: + + # ls -al /sys/kernel/debug/iaa-crypto/ + total 0 + drwxr-xr-x 2 root root 0 Mar 3 09:35 . + drwx------ 47 root root 0 Mar 3 09:35 .. + -rw-r--r-- 1 root root 0 Mar 3 09:35 max_acomp_delay_ns + -rw-r--r-- 1 root root 0 Mar 3 09:35 max_adecomp_delay_ns + -rw-r--r-- 1 root root 0 Mar 3 09:35 max_comp_delay_ns + -rw-r--r-- 1 root root 0 Mar 3 09:35 max_decomp_delay_ns + -rw-r--r-- 1 root root 0 Mar 3 09:35 stats_reset + -rw-r--r-- 1 root root 0 Mar 3 09:35 total_comp_bytes_out + -rw-r--r-- 1 root root 0 Mar 3 09:35 total_comp_calls + -rw-r--r-- 1 root root 0 Mar 3 09:35 total_decomp_bytes_in + -rw-r--r-- 1 root root 0 Mar 3 09:35 total_decomp_calls + -rw-r--r-- 1 root root 0 Mar 3 09:35 wq_stats + +Most of the above statisticss are self-explanatory. The wq_stats file +shows per-wq stats, a set for each iaa device and wq in addition to +some global stats:: + + # cat wq_stats + global stats: + total_comp_calls: 100 + total_decomp_calls: 100 + total_comp_bytes_out: 22800 + total_decomp_bytes_in: 22800 + total_completion_einval_errors: 0 + total_completion_timeout_errors: 0 + total_completion_comp_buf_overflow_errors: 0 + + iaa device: + id: 1 + n_wqs: 1 + comp_calls: 0 + comp_bytes: 0 + decomp_calls: 0 + decomp_bytes: 0 + wqs: + name: iaa_crypto + comp_calls: 0 + comp_bytes: 0 + decomp_calls: 0 + decomp_bytes: 0 + + iaa device: + id: 3 + n_wqs: 1 + comp_calls: 0 + comp_bytes: 0 + decomp_calls: 0 + decomp_bytes: 0 + wqs: + name: iaa_crypto + comp_calls: 0 + comp_bytes: 0 + decomp_calls: 0 + decomp_bytes: 0 + + iaa device: + id: 5 + n_wqs: 1 + comp_calls: 100 + comp_bytes: 22800 + decomp_calls: 100 + decomp_bytes: 22800 + wqs: + name: iaa_crypto + comp_calls: 100 + comp_bytes: 22800 + decomp_calls: 100 + decomp_bytes: 22800 + +Writing 0 to 'stats_reset' resets all the stats, including the +per-device and per-wq stats:: + + # echo 0 > stats_reset + # cat wq_stats + global stats: + total_comp_calls: 0 + total_decomp_calls: 0 + total_comp_bytes_out: 0 + total_decomp_bytes_in: 0 + total_completion_einval_errors: 0 + total_completion_timeout_errors: 0 + total_completion_comp_buf_overflow_errors: 0 + ... + + +Use cases +========= + +Simple zswap test +----------------- + +For this example, the kernel should be configured according to the +dedicated mode options described above, and zswap should be enabled as +well:: + + CONFIG_ZSWAP=y + +This is a simple test that uses iaa_compress as the compressor for a +swap (zswap) device. It sets up the zswap device and then uses the +memory_memadvise program listed below to forcibly swap out and in a +specified number of pages, demonstrating both compress and decompress. + +The zswap test expects the work queues for each IAA device on the +system to be configured properly as a kernel workqueue with a +workqueue driver_name of "crypto". + +The first step is to make sure the iaa_crypto module is loaded:: + + modprobe iaa_crypto + +If the IAA devices and workqueues haven't previously been disabled and +reconfigured, then the default configuration should be in place and no +further IAA configuration is necessary. See :ref:`iaa_default_config` +below for details of the default configuration. + +If the default configuration is in place, you should see the iaa +devices and wq0s enabled:: + + # cat /sys/bus/dsa/devices/iax1/state + enabled + # cat /sys/bus/dsa/devices/iax1/wq1.0/state + enabled + +To demonstrate that the following steps work as expected, these +commands can be used to enable debug output:: + + # echo -n 'module iaa_crypto +p' > /sys/kernel/debug/dynamic_debug/control + # echo -n 'module idxd +p' > /sys/kernel/debug/dynamic_debug/control + +Use the following commands to enable zswap:: + + # echo 0 > /sys/module/zswap/parameters/enabled + # echo 50 > /sys/module/zswap/parameters/max_pool_percent + # echo deflate-iaa > /sys/module/zswap/parameters/compressor + # echo zsmalloc > /sys/module/zswap/parameters/zpool + # echo 1 > /sys/module/zswap/parameters/enabled + # echo 0 > /sys/module/zswap/parameters/same_filled_pages_enabled + # echo 100 > /proc/sys/vm/swappiness + # echo never > /sys/kernel/mm/transparent_hugepage/enabled + # echo 1 > /proc/sys/vm/overcommit_memory + +Now you can now run the zswap workload you want to measure. For +example, using the memory_memadvise code below, the following command +will swap in and out 100 pages:: + + ./memory_madvise 100 + + Allocating 100 pages to swap in/out + Swapping out 100 pages + Swapping in 100 pages + Swapped out and in 100 pages + +You should see something like the following in the dmesg output:: + + [ 404.202972] idxd 0000:e7:02.0: iaa_comp_acompress: dma_map_sg, src_addr 223925c000, nr_sgs 1, req->src 00000000ee7cb5e6, req->slen 4096, sg_dma_len(sg) 4096 + [ 404.202973] idxd 0000:e7:02.0: iaa_comp_acompress: dma_map_sg, dst_addr 21dadf8000, nr_sgs 1, req->dst 000000008d6acea8, req->dlen 4096, sg_dma_len(sg) 8192 + [ 404.202975] idxd 0000:e7:02.0: iaa_compress: desc->src1_addr 223925c000, desc->src1_size 4096, desc->dst_addr 21dadf8000, desc->max_dst_size 4096, desc->src2_addr 2203543000, desc->src2_size 1568 + [ 404.202981] idxd 0000:e7:02.0: iaa_compress_verify: (verify) desc->src1_addr 21dadf8000, desc->src1_size 228, desc->dst_addr 223925c000, desc->max_dst_size 4096, desc->src2_addr 0, desc->src2_size 0 + ... + +Now that basic functionality has been demonstrated, the defaults can +be erased and replaced with a different configuration. To do that, +first disable zswap:: + + # echo lzo > /sys/module/zswap/parameters/compressor + # swapoff -a + # echo 0 > /sys/module/zswap/parameters/accept_threshold_percent + # echo 0 > /sys/module/zswap/parameters/max_pool_percent + # echo 0 > /sys/module/zswap/parameters/enabled + # echo 0 > /sys/module/zswap/parameters/enabled + +Then run the :ref:`iaa_disable_script` in the 'Use Cases' section +below to disable the default configuration. + +Finally turn swap back on:: + + # swapon -a + +Following all that the IAA device(s) can now be re-configured and +enabled as desired for further testing. Below is one example. + +The zswap test expects the work queues for each IAA device on the +system to be configured properly as a kernel workqueue with a +workqueue driver_name of "crypto". + +The below script automatically does that:: + + #!/bin/bash + + echo "IAA devices:" + lspci -d:0cfe + echo "# IAA devices:" + lspci -d:0cfe | wc -l + + # + # count iaa instances + # + iaa_dev_id="0cfe" + num_iaa=$(lspci -d:${iaa_dev_id} | wc -l) + echo "Found ${num_iaa} IAA instances" + + # + # disable iaa wqs and devices + # + echo "Disable IAA" + + for ((i = 1; i < ${num_iaa} * 2; i += 2)); do + echo disable wq iax${i}/wq${i}.0 + accel-config disable-wq iax${i}/wq${i}.0 + echo disable iaa iax${i} + accel-config disable-device iax${i} + done + + echo "End Disable IAA" + + # + # configure iaa wqs and devices + # + echo "Configure IAA" + for ((i = 1; i < ${num_iaa} * 2; i += 2)); do + accel-config config-wq --group-id=0 --mode=dedicated --size=128 --priority=10 --type=kernel --name="iaa_crypto" --driver_name="crypto" iax${i}/wq${i} + done + + echo "End Configure IAA" + + # + # enable iaa wqs and devices + # + echo "Enable IAA" + + for ((i = 1; i < ${num_iaa} * 2; i += 2)); do + echo enable iaa iaa${i} + accel-config enable-device iaa${i} + echo enable wq iaa${i}/wq${i}.0 + accel-config enable-wq iaa${i}/wq${i}.0 + done + + echo "End Enable IAA" + +When the workqueues are bound to the iaa_crypto driver, you should +see something similar to the following in dmesg output if you've +enabled debug output (echo -n 'module iaa_crypto +p' > +/sys/kernel/debug/dynamic_debug/control):: + + [ 60.752344] idxd 0000:f6:02.0: add_iaa_wq: added wq 000000004068d14d to iaa 00000000c9585ba2, n_wq 1 + [ 60.752346] iaa_crypto: rebalance_wq_table: nr_nodes=2, nr_cpus 160, nr_iaa 8, cpus_per_iaa 20 + [ 60.752347] iaa_crypto: rebalance_wq_table: iaa=0 + [ 60.752349] idxd 0000:6a:02.0: request_iaa_wq: getting wq from iaa_device 0000000042d7bc52 (0) + [ 60.752350] idxd 0000:6a:02.0: request_iaa_wq: returning unused wq 00000000c8bb4452 (0) from iaa device 0000000042d7bc52 (0) + [ 60.752352] iaa_crypto: rebalance_wq_table: assigned wq for cpu=0, node=0 = wq 00000000c8bb4452 + [ 60.752354] iaa_crypto: rebalance_wq_table: iaa=0 + [ 60.752355] idxd 0000:6a:02.0: request_iaa_wq: getting wq from iaa_device 0000000042d7bc52 (0) + [ 60.752356] idxd 0000:6a:02.0: request_iaa_wq: returning unused wq 00000000c8bb4452 (0) from iaa device 0000000042d7bc52 (0) + [ 60.752358] iaa_crypto: rebalance_wq_table: assigned wq for cpu=1, node=0 = wq 00000000c8bb4452 + [ 60.752359] iaa_crypto: rebalance_wq_table: iaa=0 + [ 60.752360] idxd 0000:6a:02.0: request_iaa_wq: getting wq from iaa_device 0000000042d7bc52 (0) + [ 60.752361] idxd 0000:6a:02.0: request_iaa_wq: returning unused wq 00000000c8bb4452 (0) from iaa device 0000000042d7bc52 (0) + [ 60.752362] iaa_crypto: rebalance_wq_table: assigned wq for cpu=2, node=0 = wq 00000000c8bb4452 + [ 60.752364] iaa_crypto: rebalance_wq_table: iaa=0 + . + . + . + +Once the workqueues and devices have been enabled, the IAA crypto +algorithms are enabled and available. When the IAA crypto algorithms +have been successfully enabled, you should see the following dmesg +output:: + + [ 64.893759] iaa_crypto: iaa_crypto_enable: iaa_crypto now ENABLED + +Now run the following zswap-specific setup commands to have zswap use +the 'fixed' compression mode:: + + echo 0 > /sys/module/zswap/parameters/enabled + echo 50 > /sys/module/zswap/parameters/max_pool_percent + echo deflate-iaa > /sys/module/zswap/parameters/compressor + echo zsmalloc > /sys/module/zswap/parameters/zpool + echo 1 > /sys/module/zswap/parameters/enabled + echo 0 > /sys/module/zswap/parameters/same_filled_pages_enabled + + echo 100 > /proc/sys/vm/swappiness + echo never > /sys/kernel/mm/transparent_hugepage/enabled + echo 1 > /proc/sys/vm/overcommit_memory + +Finally, you can now run the zswap workload you want to measure. For +example, using the code below, the following command will swap in and +out 100 pages:: + + ./memory_madvise 100 + + Allocating 100 pages to swap in/out + Swapping out 100 pages + Swapping in 100 pages + Swapped out and in 100 pages + +You should see something like the following in the dmesg output if +you've enabled debug output (echo -n 'module iaa_crypto +p' > +/sys/kernel/debug/dynamic_debug/control):: + + [ 404.202972] idxd 0000:e7:02.0: iaa_comp_acompress: dma_map_sg, src_addr 223925c000, nr_sgs 1, req->src 00000000ee7cb5e6, req->slen 4096, sg_dma_len(sg) 4096 + [ 404.202973] idxd 0000:e7:02.0: iaa_comp_acompress: dma_map_sg, dst_addr 21dadf8000, nr_sgs 1, req->dst 000000008d6acea8, req->dlen 4096, sg_dma_len(sg) 8192 + [ 404.202975] idxd 0000:e7:02.0: iaa_compress: desc->src1_addr 223925c000, desc->src1_size 4096, desc->dst_addr 21dadf8000, desc->max_dst_size 4096, desc->src2_addr 2203543000, desc->src2_size 1568 + [ 404.202981] idxd 0000:e7:02.0: iaa_compress_verify: (verify) desc->src1_addr 21dadf8000, desc->src1_size 228, desc->dst_addr 223925c000, desc->max_dst_size 4096, desc->src2_addr 0, desc->src2_size 0 + [ 409.203227] idxd 0000:e7:02.0: iaa_comp_adecompress: dma_map_sg, src_addr 21ddd8b100, nr_sgs 1, req->src 0000000084adab64, req->slen 228, sg_dma_len(sg) 228 + [ 409.203235] idxd 0000:e7:02.0: iaa_comp_adecompress: dma_map_sg, dst_addr 21ee3dc000, nr_sgs 1, req->dst 000000004e2990d0, req->dlen 4096, sg_dma_len(sg) 4096 + [ 409.203239] idxd 0000:e7:02.0: iaa_decompress: desc->src1_addr 21ddd8b100, desc->src1_size 228, desc->dst_addr 21ee3dc000, desc->max_dst_size 4096, desc->src2_addr 0, desc->src2_size 0 + [ 409.203254] idxd 0000:e7:02.0: iaa_comp_adecompress: dma_map_sg, src_addr 21ddd8b100, nr_sgs 1, req->src 0000000084adab64, req->slen 228, sg_dma_len(sg) 228 + [ 409.203256] idxd 0000:e7:02.0: iaa_comp_adecompress: dma_map_sg, dst_addr 21f1551000, nr_sgs 1, req->dst 000000004e2990d0, req->dlen 4096, sg_dma_len(sg) 4096 + [ 409.203257] idxd 0000:e7:02.0: iaa_decompress: desc->src1_addr 21ddd8b100, desc->src1_size 228, desc->dst_addr 21f1551000, desc->max_dst_size 4096, desc->src2_addr 0, desc->src2_size 0 + +In order to unregister the IAA crypto algorithms, and register new +ones using different parameters, any users of the current algorithm +should be stopped and the IAA workqueues and devices disabled. + +In the case of zswap, remove the IAA crypto algorithm as the +compressor and turn off swap (to remove all references to +iaa_crypto):: + + echo lzo > /sys/module/zswap/parameters/compressor + swapoff -a + + echo 0 > /sys/module/zswap/parameters/accept_threshold_percent + echo 0 > /sys/module/zswap/parameters/max_pool_percent + echo 0 > /sys/module/zswap/parameters/enabled + +Once zswap is disabled and no longer using iaa_crypto, the IAA wqs and +devices can be disabled. + +.. _iaa_disable_script: + +IAA disable script +------------------ + +The below script automatically does that:: + + #!/bin/bash + + echo "IAA devices:" + lspci -d:0cfe + echo "# IAA devices:" + lspci -d:0cfe | wc -l + + # + # count iaa instances + # + iaa_dev_id="0cfe" + num_iaa=$(lspci -d:${iaa_dev_id} | wc -l) + echo "Found ${num_iaa} IAA instances" + + # + # disable iaa wqs and devices + # + echo "Disable IAA" + + for ((i = 1; i < ${num_iaa} * 2; i += 2)); do + echo disable wq iax${i}/wq${i}.0 + accel-config disable-wq iax${i}/wq${i}.0 + echo disable iaa iax${i} + accel-config disable-device iax${i} + done + + echo "End Disable IAA" + +Finally, at this point the iaa_crypto module can be removed, which +will unregister the current IAA crypto algorithms:: + + rmmod iaa_crypto + + +memory_madvise.c (gcc -o memory_memadvise memory_madvise.c):: + + #include <stdio.h> + #include <stdlib.h> + #include <string.h> + #include <unistd.h> + #include <sys/mman.h> + #include <linux/mman.h> + + #ifndef MADV_PAGEOUT + #define MADV_PAGEOUT 21 /* force pages out immediately */ + #endif + + #define PG_SZ 4096 + + int main(int argc, char **argv) + { + int i, nr_pages = 1; + int64_t *dump_ptr; + char *addr, *a; + int loop = 1; + + if (argc > 1) + nr_pages = atoi(argv[1]); + + printf("Allocating %d pages to swap in/out\n", nr_pages); + + /* allocate pages */ + addr = mmap(NULL, nr_pages * PG_SZ, PROT_READ | PROT_WRITE, MAP_SHARED | MAP_ANONYMOUS, -1, 0); + *addr = 1; + + /* initialize data in page to all '*' chars */ + memset(addr, '*', nr_pages * PG_SZ); + + printf("Swapping out %d pages\n", nr_pages); + + /* Tell kernel to swap it out */ + madvise(addr, nr_pages * PG_SZ, MADV_PAGEOUT); + + while (loop > 0) { + /* Wait for swap out to finish */ + sleep(5); + + a = addr; + + printf("Swapping in %d pages\n", nr_pages); + + /* Access the page ... this will swap it back in again */ + for (i = 0; i < nr_pages; i++) { + if (a[0] != '*') { + printf("Bad data from decompress!!!!!\n"); + + dump_ptr = (int64_t *)a; + for (int j = 0; j < 100; j++) { + printf(" page %d data: %#llx\n", i, *dump_ptr); + dump_ptr++; + } + } + + a += PG_SZ; + } + + loop --; + } + + printf("Swapped out and in %d pages\n", nr_pages); + +Appendix +======== + +.. _iaa_sysfs_config: + +IAA sysfs config interface +-------------------------- + +Below is a description of the IAA sysfs interface, which as mentioned +in the main document, should only be used if you know exactly what you +are doing. Even then, there's no compelling reason to use it directly +since accel-config can do everything the sysfs interface can and in +fact accel-config is based on it under the covers. + +The 'IAA config path' is /sys/bus/dsa/devices and contains +subdirectories representing each IAA device, workqueue, engine, and +group. Note that in the sysfs interface, the IAA devices are actually +named using iax e.g. iax1, iax3, etc. (Note that IAA devices are the +odd-numbered devices; the even-numbered devices are DSA devices and +can be ignored for IAA). + +The 'IAA device bind path' is /sys/bus/dsa/drivers/idxd/bind and is +the file that is written to enable an IAA device. + +The 'IAA workqueue bind path' is /sys/bus/dsa/drivers/crypto/bind and +is the file that is written to enable an IAA workqueue. + +Similarly /sys/bus/dsa/drivers/idxd/unbind and +/sys/bus/dsa/drivers/crypto/unbind are used to disable IAA devices and +workqueues. + +The basic sequence of commands needed to set up the IAA devices and +workqueues is: + +For each device:: + 1) Disable any workqueues enabled on the device. For example to + disable workques 0 and 1 on IAA device 3:: + + # echo wq3.0 > /sys/bus/dsa/drivers/crypto/unbind + # echo wq3.1 > /sys/bus/dsa/drivers/crypto/unbind + + 2) Disable the device. For example to disable IAA device 3:: + + # echo iax3 > /sys/bus/dsa/drivers/idxd/unbind + + 3) configure the desired workqueues. For example, to configure + workqueue 3 on IAA device 3:: + + # echo dedicated > /sys/bus/dsa/devices/iax3/wq3.3/mode + # echo 128 > /sys/bus/dsa/devices/iax3/wq3.3/size + # echo 0 > /sys/bus/dsa/devices/iax3/wq3.3/group_id + # echo 10 > /sys/bus/dsa/devices/iax3/wq3.3/priority + # echo "kernel" > /sys/bus/dsa/devices/iax3/wq3.3/type + # echo "iaa_crypto" > /sys/bus/dsa/devices/iax3/wq3.3/name + # echo "crypto" > /sys/bus/dsa/devices/iax3/wq3.3/driver_name + + 4) Enable the device. For example to enable IAA device 3:: + + # echo iax3 > /sys/bus/dsa/drivers/idxd/bind + + 5) Enable the desired workqueues on the device. For example to + enable workques 0 and 1 on IAA device 3:: + + # echo wq3.0 > /sys/bus/dsa/drivers/crypto/bind + # echo wq3.1 > /sys/bus/dsa/drivers/crypto/bind diff --git a/Documentation/driver-api/crypto/iaa/index.rst b/Documentation/driver-api/crypto/iaa/index.rst new file mode 100644 index 000000000000..aa6837e27264 --- /dev/null +++ b/Documentation/driver-api/crypto/iaa/index.rst @@ -0,0 +1,20 @@ +.. SPDX-License-Identifier: GPL-2.0 + +================================= +IAA (Intel Analytics Accelerator) +================================= + +IAA provides hardware compression and decompression via the crypto +API. + +.. toctree:: + :maxdepth: 1 + + iaa-crypto + +.. only:: subproject and html + + Indices + ======= + + * :ref:`genindex` diff --git a/Documentation/driver-api/crypto/index.rst b/Documentation/driver-api/crypto/index.rst new file mode 100644 index 000000000000..fb9709b98bea --- /dev/null +++ b/Documentation/driver-api/crypto/index.rst @@ -0,0 +1,20 @@ +.. SPDX-License-Identifier: GPL-2.0 + +============== +Crypto Drivers +============== + +Documentation for crypto drivers that may need more involved setup and +configuration. + +.. toctree:: + :maxdepth: 1 + + iaa/index + +.. only:: subproject and html + + Indices + ======= + + * :ref:`genindex` diff --git a/Documentation/driver-api/device-io.rst b/Documentation/driver-api/device-io.rst index 2c7abd234f4e..d55384b106bd 100644 --- a/Documentation/driver-api/device-io.rst +++ b/Documentation/driver-api/device-io.rst @@ -408,11 +408,12 @@ functions for details on the CPU side of things. ioremap_uc() ------------ -ioremap_uc() behaves like ioremap() except that on the x86 architecture without -'PAT' mode, it marks memory as uncached even when the MTRR has designated -it as cacheable, see Documentation/arch/x86/pat.rst. +ioremap_uc() is only meaningful on old x86-32 systems with the PAT extension, +and on ia64 with its slightly unconventional ioremap() behavior, everywhere +elss ioremap_uc() defaults to return NULL. -Portable drivers should avoid the use of ioremap_uc(). + +Portable drivers should avoid the use of ioremap_uc(), use ioremap() instead. ioremap_cache() --------------- diff --git a/Documentation/driver-api/index.rst b/Documentation/driver-api/index.rst index 8bc4ebe7a36f..eba851605388 100644 --- a/Documentation/driver-api/index.rst +++ b/Documentation/driver-api/index.rst @@ -9,11 +9,8 @@ of device drivers. This document is an only somewhat organized collection of some of those interfaces — it will hopefully get better over time! The available subsections can be seen below. -.. class:: toc-title - - Table of contents - .. toctree:: + :caption: Table of contents :maxdepth: 2 driver-model/index @@ -81,10 +78,8 @@ available subsections can be seen below. backlight/lp855x-driver.rst connector console - dcdbas eisa isa - isapnp io-mapping io_ordering generic-counter @@ -116,6 +111,8 @@ available subsections can be seen below. wmi dpll wbrf + crypto/index + tee .. only:: subproject and html diff --git a/Documentation/driver-api/media/index.rst b/Documentation/driver-api/media/index.rst index 08e206567408..d5593182a3f9 100644 --- a/Documentation/driver-api/media/index.rst +++ b/Documentation/driver-api/media/index.rst @@ -20,13 +20,8 @@ Documentation/userspace-api/media/index.rst - for the userspace APIs used on media devices. -.. only:: html - - .. class:: toc-title - - Table of Contents - .. toctree:: + :caption: Table of Contents :maxdepth: 5 :numbered: diff --git a/Documentation/driver-api/mei/index.rst b/Documentation/driver-api/mei/index.rst index 3a22b522ee78..eae6f18f18cf 100644 --- a/Documentation/driver-api/mei/index.rst +++ b/Documentation/driver-api/mei/index.rst @@ -9,13 +9,8 @@ Intel(R) Management Engine Interface (Intel(R) MEI) **Copyright** |copy| 2019 Intel Corporation -.. only:: html - - .. class:: toc-title - - Table of Contents - .. toctree:: + :caption: Table of Contents :maxdepth: 3 mei diff --git a/Documentation/driver-api/mtd/spi-nor.rst b/Documentation/driver-api/mtd/spi-nor.rst index c22f8c0f7950..148fa4288760 100644 --- a/Documentation/driver-api/mtd/spi-nor.rst +++ b/Documentation/driver-api/mtd/spi-nor.rst @@ -2,64 +2,204 @@ SPI NOR framework ================= -Part I - Why do we need this framework? ---------------------------------------- - -SPI bus controllers (drivers/spi/) only deal with streams of bytes; the bus -controller operates agnostic of the specific device attached. However, some -controllers (such as Freescale's QuadSPI controller) cannot easily handle -arbitrary streams of bytes, but rather are designed specifically for SPI NOR. - -In particular, Freescale's QuadSPI controller must know the NOR commands to -find the right LUT sequence. Unfortunately, the SPI subsystem has no notion of -opcodes, addresses, or data payloads; a SPI controller simply knows to send or -receive bytes (Tx and Rx). Therefore, we must define a new layering scheme under -which the controller driver is aware of the opcodes, addressing, and other -details of the SPI NOR protocol. - -Part II - How does the framework work? --------------------------------------- - -This framework just adds a new layer between the MTD and the SPI bus driver. -With this new layer, the SPI NOR controller driver does not depend on the -m25p80 code anymore. - -Before this framework, the layer is like:: - - MTD - ------------------------ - m25p80 - ------------------------ - SPI bus driver - ------------------------ - SPI NOR chip - -After this framework, the layer is like:: - - MTD - ------------------------ - SPI NOR framework - ------------------------ - m25p80 - ------------------------ - SPI bus driver - ------------------------ - SPI NOR chip - -With the SPI NOR controller driver (Freescale QuadSPI), it looks like:: - - MTD - ------------------------ - SPI NOR framework - ------------------------ - fsl-quadSPI - ------------------------ - SPI NOR chip - -Part III - How can drivers use the framework? ---------------------------------------------- - -The main API is spi_nor_scan(). Before you call the hook, a driver should -initialize the necessary fields for spi_nor{}. Please see -drivers/mtd/spi-nor/spi-nor.c for detail. Please also refer to spi-fsl-qspi.c -when you want to write a new driver for a SPI NOR controller. +How to propose a new flash addition +----------------------------------- + +Most SPI NOR flashes comply with the JEDEC JESD216 +Serial Flash Discoverable Parameter (SFDP) standard. SFDP describes +the functional and feature capabilities of serial flash devices in a +standard set of internal read-only parameter tables. + +The SPI NOR driver queries the SFDP tables in order to determine the +flash's parameters and settings. If the flash defines the SFDP tables +it's likely that you won't need a flash entry at all, and instead +rely on the generic flash driver which probes the flash solely based +on its SFDP data. All one has to do is to specify the "jedec,spi-nor" +compatible in the device tree. + +There are cases however where you need to define an explicit flash +entry. This typically happens when the flash has settings or support +that is not covered by the SFDP tables (e.g. Block Protection), or +when the flash contains mangled SFDP data. If the later, one needs +to implement the ``spi_nor_fixups`` hooks in order to amend the SFDP +parameters with the correct values. + +Minimum testing requirements +----------------------------- + +Do all the tests from below and paste them in the commit's comments +section, after the ``---`` marker. + +1) Specify the controller that you used to test the flash and specify + the frequency at which the flash was operated, e.g.:: + + This flash is populated on the X board and was tested at Y + frequency using the Z (put compatible) SPI controller. + +2) Dump the sysfs entries and print the md5/sha1/sha256 SFDP checksum:: + + root@1:~# cat /sys/bus/spi/devices/spi0.0/spi-nor/partname + sst26vf064b + root@1:~# cat /sys/bus/spi/devices/spi0.0/spi-nor/jedec_id + bf2643 + root@1:~# cat /sys/bus/spi/devices/spi0.0/spi-nor/manufacturer + sst + root@1:~# xxd -p /sys/bus/spi/devices/spi0.0/spi-nor/sfdp + 53464450060102ff00060110300000ff81000106000100ffbf0001180002 + 0001fffffffffffffffffffffffffffffffffd20f1ffffffff0344eb086b + 083b80bbfeffffffffff00ffffff440b0c200dd80fd810d820914824806f + 1d81ed0f773830b030b0f7ffffff29c25cfff030c080ffffffffffffffff + ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff + ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff + ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff + ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff + ffffffffffffffffffffffffffffffffff0004fff37f0000f57f0000f9ff + 7d00f57f0000f37f0000ffffffffffffffffffffffffffffffffffffffff + ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff + ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff + ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff + ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff + ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff + ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff + ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff + ffffbf2643ffb95ffdff30f260f332ff0a122346ff0f19320f1919ffffff + ffffffff00669938ff05013506040232b03072428de89888a585c09faf5a + ffff06ec060c0003080bffffffffff07ffff0202ff060300fdfd040700fc + 0300fefe0202070e + root@1:~# sha256sum /sys/bus/spi/devices/spi0.0/spi-nor/sfdp + 428f34d0461876f189ac97f93e68a05fa6428c6650b3b7baf736a921e5898ed1 /sys/bus/spi/devices/spi0.0/spi-nor/sfdp + + Please dump the SFDP tables using ``xxd -p``. It enables us to do + the reverse operation and convert the hexdump to binary with + ``xxd -rp``. Dumping the SFDP data with ``hexdump -Cv`` is accepted, + but less desirable. + +3) Dump debugfs data:: + + root@1:~# cat /sys/kernel/debug/spi-nor/spi0.0/capabilities + Supported read modes by the flash + 1S-1S-1S + opcode 0x03 + mode cycles 0 + dummy cycles 0 + 1S-1S-1S (fast read) + opcode 0x0b + mode cycles 0 + dummy cycles 8 + 1S-1S-2S + opcode 0x3b + mode cycles 0 + dummy cycles 8 + 1S-2S-2S + opcode 0xbb + mode cycles 4 + dummy cycles 0 + 1S-1S-4S + opcode 0x6b + mode cycles 0 + dummy cycles 8 + 1S-4S-4S + opcode 0xeb + mode cycles 2 + dummy cycles 4 + 4S-4S-4S + opcode 0x0b + mode cycles 2 + dummy cycles 4 + + Supported page program modes by the flash + 1S-1S-1S + opcode 0x02 + + root@1:~# cat /sys/kernel/debug/spi-nor/spi0.0/params + name sst26vf064b + id bf 26 43 bf 26 43 + size 8.00 MiB + write size 1 + page size 256 + address nbytes 3 + flags HAS_LOCK | HAS_16BIT_SR | SOFT_RESET | SWP_IS_VOLATILE + + opcodes + read 0xeb + dummy cycles 6 + erase 0x20 + program 0x02 + 8D extension none + + protocols + read 1S-4S-4S + write 1S-1S-1S + register 1S-1S-1S + + erase commands + 20 (4.00 KiB) [0] + d8 (8.00 KiB) [1] + d8 (32.0 KiB) [2] + d8 (64.0 KiB) [3] + c7 (8.00 MiB) + + sector map + region (in hex) | erase mask | flags + ------------------+------------+---------- + 00000000-00007fff | [01 ] | + 00008000-0000ffff | [0 2 ] | + 00010000-007effff | [0 3] | + 007f0000-007f7fff | [0 2 ] | + 007f8000-007fffff | [01 ] | + +4) Use `mtd-utils <https://git.infradead.org/mtd-utils.git>`__ + and verify that erase, read and page program operations work fine:: + + root@1:~# dd if=/dev/urandom of=./spi_test bs=1M count=2 + 2+0 records in + 2+0 records out + 2097152 bytes (2.1 MB, 2.0 MiB) copied, 0.848566 s, 2.5 MB/s + + root@1:~# mtd_debug erase /dev/mtd0 0 2097152 + Erased 2097152 bytes from address 0x00000000 in flash + + root@1:~# mtd_debug read /dev/mtd0 0 2097152 spi_read + Copied 2097152 bytes from address 0x00000000 in flash to spi_read + + root@1:~# hexdump spi_read + 0000000 ffff ffff ffff ffff ffff ffff ffff ffff + * + 0200000 + + root@1:~# sha256sum spi_read + 4bda3a28f4ffe603c0ec1258c0034d65a1a0d35ab7bd523a834608adabf03cc5 spi_read + + root@1:~# mtd_debug write /dev/mtd0 0 2097152 spi_test + Copied 2097152 bytes from spi_test to address 0x00000000 in flash + + root@1:~# mtd_debug read /dev/mtd0 0 2097152 spi_read + Copied 2097152 bytes from address 0x00000000 in flash to spi_read + + root@1:~# sha256sum spi* + c444216a6ba2a4a66cccd60a0dd062bce4b865dd52b200ef5e21838c4b899ac8 spi_read + c444216a6ba2a4a66cccd60a0dd062bce4b865dd52b200ef5e21838c4b899ac8 spi_test + + If the flash comes erased by default and the previous erase was ignored, + we won't catch it, thus test the erase again:: + + root@1:~# mtd_debug erase /dev/mtd0 0 2097152 + Erased 2097152 bytes from address 0x00000000 in flash + + root@1:~# mtd_debug read /dev/mtd0 0 2097152 spi_read + Copied 2097152 bytes from address 0x00000000 in flash to spi_read + + root@1:~# sha256sum spi* + 4bda3a28f4ffe603c0ec1258c0034d65a1a0d35ab7bd523a834608adabf03cc5 spi_read + c444216a6ba2a4a66cccd60a0dd062bce4b865dd52b200ef5e21838c4b899ac8 spi_test + + Dump some other relevant data:: + + root@1:~# mtd_debug info /dev/mtd0 + mtd.type = MTD_NORFLASH + mtd.flags = MTD_CAP_NORFLASH + mtd.size = 8388608 (8M) + mtd.erasesize = 4096 (4K) + mtd.writesize = 1 + mtd.oobsize = 0 + regions = 0 diff --git a/Documentation/driver-api/nvmem.rst b/Documentation/driver-api/nvmem.rst index de221e91c8e3..5d9500d21ecc 100644 --- a/Documentation/driver-api/nvmem.rst +++ b/Documentation/driver-api/nvmem.rst @@ -41,7 +41,7 @@ A NVMEM provider can register with NVMEM core by supplying relevant nvmem configuration to nvmem_register(), on success core would return a valid nvmem_device pointer. -nvmem_unregister(nvmem) is used to unregister a previously registered provider. +nvmem_unregister() is used to unregister a previously registered provider. For example, a simple nvram case:: @@ -200,3 +200,9 @@ and let you add cells dynamically. Another use case for layouts is the post processing of cells. With layouts, it is possible to associate a custom post processing hook to a cell. It even possible to add this hook to cells not created by the layout itself. + +9. Internal kernel API +====================== + +.. kernel-doc:: drivers/nvmem/core.c + :export: diff --git a/Documentation/driver-api/pci/index.rst b/Documentation/driver-api/pci/index.rst index c6cf1fef61ce..a38e475cdbe3 100644 --- a/Documentation/driver-api/pci/index.rst +++ b/Documentation/driver-api/pci/index.rst @@ -4,11 +4,8 @@ The Linux PCI driver implementer's API guide ============================================ -.. class:: toc-title - - Table of contents - .. toctree:: + :caption: Table of contents :maxdepth: 2 pci diff --git a/Documentation/driver-api/surface_aggregator/ssh.rst b/Documentation/driver-api/surface_aggregator/ssh.rst index b955b673838b..58a757319931 100644 --- a/Documentation/driver-api/surface_aggregator/ssh.rst +++ b/Documentation/driver-api/surface_aggregator/ssh.rst @@ -39,7 +39,7 @@ Note that the standard disclaimer for this subsystem also applies to this document: All of this has been reverse-engineered and may thus be erroneous and/or incomplete. -All CRCs used in the following are two-byte ``crc_ccitt_false(0xffff, ...)``. +All CRCs used in the following are two-byte ``crc_itu_t(0xffff, ...)``. All multi-byte values are little-endian, there is no implicit padding between values. diff --git a/Documentation/driver-api/tee.rst b/Documentation/driver-api/tee.rst new file mode 100644 index 000000000000..5eaeb8103988 --- /dev/null +++ b/Documentation/driver-api/tee.rst @@ -0,0 +1,66 @@ +.. SPDX-License-Identifier: GPL-2.0 + +=============================================== +TEE (Trusted Execution Environment) driver API +=============================================== + +Kernel provides a TEE bus infrastructure where a Trusted Application is +represented as a device identified via Universally Unique Identifier (UUID) and +client drivers register a table of supported device UUIDs. + +TEE bus infrastructure registers following APIs: + +match(): + iterates over the client driver UUID table to find a corresponding + match for device UUID. If a match is found, then this particular device is + probed via corresponding probe API registered by the client driver. This + process happens whenever a device or a client driver is registered with TEE + bus. + +uevent(): + notifies user-space (udev) whenever a new device is registered on + TEE bus for auto-loading of modularized client drivers. + +TEE bus device enumeration is specific to underlying TEE implementation, so it +is left open for TEE drivers to provide corresponding implementation. + +Then TEE client driver can talk to a matched Trusted Application using APIs +listed in include/linux/tee_drv.h. + +TEE client driver example +------------------------- + +Suppose a TEE client driver needs to communicate with a Trusted Application +having UUID: ``ac6a4085-0e82-4c33-bf98-8eb8e118b6c2``, so driver registration +snippet would look like:: + + static const struct tee_client_device_id client_id_table[] = { + {UUID_INIT(0xac6a4085, 0x0e82, 0x4c33, + 0xbf, 0x98, 0x8e, 0xb8, 0xe1, 0x18, 0xb6, 0xc2)}, + {} + }; + + MODULE_DEVICE_TABLE(tee, client_id_table); + + static struct tee_client_driver client_driver = { + .id_table = client_id_table, + .driver = { + .name = DRIVER_NAME, + .bus = &tee_bus_type, + .probe = client_probe, + .remove = client_remove, + }, + }; + + static int __init client_init(void) + { + return driver_register(&client_driver.driver); + } + + static void __exit client_exit(void) + { + driver_unregister(&client_driver.driver); + } + + module_init(client_init); + module_exit(client_exit); diff --git a/Documentation/filesystems/directory-locking.rst b/Documentation/filesystems/directory-locking.rst index dccd61c7c5c3..05ea387bc9fb 100644 --- a/Documentation/filesystems/directory-locking.rst +++ b/Documentation/filesystems/directory-locking.rst @@ -11,129 +11,268 @@ When taking the i_rwsem on multiple non-directory objects, we always acquire the locks in order by increasing address. We'll call that "inode pointer" order in the following. -For our purposes all operations fall in 5 classes: -1) read access. Locking rules: caller locks directory we are accessing. -The lock is taken shared. +Primitives +========== -2) object creation. Locking rules: same as above, but the lock is taken -exclusive. +For our purposes all operations fall in 6 classes: -3) object removal. Locking rules: caller locks parent, finds victim, -locks victim and calls the method. Locks are exclusive. +1. read access. Locking rules: -4) rename() that is _not_ cross-directory. Locking rules: caller locks the -parent and finds source and target. We lock both (provided they exist). If we -need to lock two inodes of different type (dir vs non-dir), we lock directory -first. If we need to lock two inodes of the same type, lock them in inode -pointer order. Then call the method. All locks are exclusive. -NB: we might get away with locking the source (and target in exchange -case) shared. + * lock the directory we are accessing (shared) -5) link creation. Locking rules: +2. object creation. Locking rules: - * lock parent - * check that source is not a directory - * lock source - * call the method. + * lock the directory we are accessing (exclusive) -All locks are exclusive. +3. object removal. Locking rules: -6) cross-directory rename. The trickiest in the whole bunch. Locking -rules: + * lock the parent (exclusive) + * find the victim + * lock the victim (exclusive) - * lock the filesystem - * lock parents in "ancestors first" order. If one is not ancestor of - the other, lock them in inode pointer order. - * find source and target. - * if old parent is equal to or is a descendent of target - fail with -ENOTEMPTY - * if new parent is equal to or is a descendent of source - fail with -ELOOP - * Lock both the source and the target provided they exist. If we - need to lock two inodes of different type (dir vs non-dir), we lock - the directory first. If we need to lock two inodes of the same type, - lock them in inode pointer order. - * call the method. - -All ->i_rwsem are taken exclusive. Again, we might get away with locking -the source (and target in exchange case) shared. - -The rules above obviously guarantee that all directories that are going to be -read, modified or removed by method will be locked by caller. +4. link creation. Locking rules: + + * lock the parent (exclusive) + * check that the source is not a directory + * lock the source (exclusive; probably could be weakened to shared) + +5. rename that is _not_ cross-directory. Locking rules: + + * lock the parent (exclusive) + * find the source and target + * decide which of the source and target need to be locked. + The source needs to be locked if it's a non-directory, target - if it's + a non-directory or about to be removed. + * take the locks that need to be taken (exlusive), in inode pointer order + if need to take both (that can happen only when both source and target + are non-directories - the source because it wouldn't need to be locked + otherwise and the target because mixing directory and non-directory is + allowed only with RENAME_EXCHANGE, and that won't be removing the target). +6. cross-directory rename. The trickiest in the whole bunch. Locking rules: + + * lock the filesystem + * if the parents don't have a common ancestor, fail the operation. + * lock the parents in "ancestors first" order (exclusive). If neither is an + ancestor of the other, lock the parent of source first. + * find the source and target. + * verify that the source is not a descendent of the target and + target is not a descendent of source; fail the operation otherwise. + * lock the subdirectories involved (exclusive), source before target. + * lock the non-directories involved (exclusive), in inode pointer order. + +The rules above obviously guarantee that all directories that are going +to be read, modified or removed by method will be locked by the caller. + + +Splicing +======== + +There is one more thing to consider - splicing. It's not an operation +in its own right; it may happen as part of lookup. We speak of the +operations on directory trees, but we obviously do not have the full +picture of those - especially for network filesystems. What we have +is a bunch of subtrees visible in dcache and locking happens on those. +Trees grow as we do operations; memory pressure prunes them. Normally +that's not a problem, but there is a nasty twist - what should we do +when one growing tree reaches the root of another? That can happen in +several scenarios, starting from "somebody mounted two nested subtrees +from the same NFS4 server and doing lookups in one of them has reached +the root of another"; there's also open-by-fhandle stuff, and there's a +possibility that directory we see in one place gets moved by the server +to another and we run into it when we do a lookup. + +For a lot of reasons we want to have the same directory present in dcache +only once. Multiple aliases are not allowed. So when lookup runs into +a subdirectory that already has an alias, something needs to be done with +dcache trees. Lookup is already holding the parent locked. If alias is +a root of separate tree, it gets attached to the directory we are doing a +lookup in, under the name we'd been looking for. If the alias is already +a child of the directory we are looking in, it changes name to the one +we'd been looking for. No extra locking is involved in these two cases. +However, if it's a child of some other directory, the things get trickier. +First of all, we verify that it is *not* an ancestor of our directory +and fail the lookup if it is. Then we try to lock the filesystem and the +current parent of the alias. If either trylock fails, we fail the lookup. +If trylocks succeed, we detach the alias from its current parent and +attach to our directory, under the name we are looking for. + +Note that splicing does *not* involve any modification of the filesystem; +all we change is the view in dcache. Moreover, holding a directory locked +exclusive prevents such changes involving its children and holding the +filesystem lock prevents any changes of tree topology, other than having a +root of one tree becoming a child of directory in another. In particular, +if two dentries have been found to have a common ancestor after taking +the filesystem lock, their relationship will remain unchanged until +the lock is dropped. So from the directory operations' point of view +splicing is almost irrelevant - the only place where it matters is one +step in cross-directory renames; we need to be careful when checking if +parents have a common ancestor. + + +Multiple-filesystem stuff +========================= + +For some filesystems a method can involve a directory operation on +another filesystem; it may be ecryptfs doing operation in the underlying +filesystem, overlayfs doing something to the layers, network filesystem +using a local one as a cache, etc. In all such cases the operations +on other filesystems must follow the same locking rules. Moreover, "a +directory operation on this filesystem might involve directory operations +on that filesystem" should be an asymmetric relation (or, if you will, +it should be possible to rank the filesystems so that directory operation +on a filesystem could trigger directory operations only on higher-ranked +ones - in these terms overlayfs ranks lower than its layers, network +filesystem ranks lower than whatever it caches on, etc.) + + +Deadlock avoidance +================== If no directory is its own ancestor, the scheme above is deadlock-free. Proof: - First of all, at any moment we have a linear ordering of the - objects - A < B iff (A is an ancestor of B) or (B is not an ancestor - of A and ptr(A) < ptr(B)). - - That ordering can change. However, the following is true: - -(1) if object removal or non-cross-directory rename holds lock on A and - attempts to acquire lock on B, A will remain the parent of B until we - acquire the lock on B. (Proof: only cross-directory rename can change - the parent of object and it would have to lock the parent). - -(2) if cross-directory rename holds the lock on filesystem, order will not - change until rename acquires all locks. (Proof: other cross-directory - renames will be blocked on filesystem lock and we don't start changing - the order until we had acquired all locks). - -(3) locks on non-directory objects are acquired only after locks on - directory objects, and are acquired in inode pointer order. - (Proof: all operations but renames take lock on at most one - non-directory object, except renames, which take locks on source and - target in inode pointer order in the case they are not directories.) - -Now consider the minimal deadlock. Each process is blocked on -attempt to acquire some lock and already holds at least one lock. Let's -consider the set of contended locks. First of all, filesystem lock is -not contended, since any process blocked on it is not holding any locks. -Thus all processes are blocked on ->i_rwsem. - -By (3), any process holding a non-directory lock can only be -waiting on another non-directory lock with a larger address. Therefore -the process holding the "largest" such lock can always make progress, and -non-directory objects are not included in the set of contended locks. - -Thus link creation can't be a part of deadlock - it can't be -blocked on source and it means that it doesn't hold any locks. - -Any contended object is either held by cross-directory rename or -has a child that is also contended. Indeed, suppose that it is held by -operation other than cross-directory rename. Then the lock this operation -is blocked on belongs to child of that object due to (1). - -It means that one of the operations is cross-directory rename. -Otherwise the set of contended objects would be infinite - each of them -would have a contended child and we had assumed that no object is its -own descendent. Moreover, there is exactly one cross-directory rename -(see above). - -Consider the object blocking the cross-directory rename. One -of its descendents is locked by cross-directory rename (otherwise we -would again have an infinite set of contended objects). But that -means that cross-directory rename is taking locks out of order. Due -to (2) the order hadn't changed since we had acquired filesystem lock. -But locking rules for cross-directory rename guarantee that we do not -try to acquire lock on descendent before the lock on ancestor. -Contradiction. I.e. deadlock is impossible. Q.E.D. - +There is a ranking on the locks, such that all primitives take +them in order of non-decreasing rank. Namely, + + * rank ->i_rwsem of non-directories on given filesystem in inode pointer + order. + * put ->i_rwsem of all directories on a filesystem at the same rank, + lower than ->i_rwsem of any non-directory on the same filesystem. + * put ->s_vfs_rename_mutex at rank lower than that of any ->i_rwsem + on the same filesystem. + * among the locks on different filesystems use the relative + rank of those filesystems. + +For example, if we have NFS filesystem caching on a local one, we have + + 1. ->s_vfs_rename_mutex of NFS filesystem + 2. ->i_rwsem of directories on that NFS filesystem, same rank for all + 3. ->i_rwsem of non-directories on that filesystem, in order of + increasing address of inode + 4. ->s_vfs_rename_mutex of local filesystem + 5. ->i_rwsem of directories on the local filesystem, same rank for all + 6. ->i_rwsem of non-directories on local filesystem, in order of + increasing address of inode. + +It's easy to verify that operations never take a lock with rank +lower than that of an already held lock. + +Suppose deadlocks are possible. Consider the minimal deadlocked +set of threads. It is a cycle of several threads, each blocked on a lock +held by the next thread in the cycle. + +Since the locking order is consistent with the ranking, all +contended locks in the minimal deadlock will be of the same rank, +i.e. they all will be ->i_rwsem of directories on the same filesystem. +Moreover, without loss of generality we can assume that all operations +are done directly to that filesystem and none of them has actually +reached the method call. + +In other words, we have a cycle of threads, T1,..., Tn, +and the same number of directories (D1,...,Dn) such that + + T1 is blocked on D1 which is held by T2 + + T2 is blocked on D2 which is held by T3 + + ... + + Tn is blocked on Dn which is held by T1. + +Each operation in the minimal cycle must have locked at least +one directory and blocked on attempt to lock another. That leaves +only 3 possible operations: directory removal (locks parent, then +child), same-directory rename killing a subdirectory (ditto) and +cross-directory rename of some sort. + +There must be a cross-directory rename in the set; indeed, +if all operations had been of the "lock parent, then child" sort +we would have Dn a parent of D1, which is a parent of D2, which is +a parent of D3, ..., which is a parent of Dn. Relationships couldn't +have changed since the moment directory locks had been acquired, +so they would all hold simultaneously at the deadlock time and +we would have a loop. + +Since all operations are on the same filesystem, there can't be +more than one cross-directory rename among them. Without loss of +generality we can assume that T1 is the one doing a cross-directory +rename and everything else is of the "lock parent, then child" sort. + +In other words, we have a cross-directory rename that locked +Dn and blocked on attempt to lock D1, which is a parent of D2, which is +a parent of D3, ..., which is a parent of Dn. Relationships between +D1,...,Dn all hold simultaneously at the deadlock time. Moreover, +cross-directory rename does not get to locking any directories until it +has acquired filesystem lock and verified that directories involved have +a common ancestor, which guarantees that ancestry relationships between +all of them had been stable. + +Consider the order in which directories are locked by the +cross-directory rename; parents first, then possibly their children. +Dn and D1 would have to be among those, with Dn locked before D1. +Which pair could it be? + +It can't be the parents - indeed, since D1 is an ancestor of Dn, +it would be the first parent to be locked. Therefore at least one of the +children must be involved and thus neither of them could be a descendent +of another - otherwise the operation would not have progressed past +locking the parents. + +It can't be a parent and its child; otherwise we would've had +a loop, since the parents are locked before the children, so the parent +would have to be a descendent of its child. + +It can't be a parent and a child of another parent either. +Otherwise the child of the parent in question would've been a descendent +of another child. + +That leaves only one possibility - namely, both Dn and D1 are +among the children, in some order. But that is also impossible, since +neither of the children is a descendent of another. + +That concludes the proof, since the set of operations with the +properties requiered for a minimal deadlock can not exist. + +Note that the check for having a common ancestor in cross-directory +rename is crucial - without it a deadlock would be possible. Indeed, +suppose the parents are initially in different trees; we would lock the +parent of source, then try to lock the parent of target, only to have +an unrelated lookup splice a distant ancestor of source to some distant +descendent of the parent of target. At that point we have cross-directory +rename holding the lock on parent of source and trying to lock its +distant ancestor. Add a bunch of rmdir() attempts on all directories +in between (all of those would fail with -ENOTEMPTY, had they ever gotten +the locks) and voila - we have a deadlock. + +Loop avoidance +============== These operations are guaranteed to avoid loop creation. Indeed, the only operation that could introduce loops is cross-directory rename. -Since the only new (parent, child) pair added by rename() is (new parent, -source), such loop would have to contain these objects and the rest of it -would have to exist before rename(). I.e. at the moment of loop creation -rename() responsible for that would be holding filesystem lock and new parent -would have to be equal to or a descendent of source. But that means that -new parent had been equal to or a descendent of source since the moment when -we had acquired filesystem lock and rename() would fail with -ELOOP in that -case. +Suppose after the operation there is a loop; since there hadn't been such +loops before the operation, at least on of the nodes in that loop must've +had its parent changed. In other words, the loop must be passing through +the source or, in case of exchange, possibly the target. + +Since the operation has succeeded, neither source nor target could have +been ancestors of each other. Therefore the chain of ancestors starting +in the parent of source could not have passed through the target and +vice versa. On the other hand, the chain of ancestors of any node could +not have passed through the node itself, or we would've had a loop before +the operation. But everything other than source and target has kept +the parent after the operation, so the operation does not change the +chains of ancestors of (ex-)parents of source and target. In particular, +those chains must end after a finite number of steps. + +Now consider the loop created by the operation. It passes through either +source or target; the next node in the loop would be the ex-parent of +target or source resp. After that the loop would follow the chain of +ancestors of that parent. But as we have just shown, that chain must +end after a finite number of steps, which means that it can't be a part +of any loop. Q.E.D. While this locking scheme works for arbitrary DAGs, it relies on ability to check that directory is a descendent of another object. Current diff --git a/Documentation/filesystems/fscrypt.rst b/Documentation/filesystems/fscrypt.rst index 1b84f818e574..e86b886b64d0 100644 --- a/Documentation/filesystems/fscrypt.rst +++ b/Documentation/filesystems/fscrypt.rst @@ -31,15 +31,15 @@ However, except for filenames, fscrypt does not encrypt filesystem metadata. Unlike eCryptfs, which is a stacked filesystem, fscrypt is integrated -directly into supported filesystems --- currently ext4, F2FS, and -UBIFS. This allows encrypted files to be read and written without -caching both the decrypted and encrypted pages in the pagecache, -thereby nearly halving the memory used and bringing it in line with -unencrypted files. Similarly, half as many dentries and inodes are -needed. eCryptfs also limits encrypted filenames to 143 bytes, -causing application compatibility issues; fscrypt allows the full 255 -bytes (NAME_MAX). Finally, unlike eCryptfs, the fscrypt API can be -used by unprivileged users, with no need to mount anything. +directly into supported filesystems --- currently ext4, F2FS, UBIFS, +and CephFS. This allows encrypted files to be read and written +without caching both the decrypted and encrypted pages in the +pagecache, thereby nearly halving the memory used and bringing it in +line with unencrypted files. Similarly, half as many dentries and +inodes are needed. eCryptfs also limits encrypted filenames to 143 +bytes, causing application compatibility issues; fscrypt allows the +full 255 bytes (NAME_MAX). Finally, unlike eCryptfs, the fscrypt API +can be used by unprivileged users, with no need to mount anything. fscrypt does not support encrypting files in-place. Instead, it supports marking an empty directory as encrypted. Then, after @@ -1382,7 +1382,8 @@ directory.) These structs are defined as follows:: u8 contents_encryption_mode; u8 filenames_encryption_mode; u8 flags; - u8 __reserved[4]; + u8 log2_data_unit_size; + u8 __reserved[3]; u8 master_key_identifier[FSCRYPT_KEY_IDENTIFIER_SIZE]; u8 nonce[FSCRYPT_FILE_NONCE_SIZE]; }; diff --git a/Documentation/filesystems/fuse-io.rst b/Documentation/filesystems/fuse-io.rst index 255a368fe534..6464de4266ad 100644 --- a/Documentation/filesystems/fuse-io.rst +++ b/Documentation/filesystems/fuse-io.rst @@ -15,7 +15,8 @@ The direct-io mode can be selected with the FOPEN_DIRECT_IO flag in the FUSE_OPEN reply. In direct-io mode the page cache is completely bypassed for reads and writes. -No read-ahead takes place. Shared mmap is disabled. +No read-ahead takes place. Shared mmap is disabled by default. To allow shared +mmap, the FUSE_DIRECT_IO_ALLOW_MMAP flag may be enabled in the FUSE_INIT reply. In cached mode reads may be satisfied from the page cache, and data may be read-ahead by the kernel to fill the cache. The cache is always kept consistent diff --git a/Documentation/filesystems/index.rst b/Documentation/filesystems/index.rst index 09cade7eaefc..e18bc5ae3b35 100644 --- a/Documentation/filesystems/index.rst +++ b/Documentation/filesystems/index.rst @@ -121,8 +121,5 @@ Documentation for filesystem implementations. udf virtiofs vfat - xfs-delayed-logging-design - xfs-maintainer-entry-profile - xfs-self-describing-metadata - xfs-online-fsck-design + xfs/index zonefs diff --git a/Documentation/filesystems/locking.rst b/Documentation/filesystems/locking.rst index 7be2900806c8..d5bf4b6b7509 100644 --- a/Documentation/filesystems/locking.rst +++ b/Documentation/filesystems/locking.rst @@ -101,7 +101,7 @@ symlink: exclusive mkdir: exclusive unlink: exclusive (both) rmdir: exclusive (both)(see below) -rename: exclusive (all) (see below) +rename: exclusive (both parents, some children) (see below) readlink: no get_link: no setattr: exclusive @@ -123,6 +123,9 @@ get_offset_ctx no Additionally, ->rmdir(), ->unlink() and ->rename() have ->i_rwsem exclusive on victim. cross-directory ->rename() has (per-superblock) ->s_vfs_rename_sem. + ->unlink() and ->rename() have ->i_rwsem exclusive on all non-directories + involved. + ->rename() has ->i_rwsem exclusive on any subdirectory that changes parent. See Documentation/filesystems/directory-locking.rst for more detailed discussion of the locking scheme for directory operations. @@ -261,7 +264,7 @@ prototypes:: struct folio *src, enum migrate_mode); int (*launder_folio)(struct folio *); bool (*is_partially_uptodate)(struct folio *, size_t from, size_t count); - int (*error_remove_page)(struct address_space *, struct page *); + int (*error_remove_folio)(struct address_space *, struct folio *); int (*swap_activate)(struct swap_info_struct *sis, struct file *f, sector_t *span) int (*swap_deactivate)(struct file *); int (*swap_rw)(struct kiocb *iocb, struct iov_iter *iter); @@ -287,7 +290,7 @@ direct_IO: migrate_folio: yes (both) launder_folio: yes is_partially_uptodate: yes -error_remove_page: yes +error_remove_folio: yes swap_activate: no swap_deactivate: no swap_rw: yes, unlocks diff --git a/Documentation/filesystems/overlayfs.rst b/Documentation/filesystems/overlayfs.rst index 0407f361f32a..1c244866041a 100644 --- a/Documentation/filesystems/overlayfs.rst +++ b/Documentation/filesystems/overlayfs.rst @@ -39,7 +39,7 @@ objects in the original filesystem. On 64bit systems, even if all overlay layers are not on the same underlying filesystem, the same compliant behavior could be achieved with the "xino" feature. The "xino" feature composes a unique object -identifier from the real object st_ino and an underlying fsid index. +identifier from the real object st_ino and an underlying fsid number. The "xino" feature uses the high inode number bits for fsid, because the underlying filesystems rarely use the high inode number bits. In case the underlying inode number does overflow into the high xino bits, overlay @@ -118,7 +118,7 @@ Where both upper and lower objects are directories, a merged directory is formed. At mount time, the two directories given as mount options "lowerdir" and -"upperdir" are combined into a merged directory: +"upperdir" are combined into a merged directory:: mount -t overlay overlay -olowerdir=/lower,upperdir=/upper,\ workdir=/work /merged @@ -172,12 +172,12 @@ directory is being read. This is unlikely to be noticed by many programs. seek offsets are assigned sequentially when the directories are read. -Thus if +Thus if: - - read part of a directory - - remember an offset, and close the directory - - re-open the directory some time later - - seek to the remembered offset + - read part of a directory + - remember an offset, and close the directory + - re-open the directory some time later + - seek to the remembered offset there may be little correlation between the old and new locations in the list of filenames, particularly if anything has changed in the @@ -290,9 +290,9 @@ Permission checking in the overlay filesystem follows these principles: 2) task creating the overlay mount MUST NOT gain additional privileges 3) non-mounting task MAY gain additional privileges through the overlay, - compared to direct access on underlying lower or upper filesystems + compared to direct access on underlying lower or upper filesystems -This is achieved by performing two permission checks on each access +This is achieved by performing two permission checks on each access: a) check if current task is allowed access based on local DAC (owner, group, mode and posix acl), as well as MAC checks @@ -311,11 +311,11 @@ to create setups where the consistency rule (1) does not hold; normally, however, the mounting task will have sufficient privileges to perform all operations. -Another way to demonstrate this model is drawing parallels between +Another way to demonstrate this model is drawing parallels between:: mount -t overlay overlay -olowerdir=/lower,upperdir=/upper,... /merged -and +and:: cp -a /lower /upper mount --bind /upper /merged @@ -328,7 +328,7 @@ Multiple lower layers --------------------- Multiple lower layers can now be given using the colon (":") as a -separator character between the directory names. For example: +separator character between the directory names. For example:: mount -t overlay overlay -olowerdir=/lower1:/lower2:/lower3 /merged @@ -340,13 +340,13 @@ rightmost one and going left. In the above example lower1 will be the top, lower2 the middle and lower3 the bottom layer. Note: directory names containing colons can be provided as lower layer by -escaping the colons with a single backslash. For example: +escaping the colons with a single backslash. For example:: mount -t overlay overlay -olowerdir=/a\:lower\:\:dir /merged Since kernel version v6.8, directory names containing colons can also be configured as lower layer using the "lowerdir+" mount options and the -fsconfig syscall from new mount api. For example: +fsconfig syscall from new mount api. For example:: fsconfig(fs_fd, FSCONFIG_SET_STRING, "lowerdir+", "/a:lower::dir", 0); @@ -356,7 +356,7 @@ as an octal characters (\072) when displayed in /proc/self/mountinfo. Metadata only copy up --------------------- -When metadata only copy up feature is enabled, overlayfs will only copy +When the "metacopy" feature is enabled, overlayfs will only copy up metadata (as opposed to whole file), when a metadata specific operation like chown/chmod is performed. Full file will be copied up later when file is opened for WRITE operation. @@ -405,7 +405,7 @@ A normal lower layer is not allowed to be below a data-only layer, so single colon separators are not allowed to the right of double colon ("::") separators. -For example: +For example:: mount -t overlay overlay -olowerdir=/l1:/l2:/l3::/do1::/do2 /merged @@ -419,7 +419,7 @@ to the absolute path of the "lower data" file in the "data-only" lower layer. Since kernel version v6.8, "data-only" lower layers can also be added using the "datadir+" mount options and the fsconfig syscall from new mount api. -For example: +For example:: fsconfig(fs_fd, FSCONFIG_SET_STRING, "lowerdir+", "/l1", 0); fsconfig(fs_fd, FSCONFIG_SET_STRING, "lowerdir+", "/l2", 0); @@ -429,7 +429,7 @@ For example: fs-verity support ----------------------- +----------------- During metadata copy up of a lower file, if the source file has fs-verity enabled and overlay verity support is enabled, then the @@ -492,27 +492,27 @@ though it will not result in a crash or deadlock. Mounting an overlay using an upper layer path, where the upper layer path was previously used by another mounted overlay in combination with a -different lower layer path, is allowed, unless the "inodes index" feature -or "metadata only copy up" feature is enabled. +different lower layer path, is allowed, unless the "index" or "metacopy" +features are enabled. -With the "inodes index" feature, on the first time mount, an NFS file +With the "index" feature, on the first time mount, an NFS file handle of the lower layer root directory, along with the UUID of the lower filesystem, are encoded and stored in the "trusted.overlay.origin" extended attribute on the upper layer root directory. On subsequent mount attempts, the lower root directory file handle and lower filesystem UUID are compared to the stored origin in upper root directory. On failure to verify the lower root origin, mount will fail with ESTALE. An overlayfs mount with -"inodes index" enabled will fail with EOPNOTSUPP if the lower filesystem +"index" enabled will fail with EOPNOTSUPP if the lower filesystem does not support NFS export, lower filesystem does not have a valid UUID or if the upper filesystem does not support extended attributes. -For "metadata only copy up" feature there is no verification mechanism at +For the "metacopy" feature, there is no verification mechanism at mount time. So if same upper is mounted with different set of lower, mount probably will succeed but expect the unexpected later on. So don't do it. It is quite a common practice to copy overlay layers to a different directory tree on the same or different underlying filesystem, and even -to a different machine. With the "inodes index" feature, trying to mount +to a different machine. With the "index" feature, trying to mount the copied layers will fail the verification of the lower root file handle. Nesting overlayfs mounts @@ -547,20 +547,21 @@ filesystem. This is the list of cases that overlayfs doesn't currently handle: -a) POSIX mandates updating st_atime for reads. This is currently not -done in the case when the file resides on a lower layer. + a) POSIX mandates updating st_atime for reads. This is currently not + done in the case when the file resides on a lower layer. -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. + 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. + 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: -1) "redirect_dir" +redirect_dir +```````````` Enabled with the mount option or module option: "redirect_dir=on" or with the kernel config option CONFIG_OVERLAY_FS_REDIRECT_DIR=y. @@ -568,7 +569,8 @@ the kernel config option CONFIG_OVERLAY_FS_REDIRECT_DIR=y. If this feature is disabled, then rename(2) on a lower or merged directory will fail with EXDEV ("Invalid cross-device link"). -2) "inode index" +index +````` Enabled with the mount option or module option "index=on" or with the kernel config option CONFIG_OVERLAY_FS_INDEX=y. @@ -577,7 +579,8 @@ If this feature is disabled and a file with multiple hard links is copied up, then this will "break" the link. Changes will not be propagated to other names referring to the same inode. -3) "xino" +xino +```` Enabled with the mount option "xino=auto" or "xino=on", with the module option "xino_auto=on" or with the kernel config option @@ -604,7 +607,7 @@ a crash or deadlock. Offline changes, when the overlay is not mounted, are allowed to the upper tree. Offline changes to the lower tree are only allowed if the -"metadata only copy up", "inode index", "xino" and "redirect_dir" features +"metacopy", "index", "xino" and "redirect_dir" features have not been used. If the lower tree is modified and any of these features has been used, the behavior of the overlay is undefined, though it will not result in a crash or deadlock. @@ -644,12 +647,13 @@ directory inode. When encoding a file handle from an overlay filesystem object, the following rules apply: -1. For a non-upper object, encode a lower file handle from lower inode -2. For an indexed object, encode a lower file handle from copy_up origin -3. For a pure-upper object and for an existing non-indexed upper object, - encode an upper file handle from upper inode + 1. For a non-upper object, encode a lower file handle from lower inode + 2. For an indexed object, encode a lower file handle from copy_up origin + 3. For a pure-upper object and for an existing non-indexed upper object, + encode an upper file handle from upper inode The encoded overlay file handle includes: + - Header including path type information (e.g. lower/upper) - UUID of the underlying filesystem - Underlying filesystem encoding of underlying inode @@ -659,15 +663,15 @@ are stored in extended attribute "trusted.overlay.origin". When decoding an overlay file handle, the following steps are followed: -1. Find underlying layer by UUID and path type information. -2. Decode the underlying filesystem file handle to underlying dentry. -3. For a lower file handle, lookup the handle in index directory by name. -4. If a whiteout is found in index, return ESTALE. This represents an - overlay object that was deleted after its file handle was encoded. -5. For a non-directory, instantiate a disconnected overlay dentry from the - decoded underlying dentry, the path type and index inode, if found. -6. For a directory, use the connected underlying decoded dentry, path type - and index, to lookup a connected overlay dentry. + 1. Find underlying layer by UUID and path type information. + 2. Decode the underlying filesystem file handle to underlying dentry. + 3. For a lower file handle, lookup the handle in index directory by name. + 4. If a whiteout is found in index, return ESTALE. This represents an + overlay object that was deleted after its file handle was encoded. + 5. For a non-directory, instantiate a disconnected overlay dentry from the + decoded underlying dentry, the path type and index inode, if found. + 6. For a directory, use the connected underlying decoded dentry, path type + and index, to lookup a connected overlay dentry. Decoding a non-directory file handle may return a disconnected dentry. copy_up of that disconnected dentry will create an upper index entry with @@ -770,9 +774,9 @@ Testsuite There's a testsuite originally developed by David Howells and currently maintained by Amir Goldstein at: - https://github.com/amir73il/unionmount-testsuite.git +https://github.com/amir73il/unionmount-testsuite.git -Run as root: +Run as root:: # cd unionmount-testsuite # ./run --ov --verify diff --git a/Documentation/filesystems/porting.rst b/Documentation/filesystems/porting.rst index 878e72b2f8b7..1be76ef117b3 100644 --- a/Documentation/filesystems/porting.rst +++ b/Documentation/filesystems/porting.rst @@ -1061,3 +1061,76 @@ export_operations ->encode_fh() no longer has a default implementation to encode FILEID_INO32_GEN* file handles. Filesystems that used the default implementation may use the generic helper generic_encode_ino32_fh() explicitly. + +--- + +**mandatory** + +If ->rename() update of .. on cross-directory move needs an exclusion with +directory modifications, do *not* lock the subdirectory in question in your +->rename() - it's done by the caller now [that item should've been added in +28eceeda130f "fs: Lock moved directories"]. + +--- + +**mandatory** + +On same-directory ->rename() the (tautological) update of .. is not protected +by any locks; just don't do it if the old parent is the same as the new one. +We really can't lock two subdirectories in same-directory rename - not without +deadlocks. + +--- + +**mandatory** + +lock_rename() and lock_rename_child() may fail in cross-directory case, if +their arguments do not have a common ancestor. In that case ERR_PTR(-EXDEV) +is returned, with no locks taken. In-tree users updated; out-of-tree ones +would need to do so. + +--- + +**mandatory** + +The list of children anchored in parent dentry got turned into hlist now. +Field names got changed (->d_children/->d_sib instead of ->d_subdirs/->d_child +for anchor/entries resp.), so any affected places will be immediately caught +by compiler. + +--- + +**mandatory** + +->d_delete() instances are now called for dentries with ->d_lock held +and refcount equal to 0. They are not permitted to drop/regain ->d_lock. +None of in-tree instances did anything of that sort. Make sure yours do not... + +--- + +**mandatory** + +->d_prune() instances are now called without ->d_lock held on the parent. +->d_lock on dentry itself is still held; if you need per-parent exclusions (none +of the in-tree instances did), use your own spinlock. + +->d_iput() and ->d_release() are called with victim dentry still in the +list of parent's children. It is still unhashed, marked killed, etc., just not +removed from parent's ->d_children yet. + +Anyone iterating through the list of children needs to be aware of the +half-killed dentries that might be seen there; taking ->d_lock on those will +see them negative, unhashed and with negative refcount, which means that most +of the in-kernel users would've done the right thing anyway without any adjustment. + +--- + +**recommended** + +Block device freezing and thawing have been moved to holder operations. + +Before this change, get_active_super() would only be able to find the +superblock of the main block device, i.e., the one stored in sb->s_bdev. Block +device freezing now works for any block device owned by a given superblock, not +just the main block device. The get_active_super() helper and bd_fsfreeze_sb +pointer are gone. diff --git a/Documentation/filesystems/proc.rst b/Documentation/filesystems/proc.rst index 49ef12df631b..104c6d047d9b 100644 --- a/Documentation/filesystems/proc.rst +++ b/Documentation/filesystems/proc.rst @@ -528,9 +528,9 @@ replaced by copy-on-write) part of the underlying shmem object out on swap. does not take into account swapped out page of underlying shmem objects. "Locked" indicates whether the mapping is locked in memory or not. -"THPeligible" indicates whether the mapping is eligible for allocating THP -pages as well as the THP is PMD mappable or not - 1 if true, 0 otherwise. -It just shows the current status. +"THPeligible" indicates whether the mapping is eligible for allocating +naturally aligned THP pages of any currently enabled size. 1 if true, 0 +otherwise. "VmFlags" field deserves a separate description. This member represents the kernel flags associated with the particular virtual memory area in two letter diff --git a/Documentation/filesystems/squashfs.rst b/Documentation/filesystems/squashfs.rst index df42106bae71..4af8d6207509 100644 --- a/Documentation/filesystems/squashfs.rst +++ b/Documentation/filesystems/squashfs.rst @@ -64,6 +64,66 @@ obtained from this site also. The squashfs-tools development tree is now located on kernel.org git://git.kernel.org/pub/scm/fs/squashfs/squashfs-tools.git +2.1 Mount options +----------------- +=================== ========================================================= +errors=%s Specify whether squashfs errors trigger a kernel panic + or not + + ========== ============================================= + continue errors don't trigger a panic (default) + panic trigger a panic when errors are encountered, + similar to several other filesystems (e.g. + btrfs, ext4, f2fs, GFS2, jfs, ntfs, ubifs) + + This allows a kernel dump to be saved, + useful for analyzing and debugging the + corruption. + ========== ============================================= +threads=%s Select the decompression mode or the number of threads + + If SQUASHFS_CHOICE_DECOMP_BY_MOUNT is set: + + ========== ============================================= + single use single-threaded decompression (default) + + Only one block (data or metadata) can be + decompressed at any one time. This limits + CPU and memory usage to a minimum, but it + also gives poor performance on parallel I/O + workloads when using multiple CPU machines + due to waiting on decompressor availability. + multi use up to two parallel decompressors per core + + If you have a parallel I/O workload and your + system has enough memory, using this option + may improve overall I/O performance. It + dynamically allocates decompressors on a + demand basis. + percpu use a maximum of one decompressor per core + + It uses percpu variables to ensure + decompression is load-balanced across the + cores. + 1|2|3|... configure the number of threads used for + decompression + + The upper limit is num_online_cpus() * 2. + ========== ============================================= + + If SQUASHFS_CHOICE_DECOMP_BY_MOUNT is **not** set and + SQUASHFS_DECOMP_MULTI, SQUASHFS_MOUNT_DECOMP_THREADS are + both set: + + ========== ============================================= + 2|3|... configure the number of threads used for + decompression + + The upper limit is num_online_cpus() * 2. + ========== ============================================= + +=================== ========================================================= + 3. Squashfs Filesystem Design ----------------------------- diff --git a/Documentation/filesystems/vfs.rst b/Documentation/filesystems/vfs.rst index 99acc2e98673..eebcc0f9e2bc 100644 --- a/Documentation/filesystems/vfs.rst +++ b/Documentation/filesystems/vfs.rst @@ -437,7 +437,7 @@ field. This is a pointer to a "struct inode_operations" which describes the methods that can be performed on individual inodes. -struct xattr_handlers +struct xattr_handler --------------------- On filesystems that support extended attributes (xattrs), the s_xattr @@ -823,7 +823,7 @@ cache in your filesystem. The following members are defined: bool (*is_partially_uptodate) (struct folio *, size_t from, size_t count); void (*is_dirty_writeback)(struct folio *, bool *, bool *); - int (*error_remove_page) (struct mapping *mapping, struct page *page); + int (*error_remove_folio)(struct mapping *mapping, struct folio *); int (*swap_activate)(struct swap_info_struct *sis, struct file *f, sector_t *span) int (*swap_deactivate)(struct file *); int (*swap_rw)(struct kiocb *iocb, struct iov_iter *iter); @@ -1034,8 +1034,8 @@ cache in your filesystem. The following members are defined: VM if a folio should be treated as dirty or writeback for the purposes of stalling. -``error_remove_page`` - normally set to generic_error_remove_page if truncation is ok +``error_remove_folio`` + normally set to generic_error_remove_folio if truncation is ok for this address space. Used for memory failure handling. Setting this implies you deal with pages going away under you, unless you have them locked or reference counts increased. diff --git a/Documentation/filesystems/xfs/index.rst b/Documentation/filesystems/xfs/index.rst new file mode 100644 index 000000000000..ab66c57a5d18 --- /dev/null +++ b/Documentation/filesystems/xfs/index.rst @@ -0,0 +1,14 @@ +.. SPDX-License-Identifier: GPL-2.0 + +============================ +XFS Filesystem Documentation +============================ + +.. toctree:: + :maxdepth: 2 + :numbered: + + xfs-delayed-logging-design + xfs-maintainer-entry-profile + xfs-self-describing-metadata + xfs-online-fsck-design diff --git a/Documentation/filesystems/xfs-delayed-logging-design.rst b/Documentation/filesystems/xfs/xfs-delayed-logging-design.rst index 6402ab8e370c..6402ab8e370c 100644 --- a/Documentation/filesystems/xfs-delayed-logging-design.rst +++ b/Documentation/filesystems/xfs/xfs-delayed-logging-design.rst diff --git a/Documentation/filesystems/xfs-maintainer-entry-profile.rst b/Documentation/filesystems/xfs/xfs-maintainer-entry-profile.rst index 32b6ac4ca9d6..32b6ac4ca9d6 100644 --- a/Documentation/filesystems/xfs-maintainer-entry-profile.rst +++ b/Documentation/filesystems/xfs/xfs-maintainer-entry-profile.rst diff --git a/Documentation/filesystems/xfs-online-fsck-design.rst b/Documentation/filesystems/xfs/xfs-online-fsck-design.rst index a0678101a7d0..352516feef6f 100644 --- a/Documentation/filesystems/xfs-online-fsck-design.rst +++ b/Documentation/filesystems/xfs/xfs-online-fsck-design.rst @@ -962,7 +962,7 @@ disk, but these buffer verifiers cannot provide any consistency checking between metadata structures. For more information, please see the documentation for -Documentation/filesystems/xfs-self-describing-metadata.rst +Documentation/filesystems/xfs/xfs-self-describing-metadata.rst Reverse Mapping --------------- diff --git a/Documentation/filesystems/xfs-self-describing-metadata.rst b/Documentation/filesystems/xfs/xfs-self-describing-metadata.rst index a10c4ae6955e..a10c4ae6955e 100644 --- a/Documentation/filesystems/xfs-self-describing-metadata.rst +++ b/Documentation/filesystems/xfs/xfs-self-describing-metadata.rst diff --git a/Documentation/i2c/i2c-address-translators.rst b/Documentation/i2c/i2c-address-translators.rst index b22ce9f41ecf..6845c114e472 100644 --- a/Documentation/i2c/i2c-address-translators.rst +++ b/Documentation/i2c/i2c-address-translators.rst @@ -71,7 +71,7 @@ Transaction: - Physical I2C transaction on bus A, slave address 0x20 - ATR chip detects transaction on address 0x20, finds it in table, propagates transaction on bus B with address translated to 0x10, - keeps clock streched on bus A waiting for reply + keeps clock stretched on bus A waiting for reply - Slave X chip (on bus B) detects transaction at its own physical address 0x10 and replies normally - ATR chip stops clock stretching and forwards reply on bus A, diff --git a/Documentation/index.rst b/Documentation/index.rst index 9dfdc826618c..36e61783437c 100644 --- a/Documentation/index.rst +++ b/Documentation/index.rst @@ -113,6 +113,7 @@ to ReStructured Text format, or are simply too old. :maxdepth: 1 staging/index + RAS/ras Translations diff --git a/Documentation/input/input_kapi.rst b/Documentation/input/input_kapi.rst index 41f1b7e6b78e..9937522daa9b 100644 --- a/Documentation/input/input_kapi.rst +++ b/Documentation/input/input_kapi.rst @@ -4,11 +4,8 @@ Linux Input Subsystem kernel API ################################ -.. class:: toc-title - - Table of Contents - .. toctree:: + :caption: Table of Contents :maxdepth: 2 :numbered: diff --git a/Documentation/input/input_uapi.rst b/Documentation/input/input_uapi.rst index 4a0391609327..8275b4223a84 100644 --- a/Documentation/input/input_uapi.rst +++ b/Documentation/input/input_uapi.rst @@ -4,11 +4,8 @@ Linux Input Subsystem userspace API ################################### -.. class:: toc-title - - Table of Contents - .. toctree:: + :caption: Table of Contents :maxdepth: 2 :numbered: diff --git a/Documentation/input/joydev/index.rst b/Documentation/input/joydev/index.rst index ebcff43056e2..d03d6f6cbfab 100644 --- a/Documentation/input/joydev/index.rst +++ b/Documentation/input/joydev/index.rst @@ -6,11 +6,8 @@ Linux Joystick support :Copyright: |copy| 1996-2000 Vojtech Pavlik <vojtech@ucw.cz> - Sponsored by SuSE -.. class:: toc-title - - Table of Contents - .. toctree:: + :caption: Table of Contents :maxdepth: 3 joystick diff --git a/Documentation/livepatch/callbacks.rst b/Documentation/livepatch/callbacks.rst index 470944aa8658..914445784ce4 100644 --- a/Documentation/livepatch/callbacks.rst +++ b/Documentation/livepatch/callbacks.rst @@ -110,7 +110,7 @@ Global data update ------------------ A pre-patch callback can be useful to update a global variable. For -example, 75ff39ccc1bd ("tcp: make challenge acks less predictable") +example, commit 75ff39ccc1bd ("tcp: make challenge acks less predictable") changes a global sysctl, as well as patches the tcp_send_challenge_ack() function. @@ -126,7 +126,7 @@ Although __init and probe functions are not directly livepatch-able, it may be possible to implement similar updates via pre/post-patch callbacks. -The commit ``48900cb6af42 ("virtio-net: drop NETIF_F_FRAGLIST")`` change the way that +The commit 48900cb6af42 ("virtio-net: drop NETIF_F_FRAGLIST") change the way that virtnet_probe() initialized its driver's net_device features. A pre/post-patch callback could iterate over all such devices, making a similar change to their hw_features value. (Client functions of the diff --git a/Documentation/locking/mutex-design.rst b/Documentation/locking/mutex-design.rst index 78540cd7f54b..7c30b4aa5e28 100644 --- a/Documentation/locking/mutex-design.rst +++ b/Documentation/locking/mutex-design.rst @@ -101,6 +101,24 @@ features that make lock debugging easier and faster: - Detects multi-task circular deadlocks and prints out all affected locks and tasks (and only those tasks). +Mutexes - and most other sleeping locks like rwsems - do not provide an +implicit reference for the memory they occupy, which reference is released +with mutex_unlock(). + +[ This is in contrast with spin_unlock() [or completion_done()], which + APIs can be used to guarantee that the memory is not touched by the + lock implementation after spin_unlock()/completion_done() releases + the lock. ] + +mutex_unlock() may access the mutex structure even after it has internally +released the lock already - so it's not safe for another context to +acquire the mutex and assume that the mutex_unlock() context is not using +the structure anymore. + +The mutex user must ensure that the mutex is not destroyed while a +release operation is still in progress - in other words, callers of +mutex_unlock() must ensure that the mutex stays alive until mutex_unlock() +has returned. Interfaces ---------- diff --git a/Documentation/maintainer/maintainer-entry-profile.rst b/Documentation/maintainer/maintainer-entry-profile.rst index 7ad4bfc2cc03..18cee1edaecb 100644 --- a/Documentation/maintainer/maintainer-entry-profile.rst +++ b/Documentation/maintainer/maintainer-entry-profile.rst @@ -105,4 +105,4 @@ to do something different in the near future. ../driver-api/media/maintainer-entry-profile ../driver-api/vfio-pci-device-specific-driver-acceptance ../nvme/feature-and-quirk-policy - ../filesystems/xfs-maintainer-entry-profile + ../filesystems/xfs/xfs-maintainer-entry-profile diff --git a/Documentation/misc-devices/index.rst b/Documentation/misc-devices/index.rst index 7de16797987a..2d0ce9138588 100644 --- a/Documentation/misc-devices/index.rst +++ b/Documentation/misc-devices/index.rst @@ -7,11 +7,8 @@ Assorted Miscellaneous Devices Documentation This documentation contains information for assorted devices that do not fit into other categories. -.. class:: toc-title - - Table of contents - .. toctree:: + :caption: Table of contents :maxdepth: 2 ad525x_dpot diff --git a/Documentation/mm/arch_pgtable_helpers.rst b/Documentation/mm/arch_pgtable_helpers.rst index c82e3ee20e51..2466d3363af7 100644 --- a/Documentation/mm/arch_pgtable_helpers.rst +++ b/Documentation/mm/arch_pgtable_helpers.rst @@ -18,8 +18,6 @@ PTE Page Table Helpers +---------------------------+--------------------------------------------------+ | pte_same | Tests whether both PTE entries are the same | +---------------------------+--------------------------------------------------+ -| pte_bad | Tests a non-table mapped PTE | -+---------------------------+--------------------------------------------------+ | pte_present | Tests a valid mapped PTE | +---------------------------+--------------------------------------------------+ | pte_young | Tests a young PTE | diff --git a/Documentation/mm/damon/design.rst b/Documentation/mm/damon/design.rst index 1f7e0586b5fa..1bb69524a62e 100644 --- a/Documentation/mm/damon/design.rst +++ b/Documentation/mm/damon/design.rst @@ -5,6 +5,18 @@ Design ====== +.. _damon_design_execution_model_and_data_structures: + +Execution Model and Data Structures +=================================== + +The monitoring-related information including the monitoring request +specification and DAMON-based operation schemes are stored in a data structure +called DAMON ``context``. DAMON executes each context with a kernel thread +called ``kdamond``. Multiple kdamonds could run in parallel, for different +types of monitoring. + + Overall Architecture ==================== @@ -346,6 +358,19 @@ the weight will be respected are up to the underlying prioritization mechanism implementation. +.. _damon_design_damos_quotas_auto_tuning: + +Aim-oriented Feedback-driven Auto-tuning +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Automatic feedback-driven quota tuning. Instead of setting the absolute quota +value, users can repeatedly provide numbers representing how much of their goal +for the scheme is achieved as feedback. DAMOS then automatically tunes the +aggressiveness (the quota) of the corresponding scheme. For example, if DAMOS +is under achieving the goal, DAMOS automatically increases the quota. If DAMOS +is over achieving the goal, it decreases the quota. + + .. _damon_design_damos_watermarks: Watermarks @@ -477,15 +502,3 @@ modules for proactive reclamation and LRU lists manipulation are provided. For more detail, please read the usage documents for those (:doc:`/admin-guide/mm/damon/reclaim` and :doc:`/admin-guide/mm/damon/lru_sort`). - - -.. _damon_design_execution_model_and_data_structures: - -Execution Model and Data Structures -=================================== - -The monitoring-related information including the monitoring request -specification and DAMON-based operation schemes are stored in a data structure -called DAMON ``context``. DAMON executes each context with a kernel thread -called ``kdamond``. Multiple kdamonds could run in parallel, for different -types of monitoring. diff --git a/Documentation/mm/transhuge.rst b/Documentation/mm/transhuge.rst index 9a607059ea11..93c9239b9ebe 100644 --- a/Documentation/mm/transhuge.rst +++ b/Documentation/mm/transhuge.rst @@ -117,7 +117,7 @@ pages: - map/unmap of a PMD entry for the whole THP increment/decrement folio->_entire_mapcount and also increment/decrement - folio->_nr_pages_mapped by COMPOUND_MAPPED when _entire_mapcount + folio->_nr_pages_mapped by ENTIRELY_MAPPED when _entire_mapcount goes from -1 to 0 or 0 to -1. - map/unmap of individual pages with PTE entry increment/decrement @@ -156,7 +156,7 @@ Partial unmap and deferred_split_folio() Unmapping part of THP (with munmap() or other way) is not going to free memory immediately. Instead, we detect that a subpage of THP is not in use -in page_remove_rmap() and queue the THP for splitting if memory pressure +in folio_remove_rmap_*() and queue the THP for splitting if memory pressure comes. Splitting will free up unused subpages. Splitting the page right away is not an option due to locking context in diff --git a/Documentation/mm/unevictable-lru.rst b/Documentation/mm/unevictable-lru.rst index 67f1338440a5..b6a07a26b10d 100644 --- a/Documentation/mm/unevictable-lru.rst +++ b/Documentation/mm/unevictable-lru.rst @@ -486,7 +486,7 @@ munlock the pages if we're removing the last VM_LOCKED VMA that maps the pages. Before the unevictable/mlock changes, mlocking did not mark the pages in any way, so unmapping them required no processing. -For each PTE (or PMD) being unmapped from a VMA, page_remove_rmap() calls +For each PTE (or PMD) being unmapped from a VMA, folio_remove_rmap_*() calls munlock_vma_folio(), which calls munlock_folio() when the VMA is VM_LOCKED (unless it was a PTE mapping of a part of a transparent huge page). @@ -511,7 +511,7 @@ userspace; truncation even unmaps and deletes any private anonymous pages which had been Copied-On-Write from the file pages now being truncated. Mlocked pages can be munlocked and deleted in this way: like with munmap(), -for each PTE (or PMD) being unmapped from a VMA, page_remove_rmap() calls +for each PTE (or PMD) being unmapped from a VMA, folio_remove_rmap_*() calls munlock_vma_folio(), which calls munlock_folio() when the VMA is VM_LOCKED (unless it was a PTE mapping of a part of a transparent huge page). diff --git a/Documentation/netlink/netlink-raw.yaml b/Documentation/netlink/netlink-raw.yaml index 775cce8c548a..04b92f1a5cd6 100644 --- a/Documentation/netlink/netlink-raw.yaml +++ b/Documentation/netlink/netlink-raw.yaml @@ -126,8 +126,10 @@ properties: name: type: string type: - description: The netlink attribute type - enum: [ u8, u16, u32, u64, s8, s16, s32, s64, string, binary ] + description: | + The netlink attribute type. Members of type 'binary' or 'pad' + must also have the 'len' property set. + enum: [ u8, u16, u32, u64, s8, s16, s32, s64, string, binary, pad ] len: $ref: '#/$defs/len-or-define' byte-order: @@ -150,6 +152,14 @@ properties: the right formatting mechanism when displaying values of this type. enum: [ hex, mac, fddi, ipv4, ipv6, uuid ] + if: + properties: + type: + oneOf: + - const: binary + - const: pad + then: + required: [ len ] # End genetlink-legacy attribute-sets: @@ -200,8 +210,10 @@ properties: type: string type: &attr-type description: The netlink attribute type - enum: [ unused, pad, flag, binary, u8, u16, u32, u64, s32, s64, - string, nest, array-nest, nest-type-value ] + enum: [ unused, pad, flag, binary, bitfield32, + u8, u16, u32, u64, s8, s16, s32, s64, + string, nest, array-nest, nest-type-value, + sub-message ] doc: description: Documentation of the attribute. type: string @@ -260,6 +272,17 @@ properties: description: Name of the struct type used for the attribute. type: string # End genetlink-legacy + # Start netlink-raw + sub-message: + description: | + Name of the sub-message definition to use for the attribute. + type: string + selector: + description: | + Name of the attribute to use for dynamic selection of sub-message + format specifier. + type: string + # End netlink-raw # Make sure name-prefix does not appear in subsets (subsets inherit naming) dependencies: @@ -282,6 +305,43 @@ properties: items: required: [ type ] + # Start netlink-raw + sub-messages: + description: Definition of sub message attributes + type: array + items: + type: object + additionalProperties: False + required: [ name, formats ] + properties: + name: + description: Name of the sub-message definition + type: string + formats: + description: Dynamically selected format specifiers + type: array + items: + type: object + additionalProperties: False + required: [ value ] + properties: + value: + description: | + Value to match for dynamic selection of sub-message format + specifier. + type: string + fixed-header: + description: | + Name of the struct definition to use as the fixed header + for the sub message. + type: string + attribute-set: + description: | + Name of the attribute space from which to resolve attributes + in the sub message. + type: string + # End netlink-raw + operations: description: Operations supported by the protocol. type: object diff --git a/Documentation/netlink/specs/devlink.yaml b/Documentation/netlink/specs/devlink.yaml index 572d83a414d0..cf6eaa0da821 100644 --- a/Documentation/netlink/specs/devlink.yaml +++ b/Documentation/netlink/specs/devlink.yaml @@ -77,6 +77,14 @@ definitions: name: ipsec-packet-bit - type: enum + name: rate-type + entries: + - + name: leaf + - + name: node + - + type: enum name: sb-threshold-type entries: - @@ -113,6 +121,16 @@ definitions: name: basic - type: enum + name: dpipe-header-id + entries: + - + name: ethernet + - + name: ipv4 + - + name: ipv6 + - + type: enum name: dpipe-match-type entries: - @@ -174,6 +192,16 @@ definitions: name: trap - name: mirror + - + type: enum + name: trap-type + entries: + - + name: drop + - + name: exception + - + name: control attribute-sets: - @@ -194,27 +222,45 @@ attribute-sets: name: port-type type: u16 enum: port-type - - # TODO: fill in the attributes in between - + - + name: port-desired-type + type: u16 + - + name: port-netdev-ifindex + type: u32 + - + name: port-netdev-name + type: string + - + name: port-ibdev-name + type: string - name: port-split-count type: u32 - value: 9 - - # TODO: fill in the attributes in between - + - + name: port-split-group + type: u32 - name: sb-index type: u32 - value: 11 - - # TODO: fill in the attributes in between - + - + name: sb-size + type: u32 + - + name: sb-ingress-pool-count + type: u16 + - + name: sb-egress-pool-count + type: u16 + - + name: sb-ingress-tc-count + type: u16 + - + name: sb-egress-tc-count + type: u16 - name: sb-pool-index type: u16 - value: 17 - name: sb-pool-type type: u8 @@ -232,16 +278,16 @@ attribute-sets: - name: sb-tc-index type: u16 - value: 22 - - # TODO: fill in the attributes in between - + - + name: sb-occ-cur + type: u32 + - + name: sb-occ-max + type: u32 - name: eswitch-mode type: u16 - value: 25 enum: eswitch-mode - - name: eswitch-inline-mode type: u16 @@ -347,6 +393,7 @@ attribute-sets: - name: dpipe-header-id type: u32 + enum: dpipe-header-id - name: dpipe-header-fields type: nest @@ -381,7 +428,6 @@ attribute-sets: - name: eswitch-encap-mode type: u8 - value: 62 enum: eswitch-encap-mode - name: resource-list @@ -433,20 +479,25 @@ attribute-sets: name: port-flavour type: u16 enum: port-flavour - - # TODO: fill in the attributes in between - + - + name: port-number + type: u32 + - + name: port-split-subport-number + type: u32 + - + name: param + type: nest + nested-attributes: dl-param - name: param-name type: string - value: 81 - - # TODO: fill in the attributes in between - + - + name: param-generic + type: flag - name: param-type type: u8 - value: 83 # TODO: fill in the attributes in between @@ -458,20 +509,34 @@ attribute-sets: - name: region-name type: string - - # TODO: fill in the attributes in between - + - + name: region-size + type: u64 + - + name: region-snapshots + type: nest + nested-attributes: dl-region-snapshots + - + name: region-snapshot + type: nest + nested-attributes: dl-region-snapshot - name: region-snapshot-id type: u32 - value: 92 - - # TODO: fill in the attributes in between - + - + name: region-chunks + type: nest + nested-attributes: dl-region-chunks + - + name: region-chunk + type: nest + nested-attributes: dl-region-chunk + - + name: region-chunk-data + type: binary - name: region-chunk-addr type: u64 - value: 96 - name: region-chunk-len type: u64 @@ -502,14 +567,13 @@ attribute-sets: - name: info-version-value type: string - - # TODO: fill in the attributes in between - + - + name: sb-pool-cell-size + type: u32 - name: fmsg type: nest nested-attributes: dl-fmsg - value: 106 - name: fmsg-obj-nest-start type: flag @@ -525,20 +589,35 @@ attribute-sets: - name: fmsg-obj-name type: string + - + name: fmsg-obj-value-type + type: u8 # TODO: fill in the attributes in between - + name: health-reporter + type: nest + value: 114 + nested-attributes: dl-health-reporter + - name: health-reporter-name type: string - value: 115 - - # TODO: fill in the attributes in between - + - + name: health-reporter-state + type: u8 + - + name: health-reporter-err-count + type: u64 + - + name: health-reporter-recover-count + type: u64 + - + name: health-reporter-dump-ts + type: u64 - name: health-reporter-graceful-period type: u64 - value: 120 - name: health-reporter-auto-recover type: u8 @@ -548,55 +627,64 @@ attribute-sets: - name: flash-update-component type: string - - # TODO: fill in the attributes in between - + - + name: flash-update-status-msg + type: string + - + name: flash-update-status-done + type: u64 + - + name: flash-update-status-total + type: u64 - name: port-pci-pf-number type: u16 - value: 127 - - # TODO: fill in the attributes in between - + - + name: port-pci-vf-number + type: u16 + - + name: stats + type: nest + nested-attributes: dl-attr-stats - name: trap-name type: string - value: 130 - name: trap-action type: u8 enum: trap-action - - # TODO: fill in the attributes in between - + - + name: trap-type + type: u8 + enum: trap-type + - + name: trap-generic + type: flag + - + name: trap-metadata + type: nest + nested-attributes: dl-trap-metadata - name: trap-group-name type: string - value: 135 - - name: reload-failed type: u8 - - # TODO: fill in the attributes in between - + - + name: health-reporter-dump-ts-ns + type: u64 - name: netns-fd type: u32 - value: 138 - name: netns-pid type: u32 - name: netns-id type: u32 - - # TODO: fill in the attributes in between - - name: health-reporter-auto-dump type: u8 - value: 141 - name: trap-policer-id type: u32 @@ -610,22 +698,29 @@ attribute-sets: name: port-function type: nest nested-attributes: dl-port-function - - # TODO: fill in the attributes in between - + - + name: info-board-serial-number + type: string + - + name: port-lanes + type: u32 + - + name: port-splittable + type: u8 + - + name: port-external + type: u8 - name: port-controller-number type: u32 - value: 150 - - # TODO: fill in the attributes in between - + - + name: flash-update-status-timeout + type: u64 - name: flash-update-overwrite-mask type: bitfield32 enum: flash-overwrite enum-as-flags: True - value: 152 - name: reload-action type: u8 @@ -673,20 +768,16 @@ attribute-sets: type: nest multi-attr: true nested-attributes: dl-reload-act-stats - - # TODO: fill in the attributes in between - - name: port-pci-sf-number type: u32 - value: 164 - - # TODO: fill in the attributes in between - + - + name: rate-type + type: u16 + enum: rate-type - name: rate-tx-share type: u64 - value: 166 - name: rate-tx-max type: u64 @@ -696,20 +787,22 @@ attribute-sets: - name: rate-parent-node-name type: string - - # TODO: fill in the attributes in between - + - + name: region-max-snapshots + type: u32 - name: linecard-index type: u32 - value: 171 - - # TODO: fill in the attributes in between - + - + name: linecard-state + type: u8 - name: linecard-type type: string - value: 173 + - + name: linecard-supported-types + type: nest + nested-attributes: dl-linecard-supported-types # TODO: fill in the attributes in between @@ -736,12 +829,14 @@ attribute-sets: name: reload-stats - name: remote-reload-stats + - name: dl-reload-stats subset-of: devlink attributes: - name: reload-action-info + - name: dl-reload-act-info subset-of: devlink @@ -750,12 +845,14 @@ attribute-sets: name: reload-action - name: reload-action-stats + - name: dl-reload-act-stats subset-of: devlink attributes: - name: reload-stats-entry + - name: dl-reload-stats-entry subset-of: devlink @@ -764,6 +861,7 @@ attribute-sets: name: reload-stats-limit - name: reload-stats-value + - name: dl-info-version subset-of: devlink @@ -772,6 +870,7 @@ attribute-sets: name: info-version-name - name: info-version-value + - name: dl-port-function name-prefix: devlink-port-fn-attr- @@ -1006,6 +1105,49 @@ attribute-sets: name: resource - + name: dl-param + subset-of: devlink + attributes: + - + name: param-name + - + name: param-generic + - + name: param-type + + # TODO: fill in the attribute param-value-list + + - + name: dl-region-snapshots + subset-of: devlink + attributes: + - + name: region-snapshot + + - + name: dl-region-snapshot + subset-of: devlink + attributes: + - + name: region-snapshot-id + + - + name: dl-region-chunks + subset-of: devlink + attributes: + - + name: region-chunk + + - + name: dl-region-chunk + subset-of: devlink + attributes: + - + name: region-chunk-data + - + name: region-chunk-addr + + - name: dl-fmsg subset-of: devlink attributes: @@ -1021,6 +1163,62 @@ attribute-sets: name: fmsg-obj-name - + name: dl-health-reporter + subset-of: devlink + attributes: + - + name: health-reporter-name + - + name: health-reporter-state + - + name: health-reporter-err-count + - + name: health-reporter-recover-count + - + name: health-reporter-graceful-period + - + name: health-reporter-auto-recover + - + name: health-reporter-dump-ts + - + name: health-reporter-dump-ts-ns + - + name: health-reporter-auto-dump + + - + name: dl-attr-stats + name-prefix: devlink-attr- + attributes: + - name: stats-rx-packets + type: u64 + value: 0 + - + name: stats-rx-bytes + type: u64 + - + name: stats-rx-dropped + type: u64 + + - + name: dl-trap-metadata + name-prefix: devlink-attr- + attributes: + - + name: trap-metadata-type-in-port + type: flag + value: 0 + - + name: trap-metadata-type-fa-cookie + type: flag + + - + name: dl-linecard-supported-types + subset-of: devlink + attributes: + - + name: linecard-type + + - name: dl-selftest-id name-prefix: devlink-attr-selftest-id- attributes: @@ -1077,6 +1275,7 @@ operations: reply: value: 3 # due to a bug, port dump returns DEVLINK_CMD_NEW attributes: *port-id-attrs + - name: port-set doc: Set devlink port instances. @@ -1484,8 +1683,8 @@ operations: dont-validate: [ strict ] flags: [ admin-perm ] do: - pre: devlink-nl-pre-doit - post: devlink-nl-post-doit + pre: devlink-nl-pre-doit-dev-lock + post: devlink-nl-post-doit-dev-lock request: attributes: - bus-name @@ -2055,3 +2254,14 @@ operations: - bus-name - dev-name - selftests + + - + name: notify-filter-set + doc: Set notification messages socket filter. + attribute-set: devlink + do: + request: + attributes: + - bus-name + - dev-name + - port-index diff --git a/Documentation/netlink/specs/dpll.yaml b/Documentation/netlink/specs/dpll.yaml index cf8abe1c0550..b14aed18065f 100644 --- a/Documentation/netlink/specs/dpll.yaml +++ b/Documentation/netlink/specs/dpll.yaml @@ -296,6 +296,16 @@ attribute-sets: - name: phase-offset type: s64 + - + name: fractional-frequency-offset + type: sint + doc: | + The FFO (Fractional Frequency Offset) between the RX and TX + symbol rate on the media associated with the pin: + (rx_frequency-tx_frequency)/rx_frequency + Value is in PPM (parts per million). + This may be implemented for example for pin of type + PIN_TYPE_SYNCE_ETH_PORT. - name: pin-parent-device subset-of: pin @@ -460,6 +470,7 @@ operations: - phase-adjust-min - phase-adjust-max - phase-adjust + - fractional-frequency-offset dump: pre: dpll-lock-dumpit diff --git a/Documentation/netlink/specs/ethtool.yaml b/Documentation/netlink/specs/ethtool.yaml index 5c7a65b009b4..197208f419dc 100644 --- a/Documentation/netlink/specs/ethtool.yaml +++ b/Documentation/netlink/specs/ethtool.yaml @@ -908,6 +908,9 @@ attribute-sets: - name: hkey type: binary + - + name: input_xfrm + type: u32 - name: plca attributes: @@ -1598,6 +1601,7 @@ operations: - hfunc - indir - hkey + - input_xfrm dump: *rss-get-op - name: plca-get-cfg diff --git a/Documentation/netlink/specs/mptcp.yaml b/Documentation/netlink/specs/mptcp_pm.yaml index 49f90cfb4698..49f90cfb4698 100644 --- a/Documentation/netlink/specs/mptcp.yaml +++ b/Documentation/netlink/specs/mptcp_pm.yaml diff --git a/Documentation/netlink/specs/netdev.yaml b/Documentation/netlink/specs/netdev.yaml index 14511b13f305..3addac970680 100644 --- a/Documentation/netlink/specs/netdev.yaml +++ b/Documentation/netlink/specs/netdev.yaml @@ -45,7 +45,6 @@ definitions: - type: flags name: xdp-rx-metadata - render-max: true entries: - name: timestamp @@ -55,6 +54,26 @@ definitions: name: hash doc: Device is capable of exposing receive packet hash via bpf_xdp_metadata_rx_hash(). + - + name: vlan-tag + doc: + Device is capable of exposing receive packet VLAN tag via bpf_xdp_metadata_rx_vlan_tag(). + - + type: flags + name: xsk-flags + entries: + - + name: tx-timestamp + doc: + HW timestamping egress packets is supported by the driver. + - + name: tx-checksum + doc: + L3 checksum HW offload is supported by the driver. + - + name: queue-type + type: enum + entries: [ rx, tx ] attribute-sets: - @@ -86,6 +105,165 @@ attribute-sets: See Documentation/networking/xdp-rx-metadata.rst for more details. type: u64 enum: xdp-rx-metadata + - + name: xsk-features + doc: Bitmask of enabled AF_XDP features. + type: u64 + enum: xsk-flags + - + name: page-pool + attributes: + - + name: id + doc: Unique ID of a Page Pool instance. + type: uint + checks: + min: 1 + max: u32-max + - + name: ifindex + doc: | + ifindex of the netdev to which the pool belongs. + May be reported as 0 if the page pool was allocated for a netdev + which got destroyed already (page pools may outlast their netdevs + because they wait for all memory to be returned). + type: u32 + checks: + min: 1 + max: s32-max + - + name: napi-id + doc: Id of NAPI using this Page Pool instance. + type: uint + checks: + min: 1 + max: u32-max + - + name: inflight + type: uint + doc: | + Number of outstanding references to this page pool (allocated + but yet to be freed pages). Allocated pages may be held in + socket receive queues, driver receive ring, page pool recycling + ring, the page pool cache, etc. + - + name: inflight-mem + type: uint + doc: | + Amount of memory held by inflight pages. + - + name: detach-time + type: uint + doc: | + Seconds in CLOCK_BOOTTIME of when Page Pool was detached by + the driver. Once detached Page Pool can no longer be used to + allocate memory. + Page Pools wait for all the memory allocated from them to be freed + before truly disappearing. "Detached" Page Pools cannot be + "re-attached", they are just waiting to disappear. + Attribute is absent if Page Pool has not been detached, and + can still be used to allocate new memory. + - + name: page-pool-info + subset-of: page-pool + attributes: + - + name: id + - + name: ifindex + - + name: page-pool-stats + doc: | + Page pool statistics, see docs for struct page_pool_stats + for information about individual statistics. + attributes: + - + name: info + doc: Page pool identifying information. + type: nest + nested-attributes: page-pool-info + - + name: alloc-fast + type: uint + value: 8 # reserve some attr ids in case we need more metadata later + - + name: alloc-slow + type: uint + - + name: alloc-slow-high-order + type: uint + - + name: alloc-empty + type: uint + - + name: alloc-refill + type: uint + - + name: alloc-waive + type: uint + - + name: recycle-cached + type: uint + - + name: recycle-cache-full + type: uint + - + name: recycle-ring + type: uint + - + name: recycle-ring-full + type: uint + - + name: recycle-released-refcnt + type: uint + + - + name: napi + attributes: + - + name: ifindex + doc: ifindex of the netdevice to which NAPI instance belongs. + type: u32 + checks: + min: 1 + - + name: id + doc: ID of the NAPI instance. + type: u32 + - + name: irq + doc: The associated interrupt vector number for the napi + type: u32 + - + name: pid + doc: PID of the napi thread, if NAPI is configured to operate in + threaded mode. If NAPI is not in threaded mode (i.e. uses normal + softirq context), the attribute will be absent. + type: u32 + - + name: queue + attributes: + - + name: id + doc: Queue index; most queue types are indexed like a C array, with + indexes starting at 0 and ending at queue count - 1. Queue indexes + are scoped to an interface and queue type. + type: u32 + - + name: ifindex + doc: ifindex of the netdevice to which the queue belongs. + type: u32 + checks: + min: 1 + - + name: type + doc: Queue type as rx, tx. Each queue type defines a separate ID space. + type: u32 + enum: queue-type + - + name: napi-id + doc: ID of the NAPI instance which services this queue. + type: u32 operations: list: @@ -103,6 +281,7 @@ operations: - xdp-features - xdp-zc-max-segs - xdp-rx-metadata-features + - xsk-features dump: reply: *dev-all - @@ -120,8 +299,116 @@ operations: doc: Notification about device configuration being changed. notify: dev-get mcgrp: mgmt + - + name: page-pool-get + doc: | + Get / dump information about Page Pools. + (Only Page Pools associated with a net_device can be listed.) + attribute-set: page-pool + do: + request: + attributes: + - id + reply: &pp-reply + attributes: + - id + - ifindex + - napi-id + - inflight + - inflight-mem + - detach-time + dump: + reply: *pp-reply + config-cond: page-pool + - + name: page-pool-add-ntf + doc: Notification about page pool appearing. + notify: page-pool-get + mcgrp: page-pool + config-cond: page-pool + - + name: page-pool-del-ntf + doc: Notification about page pool disappearing. + notify: page-pool-get + mcgrp: page-pool + config-cond: page-pool + - + name: page-pool-change-ntf + doc: Notification about page pool configuration being changed. + notify: page-pool-get + mcgrp: page-pool + config-cond: page-pool + - + name: page-pool-stats-get + doc: Get page pool statistics. + attribute-set: page-pool-stats + do: + request: + attributes: + - info + reply: &pp-stats-reply + attributes: + - info + - alloc-fast + - alloc-slow + - alloc-slow-high-order + - alloc-empty + - alloc-refill + - alloc-waive + - recycle-cached + - recycle-cache-full + - recycle-ring + - recycle-ring-full + - recycle-released-refcnt + dump: + reply: *pp-stats-reply + config-cond: page-pool-stats + - + name: queue-get + doc: Get queue information from the kernel. + Only configured queues will be reported (as opposed to all available + hardware queues). + attribute-set: queue + do: + request: + attributes: + - ifindex + - type + - id + reply: &queue-get-op + attributes: + - id + - type + - napi-id + - ifindex + dump: + request: + attributes: + - ifindex + reply: *queue-get-op + - + name: napi-get + doc: Get information about NAPI instances configured on the system. + attribute-set: napi + do: + request: + attributes: + - id + reply: &napi-get-op + attributes: + - id + - ifindex + - irq + - pid + dump: + request: + attributes: + - ifindex + reply: *napi-get-op mcast-groups: list: - name: mgmt + - + name: page-pool diff --git a/Documentation/netlink/specs/ovs_datapath.yaml b/Documentation/netlink/specs/ovs_datapath.yaml index f709c26c3e92..edc8c95ca6f5 100644 --- a/Documentation/netlink/specs/ovs_datapath.yaml +++ b/Documentation/netlink/specs/ovs_datapath.yaml @@ -20,6 +20,7 @@ definitions: name: user-features type: flags name-prefix: ovs-dp-f- + enum-name: entries: - name: unaligned @@ -142,7 +143,6 @@ operations: do: request: attributes: - - dp-ifindex - name - upcall-pid - user-features @@ -154,7 +154,6 @@ operations: do: request: attributes: - - dp-ifindex - name mcast-groups: diff --git a/Documentation/netlink/specs/ovs_flow.yaml b/Documentation/netlink/specs/ovs_flow.yaml index 109ca1f57b6c..4fdfc6b5cae9 100644 --- a/Documentation/netlink/specs/ovs_flow.yaml +++ b/Documentation/netlink/specs/ovs_flow.yaml @@ -124,6 +124,7 @@ definitions: - name: ovs-frag-type name-prefix: ovs-frag-type- + enum-name: ovs-frag-type type: enum entries: - @@ -269,6 +270,7 @@ definitions: - name: ovs-ufid-flags name-prefix: ovs-ufid-f- + enum-name: type: flags entries: - omit-key @@ -288,6 +290,7 @@ definitions: doc: Basis used for computing hash. - name: ovs-hash-alg + enum-name: ovs-hash-alg type: enum doc: | Data path hash algorithm for computing Datapath hash. The algorithm type only specifies @@ -339,6 +342,7 @@ definitions: MPLS tunnel attributes. - name: ct-state-flags + enum-name: type: flags name-prefix: ovs-cs-f- entries: @@ -947,13 +951,11 @@ operations: do: &flow-get-op request: attributes: - - dp-ifindex - key - ufid - ufid-flags reply: attributes: - - dp-ifindex - key - ufid - mask @@ -968,7 +970,6 @@ operations: do: request: attributes: - - dp-ifindex - key - ufid - mask diff --git a/Documentation/netlink/specs/ovs_vport.yaml b/Documentation/netlink/specs/ovs_vport.yaml index f65ce62cd60d..86ba9ac2a521 100644 --- a/Documentation/netlink/specs/ovs_vport.yaml +++ b/Documentation/netlink/specs/ovs_vport.yaml @@ -135,7 +135,6 @@ operations: - name - type - upcall-pid - - dp-ifindex - ifindex - options - @@ -146,7 +145,6 @@ operations: do: request: attributes: - - dp-ifindex - port-no - type - name @@ -158,11 +156,9 @@ operations: do: &vport-get-op request: attributes: - - dp-ifindex - name reply: &dev-all attributes: - - dp-ifindex - port-no - type - name diff --git a/Documentation/netlink/specs/rt_link.yaml b/Documentation/netlink/specs/rt_link.yaml index d86a68f8475c..1ad01d52a863 100644 --- a/Documentation/netlink/specs/rt_link.yaml +++ b/Documentation/netlink/specs/rt_link.yaml @@ -66,8 +66,9 @@ definitions: name: ifi-family type: u8 - - name: padding - type: u8 + name: pad + type: pad + len: 1 - name: ifi-type type: u16 @@ -83,6 +84,18 @@ definitions: name: ifi-change type: u32 - + name: ifla-bridge-id + type: struct + members: + - + name: prio + type: u16 + - + name: addr + type: binary + len: 6 + display-hint: mac + - name: ifla-cacheinfo type: struct members: @@ -707,11 +720,9 @@ definitions: name: family type: u8 - - name: pad1 - type: u8 - - - name: pad2 - type: u16 + name: pad + type: pad + len: 3 - name: ifindex type: u32 @@ -966,8 +977,9 @@ attribute-sets: type: string - name: data - type: binary - # kind specific nest, e.g. linkinfo-bridge-attrs + type: sub-message + sub-message: linkinfo-data-msg + selector: kind - name: xstats type: binary @@ -976,10 +988,12 @@ attribute-sets: type: string - name: slave-data - type: binary - # kind specific nest + type: sub-message + sub-message: linkinfo-member-data-msg + selector: slave-kind - name: linkinfo-bridge-attrs + name-prefix: ifla-br- attributes: - name: forward-delay @@ -1011,9 +1025,11 @@ attribute-sets: - name: root-id type: binary + struct: ifla-bridge-id - name: bridge-id type: binary + struct: ifla-bridge-id - name: root-port type: u16 @@ -1041,6 +1057,7 @@ attribute-sets: - name: group-addr type: binary + display-hint: mac - name: fdb-flush type: binary @@ -1124,6 +1141,376 @@ attribute-sets: name: mcast-querier-state type: binary - + name: linkinfo-brport-attrs + name-prefix: ifla-brport- + attributes: + - + name: state + type: u8 + - + name: priority + type: u16 + - + name: cost + type: u32 + - + name: mode + type: flag + - + name: guard + type: flag + - + name: protect + type: flag + - + name: fast-leave + type: flag + - + name: learning + type: flag + - + name: unicast-flood + type: flag + - + name: proxyarp + type: flag + - + name: learning-sync + type: flag + - + name: proxyarp-wifi + type: flag + - + name: root-id + type: binary + struct: ifla-bridge-id + - + name: bridge-id + type: binary + struct: ifla-bridge-id + - + name: designated-port + type: u16 + - + name: designated-cost + type: u16 + - + name: id + type: u16 + - + name: "no" + type: u16 + - + name: topology-change-ack + type: u8 + - + name: config-pending + type: u8 + - + name: message-age-timer + type: u64 + - + name: forward-delay-timer + type: u64 + - + name: hold-timer + type: u64 + - + name: flush + type: flag + - + name: multicast-router + type: u8 + - + name: pad + type: pad + - + name: mcast-flood + type: flag + - + name: mcast-to-ucast + type: flag + - + name: vlan-tunnel + type: flag + - + name: bcast-flood + type: flag + - + name: group-fwd-mask + type: u16 + - + name: neigh-suppress + type: flag + - + name: isolated + type: flag + - + name: backup-port + type: u32 + - + name: mrp-ring-open + type: flag + - + name: mrp-in-open + type: flag + - + name: mcast-eht-hosts-limit + type: u32 + - + name: mcast-eht-hosts-cnt + type: u32 + - + name: locked + type: flag + - + name: mab + type: flag + - + name: mcast-n-groups + type: u32 + - + name: mcast-max-groups + type: u32 + - + name: neigh-vlan-suppress + type: flag + - + name: backup-nhid + type: u32 + - + name: linkinfo-gre-attrs + name-prefix: ifla-gre- + attributes: + - + name: link + type: u32 + - + name: iflags + type: u16 + - + name: oflags + type: u16 + - + name: ikey + type: u32 + - + name: okey + type: u32 + - + name: local + type: binary + display-hint: ipv4 + - + name: remote + type: binary + display-hint: ipv4 + - + name: ttl + type: u8 + - + name: tos + type: u8 + - + name: pmtudisc + type: u8 + - + name: encap-limit + type: u32 + - + name: flowinfo + type: u32 + - + name: flags + type: u32 + - + name: encap-type + type: u16 + - + name: encap-flags + type: u16 + - + name: encap-sport + type: u16 + - + name: encap-dport + type: u16 + - + name: collect-metadata + type: flag + - + name: ignore-df + type: u8 + - + name: fwmark + type: u32 + - + name: erspan-index + type: u32 + - + name: erspan-ver + type: u8 + - + name: erspan-dir + type: u8 + - + name: erspan-hwid + type: u16 + - + name: linkinfo-geneve-attrs + name-prefix: ifla-geneve- + attributes: + - + name: id + type: u32 + - + name: remote + type: binary + display-hint: ipv4 + - + name: ttl + type: u8 + - + name: tos + type: u8 + - + name: port + type: u16 + - + name: collect-metadata + type: flag + - + name: remote6 + type: binary + display-hint: ipv6 + - + name: udp-csum + type: u8 + - + name: udp-zero-csum6-tx + type: u8 + - + name: udp-zero-csum6-rx + type: u8 + - + name: label + type: u32 + - + name: ttl-inherit + type: u8 + - + name: df + type: u8 + - + name: inner-proto-inherit + type: flag + - + name: linkinfo-iptun-attrs + name-prefix: ifla-iptun- + attributes: + - + name: link + type: u32 + - + name: local + type: binary + display-hint: ipv4 + - + name: remote + type: binary + display-hint: ipv4 + - + name: ttl + type: u8 + - + name: tos + type: u8 + - + name: encap-limit + type: u8 + - + name: flowinfo + type: u32 + - + name: flags + type: u16 + - + name: proto + type: u8 + - + name: pmtudisc + type: u8 + - + name: 6rd-prefix + type: binary + display-hint: ipv6 + - + name: 6rd-relay-prefix + type: binary + display-hint: ipv4 + - + name: 6rd-prefixlen + type: u16 + - + name: 6rd-relay-prefixlen + type: u16 + - + name: encap-type + type: u16 + - + name: encap-flags + type: u16 + - + name: encap-sport + type: u16 + - + name: encap-dport + type: u16 + - + name: collect-metadata + type: flag + - + name: fwmark + type: u32 + - + name: linkinfo-tun-attrs + name-prefix: ifla-tun- + attributes: + - + name: owner + type: u32 + - + name: group + type: u32 + - + name: type + type: u8 + - + name: pi + type: u8 + - + name: vnet-hdr + type: u8 + - + name: persist + type: u8 + - + name: multi-queue + type: u8 + - + name: num-queues + type: u32 + - + name: num-disabled-queues + type: u32 + - + name: linkinfo-vrf-attrs + name-prefix: ifla-vrf- + attributes: + - + name: table + type: u32 + - name: xdp-attrs attributes: - @@ -1241,6 +1628,46 @@ attribute-sets: name: used type: u8 +sub-messages: + - + name: linkinfo-data-msg + formats: + - + value: bridge + attribute-set: linkinfo-bridge-attrs + - + value: erspan + attribute-set: linkinfo-gre-attrs + - + value: gre + attribute-set: linkinfo-gre-attrs + - + value: gretap + attribute-set: linkinfo-gre-attrs + - + value: geneve + attribute-set: linkinfo-geneve-attrs + - + value: ipip + attribute-set: linkinfo-iptun-attrs + - + value: sit + attribute-set: linkinfo-iptun-attrs + - + value: tun + attribute-set: linkinfo-tun-attrs + - + value: vrf + attribute-set: linkinfo-vrf-attrs + - + name: linkinfo-member-data-msg + formats: + - + value: bridge + attribute-set: linkinfo-brport-attrs + - + value: bond + operations: enum-model: directional list: diff --git a/Documentation/netlink/specs/tc.yaml b/Documentation/netlink/specs/tc.yaml new file mode 100644 index 000000000000..4346fa402fc9 --- /dev/null +++ b/Documentation/netlink/specs/tc.yaml @@ -0,0 +1,2031 @@ +# SPDX-License-Identifier: ((GPL-2.0 WITH Linux-syscall-note) OR BSD-3-Clause) + +name: tc +protocol: netlink-raw +protonum: 0 + +doc: + Netlink raw family for tc qdisc, chain, class and filter configuration + over rtnetlink. + +definitions: + - + name: tcmsg + type: struct + members: + - + name: family + type: u8 + - + name: pad + type: pad + len: 3 + - + name: ifindex + type: s32 + - + name: handle + type: u32 + - + name: parent + type: u32 + - + name: info + type: u32 + - + name: tc-cls-flags + type: flags + entries: + - skip-hw + - skip-sw + - in-hw + - not-in-nw + - verbose + - + name: tc-stats + type: struct + members: + - + name: bytes + type: u64 + - + name: packets + type: u32 + - + name: drops + type: u32 + - + name: overlimits + type: u32 + - + name: bps + type: u32 + - + name: pps + type: u32 + - + name: qlen + type: u32 + - + name: backlog + type: u32 + - + name: tc-cbs-qopt + type: struct + members: + - + name: offload + type: u8 + - + name: pad + type: pad + len: 3 + - + name: hicredit + type: s32 + - + name: locredit + type: s32 + - + name: idleslope + type: s32 + - + name: sendslope + type: s32 + - + name: tc-etf-qopt + type: struct + members: + - + name: delta + type: s32 + - + name: clockid + type: s32 + - + name: flags + type: s32 + - + name: tc-fifo-qopt + type: struct + members: + - + name: limit + type: u32 + - + name: tc-htb-opt + type: struct + members: + - + name: rate + type: binary + len: 12 + - + name: ceil + type: binary + len: 12 + - + name: buffer + type: u32 + - + name: cbuffer + type: u32 + - + name: quantum + type: u32 + - + name: level + type: u32 + - + name: prio + type: u32 + - + name: tc-htb-glob + type: struct + members: + - + name: version + type: u32 + - + name: rate2quantum + type: u32 + - + name: defcls + type: u32 + - + name: debug + type: u32 + - + name: direct-pkts + type: u32 + - + name: tc-gred-qopt + type: struct + members: + - + name: limit + type: u32 + - + name: qth-min + type: u32 + - + name: qth-max + type: u32 + - + name: DP + type: u32 + - + name: backlog + type: u32 + - + name: qave + type: u32 + - + name: forced + type: u32 + - + name: early + type: u32 + - + name: other + type: u32 + - + name: pdrop + type: u32 + - + name: Wlog + type: u8 + - + name: Plog + type: u8 + - + name: Scell_log + type: u8 + - + name: prio + type: u8 + - + name: packets + type: u32 + - + name: bytesin + type: u32 + - + name: tc-gred-sopt + type: struct + members: + - + name: DPs + type: u32 + - + name: def_DP + type: u32 + - + name: grio + type: u8 + - + name: flags + type: u8 + - + name: pad + type: pad + len: 2 + - + name: tc-hfsc-qopt + type: struct + members: + - + name: defcls + type: u16 + - + name: tc-mqprio-qopt + type: struct + members: + - + name: num-tc + type: u8 + - + name: prio-tc-map + type: binary + len: 16 + - + name: hw + type: u8 + - + name: count + type: binary + len: 32 + - + name: offset + type: binary + len: 32 + - + name: tc-multiq-qopt + type: struct + members: + - + name: bands + type: u16 + - + name: max-bands + type: u16 + - + name: tc-netem-qopt + type: struct + members: + - + name: latency + type: u32 + - + name: limit + type: u32 + - + name: loss + type: u32 + - + name: gap + type: u32 + - + name: duplicate + type: u32 + - + name: jitter + type: u32 + - + name: tc-plug-qopt + type: struct + members: + - + name: action + type: s32 + - + name: limit + type: u32 + - + name: tc-prio-qopt + type: struct + members: + - + name: bands + type: u16 + - + name: priomap + type: binary + len: 16 + - + name: tc-red-qopt + type: struct + members: + - + name: limit + type: u32 + - + name: qth-min + type: u32 + - + name: qth-max + type: u32 + - + name: Wlog + type: u8 + - + name: Plog + type: u8 + - + name: Scell-log + type: u8 + - + name: flags + type: u8 + - + name: tc-sfb-qopt + type: struct + members: + - + name: rehash-interval + type: u32 + - + name: warmup-time + type: u32 + - + name: max + type: u32 + - + name: bin-size + type: u32 + - + name: increment + type: u32 + - + name: decrement + type: u32 + - + name: limit + type: u32 + - + name: penalty-rate + type: u32 + - + name: penalty-burst + type: u32 + - + name: tc-sfq-qopt-v1 # TODO nested structs + type: struct + members: + - + name: quantum + type: u32 + - + name: perturb-period + type: s32 + - + name: limit + type: u32 + - + name: divisor + type: u32 + - + name: flows + type: u32 + - + name: depth + type: u32 + - + name: headdrop + type: u32 + - + name: limit + type: u32 + - + name: qth-min + type: u32 + - + name: qth-mac + type: u32 + - + name: Wlog + type: u8 + - + name: Plog + type: u8 + - + name: Scell-log + type: u8 + - + name: flags + type: u8 + - + name: max-P + type: u32 + - + name: prob-drop + type: u32 + - + name: forced-drop + type: u32 + - + name: prob-mark + type: u32 + - + name: forced-mark + type: u32 + - + name: prob-mark-head + type: u32 + - + name: forced-mark-head + type: u32 + - + name: tc-tbf-qopt + type: struct + members: + - + name: rate + type: binary # TODO nested struct tc_ratespec + len: 12 + - + name: peakrate + type: binary # TODO nested struct tc_ratespec + len: 12 + - + name: limit + type: u32 + - + name: buffer + type: u32 + - + name: mtu + type: u32 + - + name: tc-sizespec + type: struct + members: + - + name: cell-log + type: u8 + - + name: size-log + type: u8 + - + name: cell-align + type: s16 + - + name: overhead + type: s32 + - + name: linklayer + type: u32 + - + name: mpu + type: u32 + - + name: mtu + type: u32 + - + name: tsize + type: u32 + - + name: gnet-estimator + type: struct + members: + - + name: interval + type: s8 + - + name: ewma-log + type: u8 +attribute-sets: + - + name: tc-attrs + attributes: + - + name: kind + type: string + - + name: options + type: sub-message + sub-message: tc-options-msg + selector: kind + - + name: stats + type: binary + struct: tc-stats + - + name: xstats + type: binary + - + name: rate + type: binary + struct: gnet-estimator + - + name: fcnt + type: u32 + - + name: stats2 + type: nest + nested-attributes: tca-stats-attrs + - + name: stab + type: nest + nested-attributes: tca-stab-attrs + - + name: pad + type: pad + - + name: dump-invisible + type: flag + - + name: chain + type: u32 + - + name: hw-offload + type: u8 + - + name: ingress-block + type: u32 + - + name: egress-block + type: u32 + - + name: dump-flags + type: bitfield32 + - + name: ext-warn-msg + type: string + - + name: tc-cake-attrs + attributes: + - + name: pad + type: pad + - + name: base-rate64 + type: u64 + - + name: diffserv-mode + type: u32 + - + name: atm + type: u32 + - + name: flow-mode + type: u32 + - + name: overhead + type: u32 + - + name: rtt + type: u32 + - + name: target + type: u32 + - + name: autorate + type: u32 + - + name: memory + type: u32 + - + name: nat + type: u32 + - + name: raw + type: u32 + - + name: wash + type: u32 + - + name: mpu + type: u32 + - + name: ingress + type: u32 + - + name: ack-filter + type: u32 + - + name: split-gso + type: u32 + - + name: fwmark + type: u32 + - + name: tc-cake-stats-attrs + attributes: + - + name: pad + type: pad + - + name: capacity-estimate64 + type: u64 + - + name: memory-limit + type: u32 + - + name: memory-used + type: u32 + - + name: avg-netoff + type: u32 + - + name: min-netlen + type: u32 + - + name: max-netlen + type: u32 + - + name: min-adjlen + type: u32 + - + name: max-adjlen + type: u32 + - + name: tin-stats + type: binary + - + name: deficit + type: s32 + - + name: cobalt-count + type: u32 + - + name: dropping + type: u32 + - + name: drop-next-us + type: s32 + - + name: p-drop + type: u32 + - + name: blue-timer-us + type: s32 + - + name: tc-cbs-attrs + attributes: + - + name: parms + type: binary + struct: tc-cbs-qopt + - + name: tc-choke-attrs + attributes: + - + name: parms + type: binary + struct: tc-red-qopt + - + name: stab + type: binary + - + name: max-p + type: u32 + - + name: tc-codel-attrs + attributes: + - + name: target + type: u32 + - + name: limit + type: u32 + - + name: interval + type: u32 + - + name: ecn + type: u32 + - + name: ce-threshold + type: u32 + - + name: tc-drr-attrs + attributes: + - + name: quantum + type: u32 + - + name: tc-flower-attrs + attributes: + - + name: classid + type: u32 + - + name: indev + type: string + - + name: act + type: array-nest + nested-attributes: tc-act-attrs + - + name: key-eth-dst + type: binary + display-hint: mac + - + name: key-eth-dst-mask + type: binary + display-hint: mac + - + name: key-eth-src + type: binary + display-hint: mac + - + name: key-eth-src-mask + type: binary + display-hint: mac + - + name: key-eth-type + type: u16 + byte-order: big-endian + - + name: key-ip-proto + type: u8 + - + name: key-ipv4-src + type: u32 + byte-order: big-endian + display-hint: ipv4 + - + name: key-ipv4-src-mask + type: u32 + byte-order: big-endian + display-hint: ipv4 + - + name: key-ipv4-dst + type: u32 + byte-order: big-endian + display-hint: ipv4 + - + name: key-ipv4-dst-mask + type: u32 + byte-order: big-endian + display-hint: ipv4 + - + name: key-ipv6-src + type: binary + display-hint: ipv6 + - + name: key-ipv6-src-mask + type: binary + display-hint: ipv6 + - + name: key-ipv6-dst + type: binary + display-hint: ipv6 + - + name: key-ipv6-dst-mask + type: binary + display-hint: ipv6 + - + name: key-tcp-src + type: u16 + byte-order: big-endian + - + name: key-tcp-dst + type: u16 + byte-order: big-endian + - + name: key-udp-src + type: u16 + byte-order: big-endian + - + name: key-udp-dst + type: u16 + byte-order: big-endian + - + name: flags + type: u32 + enum: tc-cls-flags + enum-as-flags: true + - + name: key-vlan-id + type: u16 + byte-order: big-endian + - + name: key-vlan-prio + type: u8 + - + name: key-vlan-eth-type + type: u16 + byte-order: big-endian + - + name: key-enc-key-id + type: u32 + byte-order: big-endian + - + name: key-enc-ipv4-src + type: u32 + byte-order: big-endian + display-hint: ipv4 + - + name: key-enc-ipv4-src-mask + type: u32 + byte-order: big-endian + display-hint: ipv4 + - + name: key-enc-ipv4-dst + type: u32 + byte-order: big-endian + display-hint: ipv4 + - + name: key-enc-ipv4-dst-mask + type: u32 + byte-order: big-endian + display-hint: ipv4 + - + name: key-enc-ipv6-src + type: binary + display-hint: ipv6 + - + name: key-enc-ipv6-src-mask + type: binary + display-hint: ipv6 + - + name: key-enc-ipv6-dst + type: binary + display-hint: ipv6 + - + name: key-enc-ipv6-dst-mask + type: binary + display-hint: ipv6 + - + name: key-tcp-src-mask + type: u16 + byte-order: big-endian + - + name: key-tcp-dst-mask + type: u16 + byte-order: big-endian + - + name: key-udp-src-mask + type: u16 + byte-order: big-endian + - + name: key-udp-dst-mask + type: u16 + byte-order: big-endian + - + name: key-sctp-src-mask + type: u16 + byte-order: big-endian + - + name: key-sctp-dst-mask + type: u16 + byte-order: big-endian + - + name: key-sctp-src + type: u16 + byte-order: big-endian + - + name: key-sctp-dst + type: u16 + byte-order: big-endian + - + name: key-enc-udp-src-port + type: u16 + byte-order: big-endian + - + name: key-enc-udp-src-port-mask + type: u16 + byte-order: big-endian + - + name: key-enc-udp-dst-port + type: u16 + byte-order: big-endian + - + name: key-enc-udp-dst-port-mask + type: u16 + byte-order: big-endian + - + name: key-flags + type: u32 + byte-order: big-endian + - + name: key-flags-mask + type: u32 + byte-order: big-endian + - + name: key-icmpv4-code + type: u8 + - + name: key-icmpv4-code-mask + type: u8 + - + name: key-icmpv4-type + type: u8 + - + name: key-icmpv4-type-mask + type: u8 + - + name: key-icmpv6-code + type: u8 + - + name: key-icmpv6-code-mask + type: u8 + - + name: key-icmpv6-type + type: u8 + - + name: key-icmpv6-type-mask + type: u8 + - + name: key-arp-sip + type: u32 + byte-order: big-endian + - + name: key-arp-sip-mask + type: u32 + byte-order: big-endian + - + name: key-arp-tip + type: u32 + byte-order: big-endian + - + name: key-arp-tip-mask + type: u32 + byte-order: big-endian + - + name: key-arp-op + type: u8 + - + name: key-arp-op-mask + type: u8 + - + name: key-arp-sha + type: binary + - + name: key-arp-sha-mask + type: binary + - + name: key-arp-tha + type: binary + - + name: key-arp-tha-mask + type: binary + - + name: key-mpls-ttl + type: u8 + - + name: key-mpls-bos + type: u8 + - + name: key-mpls-tc + type: u8 + - + name: key-mpls-label + type: u32 + byte-order: big-endian + - + name: key-tcp-flags + type: u16 + byte-order: big-endian + - + name: key-tcp-flags-mask + type: u16 + byte-order: big-endian + - + name: key-ip-tos + type: u8 + - + name: key-ip-tos-mask + type: u8 + - + name: key-ip-ttl + type: u8 + - + name: key-ip-ttl-mask + type: u8 + - + name: key-cvlan-id + type: u16 + byte-order: big-endian + - + name: key-cvlan-prio + type: u8 + - + name: key-cvlan-eth-type + type: u16 + byte-order: big-endian + - + name: key-enc-ip-tos + type: u8 + - + name: key-enc-ip-tos-mask + type: u8 + - + name: key-enc-ip-ttl + type: u8 + - + name: key-enc-ip-ttl-mask + type: u8 + - + name: key-enc-opts + type: binary + - + name: key-enc-opts-mask + type: binary + - + name: in-hw-count + type: u32 + - + name: key-port-src-min + type: u16 + byte-order: big-endian + - + name: key-port-src-max + type: u16 + byte-order: big-endian + - + name: key-port-dst-min + type: u16 + byte-order: big-endian + - + name: key-port-dst-max + type: u16 + byte-order: big-endian + - + name: key-ct-state + type: u16 + - + name: key-ct-state-mask + type: u16 + - + name: key-ct-zone + type: u16 + - + name: key-ct-zone-mask + type: u16 + - + name: key-ct-mark + type: u32 + - + name: key-ct-mark-mask + type: u32 + - + name: key-ct-labels + type: binary + - + name: key-ct-labels-mask + type: binary + - + name: key-mpls-opts + type: binary + - + name: key-hash + type: u32 + - + name: key-hash-mask + type: u32 + - + name: key-num-of-vlans + type: u8 + - + name: key-pppoe-sid + type: u16 + byte-order: big-endian + - + name: key-ppp-proto + type: u16 + byte-order: big-endian + - + name: key-l2-tpv3-sid + type: u32 + byte-order: big-endian + - + name: tc-gred-attrs + attributes: + - + name: parms + type: binary # array of struct: tc-gred-qopt + - + name: stab + type: binary + sub-type: u8 + - + name: dps + type: binary + struct: tc-gred-sopt + - + name: max-p + type: binary + sub-type: u32 + - + name: limit + type: u32 + - + name: vq-list + type: nest + nested-attributes: tca-gred-vq-list-attrs + - + name: tca-gred-vq-list-attrs + attributes: + - + name: entry + type: nest + nested-attributes: tca-gred-vq-entry-attrs + multi-attr: true + - + name: tca-gred-vq-entry-attrs + attributes: + - + name: pad + type: pad + - + name: dp + type: u32 + - + name: stat-bytes + type: u32 + - + name: stat-packets + type: u32 + - + name: stat-backlog + type: u32 + - + name: stat-prob-drop + type: u32 + - + name: stat-prob-mark + type: u32 + - + name: stat-forced-drop + type: u32 + - + name: stat-forced-mark + type: u32 + - + name: stat-pdrop + type: u32 + - + name: stat-other + type: u32 + - + name: flags + type: u32 + - + name: tc-hfsc-attrs + attributes: + - + name: rsc + type: binary + - + name: fsc + type: binary + - + name: usc + type: binary + - + name: tc-hhf-attrs + attributes: + - + name: backlog-limit + type: u32 + - + name: quantum + type: u32 + - + name: hh-flows-limit + type: u32 + - + name: reset-timeout + type: u32 + - + name: admit-bytes + type: u32 + - + name: evict-timeout + type: u32 + - + name: non-hh-weight + type: u32 + - + name: tc-htb-attrs + attributes: + - + name: parms + type: binary + struct: tc-htb-opt + - + name: init + type: binary + struct: tc-htb-glob + - + name: ctab + type: binary + - + name: rtab + type: binary + - + name: direct-qlen + type: u32 + - + name: rate64 + type: u64 + - + name: ceil64 + type: u64 + - + name: pad + type: pad + - + name: offload + type: flag + - + name: tc-act-attrs + attributes: + - + name: kind + type: string + - + name: options + type: sub-message + sub-message: tc-act-options-msg + selector: kind + - + name: index + type: u32 + - + name: stats + type: binary + - + name: pad + type: pad + - + name: cookie + type: binary + - + name: flags + type: bitfield32 + - + name: hw-stats + type: bitfield32 + - + name: used-hw-stats + type: bitfield32 + - + name: in-hw-count + type: u32 + - + name: tc-etf-attrs + attributes: + - + name: parms + type: binary + struct: tc-etf-qopt + - + name: tc-ets-attrs + attributes: + - + name: nbands + type: u8 + - + name: nstrict + type: u8 + - + name: quanta + type: nest + nested-attributes: tc-ets-attrs + - + name: quanta-band + type: u32 + multi-attr: true + - + name: priomap + type: nest + nested-attributes: tc-ets-attrs + - + name: priomap-band + type: u8 + multi-attr: true + - + name: tc-fq-attrs + attributes: + - + name: plimit + type: u32 + - + name: flow-plimit + type: u32 + - + name: quantum + type: u32 + - + name: initial-quantum + type: u32 + - + name: rate-enable + type: u32 + - + name: flow-default-rate + type: u32 + - + name: flow-max-rate + type: u32 + - + name: buckets-log + type: u32 + - + name: flow-refill-delay + type: u32 + - + name: orphan-mask + type: u32 + - + name: low-rate-threshold + type: u32 + - + name: ce-threshold + type: u32 + - + name: timer-slack + type: u32 + - + name: horizon + type: u32 + - + name: horizon-drop + type: u8 + - + name: tc-fq-codel-attrs + attributes: + - + name: target + type: u32 + - + name: limit + type: u32 + - + name: interval + type: u32 + - + name: ecn + type: u32 + - + name: flows + type: u32 + - + name: quantum + type: u32 + - + name: ce-threshold + type: u32 + - + name: drop-batch-size + type: u32 + - + name: memory-limit + type: u32 + - + name: ce-threshold-selector + type: u8 + - + name: ce-threshold-mask + type: u8 + - + name: tc-fq-pie-attrs + attributes: + - + name: limit + type: u32 + - + name: flows + type: u32 + - + name: target + type: u32 + - + name: tupdate + type: u32 + - + name: alpha + type: u32 + - + name: beta + type: u32 + - + name: quantum + type: u32 + - + name: memory-limit + type: u32 + - + name: ecn-prob + type: u32 + - + name: ecn + type: u32 + - + name: bytemode + type: u32 + - + name: dq-rate-estimator + type: u32 + - + name: tc-netem-attrs + attributes: + - + name: corr + type: binary + - + name: delay-dist + type: binary + sub-type: s16 + - + name: reorder + type: binary + - + name: corrupt + type: binary + - + name: loss + type: binary + - + name: rate + type: binary + - + name: ecn + type: u32 + - + name: rate64 + type: u64 + - + name: pad + type: u32 + - + name: latency64 + type: s64 + - + name: jitter64 + type: s64 + - + name: slot + type: binary + - + name: slot-dist + type: binary + sub-type: s16 + - + name: tc-pie-attrs + attributes: + - + name: target + type: u32 + - + name: limit + type: u32 + - + name: tupdate + type: u32 + - + name: alpha + type: u32 + - + name: beta + type: u32 + - + name: ecn + type: u32 + - + name: bytemode + type: u32 + - + name: dq-rate-estimator + type: u32 + - + name: tc-qfq-attrs + attributes: + - + name: weight + type: u32 + - + name: lmax + type: u32 + - + name: tc-red-attrs + attributes: + - + name: parms + type: binary + struct: tc-red-qopt + - + name: stab + type: binary + - + name: max-p + type: u32 + - + name: flags + type: binary + - + name: early-drop-block + type: u32 + - + name: mark-block + type: u32 + - + name: tc-taprio-attrs + attributes: + - + name: priomap + type: binary + struct: tc-mqprio-qopt + - + name: sched-entry-list + type: nest + nested-attributes: tc-taprio-sched-entry-list + - + name: sched-base-time + type: s64 + - + name: sched-single-entry + type: nest + nested-attributes: tc-taprio-sched-entry + - + name: sched-clockid + type: s32 + - + name: pad + type: pad + - + name: admin-sched + type: binary + - + name: sched-cycle-time + type: s64 + - + name: sched-cycle-time-extension + type: s64 + - + name: flags + type: u32 + - + name: txtime-delay + type: u32 + - + name: tc-entry + type: nest + nested-attributes: tc-taprio-tc-entry-attrs + - + name: tc-taprio-sched-entry-list + attributes: + - + name: entry + type: nest + nested-attributes: tc-taprio-sched-entry + - + name: tc-taprio-sched-entry + attributes: + - + name: index + type: u32 + - + name: cmd + type: u8 + - + name: gate-mask + type: u32 + - + name: interval + type: u32 + - + name: tc-taprio-tc-entry-attrs + attributes: + - + name: index + type: u32 + - + name: max-sdu + type: u32 + - + name: fp + type: u32 + - + name: tc-tbf-attrs + attributes: + - + name: parms + type: binary + struct: tc-tbf-qopt + - + name: rtab + type: binary + - + name: ptab + type: binary + - + name: rate64 + type: u64 + - + name: prate4 + type: u64 + - + name: burst + type: u32 + - + name: pburst + type: u32 + - + name: pad + type: pad + - + name: tca-gact-attrs + attributes: + - + name: tm + type: binary + - + name: parms + type: binary + - + name: prob + type: binary + - + name: pad + type: pad + - + name: tca-stab-attrs + attributes: + - + name: base + type: binary + struct: tc-sizespec + - + name: data + type: binary + - + name: tca-stats-attrs + attributes: + - + name: basic + type: binary + - + name: rate-est + type: binary + - + name: queue + type: binary + - + name: app + type: binary # TODO sub-message needs 2+ level deep lookup + sub-message: tca-stats-app-msg + selector: kind + - + name: rate-est64 + type: binary + - + name: pad + type: pad + - + name: basic-hw + type: binary + - + name: pkt64 + type: binary + +sub-messages: + - + name: tc-options-msg + formats: + - + value: bfifo + fixed-header: tc-fifo-qopt + - + value: cake + attribute-set: tc-cake-attrs + - + value: cbs + attribute-set: tc-cbs-attrs + - + value: choke + attribute-set: tc-choke-attrs + - + value: clsact # no content + - + value: codel + attribute-set: tc-codel-attrs + - + value: drr + attribute-set: tc-drr-attrs + - + value: etf + attribute-set: tc-etf-attrs + - + value: ets + attribute-set: tc-ets-attrs + - + value: fq + attribute-set: tc-fq-attrs + - + value: fq_codel + attribute-set: tc-fq-codel-attrs + - + value: fq_pie + attribute-set: tc-fq-pie-attrs + - + value: flower + attribute-set: tc-flower-attrs + - + value: gred + attribute-set: tc-gred-attrs + - + value: hfsc + fixed-header: tc-hfsc-qopt + - + value: hhf + attribute-set: tc-hhf-attrs + - + value: htb + attribute-set: tc-htb-attrs + - + value: ingress # no content + - + value: mq # no content + - + value: mqprio + fixed-header: tc-mqprio-qopt + - + value: multiq + fixed-header: tc-multiq-qopt + - + value: netem + fixed-header: tc-netem-qopt + attribute-set: tc-netem-attrs + - + value: pfifo + fixed-header: tc-fifo-qopt + - + value: pfifo_fast + fixed-header: tc-prio-qopt + - + value: pfifo_head_drop + fixed-header: tc-fifo-qopt + - + value: pie + attribute-set: tc-pie-attrs + - + value: plug + fixed-header: tc-plug-qopt + - + value: prio + fixed-header: tc-prio-qopt + - + value: qfq + attribute-set: tc-qfq-attrs + - + value: red + attribute-set: tc-red-attrs + - + value: sfb + fixed-header: tc-sfb-qopt + - + value: sfq + fixed-header: tc-sfq-qopt-v1 + - + value: taprio + attribute-set: tc-taprio-attrs + - + value: tbf + attribute-set: tc-tbf-attrs + - + name: tc-act-options-msg + formats: + - + value: gact + attribute-set: tca-gact-attrs + - + name: tca-stats-app-msg + formats: + - + value: bfifo + - + value: blackhole + - + value: cake + attribute-set: tc-cake-stats-attrs + - + value: cbs + - + value: choke + - + value: clsact + - + value: codel + - + value: drr + - + value: etf + - + value: ets + - + value: fq + - + value: fq_codel + - + value: fq_pie + - + value: flower + - + value: gred + - + value: hfsc + - + value: hhf + - + value: htb + - + value: ingress + - + value: mq + - + value: mqprio + - + value: multiq + - + value: netem + - + value: noqueue + - + value: pfifo + - + value: pfifo_fast + - + value: pfifo_head_drop + - + value: pie + - + value: plug + - + value: prio + - + value: qfq + - + value: red + - + value: sfb + - + value: sfq + - + value: taprio + - + value: tbf + +operations: + enum-model: directional + list: + - + name: newqdisc + doc: Create new tc qdisc. + attribute-set: tc-attrs + fixed-header: tcmsg + do: + request: + value: 36 + attributes: &create-params + - kind + - options + - rate + - chain + - ingress-block + - egress-block + - + name: delqdisc + doc: Delete existing tc qdisc. + attribute-set: tc-attrs + fixed-header: tcmsg + do: + request: + value: 37 + - + name: getqdisc + doc: Get / dump tc qdisc information. + attribute-set: tc-attrs + fixed-header: tcmsg + do: + request: + value: 38 + attributes: + - dump-invisible + reply: + value: 36 + attributes: &tc-all + - kind + - options + - stats + - xstats + - rate + - fcnt + - stats2 + - stab + - chain + - ingress-block + - egress-block + - + name: newtclass + doc: Get / dump tc traffic class information. + attribute-set: tc-attrs + fixed-header: tcmsg + do: + request: + value: 40 + attributes: *create-params + - + name: deltclass + doc: Get / dump tc traffic class information. + attribute-set: tc-attrs + fixed-header: tcmsg + do: + request: + value: 41 + - + name: gettclass + doc: Get / dump tc traffic class information. + attribute-set: tc-attrs + fixed-header: tcmsg + do: + request: + value: 42 + reply: + value: 40 + attributes: *tc-all + - + name: newtfilter + doc: Get / dump tc filter information. + attribute-set: tc-attrs + fixed-header: tcmsg + do: + request: + value: 44 + attributes: *create-params + - + name: deltfilter + doc: Get / dump tc filter information. + attribute-set: tc-attrs + fixed-header: tcmsg + do: + request: + value: 45 + attributes: + - chain + - kind + - + name: gettfilter + doc: Get / dump tc filter information. + attribute-set: tc-attrs + fixed-header: tcmsg + do: + request: + value: 46 + attributes: + - chain + - kind + reply: + value: 44 + attributes: *tc-all + dump: + request: + value: 46 + attributes: + - chain + - dump-flags + reply: + value: 44 + attributes: *tc-all + - + name: newchain + doc: Get / dump tc chain information. + attribute-set: tc-attrs + fixed-header: tcmsg + do: + request: + value: 100 + attributes: *create-params + - + name: delchain + doc: Get / dump tc chain information. + attribute-set: tc-attrs + fixed-header: tcmsg + do: + request: + value: 101 + attributes: + - chain + - + name: getchain + doc: Get / dump tc chain information. + attribute-set: tc-attrs + fixed-header: tcmsg + do: + request: + value: 102 + attributes: + - chain + reply: + value: 100 + attributes: *tc-all + +mcast-groups: + list: + - + name: rtnlgrp-tc + value: 4 diff --git a/Documentation/networking/bridge.rst b/Documentation/networking/bridge.rst index c859f3c1636e..ba14e7b07869 100644 --- a/Documentation/networking/bridge.rst +++ b/Documentation/networking/bridge.rst @@ -4,18 +4,332 @@ Ethernet Bridging ================= -In order to use the Ethernet bridging functionality, you'll need the -userspace tools. +Introduction +============ -Documentation for Linux bridging is on: - https://wiki.linuxfoundation.org/networking/bridge +The IEEE 802.1Q-2022 (Bridges and Bridged Networks) standard defines the +operation of bridges in computer networks. A bridge, in the context of this +standard, is a device that connects two or more network segments and operates +at the data link layer (Layer 2) of the OSI (Open Systems Interconnection) +model. The purpose of a bridge is to filter and forward frames between +different segments based on the destination MAC (Media Access Control) address. -The bridge-utilities are maintained at: - git://git.kernel.org/pub/scm/linux/kernel/git/shemminger/bridge-utils.git +Bridge kAPI +=========== -Additionally, the iproute2 utilities can be used to configure -bridge devices. +Here are some core structures of bridge code. Note that the kAPI is *unstable*, +and can be changed at any time. -If you still have questions, don't hesitate to post to the mailing list -(more info https://lists.linux-foundation.org/mailman/listinfo/bridge). +.. kernel-doc:: net/bridge/br_private.h + :identifiers: net_bridge_vlan +Bridge uAPI +=========== + +Modern Linux bridge uAPI is accessed via Netlink interface. You can find +below files where the bridge and bridge port netlink attributes are defined. + +Bridge netlink attributes +------------------------- + +.. kernel-doc:: include/uapi/linux/if_link.h + :doc: Bridge enum definition + +Bridge port netlink attributes +------------------------------ + +.. kernel-doc:: include/uapi/linux/if_link.h + :doc: Bridge port enum definition + +Bridge sysfs +------------ + +The sysfs interface is deprecated and should not be extended if new +options are added. + +STP +=== + +The STP (Spanning Tree Protocol) implementation in the Linux bridge driver +is a critical feature that helps prevent loops and broadcast storms in +Ethernet networks by identifying and disabling redundant links. In a Linux +bridge context, STP is crucial for network stability and availability. + +STP is a Layer 2 protocol that operates at the Data Link Layer of the OSI +model. It was originally developed as IEEE 802.1D and has since evolved into +multiple versions, including Rapid Spanning Tree Protocol (RSTP) and +`Multiple Spanning Tree Protocol (MSTP) +<https://lore.kernel.org/netdev/20220316150857.2442916-1-tobias@waldekranz.com/>`_. + +The 802.1D-2004 removed the original Spanning Tree Protocol, instead +incorporating the Rapid Spanning Tree Protocol (RSTP). By 2014, all the +functionality defined by IEEE 802.1D has been incorporated into either +IEEE 802.1Q (Bridges and Bridged Networks) or IEEE 802.1AC (MAC Service +Definition). 802.1D has been officially withdrawn in 2022. + +Bridge Ports and STP States +--------------------------- + +In the context of STP, bridge ports can be in one of the following states: + * Blocking: The port is disabled for data traffic and only listens for + BPDUs (Bridge Protocol Data Units) from other devices to determine the + network topology. + * Listening: The port begins to participate in the STP process and listens + for BPDUs. + * Learning: The port continues to listen for BPDUs and begins to learn MAC + addresses from incoming frames but does not forward data frames. + * Forwarding: The port is fully operational and forwards both BPDUs and + data frames. + * Disabled: The port is administratively disabled and does not participate + in the STP process. The data frames forwarding are also disabled. + +Root Bridge and Convergence +--------------------------- + +In the context of networking and Ethernet bridging in Linux, the root bridge +is a designated switch in a bridged network that serves as a reference point +for the spanning tree algorithm to create a loop-free topology. + +Here's how the STP works and root bridge is chosen: + 1. Bridge Priority: Each bridge running a spanning tree protocol, has a + configurable Bridge Priority value. The lower the value, the higher the + priority. By default, the Bridge Priority is set to a standard value + (e.g., 32768). + 2. Bridge ID: The Bridge ID is composed of two components: Bridge Priority + and the MAC address of the bridge. It uniquely identifies each bridge + in the network. The Bridge ID is used to compare the priorities of + different bridges. + 3. Bridge Election: When the network starts, all bridges initially assume + that they are the root bridge. They start advertising Bridge Protocol + Data Units (BPDU) to their neighbors, containing their Bridge ID and + other information. + 4. BPDU Comparison: Bridges exchange BPDUs to determine the root bridge. + Each bridge examines the received BPDUs, including the Bridge Priority + and Bridge ID, to determine if it should adjust its own priorities. + The bridge with the lowest Bridge ID will become the root bridge. + 5. Root Bridge Announcement: Once the root bridge is determined, it sends + BPDUs with information about the root bridge to all other bridges in the + network. This information is used by other bridges to calculate the + shortest path to the root bridge and, in doing so, create a loop-free + topology. + 6. Forwarding Ports: After the root bridge is selected and the spanning tree + topology is established, each bridge determines which of its ports should + be in the forwarding state (used for data traffic) and which should be in + the blocking state (used to prevent loops). The root bridge's ports are + all in the forwarding state. while other bridges have some ports in the + blocking state to avoid loops. + 7. Root Ports: After the root bridge is selected and the spanning tree + topology is established, each non-root bridge processes incoming + BPDUs and determines which of its ports provides the shortest path to the + root bridge based on the information in the received BPDUs. This port is + designated as the root port. And it is in the Forwarding state, allowing + it to actively forward network traffic. + 8. Designated ports: A designated port is the port through which the non-root + bridge will forward traffic towards the designated segment. Designated ports + are placed in the Forwarding state. All other ports on the non-root + bridge that are not designated for specific segments are placed in the + Blocking state to prevent network loops. + +STP ensures network convergence by calculating the shortest path and disabling +redundant links. When network topology changes occur (e.g., a link failure), +STP recalculates the network topology to restore connectivity while avoiding loops. + +Proper configuration of STP parameters, such as the bridge priority, can +influence network performance, path selection and which bridge becomes the +Root Bridge. + +User space STP helper +--------------------- + +The user space STP helper *bridge-stp* is a program to control whether to use +user mode spanning tree. The ``/sbin/bridge-stp <bridge> <start|stop>`` is +called by the kernel when STP is enabled/disabled on a bridge +(via ``brctl stp <bridge> <on|off>`` or ``ip link set <bridge> type bridge +stp_state <0|1>``). The kernel enables user_stp mode if that command returns +0, or enables kernel_stp mode if that command returns any other value. + +VLAN +==== + +A LAN (Local Area Network) is a network that covers a small geographic area, +typically within a single building or a campus. LANs are used to connect +computers, servers, printers, and other networked devices within a localized +area. LANs can be wired (using Ethernet cables) or wireless (using Wi-Fi). + +A VLAN (Virtual Local Area Network) is a logical segmentation of a physical +network into multiple isolated broadcast domains. VLANs are used to divide +a single physical LAN into multiple virtual LANs, allowing different groups of +devices to communicate as if they were on separate physical networks. + +Typically there are two VLAN implementations, IEEE 802.1Q and IEEE 802.1ad +(also known as QinQ). IEEE 802.1Q is a standard for VLAN tagging in Ethernet +networks. It allows network administrators to create logical VLANs on a +physical network and tag Ethernet frames with VLAN information, which is +called *VLAN-tagged frames*. IEEE 802.1ad, commonly known as QinQ or Double +VLAN, is an extension of the IEEE 802.1Q standard. QinQ allows for the +stacking of multiple VLAN tags within a single Ethernet frame. The Linux +bridge supports both the IEEE 802.1Q and `802.1AD +<https://lore.kernel.org/netdev/1402401565-15423-1-git-send-email-makita.toshiaki@lab.ntt.co.jp/>`_ +protocol for VLAN tagging. + +`VLAN filtering <https://lore.kernel.org/netdev/1360792820-14116-1-git-send-email-vyasevic@redhat.com/>`_ +on a bridge is disabled by default. After enabling VLAN filtering on a bridge, +it will start forwarding frames to appropriate destinations based on their +destination MAC address and VLAN tag (both must match). + +Multicast +========= + +The Linux bridge driver has multicast support allowing it to process Internet +Group Management Protocol (IGMP) or Multicast Listener Discovery (MLD) +messages, and to efficiently forward multicast data packets. The bridge +driver supports IGMPv2/IGMPv3 and MLDv1/MLDv2. + +Multicast snooping +------------------ + +Multicast snooping is a networking technology that allows network switches +to intelligently manage multicast traffic within a local area network (LAN). + +The switch maintains a multicast group table, which records the association +between multicast group addresses and the ports where hosts have joined these +groups. The group table is dynamically updated based on the IGMP/MLD messages +received. With the multicast group information gathered through snooping, the +switch optimizes the forwarding of multicast traffic. Instead of blindly +broadcasting the multicast traffic to all ports, it sends the multicast +traffic based on the destination MAC address only to ports which have +subscribed the respective destination multicast group. + +When created, the Linux bridge devices have multicast snooping enabled by +default. It maintains a Multicast forwarding database (MDB) which keeps track +of port and group relationships. + +IGMPv3/MLDv2 EHT support +------------------------ + +The Linux bridge supports IGMPv3/MLDv2 EHT (Explicit Host Tracking), which +was added by `474ddb37fa3a ("net: bridge: multicast: add EHT allow/block handling") +<https://lore.kernel.org/netdev/20210120145203.1109140-1-razor@blackwall.org/>`_ + +The explicit host tracking enables the device to keep track of each +individual host that is joined to a particular group or channel. The main +benefit of the explicit host tracking in IGMP is to allow minimal leave +latencies when a host leaves a multicast group or channel. + +The length of time between a host wanting to leave and a device stopping +traffic forwarding is called the IGMP leave latency. A device configured +with IGMPv3 or MLDv2 and explicit tracking can immediately stop forwarding +traffic if the last host to request to receive traffic from the device +indicates that it no longer wants to receive traffic. The leave latency +is thus bound only by the packet transmission latencies in the multiaccess +network and the processing time in the device. + +Other multicast features +------------------------ + +The Linux bridge also supports `per-VLAN multicast snooping +<https://lore.kernel.org/netdev/20210719170637.435541-1-razor@blackwall.org/>`_, +which is disabled by default but can be enabled. And `Multicast Router Discovery +<https://lore.kernel.org/netdev/20190121062628.2710-1-linus.luessing@c0d3.blue/>`_, +which help identify the location of multicast routers. + +Switchdev +========= + +Linux Bridge Switchdev is a feature in the Linux kernel that extends the +capabilities of the traditional Linux bridge to work more efficiently with +hardware switches that support switchdev. With Linux Bridge Switchdev, certain +networking functions like forwarding, filtering, and learning of Ethernet +frames can be offloaded to a hardware switch. This offloading reduces the +burden on the Linux kernel and CPU, leading to improved network performance +and lower latency. + +To use Linux Bridge Switchdev, you need hardware switches that support the +switchdev interface. This means that the switch hardware needs to have the +necessary drivers and functionality to work in conjunction with the Linux +kernel. + +Please see the :ref:`switchdev` document for more details. + +Netfilter +========= + +The bridge netfilter module is a legacy feature that allows to filter bridged +packets with iptables and ip6tables. Its use is discouraged. Users should +consider using nftables for packet filtering. + +The older ebtables tool is more feature-limited compared to nftables, but +just like nftables it doesn't need this module either to function. + +The br_netfilter module intercepts packets entering the bridge, performs +minimal sanity tests on ipv4 and ipv6 packets and then pretends that +these packets are being routed, not bridged. br_netfilter then calls +the ip and ipv6 netfilter hooks from the bridge layer, i.e. ip(6)tables +rulesets will also see these packets. + +br_netfilter is also the reason for the iptables *physdev* match: +This match is the only way to reliably tell routed and bridged packets +apart in an iptables ruleset. + +Note that ebtables and nftables will work fine without the br_netfilter module. +iptables/ip6tables/arptables do not work for bridged traffic because they +plug in the routing stack. nftables rules in ip/ip6/inet/arp families won't +see traffic that is forwarded by a bridge either, but that's very much how it +should be. + +Historically the feature set of ebtables was very limited (it still is), +this module was added to pretend packets are routed and invoke the ipv4/ipv6 +netfilter hooks from the bridge so users had access to the more feature-rich +iptables matching capabilities (including conntrack). nftables doesn't have +this limitation, pretty much all features work regardless of the protocol family. + +So, br_netfilter is only needed if users, for some reason, need to use +ip(6)tables to filter packets forwarded by the bridge, or NAT bridged +traffic. For pure link layer filtering, this module isn't needed. + +Other Features +============== + +The Linux bridge also supports `IEEE 802.11 Proxy ARP +<https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=958501163ddd6ea22a98f94fa0e7ce6d4734e5c4>`_, +`Media Redundancy Protocol (MRP) +<https://lore.kernel.org/netdev/20200426132208.3232-1-horatiu.vultur@microchip.com/>`_, +`Media Redundancy Protocol (MRP) LC mode +<https://lore.kernel.org/r/20201124082525.273820-1-horatiu.vultur@microchip.com>`_, +`IEEE 802.1X port authentication +<https://lore.kernel.org/netdev/20220218155148.2329797-1-schultz.hans+netdev@gmail.com/>`_, +and `MAC Authentication Bypass (MAB) +<https://lore.kernel.org/netdev/20221101193922.2125323-2-idosch@nvidia.com/>`_. + +FAQ +=== + +What does a bridge do? +---------------------- + +A bridge transparently forwards traffic between multiple network interfaces. +In plain English this means that a bridge connects two or more physical +Ethernet networks, to form one larger (logical) Ethernet network. + +Is it L3 protocol independent? +------------------------------ + +Yes. The bridge sees all frames, but it *uses* only L2 headers/information. +As such, the bridging functionality is protocol independent, and there should +be no trouble forwarding IPX, NetBEUI, IP, IPv6, etc. + +Contact Info +============ + +The code is currently maintained by Roopa Prabhu <roopa@nvidia.com> and +Nikolay Aleksandrov <razor@blackwall.org>. Bridge bugs and enhancements +are discussed on the linux-netdev mailing list netdev@vger.kernel.org and +bridge@lists.linux-foundation.org. + +The list is open to anyone interested: http://vger.kernel.org/vger-lists.html#netdev + +External Links +============== + +The old Documentation for Linux bridging is on: +https://wiki.linuxfoundation.org/networking/bridge diff --git a/Documentation/networking/device_drivers/ethernet/amazon/ena.rst b/Documentation/networking/device_drivers/ethernet/amazon/ena.rst index 5eaa3ab6c73e..b842bcb14255 100644 --- a/Documentation/networking/device_drivers/ethernet/amazon/ena.rst +++ b/Documentation/networking/device_drivers/ethernet/amazon/ena.rst @@ -54,6 +54,7 @@ ena_common_defs.h Common definitions for ena_com layer. ena_regs_defs.h Definition of ENA PCI memory-mapped (MMIO) registers. ena_netdev.[ch] Main Linux kernel driver. ena_ethtool.c ethtool callbacks. +ena_xdp.[ch] XDP files ena_pci_id_tbl.h Supported device IDs. ================= ====================================================== diff --git a/Documentation/networking/device_drivers/ethernet/intel/ice.rst b/Documentation/networking/device_drivers/ethernet/intel/ice.rst index e4d065c55ea8..5038e54586af 100644 --- a/Documentation/networking/device_drivers/ethernet/intel/ice.rst +++ b/Documentation/networking/device_drivers/ethernet/intel/ice.rst @@ -895,6 +895,147 @@ driver writes raw bytes by the GNSS object to the receiver through i2c. Please refer to the hardware GNSS module documentation for configuration details. +Firmware (FW) logging +--------------------- +The driver supports FW logging via the debugfs interface on PF 0 only. The FW +running on the NIC must support FW logging; if the FW doesn't support FW logging +the 'fwlog' file will not get created in the ice debugfs directory. + +Module configuration +~~~~~~~~~~~~~~~~~~~~ +Firmware logging is configured on a per module basis. Each module can be set to +a value independent of the other modules (unless the module 'all' is specified). +The modules will be instantiated under the 'fwlog/modules' directory. + +The user can set the log level for a module by writing to the module file like +this:: + + # echo <log_level> > /sys/kernel/debug/ice/0000\:18\:00.0/fwlog/modules/<module> + +where + +* log_level is a name as described below. Each level includes the + messages from the previous/lower level + + * none + * error + * warning + * normal + * verbose + +* module is a name that represents the module to receive events for. The + module names are + + * general + * ctrl + * link + * link_topo + * dnl + * i2c + * sdp + * mdio + * adminq + * hdma + * lldp + * dcbx + * dcb + * xlr + * nvm + * auth + * vpd + * iosf + * parser + * sw + * scheduler + * txq + * rsvd + * post + * watchdog + * task_dispatch + * mng + * synce + * health + * tsdrv + * pfreg + * mdlver + * all + +The name 'all' is special and allows the user to set all of the modules to the +specified log_level or to read the log_level of all of the modules. + +Example usage to configure the modules +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +To set a single module to 'verbose':: + + # echo verbose > /sys/kernel/debug/ice/0000\:18\:00.0/fwlog/modules/link + +To set multiple modules then issue the command multiple times:: + + # echo verbose > /sys/kernel/debug/ice/0000\:18\:00.0/fwlog/modules/link + # echo warning > /sys/kernel/debug/ice/0000\:18\:00.0/fwlog/modules/ctrl + # echo none > /sys/kernel/debug/ice/0000\:18\:00.0/fwlog/modules/dcb + +To set all the modules to the same value:: + + # echo normal > /sys/kernel/debug/ice/0000\:18\:00.0/fwlog/modules/all + +To read the log_level of a specific module (e.g. module 'general'):: + + # cat /sys/kernel/debug/ice/0000\:18\:00.0/fwlog/modules/general + +To read the log_level of all the modules:: + + # cat /sys/kernel/debug/ice/0000\:18\:00.0/fwlog/modules/all + +Enabling FW log +~~~~~~~~~~~~~~~ +Configuring the modules indicates to the FW that the configured modules should +generate events that the driver is interested in, but it **does not** send the +events to the driver until the enable message is sent to the FW. To do this +the user can write a 1 (enable) or 0 (disable) to 'fwlog/enable'. An example +is:: + + # echo 1 > /sys/kernel/debug/ice/0000\:18\:00.0/fwlog/enable + +Retrieving FW log data +~~~~~~~~~~~~~~~~~~~~~~ +The FW log data can be retrieved by reading from 'fwlog/data'. The user can +write any value to 'fwlog/data' to clear the data. The data can only be cleared +when FW logging is disabled. The FW log data is a binary file that is sent to +Intel and used to help debug user issues. + +An example to read the data is:: + + # cat /sys/kernel/debug/ice/0000\:18\:00.0/fwlog/data > fwlog.bin + +An example to clear the data is:: + + # echo 0 > /sys/kernel/debug/ice/0000\:18\:00.0/fwlog/data + +Changing how often the log events are sent to the driver +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The driver receives FW log data from the Admin Receive Queue (ARQ). The +frequency that the FW sends the ARQ events can be configured by writing to +'fwlog/nr_messages'. The range is 1-128 (1 means push every log message, 128 +means push only when the max AQ command buffer is full). The suggested value is +10. The user can see what the value is configured to by reading +'fwlog/nr_messages'. An example to set the value is:: + + # echo 50 > /sys/kernel/debug/ice/0000\:18\:00.0/fwlog/nr_messages + +Configuring the amount of memory used to store FW log data +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The driver stores FW log data within the driver. The default size of the memory +used to store the data is 1MB. Some use cases may require more or less data so +the user can change the amount of memory that is allocated for FW log data. +To change the amount of memory then write to 'fwlog/log_size'. The value must be +one of: 128K, 256K, 512K, 1M, or 2M. FW logging must be disabled to change the +value. An example of changing the value is:: + + # echo 128K > /sys/kernel/debug/ice/0000\:18\:00.0/fwlog/log_size + + Performance Optimization ======================== Driver defaults are meant to fit a wide variety of workloads, but if further diff --git a/Documentation/networking/device_drivers/ethernet/marvell/octeon_ep.rst b/Documentation/networking/device_drivers/ethernet/marvell/octeon_ep.rst index cad96c8d1f97..c96d262b30be 100644 --- a/Documentation/networking/device_drivers/ethernet/marvell/octeon_ep.rst +++ b/Documentation/networking/device_drivers/ethernet/marvell/octeon_ep.rst @@ -22,8 +22,13 @@ EndPoint NIC. Supported Devices ================= Currently, this driver support following devices: + * Network controller: Cavium, Inc. Device b100 * Network controller: Cavium, Inc. Device b200 * Network controller: Cavium, Inc. Device b400 + * Network controller: Cavium, Inc. Device b900 + * Network controller: Cavium, Inc. Device ba00 + * Network controller: Cavium, Inc. Device bc00 + * Network controller: Cavium, Inc. Device bd00 Interface Control ================= diff --git a/Documentation/networking/device_drivers/wifi/index.rst b/Documentation/networking/device_drivers/wifi/index.rst index bf91a87c7acf..fb394f5de4a9 100644 --- a/Documentation/networking/device_drivers/wifi/index.rst +++ b/Documentation/networking/device_drivers/wifi/index.rst @@ -10,7 +10,6 @@ Contents: intel/ipw2100 intel/ipw2200 - ray_cs .. only:: subproject and html diff --git a/Documentation/networking/device_drivers/wifi/ray_cs.rst b/Documentation/networking/device_drivers/wifi/ray_cs.rst deleted file mode 100644 index 9a46d1ae8f20..000000000000 --- a/Documentation/networking/device_drivers/wifi/ray_cs.rst +++ /dev/null @@ -1,165 +0,0 @@ -.. SPDX-License-Identifier: GPL-2.0 - -.. include:: <isonum.txt> - -========================= -Raylink wireless LAN card -========================= - -September 21, 1999 - -Copyright |copy| 1998 Corey Thomas (corey@world.std.com) - -This file is the documentation for the Raylink Wireless LAN card driver for -Linux. The Raylink wireless LAN card is a PCMCIA card which provides IEEE -802.11 compatible wireless network connectivity at 1 and 2 megabits/second. -See http://www.raytheon.com/micro/raylink/ for more information on the Raylink -card. This driver is in early development and does have bugs. See the known -bugs and limitations at the end of this document for more information. -This driver also works with WebGear's Aviator 2.4 and Aviator Pro -wireless LAN cards. - -As of kernel 2.3.18, the ray_cs driver is part of the Linux kernel -source. My web page for the development of ray_cs is at -http://web.ralinktech.com/ralink/Home/Support/Linux.html -and I can be emailed at corey@world.std.com - -The kernel driver is based on ray_cs-1.62.tgz - -The driver at my web page is intended to be used as an add on to -David Hinds pcmcia package. All the command line parameters are -available when compiled as a module. When built into the kernel, only -the essid= string parameter is available via the kernel command line. -This will change after the method of sorting out parameters for all -the PCMCIA drivers is agreed upon. If you must have a built in driver -with nondefault parameters, they can be edited in -/usr/src/linux/drivers/net/pcmcia/ray_cs.c. Searching for module_param -will find them all. - -Information on card services is available at: - - http://pcmcia-cs.sourceforge.net/ - - -Card services user programs are still required for PCMCIA devices. -pcmcia-cs-3.1.1 or greater is required for the kernel version of -the driver. - -Currently, ray_cs is not part of David Hinds card services package, -so the following magic is required. - -At the end of the /etc/pcmcia/config.opts file, add the line: -source ./ray_cs.opts -This will make card services read the ray_cs.opts file -when starting. Create the file /etc/pcmcia/ray_cs.opts containing the -following:: - - #### start of /etc/pcmcia/ray_cs.opts ################### - # Configuration options for Raylink Wireless LAN PCMCIA card - device "ray_cs" - class "network" module "misc/ray_cs" - - card "RayLink PC Card WLAN Adapter" - manfid 0x01a6, 0x0000 - bind "ray_cs" - - module "misc/ray_cs" opts "" - #### end of /etc/pcmcia/ray_cs.opts ##################### - - -To join an existing network with -different parameters, contact the network administrator for the -configuration information, and edit /etc/pcmcia/ray_cs.opts. -Add the parameters below between the empty quotes. - -Parameters for ray_cs driver which may be specified in ray_cs.opts: - -=============== =============== ============================================= -bc integer 0 = normal mode (802.11 timing), - 1 = slow down inter frame timing to allow - operation with older breezecom access - points. - -beacon_period integer beacon period in Kilo-microseconds, - - legal values = must be integer multiple - of hop dwell - - default = 256 - -country integer 1 = USA (default), - 2 = Europe, - 3 = Japan, - 4 = Korea, - 5 = Spain, - 6 = France, - 7 = Israel, - 8 = Australia - -essid string ESS ID - network name to join - - string with maximum length of 32 chars - default value = "ADHOC_ESSID" - -hop_dwell integer hop dwell time in Kilo-microseconds - - legal values = 16,32,64,128(default),256 - -irq_mask integer linux standard 16 bit value 1bit/IRQ - - lsb is IRQ 0, bit 1 is IRQ 1 etc. - Used to restrict choice of IRQ's to use. - Recommended method for controlling - interrupts is in /etc/pcmcia/config.opts - -net_type integer 0 (default) = adhoc network, - 1 = infrastructure - -phy_addr string string containing new MAC address in - hex, must start with x eg - x00008f123456 - -psm integer 0 = continuously active, - 1 = power save mode (not useful yet) - -pc_debug integer (0-5) larger values for more verbose - logging. Replaces ray_debug. - -ray_debug integer Replaced with pc_debug - -ray_mem_speed integer defaults to 500 - -sniffer integer 0 = not sniffer (default), - 1 = sniffer which can be used to record all - network traffic using tcpdump or similar, - but no normal network use is allowed. - -translate integer 0 = no translation (encapsulate frames), - 1 = translation (RFC1042/802.1) -=============== =============== ============================================= - -More on sniffer mode: - -tcpdump does not understand 802.11 headers, so it can't -interpret the contents, but it can record to a file. This is only -useful for debugging 802.11 lowlevel protocols that are not visible to -linux. If you want to watch ftp xfers, or do similar things, you -don't need to use sniffer mode. Also, some packet types are never -sent up by the card, so you will never see them (ack, rts, cts, probe -etc.) There is a simple program (showcap) included in the ray_cs -package which parses the 802.11 headers. - -Known Problems and missing features - - Does not work with non x86 - - Does not work with SMP - - Support for defragmenting frames is not yet debugged, and in - fact is known to not work. I have never encountered a net set - up to fragment, but still, it should be fixed. - - The ioctl support is incomplete. The hardware address cannot be set - using ifconfig yet. If a different hardware address is needed, it may - be set using the phy_addr parameter in ray_cs.opts. This requires - a card insertion to take effect. diff --git a/Documentation/networking/devlink/devlink-reload.rst b/Documentation/networking/devlink/devlink-reload.rst index 505d22da027d..2fb0269b2054 100644 --- a/Documentation/networking/devlink/devlink-reload.rst +++ b/Documentation/networking/devlink/devlink-reload.rst @@ -22,8 +22,17 @@ By default ``driver_reinit`` action is selected. * - ``driver-reinit`` - Devlink driver entities re-initialization, including applying new values to devlink entities which are used during driver - load such as ``devlink-params`` in configuration mode - ``driverinit`` or ``devlink-resources`` + load which are: + + * ``devlink-params`` in configuration mode ``driverinit`` + * ``devlink-resources`` + + Other devlink entities may stay over the re-initialization: + + * ``devlink-health-reporter`` + * ``devlink-region`` + + The rest of the devlink entities have to be removed and readded. * - ``fw_activate`` - Firmware activate. Activates new firmware if such image is stored and pending activation. If no limitation specified this action may involve diff --git a/Documentation/networking/devlink/ice.rst b/Documentation/networking/devlink/ice.rst index 2f60e34ab926..7f30ebd5debb 100644 --- a/Documentation/networking/devlink/ice.rst +++ b/Documentation/networking/devlink/ice.rst @@ -38,6 +38,10 @@ The ``ice`` driver reports the following versions - fixed - K65390-000 - The Product Board Assembly (PBA) identifier of the board. + * - ``cgu.id`` + - fixed + - 36 + - The Clock Generation Unit (CGU) hardware revision identifier. * - ``fw.mgmt`` - running - 2.1.7 @@ -104,6 +108,11 @@ The ``ice`` driver reports the following versions - running - 0xee16ced7 - The first 4 bytes of the hash of the netlist module contents. + * - ``fw.cgu`` + - running + - 8032.16973825.6021 + - The version of Clock Generation Unit (CGU). Format: + <CGU type>.<configuration version>.<firmware version>. Flash Update ============ diff --git a/Documentation/networking/ethtool-netlink.rst b/Documentation/networking/ethtool-netlink.rst index 2540c70952ff..d583d9abf2f8 100644 --- a/Documentation/networking/ethtool-netlink.rst +++ b/Documentation/networking/ethtool-netlink.rst @@ -223,6 +223,9 @@ Userspace to kernel: ``ETHTOOL_MSG_PSE_SET`` set PSE parameters ``ETHTOOL_MSG_PSE_GET`` get PSE parameters ``ETHTOOL_MSG_RSS_GET`` get RSS settings + ``ETHTOOL_MSG_PLCA_GET_CFG`` get PLCA RS parameters + ``ETHTOOL_MSG_PLCA_SET_CFG`` set PLCA RS parameters + ``ETHTOOL_MSG_PLCA_GET_STATUS`` get PLCA RS status ``ETHTOOL_MSG_MM_GET`` get MAC merge layer state ``ETHTOOL_MSG_MM_SET`` set MAC merge layer parameters ===================================== ================================= @@ -267,6 +270,9 @@ Kernel to userspace: ``ETHTOOL_MSG_MODULE_GET_REPLY`` transceiver module parameters ``ETHTOOL_MSG_PSE_GET_REPLY`` PSE parameters ``ETHTOOL_MSG_RSS_GET_REPLY`` RSS settings + ``ETHTOOL_MSG_PLCA_GET_CFG_REPLY`` PLCA RS parameters + ``ETHTOOL_MSG_PLCA_GET_STATUS_REPLY`` PLCA RS status + ``ETHTOOL_MSG_PLCA_NTF`` PLCA RS parameters ``ETHTOOL_MSG_MM_GET_REPLY`` MAC merge layer status ======================================== ================================= @@ -1768,12 +1774,16 @@ Kernel response contents: ``ETHTOOL_A_RSS_HFUNC`` u32 RSS hash func ``ETHTOOL_A_RSS_INDIR`` binary Indir table bytes ``ETHTOOL_A_RSS_HKEY`` binary Hash key bytes + ``ETHTOOL_A_RSS_INPUT_XFRM`` u32 RSS input data transformation ===================================== ====== ========================== ETHTOOL_A_RSS_HFUNC attribute is bitmap indicating the hash function being used. Current supported options are toeplitz, xor or crc32. -ETHTOOL_A_RSS_INDIR attribute returns RSS indrection table where each byte +ETHTOOL_A_RSS_INDIR attribute returns RSS indirection table where each byte indicates queue number. +ETHTOOL_A_RSS_INPUT_XFRM attribute is a bitmap indicating the type of +transformation applied to the input protocol fields before given to the RSS +hfunc. Current supported option is symmetric-xor. PLCA_GET_CFG ============ diff --git a/Documentation/networking/index.rst b/Documentation/networking/index.rst index 683eb42309cc..69f3d6dcd9fd 100644 --- a/Documentation/networking/index.rst +++ b/Documentation/networking/index.rst @@ -55,6 +55,7 @@ Contents: filter generic-hdlc generic_netlink + netlink_spec/index gen_stats gtp ila @@ -74,6 +75,7 @@ Contents: mptcp-sysctl multiqueue napi + net_cachelines/index netconsole netdev-features netdevices @@ -123,6 +125,7 @@ Contents: xfrm_sync xfrm_sysctl xdp-rx-metadata + xsk-tx-metadata .. only:: subproject and html diff --git a/Documentation/networking/ip-sysctl.rst b/Documentation/networking/ip-sysctl.rst index 4dfe0d9a57bb..7afff42612e9 100644 --- a/Documentation/networking/ip-sysctl.rst +++ b/Documentation/networking/ip-sysctl.rst @@ -2511,7 +2511,7 @@ temp_valid_lft - INTEGER temp_prefered_lft - INTEGER Preferred lifetime (in seconds) for temporary addresses. If temp_prefered_lft is less than the minimum required lifetime (typically - 5 seconds), the preferred lifetime is the minimum required. If + 5 seconds), temporary addresses will not be created. If temp_prefered_lft is greater than temp_valid_lft, the preferred lifetime is temp_valid_lft. diff --git a/Documentation/networking/net_cachelines/index.rst b/Documentation/networking/net_cachelines/index.rst new file mode 100644 index 000000000000..2669e4cda086 --- /dev/null +++ b/Documentation/networking/net_cachelines/index.rst @@ -0,0 +1,16 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. Copyright (C) 2023 Google LLC + +=================================== +Common Networking Struct Cachelines +=================================== + +.. toctree:: + :maxdepth: 1 + + inet_connection_sock + inet_sock + net_device + netns_ipv4_sysctl + snmp + tcp_sock diff --git a/Documentation/networking/net_cachelines/inet_connection_sock.rst b/Documentation/networking/net_cachelines/inet_connection_sock.rst new file mode 100644 index 000000000000..7a911dc95652 --- /dev/null +++ b/Documentation/networking/net_cachelines/inet_connection_sock.rst @@ -0,0 +1,50 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. Copyright (C) 2023 Google LLC + +===================================================== +inet_connection_sock struct fast path usage breakdown +===================================================== + +Type Name fastpath_tx_access fastpath_rx_access comment +..struct ..inet_connection_sock +struct_inet_sock icsk_inet read_mostly read_mostly tcp_init_buffer_space,tcp_init_transfer,tcp_finish_connect,tcp_connect,tcp_send_rcvq,tcp_send_syn_data +struct_request_sock_queue icsk_accept_queue - - +struct_inet_bind_bucket icsk_bind_hash read_mostly - tcp_set_state +struct_inet_bind2_bucket icsk_bind2_hash read_mostly - tcp_set_state,inet_put_port +unsigned_long icsk_timeout read_mostly - inet_csk_reset_xmit_timer,tcp_connect +struct_timer_list icsk_retransmit_timer read_mostly - inet_csk_reset_xmit_timer,tcp_connect +struct_timer_list icsk_delack_timer read_mostly - inet_csk_reset_xmit_timer,tcp_connect +u32 icsk_rto read_write - tcp_cwnd_validate,tcp_schedule_loss_probe,tcp_connect_init,tcp_connect,tcp_write_xmit,tcp_push_one +u32 icsk_rto_min - - +u32 icsk_delack_max - - +u32 icsk_pmtu_cookie read_write - tcp_sync_mss,tcp_current_mss,tcp_send_syn_data,tcp_connect_init,tcp_connect +struct_tcp_congestion_ops icsk_ca_ops read_write - tcp_cwnd_validate,tcp_tso_segs,tcp_ca_dst_init,tcp_connect_init,tcp_connect,tcp_write_xmit +struct_inet_connection_sock_af_ops icsk_af_ops read_mostly - tcp_finish_connect,tcp_send_syn_data,tcp_mtup_init,tcp_mtu_check_reprobe,tcp_mtu_probe,tcp_connect_init,tcp_connect,__tcp_transmit_skb +struct_tcp_ulp_ops* icsk_ulp_ops - - +void* icsk_ulp_data - - +u8:5 icsk_ca_state read_write - tcp_cwnd_application_limited,tcp_set_ca_state,tcp_enter_cwr,tcp_tso_should_defer,tcp_mtu_probe,tcp_schedule_loss_probe,tcp_write_xmit,__tcp_transmit_skb +u8:1 icsk_ca_initialized read_write - tcp_init_transfer,tcp_init_congestion_control,tcp_init_transfer,tcp_finish_connect,tcp_connect +u8:1 icsk_ca_setsockopt - - +u8:1 icsk_ca_dst_locked write_mostly - tcp_ca_dst_init,tcp_connect_init,tcp_connect +u8 icsk_retransmits write_mostly - tcp_connect_init,tcp_connect +u8 icsk_pending read_write - inet_csk_reset_xmit_timer,tcp_connect,tcp_check_probe_timer,__tcp_push_pending_frames,tcp_rearm_rto,tcp_event_new_data_sent,tcp_event_new_data_sent +u8 icsk_backoff write_mostly - tcp_write_queue_purge,tcp_connect_init +u8 icsk_syn_retries - - +u8 icsk_probes_out - - +u16 icsk_ext_hdr_len read_mostly - __tcp_mtu_to_mss,tcp_mtu_to_rss,tcp_mtu_probe,tcp_write_xmit,tcp_mtu_to_mss, +struct_icsk_ack_u8 pending read_write read_write inet_csk_ack_scheduled,__tcp_cleanup_rbuf,tcp_cleanup_rbuf,inet_csk_clear_xmit_timer,tcp_event_ack-sent,inet_csk_reset_xmit_timer +struct_icsk_ack_u8 quick read_write write_mostly tcp_dec_quickack_mode,tcp_event_ack_sent,__tcp_transmit_skb,__tcp_select_window,__tcp_cleanup_rbuf +struct_icsk_ack_u8 pingpong - - +struct_icsk_ack_u8 retry write_mostly read_write inet_csk_clear_xmit_timer,tcp_rearm_rto,tcp_event_new_data_sent,tcp_write_xmit,__tcp_send_ack,tcp_send_ack, +struct_icsk_ack_u8 ato read_mostly write_mostly tcp_dec_quickack_mode,tcp_event_ack_sent,__tcp_transmit_skb,__tcp_send_ack,tcp_send_ack +struct_icsk_ack_unsigned_long timeout read_write read_write inet_csk_reset_xmit_timer,tcp_connect +struct_icsk_ack_u32 lrcvtime read_write - tcp_finish_connect,tcp_connect,tcp_event_data_sent,__tcp_transmit_skb +struct_icsk_ack_u16 rcv_mss write_mostly read_mostly __tcp_select_window,__tcp_cleanup_rbuf,tcp_initialize_rcv_mss,tcp_connect_init +struct_icsk_mtup_int search_high read_write - tcp_mtup_init,tcp_sync_mss,tcp_connect_init,tcp_mtu_check_reprobe,tcp_write_xmit +struct_icsk_mtup_int search_low read_write - tcp_mtu_probe,tcp_mtu_check_reprobe,tcp_write_xmit,tcp_sync_mss,tcp_connect_init,tcp_mtup_init +struct_icsk_mtup_u32:31 probe_size read_write - tcp_mtup_init,tcp_connect_init,__tcp_transmit_skb +struct_icsk_mtup_u32:1 enabled read_write - tcp_mtup_init,tcp_sync_mss,tcp_connect_init,tcp_mtu_probe,tcp_write_xmit +struct_icsk_mtup_u32 probe_timestamp read_write - tcp_mtup_init,tcp_connect_init,tcp_mtu_check_reprobe,tcp_mtu_probe +u32 icsk_probes_tstamp - - +u32 icsk_user_timeout - - +u64[104/sizeof(u64)] icsk_ca_priv - - diff --git a/Documentation/networking/net_cachelines/inet_sock.rst b/Documentation/networking/net_cachelines/inet_sock.rst new file mode 100644 index 000000000000..a2babd0d7954 --- /dev/null +++ b/Documentation/networking/net_cachelines/inet_sock.rst @@ -0,0 +1,44 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. Copyright (C) 2023 Google LLC + +===================================================== +inet_connection_sock struct fast path usage breakdown +===================================================== + +Type Name fastpath_tx_access fastpath_rx_access comment +..struct ..inet_sock +struct_sock sk read_mostly read_mostly tcp_init_buffer_space,tcp_init_transfer,tcp_finish_connect,tcp_connect,tcp_send_rcvq,tcp_send_syn_data +struct_ipv6_pinfo* pinet6 - - +be16 inet_sport read_mostly - __tcp_transmit_skb +be32 inet_daddr read_mostly - ip_select_ident_segs +be32 inet_rcv_saddr - - +be16 inet_dport read_mostly - __tcp_transmit_skb +u16 inet_num - - +be32 inet_saddr - - +s16 uc_ttl read_mostly - __ip_queue_xmit/ip_select_ttl +u16 cmsg_flags - - +struct_ip_options_rcu* inet_opt read_mostly - __ip_queue_xmit +u16 inet_id read_mostly - ip_select_ident_segs +u8 tos read_mostly - ip_queue_xmit +u8 min_ttl - - +u8 mc_ttl - - +u8 pmtudisc - - +u8:1 recverr - - +u8:1 is_icsk - - +u8:1 freebind - - +u8:1 hdrincl - - +u8:1 mc_loop - - +u8:1 transparent - - +u8:1 mc_all - - +u8:1 nodefrag - - +u8:1 bind_address_no_port - - +u8:1 recverr_rfc4884 - - +u8:1 defer_connect read_mostly - tcp_sendmsg_fastopen +u8 rcv_tos - - +u8 convert_csum - - +int uc_index - - +int mc_index - - +be32 mc_addr - - +struct_ip_mc_socklist* mc_list - - +struct_inet_cork_full cork read_mostly - __tcp_transmit_skb +struct local_port_range - - diff --git a/Documentation/networking/net_cachelines/net_device.rst b/Documentation/networking/net_cachelines/net_device.rst new file mode 100644 index 000000000000..e75a53593bb9 --- /dev/null +++ b/Documentation/networking/net_cachelines/net_device.rst @@ -0,0 +1,178 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. Copyright (C) 2023 Google LLC + +=========================================== +net_device struct fast path usage breakdown +=========================================== + +Type Name fastpath_tx_access fastpath_rx_access Comments +..struct ..net_device +char name[16] - - +struct_netdev_name_node* name_node +struct_dev_ifalias* ifalias +unsigned_long mem_end +unsigned_long mem_start +unsigned_long base_addr +unsigned_long state +struct_list_head dev_list +struct_list_head napi_list +struct_list_head unreg_list +struct_list_head close_list +struct_list_head ptype_all read_mostly - dev_nit_active(tx) +struct_list_head ptype_specific read_mostly deliver_ptype_list_skb/__netif_receive_skb_core(rx) +struct adj_list +unsigned_int flags read_mostly read_mostly __dev_queue_xmit,__dev_xmit_skb,ip6_output,__ip6_finish_output(tx);ip6_rcv_core(rx) +xdp_features_t xdp_features +unsigned_long_long priv_flags read_mostly - __dev_queue_xmit(tx) +struct_net_device_ops* netdev_ops read_mostly - netdev_core_pick_tx,netdev_start_xmit(tx) +struct_xdp_metadata_ops* xdp_metadata_ops +int ifindex - read_mostly ip6_rcv_core +unsigned_short gflags +unsigned_short hard_header_len read_mostly read_mostly ip6_xmit(tx);gro_list_prepare(rx) +unsigned_int mtu read_mostly - ip_finish_output2 +unsigned_short needed_headroom read_mostly - LL_RESERVED_SPACE/ip_finish_output2 +unsigned_short needed_tailroom +netdev_features_t features read_mostly read_mostly HARD_TX_LOCK,netif_skb_features,sk_setup_caps(tx);netif_elide_gro(rx) +netdev_features_t hw_features +netdev_features_t wanted_features +netdev_features_t vlan_features +netdev_features_t hw_enc_features - - netif_skb_features +netdev_features_t mpls_features +netdev_features_t gso_partial_features read_mostly gso_features_check +unsigned_int min_mtu +unsigned_int max_mtu +unsigned_short type +unsigned_char min_header_len +unsigned_char name_assign_type +int group +struct_net_device_stats stats +struct_net_device_core_stats* core_stats +atomic_t carrier_up_count +atomic_t carrier_down_count +struct_iw_handler_def* wireless_handlers +struct_iw_public_data* wireless_data +struct_ethtool_ops* ethtool_ops +struct_l3mdev_ops* l3mdev_ops +struct_ndisc_ops* ndisc_ops +struct_xfrmdev_ops* xfrmdev_ops +struct_tlsdev_ops* tlsdev_ops +struct_header_ops* header_ops read_mostly - ip_finish_output2,ip6_finish_output2(tx) +unsigned_char operstate +unsigned_char link_mode +unsigned_char if_port +unsigned_char dma +unsigned_char perm_addr[32] +unsigned_char addr_assign_type +unsigned_char addr_len +unsigned_char upper_level +unsigned_char lower_level +unsigned_short neigh_priv_len +unsigned_short padded +unsigned_short dev_id +unsigned_short dev_port +spinlock_t addr_list_lock +int irq +struct_netdev_hw_addr_list uc +struct_netdev_hw_addr_list mc +struct_netdev_hw_addr_list dev_addrs +struct_kset* queues_kset +struct_list_head unlink_list +unsigned_int promiscuity +unsigned_int allmulti +bool uc_promisc +unsigned_char nested_level +struct_in_device* ip_ptr read_mostly read_mostly __in_dev_get +struct_inet6_dev* ip6_ptr read_mostly read_mostly __in6_dev_get +struct_vlan_info* vlan_info +struct_dsa_port* dsa_ptr +struct_tipc_bearer* tipc_ptr +void* atalk_ptr +void* ax25_ptr +struct_wireless_dev* ieee80211_ptr +struct_wpan_dev* ieee802154_ptr +struct_mpls_dev* mpls_ptr +struct_mctp_dev* mctp_ptr +unsigned_char* dev_addr +struct_netdev_queue* _rx read_mostly - netdev_get_rx_queue(rx) +unsigned_int num_rx_queues +unsigned_int real_num_rx_queues - read_mostly get_rps_cpu +struct_bpf_prog* xdp_prog - read_mostly netif_elide_gro() +unsigned_long gro_flush_timeout - read_mostly napi_complete_done +int napi_defer_hard_irqs - read_mostly napi_complete_done +unsigned_int gro_max_size - read_mostly skb_gro_receive +unsigned_int gro_ipv4_max_size - read_mostly skb_gro_receive +rx_handler_func_t* rx_handler read_mostly - __netif_receive_skb_core +void* rx_handler_data read_mostly - +struct_netdev_queue* ingress_queue read_mostly - +struct_bpf_mprog_entry tcx_ingress - read_mostly sch_handle_ingress +struct_nf_hook_entries* nf_hooks_ingress +unsigned_char broadcast[32] +struct_cpu_rmap* rx_cpu_rmap +struct_hlist_node index_hlist +struct_netdev_queue* _tx read_mostly - netdev_get_tx_queue(tx) +unsigned_int num_tx_queues - - +unsigned_int real_num_tx_queues read_mostly - skb_tx_hash,netdev_core_pick_tx(tx) +unsigned_int tx_queue_len +spinlock_t tx_global_lock +struct_xdp_dev_bulk_queue__percpu* xdp_bulkq +struct_xps_dev_maps* xps_maps[2] read_mostly - __netif_set_xps_queue +struct_bpf_mprog_entry tcx_egress read_mostly - sch_handle_egress +struct_nf_hook_entries* nf_hooks_egress read_mostly - +struct_hlist_head qdisc_hash[16] +struct_timer_list watchdog_timer +int watchdog_timeo +u32 proto_down_reason +struct_list_head todo_list +int__percpu* pcpu_refcnt +refcount_t dev_refcnt +struct_ref_tracker_dir refcnt_tracker +struct_list_head link_watch_list +enum:8 reg_state +bool dismantle +enum:16 rtnl_link_state +bool needs_free_netdev +void*priv_destructor struct_net_device +struct_netpoll_info* npinfo - read_mostly napi_poll/napi_poll_lock +possible_net_t nd_net - read_mostly (dev_net)napi_busy_loop,tcp_v(4/6)_rcv,ip(v6)_rcv,ip(6)_input,ip(6)_input_finish +void* ml_priv +enum_netdev_ml_priv_type ml_priv_type +struct_pcpu_lstats__percpu* lstats +struct_pcpu_sw_netstats__percpu* tstats +struct_pcpu_dstats__percpu* dstats +struct_garp_port* garp_port +struct_mrp_port* mrp_port +struct_dm_hw_stat_delta* dm_private +struct_device dev - - +struct_attribute_group* sysfs_groups[4] +struct_attribute_group* sysfs_rx_queue_group +struct_rtnl_link_ops* rtnl_link_ops +unsigned_int gso_max_size read_mostly - sk_dst_gso_max_size +unsigned_int tso_max_size +u16 gso_max_segs read_mostly - gso_max_segs +u16 tso_max_segs +unsigned_int gso_ipv4_max_size read_mostly - sk_dst_gso_max_size +struct_dcbnl_rtnl_ops* dcbnl_ops +s16 num_tc read_mostly - skb_tx_hash +struct_netdev_tc_txq tc_to_txq[16] read_mostly - skb_tx_hash +u8 prio_tc_map[16] +unsigned_int fcoe_ddp_xid +struct_netprio_map* priomap +struct_phy_device* phydev +struct_sfp_bus* sfp_bus +struct_lock_class_key* qdisc_tx_busylock +bool proto_down +unsigned:1 wol_enabled +unsigned:1 threaded - - napi_poll(napi_enable,dev_set_threaded) +struct_list_head net_notifier_list +struct_macsec_ops* macsec_ops +struct_udp_tunnel_nic_info* udp_tunnel_nic_info +struct_udp_tunnel_nic* udp_tunnel_nic +unsigned_int xdp_zc_max_segs +struct_bpf_xdp_entity xdp_state[3] +u8 dev_addr_shadow[32] +netdevice_tracker linkwatch_dev_tracker +netdevice_tracker watchdog_dev_tracker +netdevice_tracker dev_registered_tracker +struct_rtnl_hw_stats64* offload_xstats_l3 +struct_devlink_port* devlink_port +struct_dpll_pin* dpll_pin diff --git a/Documentation/networking/net_cachelines/netns_ipv4_sysctl.rst b/Documentation/networking/net_cachelines/netns_ipv4_sysctl.rst new file mode 100644 index 000000000000..9b87089a84c6 --- /dev/null +++ b/Documentation/networking/net_cachelines/netns_ipv4_sysctl.rst @@ -0,0 +1,158 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. Copyright (C) 2023 Google LLC + +=========================================== +netns_ipv4 struct fast path usage breakdown +=========================================== + +Type Name fastpath_tx_access fastpath_rx_access comment +..struct ..netns_ipv4 +struct_inet_timewait_death_row tcp_death_row +struct_udp_table* udp_table +struct_ctl_table_header* forw_hdr +struct_ctl_table_header* frags_hdr +struct_ctl_table_header* ipv4_hdr +struct_ctl_table_header* route_hdr +struct_ctl_table_header* xfrm4_hdr +struct_ipv4_devconf* devconf_all +struct_ipv4_devconf* devconf_dflt +struct_ip_ra_chain ra_chain +struct_mutex ra_mutex +struct_fib_rules_ops* rules_ops +struct_fib_table fib_main +struct_fib_table fib_default +unsigned_int fib_rules_require_fldissect +bool fib_has_custom_rules +bool fib_has_custom_local_routes +bool fib_offload_disabled +atomic_t fib_num_tclassid_users +struct_hlist_head* fib_table_hash +struct_sock* fibnl +struct_sock* mc_autojoin_sk +struct_inet_peer_base* peers +struct_fqdir* fqdir +u8 sysctl_icmp_echo_ignore_all +u8 sysctl_icmp_echo_enable_probe +u8 sysctl_icmp_echo_ignore_broadcasts +u8 sysctl_icmp_ignore_bogus_error_responses +u8 sysctl_icmp_errors_use_inbound_ifaddr +int sysctl_icmp_ratelimit +int sysctl_icmp_ratemask +u32 ip_rt_min_pmtu - - +int ip_rt_mtu_expires - - +int ip_rt_min_advmss - - +struct_local_ports ip_local_ports - - +u8 sysctl_tcp_ecn - - +u8 sysctl_tcp_ecn_fallback - - +u8 sysctl_ip_default_ttl - - ip4_dst_hoplimit/ip_select_ttl +u8 sysctl_ip_no_pmtu_disc - - +u8 sysctl_ip_fwd_use_pmtu read_mostly - ip_dst_mtu_maybe_forward/ip_skb_dst_mtu +u8 sysctl_ip_fwd_update_priority - - ip_forward +u8 sysctl_ip_nonlocal_bind - - +u8 sysctl_ip_autobind_reuse - - +u8 sysctl_ip_dynaddr - - +u8 sysctl_ip_early_demux - read_mostly ip(6)_rcv_finish_core +u8 sysctl_raw_l3mdev_accept - - +u8 sysctl_tcp_early_demux - read_mostly ip(6)_rcv_finish_core +u8 sysctl_udp_early_demux +u8 sysctl_nexthop_compat_mode - - +u8 sysctl_fwmark_reflect - - +u8 sysctl_tcp_fwmark_accept - - +u8 sysctl_tcp_l3mdev_accept - - +u8 sysctl_tcp_mtu_probing - - +int sysctl_tcp_mtu_probe_floor - - +int sysctl_tcp_base_mss - - +int sysctl_tcp_min_snd_mss read_mostly - __tcp_mtu_to_mss(tcp_write_xmit) +int sysctl_tcp_probe_threshold - - tcp_mtu_probe(tcp_write_xmit) +u32 sysctl_tcp_probe_interval - - tcp_mtu_check_reprobe(tcp_write_xmit) +int sysctl_tcp_keepalive_time - - +int sysctl_tcp_keepalive_intvl - - +u8 sysctl_tcp_keepalive_probes - - +u8 sysctl_tcp_syn_retries - - +u8 sysctl_tcp_synack_retries - - +u8 sysctl_tcp_syncookies - - generated_on_syn +u8 sysctl_tcp_migrate_req - - reuseport +u8 sysctl_tcp_comp_sack_nr - - __tcp_ack_snd_check +int sysctl_tcp_reordering - read_mostly tcp_may_raise_cwnd/tcp_cong_control +u8 sysctl_tcp_retries1 - - +u8 sysctl_tcp_retries2 - - +u8 sysctl_tcp_orphan_retries - - +u8 sysctl_tcp_tw_reuse - - timewait_sock_ops +int sysctl_tcp_fin_timeout - - TCP_LAST_ACK/tcp_rcv_state_process +unsigned_int sysctl_tcp_notsent_lowat read_mostly - tcp_notsent_lowat/tcp_stream_memory_free +u8 sysctl_tcp_sack - - tcp_syn_options +u8 sysctl_tcp_window_scaling - - tcp_syn_options,tcp_parse_options +u8 sysctl_tcp_timestamps +u8 sysctl_tcp_early_retrans read_mostly - tcp_schedule_loss_probe(tcp_write_xmit) +u8 sysctl_tcp_recovery - - tcp_fastretrans_alert +u8 sysctl_tcp_thin_linear_timeouts - - tcp_retrans_timer(on_thin_streams) +u8 sysctl_tcp_slow_start_after_idle - - unlikely(tcp_cwnd_validate-network-not-starved) +u8 sysctl_tcp_retrans_collapse - - +u8 sysctl_tcp_stdurg - - unlikely(tcp_check_urg) +u8 sysctl_tcp_rfc1337 - - +u8 sysctl_tcp_abort_on_overflow - - +u8 sysctl_tcp_fack - - +int sysctl_tcp_max_reordering - - tcp_check_sack_reordering +int sysctl_tcp_adv_win_scale - - tcp_init_buffer_space +u8 sysctl_tcp_dsack - - partial_packet_or_retrans_in_tcp_data_queue +u8 sysctl_tcp_app_win - - tcp_win_from_space +u8 sysctl_tcp_frto - - tcp_enter_loss +u8 sysctl_tcp_nometrics_save - - TCP_LAST_ACK/tcp_update_metrics +u8 sysctl_tcp_no_ssthresh_metrics_save - - TCP_LAST_ACK/tcp_(update/init)_metrics +u8 sysctl_tcp_moderate_rcvbuf read_mostly read_mostly tcp_tso_should_defer(tx);tcp_rcv_space_adjust(rx) +u8 sysctl_tcp_tso_win_divisor read_mostly - tcp_tso_should_defer(tcp_write_xmit) +u8 sysctl_tcp_workaround_signed_windows - - tcp_select_window +int sysctl_tcp_limit_output_bytes read_mostly - tcp_small_queue_check(tcp_write_xmit) +int sysctl_tcp_challenge_ack_limit - - +int sysctl_tcp_min_rtt_wlen read_mostly - tcp_ack_update_rtt +u8 sysctl_tcp_min_tso_segs - - unlikely(icsk_ca_ops-written) +u8 sysctl_tcp_tso_rtt_log read_mostly - tcp_tso_autosize +u8 sysctl_tcp_autocorking read_mostly - tcp_push/tcp_should_autocork +u8 sysctl_tcp_reflect_tos - - tcp_v(4/6)_send_synack +int sysctl_tcp_invalid_ratelimit - - +int sysctl_tcp_pacing_ss_ratio - - default_cong_cont(tcp_update_pacing_rate) +int sysctl_tcp_pacing_ca_ratio - - default_cong_cont(tcp_update_pacing_rate) +int sysctl_tcp_wmem[3] read_mostly - tcp_wmem_schedule(sendmsg/sendpage) +int sysctl_tcp_rmem[3] - read_mostly __tcp_grow_window(tx),tcp_rcv_space_adjust(rx) +unsigned_int sysctl_tcp_child_ehash_entries +unsigned_long sysctl_tcp_comp_sack_delay_ns - - __tcp_ack_snd_check +unsigned_long sysctl_tcp_comp_sack_slack_ns - - __tcp_ack_snd_check +int sysctl_max_syn_backlog - - +int sysctl_tcp_fastopen - - +struct_tcp_congestion_ops tcp_congestion_control - - init_cc +struct_tcp_fastopen_context tcp_fastopen_ctx - - +unsigned_int sysctl_tcp_fastopen_blackhole_timeout - - +atomic_t tfo_active_disable_times - - +unsigned_long tfo_active_disable_stamp - - +u32 tcp_challenge_timestamp - - +u32 tcp_challenge_count - - +u8 sysctl_tcp_plb_enabled - - +u8 sysctl_tcp_plb_idle_rehash_rounds - - +u8 sysctl_tcp_plb_rehash_rounds - - +u8 sysctl_tcp_plb_suspend_rto_sec - - +int sysctl_tcp_plb_cong_thresh - - +int sysctl_udp_wmem_min +int sysctl_udp_rmem_min +u8 sysctl_fib_notify_on_flag_change +u8 sysctl_udp_l3mdev_accept +u8 sysctl_igmp_llm_reports +int sysctl_igmp_max_memberships +int sysctl_igmp_max_msf +int sysctl_igmp_qrv +struct_ping_group_range ping_group_range +atomic_t dev_addr_genid +unsigned_int sysctl_udp_child_hash_entries +unsigned_long* sysctl_local_reserved_ports +int sysctl_ip_prot_sock +struct_mr_table* mrt +struct_list_head mr_tables +struct_fib_rules_ops* mr_rules_ops +u32 sysctl_fib_multipath_hash_fields +u8 sysctl_fib_multipath_use_neigh +u8 sysctl_fib_multipath_hash_policy +struct_fib_notifier_ops* notifier_ops +unsigned_int fib_seq +struct_fib_notifier_ops* ipmr_notifier_ops +unsigned_int ipmr_seq +atomic_t rt_genid +siphash_key_t ip_id_key diff --git a/Documentation/networking/net_cachelines/snmp.rst b/Documentation/networking/net_cachelines/snmp.rst new file mode 100644 index 000000000000..6a071538566c --- /dev/null +++ b/Documentation/networking/net_cachelines/snmp.rst @@ -0,0 +1,135 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. Copyright (C) 2023 Google LLC + +=========================================== +netns_ipv4 enum fast path usage breakdown +=========================================== + +Type Name fastpath_tx_access fastpath_rx_access comment +..enum +unsigned_long LINUX_MIB_TCPKEEPALIVE write_mostly - tcp_keepalive_timer +unsigned_long LINUX_MIB_DELAYEDACKS write_mostly - tcp_delack_timer_handler,tcp_delack_timer +unsigned_long LINUX_MIB_DELAYEDACKLOCKED write_mostly - tcp_delack_timer_handler,tcp_delack_timer +unsigned_long LINUX_MIB_TCPAUTOCORKING write_mostly - tcp_push,tcp_sendmsg_locked +unsigned_long LINUX_MIB_TCPFROMZEROWINDOWADV write_mostly - tcp_select_window,tcp_transmit-skb +unsigned_long LINUX_MIB_TCPTOZEROWINDOWADV write_mostly - tcp_select_window,tcp_transmit-skb +unsigned_long LINUX_MIB_TCPWANTZEROWINDOWADV write_mostly - tcp_select_window,tcp_transmit-skb +unsigned_long LINUX_MIB_TCPORIGDATASENT write_mostly - tcp_write_xmit +unsigned_long LINUX_MIB_TCPHPHITS - write_mostly tcp_rcv_established,tcp_v4_do_rcv,tcp_v6_do_rcv +unsigned_long LINUX_MIB_TCPRCVCOALESCE - write_mostly tcp_try_coalesce,tcp_queue_rcv,tcp_rcv_established +unsigned_long LINUX_MIB_TCPPUREACKS - write_mostly tcp_ack,tcp_rcv_established +unsigned_long LINUX_MIB_TCPHPACKS - write_mostly tcp_ack,tcp_rcv_established +unsigned_long LINUX_MIB_TCPDELIVERED - write_mostly tcp_newly_delivered,tcp_ack,tcp_rcv_established +unsigned_long LINUX_MIB_SYNCOOKIESSENT +unsigned_long LINUX_MIB_SYNCOOKIESRECV +unsigned_long LINUX_MIB_SYNCOOKIESFAILED +unsigned_long LINUX_MIB_EMBRYONICRSTS +unsigned_long LINUX_MIB_PRUNECALLED +unsigned_long LINUX_MIB_RCVPRUNED +unsigned_long LINUX_MIB_OFOPRUNED +unsigned_long LINUX_MIB_OUTOFWINDOWICMPS +unsigned_long LINUX_MIB_LOCKDROPPEDICMPS +unsigned_long LINUX_MIB_ARPFILTER +unsigned_long LINUX_MIB_TIMEWAITED +unsigned_long LINUX_MIB_TIMEWAITRECYCLED +unsigned_long LINUX_MIB_TIMEWAITKILLED +unsigned_long LINUX_MIB_PAWSACTIVEREJECTED +unsigned_long LINUX_MIB_PAWSESTABREJECTED +unsigned_long LINUX_MIB_DELAYEDACKLOST +unsigned_long LINUX_MIB_LISTENOVERFLOWS +unsigned_long LINUX_MIB_LISTENDROPS +unsigned_long LINUX_MIB_TCPRENORECOVERY +unsigned_long LINUX_MIB_TCPSACKRECOVERY +unsigned_long LINUX_MIB_TCPSACKRENEGING +unsigned_long LINUX_MIB_TCPSACKREORDER +unsigned_long LINUX_MIB_TCPRENOREORDER +unsigned_long LINUX_MIB_TCPTSREORDER +unsigned_long LINUX_MIB_TCPFULLUNDO +unsigned_long LINUX_MIB_TCPPARTIALUNDO +unsigned_long LINUX_MIB_TCPDSACKUNDO +unsigned_long LINUX_MIB_TCPLOSSUNDO +unsigned_long LINUX_MIB_TCPLOSTRETRANSMIT +unsigned_long LINUX_MIB_TCPRENOFAILURES +unsigned_long LINUX_MIB_TCPSACKFAILURES +unsigned_long LINUX_MIB_TCPLOSSFAILURES +unsigned_long LINUX_MIB_TCPFASTRETRANS +unsigned_long LINUX_MIB_TCPSLOWSTARTRETRANS +unsigned_long LINUX_MIB_TCPTIMEOUTS +unsigned_long LINUX_MIB_TCPLOSSPROBES +unsigned_long LINUX_MIB_TCPLOSSPROBERECOVERY +unsigned_long LINUX_MIB_TCPRENORECOVERYFAIL +unsigned_long LINUX_MIB_TCPSACKRECOVERYFAIL +unsigned_long LINUX_MIB_TCPRCVCOLLAPSED +unsigned_long LINUX_MIB_TCPDSACKOLDSENT +unsigned_long LINUX_MIB_TCPDSACKOFOSENT +unsigned_long LINUX_MIB_TCPDSACKRECV +unsigned_long LINUX_MIB_TCPDSACKOFORECV +unsigned_long LINUX_MIB_TCPABORTONDATA +unsigned_long LINUX_MIB_TCPABORTONCLOSE +unsigned_long LINUX_MIB_TCPABORTONMEMORY +unsigned_long LINUX_MIB_TCPABORTONTIMEOUT +unsigned_long LINUX_MIB_TCPABORTONLINGER +unsigned_long LINUX_MIB_TCPABORTFAILED +unsigned_long LINUX_MIB_TCPMEMORYPRESSURES +unsigned_long LINUX_MIB_TCPMEMORYPRESSURESCHRONO +unsigned_long LINUX_MIB_TCPSACKDISCARD +unsigned_long LINUX_MIB_TCPDSACKIGNOREDOLD +unsigned_long LINUX_MIB_TCPDSACKIGNOREDNOUNDO +unsigned_long LINUX_MIB_TCPSPURIOUSRTOS +unsigned_long LINUX_MIB_TCPMD5NOTFOUND +unsigned_long LINUX_MIB_TCPMD5UNEXPECTED +unsigned_long LINUX_MIB_TCPMD5FAILURE +unsigned_long LINUX_MIB_SACKSHIFTED +unsigned_long LINUX_MIB_SACKMERGED +unsigned_long LINUX_MIB_SACKSHIFTFALLBACK +unsigned_long LINUX_MIB_TCPBACKLOGDROP +unsigned_long LINUX_MIB_PFMEMALLOCDROP +unsigned_long LINUX_MIB_TCPMINTTLDROP +unsigned_long LINUX_MIB_TCPDEFERACCEPTDROP +unsigned_long LINUX_MIB_IPRPFILTER +unsigned_long LINUX_MIB_TCPTIMEWAITOVERFLOW +unsigned_long LINUX_MIB_TCPREQQFULLDOCOOKIES +unsigned_long LINUX_MIB_TCPREQQFULLDROP +unsigned_long LINUX_MIB_TCPRETRANSFAIL +unsigned_long LINUX_MIB_TCPBACKLOGCOALESCE +unsigned_long LINUX_MIB_TCPOFOQUEUE +unsigned_long LINUX_MIB_TCPOFODROP +unsigned_long LINUX_MIB_TCPOFOMERGE +unsigned_long LINUX_MIB_TCPCHALLENGEACK +unsigned_long LINUX_MIB_TCPSYNCHALLENGE +unsigned_long LINUX_MIB_TCPFASTOPENACTIVE +unsigned_long LINUX_MIB_TCPFASTOPENACTIVEFAIL +unsigned_long LINUX_MIB_TCPFASTOPENPASSIVE +unsigned_long LINUX_MIB_TCPFASTOPENPASSIVEFAIL +unsigned_long LINUX_MIB_TCPFASTOPENLISTENOVERFLOW +unsigned_long LINUX_MIB_TCPFASTOPENCOOKIEREQD +unsigned_long LINUX_MIB_TCPFASTOPENBLACKHOLE +unsigned_long LINUX_MIB_TCPSPURIOUS_RTX_HOSTQUEUES +unsigned_long LINUX_MIB_BUSYPOLLRXPACKETS +unsigned_long LINUX_MIB_TCPSYNRETRANS +unsigned_long LINUX_MIB_TCPHYSTARTTRAINDETECT +unsigned_long LINUX_MIB_TCPHYSTARTTRAINCWND +unsigned_long LINUX_MIB_TCPHYSTARTDELAYDETECT +unsigned_long LINUX_MIB_TCPHYSTARTDELAYCWND +unsigned_long LINUX_MIB_TCPACKSKIPPEDSYNRECV +unsigned_long LINUX_MIB_TCPACKSKIPPEDPAWS +unsigned_long LINUX_MIB_TCPACKSKIPPEDSEQ +unsigned_long LINUX_MIB_TCPACKSKIPPEDFINWAIT2 +unsigned_long LINUX_MIB_TCPACKSKIPPEDTIMEWAIT +unsigned_long LINUX_MIB_TCPACKSKIPPEDCHALLENGE +unsigned_long LINUX_MIB_TCPWINPROBE +unsigned_long LINUX_MIB_TCPMTUPFAIL +unsigned_long LINUX_MIB_TCPMTUPSUCCESS +unsigned_long LINUX_MIB_TCPDELIVEREDCE +unsigned_long LINUX_MIB_TCPACKCOMPRESSED +unsigned_long LINUX_MIB_TCPZEROWINDOWDROP +unsigned_long LINUX_MIB_TCPRCVQDROP +unsigned_long LINUX_MIB_TCPWQUEUETOOBIG +unsigned_long LINUX_MIB_TCPFASTOPENPASSIVEALTKEY +unsigned_long LINUX_MIB_TCPTIMEOUTREHASH +unsigned_long LINUX_MIB_TCPDUPLICATEDATAREHASH +unsigned_long LINUX_MIB_TCPDSACKRECVSEGS +unsigned_long LINUX_MIB_TCPDSACKIGNOREDDUBIOUS +unsigned_long LINUX_MIB_TCPMIGRATEREQSUCCESS +unsigned_long LINUX_MIB_TCPMIGRATEREQFAILURE +unsigned_long __LINUX_MIB_MAX diff --git a/Documentation/networking/net_cachelines/tcp_sock.rst b/Documentation/networking/net_cachelines/tcp_sock.rst new file mode 100644 index 000000000000..97d7a5c8e01c --- /dev/null +++ b/Documentation/networking/net_cachelines/tcp_sock.rst @@ -0,0 +1,157 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. Copyright (C) 2023 Google LLC + +========================================= +tcp_sock struct fast path usage breakdown +========================================= + +Type Name fastpath_tx_access fastpath_rx_access Comments +..struct ..tcp_sock +struct_inet_connection_sock inet_conn +u16 tcp_header_len read_mostly read_mostly tcp_bound_to_half_wnd,tcp_current_mss(tx);tcp_rcv_established(rx) +u16 gso_segs read_mostly - tcp_xmit_size_goal +__be32 pred_flags read_write read_mostly tcp_select_window(tx);tcp_rcv_established(rx) +u64 bytes_received - read_write tcp_rcv_nxt_update(rx) +u32 segs_in - read_write tcp_v6_rcv(rx) +u32 data_segs_in - read_write tcp_v6_rcv(rx) +u32 rcv_nxt read_mostly read_write tcp_cleanup_rbuf,tcp_send_ack,tcp_inq_hint,tcp_transmit_skb,tcp_receive_window(tx);tcp_v6_do_rcv,tcp_rcv_established,tcp_data_queue,tcp_receive_window,tcp_rcv_nxt_update(write)(rx) +u32 copied_seq - read_mostly tcp_cleanup_rbuf,tcp_rcv_space_adjust,tcp_inq_hint +u32 rcv_wup - read_write __tcp_cleanup_rbuf,tcp_receive_window,tcp_receive_established +u32 snd_nxt read_write read_mostly tcp_rate_check_app_limited,__tcp_transmit_skb,tcp_event_new_data_sent(write)(tx);tcp_rcv_established,tcp_ack,tcp_clean_rtx_queue(rx) +u32 segs_out read_write - __tcp_transmit_skb +u32 data_segs_out read_write - __tcp_transmit_skb,tcp_update_skb_after_send +u64 bytes_sent read_write - __tcp_transmit_skb +u64 bytes_acked - read_write tcp_snd_una_update/tcp_ack +u32 dsack_dups +u32 snd_una read_mostly read_write tcp_wnd_end,tcp_urg_mode,tcp_minshall_check,tcp_cwnd_validate(tx);tcp_ack,tcp_may_update_window,tcp_clean_rtx_queue(write),tcp_ack_tstamp(rx) +u32 snd_sml read_write - tcp_minshall_check,tcp_minshall_update +u32 rcv_tstamp - read_mostly tcp_ack +u32 lsndtime read_write - tcp_slow_start_after_idle_check,tcp_event_data_sent +u32 last_oow_ack_time +u32 compressed_ack_rcv_nxt +u32 tsoffset read_mostly read_mostly tcp_established_options(tx);tcp_fast_parse_options(rx) +struct_list_head tsq_node - - +struct_list_head tsorted_sent_queue read_write - tcp_update_skb_after_send +u32 snd_wl1 - read_mostly tcp_may_update_window +u32 snd_wnd read_mostly read_mostly tcp_wnd_end,tcp_tso_should_defer(tx);tcp_fast_path_on(rx) +u32 max_window read_mostly - tcp_bound_to_half_wnd,forced_push +u32 mss_cache read_mostly read_mostly tcp_rate_check_app_limited,tcp_current_mss,tcp_sync_mss,tcp_sndbuf_expand,tcp_tso_should_defer(tx);tcp_update_pacing_rate,tcp_clean_rtx_queue(rx) +u32 window_clamp read_mostly read_write tcp_rcv_space_adjust,__tcp_select_window +u32 rcv_ssthresh read_mostly - __tcp_select_window +u82 scaling_ratio +struct tcp_rack +u16 advmss - read_mostly tcp_rcv_space_adjust +u8 compressed_ack +u8:2 dup_ack_counter +u8:1 tlp_retrans +u8:1 tcp_usec_ts +u32 chrono_start read_write - tcp_chrono_start/stop(tcp_write_xmit,tcp_cwnd_validate,tcp_send_syn_data) +u32[3] chrono_stat read_write - tcp_chrono_start/stop(tcp_write_xmit,tcp_cwnd_validate,tcp_send_syn_data) +u8:2 chrono_type read_write - tcp_chrono_start/stop(tcp_write_xmit,tcp_cwnd_validate,tcp_send_syn_data) +u8:1 rate_app_limited - read_write tcp_rate_gen +u8:1 fastopen_connect +u8:1 fastopen_no_cookie +u8:1 is_sack_reneg - read_mostly tcp_skb_entail,tcp_ack +u8:2 fastopen_client_fail +u8:4 nonagle read_write - tcp_skb_entail,tcp_push_pending_frames +u8:1 thin_lto +u8:1 recvmsg_inq +u8:1 repair read_mostly - tcp_write_xmit +u8:1 frto +u8 repair_queue - - +u8:2 save_syn +u8:1 syn_data +u8:1 syn_fastopen +u8:1 syn_fastopen_exp +u8:1 syn_fastopen_ch +u8:1 syn_data_acked +u8:1 is_cwnd_limited read_mostly - tcp_cwnd_validate,tcp_is_cwnd_limited +u32 tlp_high_seq - read_mostly tcp_ack +u32 tcp_tx_delay +u64 tcp_wstamp_ns read_write - tcp_pacing_check,tcp_tso_should_defer,tcp_update_skb_after_send +u64 tcp_clock_cache read_write read_write tcp_mstamp_refresh(tcp_write_xmit/tcp_rcv_space_adjust),__tcp_transmit_skb,tcp_tso_should_defer;timer +u64 tcp_mstamp read_write read_write tcp_mstamp_refresh(tcp_write_xmit/tcp_rcv_space_adjust)(tx);tcp_rcv_space_adjust,tcp_rate_gen,tcp_clean_rtx_queue,tcp_ack_update_rtt/tcp_time_stamp(rx);timer +u32 srtt_us read_mostly read_write tcp_tso_should_defer(tx);tcp_update_pacing_rate,__tcp_set_rto,tcp_rtt_estimator(rx) +u32 mdev_us read_write - tcp_rtt_estimator +u32 mdev_max_us +u32 rttvar_us - read_mostly __tcp_set_rto +u32 rtt_seq read_write tcp_rtt_estimator +struct_minmax rtt_min - read_mostly tcp_min_rtt/tcp_rate_gen,tcp_min_rtttcp_update_rtt_min +u32 packets_out read_write read_write tcp_packets_in_flight(tx/rx);tcp_slow_start_after_idle_check,tcp_nagle_check,tcp_rate_skb_sent,tcp_event_new_data_sent,tcp_cwnd_validate,tcp_write_xmit(tx);tcp_ack,tcp_clean_rtx_queue,tcp_update_pacing_rate(rx) +u32 retrans_out - read_mostly tcp_packets_in_flight,tcp_rate_check_app_limited +u32 max_packets_out - read_write tcp_cwnd_validate +u32 cwnd_usage_seq - read_write tcp_cwnd_validate +u16 urg_data - read_mostly tcp_fast_path_check +u8 ecn_flags read_write - tcp_ecn_send +u8 keepalive_probes +u32 reordering read_mostly - tcp_sndbuf_expand +u32 reord_seen +u32 snd_up read_write read_mostly tcp_mark_urg,tcp_urg_mode,__tcp_transmit_skb(tx);tcp_clean_rtx_queue(rx) +struct_tcp_options_received rx_opt read_mostly read_write tcp_established_options(tx);tcp_fast_path_on,tcp_ack_update_window,tcp_is_sack,tcp_data_queue,tcp_rcv_established,tcp_ack_update_rtt(rx) +u32 snd_ssthresh - read_mostly tcp_update_pacing_rate +u32 snd_cwnd read_mostly read_mostly tcp_snd_cwnd,tcp_rate_check_app_limited,tcp_tso_should_defer(tx);tcp_update_pacing_rate +u32 snd_cwnd_cnt +u32 snd_cwnd_clamp +u32 snd_cwnd_used +u32 snd_cwnd_stamp +u32 prior_cwnd +u32 prr_delivered +u32 prr_out read_mostly read_mostly tcp_rate_skb_sent,tcp_newly_delivered(tx);tcp_ack,tcp_rate_gen,tcp_clean_rtx_queue(rx) +u32 delivered read_mostly read_write tcp_rate_skb_sent, tcp_newly_delivered(tx);tcp_ack, tcp_rate_gen, tcp_clean_rtx_queue (rx) +u32 delivered_ce read_mostly read_write tcp_rate_skb_sent(tx);tcp_rate_gen(rx) +u32 lost - read_mostly tcp_ack +u32 app_limited read_write read_mostly tcp_rate_check_app_limited,tcp_rate_skb_sent(tx);tcp_rate_gen(rx) +u64 first_tx_mstamp read_write - tcp_rate_skb_sent +u64 delivered_mstamp read_write - tcp_rate_skb_sent +u32 rate_delivered - read_mostly tcp_rate_gen +u32 rate_interval_us - read_mostly rate_delivered,rate_app_limited +u32 rcv_wnd read_write read_mostly tcp_select_window,tcp_receive_window,tcp_fast_path_check +u32 write_seq read_write - tcp_rate_check_app_limited,tcp_write_queue_empty,tcp_skb_entail,forced_push,tcp_mark_push +u32 notsent_lowat read_mostly - tcp_stream_memory_free +u32 pushed_seq read_write - tcp_mark_push,forced_push +u32 lost_out read_mostly read_mostly tcp_left_out(tx);tcp_packets_in_flight(tx/rx);tcp_rate_check_app_limited(rx) +u32 sacked_out read_mostly read_mostly tcp_left_out(tx);tcp_packets_in_flight(tx/rx);tcp_clean_rtx_queue(rx) +struct_hrtimer pacing_timer +struct_hrtimer compressed_ack_timer +struct_sk_buff* lost_skb_hint read_mostly tcp_clean_rtx_queue +struct_sk_buff* retransmit_skb_hint read_mostly - tcp_clean_rtx_queue +struct_rb_root out_of_order_queue - read_mostly tcp_data_queue,tcp_fast_path_check +struct_sk_buff* ooo_last_skb +struct_tcp_sack_block[1] duplicate_sack +struct_tcp_sack_block[4] selective_acks +struct_tcp_sack_block[4] recv_sack_cache +struct_sk_buff* highest_sack read_write - tcp_event_new_data_sent +int lost_cnt_hint +u32 prior_ssthresh +u32 high_seq +u32 retrans_stamp +u32 undo_marker +int undo_retrans +u64 bytes_retrans +u32 total_retrans +u32 rto_stamp +u16 total_rto +u16 total_rto_recoveries +u32 total_rto_time +u32 urg_seq - - +unsigned_int keepalive_time +unsigned_int keepalive_intvl +int linger2 +u8 bpf_sock_ops_cb_flags +u8:1 bpf_chg_cc_inprogress +u16 timeout_rehash +u32 rcv_ooopack +u32 rcv_rtt_last_tsecr +struct rcv_rtt_est - read_write tcp_rcv_space_adjust,tcp_rcv_established +struct rcvq_space - read_write tcp_rcv_space_adjust +struct mtu_probe +u32 plb_rehash +u32 mtu_info +bool is_mptcp +bool smc_hs_congested +bool syn_smc +struct_tcp_sock_af_ops* af_specific +struct_tcp_md5sig_info* md5sig_info +struct_tcp_fastopen_request* fastopen_req +struct_request_sock* fastopen_rsk +struct_saved_syn* saved_syn
\ No newline at end of file diff --git a/Documentation/networking/netlink_spec/.gitignore b/Documentation/networking/netlink_spec/.gitignore new file mode 100644 index 000000000000..30d85567b592 --- /dev/null +++ b/Documentation/networking/netlink_spec/.gitignore @@ -0,0 +1 @@ +*.rst diff --git a/Documentation/networking/netlink_spec/readme.txt b/Documentation/networking/netlink_spec/readme.txt new file mode 100644 index 000000000000..6763f99d216c --- /dev/null +++ b/Documentation/networking/netlink_spec/readme.txt @@ -0,0 +1,4 @@ +SPDX-License-Identifier: GPL-2.0 + +This file is populated during the build of the documentation (htmldocs) by the +tools/net/ynl/ynl-gen-rst.py script. diff --git a/Documentation/networking/packet_mmap.rst b/Documentation/networking/packet_mmap.rst index 30a3be3c48f3..dca15d15feaf 100644 --- a/Documentation/networking/packet_mmap.rst +++ b/Documentation/networking/packet_mmap.rst @@ -263,20 +263,20 @@ the name indicates, this function allocates pages of memory, and the second argument is "order" or a power of two number of pages, that is (for PAGE_SIZE == 4096) order=0 ==> 4096 bytes, order=1 ==> 8192 bytes, order=2 ==> 16384 bytes, etc. The maximum size of a -region allocated by __get_free_pages is determined by the MAX_ORDER macro. More -precisely the limit can be calculated as:: +region allocated by __get_free_pages is determined by the MAX_PAGE_ORDER macro. +More precisely the limit can be calculated as:: - PAGE_SIZE << MAX_ORDER + PAGE_SIZE << MAX_PAGE_ORDER In a i386 architecture PAGE_SIZE is 4096 bytes - In a 2.4/i386 kernel MAX_ORDER is 10 - In a 2.6/i386 kernel MAX_ORDER is 11 + In a 2.4/i386 kernel MAX_PAGE_ORDER is 10 + In a 2.6/i386 kernel MAX_PAGE_ORDER is 11 So get_free_pages can allocate as much as 4MB or 8MB in a 2.4/2.6 kernel respectively, with an i386 architecture. User space programs can include /usr/include/sys/user.h and -/usr/include/linux/mmzone.h to get PAGE_SIZE MAX_ORDER declarations. +/usr/include/linux/mmzone.h to get PAGE_SIZE MAX_PAGE_ORDER declarations. The pagesize can also be determined dynamically with the getpagesize (2) system call. @@ -324,7 +324,7 @@ Definitions: (see /proc/slabinfo) <pointer size> depends on the architecture -- ``sizeof(void *)`` <page size> depends on the architecture -- PAGE_SIZE or getpagesize (2) -<max-order> is the value defined with MAX_ORDER +<max-order> is the value defined with MAX_PAGE_ORDER <frame size> it's an upper bound of frame's capture size (more on this later) ============== ================================================================ diff --git a/Documentation/networking/page_pool.rst b/Documentation/networking/page_pool.rst index 60993cb56b32..9d958128a57c 100644 --- a/Documentation/networking/page_pool.rst +++ b/Documentation/networking/page_pool.rst @@ -41,6 +41,11 @@ Architecture overview | Fast cache | | ptr-ring cache | +-----------------+ +------------------+ +Monitoring +========== +Information about page pools on the system can be accessed via the netdev +genetlink family (see Documentation/netlink/specs/netdev.yaml). + API interface ============= The number of pools created **must** match the number of hardware queues @@ -107,8 +112,9 @@ page_pool_get_stats() and structures described below are available. It takes a pointer to a ``struct page_pool`` and a pointer to a struct page_pool_stats allocated by the caller. -The API will fill in the provided struct page_pool_stats with -statistics about the page_pool. +Older drivers expose page pool statistics via ethtool or debugfs. +The same statistics are accessible via the netlink netdev family +in a driver-independent fashion. .. kernel-doc:: include/net/page_pool/types.h :identifiers: struct page_pool_recycle_stats diff --git a/Documentation/networking/scaling.rst b/Documentation/networking/scaling.rst index 03ae19a689fc..4eb50bcb9d42 100644 --- a/Documentation/networking/scaling.rst +++ b/Documentation/networking/scaling.rst @@ -44,6 +44,21 @@ by masking out the low order seven bits of the computed hash for the packet (usually a Toeplitz hash), taking this number as a key into the indirection table and reading the corresponding value. +Some NICs support symmetric RSS hashing where, if the IP (source address, +destination address) and TCP/UDP (source port, destination port) tuples +are swapped, the computed hash is the same. This is beneficial in some +applications that monitor TCP/IP flows (IDS, firewalls, ...etc) and need +both directions of the flow to land on the same Rx queue (and CPU). The +"Symmetric-XOR" is a type of RSS algorithms that achieves this hash +symmetry by XORing the input source and destination fields of the IP +and/or L4 protocols. This, however, results in reduced input entropy and +could potentially be exploited. Specifically, the algorithm XORs the input +as follows:: + + # (SRC_IP ^ DST_IP, SRC_IP ^ DST_IP, SRC_PORT ^ DST_PORT, SRC_PORT ^ DST_PORT) + +The result is then fed to the underlying RSS algorithm. + Some advanced NICs allow steering packets to queues based on programmable filters. For example, webserver bound TCP port 80 packets can be directed to their own receive queue. Such “n-tuple†filters can diff --git a/Documentation/networking/smc-sysctl.rst b/Documentation/networking/smc-sysctl.rst index 769149d98773..a874d007f2db 100644 --- a/Documentation/networking/smc-sysctl.rst +++ b/Documentation/networking/smc-sysctl.rst @@ -57,3 +57,17 @@ rmem - INTEGER only allowed 512KiB for SMC-R and 1MiB for SMC-D. Default: 64KiB + +smcr_max_links_per_lgr - INTEGER + Controls the max number of links can be added to a SMC-R link group. Notice that + the actual number of the links added to a SMC-R link group depends on the number + of RDMA devices exist in the system. The acceptable value ranges from 1 to 2. Only + for SMC-R v2.1 and later. + + Default: 2 + +smcr_max_conns_per_lgr - INTEGER + Controls the max number of connections can be added to a SMC-R link group. The + acceptable value ranges from 16 to 255. Only for SMC-R v2.1 and later. + + Default: 255 diff --git a/Documentation/networking/snmp_counter.rst b/Documentation/networking/snmp_counter.rst index 213637474478..ff1e6a8ffe21 100644 --- a/Documentation/networking/snmp_counter.rst +++ b/Documentation/networking/snmp_counter.rst @@ -313,7 +313,7 @@ https://lwn.net/Articles/576263/ * TcpExtTCPOrigDataSent -This counter is explained by `kernel commit f19c29e3e391`_, I pasted the +This counter is explained by kernel commit f19c29e3e391, I pasted the explanation below:: TCPOrigDataSent: number of outgoing packets with original data (excluding @@ -323,7 +323,7 @@ explanation below:: * TCPSynRetrans -This counter is explained by `kernel commit f19c29e3e391`_, I pasted the +This counter is explained by kernel commit f19c29e3e391, I pasted the explanation below:: TCPSynRetrans: number of SYN and SYN/ACK retransmits to break down @@ -331,14 +331,12 @@ explanation below:: * TCPFastOpenActiveFail -This counter is explained by `kernel commit f19c29e3e391`_, I pasted the +This counter is explained by kernel commit f19c29e3e391, I pasted the explanation below:: TCPFastOpenActiveFail: Fast Open attempts (SYN/data) failed because the remote does not accept it or the attempts timed out. -.. _kernel commit f19c29e3e391: https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=f19c29e3e391a66a273e9afebaf01917245148cd - * TcpExtListenOverflows and TcpExtListenDrops When kernel receives a SYN from a client, and if the TCP accept queue @@ -698,11 +696,9 @@ number of the SACK block. For more details, please refer the comment of the function tcp_is_sackblock_valid in the kernel source code. A SACK option could have up to 4 blocks, they are checked individually. E.g., if 3 blocks of a SACk is invalid, the -corresponding counter would be updated 3 times. The comment of the -`Add counters for discarded SACK blocks`_ patch has additional -explanation: - -.. _Add counters for discarded SACK blocks: https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=18f02545a9a16c9a89778b91a162ad16d510bb32 +corresponding counter would be updated 3 times. The comment of commit +18f02545a9a1 ("[TCP] MIB: Add counters for discarded SACK blocks") +has additional explanation: * TcpExtTCPSACKDiscard diff --git a/Documentation/networking/timestamping.rst b/Documentation/networking/timestamping.rst index f17c01834a12..5e93cd71f99f 100644 --- a/Documentation/networking/timestamping.rst +++ b/Documentation/networking/timestamping.rst @@ -357,7 +357,8 @@ enabling SOF_TIMESTAMPING_OPT_ID and comparing the byte offset at send time with the value returned for each timestamp. It can prevent the situation by always flushing the TCP stack in between requests, for instance by enabling TCP_NODELAY and disabling TCP_CORK and -autocork. +autocork. After linux-4.7, a better way to prevent coalescing is +to use MSG_EOR flag at sendmsg() time. These precautions ensure that the timestamp is generated only when all bytes have passed a timestamp point, assuming that the network stack diff --git a/Documentation/networking/xdp-rx-metadata.rst b/Documentation/networking/xdp-rx-metadata.rst index 205696780b78..a6e0ece18be5 100644 --- a/Documentation/networking/xdp-rx-metadata.rst +++ b/Documentation/networking/xdp-rx-metadata.rst @@ -1,3 +1,5 @@ +.. SPDX-License-Identifier: GPL-2.0 + =============== XDP RX Metadata =============== @@ -18,7 +20,13 @@ Currently, the following kfuncs are supported. In the future, as more metadata is supported, this set will grow: .. kernel-doc:: net/core/xdp.c - :identifiers: bpf_xdp_metadata_rx_timestamp bpf_xdp_metadata_rx_hash + :identifiers: bpf_xdp_metadata_rx_timestamp + +.. kernel-doc:: net/core/xdp.c + :identifiers: bpf_xdp_metadata_rx_hash + +.. kernel-doc:: net/core/xdp.c + :identifiers: bpf_xdp_metadata_rx_vlan_tag An XDP program can use these kfuncs to read the metadata into stack variables for its own consumption. Or, to pass the metadata on to other diff --git a/Documentation/networking/xsk-tx-metadata.rst b/Documentation/networking/xsk-tx-metadata.rst new file mode 100644 index 000000000000..bd033fe95cca --- /dev/null +++ b/Documentation/networking/xsk-tx-metadata.rst @@ -0,0 +1,81 @@ +.. SPDX-License-Identifier: GPL-2.0 + +================== +AF_XDP TX Metadata +================== + +This document describes how to enable offloads when transmitting packets +via :doc:`af_xdp`. Refer to :doc:`xdp-rx-metadata` on how to access similar +metadata on the receive side. + +General Design +============== + +The headroom for the metadata is reserved via ``tx_metadata_len`` in +``struct xdp_umem_reg``. The metadata length is therefore the same for +every socket that shares the same umem. The metadata layout is a fixed UAPI, +refer to ``union xsk_tx_metadata`` in ``include/uapi/linux/if_xdp.h``. +Thus, generally, the ``tx_metadata_len`` field above should contain +``sizeof(union xsk_tx_metadata)``. + +The headroom and the metadata itself should be located right before +``xdp_desc->addr`` in the umem frame. Within a frame, the metadata +layout is as follows:: + + tx_metadata_len + / \ + +-----------------+---------+----------------------------+ + | xsk_tx_metadata | padding | payload | + +-----------------+---------+----------------------------+ + ^ + | + xdp_desc->addr + +An AF_XDP application can request headrooms larger than ``sizeof(struct +xsk_tx_metadata)``. The kernel will ignore the padding (and will still +use ``xdp_desc->addr - tx_metadata_len`` to locate +the ``xsk_tx_metadata``). For the frames that shouldn't carry +any metadata (i.e., the ones that don't have ``XDP_TX_METADATA`` option), +the metadata area is ignored by the kernel as well. + +The flags field enables the particular offload: + +- ``XDP_TXMD_FLAGS_TIMESTAMP``: requests the device to put transmission + timestamp into ``tx_timestamp`` field of ``union xsk_tx_metadata``. +- ``XDP_TXMD_FLAGS_CHECKSUM``: requests the device to calculate L4 + checksum. ``csum_start`` specifies byte offset of where the checksumming + should start and ``csum_offset`` specifies byte offset where the + device should store the computed checksum. + +Besides the flags above, in order to trigger the offloads, the first +packet's ``struct xdp_desc`` descriptor should set ``XDP_TX_METADATA`` +bit in the ``options`` field. Also note that in a multi-buffer packet +only the first chunk should carry the metadata. + +Software TX Checksum +==================== + +For development and testing purposes its possible to pass +``XDP_UMEM_TX_SW_CSUM`` flag to ``XDP_UMEM_REG`` UMEM registration call. +In this case, when running in ``XDK_COPY`` mode, the TX checksum +is calculated on the CPU. Do not enable this option in production because +it will negatively affect performance. + +Querying Device Capabilities +============================ + +Every devices exports its offloads capabilities via netlink netdev family. +Refer to ``xsk-flags`` features bitmask in +``Documentation/netlink/specs/netdev.yaml``. + +- ``tx-timestamp``: device supports ``XDP_TXMD_FLAGS_TIMESTAMP`` +- ``tx-checksum``: device supports ``XDP_TXMD_FLAGS_CHECKSUM`` + +See ``tools/net/ynl/samples/netdev.c`` on how to query this information. + +Example +======= + +See ``tools/testing/selftests/bpf/xdp_hw_metadata.c`` for an example +program that handles TX metadata. Also see https://github.com/fomichev/xskgen +for a more bare-bones example. diff --git a/Documentation/power/freezing-of-tasks.rst b/Documentation/power/freezing-of-tasks.rst index 53b6a56c4635..df9755bfbd94 100644 --- a/Documentation/power/freezing-of-tasks.rst +++ b/Documentation/power/freezing-of-tasks.rst @@ -14,27 +14,28 @@ architectures). II. How does it work? ===================== -There are three per-task flags used for that, PF_NOFREEZE, PF_FROZEN -and PF_FREEZER_SKIP (the last one is auxiliary). The tasks that have -PF_NOFREEZE unset (all user space processes and some kernel threads) are -regarded as 'freezable' and treated in a special way before the system enters a -suspend state as well as before a hibernation image is created (in what follows -we only consider hibernation, but the description also applies to suspend). +There is one per-task flag (PF_NOFREEZE) and three per-task states +(TASK_FROZEN, TASK_FREEZABLE and __TASK_FREEZABLE_UNSAFE) used for that. +The tasks that have PF_NOFREEZE unset (all user space tasks and some kernel +threads) are regarded as 'freezable' and treated in a special way before the +system enters a sleep state as well as before a hibernation image is created +(hibernation is directly covered by what follows, but the description applies +to system-wide suspend too). Namely, as the first step of the hibernation procedure the function freeze_processes() (defined in kernel/power/process.c) is called. A system-wide -variable system_freezing_cnt (as opposed to a per-task flag) is used to indicate -whether the system is to undergo a freezing operation. And freeze_processes() -sets this variable. After this, it executes try_to_freeze_tasks() that sends a -fake signal to all user space processes, and wakes up all the kernel threads. -All freezable tasks must react to that by calling try_to_freeze(), which -results in a call to __refrigerator() (defined in kernel/freezer.c), which sets -the task's PF_FROZEN flag, changes its state to TASK_UNINTERRUPTIBLE and makes -it loop until PF_FROZEN is cleared for it. Then, we say that the task is -'frozen' and therefore the set of functions handling this mechanism is referred -to as 'the freezer' (these functions are defined in kernel/power/process.c, -kernel/freezer.c & include/linux/freezer.h). User space processes are generally -frozen before kernel threads. +static key freezer_active (as opposed to a per-task flag or state) is used to +indicate whether the system is to undergo a freezing operation. And +freeze_processes() sets this static key. After this, it executes +try_to_freeze_tasks() that sends a fake signal to all user space processes, and +wakes up all the kernel threads. All freezable tasks must react to that by +calling try_to_freeze(), which results in a call to __refrigerator() (defined +in kernel/freezer.c), which changes the task's state to TASK_FROZEN, and makes +it loop until it is woken by an explicit TASK_FROZEN wakeup. Then, that task +is regarded as 'frozen' and so the set of functions handling this mechanism is +referred to as 'the freezer' (these functions are defined in +kernel/power/process.c, kernel/freezer.c & include/linux/freezer.h). User space +tasks are generally frozen before kernel threads. __refrigerator() must not be called directly. Instead, use the try_to_freeze() function (defined in include/linux/freezer.h), that checks @@ -43,31 +44,40 @@ if the task is to be frozen and makes the task enter __refrigerator(). For user space processes try_to_freeze() is called automatically from the signal-handling code, but the freezable kernel threads need to call it explicitly in suitable places or use the wait_event_freezable() or -wait_event_freezable_timeout() macros (defined in include/linux/freezer.h) -that combine interruptible sleep with checking if the task is to be frozen and -calling try_to_freeze(). The main loop of a freezable kernel thread may look +wait_event_freezable_timeout() macros (defined in include/linux/wait.h) +that put the task to sleep (TASK_INTERRUPTIBLE) or freeze it (TASK_FROZEN) if +freezer_active is set. The main loop of a freezable kernel thread may look like the following one:: set_freezable(); - do { - hub_events(); - wait_event_freezable(khubd_wait, - !list_empty(&hub_event_list) || - kthread_should_stop()); - } while (!kthread_should_stop() || !list_empty(&hub_event_list)); - -(from drivers/usb/core/hub.c::hub_thread()). - -If a freezable kernel thread fails to call try_to_freeze() after the freezer has -initiated a freezing operation, the freezing of tasks will fail and the entire -hibernation operation will be cancelled. For this reason, freezable kernel -threads must call try_to_freeze() somewhere or use one of the + + while (true) { + struct task_struct *tsk = NULL; + + wait_event_freezable(oom_reaper_wait, oom_reaper_list != NULL); + spin_lock_irq(&oom_reaper_lock); + if (oom_reaper_list != NULL) { + tsk = oom_reaper_list; + oom_reaper_list = tsk->oom_reaper_list; + } + spin_unlock_irq(&oom_reaper_lock); + + if (tsk) + oom_reap_task(tsk); + } + +(from mm/oom_kill.c::oom_reaper()). + +If a freezable kernel thread is not put to the frozen state after the freezer +has initiated a freezing operation, the freezing of tasks will fail and the +entire system-wide transition will be cancelled. For this reason, freezable +kernel threads must call try_to_freeze() somewhere or use one of the wait_event_freezable() and wait_event_freezable_timeout() macros. After the system memory state has been restored from a hibernation image and devices have been reinitialized, the function thaw_processes() is called in -order to clear the PF_FROZEN flag for each frozen task. Then, the tasks that -have been frozen leave __refrigerator() and continue running. +order to wake up each frozen task. Then, the tasks that have been frozen leave +__refrigerator() and continue running. Rationale behind the functions dealing with freezing and thawing of tasks @@ -96,7 +106,8 @@ III. Which kernel threads are freezable? Kernel threads are not freezable by default. However, a kernel thread may clear PF_NOFREEZE for itself by calling set_freezable() (the resetting of PF_NOFREEZE directly is not allowed). From this point it is regarded as freezable -and must call try_to_freeze() in a suitable place. +and must call try_to_freeze() or variants of wait_event_freezable() in a +suitable place. IV. Why do we do that? ====================== diff --git a/Documentation/process/changes.rst b/Documentation/process/changes.rst index bb96ca0f774b..50b3d1cb1115 100644 --- a/Documentation/process/changes.rst +++ b/Documentation/process/changes.rst @@ -31,7 +31,7 @@ you probably needn't concern yourself with pcmciautils. ====================== =============== ======================================== GNU C 5.1 gcc --version Clang/LLVM (optional) 11.0.0 clang --version -Rust (optional) 1.73.0 rustc --version +Rust (optional) 1.74.1 rustc --version bindgen (optional) 0.65.1 bindgen --version GNU make 3.82 make --version bash 4.2 bash --version @@ -39,7 +39,7 @@ binutils 2.25 ld -v flex 2.5.35 flex --version bison 2.0 bison --version pahole 1.16 pahole --version -util-linux 2.10o fdformat --version +util-linux 2.10o mount --version kmod 13 depmod -V e2fsprogs 1.41.4 e2fsck -V jfsutils 1.1.3 fsck.jfs -V @@ -58,7 +58,7 @@ mcelog 0.6 mcelog --version iptables 1.4.2 iptables -V openssl & libcrypto 1.0.0 openssl version bc 1.06.95 bc --version -Sphinx\ [#f1]_ 1.7 sphinx-build --version +Sphinx\ [#f1]_ 2.4.4 sphinx-build --version cpio any cpio --version GNU tar 1.28 tar --version gtags (optional) 6.6.5 gtags --version @@ -213,7 +213,7 @@ Util-linux New versions of util-linux provide ``fdisk`` support for larger disks, support new options to mount, recognize more supported partition -types, have a fdformat which works with 2.4 kernels, and similar goodies. +types, and similar goodies. You'll probably want to upgrade. Ksymoops diff --git a/Documentation/process/development-process.rst b/Documentation/process/development-process.rst index 61c627e41ba8..e34d7da58b7f 100644 --- a/Documentation/process/development-process.rst +++ b/Documentation/process/development-process.rst @@ -3,9 +3,17 @@ A guide to the Kernel Development Process ========================================= -Contents: +The purpose of this document is to help developers (and their managers) +work with the development community with a minimum of frustration. It is +an attempt to document how this community works in a way which is +accessible to those who are not intimately familiar with Linux kernel +development (or, indeed, free software development in general). While +there is some technical material here, this is very much a process-oriented +discussion which does not require a deep knowledge of kernel programming to +understand. .. toctree:: + :caption: Contents :numbered: :maxdepth: 2 @@ -17,12 +25,3 @@ Contents: 6.Followthrough 7.AdvancedTopics 8.Conclusion - -The purpose of this document is to help developers (and their managers) -work with the development community with a minimum of frustration. It is -an attempt to document how this community works in a way which is -accessible to those who are not intimately familiar with Linux kernel -development (or, indeed, free software development in general). While -there is some technical material here, this is very much a process-oriented -discussion which does not require a deep knowledge of kernel programming to -understand. diff --git a/Documentation/process/howto.rst b/Documentation/process/howto.rst index deb8235e20ff..6c73889c98fc 100644 --- a/Documentation/process/howto.rst +++ b/Documentation/process/howto.rst @@ -82,8 +82,7 @@ documentation files are also added which explain how to use the feature. When a kernel change causes the interface that the kernel exposes to userspace to change, it is recommended that you send the information or a patch to the manual pages explaining the change to the manual pages -maintainer at mtk.manpages@gmail.com, and CC the list -linux-api@vger.kernel.org. +maintainer at alx@kernel.org, and CC the list linux-api@vger.kernel.org. Here is a list of files that are in the kernel source tree that are required reading: diff --git a/Documentation/process/index.rst b/Documentation/process/index.rst index a1daa309b58d..6cb732dfcc72 100644 --- a/Documentation/process/index.rst +++ b/Documentation/process/index.rst @@ -15,49 +15,96 @@ to learn about how our community works. Reading these documents will make it much easier for you to get your changes merged with a minimum of trouble. -Below are the essential guides that every developer should read. +An introduction to how kernel development works +----------------------------------------------- + +Read these documents first: an understanding of the material here will ease +your entry into the kernel community. .. toctree:: :maxdepth: 1 - license-rules howto - code-of-conduct - code-of-conduct-interpretation development-process submitting-patches - handling-regressions + submit-checklist + +Tools and technical guides for kernel developers +------------------------------------------------ + +This is a collection of material that kernel developers should be familiar +with. + +.. toctree:: + :maxdepth: 1 + + changes programming-language coding-style - maintainer-handbooks maintainer-pgp-guide email-clients + applying-patches + backporting + adding-syscalls + volatile-considered-harmful + botching-up-ioctls + +Policy guides and developer statements +-------------------------------------- + +These are the rules that we try to live by in the kernel community (and +beyond). + +.. toctree:: + :maxdepth: 1 + + license-rules + code-of-conduct + code-of-conduct-interpretation + contribution-maturity-model kernel-enforcement-statement kernel-driver-statement + stable-api-nonsense + stable-kernel-rules + management-style + researcher-guidelines -For security issues, see: +Dealing with bugs +----------------- + +Bugs are a fact of life; it is important that we handle them properly. +The documents below describe our policies around the handling of a couple +of special classes of bugs: regressions and security problems. .. toctree:: :maxdepth: 1 + handling-regressions security-bugs embargoed-hardware-issues -Other guides to the community that are of interest to most developers are: +Maintainer information +---------------------- + +How to find the people who will accept your patches. + +.. toctree:: + :maxdepth: 1 + + maintainer-handbooks + maintainers + +Other material +-------------- + +Here are some other guides to the community that are of interest to most +developers: .. toctree:: :maxdepth: 1 - changes - stable-api-nonsense - management-style - stable-kernel-rules - submit-checklist kernel-docs deprecated - maintainers - researcher-guidelines - contribution-maturity-model These are some overall technical guides that have been put here for now for lack of a better place. @@ -65,12 +112,7 @@ lack of a better place. .. toctree:: :maxdepth: 1 - applying-patches - backporting - adding-syscalls magic-number - volatile-considered-harmful - botching-up-ioctls clang-format ../arch/riscv/patch-acceptance ../core-api/unaligned-memory-access diff --git a/Documentation/process/submitting-patches.rst b/Documentation/process/submitting-patches.rst index 86d346bcb8ef..66029999b587 100644 --- a/Documentation/process/submitting-patches.rst +++ b/Documentation/process/submitting-patches.rst @@ -790,10 +790,14 @@ Providing base tree information ------------------------------- When other developers receive your patches and start the review process, -it is often useful for them to know where in the tree history they -should place your work. This is particularly useful for automated CI -processes that attempt to run a series of tests in order to establish -the quality of your submission before the maintainer starts the review. +it is absolutely necessary for them to know what is the base +commit/branch your work applies on, considering the sheer amount of +maintainer trees present nowadays. Note again the **T:** entry in the +MAINTAINERS file explained above. + +This is even more important for automated CI processes that attempt to +run a series of tests in order to establish the quality of your +submission before the maintainer starts the review. If you are using ``git format-patch`` to generate your patches, you can automatically include the base tree information in your submission by @@ -836,6 +840,9 @@ letter or in the first patch of the series and it should be placed either below the ``---`` line or at the very bottom of all other content, right before your email signature. +Make sure that base commit is in an official maintainer/mainline tree +and not in some internal, accessible only to you tree - otherwise it +would be worthless. References ---------- diff --git a/Documentation/rust/coding-guidelines.rst b/Documentation/rust/coding-guidelines.rst index aa8ed082613e..05542840b16c 100644 --- a/Documentation/rust/coding-guidelines.rst +++ b/Documentation/rust/coding-guidelines.rst @@ -177,6 +177,19 @@ please take a look at the ``rustdoc`` book at: https://doc.rust-lang.org/rustdoc/how-to-write-documentation.html +In addition, the kernel supports creating links relative to the source tree by +prefixing the link destination with ``srctree/``. For instance: + +.. code-block:: rust + + //! C header: [`include/linux/printk.h`](srctree/include/linux/printk.h) + +or: + +.. code-block:: rust + + /// [`struct mutex`]: srctree/include/linux/mutex.h + Naming ------ diff --git a/Documentation/rust/general-information.rst b/Documentation/rust/general-information.rst index 081397827a7e..236c6dd3c647 100644 --- a/Documentation/rust/general-information.rst +++ b/Documentation/rust/general-information.rst @@ -77,3 +77,27 @@ configuration: #[cfg(CONFIG_X="y")] // Enabled as a built-in (`y`) #[cfg(CONFIG_X="m")] // Enabled as a module (`m`) #[cfg(not(CONFIG_X))] // Disabled + + +Testing +------- + +There are the tests that come from the examples in the Rust documentation +and get transformed into KUnit tests. These can be run via KUnit. For example +via ``kunit_tool`` (``kunit.py``) on the command line:: + + ./tools/testing/kunit/kunit.py run --make_options LLVM=1 --arch x86_64 --kconfig_add CONFIG_RUST=y + +Alternatively, KUnit can run them as kernel built-in at boot. Refer to +Documentation/dev-tools/kunit/index.rst for the general KUnit documentation +and Documentation/dev-tools/kunit/architecture.rst for the details of kernel +built-in vs. command line testing. + +Additionally, there are the ``#[test]`` tests. These can be run using +the ``rusttest`` Make target:: + + make LLVM=1 rusttest + +This requires the kernel ``.config`` and downloads external repositories. +It runs the ``#[test]`` tests on the host (currently) and thus is fairly +limited in what these tests can test. diff --git a/Documentation/rust/quick-start.rst b/Documentation/rust/quick-start.rst index f382914f4191..cc3f11e0d441 100644 --- a/Documentation/rust/quick-start.rst +++ b/Documentation/rust/quick-start.rst @@ -33,14 +33,18 @@ A particular version of the Rust compiler is required. Newer versions may or may not work because, for the moment, the kernel depends on some unstable Rust features. -If ``rustup`` is being used, enter the checked out source code directory -and run:: +If ``rustup`` is being used, enter the kernel build directory (or use +``--path=<build-dir>`` argument to the ``set`` sub-command) and run:: rustup override set $(scripts/min-tool-version.sh rustc) This will configure your working directory to use the correct version of -``rustc`` without affecting your default toolchain. If you are not using -``rustup``, fetch a standalone installer from: +``rustc`` without affecting your default toolchain. + +Note that the override applies to the current working directory (and its +sub-directories). + +If you are not using ``rustup``, fetch a standalone installer from: https://forge.rust-lang.org/infra/other-installation-methods.html#standalone @@ -76,7 +80,7 @@ libclang ``libclang`` (part of LLVM) is used by ``bindgen`` to understand the C code in the kernel, which means LLVM needs to be installed; like when the kernel -is compiled with ``CC=clang`` or ``LLVM=1``. +is compiled with ``LLVM=1``. Linux distributions are likely to have a suitable one available, so it is best to check that first. @@ -229,10 +233,6 @@ at the moment. That is:: make LLVM=1 -For architectures that do not support a full LLVM toolchain, use:: - - make CC=clang - Using GCC also works for some configurations, but it is very experimental at the moment. diff --git a/Documentation/scheduler/sched-design-CFS.rst b/Documentation/scheduler/sched-design-CFS.rst index f68919800f05..6cffffe26500 100644 --- a/Documentation/scheduler/sched-design-CFS.rst +++ b/Documentation/scheduler/sched-design-CFS.rst @@ -180,7 +180,7 @@ This is the (partial) list of the hooks: compat_yield sysctl is turned on; in that case, it places the scheduling entity at the right-most end of the red-black tree. - - check_preempt_curr(...) + - wakeup_preempt(...) This function checks if a task that entered the runnable state should preempt the currently running task. @@ -189,10 +189,10 @@ This is the (partial) list of the hooks: This function chooses the most appropriate task eligible to run next. - - set_curr_task(...) + - set_next_task(...) - This function is called when a task changes its scheduling class or changes - its task group. + This function is called when a task changes its scheduling class, changes + its task group or is scheduled. - task_tick(...) diff --git a/Documentation/scheduler/schedutil.rst b/Documentation/scheduler/schedutil.rst index 32c7d69fc86c..803fba8fc714 100644 --- a/Documentation/scheduler/schedutil.rst +++ b/Documentation/scheduler/schedutil.rst @@ -90,8 +90,8 @@ For more detail see: - Documentation/scheduler/sched-capacity.rst:"1. CPU Capacity + 2. Task utilization" -UTIL_EST / UTIL_EST_FASTUP -========================== +UTIL_EST +======== Because periodic tasks have their averages decayed while they sleep, even though when running their expected utilization will be the same, they suffer a @@ -99,8 +99,7 @@ though when running their expected utilization will be the same, they suffer a To alleviate this (a default enabled option) UTIL_EST drives an Infinite Impulse Response (IIR) EWMA with the 'running' value on dequeue -- when it is -highest. A further default enabled option UTIL_EST_FASTUP modifies the IIR -filter to instantly increase and only decay on decrease. +highest. UTIL_EST filters to instantly increase and only decay on decrease. A further runqueue wide sum (of runnable tasks) is maintained of: diff --git a/Documentation/security/keys/trusted-encrypted.rst b/Documentation/security/keys/trusted-encrypted.rst index 9bc9db8ec651..e989b9802f92 100644 --- a/Documentation/security/keys/trusted-encrypted.rst +++ b/Documentation/security/keys/trusted-encrypted.rst @@ -88,7 +88,7 @@ safe. (2) TEE TEEs have well-documented, standardized client interface and APIs. For - more details refer to ``Documentation/staging/tee.rst``. + more details refer to ``Documentation/driver-api/tee.rst``. (3) CAAM diff --git a/Documentation/sphinx-static/custom.css b/Documentation/sphinx-static/custom.css index 084a884f6fb7..f4285417c71a 100644 --- a/Documentation/sphinx-static/custom.css +++ b/Documentation/sphinx-static/custom.css @@ -7,6 +7,10 @@ div.body h1 { font-size: 180%; } div.body h2 { font-size: 150%; } div.body h3 { font-size: 130%; } +div.body h4 { font-size: 110%; } + +/* toctree captions are styled like h2 */ +div.toctree-wrapper p.caption[role=heading] { font-size: 150%; } /* Tighten up the layout slightly */ div.body { padding: 0 15px 0 10px; } @@ -20,6 +24,12 @@ div.document { width: auto; } +/* Size the logo appropriately */ +img.logo { + width: 104px; + margin-bottom: 20px; +} + /* * Parameters for the display of function prototypes and such included * from C source files. @@ -73,3 +83,56 @@ input.kernel-toc-toggle { display: none; } h3.kernel-toc-contents { display: inline; } div.kerneltoc a { color: black; } } + +/* Language selection menu */ + +div.admonition { + /* + * Make sure we don't overlap notes and warnings at the top of the + * document. + */ + clear: both; +} + +div.language-selection { + background: #eeeeee; + border: 1px solid #cccccc; + margin-bottom: 1em; + padding: .5em; + + position: relative; + float: right; +} + +div.language-selection a { + display: block; + padding: 0.5em; + color: #333333; + text-decoration: none; +} + +div.language-selection ul { + display: none; + position: absolute; + + /* Align with the parent div */ + top: 100%; + right: 0; + margin: 0; + + list-style: none; + + background: #fafafa; + border: 1px solid #cccccc; + + /* Never break menu item lines */ + white-space: nowrap; +} + +div.language-selection:hover ul { + display: block; +} + +div.language-selection ul li:hover { + background: #dddddd; +} diff --git a/Documentation/sphinx-static/theme_overrides.css b/Documentation/sphinx-static/theme_overrides.css index f6f2b941a5d6..79000b26e64e 100644 --- a/Documentation/sphinx-static/theme_overrides.css +++ b/Documentation/sphinx-static/theme_overrides.css @@ -81,11 +81,6 @@ div[class^="highlight"] pre { * - hide the permalink symbol as long as link is not hovered */ - .toc-title { - font-size: 150%; - font-weight: bold; - } - caption, .wy-table caption, .rst-content table.field-list caption { font-size: 100%; } diff --git a/Documentation/sphinx/automarkup.py b/Documentation/sphinx/automarkup.py index 06b34740bf90..a413f8dd5115 100644 --- a/Documentation/sphinx/automarkup.py +++ b/Documentation/sphinx/automarkup.py @@ -7,11 +7,7 @@ from docutils import nodes import sphinx from sphinx import addnodes -if sphinx.version_info[0] < 2 or \ - sphinx.version_info[0] == 2 and sphinx.version_info[1] < 1: - from sphinx.environment import NoUri -else: - from sphinx.errors import NoUri +from sphinx.errors import NoUri import re from itertools import chain @@ -74,6 +70,12 @@ Skipfuncs = [ 'open', 'close', 'read', 'write', 'fcntl', 'mmap', c_namespace = '' +# +# Detect references to commits. +# +RE_git = re.compile(r'commit\s+(?P<rev>[0-9a-f]{12,40})(?:\s+\(".*?"\))?', + flags=re.IGNORECASE | re.DOTALL) + def markup_refs(docname, app, node): t = node.astext() done = 0 @@ -90,7 +92,8 @@ def markup_refs(docname, app, node): RE_struct: markup_c_ref, RE_union: markup_c_ref, RE_enum: markup_c_ref, - RE_typedef: markup_c_ref} + RE_typedef: markup_c_ref, + RE_git: markup_git} if sphinx.version_info[0] >= 3: markup_func = markup_func_sphinx3 @@ -276,6 +279,17 @@ def get_c_namespace(app, docname): return match.group(1) return '' +def markup_git(docname, app, match): + # While we could probably assume that we are running in a git + # repository, we can't know for sure, so let's just mechanically + # turn them into git.kernel.org links without checking their + # validity. (Maybe we can do something in the future to warn about + # these references if this is explicitly requested.) + text = match.group(0) + rev = match.group('rev') + return nodes.reference('', nodes.Text(text), + refuri=f'https://git.kernel.org/torvalds/c/{rev}') + def auto_markup(app, doctree, name): global c_namespace c_namespace = get_c_namespace(app, name) diff --git a/Documentation/sphinx/cdomain.py b/Documentation/sphinx/cdomain.py index 4eb150bf509c..e6959af25402 100644 --- a/Documentation/sphinx/cdomain.py +++ b/Documentation/sphinx/cdomain.py @@ -127,11 +127,7 @@ def setup(app): # Handle easy Sphinx 3.1+ simple new tags: :c:expr and .. c:namespace:: app.connect('source-read', c_markups) - - if (major == 1 and minor < 8): - app.override_domain(CDomain) - else: - app.add_domain(CDomain, override=True) + app.add_domain(CDomain, override=True) return dict( version = __version__, diff --git a/Documentation/sphinx/kernel_abi.py b/Documentation/sphinx/kernel_abi.py index 49797c55479c..5911bd0d7965 100644 --- a/Documentation/sphinx/kernel_abi.py +++ b/Documentation/sphinx/kernel_abi.py @@ -39,8 +39,6 @@ import sys import re import kernellog -from os import path - from docutils import nodes, statemachine from docutils.statemachine import ViewList from docutils.parsers.rst import directives, Directive @@ -73,60 +71,26 @@ class KernelCmd(Directive): } def run(self): - doc = self.state.document if not doc.settings.file_insertion_enabled: raise self.warning("docutils: file insertion disabled") - env = doc.settings.env - cwd = path.dirname(doc.current_source) - cmd = "get_abi.pl rest --enable-lineno --dir " - cmd += self.arguments[0] - - if 'rst' in self.options: - cmd += " --rst-source" + srctree = os.path.abspath(os.environ["srctree"]) - srctree = path.abspath(os.environ["srctree"]) + args = [ + os.path.join(srctree, 'scripts/get_abi.pl'), + 'rest', + '--enable-lineno', + '--dir', os.path.join(srctree, 'Documentation', self.arguments[0]), + ] - fname = cmd - - # extend PATH with $(srctree)/scripts - path_env = os.pathsep.join([ - srctree + os.sep + "scripts", - os.environ["PATH"] - ]) - shell_env = os.environ.copy() - shell_env["PATH"] = path_env - shell_env["srctree"] = srctree + if 'rst' in self.options: + args.append('--rst-source') - lines = self.runCmd(cmd, shell=True, cwd=cwd, env=shell_env) + lines = subprocess.check_output(args, cwd=os.path.dirname(doc.current_source)).decode('utf-8') nodeList = self.nestedParse(lines, self.arguments[0]) return nodeList - def runCmd(self, cmd, **kwargs): - u"""Run command ``cmd`` and return its stdout as unicode.""" - - try: - proc = subprocess.Popen( - cmd - , stdout = subprocess.PIPE - , stderr = subprocess.PIPE - , **kwargs - ) - out, err = proc.communicate() - - out, err = codecs.decode(out, 'utf-8'), codecs.decode(err, 'utf-8') - - if proc.returncode != 0: - raise self.severe( - u"command '%s' failed with return code %d" - % (cmd, proc.returncode) - ) - except OSError as exc: - raise self.severe(u"problems with '%s' directive: %s." - % (self.name, ErrorString(exc))) - return out - def nestedParse(self, lines, fname): env = self.state.document.settings.env content = ViewList() diff --git a/Documentation/sphinx/kfigure.py b/Documentation/sphinx/kfigure.py index 13e885bbd499..97166333b727 100644 --- a/Documentation/sphinx/kfigure.py +++ b/Documentation/sphinx/kfigure.py @@ -61,13 +61,7 @@ import sphinx from sphinx.util.nodes import clean_astext import kernellog -# Get Sphinx version -major, minor, patch = sphinx.version_info[:3] -if major == 1 and minor > 3: - # patches.Figure only landed in Sphinx 1.4 - from sphinx.directives.patches import Figure # pylint: disable=C0413 -else: - Figure = images.Figure +Figure = images.Figure __version__ = '1.0.0' diff --git a/Documentation/sphinx/requirements.txt b/Documentation/sphinx/requirements.txt index 335b53df35e2..a8a1aff6445e 100644 --- a/Documentation/sphinx/requirements.txt +++ b/Documentation/sphinx/requirements.txt @@ -1,3 +1,4 @@ # jinja2>=3.1 is not compatible with Sphinx<4.0 jinja2<3.1 Sphinx==2.4.4 +pyyaml diff --git a/Documentation/sphinx/templates/translations.html b/Documentation/sphinx/templates/translations.html new file mode 100644 index 000000000000..8df5d42d8dcd --- /dev/null +++ b/Documentation/sphinx/templates/translations.html @@ -0,0 +1,15 @@ +<!-- SPDX-License-Identifier: GPL-2.0 --> +<!-- Copyright © 2023, Oracle and/or its affiliates. --> + +{# Create a language menu for translations #} +{% if languages|length > 0: %} +<div class="language-selection"> +{{ current_language }} + +<ul> +{% for ref in languages: %} +<li><a href="{{ ref.refuri }}">{{ ref.astext() }}</a></li> +{% endfor %} +</ul> +</div> +{% endif %} diff --git a/Documentation/sphinx/translations.py b/Documentation/sphinx/translations.py new file mode 100644 index 000000000000..47161e6eba99 --- /dev/null +++ b/Documentation/sphinx/translations.py @@ -0,0 +1,101 @@ +# SPDX-License-Identifier: GPL-2.0 +# +# Copyright © 2023, Oracle and/or its affiliates. +# Author: Vegard Nossum <vegard.nossum@oracle.com> +# +# Add translation links to the top of the document. +# + +import os + +from docutils import nodes +from docutils.transforms import Transform + +import sphinx +from sphinx import addnodes +from sphinx.errors import NoUri + +all_languages = { + # English is always first + None: 'English', + + # Keep the rest sorted alphabetically + 'zh_CN': 'Chinese (Simplified)', + 'zh_TW': 'Chinese (Traditional)', + 'it_IT': 'Italian', + 'ja_JP': 'Japanese', + 'ko_KR': 'Korean', + 'sp_SP': 'Spanish', +} + +class LanguagesNode(nodes.Element): + def __init__(self, current_language, *args, **kwargs): + super().__init__(*args, **kwargs) + + self.current_language = current_language + +class TranslationsTransform(Transform): + default_priority = 900 + + def apply(self): + app = self.document.settings.env.app + docname = self.document.settings.env.docname + + this_lang_code = None + components = docname.split(os.sep) + if components[0] == 'translations' and len(components) > 2: + this_lang_code = components[1] + + # normalize docname to be the untranslated one + docname = os.path.join(*components[2:]) + + new_nodes = LanguagesNode(all_languages[this_lang_code]) + + for lang_code, lang_name in all_languages.items(): + if lang_code == this_lang_code: + continue + + if lang_code is None: + target_name = docname + else: + target_name = os.path.join('translations', lang_code, docname) + + pxref = addnodes.pending_xref('', refdomain='std', + reftype='doc', reftarget='/' + target_name, modname=None, + classname=None, refexplicit=True) + pxref += nodes.Text(lang_name) + new_nodes += pxref + + self.document.insert(0, new_nodes) + +def process_languages(app, doctree, docname): + for node in doctree.traverse(LanguagesNode): + if app.builder.format not in ['html']: + node.parent.remove(node) + continue + + languages = [] + + # Iterate over the child nodes; any resolved links will have + # the type 'nodes.reference', while unresolved links will be + # type 'nodes.Text'. + languages = list(filter(lambda xref: + isinstance(xref, nodes.reference), node.children)) + + html_content = app.builder.templates.render('translations.html', + context={ + 'current_language': node.current_language, + 'languages': languages, + }) + + node.replace_self(nodes.raw('', html_content, format='html')) + +def setup(app): + app.add_node(LanguagesNode) + app.add_transform(TranslationsTransform) + app.connect('doctree-resolved', process_languages) + + return { + 'parallel_read_safe': True, + 'parallel_write_safe': True, + } diff --git a/Documentation/spi/pxa2xx.rst b/Documentation/spi/pxa2xx.rst index 04f2a3856c40..19479b801826 100644 --- a/Documentation/spi/pxa2xx.rst +++ b/Documentation/spi/pxa2xx.rst @@ -3,13 +3,13 @@ PXA2xx SPI on SSP driver HOWTO ============================== This a mini HOWTO on the pxa2xx_spi driver. The driver turns a PXA2xx -synchronous serial port into an SPI master controller +synchronous serial port into an SPI host controller (see Documentation/spi/spi-summary.rst). The driver has the following features - Support for any PXA2xx and compatible SSP. - SSP PIO and SSP DMA data transfers. - External and Internal (SSPFRM) chip selects. -- Per slave device (chip) configuration. +- Per peripheral device (chip) configuration. - Full suspend, freeze, resume support. The driver is built around a &struct spi_message FIFO serviced by kernel @@ -17,10 +17,10 @@ thread. The kernel thread, spi_pump_messages(), drives message FIFO and is responsible for queuing SPI transactions and setting up and launching the DMA or interrupt driven transfers. -Declaring PXA2xx Master Controllers ------------------------------------ -Typically, for a legacy platform, an SPI master is defined in the -arch/.../mach-*/board-*.c as a "platform device". The master configuration +Declaring PXA2xx host controllers +--------------------------------- +Typically, for a legacy platform, an SPI host controller is defined in the +arch/.../mach-*/board-*.c as a "platform device". The host controller configuration is passed to the driver via a table found in include/linux/spi/pxa2xx_spi.h:: struct pxa2xx_spi_controller { @@ -30,7 +30,7 @@ is passed to the driver via a table found in include/linux/spi/pxa2xx_spi.h:: }; The "pxa2xx_spi_controller.num_chipselect" field is used to determine the number of -slave device (chips) attached to this SPI master. +peripheral devices (chips) attached to this SPI host controller. The "pxa2xx_spi_controller.enable_dma" field informs the driver that SSP DMA should be used. This caused the driver to acquire two DMA channels: Rx channel and @@ -40,8 +40,8 @@ See the "PXA2xx Developer Manual" section "DMA Controller". For the new platforms the description of the controller and peripheral devices comes from Device Tree or ACPI. -NSSP MASTER SAMPLE ------------------- +NSSP HOST SAMPLE +---------------- Below is a sample configuration using the PXA255 NSSP for a legacy platform:: static struct resource pxa_spi_nssp_resources[] = { @@ -57,7 +57,7 @@ Below is a sample configuration using the PXA255 NSSP for a legacy platform:: }, }; - static struct pxa2xx_spi_controller pxa_nssp_master_info = { + static struct pxa2xx_spi_controller pxa_nssp_controller_info = { .num_chipselect = 1, /* Matches the number of chips attached to NSSP */ .enable_dma = 1, /* Enables NSSP DMA */ }; @@ -68,7 +68,7 @@ Below is a sample configuration using the PXA255 NSSP for a legacy platform:: .resource = pxa_spi_nssp_resources, .num_resources = ARRAY_SIZE(pxa_spi_nssp_resources), .dev = { - .platform_data = &pxa_nssp_master_info, /* Passed to driver */ + .platform_data = &pxa_nssp_controller_info, /* Passed to driver */ }, }; @@ -81,17 +81,17 @@ Below is a sample configuration using the PXA255 NSSP for a legacy platform:: (void)platform_add_device(devices, ARRAY_SIZE(devices)); } -Declaring Slave Devices ------------------------ -Typically, for a legacy platform, each SPI slave (chip) is defined in the +Declaring peripheral devices +---------------------------- +Typically, for a legacy platform, each SPI peripheral device (chip) is defined in the arch/.../mach-*/board-*.c using the "spi_board_info" structure found in "linux/spi/spi.h". See "Documentation/spi/spi-summary.rst" for additional information. -Each slave device attached to the PXA must provide slave specific configuration +Each peripheral device (chip) attached to the PXA2xx must provide specific chip configuration information via the structure "pxa2xx_spi_chip" found in -"include/linux/spi/pxa2xx_spi.h". The pxa2xx_spi master controller driver -will uses the configuration whenever the driver communicates with the slave +"include/linux/spi/pxa2xx_spi.h". The PXA2xx host controller driver will use +the configuration whenever the driver communicates with the peripheral device. All fields are optional. :: @@ -123,7 +123,7 @@ dma_burst_size == 0. The "pxa2xx_spi_chip.timeout" fields is used to efficiently handle trailing bytes in the SSP receiver FIFO. The correct value for this field is dependent on the SPI bus speed ("spi_board_info.max_speed_hz") and the specific -slave device. Please note that the PXA2xx SSP 1 does not support trailing byte +peripheral device. Please note that the PXA2xx SSP 1 does not support trailing byte timeouts and must busy-wait any trailing bytes. NOTE: the SPI driver cannot control the chip select if SSPFRM is used, so the @@ -132,8 +132,8 @@ asserted around the complete message. Use SSPFRM as a GPIO (through a descriptor to accommodate these chips. -NSSP SLAVE SAMPLE ------------------ +NSSP PERIPHERAL SAMPLE +---------------------- For a legacy platform or in some other cases, the pxa2xx_spi_chip structure is passed to the pxa2xx_spi driver in the "spi_board_info.controller_data" field. Below is a sample configuration using the PXA255 NSSP. @@ -161,16 +161,16 @@ field. Below is a sample configuration using the PXA255 NSSP. .bus_num = 2, /* Framework bus number */ .chip_select = 0, /* Framework chip select */ .platform_data = NULL; /* No spi_driver specific config */ - .controller_data = &cs8415a_chip_info, /* Master chip config */ - .irq = STREETRACER_APCI_IRQ, /* Slave device interrupt */ + .controller_data = &cs8415a_chip_info, /* Host controller config */ + .irq = STREETRACER_APCI_IRQ, /* Peripheral device interrupt */ }, { .modalias = "cs8405a", /* Name of spi_driver for this device */ .max_speed_hz = 3686400, /* Run SSP as fast a possible */ .bus_num = 2, /* Framework bus number */ .chip_select = 1, /* Framework chip select */ - .controller_data = &cs8405a_chip_info, /* Master chip config */ - .irq = STREETRACER_APCI_IRQ, /* Slave device interrupt */ + .controller_data = &cs8405a_chip_info, /* Host controller config */ + .irq = STREETRACER_APCI_IRQ, /* Peripheral device interrupt */ }, }; @@ -193,17 +193,14 @@ mode supports both coherent and stream based DMA mappings. The following logic is used to determine the type of I/O to be used on a per "spi_transfer" basis:: - if !enable_dma then - always use PIO transfers + if spi_message.len > 65536 then + if spi_message.is_dma_mapped or rx_dma_buf != 0 or tx_dma_buf != 0 then + reject premapped transfers - if spi_message.len > 8191 then print "rate limited" warning use PIO transfers - if spi_message.is_dma_mapped and rx_dma_buf != 0 and tx_dma_buf != 0 then - use coherent DMA mode - - if rx_buf and tx_buf are aligned on 8 byte boundary then + if enable_dma and the size is in the range [DMA burst size..65536] then use streaming DMA mode otherwise diff --git a/Documentation/staging/index.rst b/Documentation/staging/index.rst index ded8254bc0d7..71592f3ce89b 100644 --- a/Documentation/staging/index.rst +++ b/Documentation/staging/index.rst @@ -12,5 +12,4 @@ Unsorted Documentation rpmsg speculation static-keys - tee xz diff --git a/Documentation/staging/tee.rst b/Documentation/staging/tee.rst deleted file mode 100644 index 22baa077a3b9..000000000000 --- a/Documentation/staging/tee.rst +++ /dev/null @@ -1,364 +0,0 @@ -============= -TEE subsystem -============= - -This document describes the TEE subsystem in Linux. - -A TEE (Trusted Execution Environment) is a trusted OS running in some -secure environment, for example, TrustZone on ARM CPUs, or a separate -secure co-processor etc. A TEE driver handles the details needed to -communicate with the TEE. - -This subsystem deals with: - -- Registration of TEE drivers - -- Managing shared memory between Linux and the TEE - -- Providing a generic API to the TEE - -The TEE interface -================= - -include/uapi/linux/tee.h defines the generic interface to a TEE. - -User space (the client) connects to the driver by opening /dev/tee[0-9]* or -/dev/teepriv[0-9]*. - -- TEE_IOC_SHM_ALLOC allocates shared memory and returns a file descriptor - which user space can mmap. When user space doesn't need the file - descriptor any more, it should be closed. When shared memory isn't needed - any longer it should be unmapped with munmap() to allow the reuse of - memory. - -- TEE_IOC_VERSION lets user space know which TEE this driver handles and - its capabilities. - -- TEE_IOC_OPEN_SESSION opens a new session to a Trusted Application. - -- TEE_IOC_INVOKE invokes a function in a Trusted Application. - -- TEE_IOC_CANCEL may cancel an ongoing TEE_IOC_OPEN_SESSION or TEE_IOC_INVOKE. - -- TEE_IOC_CLOSE_SESSION closes a session to a Trusted Application. - -There are two classes of clients, normal clients and supplicants. The latter is -a helper process for the TEE to access resources in Linux, for example file -system access. A normal client opens /dev/tee[0-9]* and a supplicant opens -/dev/teepriv[0-9]. - -Much of the communication between clients and the TEE is opaque to the -driver. The main job for the driver is to receive requests from the -clients, forward them to the TEE and send back the results. In the case of -supplicants the communication goes in the other direction, the TEE sends -requests to the supplicant which then sends back the result. - -The TEE kernel interface -======================== - -Kernel provides a TEE bus infrastructure where a Trusted Application is -represented as a device identified via Universally Unique Identifier (UUID) and -client drivers register a table of supported device UUIDs. - -TEE bus infrastructure registers following APIs: - -match(): - iterates over the client driver UUID table to find a corresponding - match for device UUID. If a match is found, then this particular device is - probed via corresponding probe API registered by the client driver. This - process happens whenever a device or a client driver is registered with TEE - bus. - -uevent(): - notifies user-space (udev) whenever a new device is registered on - TEE bus for auto-loading of modularized client drivers. - -TEE bus device enumeration is specific to underlying TEE implementation, so it -is left open for TEE drivers to provide corresponding implementation. - -Then TEE client driver can talk to a matched Trusted Application using APIs -listed in include/linux/tee_drv.h. - -TEE client driver example -------------------------- - -Suppose a TEE client driver needs to communicate with a Trusted Application -having UUID: ``ac6a4085-0e82-4c33-bf98-8eb8e118b6c2``, so driver registration -snippet would look like:: - - static const struct tee_client_device_id client_id_table[] = { - {UUID_INIT(0xac6a4085, 0x0e82, 0x4c33, - 0xbf, 0x98, 0x8e, 0xb8, 0xe1, 0x18, 0xb6, 0xc2)}, - {} - }; - - MODULE_DEVICE_TABLE(tee, client_id_table); - - static struct tee_client_driver client_driver = { - .id_table = client_id_table, - .driver = { - .name = DRIVER_NAME, - .bus = &tee_bus_type, - .probe = client_probe, - .remove = client_remove, - }, - }; - - static int __init client_init(void) - { - return driver_register(&client_driver.driver); - } - - static void __exit client_exit(void) - { - driver_unregister(&client_driver.driver); - } - - module_init(client_init); - module_exit(client_exit); - -OP-TEE driver -============= - -The OP-TEE driver handles OP-TEE [1] based TEEs. Currently it is only the ARM -TrustZone based OP-TEE solution that is supported. - -Lowest level of communication with OP-TEE builds on ARM SMC Calling -Convention (SMCCC) [2], which is the foundation for OP-TEE's SMC interface -[3] used internally by the driver. Stacked on top of that is OP-TEE Message -Protocol [4]. - -OP-TEE SMC interface provides the basic functions required by SMCCC and some -additional functions specific for OP-TEE. The most interesting functions are: - -- OPTEE_SMC_FUNCID_CALLS_UID (part of SMCCC) returns the version information - which is then returned by TEE_IOC_VERSION - -- OPTEE_SMC_CALL_GET_OS_UUID returns the particular OP-TEE implementation, used - to tell, for instance, a TrustZone OP-TEE apart from an OP-TEE running on a - separate secure co-processor. - -- OPTEE_SMC_CALL_WITH_ARG drives the OP-TEE message protocol - -- OPTEE_SMC_GET_SHM_CONFIG lets the driver and OP-TEE agree on which memory - range to used for shared memory between Linux and OP-TEE. - -The GlobalPlatform TEE Client API [5] is implemented on top of the generic -TEE API. - -Picture of the relationship between the different components in the -OP-TEE architecture:: - - User space Kernel Secure world - ~~~~~~~~~~ ~~~~~~ ~~~~~~~~~~~~ - +--------+ +-------------+ - | Client | | Trusted | - +--------+ | Application | - /\ +-------------+ - || +----------+ /\ - || |tee- | || - || |supplicant| \/ - || +----------+ +-------------+ - \/ /\ | TEE Internal| - +-------+ || | API | - + TEE | || +--------+--------+ +-------------+ - | Client| || | TEE | OP-TEE | | OP-TEE | - | API | \/ | subsys | driver | | Trusted OS | - +-------+----------------+----+-------+----+-----------+-------------+ - | Generic TEE API | | OP-TEE MSG | - | IOCTL (TEE_IOC_*) | | SMCCC (OPTEE_SMC_CALL_*) | - +-----------------------------+ +------------------------------+ - -RPC (Remote Procedure Call) are requests from secure world to kernel driver -or tee-supplicant. An RPC is identified by a special range of SMCCC return -values from OPTEE_SMC_CALL_WITH_ARG. RPC messages which are intended for the -kernel are handled by the kernel driver. Other RPC messages will be forwarded to -tee-supplicant without further involvement of the driver, except switching -shared memory buffer representation. - -OP-TEE device enumeration -------------------------- - -OP-TEE provides a pseudo Trusted Application: drivers/tee/optee/device.c in -order to support device enumeration. In other words, OP-TEE driver invokes this -application to retrieve a list of Trusted Applications which can be registered -as devices on the TEE bus. - -OP-TEE notifications --------------------- - -There are two kinds of notifications that secure world can use to make -normal world aware of some event. - -1. Synchronous notifications delivered with ``OPTEE_RPC_CMD_NOTIFICATION`` - using the ``OPTEE_RPC_NOTIFICATION_SEND`` parameter. -2. Asynchronous notifications delivered with a combination of a non-secure - edge-triggered interrupt and a fast call from the non-secure interrupt - handler. - -Synchronous notifications are limited by depending on RPC for delivery, -this is only usable when secure world is entered with a yielding call via -``OPTEE_SMC_CALL_WITH_ARG``. This excludes such notifications from secure -world interrupt handlers. - -An asynchronous notification is delivered via a non-secure edge-triggered -interrupt to an interrupt handler registered in the OP-TEE driver. The -actual notification value are retrieved with the fast call -``OPTEE_SMC_GET_ASYNC_NOTIF_VALUE``. Note that one interrupt can represent -multiple notifications. - -One notification value ``OPTEE_SMC_ASYNC_NOTIF_VALUE_DO_BOTTOM_HALF`` has a -special meaning. When this value is received it means that normal world is -supposed to make a yielding call ``OPTEE_MSG_CMD_DO_BOTTOM_HALF``. This -call is done from the thread assisting the interrupt handler. This is a -building block for OP-TEE OS in secure world to implement the top half and -bottom half style of device drivers. - -OPTEE_INSECURE_LOAD_IMAGE Kconfig option ----------------------------------------- - -The OPTEE_INSECURE_LOAD_IMAGE Kconfig option enables the ability to load the -BL32 OP-TEE image from the kernel after the kernel boots, rather than loading -it from the firmware before the kernel boots. This also requires enabling the -corresponding option in Trusted Firmware for Arm. The Trusted Firmware for Arm -documentation [8] explains the security threat associated with enabling this as -well as mitigations at the firmware and platform level. - -There are additional attack vectors/mitigations for the kernel that should be -addressed when using this option. - -1. Boot chain security. - - * Attack vector: Replace the OP-TEE OS image in the rootfs to gain control of - the system. - - * Mitigation: There must be boot chain security that verifies the kernel and - rootfs, otherwise an attacker can modify the loaded OP-TEE binary by - modifying it in the rootfs. - -2. Alternate boot modes. - - * Attack vector: Using an alternate boot mode (i.e. recovery mode), the - OP-TEE driver isn't loaded, leaving the SMC hole open. - - * Mitigation: If there are alternate methods of booting the device, such as a - recovery mode, it should be ensured that the same mitigations are applied - in that mode. - -3. Attacks prior to SMC invocation. - - * Attack vector: Code that is executed prior to issuing the SMC call to load - OP-TEE can be exploited to then load an alternate OS image. - - * Mitigation: The OP-TEE driver must be loaded before any potential attack - vectors are opened up. This should include mounting of any modifiable - filesystems, opening of network ports or communicating with external - devices (e.g. USB). - -4. Blocking SMC call to load OP-TEE. - - * Attack vector: Prevent the driver from being probed, so the SMC call to - load OP-TEE isn't executed when desired, leaving it open to being executed - later and loading a modified OS. - - * Mitigation: It is recommended to build the OP-TEE driver as builtin driver - rather than as a module to prevent exploits that may cause the module to - not be loaded. - -AMD-TEE driver -============== - -The AMD-TEE driver handles the communication with AMD's TEE environment. The -TEE environment is provided by AMD Secure Processor. - -The AMD Secure Processor (formerly called Platform Security Processor or PSP) -is a dedicated processor that features ARM TrustZone technology, along with a -software-based Trusted Execution Environment (TEE) designed to enable -third-party Trusted Applications. This feature is currently enabled only for -APUs. - -The following picture shows a high level overview of AMD-TEE:: - - | - x86 | - | - User space (Kernel space) | AMD Secure Processor (PSP) - ~~~~~~~~~~ ~~~~~~~~~~~~~~ | ~~~~~~~~~~~~~~~~~~~~~~~~~~ - | - +--------+ | +-------------+ - | Client | | | Trusted | - +--------+ | | Application | - /\ | +-------------+ - || | /\ - || | || - || | \/ - || | +----------+ - || | | TEE | - || | | Internal | - \/ | | API | - +---------+ +-----------+---------+ +----------+ - | TEE | | TEE | AMD-TEE | | AMD-TEE | - | Client | | subsystem | driver | | Trusted | - | API | | | | | OS | - +---------+-----------+----+------+---------+---------+----------+ - | Generic TEE API | | ASP | Mailbox | - | IOCTL (TEE_IOC_*) | | driver | Register Protocol | - +--------------------------+ +---------+--------------------+ - -At the lowest level (in x86), the AMD Secure Processor (ASP) driver uses the -CPU to PSP mailbox register to submit commands to the PSP. The format of the -command buffer is opaque to the ASP driver. It's role is to submit commands to -the secure processor and return results to AMD-TEE driver. The interface -between AMD-TEE driver and AMD Secure Processor driver can be found in [6]. - -The AMD-TEE driver packages the command buffer payload for processing in TEE. -The command buffer format for the different TEE commands can be found in [7]. - -The TEE commands supported by AMD-TEE Trusted OS are: - -* TEE_CMD_ID_LOAD_TA - loads a Trusted Application (TA) binary into - TEE environment. -* TEE_CMD_ID_UNLOAD_TA - unloads TA binary from TEE environment. -* TEE_CMD_ID_OPEN_SESSION - opens a session with a loaded TA. -* TEE_CMD_ID_CLOSE_SESSION - closes session with loaded TA -* TEE_CMD_ID_INVOKE_CMD - invokes a command with loaded TA -* TEE_CMD_ID_MAP_SHARED_MEM - maps shared memory -* TEE_CMD_ID_UNMAP_SHARED_MEM - unmaps shared memory - -AMD-TEE Trusted OS is the firmware running on AMD Secure Processor. - -The AMD-TEE driver registers itself with TEE subsystem and implements the -following driver function callbacks: - -* get_version - returns the driver implementation id and capability. -* open - sets up the driver context data structure. -* release - frees up driver resources. -* open_session - loads the TA binary and opens session with loaded TA. -* close_session - closes session with loaded TA and unloads it. -* invoke_func - invokes a command with loaded TA. - -cancel_req driver callback is not supported by AMD-TEE. - -The GlobalPlatform TEE Client API [5] can be used by the user space (client) to -talk to AMD's TEE. AMD's TEE provides a secure environment for loading, opening -a session, invoking commands and closing session with TA. - -References -========== - -[1] https://github.com/OP-TEE/optee_os - -[2] http://infocenter.arm.com/help/topic/com.arm.doc.den0028a/index.html - -[3] drivers/tee/optee/optee_smc.h - -[4] drivers/tee/optee/optee_msg.h - -[5] http://www.globalplatform.org/specificationsdevice.asp look for - "TEE Client API Specification v1.0" and click download. - -[6] include/linux/psp-tee.h - -[7] drivers/tee/amdtee/amdtee_if.h - -[8] https://trustedfirmware-a.readthedocs.io/en/latest/threat_model/threat_model.html diff --git a/Documentation/subsystem-apis.rst b/Documentation/subsystem-apis.rst index 930dc23998a0..2d353fb8ea26 100644 --- a/Documentation/subsystem-apis.rst +++ b/Documentation/subsystem-apis.rst @@ -86,3 +86,4 @@ Storage interfaces misc-devices/index peci/index wmi/index + tee/index diff --git a/Documentation/tee/amd-tee.rst b/Documentation/tee/amd-tee.rst new file mode 100644 index 000000000000..51500fde7038 --- /dev/null +++ b/Documentation/tee/amd-tee.rst @@ -0,0 +1,90 @@ +.. SPDX-License-Identifier: GPL-2.0 + +============================================= +AMD-TEE (AMD's Trusted Execution Environment) +============================================= + +The AMD-TEE driver handles the communication with AMD's TEE environment. The +TEE environment is provided by AMD Secure Processor. + +The AMD Secure Processor (formerly called Platform Security Processor or PSP) +is a dedicated processor that features ARM TrustZone technology, along with a +software-based Trusted Execution Environment (TEE) designed to enable +third-party Trusted Applications. This feature is currently enabled only for +APUs. + +The following picture shows a high level overview of AMD-TEE:: + + | + x86 | + | + User space (Kernel space) | AMD Secure Processor (PSP) + ~~~~~~~~~~ ~~~~~~~~~~~~~~ | ~~~~~~~~~~~~~~~~~~~~~~~~~~ + | + +--------+ | +-------------+ + | Client | | | Trusted | + +--------+ | | Application | + /\ | +-------------+ + || | /\ + || | || + || | \/ + || | +----------+ + || | | TEE | + || | | Internal | + \/ | | API | + +---------+ +-----------+---------+ +----------+ + | TEE | | TEE | AMD-TEE | | AMD-TEE | + | Client | | subsystem | driver | | Trusted | + | API | | | | | OS | + +---------+-----------+----+------+---------+---------+----------+ + | Generic TEE API | | ASP | Mailbox | + | IOCTL (TEE_IOC_*) | | driver | Register Protocol | + +--------------------------+ +---------+--------------------+ + +At the lowest level (in x86), the AMD Secure Processor (ASP) driver uses the +CPU to PSP mailbox register to submit commands to the PSP. The format of the +command buffer is opaque to the ASP driver. It's role is to submit commands to +the secure processor and return results to AMD-TEE driver. The interface +between AMD-TEE driver and AMD Secure Processor driver can be found in [1]. + +The AMD-TEE driver packages the command buffer payload for processing in TEE. +The command buffer format for the different TEE commands can be found in [2]. + +The TEE commands supported by AMD-TEE Trusted OS are: + +* TEE_CMD_ID_LOAD_TA - loads a Trusted Application (TA) binary into + TEE environment. +* TEE_CMD_ID_UNLOAD_TA - unloads TA binary from TEE environment. +* TEE_CMD_ID_OPEN_SESSION - opens a session with a loaded TA. +* TEE_CMD_ID_CLOSE_SESSION - closes session with loaded TA +* TEE_CMD_ID_INVOKE_CMD - invokes a command with loaded TA +* TEE_CMD_ID_MAP_SHARED_MEM - maps shared memory +* TEE_CMD_ID_UNMAP_SHARED_MEM - unmaps shared memory + +AMD-TEE Trusted OS is the firmware running on AMD Secure Processor. + +The AMD-TEE driver registers itself with TEE subsystem and implements the +following driver function callbacks: + +* get_version - returns the driver implementation id and capability. +* open - sets up the driver context data structure. +* release - frees up driver resources. +* open_session - loads the TA binary and opens session with loaded TA. +* close_session - closes session with loaded TA and unloads it. +* invoke_func - invokes a command with loaded TA. + +cancel_req driver callback is not supported by AMD-TEE. + +The GlobalPlatform TEE Client API [3] can be used by the user space (client) to +talk to AMD's TEE. AMD's TEE provides a secure environment for loading, opening +a session, invoking commands and closing session with TA. + +References +========== + +[1] include/linux/psp-tee.h + +[2] drivers/tee/amdtee/amdtee_if.h + +[3] http://www.globalplatform.org/specificationsdevice.asp look for + "TEE Client API Specification v1.0" and click download. diff --git a/Documentation/tee/index.rst b/Documentation/tee/index.rst new file mode 100644 index 000000000000..a23bd08847e5 --- /dev/null +++ b/Documentation/tee/index.rst @@ -0,0 +1,19 @@ +.. SPDX-License-Identifier: GPL-2.0 + +============= +TEE Subsystem +============= + +.. toctree:: + :maxdepth: 1 + + tee + op-tee + amd-tee + +.. only:: subproject and html + + Indices + ======= + + * :ref:`genindex` diff --git a/Documentation/tee/op-tee.rst b/Documentation/tee/op-tee.rst new file mode 100644 index 000000000000..b0ac097d5547 --- /dev/null +++ b/Documentation/tee/op-tee.rst @@ -0,0 +1,166 @@ +.. SPDX-License-Identifier: GPL-2.0 + +==================================================== +OP-TEE (Open Portable Trusted Execution Environment) +==================================================== + +The OP-TEE driver handles OP-TEE [1] based TEEs. Currently it is only the ARM +TrustZone based OP-TEE solution that is supported. + +Lowest level of communication with OP-TEE builds on ARM SMC Calling +Convention (SMCCC) [2], which is the foundation for OP-TEE's SMC interface +[3] used internally by the driver. Stacked on top of that is OP-TEE Message +Protocol [4]. + +OP-TEE SMC interface provides the basic functions required by SMCCC and some +additional functions specific for OP-TEE. The most interesting functions are: + +- OPTEE_SMC_FUNCID_CALLS_UID (part of SMCCC) returns the version information + which is then returned by TEE_IOC_VERSION + +- OPTEE_SMC_CALL_GET_OS_UUID returns the particular OP-TEE implementation, used + to tell, for instance, a TrustZone OP-TEE apart from an OP-TEE running on a + separate secure co-processor. + +- OPTEE_SMC_CALL_WITH_ARG drives the OP-TEE message protocol + +- OPTEE_SMC_GET_SHM_CONFIG lets the driver and OP-TEE agree on which memory + range to used for shared memory between Linux and OP-TEE. + +The GlobalPlatform TEE Client API [5] is implemented on top of the generic +TEE API. + +Picture of the relationship between the different components in the +OP-TEE architecture:: + + User space Kernel Secure world + ~~~~~~~~~~ ~~~~~~ ~~~~~~~~~~~~ + +--------+ +-------------+ + | Client | | Trusted | + +--------+ | Application | + /\ +-------------+ + || +----------+ /\ + || |tee- | || + || |supplicant| \/ + || +----------+ +-------------+ + \/ /\ | TEE Internal| + +-------+ || | API | + + TEE | || +--------+--------+ +-------------+ + | Client| || | TEE | OP-TEE | | OP-TEE | + | API | \/ | subsys | driver | | Trusted OS | + +-------+----------------+----+-------+----+-----------+-------------+ + | Generic TEE API | | OP-TEE MSG | + | IOCTL (TEE_IOC_*) | | SMCCC (OPTEE_SMC_CALL_*) | + +-----------------------------+ +------------------------------+ + +RPC (Remote Procedure Call) are requests from secure world to kernel driver +or tee-supplicant. An RPC is identified by a special range of SMCCC return +values from OPTEE_SMC_CALL_WITH_ARG. RPC messages which are intended for the +kernel are handled by the kernel driver. Other RPC messages will be forwarded to +tee-supplicant without further involvement of the driver, except switching +shared memory buffer representation. + +OP-TEE device enumeration +------------------------- + +OP-TEE provides a pseudo Trusted Application: drivers/tee/optee/device.c in +order to support device enumeration. In other words, OP-TEE driver invokes this +application to retrieve a list of Trusted Applications which can be registered +as devices on the TEE bus. + +OP-TEE notifications +-------------------- + +There are two kinds of notifications that secure world can use to make +normal world aware of some event. + +1. Synchronous notifications delivered with ``OPTEE_RPC_CMD_NOTIFICATION`` + using the ``OPTEE_RPC_NOTIFICATION_SEND`` parameter. +2. Asynchronous notifications delivered with a combination of a non-secure + edge-triggered interrupt and a fast call from the non-secure interrupt + handler. + +Synchronous notifications are limited by depending on RPC for delivery, +this is only usable when secure world is entered with a yielding call via +``OPTEE_SMC_CALL_WITH_ARG``. This excludes such notifications from secure +world interrupt handlers. + +An asynchronous notification is delivered via a non-secure edge-triggered +interrupt to an interrupt handler registered in the OP-TEE driver. The +actual notification value are retrieved with the fast call +``OPTEE_SMC_GET_ASYNC_NOTIF_VALUE``. Note that one interrupt can represent +multiple notifications. + +One notification value ``OPTEE_SMC_ASYNC_NOTIF_VALUE_DO_BOTTOM_HALF`` has a +special meaning. When this value is received it means that normal world is +supposed to make a yielding call ``OPTEE_MSG_CMD_DO_BOTTOM_HALF``. This +call is done from the thread assisting the interrupt handler. This is a +building block for OP-TEE OS in secure world to implement the top half and +bottom half style of device drivers. + +OPTEE_INSECURE_LOAD_IMAGE Kconfig option +---------------------------------------- + +The OPTEE_INSECURE_LOAD_IMAGE Kconfig option enables the ability to load the +BL32 OP-TEE image from the kernel after the kernel boots, rather than loading +it from the firmware before the kernel boots. This also requires enabling the +corresponding option in Trusted Firmware for Arm. The Trusted Firmware for Arm +documentation [6] explains the security threat associated with enabling this as +well as mitigations at the firmware and platform level. + +There are additional attack vectors/mitigations for the kernel that should be +addressed when using this option. + +1. Boot chain security. + + * Attack vector: Replace the OP-TEE OS image in the rootfs to gain control of + the system. + + * Mitigation: There must be boot chain security that verifies the kernel and + rootfs, otherwise an attacker can modify the loaded OP-TEE binary by + modifying it in the rootfs. + +2. Alternate boot modes. + + * Attack vector: Using an alternate boot mode (i.e. recovery mode), the + OP-TEE driver isn't loaded, leaving the SMC hole open. + + * Mitigation: If there are alternate methods of booting the device, such as a + recovery mode, it should be ensured that the same mitigations are applied + in that mode. + +3. Attacks prior to SMC invocation. + + * Attack vector: Code that is executed prior to issuing the SMC call to load + OP-TEE can be exploited to then load an alternate OS image. + + * Mitigation: The OP-TEE driver must be loaded before any potential attack + vectors are opened up. This should include mounting of any modifiable + filesystems, opening of network ports or communicating with external + devices (e.g. USB). + +4. Blocking SMC call to load OP-TEE. + + * Attack vector: Prevent the driver from being probed, so the SMC call to + load OP-TEE isn't executed when desired, leaving it open to being executed + later and loading a modified OS. + + * Mitigation: It is recommended to build the OP-TEE driver as builtin driver + rather than as a module to prevent exploits that may cause the module to + not be loaded. + +References +========== + +[1] https://github.com/OP-TEE/optee_os + +[2] http://infocenter.arm.com/help/topic/com.arm.doc.den0028a/index.html + +[3] drivers/tee/optee/optee_smc.h + +[4] drivers/tee/optee/optee_msg.h + +[5] http://www.globalplatform.org/specificationsdevice.asp look for + "TEE Client API Specification v1.0" and click download. + +[6] https://trustedfirmware-a.readthedocs.io/en/latest/threat_model/threat_model.html diff --git a/Documentation/tee/tee.rst b/Documentation/tee/tee.rst new file mode 100644 index 000000000000..fd9f8c4ff63d --- /dev/null +++ b/Documentation/tee/tee.rst @@ -0,0 +1,22 @@ +.. SPDX-License-Identifier: GPL-2.0 + +=================================== +TEE (Trusted Execution Environment) +=================================== + +This document describes the TEE subsystem in Linux. + +Overview +======== + +A TEE is a trusted OS running in some secure environment, for example, +TrustZone on ARM CPUs, or a separate secure co-processor etc. A TEE driver +handles the details needed to communicate with the TEE. + +This subsystem deals with: + +- Registration of TEE drivers + +- Managing shared memory between Linux and the TEE + +- Providing a generic API to the TEE diff --git a/Documentation/trace/ftrace-uses.rst b/Documentation/trace/ftrace-uses.rst index f7d98ae5b885..e198854ace79 100644 --- a/Documentation/trace/ftrace-uses.rst +++ b/Documentation/trace/ftrace-uses.rst @@ -182,7 +182,7 @@ FTRACE_OPS_FL_SAVE_REGS_IF_SUPPORTED FTRACE_OPS_FL_RECURSION By default, it is expected that the callback can handle recursion. - But if the callback is not that worried about overehead, then + But if the callback is not that worried about overhead, then setting this bit will add the recursion protection around the callback by calling a helper function that will do the recursion protection and only call the callback if it did not recurse. @@ -190,7 +190,7 @@ FTRACE_OPS_FL_RECURSION Note, if this flag is not set, and recursion does occur, it could cause the system to crash, and possibly reboot via a triple fault. - Not, if this flag is set, then the callback will always be called + Note, if this flag is set, then the callback will always be called with preemption disabled. If it is not set, then it is possible (but not guaranteed) that the callback will be called in preemptable context. diff --git a/Documentation/trace/ftrace.rst b/Documentation/trace/ftrace.rst index 23572f6697c0..16122a8895ba 100644 --- a/Documentation/trace/ftrace.rst +++ b/Documentation/trace/ftrace.rst @@ -180,6 +180,21 @@ of ftrace. Here is a list of some of the key files: Only active when the file contains a number greater than 0. (in microseconds) + buffer_percent: + + This is the watermark for how much the ring buffer needs to be filled + before a waiter is woken up. That is, if an application calls a + blocking read syscall on one of the per_cpu trace_pipe_raw files, it + will block until the given amount of data specified by buffer_percent + is in the ring buffer before it wakes the reader up. This also + controls how the splice system calls are blocked on this file:: + + 0 - means to wake up as soon as there is any data in the ring buffer. + 50 - means to wake up when roughly half of the ring buffer sub-buffers + are full. + 100 - means to block until the ring buffer is totally full and is + about to start overwriting the older data. + buffer_size_kb: This sets or displays the number of kilobytes each CPU @@ -2574,7 +2589,7 @@ want, depending on your needs. - The cpu number on which the function executed is default enabled. It is sometimes better to only trace one cpu (see - tracing_cpu_mask file) or you might sometimes see unordered + tracing_cpumask file) or you might sometimes see unordered function calls while cpu tracing switch. - hide: echo nofuncgraph-cpu > trace_options diff --git a/Documentation/translations/it_IT/process/development-process.rst b/Documentation/translations/it_IT/process/development-process.rst index f1a6eca30824..20e77c9816a1 100644 --- a/Documentation/translations/it_IT/process/development-process.rst +++ b/Documentation/translations/it_IT/process/development-process.rst @@ -8,9 +8,17 @@ Una guida al processo di sviluppo del Kernel ============================================ -Contenuti: +Lo scopo di questo documento è quello di aiutare gli sviluppatori (ed i loro +supervisori) a lavorare con la communità di sviluppo con il minimo sforzo. È +un tentativo di documentare il funzionamento di questa communità in modo che +sia accessibile anche a coloro che non hanno famigliarità con lo sviluppo del +Kernel Linux (o, anzi, con lo sviluppo di software libero in generale). Benchè +qui sia presente del materiale tecnico, questa è una discussione rivolta in +particolare al procedimento, e quindi per essere compreso non richiede una +conoscenza approfondità sullo sviluppo del kernel. .. toctree:: + :caption: Contenuti :numbered: :maxdepth: 2 @@ -22,12 +30,3 @@ Contenuti: 6.Followthrough 7.AdvancedTopics 8.Conclusion - -Lo scopo di questo documento è quello di aiutare gli sviluppatori (ed i loro -supervisori) a lavorare con la communità di sviluppo con il minimo sforzo. È -un tentativo di documentare il funzionamento di questa communità in modo che -sia accessibile anche a coloro che non hanno famigliarità con lo sviluppo del -Kernel Linux (o, anzi, con lo sviluppo di software libero in generale). Benchè -qui sia presente del materiale tecnico, questa è una discussione rivolta in -particolare al procedimento, e quindi per essere compreso non richiede una -conoscenza approfondità sullo sviluppo del kernel. diff --git a/Documentation/translations/ja_JP/SubmitChecklist b/Documentation/translations/ja_JP/SubmitChecklist index 4429447b0965..1759c6b452d6 100644 --- a/Documentation/translations/ja_JP/SubmitChecklist +++ b/Documentation/translations/ja_JP/SubmitChecklist @@ -56,8 +56,8 @@ Linux カーãƒãƒ«ãƒ‘ッãƒæŠ•ç¨¿è€…å‘ã‘ãƒã‚§ãƒƒã‚¯ãƒªã‚¹ãƒˆ 9: sparseを利用ã—ã¦ã¡ã‚ƒã‚“ã¨ã—ãŸã‚³ãƒ¼ãƒ‰ãƒã‚§ãƒƒã‚¯ã‚’ã—ã¦ãã ã•ã„。 -10: 'make checkstack' 㨠'make namespacecheck' を利用ã—ã€å•é¡ŒãŒç™ºè¦‹ã•ã‚ŒãŸã‚‰ - ä¿®æ£ã—ã¦ãã ã•ã„。'make checkstack' ã¯æ˜Žç¤ºçš„ã«å•é¡Œã‚’示ã—ã¾ã›ã‚“ãŒã€ã©ã‚Œã‹ +10: 'make checkstack' を利用ã—ã€å•é¡ŒãŒç™ºè¦‹ã•ã‚ŒãŸã‚‰ä¿®æ£ã—ã¦ãã ã•ã„。 + 'make checkstack' ã¯æ˜Žç¤ºçš„ã«å•é¡Œã‚’示ã—ã¾ã›ã‚“ãŒã€ã©ã‚Œã‹ １ã¤ã®é–¢æ•°ãŒ512ãƒã‚¤ãƒˆã‚ˆã‚Šå¤§ãã„スタックを使ã£ã¦ã„ã‚Œã°ã€ä¿®æ£ã™ã¹ã候補㨠ãªã‚Šã¾ã™ã€‚ diff --git a/Documentation/translations/sp_SP/disclaimer-sp.rst b/Documentation/translations/sp_SP/disclaimer-sp.rst index a400034e95f9..841c2523e3dd 100644 --- a/Documentation/translations/sp_SP/disclaimer-sp.rst +++ b/Documentation/translations/sp_SP/disclaimer-sp.rst @@ -4,3 +4,6 @@ Si tiene alguna duda sobre la exactitud del contenido de esta traducción, la única referencia válida es la documentación oficial en inglés. + Además, por defecto, los enlaces a documentos redirigen a la + documentación en inglés, incluso si existe una versión traducida. + Consulte el Ãndice para más información. diff --git a/Documentation/translations/sp_SP/index.rst b/Documentation/translations/sp_SP/index.rst index 5c2a2131524b..c543b495c042 100644 --- a/Documentation/translations/sp_SP/index.rst +++ b/Documentation/translations/sp_SP/index.rst @@ -76,6 +76,5 @@ Traducciones al español .. toctree:: :maxdepth: 1 - howto process/index wrappers/memory-barriers diff --git a/Documentation/translations/sp_SP/process/handling-regressions.rst b/Documentation/translations/sp_SP/process/handling-regressions.rst new file mode 100644 index 000000000000..aa0988985c55 --- /dev/null +++ b/Documentation/translations/sp_SP/process/handling-regressions.rst @@ -0,0 +1,797 @@ +.. include:: ../disclaimer-sp.rst + +:Translator: Sergio González Collado <sergio.collado@gmail.com> + +.. _sp_handling_regressions: + +Gestión de regresiones +++++++++++++++++++++++ + +*No causamos regresiones* -- este documento describe la que es la "primera +regla del desarrollo del kernel de Linux" y que implica en la práctica para +los desarrolladores. Y complementa la documentación: +Documentation/admin-guide/reporting-regressions.rst, que cubre el tema +desde el punto de vista de un usuario; si nunca ha leÃdo ese texto, realice +al menos una lectura rápida del mismo antes de continuar. + +Las partes importantes (el "TL;DR") +=================================== + +#. Asegúrese de que los suscriptores a la lista `regression mailing list + <https://lore.kernel.org/regressions/>`_ (regressions@lists.linux.dev) + son conocedores con rapidez de cualquier nuevo informe de regresión: + + * Cuando se reciba un correo que no incluyó a la lista, inclúyalo en la + conversación de los correos, mandando un breve "Reply-all" con la + lista en CCed. + + * Mande o redirija cualquier informe originado en los gestores de bugs + a la lista. + +#. Haga que el bot del kernel de Linux "regzbot" realice el seguimiento del + incidente (esto es opcional, pero recomendado). + + * Para reportes enviados por correo, verificar si contiene alguna lÃnea + como ``#regzbot introduced v5.13..v5.14-rc1``. Si no, mandar una + respuesta (con la lista de regresiones en CC) que contenga un párrafo + como el siguiente, lo que le indica a regzbot cuando empezó a suceder + el incidente:: + + #regzbot ^introduced 1f2e3d4c5b6a + + * Cuando se mandan informes desde un gestor de incidentes a la lista de + regresiones(ver más arriba), incluir un párrafo como el siguiente:: + + #regzbot introduced: v5.13..v5.14-rc1 + #regzbot from: Some N. Ice Human <some.human@example.com> + #regzbot monitor: http://some.bugtracker.example.com/ticket?id=123456789 + +#. Cuando se manden correcciones para las regresiones, añadir etiquetas + "Link:" a la descripción, apuntado a todos los sitios donde se informó + del incidente, como se indica en el documento: + Documentation/process/submitting-patches.rst y + :ref:`Documentation/process/5.Posting.rst <development_posting>`. + +#. Intente arreglar las regresiones rápidamente una vez la causa haya sido + identificada; las correcciones para la mayor parte de las regresiones + deberÃan ser integradas en menos de dos semanas, pero algunas pueden + resolverse en dos o tres dÃas. + +Detalles importantes para desarrolladores en la regresiones de kernel de Linux +============================================================================== + +Puntos básicos importantes más en detalle +----------------------------------------- + +Qué hacer cuando se recibe un aviso de regresión. +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Asegúrese de que el programa de gestión de regresiones del kernel de Linux +y los subscritos a la lista de correo `regression mailing list +<https://lore.kernel.org/regressions/>`_ (regressions@lists.linux.dev) son +conocedores de cualquier nuevo informe de regresión: + + * Cuando se recibe un informe por email que no tiene en CC la lista, + inmediatamente meterla en el la cadena de emails mandado al menos un + breve "Reply-all" con la lista en CC; Intentar asegurar que la lista es + añadida en CC de nuevo en caso de que alguna respuesta la omita de la + lista. + + * Si un informe enviado a un gestor de defectos, llega a su correo, + reenvÃelo o redirijalo a la lista. Considere verificar los archivos de + la lista de antemano, si la persona que lo ha informado, lo ha enviado + anteriormente, como se indica en: + Documentation/admin-guide/reporting-issues.rst. + +Cuando se realice cualquiera de las acciones anteriores, considere +inmediatamente iniciar el seguimiento de la regresión con "regzbot" el +gestor de regresiones del kernel de Linux. + + * Para los informes enviados por email, verificar si se ha incluido un + comando a "regzbot", como ``#regzbot introduced 1f2e3d4c5b6a``. Si no es + asÃ, envÃe una respuesta (con la lista de regresiones en CC) con un + párrafo como el siguiente:: + + #regzbot ^introduced: v5.13..v5.14-rc1 + + Esto indica a regzbot el rango de versiones en el cual es defecto + comenzó a suceder; Puede especificar un rango usando los identificadores + de los commits asà como un único commit, en caso en el que el informante + haya identificado el commit causante con 'bisect'. + + Tenga en cuenta que el acento circunflejo (^) antes de "introduced": + Esto indica a regzbot, que debe tratar el email padre (el que ha sido + respondido) como el informeinicial para la regresión que quiere ser + seguida. Esto es importante, ya que regzbot buscará más tarde parches + con etiquetas "Link:" que apunten al al informe de losarchivos de + lore.kernel.org. + + * Cuando mande informes de regresiones a un gestor de defectos, incluya un + párrafo con los siguientes comandos a regzbot:: + + #regzbot introduced: 1f2e3d4c5b6a + #regzbot from: Some N. Ice Human <some.human@example.com> + #regzbot monitor: http://some.bugtracker.example.com/ticket?id=123456789 + + Regzbot asociará automáticamente parches con el informe que contengan + las etiquetas "Link:" apuntando a su email o el ticket indicado. + +Qué es importante cuando se corrigen regresiones +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +No se necesita hacer nada especial cuando se mandan las correcciones para +las regresiones únicamente recordar lo que se explica en los documentos: +Documentation/process/submitting-patches.rst, +:ref:`Documentation/process/5.Posting.rst <development_posting>`, y +Documentation/process/stable-kernel-rules.rst + + * Apunte a todos los lugares donde el incidente se reportó usando la + etiqueta "Link:" :: + + Link: https://lore.kernel.org/r/30th.anniversary.repost@klaava.Helsinki.FI/ + Link: https://bugzilla.kernel.org/show_bug.cgi?id=1234567890 + + * Añada la etiqueta "Fixes:" para indicar el commit causante de la + regresión. + + * Si el culpable ha sido "mergeado" en un ciclo de desarrollo anterior, + marque explÃcitamente el fix para retro-importarlo usando la etiqueta + ``Cc: stable@vger.kernel.org`` tag. + +Todo esto se espera y es importante en una regresión, ya que estas +etiquetas son de gran valor para todos (incluido usted) que pueda estar +mirando en ese incidente semanas, meses o años después. Estas etiquetas son +también cruciales para las herramientas y scripts usados por otros +desarrolladores del kernel o distribuciones de Linux; una de esas +herramientas es regzbot, el cual depende mucho de las etiquetas "Link:" +para asociar los informes por regresiones con los cambios que las +resuelven. + + +Priorización del trabajo en arreglar regresiones +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Al final, los desarrolladores deberÃan hacer lo posible para evitar a los +usuarios situaciones donde una regresión les deje solo tres opciones: + + * Ejecutar el kernel con una regresión que afecta seriamente al uso. + + * Cambiar a un kernel nuevo o mas antiguo -- rebajarse a una versión + soportada del kernel que no tenga las funcionalidades requeridas. + + * Continuar ejecutando una versión desfasada y potencialmente insegura del + kernel por más de dos semanas después de que el causante de una regresión + fuese identificado. + +Cómo se ejecuta esto depende mucho de la situación. A continuación se +presentan unas reglas generales, en orden de importancia: + + * Priorice el trabajo en la gestión de los informes de la regresión y + arreglar la regresión por encima de cualquier otro trabajo en el kernel + de Linux, a menos que lo último afecte profundamente a efectos de + seguridad, o cause errores en los que haya pérdida o daño de datos. + + * Considere siempre revertir los commits responsables y re-aplicarlos + después, junto con las correcciones necesarias, ya que esto puede la + forma menos peligrosa y más rápida de arreglar la regresión. + + * Los desarrolladores deberÃan gestionar la regresión en todos los kernels + soportados de la serie, pero son libres de delegar el trabajo al equipo + permanente el incidente no hubiese ocurrido en la lÃnea principal. + + * Intente resolver cualquier regresión que apareciera en el ciclo de + desarrollo antes de que este acabe. Si se teme que una corrección + pudiera ser demasiado arriesgada para aplicarla dÃas antes de una + liberación de la lÃnea principal de desarrollo, dejar decidir a Linus: + mande la corrección a él de forma separada, tan pronto como sea posible + con una explicación de la situación. El podrá decidir, y posponer la + liberación si fuese necesario, por ejemplo si aparecieran múltiples + cambios como ese. + + * Gestione las regresiones en la rama estable, de largo término, o la + propia rama principal de las versiones, con más urgencia que la + regresiones en las preliberaciones. Esto cambia después de la liberación + de la quinta pre-liberación, aka "-rc5": la rama principal entonces se + vuelve más importante, asegurar que todas las mejoras y correcciones son + idealmente testeados juntos por al menos una semana antes de que Linux + libere la nueva versión en la rama principal. + + * Intente arreglar regresiones en un intervalo de una semana después de + que se ha identificado el responsable, si el incidente fue introducido + en alguno de los siguientes casos: + + * una versión estable/largo-plazo reciente + + * en el último ciclo de desarrollo de la rama principal + + En el último caso (por ejemplo v5.14), intentar gestionar las + regresiones incluso más rápido, si la versión estable precedente (v5.13) + ha de ser abandonada pronto o ya se ha etiquetado como de final de vida + (EOL de las siglas en inglés End-of-Life) -- esto sucede usualmente + sobre tres o cuatro semanas después de una liberación de una versión en + la rama principal. + + * Intente arreglar cualquier otra regresión en un periodo de dos semanas + después de que el culpable haya sido identificado. Dos o tres semanas + adicionales son aceptables para regresiones de rendimiento y otros + incidentes que son molestos, pero no bloquean a nadie la ejecución de + Linux (a menos que se un incidente en el ciclo de desarrollo actual, en + ese caso se deberÃa gestionar antes de la liberación de la versión). + Unas semanas son aceptables si la regresión únicamente puede ser + arreglada con un cambio arriesgado y al mismo tiempo únicamente afecta a + unos pocos usuarios; también está bien si se usa tanto tiempo como fuera + necesario si la regresión está presente en la segunda versión más nueva + de largo plazo del kernel. + +Nota: Los intervalos de tiempo mencionados anteriormente para la resolución +de las regresiones, incluyen la verificación de esta, revisión e inclusión +en la rama principal, idealmente con la corrección incluida en la rama +"linux-next" al menos brevemente. Esto conllevará retrasos que también se +tienen tener en cuenta. + +Se espera que los maintainers de los subsistemas, ayuden en conseguir esos +tiempos, haciendo revisiones con prontitud y gestionando con rapidez los +parches aceptados. Esto puede resultar en tener que mandar peticiones de +git-pull antes o de forma más frecuente que lo normal; dependiendo del +arreglo, podrÃa incluso ser aceptable saltarse la verificación en +linux-next. Especialmente para las correcciones en las ramas de los kernels +estable y de largo plazo necesitan ser gestionadas rápidamente, y las +correcciones necesitan ser incluidas en la rama principal antes de que +puedan ser incluidas posteriormente a las series precedentes. + + +Más aspectos sobre regresiones que los desarrolladores deben saber +------------------------------------------------------------------ + +Cómo tratar con cambios donde se sabe que hay riesgo de regresión +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Evalué cómo de grande es el riesgo de una regresión, por ejemplo realizando +una búsqueda en las distribuciones de linux y en Git forges. Considere +también preguntar a otros desarrolladores o proyectos que pudieran ser +afectados para evaluar o incluso testear el cambio propuesto; si +apareciesen problemas, quizás se pudiera encontrar una solución aceptable +para todos. + +Si al final, el riesgo de la regresión parece ser relativamente pequeño, +entonces adelante con el cambio, pero siempre informe a todas las partes +involucradas del posible riesgo. Por tanto, asegúrese de que la descripción +del parche, se hace explÃcito este hecho. Una vez el cambio ha sido +integrado, informe al gestor de regresiones de Linux y a las listas de +correo de regresiones sobre el riesgo, de manera que cualquiera que tenga +el cambio en el radar, en el caso de que aparezcan reportes. Dependiendo +del riesgo, quizás se quiera preguntar al mantenedor del subsistema, que +mencione el hecho en su lÃnea principal de desarrollo. + +¿Qué más hay que saber sobre regresiones? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Repase la documentación: Documentation/admin-guide/reporting-regressions.rst, +esta cubre otros aspectos a tener a en cuenta y conocer: + + * la finalidad de la "regla de no regresión" + + * qué incidencias no se califican como regresión + + * quién es el responsable de identificar la causa raÃz de una regresión + + * cómo gestionar situaciones difÃciles, como por ejemplo cuando una + regresión es causada por una corrección de seguridad o cuando una + regresión causa otra regresión + +A quién preguntar por consejo cuando se trata de regresiones +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Mande un email a la lista de correo de regresiones +(regressions@lists.linux.dev) y CC al seguidor de regresiones del kernel de +Linux (regressions@leemhuis.info); Si el incidente pudiera ser mejor +gestionarlo en privado, puede omitirse la lista. + + +Más sobre la gestión de regresiones con regzbot +----------------------------------------------- + +¿Por qué el kernel de Linux tiene un gestor de regresiones, y por qué se usa regzbot? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Reglas como "no regresiones" necesitan asegurar que se cumplen, de otro +modo se romperÃan accidentalmente o a propósito. La historia ha mostrado +que esto es verdad también para el kernel de Linux. Esto es por lo que +Thorsten Leemhuis se ofreció como voluntario para dar una solución a esto, +con el gestor de regresiones del kernel de Linux. A nadie se le paga por +hacer esto, y esa es la razón por la gestión de regresiones es un servicio +con el "mejor esfuerzo". + +Intentos iniciales de gestionar manualmente las regresiones han demostrado +que es una tarea extenuante y frustrante, y por esa razón se dejaron de +hacer después de un tiempo. Para evitar que volviese a suceder esto, +Thorsten desarrollo regbot para facilitar el trabajo, con el objetivo a +largo plazo de automatizar la gestión de regresiones tanto como fuese +posible para cualquiera que estuviese involucrado. + +¿Cómo funciona el seguimiento de regresiones con regzbot? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +El bot monitoriza las respuestas de los informes de las regresiones +identificadas. Adicionalmente mira si se han publicado o enviado parches +que hagan referencia a esos informes con la etiqueta: "Link:"; respuestas a +esos parches también se siguen. Combinando esta información, también +proporciona una buena imagen del estado actual del proceso de corrección. + +Regzbot intenta hacer todo este trabajo con tan poco retraso como sea +posible tanto para la gente que lo reporta, como para los desarrolladores. +De hecho, solo los informantes son requeridos para una tarea adicional: +necesitan informar a regzbot con el comando ``#regzbot introduced`` +indicado anteriormente; si no hacen esto, alguien más puede hacerlo usando +``#regzbot ^introduced``. + +Para los desarrolladores normalmente no hay un trabajo adicional que +realizar, únicamente necesitan asegurarse una cosa, que ya se hacÃa mucho +antes de que regzbot apareciera: añadir las etiquetas "Link:" a la +descripción del parche apuntando a todos los informes sobre el error +corregido. + +¿Tengo que usar regzbot? +~~~~~~~~~~~~~~~~~~~~~~~~ + +Hacerlo es por el bien de todo el mundo, tanto los mantenedores del kernel, +como Linus Torvalds dependen parcialmente en regzbot para seguir su trabajo +-- por ejemplo cuando deciden liberar una nueva versión o ampliar la fase de +desarrollo. Para esto necesitan conocer todas las regresiones que están sin +corregir; para esto, es conocido que Linux mira los informes semanales que +manda regzbot. + +¿He de informar a regzbot cada regresión que encuentre? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Idealmente, sÃ: todos somos humanos y olvidamos fácilmente los problemas +cuando algo más importante aparece inesperadamente -- por ejemplo un +problema mayor en el kernel de Linux o algo en la vida real que nos mantenga +alejados de los teclados por un tiempo. Por eso es mejor informar a regzbot +sobre cada regresión, excepto cuando inmediatamente escribimos un parche y +los mandamos al árbol de desarrollo en el que se integran habitualmente a +la serie del kernel. + +¿Cómo ver qué regresiones esta siguiendo regbot actualmente? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Verifique el `interfaz web de regzbot <https://linux-regtracking.leemhuis.info/regzbot/>`_ +para ver la última información; o `busque el último informe de regresiones +<https://lore.kernel.org/lkml/?q=%22Linux+regressions+report%22+f%3Aregzbot>`_, +el cual suele ser enviado por regzbot una vez a la semana el domingo por la +noche (UTC), lo cual es unas horas antes de que Linus normalmente anuncie +las "(pre-)releases". + +¿Qué sitios supervisa regzbot? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Regzbot supervisa las listas de correo más importantes de Linux, como +también las de los repositorios linux-next, mainline y stable/longterm. + + +¿Qué tipos de incidentes han de ser monitorizados por regzbot? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +El bot debe hacer seguimiento de las regresiones, y por tanto por favor, +no involucre a regzbot para incidencias normales. Pero es correcto para +el gestor de incidencias de kernel de Linux, monitorizar incidentes +graves, como informes sobre cuelgues, corrupción de datos o errores +internos (Panic, Oops, BUG(), warning, ...). + + +¿Puedo añadir una regresión detectada por un sistema de CI al seguimiento de regzbot? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Siéntase libre de hacerlo, si la regresión en concreto puede tener un +impacto en casos de uso prácticos y por tanto ser detectado por los usuarios; +AsÃ, por favor no involucre a regzbot en regresiones teóricas que +difÃcilmente pudieran manifestarse en un uso real. + +¿Cómo interactuar con regzbot? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Usando el comando 'regzbot' en una respuesta directa o indirecta al correo +con el informe de regresión. Ese comando necesita estar en su propio +párrafo (debe estar separado del resto del texto usando lÃneas en blanco): + +Por ejemplo ``#regzbot introduced <version or commit>``, que hace que regzbot +considere el correo como un informe de regressión que se ha de añadir al +seguimiento, como se ha descrito anteriormente; ``#regzbot ^introduced <version or commit>`` +es otro ejemplo del comando, el cual indica a regzbot que considere el email +anterior como el informe de una regresión que se ha de comenzar a monitorizar. + +Una vez uno de esos dos comandos se ha utilizado, se pueden usar otros +comandos regzbot en respuestas directas o indirectas al informe. Puede +escribirlos debajo de uno de los comandos anteriormente usados o en las +respuestas al correo en el que se uso como respuesta a ese correo: + + * Definir o actualizar el tÃtulo:: + + #regzbot title: foo + + * Monitorizar una discusión o un tiquet de bugzilla.kernel.org donde + aspectos adicionales del incidente o de la corrección se están + comentando -- por ejemplo presentar un parche que corrige la regresión:: + + #regzbot monitor: https://lore.kernel.org/all/30th.anniversary.repost@klaava.Helsinki.FI/ + + Monitorizar solamente funciona para lore.kernel.org y bugzilla.kernel.org; + regzbot considerará todos los mensajes en ese hilo o el tiquet como + relacionados al proceso de corrección. + + * Indicar a un lugar donde más detalles de interés, como un mensaje en una + lista de correo o un tiquet en un gestor de incidencias que pueden estar + levemente relacionados, pero con un tema diferente:: + + #regzbot link: https://bugzilla.kernel.org/show_bug.cgi?id=123456789 + + * Identificar una regresión como corregida por un commit que se ha mandado + aguas arriba o se ha publicado:: + + #regzbot fixed-by: 1f2e3d4c5d + + + * Identificar una regresión como un duplicado de otra que ya es seguida + por regzbot:: + + #regzbot dup-of: https://lore.kernel.org/all/30th.anniversary.repost@klaava.Helsinki.FI/ + + * Identificar una regresión como inválida:: + + #regzbot invalid: wasn't a regression, problem has always existed + + +¿Algo más que decir sobre regzbot y sus comandos? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Hay información más detallada y actualizada sobre el bot de seguimiento de +regresiones del kernel de Linux en: `project page <https://gitlab.com/knurd42/regzbot>`_, +y entre otros contiene una `guia de inicio <https://gitlab.com/knurd42/regzbot/-/blob/main/docs/getting_started.md>`_ +y `documentación de referencia <https://gitlab.com/knurd42/regzbot/-/blob/main/docs/reference.md>`_ +Ambos contienen más detalles que las secciones anteriores. + + +Citas de Linus sobre regresiones +-------------------------------- + +A continuación se encuentran unos ejemplos reales (traducidos) de como +Linus Torvalds espera que se gestionen las regresiones: + + + * De 2017-10-26 (1/2) + <https://lore.kernel.org/lkml/CA+55aFwiiQYJ+YoLKCXjN_beDVfu38mg=Ggg5LFOcqHE8Qi7Zw@mail.gmail.com/>`_:: + + Si rompes la configuración de los espacios de usuario ESO ES UNA REGRESIÓN. + + No está bien decir "pero nosotros arreglaremos la configuración del espacio + de usuario". + + Realmente. NO ESTà BIEN. + + [...] + + La primera regla es: + + - no causamos regresiones + + y el corolario es que cuando una regresión pasa, lo admitimos y lo + arreglamos, en vez de echar la culpa al espacio de usuario. + + El hecho de que aparentemente se haya negado la regresión durante + tres semanas, significa que lo revertiré y dejaré de integrar peticiones + de apparmor hasta que la gente involucrada entienda como se hace + el desarrollo del kernel. + + + * De `2017-10-26 (2/2) + <https://lore.kernel.org/lkml/CA+55aFxW7NMAMvYhkvz1UPbUTUJewRt6Yb51QAx5RtrWOwjebg@mail.gmail.com/>`_:: + + La gente deberÃa sentirse libre de actualizar su kernel y simplemente + no preocuparse por ello. + + Me niego a imponer una limitación del tipo "solo puede actualizar + el kernel si actualiza otro programa". Si el kernel trabaja para tÃ, + la regla es que continúe trabajando para tÃ. + + Ha habido algunas excepciones, pero son pocas y separadas entre sÃ, y + generalmente tienen una razón fundamental para haber sucedido, que era + básicamente inevitable, y la gente intentó evitarlas por todos los + medios. Quizás no podamos mantener el hardware más, después de que han + pasado décadas y nadie los usacon kernel modernos. Quizás haya un + problema de seguridad serio con cómo hicimos las cosas, y la gente + depende de un modelo fundamentalmente roto. Quizás haya algún otro roto + fundamental, que tenga que tener una _flag_ y por razones internas y + fundamentales. + + Y nótese que esto trata sobre *romper* los entornos de la gente. + + Cambios de comportamiento pasan, y quizás no se mantengan algunas + funcionalidades más. Hay un número de campos en /proc/<pid>/stat que + se imprimen como ceros, simplemente porque ni siquiera existen ya en + kernel, o porque mostrarlos era un error (tÃpica una fuga de + información). Pero los números se sustituyeron por ceros, asà que + el código que se usaba para parsear esos campos todavÃa existe. El + usuario puede no ver todo lo que podÃa ver antes, y por eso el + omportamiento es claramente diferente, pero las cosas todavÃa + _funcionan_, incluso si no se puede mostrar información sensible + (o que no es ya importante). + + Pero si algo realmente se rompe, entonces el cambio debe de arreglarse + o revertirse. Y se arregla en el *kernel*. No diciendo "bueno, arreglaremos + tu espacio de usuario". Ha sido un cambio en el kernel el que creo + el problema, entonces ha de ser el kernel el que lo corrija, porque + tenemos un modelo de "actualización". Pero no tenemos una "actualización + con el nuevo espacio de usuario". + + Y yo seriamente me negaré a coger código de gente que no entiende y + honre esta sencilla regla. + + Y esta regla no va a cambiar. + + Y sÃ, me doy cuenta que el kernel es "especial" en este respecto. Y + estoy orgulloso de ello. + + Y he visto, y puedo señalar, muchos proyectos que dicen "Tenemos que + romper ese caso de uso para poder hacer progresos" o "estabas basandote + en comportamientos no documentados, debe ser duro ser tú" o "hay una + forma mejor de hacer lo que quieres hacer, y tienes que cambiar a esa + nueva forma", y yo simplemente no pienso que eso sea aceptable fuera + de una fase alfa muy temprana que tenga usuarios experimentales que + saben a lo que se han apuntado. El kernel no ha estado en esta + situación en las dos últimas décadas. + + Nosotros rompemos la API _dentro_ del kernel todo el tiempo. Y + arreglaremos los problemas internos diciendo "tú ahora necesitas + hacer XYZ", pero entonces es sobre la API interna del kernel y la + gente que hace esto entonces tendrá obviamente que arreglar todos + los usos de esa API del kernel. Nadie puede decir "ahora, yo he roto + la API que usas, y ahora tú necesitas arreglarlo". Quién rompa algo, + lo arregla también. + + Y nosotros, simplemente, no rompemos el espacio de usuario. + + * De `2020-05-21 + <https://lore.kernel.org/all/CAHk-=wiVi7mSrsMP=fLXQrXK_UimybW=ziLOwSzFTtoXUacWVQ@mail.gmail.com/>`_:: + + Las reglas sobre regresiones nunca han sido sobre ningún tipo de + comportamiento documentado, o dónde está situado el código. + + Las reglas sobre regresiones son siempre sobre "roturas en el + flujo de trabajo del usuario". + + Los usuarios son literalmente la _única_ cosa que importa. + + Argumentaciones como "no deberÃa haber usado esto" o "ese + comportamiento es indefinido, es su culpa que su aplicación no + funcione" o "eso solÃa funcionar únicamente por un bug del kernel" son + irrelevantes. + + Ahora, la realidad nunca es blanca o negra. Asà hemos tenido situaciones + como "un serio incidente de seguridad" etc que solamente nos fuerza + a hacer cambios que pueden romper el espacio de usuario. Pero incluso + entonces la regla es que realmente no hay otras opciones para que + las cosas sigan funcionando. + + Y obviamente, si los usuarios tardan años en darse cuenta que algo + se ha roto, o si hay formas adecuadas para sortear la rotura que + no causen muchos problemas para los usuarios (por ejemplo: "hay un + puñado de usuarios, y estos pueden usar la lÃnea de comandos del + kernel para evitarlos"; ese tipo de casos), en esos casos se ha sido + un poco menos estricto. + + Pero no, "eso que está documentado que está roto" (si es dado a que + el código estaba en preparación o porque el manual dice otra cosa) eso + es irrelevante. Si preparar el código es tan útil que la gente, + acaba usando, esto implica que básicamente es código del kernel con + una señal diciendo "por favor limpiar esto". + + El otro lado de la moneda es que la gente que habla sobre "estabilidad + de las APIs" están totalmente equivocados. Las APIs tampoco importan. + Se puede hacer cualquier cambio que se quiera a una API ... siempre y + cuando nadie se de cuenta. + + De nuevo, la regla de las regresiones no trata sobre la documentación, + tampoco sobre las APIs y tampoco sobre las fases de la Luna. + + Únicamente trata sobre "hemos causado problemas al espacio de usuario que + antes funcionaba". + + * De `2017-11-05 + <https://lore.kernel.org/all/CA+55aFzUvbGjD8nQ-+3oiMBx14c_6zOj2n7KLN3UsJ-qsd4Dcw@mail.gmail.com/>`_:: + + Y nuestra regla sobre las regresiones nunca ha sido "el comportamiento + no cambia". Eso podrÃa significar que nunca podrÃamos hacer ningún + cambio. + + Por ejemplo, hacemos cosas como añadir una nueva gestión de + errores etc todo el tiempo, con lo cual a veces incluso añadimos + tests en el directorio de kselftest. + + Asà que claramente cambia el comportamiento todo el tiempo y + nosotros no consideramos eso una regresión per se. + + La regla para regresiones para el kernel es para cuando se + rompe algo en el espacio de usuario. No en algún test. No en + "mira, antes podÃa hacer X, y ahora no puedo". + + * De `2018-08-03 + <https://lore.kernel.org/all/CA+55aFwWZX=CXmWDTkDGb36kf12XmTehmQjbiMPCqCRG2hi9kw@mail.gmail.com/>`_:: + + ESTÃS OLVIDANDO LA REGLA #1 DEL KERNEL. + + No hacemos regresiones, y no hacemos regresiones porque estás 100% + equivocado. + + Y la razón que apuntas en tú opinión es exactamente *PORQUÉ* estás + equivocado. + + Tus "buenas razones" son honradas y pura basura. + + El punto de "no hacemos regresiones" es para que la gente pueda + actualizar el kernel y nunca tengan que preocuparse por ello. + + > El kernel tiene un bug que ha de ser arreglado + + Eso es *TOTALMENTE* insustancial. + + Chicos, si algo estaba roto o no, NO IMPORTA. + + ¿Porqué? + + Los errores pasan. Eso es un hecho de la vida. Discutir que + "tenemos que romper algo porque estábamos arreglando un error" es + una locura. Arreglamos decenas de errores cada dia, pensando que + "arreglando un bug" significa que podemos romper otra cosa es algo + que simplemente NO ES VERDAD. + + Asà que los bugs no son realmente relevantes para la discusión. Estos + suceden y se detectan, se arreglan, y no tienen nada que ver con + "rompemos a los usuarios". + + Porque la única cosa que importa ES EL USUARIO. + + ¿Cómo de complicado es eso de comprender? + + Cualquier persona que use "pero no funcionaba correctamente" es + un argumento no tiene la razón. Con respecto al USUARIO, no era + erróneo - funcionaba para él/ella. + + Quizás funcionaba *porque* el usuario habÃa tenido el bug en cuenta, + y quizás funcionaba porque el usuario no lo habÃa notado - de nuevo + no importa. Funcionaba para el usuario. + + Romper el flujo del trabajo de un usuario, debido a un "bug" es la + PEOR razón que se pueda usar. + + Es básicamente decir "He cogido algo que funcionaba, y lo he roto, + pero ahora es mejor". ¿No ves que un argumento como este es j*didamente + absurdo? + + y sin usuarios, tu programa no es un programa, es una pieza de + código sin finalidad que puedes perfectamente tirar a la basura. + + Seriamente. Esto es *porque* la regla #1 para el desarrollo del + kernel es "no rompemos el espacio de usuario". Porque "He arreglado + un error" PARA NADA ES UN ARGUMENTO si esa corrección del código + rompe el espacio de usuario. + + si actualizamos el kernel TODO EL TIEMPO, sin actualizar ningún otro + programa en absoluto. Y esto es absolutamente necesario, porque + las dependencias son terribles. + + Y esto es necesario simplemente porque yo como desarrollador del + kernel no actualizo al azar otras herramientas que ni siquiera me + importan como desarrollador del kernel, y yo quiero que mis usuarios + se sientan a salvo haciendo lo mismo. + + Asà que no. Tu regla está COMPLETAMENTE equivocada. Si no puedes + actualizar el kernel sin actualizar otro binario al azar, entonces + tenemos un problema. + + * De `2021-06-05 + <https://lore.kernel.org/all/CAHk-=wiUVqHN76YUwhkjZzwTdjMMJf_zN4+u7vEJjmEGh3recw@mail.gmail.com/>`_:: + + NO HAY ARGUMENTOS VÃLIDOS PARA UNA REGRESIÓN. + + Honestamente, la gente de seguridad necesita entender que "no funciona" + no es un caso de éxito sobre seguridad. Es un caso de fallo. + + SÃ, "no funciona" puede ser seguro. Pero en este caso es totalmente + inutil. + + * De `2011-05-06 (1/3) + <https://lore.kernel.org/all/BANLkTim9YvResB+PwRp7QTK-a5VNg2PvmQ@mail.gmail.com/>`_:: + + La compatibilidad de los binarios es más importante. + + Y si los binarios no usan el interfaz para parsear el formato + (o justamente lo parsea incorrectamente - como el reciente ejemplo + de añadir uuid al /proc/self/mountinfo), entonces es una regresión. + + Y las regresiones se revierten, a menos que haya problemas de + seguridad o similares que nos hagan decir "Dios mÃo, realmente + tenemos que romper las cosas". + + No entiendo porqué esta simple lógica es tan difÃcil para algunos + desarrolladores del kernel. La realidad importa. Sus deseos personales + NO IMPORTAN NADA. + + Si se crea un interface que puede usarse sin parsear la + descripción del interface, entonces estaḿos atascados en el interface. + La teorÃa simplemente no importa. + + Podrias alludar a arreglar las herramientas, e intentar evitar los + errores de compatibilidad de ese modo. No hay tampoco tantos de esos. + + De `2011-05-06 (2/3) + <https://lore.kernel.org/all/BANLkTi=KVXjKR82sqsz4gwjr+E0vtqCmvA@mail.gmail.com/>`_:: + + Esto claramente NO es un tracepoint interno. Por definición. Y está + siendo usado por powertop. + + De `2011-05-06 (3/3) + <https://lore.kernel.org/all/BANLkTinazaXRdGovYL7rRVp+j6HbJ7pzhg@mail.gmail.com/>`_:: + + Tenemos programas que usan esa ABI y si eso se rompe eso es una + regresión. + + * De `2012-07-06 <https://lore.kernel.org/all/CA+55aFwnLJ+0sjx92EGREGTWOx84wwKaraSzpTNJwPVV8edw8g@mail.gmail.com/>`_:: + + > Ahora esto me ha dejado preguntandome si Debian _inestable_ + realmente califica + > como espacio de usuario estándar. + + Oh, si el kernel rompe algún espacio de usuario estándar, eso cuenta. + MuchÃsima gente usa Debian inestable. + + * De `2019-09-15 + <https://lore.kernel.org/lkml/CAHk-=wiP4K8DRJWsCo=20hn_6054xBamGKF2kPgUzpB5aMaofA@mail.gmail.com/>`_:: + + Una reversión _en particular_ en el último minuto en el último commit + (no teniendo en cuenta el propio cambio de versión) justo antes + de la liberación, y aunque es bastante incómodo, quizás también es + instructivo. + + Lo que es instructivo sobre esto es que he revertido un commit que no + tenÃa ningún error. De hecho, hacÃa exactamente lo que pretendÃa, y lo + hacÃa muy bien. De hecho lo hacÃa _tan_ bien que los muy mejorados + patrones de IO que causaba han acabado revelando una regresión observable + desde el espacio de usuario, debido a un error real en un componente + no relacionado en absoluto. + + De todas maneras, los detalles actuales de esta regresión no son la + razón por la que señalo esto como instructivo. Es más que es un ejemplo + ilustrativo sobre lo que cuenta como una regresión, y lo que conlleva + la regla del kernel de "no regresiones". El commit que ha sido revertido + no cambiaba ninguna API, y no introducÃa ningún error nuevo en el código. + Pero acabó exponiendo otro problema, y como eso causaba que la + actualización del kernel fallara para el usuario. Asà que ha sido + revertido. + + El foco aquÃ, es que hemos hecho la reversión basándonos en el + comportamiento reportado en el espacio de usuario, no basado en + conceptos como "cambios de ABI" o "provocaba un error". Los mejores + patrones de IO que se han presentado debido al cambio únicamente han + expuesto un viejo error, y la gente ya dependÃa del benigno + comportamiento de ese viejo error. + + Y que no haya miedo, reintroduciremos el arreglo que mejoraba los + patrones de IO una vez hayamos decidido cómo gestionar el hecho de + que hay una interacción incorrecta con un interfaz en el que la + gente dependÃa de ese comportamiento previo. Es únicamente que + tenemos que ver cómo gestionamos y cómo lo hacemos (no hay menos de + tres parches diferentes de tres desarrolladores distintos que estamos + evaluando, ... puede haber más por llegar). Mientras tanto, he + revertido lo que exponÃa el problema a los usuarios de esta release, + incluso cuando espero que el fix será reintroducido (quizás insertado + a posteriormente como un parche estable) una vez lleguemos a un + acuerdo sobre cómo se ha de exponer el error. + + Lo que hay que recordar de todo el asunto no es sobre si el cambio + de kernel-espacio-de-usuario ABI, o la corrección de un error, o si + el código antiguo "en primer lugar nunca deberÃa haber estado ahÃ". + Es sobre si algo rompe el actual flujo de trabajo del usuario. + + De todas formas, esto era mi pequeña aclaración en todo este + tema de la regresión. Ya que es la "primera regla de la programación + del kernel", me ha parecido que quizás es bueno mencionarlo de + vez en cuando. diff --git a/Documentation/translations/sp_SP/howto.rst b/Documentation/translations/sp_SP/process/howto.rst index f1629738b49d..dd793c0f8574 100644 --- a/Documentation/translations/sp_SP/howto.rst +++ b/Documentation/translations/sp_SP/process/howto.rst @@ -1,4 +1,4 @@ -.. include:: ./disclaimer-sp.rst +.. include:: ../disclaimer-sp.rst :Original: :ref:`Documentation/process/howto.rst <process_howto>` :Translator: Carlos Bilbao <carlos.bilbao@amd.com> diff --git a/Documentation/translations/sp_SP/process/index.rst b/Documentation/translations/sp_SP/process/index.rst index d6f3ccfb160e..2239373b3999 100644 --- a/Documentation/translations/sp_SP/process/index.rst +++ b/Documentation/translations/sp_SP/process/index.rst @@ -24,3 +24,7 @@ contribution-maturity-model security-bugs embargoed-hardware-issues + handling-regressions + management-style + submit-checklist + howto diff --git a/Documentation/translations/sp_SP/process/management-style.rst b/Documentation/translations/sp_SP/process/management-style.rst new file mode 100644 index 000000000000..4db33fbf8941 --- /dev/null +++ b/Documentation/translations/sp_SP/process/management-style.rst @@ -0,0 +1,299 @@ +.. include:: ../disclaimer-sp.rst + +:Original: Documentation/process/management-style.rst +:Translator: Avadhut Naik <avadhut.naik@amd.com> + +.. _sp_managementstyle: + + +Estilo de gestión del kernel de Linux +===================================== + +Este es un documento breve que describe el estilo de gestión preferido (o +inventado, dependiendo de a quién le preguntes) para el kernel de Linux. +Está destinado a reflejar el documento +:ref:`translations/sp_SP/process/coding-style.rst <sp_codingstyle>` hasta +cierto punto y está escrito principalmente para evitar responder a [#f1]_ +las mismas preguntas (o similares) una y otra vez. + +El estilo de gestión es muy personal y mucho más difÃcil de cuantificar +que reglas simples de estilo de codificación, por lo que este documento +puede o no tener relación con la realidad. Comenzó como una broma, pero +eso no significa que no pueda ser realmente cierto. Tendrás que decidir +por ti mismo. + +Por cierto, cuando se hable de “gerente de kernelâ€, se refiere a las +personas lideres técnicas, no de las personas que hacen la gestión +tradicional dentro de las empresas. Si firmas pedidos de compra o tienes +alguna idea sobre el presupuesto de tu grupo, es casi seguro que no eres +un gerente de kernel. Estas sugerencias pueden o no aplicarse a usted. + +En primer lugar, sugerirÃa comprar “Seven Habits of Highly Effective +People†y NO leerlo. Quemarlo, es un gran gesto simbólico. + +.. [#f1] Este documento lo hace no tanto respondiendo a la pregunta, sino + haciendo dolorosamente obvio para el interrogador que no tenemos ni idea + de cuál es la respuesta. + +De todos modos, aquà va: + +.. _decisiones: + +1) Decisiones +------------- + +Todos piensan que los gerentes toman decisiones, y que la toma de +decisiones en importante. Cuanto más grande y dolorosa sea la decisión, +más grande debe ser el gerente para tomarla. Eso es muy profundo y obvio, +pero en realidad no es cierto. + +El nombre del partido es **evitar** tener que tomar una decisión. En +particular, si alguien te dice “elige (a) o (b), realmente necesitamos +que decidas sobre estoâ€, estas en problemas como gerente. Es mejor que +las personas a las que diriges conozcan los detalles mejor que tú, asà +que, si acuden a ti para tomar una decisión técnica, estas jodido. +Claramente no eres competente para tomar una decisión por ellos. + +(Corolario: Si las personas a las que diriges no conocen los detalles +mejor que tú, también estas jodido, aunque por una razón totalmente +diferente. Es decir, que estas en el trabajo equivocado y que **ellos** +deberÃan gestionando tu brillantez en su lugar). + +Asà que el nombre del partido es **evitar** las decisiones, al menos las +grandes y dolorosas. Tomar decisiones pequeñas y sin consecuencias está +bien, y te hace parecer que sabes lo que estás haciendo, asà que lo que +un gerente de kernel necesita hacer es convertir las decisiones grandes +y dolorosas en cosas pequeñas a los que a nadie realmente le importa. + +Ayuda darse cuenta de que la diferencia clave entre una decisión grande +y una pequeña es si puede arreglar su decisión después. Cualquier +decisión se puede hacer pequeña simplemente asegurándose siempre de que +si te equivocaste (u **estarás** equivocado), siempre puede deshacer el +daño más tarde retrocediendo. De repente, llegas a ser doblemente +gerencial por tomar **dos** decisiones intrascendentes - la equivocada +**y** la correcta. + +Y las personas incluso verán eso como un verdadero liderazgo (*tos* +mierda *tos*). + +Por lo tanto, la llave para evitar las grandes decisiones se convierte en +simplemente evitar hacer cosas que no se pueden deshacer. No te dejes +llevar a una esquina del que no puedas escapar. Una rata acorralada puede +ser peligrosa – un gerente acorralado es directamente lamentable. + +Resulta que, dado que nadie serÃa tan estúpido como para dejar que un +gerente de kernel tenga una gran responsabilidad **de todos modos**, +generalmente es bastante fácil retroceder. Dado que no vas a poder +malgastar grandes cantidades de dinero que tal vez no puedas pagar, lo +único que puedes revertir es una decisión técnica, y ahà retroceder es +muy fácil: simplemente diles a todos que fuiste un bobo incompetente, +pide disculpas y deshaz todo el trabajo inútil que hiciste trabajar a la +gente durante el año pasado. De repente, la decisión que tomaste hace un +año no era una gran decisión después de todo, ya que se podÃa deshacer +fácilmente. + +Resulta que algunas personas tienen problemas con este enfoque, por dos +razones: + + - admitir que eras un idiota es más difÃcil de lo que parece. A todos + nos gusta mantener las apariencias, y salir en público a decir que te + equivocaste a veces es muy duro. + - que alguien te diga que lo que trabajaste durante el último año no + valió la pena después de todo también puede ser duro para los pobres + ingenieros humildes, y aunque el **trabajo** real fue bastante fácil + de deshacer simplemente eliminándolo, es posible que hayas perdido + irrevocablemente la confianza de ese ingeniero. Y recuerda: + “irrevocablemente†fue lo que tratamos de evitar en primer lugar, y + tu decisión terminó siendo muy grande después de todo. + +Afortunadamente, estas dos razones pueden mitigarse eficazmente +simplemente admitiendo inicialmente que no tienes ni idea, y diciéndole +a la gente que tu decisión es puramente preliminar, y podrÃa ser la cosa +equivocada. Siempre te debes reservar el derecho de cambiar de opinión, y +hacer que la gente sea muy **consciente** de eso. Y es mucho más fácil +admitir que eres estúpido cuando **aun** no has hecho la cosa realmente +estúpida. + +Entonces, cuando realmente resulta ser estúpido, la gente simplemente +pone los ojos y dice “Ups, otra vez noâ€. + +Esta admisión preventiva de incompetencia también podrÃa hacer que las +personas que realmente hacen el trabajo piensen dos veces sobre si vale la +pena hacerlo o no. Después de todo, si **ellos** no están seguros de si es +una buena idea, seguro que no deberÃas alentarlos prometiéndoles que lo +que trabajan será incluido. Haz que al menos lo piensen dos veces antes de +embarcarse en un gran esfuerzo. + +Recuerda: Es mejor que sepan más sobre los detalles que tú, y +generalmente ya piensan que tienen la respuesta a todo. Lo mejor que puede +hacer como gerente no es inculcar confianza, sino más bien una dosis +saludable de pensamiento crÃtico sobre lo que hacen. + +Por cierto, otra forma de evitar una decisión es quejarse lastimeramente +de “no podemos hacer ambas cosas?†y parecer lamentable. Créeme, funciona. +Si no está claro cuál enfoque es mejor, lo descubrirán. La respuesta puede +terminar siendo que ambos equipos se sientan tan frustrados por la +situación que simplemente se den por vencidos. + +Eso puede sonar como un fracaso, pero generalmente es una señal de que +habÃa algo mal con ambos proyectos, y la razón por la que las personas +involucradas no pudieron decidir fue que ambos estaban equivocados. +Terminas oliendo a rosas y evitaste otra decisión que podrÃas haber +metido la pata. + +2) Gente +-------- + +La mayorÃa de las personas son idiotas, y ser gerente significa que +tendrás que lidiar con eso, y quizás lo más importante, que **ellos** +tienen que lidiar **contigo**. + +Resulta que, si bien es fácil deshacer los errores técnicos, no es tan +fácil deshacer los trastornos de personalidad. Solo tienes que vivir +con los suyos - y el tuyo. + +Sin embargo, para prepararse como gerente del kernel, es mejor recordar +no quemar ningún puente, bombardear a ningún aldeano inocente o alienar +a demasiados desarrolladores del kernel. Resulta que alienar a las +personas es bastante fácil, y desalienarlas es difÃcil. Por lo tanto, +“alienar†cae inmediatamente debajo del tÃtulo “no reversibleâ€, y se +convierte en un no-no según :ref:`decisiones`. + +Aquà solo hay algunas reglas simples: + + (1) No llames a la gente pen*ejos (al menos no en público) + (2) Aprende a disculparte cuando olvidaste la regla (1) + +El problema con #1 es que es muy fácil de hacer, ya que puedes decir +“eres un pen*ejo†de millones de manera diferentes [#f2]_, a veces sin +siquiera darte cuenta, y casi siempre con una convicción ardiente de que +tienes razón. + +Y cuanto más convencido estés de que tienes razón (y seamos sinceros, +puedes llamar a casi **cualquiera** un pen*ejo, y a menudo **tendrás** +razón), más difÃcil termina siendo disculparse después. + +Para resolver este problema, realmente solo tienes dos opciones: + + - Se muy buenos en las disculpas. + - Difunde el “amor†de manera tan uniforme que nadie termina sintiendo + que es atacado injustamente. Hazlo lo suficientemente ingenioso, e + incluso podrÃa divertirse. + +La opción de ser infaliblemente educado realmente no existe. Nadie +confiará en alguien que está ocultando tan claramente su verdadero +carácter. + +.. [#f2] Paul Simon cantó “Cincuenta maneras de dejar a tu amante†porque, + francamente, “Un millón de maneras de decirle a un desarrollador que es + un pen*ejo†no escanea tan bien. Pero estoy seguro de que lo pensó. + +3) Gente II – el Buen Tipo +-------------------------- + +Aunque resulta que la mayorÃa de las personas son idiotas, el corolario +de eso es, tristemente, que tú también seas uno, y aunque todos podemos +disfrutar del conocimiento seguro de que somos mejores que la persona +promedio (somos realistas, nadie cree que nunca que son promedio o debajo +del promedio), también debemos admitir que no somos el cuchillo más +afilado alrededor, y habrá otras personas que son menos idiotas que tú. + +Algunas personas reaccionan mal a las personas inteligentes. Otras se +aprovechan de ellos. + +Asegúrate de que tú, como mantenedor del kernel, estás en el segundo +grupo. Aguanta con ellos, porque son las personas que te facilitarán el +trabajo. En particular, podrán tomar tus decisiones por ti, que es de lo +que se trata el juego. + +Asà que cuando encuentras a alguien más inteligente que tú, simplemente +sigue adelante. Sus responsabilidades de gestión se convierten en gran +medida en las de decir “Suena como una buena idea, - hazlo sin +restriccionesâ€, o “Eso suena bien, pero ¿qué pasa con xxx?". La segunda +versión en particular es una excelente manera de aprender algo nuevo +sobre “xxx†o parecer **extra** gerencial al señalar algo que la persona +más inteligente no habÃa pensado. En cualquier caso, sales ganando. + +Una cosa para tener en cuenta es darse cuenta de que la grandeza en un +área no necesariamente se traduce en otras áreas. Asà que puedes impulsar +a la gente en direcciones especÃficas, pero seamos realistas, pueden ser +buenos en lo que hacen, y ser malos en todo lo demás. La buena noticia es +que las personas tienden a gravitar naturalmente hacia lo que son buenos, +por lo que no es como si estuvieras haciendo algo irreversible cuando los +impulsas en alguna dirección, simplemente no presiones demasiado. + +4) Colocar la culpa +------------------- + +Las cosas saldrán mal, y la gente quiere culpar a alguien. Etiqueta, tú +lo eres. + +En realidad, no es tan difÃcil aceptar la culpa, especialmente si la gente +se da cuenta de que no fue **toda** tu culpa. Lo que nos lleva a la mejor +manera de asumir la culpa: hacerlo por otra persona. Te sentirás bien por +asumir la caÃda, ellos se sentirán bien por no ser culpados, y la persona +que perdió toda su colección de pornografÃa de 36 GB debido a tu +incompetencia admitirá a regañadientes que al menos intentaste escapar +de ella. + +Luego haz que el desarrollador que realmente metió la pata (si puedes +encontrarlo) sepa **en privado** que metió la pata. No solo para que +pueda evitarlo en futuro, sino para que sepan que te deben uno. Y, quizás +aún más importante, también es probable que sea la persona que puede +solucionarlo. Porque, seamos sinceros, seguro que no eres tú. + +Asumir la culpa también es la razón por la que llegas a ser un gerente +en primer lugar. Es parte de lo que hace que la gente confÃe en ti y te +permita la gloria potencial porque eres tú quien puede decir “metà la +pataâ€. Y si has seguido las reglas anteriores, ya serás bastante bueno +para decir eso. + +5) Cosas que evitar +------------------- + +Hay una cosa que la gente odia incluso más que ser llamado “pen*ejoâ€, +y que es ser llamado “pen*ejo†en una voz mojigata. Por lo primero, +puedes disculparte, por lo segundo, realmente, no tendrás la oportunidad. +Es probable que ya no estén escuchando, incluso si de lo contrario haces +un buen trabajo. + +Todos pensamos que somos mejores que los demás, lo que significa que +cuando alguien más se da aires, **realmente** nos molesta. Puedes ser +moral e intelectualmente superior a todos los que te rodean, pero no +trates de hacerlo demasiado obvio a menos que tengas **la intención** +real de irritar a alguien [#f3]_. + +Del mismo modo, no seas demasiado educado o sutil acerca de las cosas. La +cortesÃa fácilmente termina yendo demasiado lejos y ocultado el problema, +y como dicen “En internet, nadie puede oÃrte ser sutilâ€. Usa un gran +objeto contundente para enfatizar el punto, porque realmente no puedes +depender de que las personas entiendan tu punto de otra manera. + +Un poco de humor puede ayudar a suavizar tanto la franqueza como la +moralización. Exagerar hasta el punto de ser ridÃculo puede reforzar un +punto sin hacer que sea doloroso para el destinatario, quien simplemente +piensa que estas siendo tonto. Por lo tanto, puede ayudarnos a superar el +bloqueo mental personal que todos tenemos sobre la crÃtica. + +.. [#f3] La pista: Los grupos de noticias de Internet que no están + directamente relacionados con tu trabajo son excelentes maneras de + desahogar tus frustraciones con otras personas. Escribe mensajes + insultantes con una mueca de desprecio solo para entrar en un humor de + vez en cuando, y te sentirás limpio. Eso sÃ, no te cagues demasiado + cerca de casa. + +6) ¿Por qué a mÃ? +----------------- + +Dado que tu principal responsabilidad parece ser asumir la culpa de los +errores de otras personas y hacer dolorosamente obvio para todos los +demás que eres incompetente, la pregunta obvia es: ¿por qué hacerlo en +primer lugar? + +Pase lo que pase, **tendrás** una sensación inmensa de logro personal por +estar “a cargoâ€. No importa el hecho de que realmente estés liderando al +tratar de mantenerte al dÃa con todos los demás y correr detrás de ellos +lo más rápido que puedes. Todo el mundo seguirá pensando que eres la +persona a cargo. + +Es un gran trabajo si puedes descifrarlo. diff --git a/Documentation/translations/sp_SP/process/submit-checklist.rst b/Documentation/translations/sp_SP/process/submit-checklist.rst new file mode 100644 index 000000000000..0d6651f9d871 --- /dev/null +++ b/Documentation/translations/sp_SP/process/submit-checklist.rst @@ -0,0 +1,133 @@ +.. include:: ../disclaimer-sp.rst + +:Original: Documentation/process/submit-checklist.rst +:Translator: Avadhut Naik <avadhut.naik@amd.com> + +.. _sp_submitchecklist: + +Lista de comprobación para enviar parches del kernel de Linux +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Aquà hay algunas cosas básicas que los desarrolladores deben hacer si +quieren que sus envÃos de parches del kernel sean aceptados más +rápidamente. + +Todo esto está más allá de la documentación que se proporciona en +:ref:`Documentation/translations/sp_SP/process/submitting-patches.rst <sp_submittingpatches>` +y en otros lugares con respecto al envÃo de parches del kernel de Linux. + +1) Si utiliza una funcionalidad, #include el archivo que define/declara + esa funcionalidad. No dependa de otros archivos de encabezado que + extraigan los que utiliza. + +2) Compile limpiamente: + + a) Con las opciones ``CONFIG`` aplicables o modificadas ``=y``, ``=m``, + y ``=n``. Sin advertencias/errores del compilador ``gcc``, ni + advertencias/errores del linker. + + b) Aprobar ``allnoconfig``, ``allmodconfig`` + + c) Compila correctamente cuando se usa ``O=builddir`` + + d) Cualquier documentación o cambios se compilan correctamente sin + nuevas advertencias/errores. Utilice ``make htmldocs`` o + ``make pdfdocs`` para comprobar la compilación y corregir cualquier + problema. + +3) Se compila en varias arquitecturas de CPU mediante herramientas de + compilación cruzada locales o alguna otra granja de compilación. + +4) ppc64 es una buena arquitectura para verificar la compilación cruzada + por que tiende a usar ``unsigned long`` para cantidades de 64-bits. + +5) Verifique su parche para el estilo general según se detalla en + :ref:`Documentation/translations/sp_SP/process/coding-style.rst <sp_codingstyle>`. + Verifique las infracciones triviales con el verificador de estilo de + parches antes de la entrega (``scripts/checkpatch.pl``). + DeberÃa ser capaz de justificar todas las infracciones que permanezcan + en su parche. + +6) Cualquier opción ``CONFIG`` nueva o modificada no altera el menú de + configuración y se desactiva por defecto, a menos que cumpla con los + criterios de excepción documentados en + ``Documentation/kbuild/kconfig-language.rst`` Atributos del menú: valor por defecto. + +7) Todas las nuevas opciones de ``Kconfig`` tienen texto de ayuda. + +8) Ha sido revisado cuidadosamente con respecto a las combinaciones + relevantes de ``Kconfig``. Esto es muy difÃcil de hacer correctamente + con las pruebas -- la concentración mental da resultados aquÃ. + +9) Verifique limpiamente con sparse. + +10) Use ``make checkstack`` y solucione cualquier problema que encuentre. + + .. note:: + + ``checkstack`` no señala los problemas explÃcitamente, pero + cualquier función que use más de 512 bytes en la pila es + candidata para el cambio. + +11) Incluya :ref:`kernel-doc <kernel_doc>` para documentar las API + globales del kernel. (No es necesario para funciones estáticas, pero + también está bien.) Utilice ``make htmldocs`` o ``make pdfdocs`` + para comprobar el :ref:`kernel-doc <kernel_doc>` y solucionar + cualquier problema. + +12) Ha sido probado con ``CONFIG_PREEMPT``, ``CONFIG_DEBUG_PREEMPT``, + ``CONFIG_DEBUG_SLAB``, ``CONFIG_DEBUG_PAGEALLOC``, ``CONFIG_DEBUG_MUTEXES``, + ``CONFIG_DEBUG_SPINLOCK``, ``CONFIG_DEBUG_ATOMIC_SLEEP`` + ``CONFIG_PROVE_RCU`` y ``CONFIG_DEBUG_OBJECTS_RCU_HEAD`` todos + habilitados simultáneamente. + +13) Ha sido probado en tiempo de compilación y ejecución con y sin + ``CONFIG_SMP`` y ``CONFIG_PREEMPT``. + +14) Todas las rutas de código se han ejercido con todas las + caracterÃsticas de lockdep habilitadas. + +15) Todas las nuevas entradas de ``/proc`` están documentadas en + ``Documentation/``. + +16) Todos los nuevos parámetros de arranque del kernel están documentados + en ``Documentation/admin-guide/kernel-parameters.rst``. + +17) Todos los nuevos parámetros del módulo están documentados con + ``MODULE_PARM_DESC()``. + +18) Todas las nuevas interfaces de espacio de usuario están documentadas + en ``Documentation/ABI/``. Consulte ``Documentation/ABI/README`` para + obtener más información. Los parches que cambian las interfaces del + espacio de usuario deben ser CCed a linux-api@vger.kernel.org. + +19) Se ha comprobado con la inyección de al menos errores de asignación + de slab y página. Consulte ``Documentation/fault-injection/``. + + Si el nuevo código es sustancial, la adición de la inyección de + errores especÃfica del subsistema podrÃa ser apropiada. + +20) El nuevo código añadido ha sido compilado con ``gcc -W`` (use + ``make KCFLAGS=-W``). Esto generara mucho ruido per es buena para + encontrar errores como "warning: comparison between signed and unsigned". + +21) Se prueba después de que se haya fusionado en el conjunto de + parches -mm para asegurarse de que siga funcionando con todos los + demás parches en cola y varios cambios en VM, VFS y otros subsistemas. + +22) Todas las barreras de memoria {p.ej., ``barrier()``, ``rmb()``, + ``wmb()``} necesitan un comentario en el código fuente que explique + la lógica de lo que están haciendo y por qué. + +23) Si se añaden algún ioctl en el parche, actualice también + ``Documentation/userspace-api/ioctl/ioctl-number.rst``. + +24) Si su código fuente modificado depende o utiliza cualquiera de las + API o caracterÃsticas del kernel que están relacionadas con los + siguientes sÃmbolos ``Kconfig`` entonces pruebe varias compilaciones + con los sÃmbolos ``Kconfig`` relacionados deshabilitados y/o ``=m`` + (si esa opción esta disponible) [no todos estos al mismo tiempo, solo + varias/aleatorias combinaciones de ellos]: + + ``CONFIG_SMP``, ``CONFIG_SYSFS``, ``CONFIG_PROC_FS``, ``CONFIG_INPUT``, ``CONFIG_PCI``, ``CONFIG_BLOCK``, ``CONFIG_PM``, ``CONFIG_MAGIC_SYSRQ`` + ``CONFIG_NET``, ``CONFIG_INET=n`` (pero luego con ``CONFIG_NET=y``). diff --git a/Documentation/translations/zh_CN/arch/riscv/boot.rst b/Documentation/translations/zh_CN/arch/riscv/boot.rst new file mode 100644 index 000000000000..0c2619095819 --- /dev/null +++ b/Documentation/translations/zh_CN/arch/riscv/boot.rst @@ -0,0 +1,155 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. include:: ../../disclaimer-zh_CN.rst + +:Original: Documentation/arch/riscv/boot.rst + +:翻译: + + 龙进 Jin Long <longjin@dragonos.org> + +======================== +RISC-Vå†…æ ¸å¯åŠ¨è¦æ±‚å’Œé™åˆ¶ +======================== + +:Author: Alexandre Ghiti <alexghiti@rivosinc.com> +:Date: 23 May 2023 + +这份文档æ述了RISC-Vå†…æ ¸å¯¹å¼•å¯¼åŠ è½½ç¨‹åºå’Œå›ºä»¶çš„期望，以åŠä»»ä½•å¼€å‘者在接触 +早期å¯åŠ¨è¿‡ç¨‹æ—¶å¿…须牢记的约æŸã€‚在这份文档ä¸ï¼Œ ``早期å¯åŠ¨è¿‡ç¨‹`` 指的是在最 +ç»ˆè™šæ‹Ÿæ˜ å°„è®¾ç½®ä¹‹å‰è¿è¡Œçš„任何代ç 。 + +å†…æ ¸é¢„åŠ è½½çš„è¦æ±‚å’Œé™åˆ¶ +====================== + +RISC-Vå†…æ ¸å¯¹å¼•å¯¼åŠ è½½ç¨‹åºå’Œå¹³å°å›ºä»¶æœ‰ä»¥ä¸‹è¦æ±‚： + +寄å˜å™¨çŠ¶æ€ +---------- + +RISC-Vå†…æ ¸æœŸæœ›ï¼š + + * ``$a0`` 应包å«å½“å‰æ ¸å¿ƒçš„hartid。 + * ``$a1`` 应包å«å†…å˜ä¸è®¾å¤‡æ ‘的地å€ã€‚ + +CSR 寄å˜å™¨çŠ¶æ€ +-------------- + +RISC-Vå†…æ ¸æœŸæœ›ï¼š + + * ``$satp = 0``： 如果å˜åœ¨MMU，必须将其ç¦ç”¨ã€‚ + +为常驻固件ä¿ç•™çš„å†…å˜ +-------------------- + +RISC-Vå†…æ ¸åœ¨ç›´æŽ¥æ˜ å°„ä¸ä¸èƒ½æ˜ 射任何常驻内å˜æˆ–用PMPsä¿æŠ¤çš„内å˜ï¼Œ +å› æ¤å›ºä»¶å¿…é¡»æ ¹æ®è®¾å¤‡æ ‘规范 å’Œ/或 UEFI规范æ£ç¡®æ ‡è®°è¿™äº›åŒºåŸŸã€‚ + +å†…æ ¸çš„ä½ç½® +---------- + +RISC-Vå†…æ ¸æœŸæœ›è¢«æ”¾ç½®åœ¨PMD边界（对于rv64为2MB对é½ï¼Œå¯¹äºŽrv32为4MB对é½ï¼‰ã€‚ +请注æ„，如果ä¸æ˜¯è¿™æ ·ï¼ŒEFI stub å°†é‡å®šä½å†…æ ¸ã€‚ + +硬件æè¿° +-------- + +固件å¯ä»¥å°†è®¾å¤‡æ ‘或ACPIè¡¨ä¼ é€’ç»™RISC-Vå†…æ ¸ã€‚ + +è®¾å¤‡æ ‘å¯ä»¥ç›´æŽ¥ä»Žå‰ä¸€é˜¶æ®µé€šè¿‡$a1寄å˜å™¨ä¼ é€’ç»™å†…æ ¸ï¼Œæˆ–è€…åœ¨ä½¿ç”¨UEFIå¯åŠ¨æ—¶ï¼Œ +å¯ä»¥é€šè¿‡EFIé…ç½®è¡¨ä¼ é€’ã€‚ + +ACPI表通过EFIé…ç½®è¡¨ä¼ é€’ç»™å†…æ ¸ã€‚åœ¨è¿™ç§æƒ…况下，EFI stub ä»ç„¶ä¼šåˆ›å»ºä¸€ä¸ª +å°çš„è®¾å¤‡æ ‘ã€‚è¯·å‚阅下é¢çš„"EFI stub å’Œè®¾å¤‡æ ‘"éƒ¨åˆ†ï¼Œäº†è§£è¿™ä¸ªè®¾å¤‡æ ‘çš„è¯¦ç»† +ä¿¡æ¯ã€‚ + +å†…æ ¸å…¥å£ +-------- + +在SMP系统ä¸ï¼Œæœ‰ä¸¤ç§æ–¹æ³•å¯ä»¥è¿›å…¥å†…æ ¸ï¼š + +- ``RISCV_BOOT_SPINWAIT``ï¼šå›ºä»¶åœ¨å†…æ ¸ä¸é‡Šæ”¾æ‰€æœ‰çš„hart，一个hartèµ¢ + 得抽奖并执行早期å¯åŠ¨ä»£ç ，而其他的hart则åœåœ¨é‚£é‡Œç‰å¾…åˆå§‹åŒ–完æˆã€‚è¿™ç§ + 方法主è¦ç”¨äºŽæ”¯æŒæ²¡æœ‰SBI HSM扩展和M模å¼RISC-Vå†…æ ¸çš„æ—§å›ºä»¶ã€‚ +- ``有åºå¯åŠ¨``：固件åªé‡Šæ”¾ä¸€ä¸ªå°†æ‰§è¡Œåˆå§‹åŒ–阶段的hart，然åŽä½¿ç”¨SBI HSM + 扩展å¯åŠ¨æ‰€æœ‰å…¶ä»–çš„hart。有åºå¯åŠ¨æ–¹æ³•æ˜¯å¯åŠ¨RISC-Vå†…æ ¸çš„é¦–é€‰å¯åŠ¨æ–¹æ³•ï¼Œ + å› ä¸ºå®ƒå¯ä»¥æ”¯æŒCPUçƒæ’拔和kexec。 + +UEFI +---- + +UEFI 内å˜æ˜ å°„ +~~~~~~~~~~~~~ + +使用UEFIå¯åŠ¨æ—¶ï¼ŒRISC-Vå†…æ ¸å°†åªä½¿ç”¨EFI内å˜æ˜ å°„æ¥å¡«å……系统内å˜ã€‚ + +UEFIå›ºä»¶å¿…é¡»è§£æž ``/reserved-memory`` è®¾å¤‡æ ‘èŠ‚ç‚¹çš„å节点，并éµå®ˆè®¾å¤‡ +æ ‘è§„èŒƒï¼Œå°†è¿™äº›å节点的属性（ ``no-map`` å’Œ ``reusable`` ）转æ¢ä¸ºå…¶æ£ +确的EFIç‰ä»·ç‰©ï¼ˆå‚è§è®¾å¤‡æ ‘规范v0.4-rc1çš„"3.5.4/reserved-memoryå’Œ +UEFI"部分）。 + +RISCV_EFI_BOOT_PROTOCOL +~~~~~~~~~~~~~~~~~~~~~~~ + +使用UEFIå¯åŠ¨æ—¶ï¼ŒEFI stub 需è¦å¼•å¯¼hartidä»¥ä¾¿å°†å…¶ä¼ é€’ç»™ ``$a1`` ä¸çš„ +RISC-Vå†…æ ¸ã€‚EFI stub使用以下方法之一获å–引导hartid： + +- ``RISCV_EFI_BOOT_PROTOCOL`` （**首选**）。 +- ``boot-hartid`` è®¾å¤‡æ ‘å节点（**已弃用**）。 + +任何新的固件都必须实现 ``RISCV_EFI_BOOT_PROTOCOL``ï¼Œå› ä¸ºåŸºäºŽè®¾å¤‡æ ‘ +的方法现已被弃用。 + +早期å¯åŠ¨çš„è¦æ±‚å’Œçº¦æŸ +==================== + +RISC-Vå†…æ ¸çš„æ—©æœŸå¯åŠ¨è¿‡ç¨‹éµå¾ªä»¥ä¸‹çº¦æŸï¼š + +EFI stub å’Œè®¾å¤‡æ ‘ +----------------- + +使用UEFIå¯åŠ¨æ—¶ï¼ŒEFI stub 会用与arm64相åŒçš„å‚æ•°è¡¥å……ï¼ˆæˆ–åˆ›å»ºï¼‰è®¾å¤‡æ ‘ï¼Œ +这些å‚数在Documentation/arch/arm/uefi.rstä¸çš„ +"UEFI kernel supporton ARM"段è½ä¸æœ‰æ述。 + +è™šæ‹Ÿæ˜ å°„å®‰è£… +------------ + +在RISC-Vå†…æ ¸ä¸ï¼Œè™šæ‹Ÿæ˜ 射的安装分为两æ¥è¿›è¡Œï¼š + +1. ``setup_vm()`` 在 ``early_pg_dir`` ä¸å®‰è£…ä¸€ä¸ªä¸´æ—¶çš„å†…æ ¸æ˜ å°„ï¼Œè¿™ + å…许å‘现系统内å˜ã€‚ æ¤æ—¶åªæœ‰å†…æ ¸æ–‡æœ¬/æ•°æ®è¢«æ˜ å°„ã€‚åœ¨å»ºç«‹è¿™ä¸ªæ˜ å°„æ—¶ï¼Œ + ä¸èƒ½è¿›è¡Œåˆ†é…ï¼ˆå› ä¸ºç³»ç»Ÿå†…å˜è¿˜æœªçŸ¥ï¼‰ï¼Œæ‰€ä»¥``early_pg_dir``é¡µè¡¨æ˜¯é™ + æ€åˆ†é…的（æ¯ä¸ªçº§åˆ«åªä½¿ç”¨ä¸€ä¸ªè¡¨ï¼‰ã€‚ + +2. ``setup_vm_final()`` 在 ``swapper_pg_dir`` ä¸åˆ›å»ºæœ€ç»ˆçš„å†…æ ¸æ˜ + 射，并利用å‘çŽ°çš„ç³»ç»Ÿå†…å˜ åˆ›å»ºçº¿æ€§æ˜ å°„ã€‚åœ¨å»ºç«‹è¿™ä¸ªæ˜ å°„æ—¶ï¼Œå†…æ ¸å¯ä»¥ + 分é…内å˜ï¼Œä½†ä¸èƒ½ç›´æŽ¥è®¿é—®å®ƒï¼ˆå› ä¸ºç›´æŽ¥æ˜ å°„è¿˜ä¸å˜åœ¨ï¼‰ï¼Œæ‰€ä»¥å®ƒä½¿ç”¨fixmap + åŒºåŸŸçš„ä¸´æ—¶æ˜ å°„æ¥è®¿é—®æ–°åˆ†é…的页表级别。 + +为了让 ``virt_to_phys()`` å’Œ ``phys_to_virt()`` 能够æ£ç¡®åœ°å°†ç›´æŽ¥ +æ˜ å°„åœ°å€è½¬æ¢ä¸ºç‰©ç†åœ°å€ï¼Œå®ƒä»¬éœ€è¦çŸ¥é“DRAM的起始ä½ç½®ã€‚è¿™å‘生在æ¥éª¤1之åŽï¼Œ +就在æ¥éª¤2å®‰è£…ç›´æŽ¥æ˜ å°„ä¹‹å‰ï¼ˆå‚è§arch/riscv/mm/init.cä¸çš„ +``setup_bootmem()`` å‡½æ•°ï¼‰ã€‚åœ¨å®‰è£…æœ€ç»ˆè™šæ‹Ÿæ˜ å°„ä¹‹å‰ä½¿ç”¨è¿™äº›å®æ—¶å¿…é¡» +仔细检查。 + +通过fixmapè¿›è¡Œè®¾å¤‡æ ‘æ˜ å°„ +------------------------ + +由于 ``reserved_mem`` 数组是用 ``setup_vm()`` 建立的虚拟地å€åˆå§‹åŒ– +的，并且与``setup_vm_final()``å»ºç«‹çš„æ˜ å°„ä¸€èµ·ä½¿ç”¨ï¼ŒRISC-Vå†…æ ¸ä½¿ç”¨ +fixmap区域æ¥æ˜ å°„è®¾å¤‡æ ‘ã€‚è¿™ç¡®ä¿è®¾å¤‡æ ‘å¯ä»¥é€šè¿‡ä¸¤ç§è™šæ‹Ÿæ˜ 射访问。 + +Pre-MMU执行 +----------- + +åœ¨å»ºç«‹ç¬¬ä¸€ä¸ªè™šæ‹Ÿæ˜ å°„ä¹‹å‰ï¼Œéœ€è¦è¿è¡Œä¸€äº›ä»£ç ã€‚è¿™äº›åŒ…æ‹¬ç¬¬ä¸€ä¸ªè™šæ‹Ÿæ˜ å°„çš„å®‰è£…æœ¬èº«ï¼Œ +早期替代方案的修补，以åŠå†…æ ¸å‘½ä»¤è¡Œçš„æ—©æœŸè§£æžã€‚这些代ç å¿…é¡»éžå¸¸å°å¿ƒåœ°ç¼–è¯‘ï¼Œå› ä¸ºï¼š + +- ``-fno-pie``：这对于使用``-fPIE``çš„å¯é‡å®šä½å†…æ ¸æ˜¯å¿…éœ€çš„ï¼Œå¦åˆ™ï¼Œä»»ä½•å¯¹ + 全局符å·çš„访问都将通过 GOT进行，而GOTåªæ˜¯è™šæ‹Ÿåœ°é‡æ–°å®šä½ã€‚ +- ``-mcmodel=medany``：任何对全局符å·çš„访问都必须是PC相对的，以é¿å…在设 + ç½®MMU之å‰å‘生任何é‡å®šä½ã€‚ +- *所有* 的仪表化功能也必须被ç¦ç”¨ï¼ˆåŒ…括KASAN，ftrace和其他）。 + +由于使用æ¥è‡ªä¸åŒç¼–译å•å…ƒçš„符å·éœ€è¦ç”¨è¿™äº›æ ‡å¿—编译该å•å…ƒï¼Œæˆ‘们建议尽å¯èƒ½ä¸è¦ä½¿ç”¨ +外部符å·ã€‚ diff --git a/Documentation/translations/zh_CN/arch/riscv/index.rst b/Documentation/translations/zh_CN/arch/riscv/index.rst index 3b041c116169..96573459105e 100644 --- a/Documentation/translations/zh_CN/arch/riscv/index.rst +++ b/Documentation/translations/zh_CN/arch/riscv/index.rst @@ -17,6 +17,7 @@ RISC-V 体系结构 .. toctree:: :maxdepth: 1 + boot boot-image-header vm-layout patch-acceptance diff --git a/Documentation/translations/zh_CN/core-api/printk-basics.rst b/Documentation/translations/zh_CN/core-api/printk-basics.rst index 59c6efb3fc41..cafa01bccff2 100644 --- a/Documentation/translations/zh_CN/core-api/printk-basics.rst +++ b/Documentation/translations/zh_CN/core-api/printk-basics.rst @@ -100,7 +100,7 @@ printk()çš„ç”¨æ³•é€šå¸¸æ˜¯è¿™æ ·çš„:: 为了调试，还有两个有æ¡ä»¶ç¼–译的å®ï¼š pr_debug()å’Œpr_devel()，除éžå®šä¹‰äº† ``DEBUG`` (或者在pr_debug()的情况下定义了 -``CONFIG_DYNAMIC_DEBUG`` )，å¦åˆ™å®ƒä»¬ä¼šè¢«ç¼–译。 +``CONFIG_DYNAMIC_DEBUG`` )，å¦åˆ™å®ƒä»¬ä¸ä¼šè¢«ç¼–译。 å‡½æ•°æŽ¥å£ diff --git a/Documentation/translations/zh_CN/dev-tools/index.rst b/Documentation/translations/zh_CN/dev-tools/index.rst index 02577c379007..c2db3e566b1b 100644 --- a/Documentation/translations/zh_CN/dev-tools/index.rst +++ b/Documentation/translations/zh_CN/dev-tools/index.rst @@ -14,11 +14,8 @@ 有关测试专用工具的简è¦æ¦‚述，å‚è§ Documentation/translations/zh_CN/dev-tools/testing-overview.rst -.. class:: toc-title - - 目录 - .. toctree:: + :caption: 目录 :maxdepth: 2 testing-overview diff --git a/Documentation/translations/zh_CN/dev-tools/testing-overview.rst b/Documentation/translations/zh_CN/dev-tools/testing-overview.rst index 69e7e4cb2002..c91f9b60f9f1 100644 --- a/Documentation/translations/zh_CN/dev-tools/testing-overview.rst +++ b/Documentation/translations/zh_CN/dev-tools/testing-overview.rst @@ -3,7 +3,7 @@ .. include:: ../disclaimer-zh_CN.rst :Original: Documentation/dev-tools/testing-overview.rst -:Translator: 胡皓文 Hu Haowen <src.res.211@gmail.com> +:Translator: 胡皓文 Hu Haowen <2023002089@link.tyut.edu.cn> ============ å†…æ ¸æµ‹è¯•æŒ‡å— diff --git a/Documentation/translations/zh_CN/driver-api/gpio/index.rst b/Documentation/translations/zh_CN/driver-api/gpio/index.rst index 9ab64e94aced..9a6a14162a6c 100644 --- a/Documentation/translations/zh_CN/driver-api/gpio/index.rst +++ b/Documentation/translations/zh_CN/driver-api/gpio/index.rst @@ -14,9 +14,8 @@ 通用型输入/输出（GPIO） ======================= -目录: - .. toctree:: + :caption: 目录 :maxdepth: 2 legacy diff --git a/Documentation/translations/zh_CN/driver-api/index.rst b/Documentation/translations/zh_CN/driver-api/index.rst index ba354e1f4e6d..92ff1b7fc3d3 100644 --- a/Documentation/translations/zh_CN/driver-api/index.rst +++ b/Documentation/translations/zh_CN/driver-api/index.rst @@ -17,11 +17,8 @@ Linux驱动实现者的APIæŒ‡å— å†…æ ¸æ供了å„ç§å„æ ·çš„æŽ¥å£æ¥æ”¯æŒè®¾å¤‡é©±åŠ¨çš„å¼€å‘。这份文档åªæ˜¯å¯¹å…¶ä¸ä¸€äº›æŽ¥å£è¿›è¡Œäº† 一定程度的整ç†â€”—希望éšç€æ—¶é—´çš„推移，它能å˜å¾—更好ï¼å¯ç”¨çš„å°èŠ‚å¯ä»¥åœ¨ä¸‹é¢çœ‹åˆ°ã€‚ -.. class:: toc-title - - 目录列表： - .. toctree:: + :caption: 目录列表 :maxdepth: 2 gpio/index diff --git a/Documentation/translations/zh_CN/process/development-process.rst b/Documentation/translations/zh_CN/process/development-process.rst index 30cffe66c075..c10d8e2e21eb 100644 --- a/Documentation/translations/zh_CN/process/development-process.rst +++ b/Documentation/translations/zh_CN/process/development-process.rst @@ -8,9 +8,10 @@ å†…æ ¸å¼€å‘è¿‡ç¨‹æŒ‡å— ================ -内容: +本文档的目的是帮助开å‘人员（åŠå…¶ç»ç†ï¼‰ä»¥æœ€å°çš„挫折感与开å‘社区åˆä½œã€‚它试图记录这个社区如何以一ç§ä¸ç†Ÿæ‚‰Linuxå†…æ ¸å¼€å‘（或者实际上是自由软件开å‘）的人å¯ä»¥è®¿é—®çš„æ–¹å¼å·¥ä½œã€‚虽然这里有一些技术资料，但这是一个é¢å‘过程的讨论，ä¸éœ€è¦æ·±å…¥äº†è§£å†…æ ¸ç¼–ç¨‹å°±å¯ä»¥ç†è§£ã€‚ .. toctree:: + :caption: 内容 :numbered: :maxdepth: 2 @@ -22,5 +23,3 @@ 6.Followthrough 7.AdvancedTopics 8.Conclusion - -本文档的目的是帮助开å‘人员（åŠå…¶ç»ç†ï¼‰ä»¥æœ€å°çš„挫折感与开å‘社区åˆä½œã€‚它试图记录这个社区如何以一ç§ä¸ç†Ÿæ‚‰Linuxå†…æ ¸å¼€å‘（或者实际上是自由软件开å‘）的人å¯ä»¥è®¿é—®çš„æ–¹å¼å·¥ä½œã€‚虽然这里有一些技术资料，但这是一个é¢å‘过程的讨论，ä¸éœ€è¦æ·±å…¥äº†è§£å†…æ ¸ç¼–ç¨‹å°±å¯ä»¥ç†è§£ã€‚ diff --git a/Documentation/translations/zh_CN/process/index.rst b/Documentation/translations/zh_CN/process/index.rst index a1a35f88f4ae..3ca02d281be0 100644 --- a/Documentation/translations/zh_CN/process/index.rst +++ b/Documentation/translations/zh_CN/process/index.rst @@ -5,10 +5,11 @@ .. include:: ../disclaimer-zh_CN.rst -:Original: :ref:`Documentation/process/index.rst <process_index>` -:Translator: Alex Shi <alex.shi@linux.alibaba.com> +:Original: Documentation/process/index.rst -.. _cn_process_index: +:翻译: + + Alex Shi <alex.shi@linux.alibaba.com> ======================== 与Linux å†…æ ¸ç¤¾åŒºä¸€èµ·å·¥ä½œ @@ -23,29 +24,55 @@ .. toctree:: :maxdepth: 1 + license-rules howto code-of-conduct code-of-conduct-interpretation + development-process submitting-patches programming-language coding-style - development-process + maintainer-pgp-guide email-clients - license-rules kernel-enforcement-statement kernel-driver-statement +TODOLIST: + +* handling-regressions +* maintainer-handbooks + +安全方é¢, 请阅读: + +.. toctree:: + :maxdepth: 1 + + embargoed-hardware-issues + +TODOLIST: + +* security-bugs + 其它大多数开å‘人员感兴趣的社区指å—： .. toctree:: :maxdepth: 1 - submit-checklist stable-api-nonsense - stable-kernel-rules management-style - embargoed-hardware-issues + stable-kernel-rules + submit-checklist + +TODOLIST: + +* changes +* kernel-docs +* deprecated +* maintainers +* researcher-guidelines +* contribution-maturity-model + 这些是一些总体性技术指å—，由于ä¸å¤§å¥½åˆ†ç±»è€Œæ”¾åœ¨è¿™é‡Œï¼š @@ -54,6 +81,16 @@ magic-number volatile-considered-harmful + ../arch/riscv/patch-acceptance + ../core-api/unaligned-memory-access + +TODOLIST: + +* applying-patches +* backporting +* adding-syscalls +* botching-up-ioctls +* clang-format .. only:: subproject and html diff --git a/Documentation/translations/zh_CN/process/magic-number.rst b/Documentation/translations/zh_CN/process/magic-number.rst index 4a92ebb619ee..4e4aeaca796c 100644 --- a/Documentation/translations/zh_CN/process/magic-number.rst +++ b/Documentation/translations/zh_CN/process/magic-number.rst @@ -1,58 +1,67 @@ -.. _cn_magicnumbers: - .. include:: ../disclaimer-zh_CN.rst -:Original: :ref:`Documentation/process/magic-number.rst <magicnumbers>` +:Original: Documentation/process/magic-number.rst + +:翻译: -如果想评论或更新本文的内容，请直接å‘信到LKMLã€‚å¦‚æžœä½ ä½¿ç”¨è‹±æ–‡äº¤æµæœ‰å›°éš¾çš„è¯ï¼Œä¹Ÿå¯ -以å‘ä¸æ–‡ç‰ˆç»´æŠ¤è€…求助。如果本翻译更新ä¸åŠæ—¶æˆ–者翻译å˜åœ¨é—®é¢˜ï¼Œè¯·è”ç³»ä¸æ–‡ç‰ˆç»´æŠ¤è€…:: + è´¾å¨å¨ Jia Wei Wei <harryxiyou@gmail.com> - ä¸æ–‡ç‰ˆç»´æŠ¤è€…： è´¾å¨å¨ Jia Wei Wei <harryxiyou@gmail.com> - ä¸æ–‡ç‰ˆç¿»è¯‘者： è´¾å¨å¨ Jia Wei Wei <harryxiyou@gmail.com> - ä¸æ–‡ç‰ˆæ ¡è¯‘者： è´¾å¨å¨ Jia Wei Wei <harryxiyou@gmail.com> +:æ ¡è¯‘: + + å¸å»¶è…¾ Yanteng Si <siyanteng@loongson.cn> Linux é”术数 ============ -这个文件是有关当å‰ä½¿ç”¨çš„é”æœ¯å€¼æ³¨å†Œè¡¨ã€‚å½“ä½ ç»™ä¸€ä¸ªç»“æž„æ·»åŠ äº†ä¸€ä¸ªé”æœ¯å€¼ï¼Œä½ ä¹Ÿåº”è¯¥æŠŠè¿™ä¸ªé”æœ¯å€¼æ·»åŠ åˆ°è¿™ä¸ªæ–‡ä»¶ï¼Œå› ä¸ºæˆ‘ä»¬æœ€å¥½æŠŠç”¨äºŽå„ç§ç»“æž„çš„é”术值统一起æ¥ã€‚ +这个文件是有关当å‰ä½¿ç”¨çš„é”æœ¯å€¼æ³¨å†Œè¡¨ã€‚å½“ä½ ç»™ä¸€ä¸ªç»“æž„ä½“æ·»åŠ äº†ä¸€ä¸ªé”æœ¯å€¼ï¼Œä½ ä¹Ÿ +应该把这个é”æœ¯å€¼æ·»åŠ åˆ°è¿™ä¸ªæ–‡ä»¶ï¼Œå› ä¸ºæˆ‘ä»¬æœ€å¥½æŠŠç”¨äºŽå„ç§ç»“构体的é”术值统一起æ¥ã€‚ -使用é”术值æ¥ä¿æŠ¤å†…æ ¸æ•°æ®ç»“构是一个éžå¸¸å¥½çš„主æ„。这就å…è®¸ä½ åœ¨è¿è¡ŒæœŸæ£€æŸ¥(a)一个结构是å¦å·²ç»è¢«æ”»å‡»ï¼Œæˆ–者(b)ä½ å·²ç»ç»™ä¸€ä¸ªä¾‹è¡Œç¨‹åºé€šè¿‡äº†ä¸€ä¸ªé”™è¯¯çš„结构。åŽä¸€ç§æƒ…况特别地有用---ç‰¹åˆ«æ˜¯å½“ä½ é€šè¿‡ä¸€ä¸ªç©ºæŒ‡é’ˆæŒ‡å‘结构体的时候。ttyæºç ，例如，ç»å¸¸é€šè¿‡ç‰¹å®šé©±åŠ¨ä½¿ç”¨è¿™ç§æ–¹æ³•å¹¶ä¸”åå¤åœ°æŽ’列特定方é¢çš„结构。 +使用é”术值æ¥ä¿æŠ¤å†…æ ¸æ•°æ®ç»“构是一个 **éžå¸¸å¥½çš„主æ„** 。这就å…è®¸ä½ åœ¨è¿è¡Œæ—¶æ£€ +查一个结构体(a)是å¦å·²ç»è¢«æ”»å‡»ï¼Œæˆ–者(b)ä½ å·²ç»ç»™ä¸€ä¸ªä¾‹ç¨‹ä¼ 递了一个错误的结构 +体。最åŽä¸€ç§æƒ…况特别地有用---ç‰¹åˆ«æ˜¯å½“ä½ é€šè¿‡ä¸€ä¸ªç©ºæŒ‡é’ˆæŒ‡å‘结构体的时候。例如， +ttyæºç ç»å¸¸é€šè¿‡ç‰¹å®šé©±åŠ¨ä½¿ç”¨è¿™ç§æ–¹æ³•ç”¨æ¥åå¤åœ°æŽ’列特定方é¢çš„结构体。 -使用é”术值的方法是在结构的开始处声明的，如下:: +使用é”术值的方法是在结构体的开头声明它们，如下:: struct tty_ldisc { int magic; ... }; -å½“ä½ ä»¥åŽç»™å†…æ ¸æ·»åŠ å¢žå¼ºåŠŸèƒ½çš„æ—¶å€™ï¼Œè¯·éµå®ˆè¿™æ¡è§„则ï¼è¿™æ ·å°±ä¼šèŠ‚çœæ•°ä¸æ¸…的调试时间，特别是一些å¤æ€ªçš„情况，例如，数组超出范围并且é‡æ–°å†™äº†è¶…出部分。éµå®ˆè¿™ä¸ªè§„则，这些情况å¯ä»¥è¢«å¿«é€Ÿåœ°ï¼Œå®‰å…¨åœ°é¿å…。 +å½“ä½ ä»¥åŽç»™å†…æ ¸æ·»åŠ å¢žå¼ºåŠŸèƒ½çš„æ—¶å€™ï¼Œè¯·éµå®ˆè¿™æ¡è§„则ï¼è¿™æ ·å°±ä¼šèŠ‚çœæ•°ä¸æ¸…的调试 +时间，特别是一些å¤æ€ªçš„情况，例如，数组超出范围并且覆盖写了超出部分。利用这 +个规则，这些情况å¯ä»¥è¢«å¿«é€Ÿåœ°ï¼Œå®‰å…¨åœ°æ£€æµ‹åˆ°è¿™äº›æ¡ˆä¾‹ã€‚ + +å˜æ›´æ—¥å¿—:: - Theodore Ts'o - 31 Mar 94 + Theodore Ts'o + 31 Mar 94 -给当å‰çš„Linux 2.1.55æ·»åŠ é”术表。 + 给当å‰çš„Linux 2.1.55æ·»åŠ é”术表。 - Michael Chastain - <mailto:mec@shout.net> - 22 Sep 1997 + Michael Chastain + <mailto:mec@shout.net> + 22 Sep 1997 -现在应该最新的Linux 2.1.112.å› ä¸ºåœ¨ç‰¹æ€§å†»ç»“æœŸé—´ï¼Œä¸èƒ½åœ¨2.2.xå‰æ”¹å˜ä»»ä½•ä¸œè¥¿ã€‚这些æ¡ç›®è¢«æ•°åŸŸæ‰€æŽ’åºã€‚ + 现在应该最新的Linux 2.1.112.å› ä¸ºåœ¨ç‰¹æ€§å†»ç»“æœŸé—´ï¼Œä¸èƒ½åœ¨2.2.xå‰æ”¹å˜ä»» + 何东西。这些æ¡ç›®è¢«æ•°åŸŸæ‰€æŽ’åºã€‚ - Krzysztof G.Baranowski - <mailto: kgb@knm.org.pl> - 29 Jul 1998 + Krzysztof G.Baranowski + <mailto: kgb@knm.org.pl> + 29 Jul 1998 -æ›´æ–°é”术表到Linux 2.5.45。刚好越过特性冻结，但是有å¯èƒ½è¿˜ä¼šæœ‰ä¸€äº›æ–°çš„é”术值在2.6.x之å‰èžå…¥åˆ°å†…æ ¸ä¸ã€‚ + æ›´æ–°é”术表到Linux 2.5.45。刚好越过特性冻结，但是有å¯èƒ½è¿˜ä¼šæœ‰ä¸€äº›æ–°çš„é” + 术值在2.6.x之å‰èžå…¥åˆ°å†…æ ¸ä¸ã€‚ - Petr Baudis - <pasky@ucw.cz> - 03 Nov 2002 + Petr Baudis + <pasky@ucw.cz> + 03 Nov 2002 -æ›´æ–°é”术表到Linux 2.5.74。 + æ›´æ–°é”术表到Linux 2.5.74。 - Fabian Frederick - <ffrederick@users.sourceforge.net> - 09 Jul 2003 + Fabian Frederick + <ffrederick@users.sourceforge.net> + 09 Jul 2003 ===================== ================ ======================== ========================================== é”术数å æ•°å— ç»“æž„ 文件 diff --git a/Documentation/translations/zh_CN/process/maintainer-pgp-guide.rst b/Documentation/translations/zh_CN/process/maintainer-pgp-guide.rst new file mode 100644 index 000000000000..eb12694a4c59 --- /dev/null +++ b/Documentation/translations/zh_CN/process/maintainer-pgp-guide.rst @@ -0,0 +1,789 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/process/maintainer-pgp-guide.rst + +:翻译: + + å¸å»¶è…¾ Yanteng Si <siyanteng@loongson.cn> + +:æ ¡è¯‘: + + +=================== +å†…æ ¸ç»´æŠ¤è€… PGP æŒ‡å— +=================== + +:作者: Konstantin Ryabitsev <konstantin@linuxfoundation.org> + +本文档é¢å‘ Linux å†…æ ¸å¼€å‘者，特别是å系统维护人员。文档ä¸å«æœ‰Linux 基金 +会å‘布的更通用的 `ä¿æŠ¤ä»£ç 完整性`_ 指å—ä¸è®¨è®ºçš„内容å集。阅读该文档，以更 +深入地讨论本指å—ä¸æ到的一些主题。 + +.. _`ä¿æŠ¤ä»£ç 完整性`: https://github.com/lfit/itpol/blob/master/protecting-code-integrity.md + +PGP 在 Linux å†…æ ¸å¼€å‘ä¸çš„作用 +============================= + +PGP æœ‰åŠ©äºŽç¡®ä¿ Linux å†…æ ¸å¼€å‘社区产出代ç 的完整性，并在较å°ç¨‹åº¦ä¸Šï¼Œé€šè¿‡ +PGP ç¾å的电å邮件交æ¢ï¼Œåœ¨å¼€å‘者之间建立å¯ä¿¡çš„交æµæ¸ é“。 + +Linux å†…æ ¸æºä»£ç 主è¦æœ‰ä¸¤ç§ï¼ˆç»´æŠ¤ï¼‰æ–¹å¼: + +- 分布å¼æºä»“库 (git) +- 定期å‘布快照 (tarballs) + +git 仓库和 tarball éƒ½å¸¦æœ‰åˆ›å»ºå®˜æ–¹å†…æ ¸ç‰ˆæœ¬çš„å†…æ ¸å¼€å‘者的 PGP ç¾å。这 +些ç¾åæä¾›äº†åŠ å¯†ä¿è¯ï¼Œå³ä¿è¯ kernel.org 或任何其他镜åƒæ供的å¯ä¸‹è½½ç‰ˆæœ¬ +与这些开å‘者在其工作站上的版本相åŒã€‚为æ¤: + +- git ä»“åº“åœ¨æ‰€æœ‰æ ‡ç¾ä¸Šæä¾› PGP ç¾å +- tarball 为所有下载æ供独立的 PGP ç¾å + +信任开å‘者，ä¸è¦ä¿¡åŸºç¡€è®¾æ–½ +-------------------------- + +自从 2011 å¹´ kernel.org æ ¸å¿ƒç³»ç»Ÿé到入侵以æ¥ï¼Œå†…æ ¸å˜æ¡£é¡¹ç›®çš„主è¦è¿è¡ŒåŽŸ +则就是å‡å®šåŸºç¡€è®¾æ–½çš„任何部分都å¯èƒ½éšæ—¶å—åˆ°å…¥ä¾µã€‚å› æ¤ï¼Œç®¡ç†å‘˜ç‰¹æ„采å–措施， +强调必须始终信任开å‘者，ä¸èƒ½ä¿¡ä»»ä»£ç æ‰˜ç®¡åŸºç¡€è®¾æ–½ï¼Œæ— è®ºåŽè€…的安全实践有多好。 + +上述指导原则æ£æ˜¯éœ€è¦æœ¬æŒ‡å—çš„åŽŸå› ã€‚å¸Œæœ›ç¡®ä¿é€šè¿‡å¯¹å¼€å‘者的信任，我们ä¸ä¼šç®€ +å•åœ°å°†æœªæ¥æ½œåœ¨å®‰å…¨äº‹ä»¶çš„责任归咎于其他人。目的是æ供一套指导开å‘者å¯ä»¥ç”¨ +æ¥åˆ›å»ºå®‰å…¨çš„工作环境并ä¿æŠ¤ç”¨äºŽå»ºç«‹ Linux å†…æ ¸æœ¬èº«å®Œæ•´æ€§çš„ PGP 密钥。 + +PGP 工具 +======== + +使用 GnuPG 2.2 或更高版本 +------------------------- + +é»˜è®¤æƒ…å†µä¸‹ï¼Œä½ çš„å‘行版应该已ç»å®‰è£…了 GnuPGï¼Œä½ åªéœ€è¦éªŒè¯ä½ 使用的是相当新的 +版本å³å¯ã€‚è¦æ£€æŸ¥ï¼Œè¯·è¿è¡Œ:: + + $ gpg --version | head -n1 + +å¦‚æžœä½ æœ‰ 2.2 æˆ–æ›´é«˜ç‰ˆæœ¬ï¼Œé‚£ä¹ˆä½ å°±å¯ä»¥å¼€å§‹äº†ã€‚å¦‚æžœä½ çš„ç‰ˆæœ¬æ—©äºŽ 2.2，则本指 +å—ä¸çš„æŸäº›å‘½ä»¤å¯èƒ½ä¸èµ·ä½œç”¨ã€‚ + +é…ç½® gpg-agent 选项 +~~~~~~~~~~~~~~~~~~~ + +GnuPG agent是一个辅助工具，æ¯å½“ä½ ä½¿ç”¨è¯¥å‘½ä»¤æ—¶ï¼Œå®ƒéƒ½ä¼šè‡ªåŠ¨å¯åŠ¨gpg，并在 +åŽå°è¿è¡Œï¼Œç›®çš„是缓å˜ç§é’¥å¯†ç ã€‚ä½ åº”è¯¥çŸ¥é“两个选项，以便调整密ç ä½•æ—¶ä»Žç¼“å˜ +过期: + +- ``default-cache-ttl`` (秒): 如果在生命周期结æŸä¹‹å‰å†æ¬¡ä½¿ç”¨ç›¸åŒçš„ + 密钥，倒计时将é‡ç½®ä¸ºå¦ä¸€æ®µæ—¶é—´ã€‚默认值为 600（10 分钟）。 +- ``max-cache-ttl`` (秒): æ— è®ºä½ è‡ªè¾“å…¥åˆå§‹å¯†ç 以æ¥å¤šä¹…使用过密钥， + 如果最大生å˜æ—¶é—´å€’计时结æŸï¼Œä½ 都必须å†æ¬¡è¾“入密ç 。默认值为 30 分钟。 + +å¦‚æžœä½ å‘现这些默认值太çŸï¼ˆæˆ–å¤ªé•¿ï¼‰ï¼Œä½ å¯ä»¥ç¼–辑 ``~/.gnupg/gpg-agent.conf`` +æ–‡ä»¶ä»¥è®¾ç½®ä½ è‡ªå·±çš„å€¼:: + + # 常规ttl设置为30分钟，最大ttl设置为2å°æ—¶ + default-cache-ttl 1800 + max-cache-ttl 7200 + +.. note:: + + ä¸éœ€è¦åœ¨ shell 会è¯å¼€å§‹æ—¶æ‰‹åŠ¨å¯åŠ¨ gpg-agentã€‚ä½ å¯èƒ½éœ€è¦æ£€æŸ¥ + rc 文件æ¥åˆ 除旧版本 GnuPG ä¸çš„æ‰€æœ‰å†…å®¹ï¼Œå› ä¸ºå®ƒå¯èƒ½ä¸å†åšæ£ç¡® + 的事情。 + +ä¿æŠ¤ä½ çš„ PGP 密钥 +================= + +本指å—å‡å®šä½ å·²ç»æ‹¥æœ‰ç”¨äºŽ Linux å†…æ ¸å¼€å‘目的的 PGP å¯†é’¥ã€‚å¦‚æžœä½ è¿˜æ²¡ +有，请å‚阅å‰é¢æ到的 "`ä¿æŠ¤ä»£ç 完整性`_" 文档，以获å–有关如何创建新 +密钥的指导。 + +å¦‚æžœä½ å½“å‰çš„密钥低于 2048 ä½ (RSA)ï¼Œä½ è¿˜åº”è¯¥åˆ›å»ºä¸€ä¸ªæ–°å¯†é’¥ã€‚ + +了解 PGP å密钥 +--------------- + +PGP 密钥很少由å•ä¸ªå¯†é’¥å¯¹ç»„æˆ - 通常它是独立å密钥的集åˆï¼Œè¿™äº›å密钥 +å¯æ ¹æ®å…¶åŠŸèƒ½ç”¨äºŽä¸åŒçš„目的，并在创建时分é…。PGP 定义了密钥å¯ä»¥å…·æœ‰çš„ +å››ç§åŠŸèƒ½: + +- **[S]** 密钥å¯ç”¨äºŽç¾å +- **[E]** 密钥å¯ç”¨äºŽåŠ 密 +- **[A]** 密钥å¯ç”¨äºŽèº«ä»½éªŒè¯ +- **[C]** 密钥å¯ç”¨äºŽéªŒè¯å…¶ä»–密钥 + +具有 **[C]** 功能的密钥通常称为“主â€å¯†é’¥ï¼Œä½†è¯¥æœ¯è¯å…·æœ‰è¯¯å¯¼æ€§ï¼Œå› 为 +它æ„味ç€å¯ä»¥ä½¿ç”¨Certify密钥æ¥ä»£æ›¿åŒä¸€é“¾ä¸Šçš„任何其他åå¯†é’¥ï¼ˆå¦‚ç‰©ç† +“主密钥â€å¯ç”¨äºŽæ‰“开为其他钥匙制作的é”）。由于情况并éžå¦‚æ¤ï¼Œæœ¬æŒ‡å—å°† +其称为“认è¯å¯†é’¥â€ä»¥é¿å…任何æ§ä¹‰ã€‚ + +充分ç†è§£ä»¥ä¸‹å†…容至关é‡è¦: + +1. 所有å项彼æ¤å®Œå…¨ç‹¬ç«‹ã€‚å¦‚æžœä½ ä¸¢å¤±äº†ç§æœ‰åå¯†é’¥ï¼Œåˆ™æ— æ³•ä»Žé“¾ä¸Šçš„ä»»ä½• + 其他ç§é’¥æ¢å¤æˆ–é‡æ–°åˆ›å»ºå®ƒã€‚ +2. 除 Certify 密钥外，å¯ä»¥æœ‰å¤šä¸ªå…·æœ‰ç›¸åŒåŠŸèƒ½çš„åå¯†é’¥ï¼ˆä¾‹å¦‚ï¼Œä½ å¯ + 以有 2 ä¸ªæœ‰æ•ˆçš„åŠ å¯†å密钥ã€3 个有效的ç¾åå密钥，但åªæœ‰ 1 个有 + 效的认è¯å密钥）。所有åå¯†é’¥éƒ½æ˜¯å®Œå…¨ç‹¬ç«‹çš„â€”â€”åŠ å¯†åˆ°ä¸€ä¸ª **[E]** + å密钥的信æ¯ï¼ˆmessagesï¼‰æ— æ³•ä½¿ç”¨ä½ å¯èƒ½æ‹¥æœ‰çš„任何其他 **[E]** + å密钥解密。 +3. å•ä¸ªå密钥å¯èƒ½å…·æœ‰å¤šç§åŠŸèƒ½ï¼ˆä¾‹å¦‚ï¼Œä½ çš„ **[C]** 密钥也å¯ä»¥æ˜¯ä½ + çš„ **[S]** 密钥）。 + +æºå¸¦ **[C]** （è¯æ˜Žï¼‰èƒ½åŠ›çš„密钥是唯一å¯ä»¥ç”¨æ¥æŒ‡ç¤ºä¸Žå…¶ä»–密钥的关系 +的密钥。仅 **[C]** 密钥å¯ç”¨äºŽ: + +- æ·»åŠ æˆ–æ’¤é”€å…·æœ‰ S/E/A 功能的其他密钥（å密钥） +- æ·»åŠ ã€æ›´æ”¹æˆ–撤销与密钥关è”的身份 (uid) +- æ·»åŠ æˆ–æ›´æ”¹å…¶æœ¬èº«æˆ–ä»»ä½•å密钥的到期日期 +- 出于信任网络的目的ç¾ç½²å…¶ä»–人的密钥 + +默认情况下，GnuPG 在生æˆæ–°å¯†é’¥æ—¶åˆ›å»ºä»¥ä¸‹å†…容: + +- 一个å密钥åŒæ—¶å…·æœ‰è®¤è¯å’Œç¾å功能 (**[SC]**) +- å…·æœ‰åŠ å¯†åŠŸèƒ½çš„å•ç‹¬å密钥 (**[E]**) + +å¦‚æžœä½ åœ¨ç”Ÿæˆå¯†é’¥æ—¶ä½¿ç”¨äº†é»˜è®¤å‚æ•°ï¼Œé‚£ä¹ˆè¿™å°±æ˜¯ä½ å°†å¾—åˆ°çš„ã€‚ä½ å¯ä»¥é€šè¿‡ +è¿è¡Œå‘½ä»¤æ¥éªŒè¯ï¼Œä¾‹å¦‚： ``gpg --list-secret-keys`` + +:: + + sec ed25519 2022-12-20 [SC] [expires: 2024-12-19] + 000000000000000000000000AAAABBBBCCCCDDDD + uid [ultimate] Alice Dev <adev@kernel.org> + ssb cv25519 2022-12-20 [E] [expires: 2024-12-19] + +在 ``sec`` 这行下é¢é•¿é•¿çš„ä¸€è¡Œå°±æ˜¯ä½ çš„å¯†é’¥æŒ‡çº¹-æ— è®ºåœ¨ä¸‹æ–‡ä»»ä½•åœ°æ–¹ +看到 ``[fpr]`` 都指的是这40个å—符。 + +ç¡®ä¿ä½ 的密ç 强度高 +------------------ + +GnuPG 在将ç§é’¥å˜å‚¨åˆ°ç£ç›˜ä¹‹å‰ä½¿ç”¨å¯†ç å¯¹å…¶è¿›è¡ŒåŠ å¯†ã€‚è¿™æ ·ï¼Œå³ä½¿ä½ çš„ +``.gnupg`` 目录全部泄露或被盗，攻击者在没有事先获å–密ç æ¥è§£å¯†çš„ +æƒ…å†µä¸‹ä¹Ÿæ— æ³•ä½¿ç”¨ä½ çš„ç§é’¥ã€‚ + +ä½ çš„ç§é’¥å—到强密ç ä¿æŠ¤æ˜¯ç»å¯¹å¿…è¦çš„。è¦è®¾ç½®æˆ–更改它，请使用:: + + $ gpg --change-passphrase [fpr] + +创建一个å•ç‹¬çš„ç¾åå密钥 +------------------------ + +æˆ‘ä»¬çš„ç›®çš„æ˜¯é€šè¿‡å°†ä½ çš„è¯ä¹¦å¯†é’¥ç§»åŠ¨åˆ°ç¦»çº¿åª’介æ¥ä¿æŠ¤å®ƒï¼Œå› æ¤å¦‚æžœä½ åª +有组åˆçš„ **[SC]** å¯†é’¥ï¼Œé‚£ä¹ˆä½ åº”è¯¥åˆ›å»ºä¸€ä¸ªå•ç‹¬çš„ç¾åå密钥:: + + $ gpg --quick-addkey [fpr] ed25519 sign + +.. note:: GnuPG ä¸çš„ ECC æ”¯æŒ + + 请注æ„ï¼Œå¦‚æžœä½ æ‰“ç®—ä½¿ç”¨ä¸æ”¯æŒ ED25519 ECC 密钥的硬件密钥，则 + 应选择“nistp256â€æˆ–“ed25519â€ã€‚请å‚阅下é¢æœ‰å…³æŽ¨è硬件设备的 + 部分。 + + +å¤‡ä»½ä½ çš„è¯ä¹¦å¯†é’¥ä»¥è¿›è¡Œç¾éš¾æ¢å¤ +------------------------------ + +ä½ çš„ PGP 密钥上æ¥è‡ªå…¶ä»–å¼€å‘者的ç¾å越多，出于ç¾éš¾æ¢å¤çš„åŽŸå› ï¼Œä½ å°±è¶Š +有ç†ç”±åˆ›å»ºä¸€ä¸ªä½äºŽæ•°å—媒体之外的备份版本。 + +创建ç§é’¥çš„å¯æ‰“å°ç¡¬æ‹·è´çš„最佳方法是使用 ``paperkey`` 为æ¤ç›®çš„编写 +çš„è½¯ä»¶ã€‚æœ‰å…³è¾“å‡ºæ ¼å¼åŠå…¶ç›¸å¯¹äºŽå…¶ä»–解决方案的优势的更多详细信æ¯ï¼Œè¯·å‚ +阅 ``paperkey`` å‚考资料。大多数å‘行版都应该已ç»æ‰“包了 Paperkey。 + +è¿è¡Œä»¥ä¸‹å‘½ä»¤æ¥åˆ›å»ºç§é’¥çš„硬拷è´å¤‡ä»½:: + + $ gpg --export-secret-key [fpr] | paperkey -o /tmp/key-backup.txt + +打å°å‡ºè¯¥æ–‡ä»¶ï¼ˆæˆ–å°†è¾“å‡ºç›´æŽ¥ä¼ è¾“åˆ° lpr），然åŽç”¨ç¬”åœ¨çº¸çš„è¾¹ç¼˜å†™ä¸‹ä½ çš„å¯† +ç 。 **å¼ºçƒˆå»ºè®®è¿™æ ·åš**ï¼Œå› ä¸ºå¯†é’¥æ‰“å°è¾“出ä»ç„¶ä½¿ç”¨è¯¥å¯†ç è¿›è¡ŒåŠ å¯†ï¼Œå¹¶ä¸” +å¦‚æžœä½ æ›´æ”¹äº†å®ƒï¼Œä½ å°†ä¸è®°å¾—创建备份时它曾ç»æ˜¯ä»€ä¹ˆ - *ä¿è¯*。 + +将生æˆçš„打å°è¾“出和手写密ç 放入信å°ä¸ï¼Œå¹¶å˜æ”¾åœ¨å®‰å…¨ä¸”å—到良好ä¿æŠ¤çš„地 +æ–¹ï¼Œæœ€å¥½è¿œç¦»ä½ çš„å®¶ï¼Œä¾‹å¦‚é“¶è¡Œä¿é™©æŸœã€‚ + +.. note:: + + ä½ çš„æ‰“å°æœºå¯èƒ½ä¸å†æ˜¯è¿žæŽ¥åˆ°å¹¶è¡Œç«¯å£çš„简å•å“‘设备，但由于输出ä»ç„¶ä½¿ + ç”¨ä½ çš„å¯†ç è¿›è¡ŒåŠ å¯†ï¼Œå› æ¤å³ä½¿â€œäº‘端打å°â€çš„现代打å°æœºä¹Ÿåº”该ä¿æŒç›¸ + 对安全的æ“作 + +备份整个 GnuPG 目录 +------------------- + +.. warning:: + + **!!!ä¸è¦è·³è¿‡è¿™ä¸ªæ¥éª¤!!!** + +å¦‚æžœä½ éœ€è¦æ¢å¤ PGP 密钥，拥有一个éšæ—¶å¯ç”¨çš„备份éžå¸¸é‡è¦ã€‚这与我们 +所åšçš„ç¾éš¾çº§å‡†å¤‡ä¸åŒ ``paperkey`` 。æ¯å½“ä½ éœ€è¦ä½¿ç”¨ä½ çš„è¯ä¹¦å¯†é’¥æ—¶ï¼Œ +例如在会议和峰会åŽæ›´æ”¹ä½ 自己的密钥或ç¾ç½²å…¶ä»–äººçš„å¯†é’¥æ—¶ï¼Œä½ è¿˜å°†ä¾èµ– +这些外部副本。 + +首先获å–一个å°åž‹ USB “拇指†驱动器（最好是两个ï¼ï¼‰ï¼Œç”¨äºŽå¤‡ä»½ç›®çš„。 +ä½ éœ€è¦ä½¿ç”¨ LUKS å¯¹å…¶è¿›è¡ŒåŠ å¯†â€”â€”è¯·å‚é˜…ä½ çš„å‘è¡Œç‰ˆæ–‡æ¡£ä»¥äº†è§£å¦‚ä½•å®Œæˆ +æ¤æ“作。 + +å¯¹äºŽåŠ å¯†å¯†ç ï¼Œä½ å¯ä»¥ä½¿ç”¨ä¸Ž PGP 密钥相åŒçš„密ç 。 + +åŠ å¯†è¿‡ç¨‹å®ŒæˆåŽï¼Œé‡æ–°æ’å…¥ USB 驱动器并确ä¿å…¶æ£ç¡®å®‰è£…。将整个 ``.gnupg`` +目录å¤åˆ¶åˆ°åŠ 密å˜å‚¨:: + + $ cp -a ~/.gnupg /media/disk/foo/gnupg-backup + +ä½ çŽ°åœ¨åº”è¯¥æµ‹è¯•ä¸€ä¸‹ï¼Œç¡®ä¿ä¸€åˆ‡ä¾ç„¶èƒ½æ£å¸¸å·¥ä½œ:: + + $ gpg --homedir=/media/disk/foo/gnupg-backup --list-key [fpr] + +如果没有出现任何错误，那么就å¯ä»¥å¼€å§‹äº†ã€‚å¸ä¸‹ USB 驱动器，给它贴上 +æ˜Žæ˜¾çš„æ ‡ç¾ï¼Œè¿™æ ·ä¸‹æ¬¡éœ€è¦ä½¿ç”¨éšæœº USB 驱动器时就ä¸ä¼šæŠŠå®ƒå¹èµ°ï¼Œç„¶åŽ +放在安全的地方 - 但ä¸è¦å¤ªè¿œï¼Œå› ä¸ºä½ æ¯æ¬¡éƒ½éœ€è¦ä½¿ç”¨å®ƒæ—¶ä¸æ—¶åœ°ç”¨äºŽè¯¸ +如编辑身份ã€æ·»åŠ 或撤销å密钥或ç¾ç½²å…¶ä»–人的密钥之类的事情。 + +ä»Žä½ çš„ homedir ä¸åˆ 除 Certify 密钥 +---------------------------------- + +我们的主目录ä¸çš„文件并没有我们想象的那么å—到ä¿æŠ¤ã€‚它们å¯ä»¥é€šè¿‡å¤šç§ +ä¸åŒçš„æ–¹å¼æ³„露或被盗: + +- 在制作快速主目录备份以设置新工作站时æ„外å‘生 +- 系统管ç†å‘˜çš„ç–忽或æ¶æ„ +- 通过ä¸å®‰å…¨çš„备份 +- 通过桌é¢åº”用程åºï¼ˆæµè§ˆå™¨ã€pdf 查看器ç‰ï¼‰ä¸çš„æ¶æ„软件 +- 跨越国界时通过èƒè¿« + +使用良好的密ç çŸè¯ä¿æŠ¤ä½ 的密钥æžå¤§åœ°æœ‰åŠ©äºŽé™ä½Žä¸Šè¿°ä»»ä½•é£Žé™©ï¼Œä½†å¯†ç +çŸè¯å¯ä»¥é€šè¿‡é”®ç›˜è®°å½•å™¨ã€è‚©çª¥æˆ–任何其他方å¼å‘çŽ°ã€‚å› æ¤ï¼Œå»ºè®®çš„设置是 +从主目录ä¸åˆ é™¤ä½ çš„è¯ä¹¦å¯†é’¥å¹¶å°†å…¶å˜å‚¨åœ¨ç¦»çº¿å˜å‚¨ä¸ã€‚ + +.. warning:: + + 请å‚阅上一节并确ä¿ä½ 已完整备份 GnuPG ç›®å½•ã€‚å¦‚æžœä½ æ²¡æœ‰å¯ç”¨çš„ + 备份，我们è¦åšçš„äº‹æƒ…å°†ä½¿ä½ çš„å¯†é’¥æ¯«æ— ç”¨å¤„ï¼ + +é¦–å…ˆï¼Œç¡®å®šä½ çš„è¯ä¹¦å¯†é’¥çš„keygrip:: + + $ gpg --with-keygrip --list-key [fpr] + +è¾“å‡ºå°†æ˜¯è¿™æ ·çš„:: + + pub ed25519 2022-12-20 [SC] [expires: 2022-12-19] + 000000000000000000000000AAAABBBBCCCCDDDD + Keygrip = 1111000000000000000000000000000000000000 + uid [ultimate] Alice Dev <adev@kernel.org> + sub cv25519 2022-12-20 [E] [expires: 2022-12-19] + Keygrip = 2222000000000000000000000000000000000000 + sub ed25519 2022-12-20 [S] + Keygrip = 3333000000000000000000000000000000000000 + +找到该线 ``pub`` 下方的keygrip项 （ä½äºŽâ€œè®¤è¯å¯†é’¥æŒ‡çº¹â€çš„æ£ä¸‹æ–¹ï¼‰ã€‚ +è¿™å°†ç›´æŽ¥å¯¹åº”äºŽä½ ``~/.gnupg`` 目录ä¸çš„一个文件:: + + $ cd ~/.gnupg/private-keys-v1.d + $ ls + 1111000000000000000000000000000000000000.key + 2222000000000000000000000000000000000000.key + 3333000000000000000000000000000000000000.key + +ä½ æ‰€è¦åšçš„åªæ˜¯åˆ 除与è¯ä¹¦å¯†é’¥ keygrip 对应的 .key 文件:: + + $ cd ~/.gnupg/private-keys-v1.d + $ rm 1111000000000000000000000000000000000000.key + +çŽ°åœ¨ï¼Œå¦‚æžœä½ å‘出命令 ``--list-secret-keys`` ，它将显示è¯ä¹¦å¯†é’¥ä¸¢ +失（ 表示 ``#`` 它ä¸å¯ç”¨ï¼‰:: + + $ gpg --list-secret-keys + sec# ed25519 2022-12-20 [SC] [expires: 2024-12-19] + 000000000000000000000000AAAABBBBCCCCDDDD + uid [ultimate] Alice Dev <adev@kernel.org> + ssb cv25519 2022-12-20 [E] [expires: 2024-12-19] + ssb ed25519 2022-12-20 [S] + +ä½ è¿˜åº”è¯¥åˆ é™¤ ``~/.gnupg``目录ä¸çš„所有 ``secring.gpg`` 文件 ，这些 +文件å¯èƒ½æ˜¯ä»¥å‰ç‰ˆæœ¬çš„ GnuPG 留下的。 + +å¦‚æžœä½ æ²¡æœ‰â€œprivate-keys-v1.dâ€ç›®å½• +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +å¦‚æžœä½ æ²¡æœ‰ ``~/.gnupg/private-keys-v1.d`` ç›®å½•ï¼Œé‚£ä¹ˆä½ çš„å¯†é’¥ä»å˜ +储在 GnuPG v1 使用的旧文件 ``secring.gpg`` ä¸ã€‚对密钥进行任何更改 +（例如更改密ç æˆ–æ·»åŠ å密钥）应该会自动转æ¢æ—§ ``secring.gpg`` æ ¼å¼ä»¥ +供使用 ``private-keys-v1.d`` 。 + +完æˆæ¤æ“作åŽï¼Œè¯·ç¡®ä¿åˆ 除过时的 ``secring.gpg`` 文件，其ä¸ä»ç„¶åŒ…å«ä½ +çš„ç§é’¥ã€‚ + + +å°†åå¯†é’¥ç§»è‡³ä¸“ç”¨åŠ å¯†è®¾å¤‡ +======================== + +尽管 Certify 密钥现在ä¸ä¼šè¢«æ³„露或被盗，但å密钥ä»ç„¶ä½äºŽä½ 的主目录ä¸ã€‚ +ä»»ä½•è®¾æ³•èŽ·å¾—è¿™äº›å†…å®¹çš„äººéƒ½å°†èƒ½å¤Ÿè§£å¯†ä½ çš„é€šä¿¡æˆ–ä¼ªé€ ä½ çš„ç¾å（如果他们知 +é“密ç ）。æ¤å¤–，æ¯æ¬¡æ‰§è¡Œ GnuPG æ“ä½œæ—¶ï¼Œå¯†é’¥éƒ½ä¼šåŠ è½½åˆ°ç³»ç»Ÿå†…å˜ä¸ï¼Œå¹¶ +å¯èƒ½è¢«è¶³å¤Ÿé«˜çº§çš„æ¶æ„软件（例如 Meltdown å’Œ Spectre）从那里窃å–。 + +完全ä¿æŠ¤å¯†é’¥çš„最佳方法是将它们转移到能够进行智能å¡æ“作的专用硬件设备上。 + +智能å¡çš„好处 +------------ + +智能å¡åŒ…å«ä¸€ä¸ªåŠ 密芯片，能够å˜å‚¨ç§é’¥å¹¶ç›´æŽ¥åœ¨å¡æœ¬èº«ä¸Šæ‰§è¡ŒåŠ 密æ“作。由于 +密钥内容永远ä¸ä¼šç¦»å¼€æ™ºèƒ½å¡ï¼Œå› æ¤æ’入硬件设备的计算机的æ“ä½œç³»ç»Ÿæ— æ³•è‡ªè¡Œ +检索ç§é’¥ã€‚这与我们之å‰ç”¨äºŽå¤‡ä»½ç›®çš„çš„åŠ å¯† USB å˜å‚¨è®¾å¤‡æœ‰å¾ˆå¤§ä¸åŒâ€”—当 +USB 设备æ’入并安装时，æ“作系统能够访问ç§é’¥å†…容。 + +ä½¿ç”¨å¤–éƒ¨åŠ å¯† USB 介质并ä¸èƒ½æ›¿ä»£å…·æœ‰æ™ºèƒ½å¡åŠŸèƒ½çš„设备。 + +å¯ç”¨çš„智能å¡è®¾å¤‡ +---------------- + +除éžä½ 的所有笔记本电脑和工作站都有智能å¡è¯»å¡å™¨ï¼Œå¦åˆ™æœ€ç®€å•çš„方法是获 +å–实现智能å¡åŠŸèƒ½çš„专用 USB 设备。有多ç§é€‰æ‹©ï¼š: + +- `Nitrokey Start`_: 开放硬件和å…费软件，日本基于FSIçš„ `Gnuk` 。 + å°‘æ•°æ”¯æŒ ED25519 ECC 密钥的商用设备之一，但æ供的安全功能最少 + （例如防篡改或æŸäº›æ—路攻击）。 +- `Nitrokey Pro 2`_: 与 Nitrokey Start 类似，但更防篡改并æä¾› + 更多安全功能。Pro 2 æ”¯æŒ ECC åŠ å¯† (NISTP)。 +- `Yubikey 5`_: 专有硬件和软件，但比 Nitrokey Pro 便宜，并且以 + USB-C å½¢å¼æ供，对于较新的笔记本电脑更有用。æä¾›é¢å¤–的安全功能， + 例如 FIDO U2F ç‰ï¼ŒçŽ°åœ¨ç»ˆäºŽæ”¯æŒ NISTP å’Œ ED25519 ECC 密钥。 + +ä½ çš„é€‰æ‹©å°†å–决于æˆæœ¬ã€ä½ 所在地ç†åŒºåŸŸçš„è´§è¿ä¾¿åˆ©æ€§ä»¥åŠå¼€æ”¾/专有硬件考虑 +å› ç´ ã€‚ + +.. note:: + + å¦‚æžœä½ ä½åˆ—于 MAINTAINERS ä¸æˆ–在 kernel.org 上拥有å¸æˆ·ï¼Œåˆ™ä½ 有 + èµ„æ ¼èŽ·å¾—Linux 基金会æ供的_`qualify for a free Nitrokey Start` 。 + +.. _`Nitrokey Start`: https://shop.nitrokey.com/shop/product/nitrokey-start-6 +.. _`Nitrokey Pro 2`: https://shop.nitrokey.com/shop/product/nkpr2-nitrokey-pro-2-3 +.. _`Yubikey 5`: https://www.yubico.com/products/yubikey-5-overview/ +.. _Gnuk: https://www.fsij.org/doc-gnuk/ +.. _`qualify for a free Nitrokey Start`: https://www.kernel.org/nitrokey-digital-tokens-for-kernel-developers.html + +é…ç½®ä½ çš„æ™ºèƒ½å¡è®¾å¤‡ +------------------ + +å½“ä½ å°†æ™ºèƒ½å¡è®¾å¤‡æ’入任何现代 Linux 工作站时，它就应该å¯ä»¥æ£å¸¸å·¥ä½œ +(TM)ã€‚ä½ å¯ä»¥é€šè¿‡è¿è¡Œæ¥éªŒè¯å®ƒ:: + + $ gpg --card-status + +å¦‚æžœä½ çœ‹åˆ°å®Œæ•´çš„æ™ºèƒ½å¡è¯¦ç»†ä¿¡æ¯ï¼Œé‚£ä¹ˆä½ å°±å¯ä»¥å¼€å§‹äº†ã€‚ä¸å¹¸çš„是，对所有 +å¯èƒ½æ— 法æ£å¸¸å·¥ä½œçš„åŽŸå› è¿›è¡Œæ•…éšœæŽ’é™¤è¶…å‡ºäº†æœ¬æŒ‡å—çš„èŒƒå›´ã€‚å¦‚æžœä½ åœ¨ä½¿è¯¥å¡ +与 GnuPG é…åˆä½¿ç”¨æ—¶é‡åˆ°é—®é¢˜ï¼Œè¯·é€šè¿‡å¸¸è§„支æŒæ¸ é“寻求帮助。 + +è¦é…ç½®ä½ çš„æ™ºèƒ½å¡ï¼Œä½ 需è¦ä½¿ç”¨ GnuPG èœå•ç³»ç»Ÿï¼Œå› 为没有方便的命令行开 +å…³:: + + $ gpg --card-edit + [...omitted...] + gpg/card> admin + Admin commands are allowed + gpg/card> passwd + +ä½ åº”è¯¥è®¾ç½®ç”¨æˆ· PIN (1)ã€ç®¡ç†å‘˜ PIN (3) å’Œé‡ç½®ä»£ç (4)。请确ä¿å°† +这些信æ¯è®°å½•å¹¶å˜å‚¨åœ¨å®‰å…¨çš„地方，尤其是管ç†å‘˜ PIN ç å’Œé‡ç½®ä»£ç ï¼ˆå®ƒå… +è®¸ä½ å®Œå…¨æ“¦é™¤æ™ºèƒ½å¡ï¼‰ã€‚ä½ å¾ˆå°‘éœ€è¦ä½¿ç”¨ç®¡ç†å‘˜ PIN ç ï¼Œå¦‚æžœä½ ä¸è®°å½•å®ƒï¼Œ +ä½ å°†ä¸å¯é¿å…地忘记它是什么。 + +回到主å¡èœå•ï¼Œä½ 还å¯ä»¥è®¾ç½®å…¶ä»–值（例如姓åã€æ€§åˆ«ã€ç™»å½•æ•°æ®ç‰ï¼‰ï¼Œä½†è¿™ +ä¸æ˜¯å¿…éœ€çš„ï¼Œå¹¶ä¸”å¦‚æžœä½ ä¸¢å¤±æ™ºèƒ½å¡ï¼Œè¿˜ä¼šæ³„露有关智能å¡çš„ä¿¡æ¯ã€‚ + +.. note:: + + 尽管å称为“PINâ€ï¼Œä½†å¡ä¸Šçš„用户 PIN 和管ç†å‘˜ PIN 都ä¸éœ€è¦æ˜¯æ•°å—。 + +.. warning:: + + æŸäº›è®¾å¤‡å¯èƒ½è¦æ±‚ä½ å°†å密钥移至设备上，然åŽæ‰èƒ½æ›´æ”¹å¯†ç 。请检查设 + å¤‡åˆ¶é€ å•†æ供的文档。 + +å°†åå¯†é’¥ç§»è‡³ä½ çš„æ™ºèƒ½å¡ +---------------------- + +退出å¡èœå•ï¼ˆä½¿ç”¨â€œqâ€ï¼‰å¹¶ä¿å˜æ‰€æœ‰æ›´æ”¹ã€‚接下æ¥ï¼Œè®©æˆ‘们将åå¯†é’¥ç§»è‡³æ™ºèƒ½å¡ +上。对于大多数æ“ä½œï¼Œä½ å°†éœ€è¦ PGP 密钥密ç å’Œå¡çš„管ç†å‘˜ PIN:: + + $ gpg --edit-key [fpr] + + Secret subkeys are available. + + pub ed25519/AAAABBBBCCCCDDDD + created: 2022-12-20 expires: 2024-12-19 usage: SC + trust: ultimate validity: ultimate + ssb cv25519/1111222233334444 + created: 2022-12-20 expires: never usage: E + ssb ed25519/5555666677778888 + created: 2017-12-07 expires: never usage: S + [ultimate] (1). Alice Dev <adev@kernel.org> + + gpg> + +使用 ``--edit-key`` 使我们å†æ¬¡è¿›å…¥èœå•æ¨¡å¼ï¼Œä½ 会注æ„到按键列表有点 +ä¸åŒã€‚从现在开始，所有命令都在æ¤èœå•æ¨¡å¼å†…完æˆï¼Œå¦‚ 所示 ``gpg>``。 + +首先，让我们选择è¦æ”¾å…¥å¡ä¸Šçš„密钥 - ä½ å¯ä»¥é€šè¿‡é”®å…¥ ``key 1`` （它是 +列表ä¸çš„第一个， **[E]** å密钥）æ¥å®Œæˆæ¤æ“作： + + gpg> key 1 + +在输出ä¸ï¼Œä½ 现在在 **[E]** å密钥应该看到 ``ssb*`` 。æ„味ç€è¿™ä¸ªå +密钥当å‰è¢«é€‰ä¸ã€‚它用作切æ¢é”®ï¼Œè¿™æ„味ç€å¦‚æžœä½ å†æ¬¡è¾“å…¥ ``key 1`` ， +``*`` 将会消失并且该键将ä¸å†è¢«é€‰æ‹©ã€‚ + +现在，让我们将该密钥移至智能å¡ä¸Š:: + + gpg> keytocard + Please select where to store the key: + (2) Encryption key + Your selection? 2 + +由于它是我们的 **[E]** å¯†é’¥ï¼Œå› æ¤å°†å…¶æ”¾å…¥åŠ 密槽ä¸æ˜¯æœ‰æ„ä¹‰çš„ã€‚å½“ä½ æ +交选择时，系统将首先æç¤ºä½ è¾“å…¥ PGP 密钥密ç ，然åŽè¾“入管ç†å‘˜ PIN ç 。 +å¦‚æžœå‘½ä»¤è¿”å›žä¸”æ²¡æœ‰é”™è¯¯ï¼Œåˆ™ä½ çš„å¯†é’¥å·²è¢«ç§»åŠ¨ã€‚ + +**é‡è¦æ示**：现在å†æ¬¡é”®å…¥ ``key 1`` 以å–消选择第一个键，并 ``key 2`` +选择 **[S]** 密钥:: + + gpg> key 1 + gpg> key 2 + gpg> keytocard + Please select where to store the key: + (1) Signature key + (3) Authentication key + Your selection? 1 + +ä½ å¯ä»¥ä½¿ç”¨ **[S]** 密钥进行ç¾å和身份验è¯ï¼Œä½†æˆ‘们希望确ä¿å®ƒä½äºŽç¾å槽ä¸ï¼Œ +å› æ¤é€‰æ‹© (1)。跟之å‰ä¸€æ ·ï¼Œå¦‚æžœä½ çš„å‘½ä»¤è¿”å›žä¸”æ²¡æœ‰é”™è¯¯ï¼Œåˆ™æ“作æˆåŠŸ:: + + gpg> q + Save changes? (y/N) y + +ä¿å˜æ›´æ”¹å°†åˆ é™¤ä½ ä»Žä¸»ç›®å½•ç§»åŠ¨åˆ°å¡ä¸Šçš„å¯†é’¥ï¼ˆä½†è¿™æ²¡å…³ç³»ï¼Œå› ä¸ºæˆ‘ä»¬è¿˜æœ‰å¤‡ä»½ï¼Œ +让我们需è¦æ›¿æ¢æ™ºèƒ½å¡æ—¶å†æ¬¡æ‰§è¡Œæ¤æ“作）。 + +验è¯å¯†é’¥æ˜¯å¦å·²ç§»åŠ¨ +~~~~~~~~~~~~~~~~~~ + +å¦‚æžœä½ çŽ°åœ¨æ‰§è¡Œ ``--list-secret-keys`` ï¼Œä½ å°†çœ‹åˆ°è¾“å‡ºä¸å˜åœ¨ç»†å¾®çš„差异:: + + $ gpg --list-secret-keys + sec# ed25519 2022-12-20 [SC] [expires: 2024-12-19] + 000000000000000000000000AAAABBBBCCCCDDDD + uid [ultimate] Alice Dev <adev@kernel.org> + ssb> cv25519 2022-12-20 [E] [expires: 2024-12-19] + ssb> ed25519 2022-12-20 [S] + +在 ``ssb>``ä¸çš„ ``>`` 输出æ„味ç€å密钥åªèƒ½åœ¨æ™ºèƒ½å¡ä¸Šå¯ç”¨ï¼Œå¦‚æžœä½ è¿”å›ž +å¯†é’¥ç›®å½•å¹¶æŸ¥çœ‹é‚£é‡Œçš„å†…å®¹ï¼Œä½ ä¼šæ³¨æ„到 ``.key`` 那里的文件已被å˜æ ¹æ›¿æ¢:: + + $ cd ~/.gnupg/private-keys-v1.d + $ strings *.key | grep 'private-key' + +è¾“å‡ºåº”åŒ…å« ``shadowed-private-key`` 指示这些文件åªæ˜¯å˜æ ¹ï¼Œå®žé™…内容 +ä½äºŽæ™ºèƒ½å¡ä¸Šã€‚ + +验è¯æ™ºèƒ½å¡æ˜¯å¦æ£å¸¸å·¥ä½œ +~~~~~~~~~~~~~~~~~~~~~~ + +è¦éªŒè¯æ™ºèƒ½å¡æ˜¯å¦æŒ‰é¢„æœŸå·¥ä½œï¼Œä½ å¯ä»¥åˆ›å»ºç¾å:: + + $ echo "Hello world" | gpg --clearsign > /tmp/test.asc + $ gpg --verify /tmp/test.asc + +åœ¨ä½ çš„ç¬¬ä¸€æ¡å‘½ä»¤æ‰§è¡Œæ—¶ï¼Œåº”è¯¥ä¼šè¯¢é—®ä½ æ™ºèƒ½å¡çš„PIN，然åŽåœ¨ä½ è¿è¡Œ +``gpg --verify`` åŽæ˜¾ç¤º"Good signature"。 + +æå–œï¼Œä½ å·²æˆåŠŸä½¿çªƒå–ä½ çš„æ•°å—å¼€å‘者身份å˜å¾—æžå…¶å›°éš¾ï¼ + +其他常è§çš„ GnuPG æ“作 +--------------------- + +ä»¥ä¸‹æ˜¯ä½ éœ€è¦ä½¿ç”¨ PGP 密钥执行的一些常è§æ“作的快速å‚考。 + +å®‰è£…ä½ çš„å®‰å…¨ç¦»çº¿å˜å‚¨ +~~~~~~~~~~~~~~~~~~~~ + +ä½ å°†éœ€è¦ä½ çš„è¯ä¹¦å¯†é’¥æ¥æ‰§è¡Œä»¥ä¸‹ä»»ä½•æ“ä½œï¼Œå› æ¤ä½ 首先需è¦å®‰è£…备份离线å˜å‚¨ +并告诉 GnuPG 使用它:: + + $ export GNUPGHOME=/media/disk/foo/gnupg-backup + $ gpg --list-secret-keys + +ä½ éœ€è¦ç¡®ä¿ä½ 看到 ``sec`` 而ä¸æ˜¯ ``sec#`` 在输出ä¸ï¼ˆ ``#`` æ„å‘³ç€ +密钥ä¸å¯ç”¨å¹¶ä¸”ä½ ä»åœ¨ä½¿ç”¨å¸¸è§„主目录ä½ç½®ï¼‰ã€‚ + +延长密钥有效期 +~~~~~~~~~~~~~~ + +è¯ä¹¦å¯†é’¥çš„默认到期日期为自创建之日起 2 å¹´ã€‚è¿™æ ·åšæ—¢æ˜¯å‡ºäºŽå®‰å…¨åŽŸå› ，也 +是为了使过时的密钥最终从密钥æœåŠ¡å™¨ä¸æ¶ˆå¤±ã€‚ + +è¦å°†å¯†é’¥çš„有效期从当å‰æ—¥æœŸå»¶é•¿ä¸€å¹´ï¼Œåªéœ€è¿è¡Œ:: + + $ gpg --quick-set-expire [fpr] 1y + +如果更容易记ä½ï¼Œä½ 也å¯ä»¥ä½¿ç”¨ç‰¹å®šæ—¥æœŸï¼ˆä¾‹å¦‚ä½ çš„ç”Ÿæ—¥ã€1 月 1 æ—¥æˆ–åŠ æ‹¿å¤§ +国庆日）:: + + $ gpg --quick-set-expire [fpr] 2025-07-01 + +请记ä½å°†æ›´æ–°åŽçš„密钥å‘é€å›žå¯†é’¥æœåŠ¡å™¨:: + + $ gpg --send-key [fpr] + +进行任何更改åŽæ›´æ–°ä½ 的工作目录 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +使用离线å˜å‚¨å¯¹å¯†é’¥è¿›è¡Œä»»ä½•æ›´æ”¹åŽï¼Œä½ 需è¦å°†è¿™äº›æ›´æ”¹å¯¼å…¥å›žå¸¸è§„工作目录 +ä¸:: + + $ gpg --export | gpg --homedir ~/.gnupg --import + $ unset GNUPGHOME + +通过 ssh 使用 gpg-agent +~~~~~~~~~~~~~~~~~~~~~~~ + +å¦‚æžœä½ éœ€è¦åœ¨è¿œç¨‹ç³»ç»Ÿä¸Šç¾ç½²æ ‡ç¾æˆ–æäº¤ï¼Œä½ å¯ä»¥é€šè¿‡ ssh 转å‘ä½ çš„ +gpg-agent。 + +请å‚考 GnuPG wiki 上æ供的说明: + +- `Agent通过SSH转å‘`_ + +å¦‚æžœä½ å¯ä»¥ä¿®æ”¹è¿œç¨‹ç«¯çš„ sshd æœåŠ¡å™¨è®¾ç½®ï¼Œåˆ™å·¥ä½œä¼šæ›´é¡ºåˆ©ã€‚ + +.. _`Agent通过SSH转å‘`: https://wiki.gnupg.org/AgentForwarding + +å°† PGP 与 Git 结åˆä½¿ç”¨ +====================== + +Git çš„æ ¸å¿ƒåŠŸèƒ½ä¹‹ä¸€æ˜¯å®ƒçš„åˆ†æ•£æ€§â€”â€”ä¸€æ—¦å°†ä»“åº“å…‹éš†åˆ°ä½ çš„ç³»ç»Ÿï¼Œä½ å°±æ‹¥æœ‰è¯¥ +项目的完整历å²è®°å½•ï¼ŒåŒ…æ‹¬å…¶æ‰€æœ‰æ ‡ç¾ã€æ交和分支。然而，éšç€æ•°ç™¾ä¸ªå…‹éš†ä»“ +库的出现，人们如何验è¯ä»–们的 linux.git 副本没有被æ¶æ„第三方篡改？ + +或者，如果在代ç ä¸å‘现åŽé—¨ï¼Œå¹¶ä¸”æ交ä¸çš„“Authorâ€è¡Œè¡¨ç¤ºå®ƒæ˜¯ç”±ä½ 完æˆçš„， +è€Œä½ éžå¸¸ç¡®å®š `è‡ªå·±ä¸Žå®ƒæ— å…³`_ ，会å‘生什么？ + +为了解决这两个问题，Git 引入了 PGP 集æˆã€‚ç¾åçš„æ ‡ç¾é€šè¿‡ç¡®ä¿å…¶å†…容与创 +å»ºæ ‡ç¾çš„å¼€å‘人员的工作站上的内容完全相åŒæ¥è¯æ˜Žä»“库的完整性，而ç¾åçš„æ +äº¤ä½¿å…¶ä»–äººå‡ ä¹Žä¸å¯èƒ½åœ¨æ— æ³•è®¿é—®ä½ çš„ PGP å¯†é’¥çš„æƒ…å†µä¸‹å†’å……ä½ ã€‚ + +.. _`è‡ªå·±ä¸Žå®ƒæ— å…³`: https://github.com/jayphelps/git-blame-someone-else + +é…ç½® git ä½¿ç”¨ä½ çš„ PGP 密钥 +-------------------------- + +å¦‚æžœä½ çš„å¯†é’¥çŽ¯ä¸åªæœ‰ä¸€ä¸ªå¯†é’¥ï¼Œé‚£ä¹ˆä½ 实际上ä¸éœ€è¦æ‰§è¡Œä»»ä½•é¢å¤–æ“ä½œï¼Œå› ä¸º +它会æˆä¸ºä½ çš„é»˜è®¤å¯†é’¥ã€‚ä½†æ˜¯ï¼Œå¦‚æžœä½ ç¢°å·§æœ‰å¤šä¸ªå¯†é’¥ï¼Œä½ å¯ä»¥å‘Šè¯‰ git 应该 +使用哪个密钥（``[fpr]`` æ˜¯ä½ å¯†é’¥çš„æŒ‡çº¹ï¼‰:: + + $ git config --global user.signingKey [fpr] + +如何使用ç¾åæ ‡ç¾ +---------------- + +è¦åˆ›å»ºç¾åæ ‡ç¾ï¼Œåªéœ€å°† ``-s`` å¼€å…³ä¼ é€’ç»™ tag 命令:: + + $ git tag -s [tagname] + +我们的建议是始终ç¾ç½² git æ ‡ç¾ï¼Œå› 为这å¯ä»¥è®©å…¶ä»–å¼€å‘人员确ä¿ä»–们从ä¸æ +å–çš„ git 仓库没有被æ¶æ„更改。 + +如何验è¯ç¾åæ ‡ç¾ +~~~~~~~~~~~~~~~~ + +è¦éªŒè¯ç¾åæ ‡ç¾ï¼Œåªéœ€ä½¿ç”¨ä»¥ä¸‹ ``verify-tag`` 命令:: + + $ git verify-tag [tagname] + +å¦‚æžœä½ ä»Žé¡¹ç›®ä»“åº“çš„å¦ä¸€ä¸ªåˆ†æ”¯ä¸æ‹‰å–æ ‡ç¾ï¼Œgit 应该自动验è¯ä½ 拉å–的顶 +部的ç¾å，并在åˆå¹¶æ“作期间å‘ä½ æ˜¾ç¤ºç»“æžœ:: + + $ git pull [url] tags/sometag + +åˆå¹¶æ¶ˆæ¯å°†åŒ…å«å¦‚下内容:: + + Merge tag 'sometag' of [url] + + [Tag message] + + # gpg: Signature made [...] + # gpg: Good signature from [...] + +å¦‚æžœä½ æ£åœ¨éªŒè¯å…¶ä»–人的 git æ ‡ç¾ï¼Œé‚£ä¹ˆä½ 将需è¦å¯¼å…¥ä»–们的 PGP 密钥。 +请å‚阅下é¢çš„":ref:`身份验è¯`"部分。 + +é…ç½® git å§‹ç»ˆå¯¹å¸¦æ³¨é‡Šçš„æ ‡ç¾ï¼ˆannotated tags）进行ç¾åannotated tags +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +å¦‚æžœä½ è¦åˆ›å»ºå¸¦æ³¨é‡Šçš„æ ‡ç¾ï¼Œä½ 很å¯èƒ½ä¼šæƒ³è¦å¯¹å…¶è¿›è¡Œç¾å。è¦å¼ºåˆ¶ git å§‹ç»ˆç¾ +ç½²å¸¦æ³¨é‡Šçš„æ ‡ç¾ï¼Œä½ å¯ä»¥è®¾ç½®ä¸€ä¸ªå…¨å±€é…置选项:: + + $ git config --global tag.forceSignAnnotated true + +如何使用ç¾åçš„æ交 +------------------ + +创建ç¾åæ交很容易，但在 Linux å†…æ ¸å¼€å‘ä¸ä½¿ç”¨å®ƒä»¬è¦å›°éš¾å¾—å¤šï¼Œå› ä¸ºå®ƒä¾èµ– +于å‘é€åˆ°é‚®ä»¶åˆ—表的补ä¸ï¼Œå¹¶ä¸”æ¤å·¥ä½œæµç¨‹ä¸ä¿ç•™ PGP æ交ç¾å。æ¤å¤–，当é‡æ–° +调整仓库以匹é…ä¸Šæ¸¸æ—¶ï¼Œç”šè‡³ä½ è‡ªå·±çš„ PGP æ交ç¾åæœ€ç»ˆä¹Ÿä¼šè¢«ä¸¢å¼ƒã€‚å› æ¤ï¼Œå¤§ +å¤šæ•°å†…æ ¸å¼€å‘人员ä¸ä¼šè´¹å¿ƒç¾ç½²ä»–们的æ交，并且会忽略他们在工作ä¸ä¾èµ–的任何 +外部仓库ä¸çš„ç¾åæ交。 + +ä½†æ˜¯ï¼Œå¦‚æžœä½ çš„å·¥ä½œ git æ ‘åœ¨æŸäº› git 托管æœåŠ¡ï¼ˆkernel.org〠+infradead.orgã€ozlabs.org 或其他）上公开å¯ç”¨ï¼Œé‚£ä¹ˆå»ºè®®ä½ ç¾ç½²æ‰€æœ‰ git +æ交，å³ä½¿ä¸Šæ¸¸å¼€å‘人员ä¸ç›´æŽ¥å—益于这ç§åšæ³•ã€‚ + +我们推èè¿™æ ·åšçš„åŽŸå› å¦‚ä¸‹: + +1. 如果需è¦æ‰§è¡Œä»£ç å–è¯æˆ–跟踪代ç æ¥æºï¼Œå³ä½¿æ˜¯å¤–部维护的带有 PGP æ交ç¾å + çš„æ ‘å¯¹äºŽæ¤ç±»é—®é¢˜ä¹Ÿå¾ˆæœ‰ä»·å€¼ã€‚ +2. å¦‚æžœä½ éœ€è¦é‡æ–°å…‹éš†æœ¬åœ°ä»“库（例如，在ç£ç›˜æ•…éšœåŽï¼‰ï¼Œè¿™å¯ä»¥è®©ä½ 在æ¢å¤å·¥ + 作之å‰è½»æ¾éªŒè¯ä»“库的完整性。 +3. 如果有人需è¦æŒ‘é€‰ä½ çš„æ交，这å¯ä»¥è®©ä»–们在应用之å‰å¿«é€ŸéªŒè¯å…¶å®Œæ•´æ€§ã€‚ + +创建ç¾åæ交 +~~~~~~~~~~~~ + +è¦åˆ›å»ºç¾åæäº¤ï¼Œä½ åªéœ€å°† ``-S`` æ ‡å¿—ä¼ é€’ç»™ ``git commit`` 命令（由于 +与å¦ä¸€ä¸ªæ ‡å¿—冲çªï¼Œæ‰€ä»¥å®ƒæ˜¯å¤§å†™çš„ ``-S`` ）:: + + $ git commit -S + +é…ç½® git 始终对æ交进行ç¾å +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +ä½ å¯ä»¥å‘Šè¯‰ git 总是ç¾ç½²æ交:: + + git config --global commit.gpgSign true + +.. note:: + + ç¡®ä¿ ``gpg-agent`` 在打开æ¤åŠŸèƒ½ä¹‹å‰è¿›è¡Œé…置。 + +.. _身份验è¯: + + +如何使用ç¾åè¡¥ä¸ +---------------- + +å¯ä»¥ä½¿ç”¨ä½ çš„ PGP 密钥æ¥ç¾ç½²å‘é€åˆ°å†…æ ¸å¼€å‘人员邮件列表的补ä¸ã€‚由于现有的 +电å邮件ç¾å机制（PGP-Mime 或 PGP-inline）往往会导致常规代ç 审查任务 +å‡ºçŽ°é—®é¢˜ï¼Œå› æ¤ä½ 应该使用为æ¤åˆ›å»ºçš„ kernel.org å·¥å…·ï¼Œè¯¥å·¥å…·å°†åŠ å¯†è¯æ˜Žç¾ +å放入消æ¯æ ‡å¤´ä¸ï¼ˆa-la DKIM）: + +- `Patatt Patch Attestation`_ + +.. _`Patatt Patch Attestation`: https://pypi.org/project/patatt/ + +安装和é…ç½® patatt +~~~~~~~~~~~~~~~~~ + +Patatt 已针对许多å‘è¡Œç‰ˆè¿›è¡Œäº†æ‰“åŒ…ï¼Œå› æ¤è¯·å…ˆæ£€æŸ¥é‚£é‡Œã€‚ä½ è¿˜å¯ä»¥ä½¿ç”¨ +“ ``pip install patatt`` â€ä»Ž pypi 安装它。 + +å¦‚æžœä½ å·²ç»ä½¿ç”¨ git é…置了 PGP 密钥（通过``user.signingKey`` é…ç½®å‚数）， +则 patatt ä¸éœ€è¦è¿›ä¸€æ¥é…ç½®ã€‚ä½ å¯ä»¥é€šè¿‡åœ¨æ‰€éœ€çš„仓库ä¸å®‰è£… git-send-email +é’©åæ¥å¼€å§‹ç¾ç½²è¡¥ä¸:: + + patatt install-hook + +çŽ°åœ¨ï¼Œä½ ä½¿ç”¨ ``git send-email`` å‘é€çš„任何补ä¸éƒ½å°†è‡ªåŠ¨ä½¿ç”¨ä½ çš„åŠ å¯†ç¾ +å进行ç¾å + +检查 patatt ç¾å +~~~~~~~~~~~~~~~~ + +å¦‚æžœä½ ç”¨äºŽ ``b4`` 检索和应用补ä¸ï¼Œé‚£ä¹ˆå®ƒå°†è‡ªåŠ¨å°è¯•éªŒè¯å®ƒé‡åˆ°çš„所有 +DKIM å’Œ patatt ç¾å，例如:: + + $ b4 am 20220720205013.890942-1-broonie@kernel.org + [...] + Checking attestation on all messages, may take a moment... + --- + ✓ [PATCH v1 1/3] kselftest/arm64: Correct buffer allocation for SVE Z registers + ✓ [PATCH v1 2/3] arm64/sve: Document our actual ABI for clearing registers on syscall + ✓ [PATCH v1 3/3] kselftest/arm64: Enforce actual ABI for SVE syscalls + --- + ✓ Signed: openpgp/broonie@kernel.org + ✓ Signed: DKIM/kernel.org + +.. note:: + + Patatt å’Œ b4 ä»åœ¨ç§¯æžå¼€å‘ä¸ï¼Œä½ 应该检查这些项目的最新文档以了解任 + 何新功能或更新功能。 + +如何验è¯å†…æ ¸å¼€å‘者身份 +====================== + +ç¾ç½²æ ‡ç¾å’Œæ交很容易，但是如何验è¯ç”¨äºŽç¾ç½²æŸé¡¹å†…容的密钥是å¦å±žäºŽå®žé™…的内 +æ ¸å¼€å‘人员而ä¸æ˜¯æ¶æ„冒å顶替者？ + +使用 WKD å’Œ DANE é…ç½®auto-key-locate（自动密钥检索） +---------------------------------------------------- + +å¦‚æžœä½ è¿˜æ²¡æœ‰å¹¿æ³›æ”¶é›†å…¶ä»–å¼€å‘äººå‘˜çš„å…¬é’¥ï¼Œé‚£ä¹ˆä½ å¯ä»¥ä¾é 密钥自动å‘现和自动 +检索æ¥å¿«é€Ÿå¯åŠ¨ä½ 的密钥环。如果从头开始创建自己的信任 Web çš„é¢„æœŸå¤ªä»¤äººç• +惧， GnuPG å¯ä»¥å€ŸåŠ©å…¶ä»–å§”æ‰˜ä¿¡ä»»æŠ€æœ¯ï¼ˆå³ DNSSEC å’Œ TLS）æ¥å¸®åŠ©ä½ 继ç»å‰ +进。 + +å°†ä»¥ä¸‹å†…å®¹æ·»åŠ åˆ°ä½ çš„ ``~/.gnupg/gpg.conf``:: + + auto-key-locate wkd,dane,local + auto-key-retrieve + +基于 DNS 的命å实体身份验è¯ï¼ˆâ€œDANEâ€ï¼‰æ˜¯ä¸€ç§åœ¨ DNS ä¸å‘布公钥并使用 +DNSSEC ç¾å区域ä¿æŠ¤å®ƒä»¬çš„方法。Web 密钥目录（“WKDâ€ï¼‰æ˜¯ä½¿ç”¨ https +查找æ¥è¾¾åˆ°ç›¸åŒç›®çš„的替代方法。当使用 DANE 或 WKD 查找公钥时，GnuPG +å°†åˆ†åˆ«éªŒè¯ DNSSEC 或 TLS è¯ä¹¦ï¼Œç„¶åŽå°†è‡ªåŠ¨æ£€ç´¢çš„å…¬é’¥æ·»åŠ åˆ°æœ¬åœ°å¯†é’¥çŽ¯ã€‚ + +Kernel.org 为所有拥有 kernel.org å¸æˆ·çš„å¼€å‘人员å‘布 WKDã€‚ä¸€æ—¦ä½ çš„ +``gpg.conf`` ä¸è¿›è¡Œäº†ä¸Šè¿°æ›´æ”¹ï¼Œä½ å°±å¯ä»¥è‡ªåŠ¨æ£€ç´¢ Linus Torvalds å’Œ +Greg Kroah-Hartman çš„å¯†é’¥ï¼ˆå¦‚æžœä½ è¿˜æ²¡æœ‰å®ƒä»¬ï¼‰:: + + $ gpg --locate-keys torvalds@kernel.org gregkh@kernel.org + +å¦‚æžœä½ æœ‰ kernel.org å¸æˆ·ï¼Œé‚£ä¹ˆä½ 应该 `æ·»åŠ kernel.org UID åˆ°ä½ çš„å¯†é’¥ä¸`_ +æ·»åŠ åˆ°ä½ çš„å¯†é’¥ä¸ï¼Œä»¥ä½¿ WKD å¯¹å…¶ä»–å†…æ ¸å¼€å‘人员更有用。 + +.. _`æ·»åŠ kernel.org UID åˆ°ä½ çš„å¯†é’¥ä¸`: https://korg.wiki.kernel.org/userdoc/mail#adding_a_kernelorg_uid_to_your_pgp_key + +信任网 (WOT) 与首次使用信任 (TOFU) +----------------------------------- + +PGP 结åˆäº†ç§°ä¸ºâ€œä¿¡ä»»ç½‘â€çš„信任委托机制。从本质上讲，这是一次å°è¯•å–代 +HTTPS/TLS 世界对集ä¸å¼è¯ä¹¦é¢å‘机构的需求。PGP 将这一责任留给æ¯ä¸ª +用户，而ä¸æ˜¯ç”±å„ç§è½¯ä»¶åˆ¶é€ 商规定è°åº”è¯¥æ˜¯ä½ å€¼å¾—ä¿¡èµ–çš„è®¤è¯å®žä½“。 + +ä¸å¹¸çš„是，很少有人了解信任网是如何è¿ä½œçš„。虽然它ä»ç„¶æ˜¯ OpenPGP 规 +范的一个é‡è¦æ–¹é¢ï¼Œä½†æœ€æ–°ç‰ˆæœ¬çš„ GnuPG（2.2 åŠæ›´é«˜ç‰ˆæœ¬ï¼‰å·²ç»å®žçŽ°äº† +一ç§ç§°ä¸ºâ€œé¦–次使用信任â€(TOFU) çš„æ›¿ä»£æœºåˆ¶ã€‚ä½ å¯ä»¥å°† TOFU 视为“类似 +SSH 的信任方法â€ã€‚使用 SSH，第一次连接到远程系统时，其密钥指纹会被 +记录并记ä½ã€‚如果将æ¥å¯†é’¥å‘生å˜åŒ–，SSH 客户端将å‘ä½ å‘出è¦æŠ¥å¹¶æ‹’ç»è¿ž +æŽ¥ï¼Œè¿«ä½¿ä½ å†³å®šæ˜¯å¦é€‰æ‹©ä¿¡ä»»æ›´æ”¹åŽçš„密钥。åŒæ ·ï¼Œç¬¬ä¸€æ¬¡å¯¼å…¥æŸäººçš„ PGP +密钥时，它被认为是有效的。如果将æ¥çš„任何时候 GnuPG é‡åˆ°å…·æœ‰ç›¸åŒæ ‡ +识的å¦ä¸€ä¸ªå¯†é’¥ï¼Œåˆ™å…ˆå‰å¯¼å…¥çš„å¯†é’¥å’Œæ–°å¯†é’¥éƒ½å°†è¢«æ ‡è®°ä¸ºæ— æ•ˆï¼Œä½ å°†éœ€è¦æ‰‹ +动确定ä¿ç•™å“ªä¸€ä¸ªã€‚ + +æˆ‘ä»¬å»ºè®®ä½ ä½¿ç”¨ TOFU+PGP 组åˆä¿¡ä»»æ¨¡åž‹ï¼ˆè¿™æ˜¯ GnuPG v2 ä¸æ–°é»˜è®¤çš„）。 +è‹¥è¦è®¾ç½®å®ƒï¼Œåœ¨ ``~/.gnupg/gpg.conf`` ä¸æ·»åŠ （或修改） +``trust-model`` 设置:: + + trust-model tofu+pgp + +使用 kernel.org 信任网仓库 +-------------------------- + +Kernel.org 维护ç€ä¸€ä¸ªåŒ…å«å¼€å‘人员公钥的 git 仓库，作为å¤åˆ¶å¯†é’¥æœ +务器网络的替代å“ï¼Œè€Œåœ¨è¿‡åŽ»å‡ å¹´ä¸ï¼Œè¯¥ç½‘ç»œå‡ ä¹Žå·²ç»é™·å…¥é»‘暗。有关如何将 +该仓库设置为公钥æ¥æºçš„完整文档å¯ä»¥åœ¨æ¤å¤„找到: + +- `å†…æ ¸å¼€å‘者密钥环`_ + +å¦‚æžœä½ æ˜¯å†…æ ¸å¼€å‘人员，请考虑æäº¤ä½ çš„å¯†é’¥ä»¥å°†å…¶åŒ…å«åˆ°è¯¥å¯†é’¥çŽ¯ä¸ã€‚ + +.. _`å†…æ ¸å¼€å‘者密钥环`: https://korg.docs.kernel.org/pgpkeys.html diff --git a/Documentation/translations/zh_CN/process/submit-checklist.rst b/Documentation/translations/zh_CN/process/submit-checklist.rst index 3d6ee21c74ae..10536b74aeec 100644 --- a/Documentation/translations/zh_CN/process/submit-checklist.rst +++ b/Documentation/translations/zh_CN/process/submit-checklist.rst @@ -53,8 +53,7 @@ Linuxå†…æ ¸è¡¥ä¸æäº¤æ£€æŸ¥å• 9) 通过 sparse 清查。 （å‚è§ Documentation/translations/zh_CN/dev-tools/sparse.rst ） -10) 使用 ``make checkstack`` å’Œ ``make namespacecheck`` 并修å¤ä»–们å‘现的任何 - 问题。 +10) 使用 ``make checkstack`` 并修å¤ä»–们å‘现的任何问题。 .. note:: diff --git a/Documentation/translations/zh_CN/scheduler/sched-design-CFS.rst b/Documentation/translations/zh_CN/scheduler/sched-design-CFS.rst index 3076402406c4..abc6709ec3b2 100644 --- a/Documentation/translations/zh_CN/scheduler/sched-design-CFS.rst +++ b/Documentation/translations/zh_CN/scheduler/sched-design-CFS.rst @@ -80,7 +80,7 @@ p->se.vruntime。一旦p->se.vruntimeå˜å¾—足够大，其它的任务将æˆä¸ºæ CFS使用纳秒粒度的计时，ä¸ä¾èµ–于任何jiffies或HZçš„ç»†èŠ‚ã€‚å› æ¤CFS并ä¸åƒä¹‹å‰çš„è°ƒåº¦å™¨é‚£æ · 有“时间片â€çš„概念，也没有任何å¯å‘å¼çš„设计。唯一å¯è°ƒçš„å‚æ•°ï¼ˆä½ éœ€è¦æ‰“å¼€CONFIG_SCHED_DEBUG）是： - /sys/kernel/debug/sched/min_granularity_ns + /sys/kernel/debug/sched/base_slice_ns 它å¯ä»¥ç”¨æ¥å°†è°ƒåº¦å™¨ä»Žâ€œæ¡Œé¢â€æ¨¡å¼ï¼ˆä¹Ÿå°±æ˜¯ä½Žæ—¶å»¶ï¼‰è°ƒèŠ‚为“æœåŠ¡å™¨â€ï¼ˆä¹Ÿå°±æ˜¯é«˜æ‰¹å¤„ç†ï¼‰æ¨¡å¼ã€‚ 它的默认设置是适åˆæ¡Œé¢çš„工作负载。SCHED_BATCH也被CFS调度器模å—处ç†ã€‚ @@ -147,7 +147,7 @@ array）。 这个函数的行为基本上是出队，紧接ç€å…¥é˜Ÿï¼Œé™¤éžcompat_yield sysctl被开å¯ã€‚在那ç§æƒ…况下， å®ƒå°†è°ƒåº¦å®žä½“æ”¾åœ¨çº¢é»‘æ ‘çš„æœ€å³ç«¯ã€‚ - - check_preempt_curr(...) + - wakeup_preempt(...) 这个函数检查进入å¯è¿è¡ŒçŠ¶æ€çš„任务能å¦æŠ¢å 当å‰æ£åœ¨è¿è¡Œçš„任务。 @@ -155,9 +155,9 @@ array）。 这个函数选择接下æ¥æœ€é€‚åˆè¿è¡Œçš„任务。 - - set_curr_task(...) + - set_next_task(...) - 这个函数在任务改å˜è°ƒåº¦ç±»æˆ–改å˜ä»»åŠ¡ç»„时被调用。 + 这个函数在任务改å˜è°ƒåº¦ç±»ï¼Œæ”¹å˜ä»»åŠ¡ç»„时，或者任务被调度时被调用。 - task_tick(...) diff --git a/Documentation/translations/zh_CN/scheduler/schedutil.rst b/Documentation/translations/zh_CN/scheduler/schedutil.rst index d1ea68007520..7c8d87f21c42 100644 --- a/Documentation/translations/zh_CN/scheduler/schedutil.rst +++ b/Documentation/translations/zh_CN/scheduler/schedutil.rst @@ -89,16 +89,15 @@ r_cpu被定义为当å‰CPU的最高性能水平与系统ä¸ä»»ä½•å…¶å®ƒCPU的最 - Documentation/translations/zh_CN/scheduler/sched-capacity.rst:"1. CPU Capacity + 2. Task utilization" -UTIL_EST / UTIL_EST_FASTUP -========================== +UTIL_EST +======== 由于周期性任务的平å‡æ•°åœ¨ç¡çœ 时会衰å‡ï¼Œè€Œåœ¨è¿è¡Œæ—¶å…¶é¢„期利用率会和ç¡çœ å‰ç›¸åŒï¼Œ å› æ¤å®ƒä»¬åœ¨å†æ¬¡è¿è¡ŒåŽä¼šé¢ä¸´ï¼ˆDVFS）的上涨。 为了缓解这个问题，（一个默认使能的编译选项）UTIL_ESTé©±åŠ¨ä¸€ä¸ªæ— é™è„‰å†²å“应 （Infinite Impulse Response，IIR）的EWMA，“è¿è¡Œâ€å€¼åœ¨å‡ºé˜Ÿæ—¶æ˜¯æœ€é«˜çš„。 -å¦ä¸€ä¸ªé»˜è®¤ä½¿èƒ½çš„编译选项UTIL_EST_FASTUP修改了IIR滤波器，使其å…许立å³å¢žåŠ ， -仅在利用率下é™æ—¶è¡°å‡ã€‚ +UTIL_EST滤波使其在é‡åˆ°æ›´é«˜å€¼æ—¶ç«‹åˆ»å¢žåŠ ，而é‡åˆ°ä½Žå€¼æ—¶ä¼šç¼“慢衰å‡ã€‚ 进一æ¥ï¼Œè¿è¡Œé˜Ÿåˆ—的（å¯è¿è¡Œä»»åŠ¡çš„）利用率之和由下å¼è®¡ç®—： diff --git a/Documentation/translations/zh_CN/userspace-api/index.rst b/Documentation/translations/zh_CN/userspace-api/index.rst index 5dc0f2e69c17..5b14721c8264 100644 --- a/Documentation/translations/zh_CN/userspace-api/index.rst +++ b/Documentation/translations/zh_CN/userspace-api/index.rst @@ -17,11 +17,8 @@ Linux å†…æ ¸ç”¨æˆ·ç©ºé—´APIæŒ‡å— åœ¨ä»£ç æ ‘ä¸ä»ç„¶å¯ä»¥æ‰¾åˆ°æœ‰å…³ç”¨æˆ·ç©ºé—´çš„部分信æ¯ã€‚这个手册æ„在æˆä¸ºè¿™äº›ä¿¡æ¯ èšé›†çš„地方。 -.. class:: toc-title - - 目录 - .. toctree:: + :caption: 目录 :maxdepth: 2 no_new_privs diff --git a/Documentation/translations/zh_TW/IRQ.txt b/Documentation/translations/zh_TW/IRQ.txt index fd78ca720298..8115a7618307 100644 --- a/Documentation/translations/zh_TW/IRQ.txt +++ b/Documentation/translations/zh_TW/IRQ.txt @@ -7,7 +7,7 @@ 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.211@gmail.com> +Traditional Chinese maintainer: Hu Haowen <2023002089@link.tyut.edu.cn> --------------------------------------------------------------------- Documentation/core-api/irq/index.rst çš„ç¹é«”ä¸æ–‡ç¿»è¯ @@ -16,9 +16,9 @@ Documentation/core-api/irq/index.rst çš„ç¹é«”ä¸æ–‡ç¿»è¯ 者翻è¯å˜åœ¨å•é¡Œï¼Œè«‹è¯ç¹«ç¹é«”ä¸æ–‡ç‰ˆç¶è·è€…。 英文版ç¶è·è€…： Eric W. Biederman <ebiederman@xmission.com> -ç¹é«”ä¸æ–‡ç‰ˆç¶è·è€…： 胡皓文 Hu Haowen <src.res.211@gmail.com> -ç¹é«”ä¸æ–‡ç‰ˆç¿»è¯è€…： 胡皓文 Hu Haowen <src.res.211@gmail.com> -ç¹é«”ä¸æ–‡ç‰ˆæ ¡è¯è€…： 胡皓文 Hu Haowen <src.res.211@gmail.com> +ç¹é«”ä¸æ–‡ç‰ˆç¶è·è€…： 胡皓文 Hu Haowen <2023002089@link.tyut.edu.cn> +ç¹é«”ä¸æ–‡ç‰ˆç¿»è¯è€…： 胡皓文 Hu Haowen <2023002089@link.tyut.edu.cn> +ç¹é«”ä¸æ–‡ç‰ˆæ ¡è¯è€…： 胡皓文 Hu Haowen <2023002089@link.tyut.edu.cn> 以下爲æ£æ–‡ diff --git a/Documentation/translations/zh_TW/admin-guide/README.rst b/Documentation/translations/zh_TW/admin-guide/README.rst index 4cb581f5994a..a6e34c200ea3 100644 --- a/Documentation/translations/zh_TW/admin-guide/README.rst +++ b/Documentation/translations/zh_TW/admin-guide/README.rst @@ -7,7 +7,7 @@ :è¯è€…: å³æƒ³æˆ Wu XiangCheng <bobwxc@email.cn> - 胡皓文 Hu Haowen <src.res.211@gmail.com> + 胡皓文 Hu Haowen <2023002089@link.tyut.edu.cn> Linuxå…§æ ¸6.x版本 <http://kernel.org/> ========================================= diff --git a/Documentation/translations/zh_TW/admin-guide/bug-bisect.rst b/Documentation/translations/zh_TW/admin-guide/bug-bisect.rst index 3f10a9f8f223..1efe913b8da0 100644 --- a/Documentation/translations/zh_TW/admin-guide/bug-bisect.rst +++ b/Documentation/translations/zh_TW/admin-guide/bug-bisect.rst @@ -7,7 +7,7 @@ :è¯è€…: å³æƒ³æˆ Wu XiangCheng <bobwxc@email.cn> - 胡皓文 Hu Haowen <src.res.211@gmail.com> + 胡皓文 Hu Haowen <2023002089@link.tyut.edu.cn> 二分（bisect）缺陷 +++++++++++++++++++ diff --git a/Documentation/translations/zh_TW/admin-guide/bug-hunting.rst b/Documentation/translations/zh_TW/admin-guide/bug-hunting.rst index 631fd2650929..c139ec99cab1 100644 --- a/Documentation/translations/zh_TW/admin-guide/bug-hunting.rst +++ b/Documentation/translations/zh_TW/admin-guide/bug-hunting.rst @@ -7,7 +7,7 @@ :è¯è€…: å³æƒ³æˆ Wu XiangCheng <bobwxc@email.cn> - 胡皓文 Hu Haowen <src.res.211@gmail.com> + 胡皓文 Hu Haowen <2023002089@link.tyut.edu.cn> 追蹤缺陷 ========= diff --git a/Documentation/translations/zh_TW/admin-guide/clearing-warn-once.rst b/Documentation/translations/zh_TW/admin-guide/clearing-warn-once.rst index 6961006b4a2d..a3e82ff9daac 100644 --- a/Documentation/translations/zh_TW/admin-guide/clearing-warn-once.rst +++ b/Documentation/translations/zh_TW/admin-guide/clearing-warn-once.rst @@ -2,7 +2,7 @@ .. include:: ../disclaimer-zh_TW.rst -:Translator: 胡皓文 Hu Haowen <src.res.211@gmail.com> +:Translator: 胡皓文 Hu Haowen <2023002089@link.tyut.edu.cn> 清除 WARN_ONCE -------------- diff --git a/Documentation/translations/zh_TW/admin-guide/cpu-load.rst b/Documentation/translations/zh_TW/admin-guide/cpu-load.rst index cc046f3b7ffa..4c25a2105b39 100644 --- a/Documentation/translations/zh_TW/admin-guide/cpu-load.rst +++ b/Documentation/translations/zh_TW/admin-guide/cpu-load.rst @@ -2,7 +2,7 @@ .. include:: ../disclaimer-zh_TW.rst -:Translator: 胡皓文 Hu Haowen <src.res.211@gmail.com> +:Translator: 胡皓文 Hu Haowen <2023002089@link.tyut.edu.cn> ======== CPU è² è¼‰ diff --git a/Documentation/translations/zh_TW/admin-guide/index.rst b/Documentation/translations/zh_TW/admin-guide/index.rst index aba8939351e0..9335c0e9105d 100644 --- a/Documentation/translations/zh_TW/admin-guide/index.rst +++ b/Documentation/translations/zh_TW/admin-guide/index.rst @@ -4,7 +4,7 @@ :Original: :doc:`../../../admin-guide/index` :Translator: Alex Shi <alex.shi@linux.alibaba.com> - 胡皓文 Hu Haowen <src.res.211@gmail.com> + 胡皓文 Hu Haowen <2023002089@link.tyut.edu.cn> Linux å…§æ ¸ç”¨æˆ¶å’Œç®¡ç†å“¡æŒ‡å— ========================== diff --git a/Documentation/translations/zh_TW/admin-guide/init.rst b/Documentation/translations/zh_TW/admin-guide/init.rst index be6e34f5f7fa..4cef1994c650 100644 --- a/Documentation/translations/zh_TW/admin-guide/init.rst +++ b/Documentation/translations/zh_TW/admin-guide/init.rst @@ -7,7 +7,7 @@ :è¯è€…: å³æƒ³æˆ Wu XiangCheng <bobwxc@email.cn> - 胡皓文 Hu Haowen <src.res.211@gmail.com> + 胡皓文 Hu Haowen <2023002089@link.tyut.edu.cn> 解釋“No working init found.â€å•“å‹•æŽ›èµ·æ¶ˆæ¯ ========================================= diff --git a/Documentation/translations/zh_TW/admin-guide/reporting-issues.rst b/Documentation/translations/zh_TW/admin-guide/reporting-issues.rst index fe5a5a07d51a..bc132b25f2ae 100644 --- a/Documentation/translations/zh_TW/admin-guide/reporting-issues.rst +++ b/Documentation/translations/zh_TW/admin-guide/reporting-issues.rst @@ -9,7 +9,7 @@ :è¯è€…: å³æƒ³æˆ Wu XiangCheng <bobwxc@email.cn> - 胡皓文 Hu Haowen <src.res.211@gmail.com> + 胡皓文 Hu Haowen <2023002089@link.tyut.edu.cn> å ±å‘Šå•é¡Œ diff --git a/Documentation/translations/zh_TW/admin-guide/security-bugs.rst b/Documentation/translations/zh_TW/admin-guide/security-bugs.rst index c0e9fc247695..cfe1e58e116b 100644 --- a/Documentation/translations/zh_TW/admin-guide/security-bugs.rst +++ b/Documentation/translations/zh_TW/admin-guide/security-bugs.rst @@ -7,7 +7,7 @@ :è¯è€…: å³æƒ³æˆ Wu XiangCheng <bobwxc@email.cn> - 胡皓文 Hu Haowen <src.res.211@gmail.com> + 胡皓文 Hu Haowen <2023002089@link.tyut.edu.cn> 安全缺陷 ========= diff --git a/Documentation/translations/zh_TW/admin-guide/tainted-kernels.rst b/Documentation/translations/zh_TW/admin-guide/tainted-kernels.rst index 47629f6b05de..0d8046576d04 100644 --- a/Documentation/translations/zh_TW/admin-guide/tainted-kernels.rst +++ b/Documentation/translations/zh_TW/admin-guide/tainted-kernels.rst @@ -7,7 +7,7 @@ :è¯è€…: å³æƒ³æˆ Wu XiangCheng <bobwxc@email.cn> - 胡皓文 Hu Haowen <src.res.211@gmail.com> + 胡皓文 Hu Haowen <2023002089@link.tyut.edu.cn> å—æ±¡æŸ“çš„å…§æ ¸ ------------- diff --git a/Documentation/translations/zh_TW/admin-guide/unicode.rst b/Documentation/translations/zh_TW/admin-guide/unicode.rst index a2b48b5d0a64..f43edb2b5ed0 100644 --- a/Documentation/translations/zh_TW/admin-guide/unicode.rst +++ b/Documentation/translations/zh_TW/admin-guide/unicode.rst @@ -7,7 +7,7 @@ :è¯è€…: å³æƒ³æˆ Wu XiangCheng <bobwxc@email.cn> - 胡皓文 Hu Haowen <src.res.211@gmail.com> + 胡皓文 Hu Haowen <2023002089@link.tyut.edu.cn> Unicodeï¼ˆçµ±ä¸€ç¢¼ï¼‰æ”¯æŒ ====================== diff --git a/Documentation/translations/zh_TW/arch/arm64/amu.rst b/Documentation/translations/zh_TW/arch/arm64/amu.rst index 1b451eae2bee..3726c1671ab6 100644 --- a/Documentation/translations/zh_TW/arch/arm64/amu.rst +++ b/Documentation/translations/zh_TW/arch/arm64/amu.rst @@ -5,7 +5,7 @@ :Original: :ref:`Documentation/arch/arm64/amu.rst <amu_index>` Translator: Bailu Lin <bailu.lin@vivo.com> - Hu Haowen <src.res.211@gmail.com> + Hu Haowen <2023002089@link.tyut.edu.cn> ================================== AArch64 Linux ä¸æ“´å±•çš„活動監控單元 diff --git a/Documentation/translations/zh_TW/arch/arm64/booting.txt b/Documentation/translations/zh_TW/arch/arm64/booting.txt index be0de91ecebd..f1ac96370ace 100644 --- a/Documentation/translations/zh_TW/arch/arm64/booting.txt +++ b/Documentation/translations/zh_TW/arch/arm64/booting.txt @@ -10,7 +10,7 @@ or if there is a problem with the translation. M: Will Deacon <will.deacon@arm.com> zh_CN: Fu Wei <wefu@redhat.com> -zh_TW: Hu Haowen <src.res.211@gmail.com> +zh_TW: Hu Haowen <2023002089@link.tyut.edu.cn> C: 55f058e7574c3615dea4615573a19bdb258696c6 --------------------------------------------------------------------- Documentation/arch/arm64/booting.rst çš„ä¸æ–‡ç¿»è¯ @@ -23,7 +23,7 @@ Documentation/arch/arm64/booting.rst çš„ä¸æ–‡ç¿»è¯ ä¸æ–‡ç‰ˆç¶è·è€…： å‚…ç…’ Fu Wei <wefu@redhat.com> ä¸æ–‡ç‰ˆç¿»è¯è€…： å‚…ç…’ Fu Wei <wefu@redhat.com> ä¸æ–‡ç‰ˆæ ¡è¯è€…： å‚…ç…’ Fu Wei <wefu@redhat.com> -ç¹é«”ä¸æ–‡ç‰ˆæ ¡è¯è€…： 胡皓文 Hu Haowen <src.res.211@gmail.com> +ç¹é«”ä¸æ–‡ç‰ˆæ ¡è¯è€…： 胡皓文 Hu Haowen <2023002089@link.tyut.edu.cn> 本文翻è¯æ交時的 Git 檢出點爲： 55f058e7574c3615dea4615573a19bdb258696c6 以下爲æ£æ–‡ diff --git a/Documentation/translations/zh_TW/arch/arm64/elf_hwcaps.rst b/Documentation/translations/zh_TW/arch/arm64/elf_hwcaps.rst index d2c1c2f23812..cada25303e8d 100644 --- a/Documentation/translations/zh_TW/arch/arm64/elf_hwcaps.rst +++ b/Documentation/translations/zh_TW/arch/arm64/elf_hwcaps.rst @@ -5,7 +5,7 @@ :Original: :ref:`Documentation/arch/arm64/elf_hwcaps.rst <elf_hwcaps_index>` Translator: Bailu Lin <bailu.lin@vivo.com> - Hu Haowen <src.res.211@gmail.com> + Hu Haowen <2023002089@link.tyut.edu.cn> ================ ARM64 ELF hwcaps diff --git a/Documentation/translations/zh_TW/arch/arm64/hugetlbpage.rst b/Documentation/translations/zh_TW/arch/arm64/hugetlbpage.rst index a17858c978d6..b6849935e028 100644 --- a/Documentation/translations/zh_TW/arch/arm64/hugetlbpage.rst +++ b/Documentation/translations/zh_TW/arch/arm64/hugetlbpage.rst @@ -5,7 +5,7 @@ :Original: :ref:`Documentation/arch/arm64/hugetlbpage.rst <hugetlbpage_index>` Translator: Bailu Lin <bailu.lin@vivo.com> - Hu Haowen <src.res.211@gmail.com> + Hu Haowen <2023002089@link.tyut.edu.cn> ===================== ARM64ä¸çš„ HugeTLBpage diff --git a/Documentation/translations/zh_TW/arch/arm64/index.rst b/Documentation/translations/zh_TW/arch/arm64/index.rst index a62b5f06b66c..86014346792e 100644 --- a/Documentation/translations/zh_TW/arch/arm64/index.rst +++ b/Documentation/translations/zh_TW/arch/arm64/index.rst @@ -4,7 +4,7 @@ :Original: :ref:`Documentation/arch/arm64/index.rst <arm64_index>` :Translator: Bailu Lin <bailu.lin@vivo.com> - Hu Haowen <src.res.211@gmail.com> + Hu Haowen <2023002089@link.tyut.edu.cn> .. _tw_arm64_index: diff --git a/Documentation/translations/zh_TW/arch/arm64/legacy_instructions.txt b/Documentation/translations/zh_TW/arch/arm64/legacy_instructions.txt index 7d1f0593d7ca..5c664555a71a 100644 --- a/Documentation/translations/zh_TW/arch/arm64/legacy_instructions.txt +++ b/Documentation/translations/zh_TW/arch/arm64/legacy_instructions.txt @@ -11,7 +11,7 @@ or if there is a problem with the translation. Maintainer: Punit Agrawal <punit.agrawal@arm.com> Suzuki K. Poulose <suzuki.poulose@arm.com> Chinese maintainer: Fu Wei <wefu@redhat.com> -Traditional Chinese maintainer: Hu Haowen <src.res.211@gmail.com> +Traditional Chinese maintainer: Hu Haowen <2023002089@link.tyut.edu.cn> --------------------------------------------------------------------- Documentation/arch/arm64/legacy_instructions.rst çš„ä¸æ–‡ç¿»è¯ @@ -26,7 +26,7 @@ Documentation/arch/arm64/legacy_instructions.rst çš„ä¸æ–‡ç¿»è¯ ä¸æ–‡ç‰ˆç¶è·è€…： å‚…ç…’ Fu Wei <wefu@redhat.com> ä¸æ–‡ç‰ˆç¿»è¯è€…： å‚…ç…’ Fu Wei <wefu@redhat.com> ä¸æ–‡ç‰ˆæ ¡è¯è€…： å‚…ç…’ Fu Wei <wefu@redhat.com> -ç¹é«”ä¸æ–‡ç‰ˆæ ¡è¯è€…：胡皓文 Hu Haowen <src.res.211@gmail.com> +ç¹é«”ä¸æ–‡ç‰ˆæ ¡è¯è€…：胡皓文 Hu Haowen <2023002089@link.tyut.edu.cn> 以下爲æ£æ–‡ --------------------------------------------------------------------- diff --git a/Documentation/translations/zh_TW/arch/arm64/memory.txt b/Documentation/translations/zh_TW/arch/arm64/memory.txt index e41c518e71c6..6ee2239c293f 100644 --- a/Documentation/translations/zh_TW/arch/arm64/memory.txt +++ b/Documentation/translations/zh_TW/arch/arm64/memory.txt @@ -10,7 +10,7 @@ or if there is a problem with the translation. Maintainer: Catalin Marinas <catalin.marinas@arm.com> Chinese maintainer: Fu Wei <wefu@redhat.com> -Traditional Chinese maintainer: Hu Haowen <src.res.211@gmail.com> +Traditional Chinese maintainer: Hu Haowen <2023002089@link.tyut.edu.cn> --------------------------------------------------------------------- Documentation/arch/arm64/memory.rst çš„ä¸æ–‡ç¿»è¯ @@ -24,7 +24,7 @@ Documentation/arch/arm64/memory.rst çš„ä¸æ–‡ç¿»è¯ ä¸æ–‡ç‰ˆç¶è·è€…： å‚…ç…’ Fu Wei <wefu@redhat.com> ä¸æ–‡ç‰ˆç¿»è¯è€…： å‚…ç…’ Fu Wei <wefu@redhat.com> ä¸æ–‡ç‰ˆæ ¡è¯è€…： å‚…ç…’ Fu Wei <wefu@redhat.com> -ç¹é«”ä¸æ–‡ç‰ˆæ ¡è¯è€…： 胡皓文 Hu Haowen <src.res.211@gmail.com> +ç¹é«”ä¸æ–‡ç‰ˆæ ¡è¯è€…： 胡皓文 Hu Haowen <2023002089@link.tyut.edu.cn> 以下爲æ£æ–‡ --------------------------------------------------------------------- diff --git a/Documentation/translations/zh_TW/arch/arm64/perf.rst b/Documentation/translations/zh_TW/arch/arm64/perf.rst index 405d5f66964f..ce083ba63872 100644 --- a/Documentation/translations/zh_TW/arch/arm64/perf.rst +++ b/Documentation/translations/zh_TW/arch/arm64/perf.rst @@ -5,7 +5,7 @@ :Original: :ref:`Documentation/arch/arm64/perf.rst <perf_index>` Translator: Bailu Lin <bailu.lin@vivo.com> - Hu Haowen <src.res.211@gmail.com> + Hu Haowen <2023002089@link.tyut.edu.cn> ============= Perf 事件屬性 diff --git a/Documentation/translations/zh_TW/arch/arm64/silicon-errata.txt b/Documentation/translations/zh_TW/arch/arm64/silicon-errata.txt index 70371807ca83..16d73b6c309f 100644 --- a/Documentation/translations/zh_TW/arch/arm64/silicon-errata.txt +++ b/Documentation/translations/zh_TW/arch/arm64/silicon-errata.txt @@ -10,7 +10,7 @@ or if there is a problem with the translation. M: Will Deacon <will.deacon@arm.com> zh_CN: Fu Wei <wefu@redhat.com> -zh_TW: Hu Haowen <src.res.211@gmail.com> +zh_TW: Hu Haowen <2023002089@link.tyut.edu.cn> C: 1926e54f115725a9248d0c4c65c22acaf94de4c4 --------------------------------------------------------------------- Documentation/arch/arm64/silicon-errata.rst çš„ä¸æ–‡ç¿»è¯ @@ -23,7 +23,7 @@ Documentation/arch/arm64/silicon-errata.rst çš„ä¸æ–‡ç¿»è¯ ä¸æ–‡ç‰ˆç¶è·è€…： å‚…ç…’ Fu Wei <wefu@redhat.com> ä¸æ–‡ç‰ˆç¿»è¯è€…： å‚…ç…’ Fu Wei <wefu@redhat.com> ä¸æ–‡ç‰ˆæ ¡è¯è€…： å‚…ç…’ Fu Wei <wefu@redhat.com> -ç¹é«”ä¸æ–‡ç‰ˆæ ¡è¯è€…： 胡皓文 Hu Haowen <src.res.211@gmail.com> +ç¹é«”ä¸æ–‡ç‰ˆæ ¡è¯è€…： 胡皓文 Hu Haowen <2023002089@link.tyut.edu.cn> 本文翻è¯æ交時的 Git 檢出點爲： 1926e54f115725a9248d0c4c65c22acaf94de4c4 以下爲æ£æ–‡ diff --git a/Documentation/translations/zh_TW/arch/arm64/tagged-pointers.txt b/Documentation/translations/zh_TW/arch/arm64/tagged-pointers.txt index 9812d99549ba..e86ffa893ef6 100644 --- a/Documentation/translations/zh_TW/arch/arm64/tagged-pointers.txt +++ b/Documentation/translations/zh_TW/arch/arm64/tagged-pointers.txt @@ -10,7 +10,7 @@ or if there is a problem with the translation. Maintainer: Will Deacon <will.deacon@arm.com> Chinese maintainer: Fu Wei <wefu@redhat.com> -Traditional Chinese maintainer: Hu Haowen <src.res.211@gmail.com> +Traditional Chinese maintainer: Hu Haowen <2023002089@link.tyut.edu.cn> --------------------------------------------------------------------- Documentation/arch/arm64/tagged-pointers.rst çš„ä¸æ–‡ç¿»è¯ @@ -22,7 +22,7 @@ Documentation/arch/arm64/tagged-pointers.rst çš„ä¸æ–‡ç¿»è¯ ä¸æ–‡ç‰ˆç¶è·è€…： å‚…ç…’ Fu Wei <wefu@redhat.com> ä¸æ–‡ç‰ˆç¿»è¯è€…： å‚…ç…’ Fu Wei <wefu@redhat.com> ä¸æ–‡ç‰ˆæ ¡è¯è€…： å‚…ç…’ Fu Wei <wefu@redhat.com> -ç¹é«”ä¸æ–‡ç‰ˆæ ¡è¯è€…： 胡皓文 Hu Haowen <src.res.211@gmail.com> +ç¹é«”ä¸æ–‡ç‰ˆæ ¡è¯è€…： 胡皓文 Hu Haowen <2023002089@link.tyut.edu.cn> 以下爲æ£æ–‡ --------------------------------------------------------------------- diff --git a/Documentation/translations/zh_TW/dev-tools/sparse.rst b/Documentation/translations/zh_TW/dev-tools/sparse.rst index 11d64709d6a4..55f0ad2c0beb 100644 --- a/Documentation/translations/zh_TW/dev-tools/sparse.rst +++ b/Documentation/translations/zh_TW/dev-tools/sparse.rst @@ -6,19 +6,19 @@ 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.211@gmail.com> ---------------------------------------------------------------------- +Traditional Chinese maintainer: Hu Haowen <2023002089@link.tyut.edu.cn> +------------------------------------------------------------------------- Documentation/dev-tools/sparse.rst çš„ç¹é«”ä¸æ–‡ç¿»è¯ 如果想評論或更新本文的內容，請直接è¯ç¹«åŽŸæ–‡æª”çš„ç¶è·è€…ã€‚å¦‚æžœä½ ä½¿ç”¨è‹±æ–‡ 交æµæœ‰å›°é›£çš„話，也å¯ä»¥å‘ç¹é«”ä¸æ–‡ç‰ˆç¶è·è€…求助。如果本翻è¯æ›´æ–°ä¸åŠæ™‚或 者翻è¯å˜åœ¨å•é¡Œï¼Œè«‹è¯ç¹«ç¹é«”ä¸æ–‡ç‰ˆç¶è·è€…。 -ç¹é«”ä¸æ–‡ç‰ˆç¶è·è€…： 胡皓文 Hu Haowen <src.res.211@gmail.com> -ç¹é«”ä¸æ–‡ç‰ˆç¿»è¯è€…： 胡皓文 Hu Haowen <src.res.211@gmail.com> +ç¹é«”ä¸æ–‡ç‰ˆç¶è·è€…： 胡皓文 Hu Haowen <2023002089@link.tyut.edu.cn> +ç¹é«”ä¸æ–‡ç‰ˆç¿»è¯è€…： 胡皓文 Hu Haowen <2023002089@link.tyut.edu.cn> 以下爲æ£æ–‡ ---------------------------------------------------------------------- +------------------------------------------------------------------------- Copyright 2004 Linus Torvalds Copyright 2004 Pavel Machek <pavel@ucw.cz> diff --git a/Documentation/translations/zh_TW/dev-tools/testing-overview.rst b/Documentation/translations/zh_TW/dev-tools/testing-overview.rst index fb3f691f46c3..3b08aad1da00 100644 --- a/Documentation/translations/zh_TW/dev-tools/testing-overview.rst +++ b/Documentation/translations/zh_TW/dev-tools/testing-overview.rst @@ -3,7 +3,7 @@ .. include:: ../disclaimer-zh_TW.rst :Original: Documentation/dev-tools/testing-overview.rst -:Translator: 胡皓文 Hu Haowen <src.res.211@gmail.com> +:Translator: 胡皓文 Hu Haowen <2023002089@link.tyut.edu.cn> ============ å…§æ ¸æ¸¬è©¦æŒ‡å— diff --git a/Documentation/translations/zh_TW/disclaimer-zh_TW.rst b/Documentation/translations/zh_TW/disclaimer-zh_TW.rst index 0d0ffb1ca4e8..28b734c223b6 100644 --- a/Documentation/translations/zh_TW/disclaimer-zh_TW.rst +++ b/Documentation/translations/zh_TW/disclaimer-zh_TW.rst @@ -7,5 +7,5 @@ .. note:: 如果您發ç¾æœ¬æ–‡æª”與原始文件有任何ä¸åŒæˆ–者有翻è¯å•é¡Œï¼Œè«‹è¯ç¹«è©²æ–‡ä»¶çš„è¯è€…， - 或者發é€é›»å郵件給胡皓文以ç²å–幫助：<src.res.211@gmail.com>。 + 或者發é€é›»å郵件給胡皓文以ç²å–幫助：<2023002089@link.tyut.edu.cn>。 diff --git a/Documentation/translations/zh_TW/filesystems/debugfs.rst b/Documentation/translations/zh_TW/filesystems/debugfs.rst index 78e2e08af95e..cda7d0e18b9b 100644 --- a/Documentation/translations/zh_TW/filesystems/debugfs.rst +++ b/Documentation/translations/zh_TW/filesystems/debugfs.rst @@ -14,7 +14,7 @@ Debugfs ä¸æ–‡ç‰ˆç¶è·è€…： ç¾…æ¥šæˆ Chucheng Luo <luochucheng@vivo.com> ä¸æ–‡ç‰ˆç¿»è¯è€…： ç¾…æ¥šæˆ Chucheng Luo <luochucheng@vivo.com> ä¸æ–‡ç‰ˆæ ¡è¯è€…: ç¾…æ¥šæˆ Chucheng Luo <luochucheng@vivo.com> - ç¹é«”ä¸æ–‡ç‰ˆæ ¡è¯è€…: 胡皓文 Hu Haowen <src.res.211@gmail.com> + ç¹é«”ä¸æ–‡ç‰ˆæ ¡è¯è€…: 胡皓文 Hu Haowen <2023002089@link.tyut.edu.cn> diff --git a/Documentation/translations/zh_TW/filesystems/index.rst b/Documentation/translations/zh_TW/filesystems/index.rst index d7f9d61f654c..88f0e632bfe2 100644 --- a/Documentation/translations/zh_TW/filesystems/index.rst +++ b/Documentation/translations/zh_TW/filesystems/index.rst @@ -4,7 +4,7 @@ :Original: :ref:`Documentation/filesystems/index.rst <filesystems_index>` :Translator: Wang Wenhu <wenhu.wang@vivo.com> - Hu Haowen <src.res.211@gmail.com> + Hu Haowen <2023002089@link.tyut.edu.cn> .. _tw_filesystems_index: diff --git a/Documentation/translations/zh_TW/filesystems/sysfs.txt b/Documentation/translations/zh_TW/filesystems/sysfs.txt index ebe90651fc3b..978462d5fe14 100644 --- a/Documentation/translations/zh_TW/filesystems/sysfs.txt +++ b/Documentation/translations/zh_TW/filesystems/sysfs.txt @@ -22,7 +22,7 @@ Documentation/filesystems/sysfs.rst çš„ä¸æ–‡ç¿»è¯ ä¸æ–‡ç‰ˆç¶è·è€…： å‚…ç…’ Fu Wei <tekkamanninja@gmail.com> ä¸æ–‡ç‰ˆç¿»è¯è€…： å‚…ç…’ Fu Wei <tekkamanninja@gmail.com> ä¸æ–‡ç‰ˆæ ¡è¯è€…： å‚…ç…’ Fu Wei <tekkamanninja@gmail.com> -ç¹é«”ä¸æ–‡ç‰ˆæ ¡è¯è€…：胡皓文 Hu Haowen <src.res.211@gmail.com> +ç¹é«”ä¸æ–‡ç‰ˆæ ¡è¯è€…：胡皓文 Hu Haowen <2023002089@link.tyut.edu.cn> 以下爲æ£æ–‡ diff --git a/Documentation/translations/zh_TW/filesystems/virtiofs.rst b/Documentation/translations/zh_TW/filesystems/virtiofs.rst index 6150ad964e78..704a0ee44fd2 100644 --- a/Documentation/translations/zh_TW/filesystems/virtiofs.rst +++ b/Documentation/translations/zh_TW/filesystems/virtiofs.rst @@ -10,7 +10,7 @@ ä¸æ–‡ç‰ˆç¶è·è€…： 王文虎 Wang Wenhu <wenhu.wang@vivo.com> ä¸æ–‡ç‰ˆç¿»è¯è€…： 王文虎 Wang Wenhu <wenhu.wang@vivo.com> ä¸æ–‡ç‰ˆæ ¡è¯è€…： 王文虎 Wang Wenhu <wenhu.wang@vivo.com> - ç¹é«”ä¸æ–‡ç‰ˆæ ¡è¯è€…：胡皓文 Hu Haowen <src.res.211@gmail.com> + ç¹é«”ä¸æ–‡ç‰ˆæ ¡è¯è€…：胡皓文 Hu Haowen <2023002089@link.tyut.edu.cn> =========================================== virtiofs: virtio-fs 主機<->客機共享文件系統 diff --git a/Documentation/translations/zh_TW/gpio.txt b/Documentation/translations/zh_TW/gpio.txt index 555e4b11a5c7..b9b48012c62e 100644 --- a/Documentation/translations/zh_TW/gpio.txt +++ b/Documentation/translations/zh_TW/gpio.txt @@ -8,7 +8,7 @@ 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.211@gmail.com> +Traditional Chinese maintainer: Hu Haowen <2023002089@link.tyut.edu.cn> --------------------------------------------------------------------- Documentation/admin-guide/gpio çš„ç¹é«”ä¸æ–‡ç¿»è¯ @@ -18,9 +18,9 @@ Documentation/admin-guide/gpio çš„ç¹é«”ä¸æ–‡ç¿»è¯ 英文版ç¶è·è€…： Grant Likely <grant.likely@secretlab.ca> Linus Walleij <linus.walleij@linaro.org> -ç¹é«”ä¸æ–‡ç‰ˆç¶è·è€…： 胡皓文 Hu Haowen <src.res.211@gmail.com> -ç¹é«”ä¸æ–‡ç‰ˆç¿»è¯è€…： 胡皓文 Hu Haowen <src.res.211@gmail.com> -ç¹é«”ä¸æ–‡ç‰ˆæ ¡è¯è€…： 胡皓文 Hu Haowen <src.res.211@gmail.com> +ç¹é«”ä¸æ–‡ç‰ˆç¶è·è€…： 胡皓文 Hu Haowen <2023002089@link.tyut.edu.cn> +ç¹é«”ä¸æ–‡ç‰ˆç¿»è¯è€…： 胡皓文 Hu Haowen <2023002089@link.tyut.edu.cn> +ç¹é«”ä¸æ–‡ç‰ˆæ ¡è¯è€…： 胡皓文 Hu Haowen <2023002089@link.tyut.edu.cn> 以下爲æ£æ–‡ --------------------------------------------------------------------- diff --git a/Documentation/translations/zh_TW/index.rst b/Documentation/translations/zh_TW/index.rst index 563ac9bfc66b..660a74d2023c 100644 --- a/Documentation/translations/zh_TW/index.rst +++ b/Documentation/translations/zh_TW/index.rst @@ -15,7 +15,7 @@ .. note:: å…§æ ¸æ–‡æª”ç¹é«”ä¸æ–‡ç‰ˆçš„ç¿»è¯å·¥ä½œæ£åœ¨é€²è¡Œä¸ã€‚如果您願æ„並且有時間åƒèˆ‡é€™é …å·¥ - 作，æ¡è¿Žæ交補ä¸çµ¦èƒ¡çš“æ–‡ <src.res.211@gmail.com>。 + 作，æ¡è¿Žæ交補ä¸çµ¦èƒ¡çš“æ–‡ <2023002089@link.tyut.edu.cn>。 與Linux å…§æ ¸ç¤¾å€ä¸€èµ·å·¥ä½œ ------------------------ diff --git a/Documentation/translations/zh_TW/io_ordering.txt b/Documentation/translations/zh_TW/io_ordering.txt index 03f86840c139..00b374092d7e 100644 --- a/Documentation/translations/zh_TW/io_ordering.txt +++ b/Documentation/translations/zh_TW/io_ordering.txt @@ -6,7 +6,7 @@ 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.211@gmail.com> +Traditional Chinese maintainer: Hu Haowen <2023002089@link.tyut.edu.cn> --------------------------------------------------------------------- Documentation/driver-api/io_ordering.rst çš„ç¹é«”ä¸æ–‡ç¿»è¯ @@ -14,9 +14,9 @@ Documentation/driver-api/io_ordering.rst çš„ç¹é«”ä¸æ–‡ç¿»è¯ 交æµæœ‰å›°é›£çš„話，也å¯ä»¥å‘ç¹é«”ä¸æ–‡ç‰ˆç¶è·è€…求助。如果本翻è¯æ›´æ–°ä¸åŠæ™‚或 者翻è¯å˜åœ¨å•é¡Œï¼Œè«‹è¯ç¹«ç¹é«”ä¸æ–‡ç‰ˆç¶è·è€…。 -ç¹é«”ä¸æ–‡ç‰ˆç¶è·è€…： 胡皓文 Hu Haowen <src.res.211@gmail.com> -ç¹é«”ä¸æ–‡ç‰ˆç¿»è¯è€…： 胡皓文 Hu Haowen <src.res.211@gmail.com> -ç¹é«”ä¸æ–‡ç‰ˆæ ¡è¯è€…： 胡皓文 Hu Haowen <src.res.211@gmail.com> +ç¹é«”ä¸æ–‡ç‰ˆç¶è·è€…： 胡皓文 Hu Haowen <2023002089@link.tyut.edu.cn> +ç¹é«”ä¸æ–‡ç‰ˆç¿»è¯è€…： 胡皓文 Hu Haowen <2023002089@link.tyut.edu.cn> +ç¹é«”ä¸æ–‡ç‰ˆæ ¡è¯è€…： 胡皓文 Hu Haowen <2023002089@link.tyut.edu.cn> 以下爲æ£æ–‡ diff --git a/Documentation/translations/zh_TW/process/1.Intro.rst b/Documentation/translations/zh_TW/process/1.Intro.rst index 6e754ac48964..345c4cbe9b55 100644 --- a/Documentation/translations/zh_TW/process/1.Intro.rst +++ b/Documentation/translations/zh_TW/process/1.Intro.rst @@ -11,7 +11,7 @@ :æ ¡è¯: å³æƒ³æˆ Wu XiangCheng <bobwxc@email.cn> - 胡皓文 Hu Haowen <src.res.211@gmail.com> + 胡皓文 Hu Haowen <2023002089@link.tyut.edu.cn> .. _tw_development_process_intro: diff --git a/Documentation/translations/zh_TW/process/2.Process.rst b/Documentation/translations/zh_TW/process/2.Process.rst index 49385d65c216..f45ddba6238f 100644 --- a/Documentation/translations/zh_TW/process/2.Process.rst +++ b/Documentation/translations/zh_TW/process/2.Process.rst @@ -11,7 +11,7 @@ :æ ¡è¯: å³æƒ³æˆ Wu XiangCheng <bobwxc@email.cn> - 胡皓文 Hu Haowen <src.res.211@gmail.com> + 胡皓文 Hu Haowen <2023002089@link.tyut.edu.cn> .. _tw_development_process: diff --git a/Documentation/translations/zh_TW/process/3.Early-stage.rst b/Documentation/translations/zh_TW/process/3.Early-stage.rst index a6959e6350f4..a58fc9e0ea99 100644 --- a/Documentation/translations/zh_TW/process/3.Early-stage.rst +++ b/Documentation/translations/zh_TW/process/3.Early-stage.rst @@ -11,7 +11,7 @@ :æ ¡è¯: å³æƒ³æˆ Wu XiangCheng <bobwxc@email.cn> - 胡皓文 Hu Haowen <src.res.211@gmail.com> + 胡皓文 Hu Haowen <2023002089@link.tyut.edu.cn> .. _tw_development_early_stage: diff --git a/Documentation/translations/zh_TW/process/4.Coding.rst b/Documentation/translations/zh_TW/process/4.Coding.rst index 7a4e01eabd81..bdd2abe4daf4 100644 --- a/Documentation/translations/zh_TW/process/4.Coding.rst +++ b/Documentation/translations/zh_TW/process/4.Coding.rst @@ -11,7 +11,7 @@ :æ ¡è¯: å³æƒ³æˆ Wu XiangCheng <bobwxc@email.cn> - 胡皓文 Hu Haowen <src.res.211@gmail.com> + 胡皓文 Hu Haowen <2023002089@link.tyut.edu.cn> .. _tw_development_coding: diff --git a/Documentation/translations/zh_TW/process/5.Posting.rst b/Documentation/translations/zh_TW/process/5.Posting.rst index d398dda427aa..7d66a1c638be 100644 --- a/Documentation/translations/zh_TW/process/5.Posting.rst +++ b/Documentation/translations/zh_TW/process/5.Posting.rst @@ -11,7 +11,7 @@ :æ ¡è¯: å³æƒ³æˆ Wu XiangCheng <bobwxc@email.cn> - 胡皓文 Hu Haowen <src.res.211@gmail.com> + 胡皓文 Hu Haowen <2023002089@link.tyut.edu.cn> .. _tw_development_posting: diff --git a/Documentation/translations/zh_TW/process/6.Followthrough.rst b/Documentation/translations/zh_TW/process/6.Followthrough.rst index bcc885ae1b8e..f3b195966632 100644 --- a/Documentation/translations/zh_TW/process/6.Followthrough.rst +++ b/Documentation/translations/zh_TW/process/6.Followthrough.rst @@ -11,7 +11,7 @@ :æ ¡è¯: å³æƒ³æˆ Wu XiangCheng <bobwxc@email.cn> - 胡皓文 Hu Haowen <src.res.211@gmail.com> + 胡皓文 Hu Haowen <2023002089@link.tyut.edu.cn> .. _tw_development_followthrough: diff --git a/Documentation/translations/zh_TW/process/7.AdvancedTopics.rst b/Documentation/translations/zh_TW/process/7.AdvancedTopics.rst index db74d8ca3f3b..b449d67e3ad9 100644 --- a/Documentation/translations/zh_TW/process/7.AdvancedTopics.rst +++ b/Documentation/translations/zh_TW/process/7.AdvancedTopics.rst @@ -11,7 +11,7 @@ :æ ¡è¯: å³æƒ³æˆ Wu XiangCheng <bobwxc@email.cn> - 胡皓文 Hu Haowen <src.res.211@gmail.com> + 胡皓文 Hu Haowen <2023002089@link.tyut.edu.cn> .. _tw_development_advancedtopics: diff --git a/Documentation/translations/zh_TW/process/8.Conclusion.rst b/Documentation/translations/zh_TW/process/8.Conclusion.rst index a0c00741f912..d1634421b62c 100644 --- a/Documentation/translations/zh_TW/process/8.Conclusion.rst +++ b/Documentation/translations/zh_TW/process/8.Conclusion.rst @@ -10,7 +10,7 @@ :æ ¡è¯: å³æƒ³æˆ Wu XiangCheng <bobwxc@email.cn> - 胡皓文 Hu Haowen <src.res.211@gmail.com> + 胡皓文 Hu Haowen <2023002089@link.tyut.edu.cn> .. _tw_development_conclusion: diff --git a/Documentation/translations/zh_TW/process/code-of-conduct-interpretation.rst b/Documentation/translations/zh_TW/process/code-of-conduct-interpretation.rst index 48df918000e9..fbe66b001322 100644 --- a/Documentation/translations/zh_TW/process/code-of-conduct-interpretation.rst +++ b/Documentation/translations/zh_TW/process/code-of-conduct-interpretation.rst @@ -4,7 +4,7 @@ :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.211@gmail.com> + Hu Haowen <2023002089@link.tyut.edu.cn> .. _tw_code_of_conduct_interpretation: diff --git a/Documentation/translations/zh_TW/process/code-of-conduct.rst b/Documentation/translations/zh_TW/process/code-of-conduct.rst index a7a31de03526..d24f1695bd02 100644 --- a/Documentation/translations/zh_TW/process/code-of-conduct.rst +++ b/Documentation/translations/zh_TW/process/code-of-conduct.rst @@ -4,7 +4,7 @@ :Original: :ref:`Documentation/process/code-of-conduct.rst <code_of_conduct>` :Translator: Alex Shi <alex.shi@linux.alibaba.com> - Hu Haowen <src.res.211@gmail.com> + Hu Haowen <2023002089@link.tyut.edu.cn> .. _tw_code_of_conduct: diff --git a/Documentation/translations/zh_TW/process/coding-style.rst b/Documentation/translations/zh_TW/process/coding-style.rst index 5749363de421..f11dbb65ca21 100644 --- a/Documentation/translations/zh_TW/process/coding-style.rst +++ b/Documentation/translations/zh_TW/process/coding-style.rst @@ -17,7 +17,7 @@ - 管æ—æ± Xudong Guan <xudong.guan@gmail.com> - Li Zefan <lizf@cn.fujitsu.com> - Wang Chen <wangchen@cn.fujitsu.com> - - Hu Haowen <src.res.211@gmail.com> + - Hu Haowen <2023002089@link.tyut.edu.cn> Linux å…§æ ¸ä»£ç¢¼é¢¨æ ¼ ================== diff --git a/Documentation/translations/zh_TW/process/development-process.rst b/Documentation/translations/zh_TW/process/development-process.rst index 7d803d3db89e..305d9472b017 100644 --- a/Documentation/translations/zh_TW/process/development-process.rst +++ b/Documentation/translations/zh_TW/process/development-process.rst @@ -4,16 +4,17 @@ :Original: :ref:`Documentation/process/development-process.rst <development_process_main>` :Translator: Alex Shi <alex.shi@linux.alibaba.com> - Hu Haowen <src.res.211@gmail.com> + Hu Haowen <2023002089@link.tyut.edu.cn> .. _tw_development_process_main: å…§æ ¸é–‹ç™¼éŽç¨‹æŒ‡å— ================ -內容: +本文檔的目的是幫助開發人員（åŠå…¶ç¶“ç†ï¼‰ä»¥æœ€å°çš„挫折感與開發社å€åˆä½œã€‚它試圖記錄這個社å€å¦‚何以一種ä¸ç†Ÿæ‚‰Linuxå…§æ ¸é–‹ç™¼ï¼ˆæˆ–è€…å¯¦éš›ä¸Šæ˜¯è‡ªç”±è»Ÿé«”é–‹ç™¼ï¼‰çš„äººå¯ä»¥è¨ªå•çš„æ–¹å¼å·¥ä½œã€‚雖然這裡有一些技術資料，但這是一個é¢å‘éŽç¨‹çš„討論，ä¸éœ€è¦æ·±å…¥äº†è§£å…§æ ¸ç·¨ç¨‹å°±å¯ä»¥ç†è§£ã€‚ .. toctree:: + :caption: 內容 :numbered: :maxdepth: 2 @@ -27,4 +28,3 @@ 8.Conclusion 本文檔的目的是幫助開發人員（åŠå…¶ç¶“ç†ï¼‰ä»¥æœ€å°çš„挫折感與開發社å€åˆä½œã€‚它試圖記錄這個社å€å¦‚何以一種ä¸ç†Ÿæ‚‰Linuxå…§æ ¸é–‹ç™¼ï¼ˆæˆ–è€…å¯¦éš›ä¸Šæ˜¯è‡ªç”±è»Ÿä»¶é–‹ç™¼ï¼‰çš„äººå¯ä»¥è¨ªå•çš„æ–¹å¼å·¥ä½œã€‚雖然這è£æœ‰ä¸€äº›æŠ€è¡“資料，但這是一個é¢å‘éŽç¨‹çš„討論，ä¸éœ€è¦æ·±å…¥çžè§£å…§æ ¸ç·¨ç¨‹å°±å¯ä»¥ç†è§£ã€‚ - diff --git a/Documentation/translations/zh_TW/process/email-clients.rst b/Documentation/translations/zh_TW/process/email-clients.rst index 55e10d3fc28a..a5ac9400a9f5 100644 --- a/Documentation/translations/zh_TW/process/email-clients.rst +++ b/Documentation/translations/zh_TW/process/email-clients.rst @@ -15,7 +15,7 @@ - Yinglin Luan <synmyth@gmail.com> - Xiaochen Wang <wangxiaochen0@gmail.com> - yaxinsn <yaxinsn@163.com> - - Hu Haowen <src.res.211@gmail.com> + - Hu Haowen <2023002089@link.tyut.edu.cn> Linux郵件客戶端é…ç½®ä¿¡æ¯ ======================= diff --git a/Documentation/translations/zh_TW/process/embargoed-hardware-issues.rst b/Documentation/translations/zh_TW/process/embargoed-hardware-issues.rst index b9f6ab7b6666..3cce7db2ab7e 100644 --- a/Documentation/translations/zh_TW/process/embargoed-hardware-issues.rst +++ b/Documentation/translations/zh_TW/process/embargoed-hardware-issues.rst @@ -4,7 +4,7 @@ :Original: :ref:`Documentation/process/embargoed-hardware-issues.rst <embargoed_hardware_issues>` :Translator: Alex Shi <alex.shi@linux.alibaba.com> - Hu Haowen <src.res.211@gmail.com> + Hu Haowen <2023002089@link.tyut.edu.cn> 被é™åˆ¶çš„硬件å•é¡Œ ================ diff --git a/Documentation/translations/zh_TW/process/howto.rst b/Documentation/translations/zh_TW/process/howto.rst index 306f5b77b4b8..80c416483e73 100644 --- a/Documentation/translations/zh_TW/process/howto.rst +++ b/Documentation/translations/zh_TW/process/howto.rst @@ -16,7 +16,7 @@ é¾å®‡ TripleX Chung <xxx.phy@gmail.com> é™³ç¦ Maggie Chen <chenqi@beyondsoft.com> çŽ‹è° Wang Cong <xiyou.wangcong@gmail.com> - 胡皓文 Hu Haowen <src.res.211@gmail.com> + 胡皓文 Hu Haowen <2023002089@link.tyut.edu.cn> 如何åƒèˆ‡Linuxå…§æ ¸é–‹ç™¼ ===================== diff --git a/Documentation/translations/zh_TW/process/index.rst b/Documentation/translations/zh_TW/process/index.rst index 6a0d98b2f9ee..65922d9faa20 100644 --- a/Documentation/translations/zh_TW/process/index.rst +++ b/Documentation/translations/zh_TW/process/index.rst @@ -9,7 +9,7 @@ :Original: :ref:`Documentation/process/index.rst <process_index>` :Translator: Alex Shi <alex.shi@linux.alibaba.com> - Hu Haowen <src.res.211@gmail.com> + Hu Haowen <2023002089@link.tyut.edu.cn> .. _tw_process_index: diff --git a/Documentation/translations/zh_TW/process/kernel-driver-statement.rst b/Documentation/translations/zh_TW/process/kernel-driver-statement.rst index e967089d2e1f..23d5cae9685b 100644 --- a/Documentation/translations/zh_TW/process/kernel-driver-statement.rst +++ b/Documentation/translations/zh_TW/process/kernel-driver-statement.rst @@ -6,7 +6,7 @@ :Original: :ref:`Documentation/process/kernel-driver-statement.rst <process_statement_driver>` :Translator: Alex Shi <alex.shi@linux.alibaba.com> - Hu Haowen <src.res.211@gmail.com> + Hu Haowen <2023002089@link.tyut.edu.cn> å…§æ ¸é©…å‹•è²æ˜Ž ------------ diff --git a/Documentation/translations/zh_TW/process/kernel-enforcement-statement.rst b/Documentation/translations/zh_TW/process/kernel-enforcement-statement.rst index 2861f4a15721..524eb4ac26cc 100644 --- a/Documentation/translations/zh_TW/process/kernel-enforcement-statement.rst +++ b/Documentation/translations/zh_TW/process/kernel-enforcement-statement.rst @@ -6,7 +6,7 @@ :Original: :ref:`Documentation/process/kernel-enforcement-statement.rst <process_statement_kernel>` :Translator: Alex Shi <alex.shi@linux.alibaba.com> - Hu Haowen <src.res.211@gmail.com> + Hu Haowen <2023002089@link.tyut.edu.cn> Linux å…§æ ¸åŸ·è¡Œè²æ˜Ž ------------------ diff --git a/Documentation/translations/zh_TW/process/license-rules.rst b/Documentation/translations/zh_TW/process/license-rules.rst index 2c43bcf2ac79..594255856b68 100644 --- a/Documentation/translations/zh_TW/process/license-rules.rst +++ b/Documentation/translations/zh_TW/process/license-rules.rst @@ -4,7 +4,7 @@ :Original: :ref:`Documentation/process/license-rules.rst <kernel_licensing>` :Translator: Alex Shi <alex.shi@linux.alibaba.com> - Hu Haowen <src.res.211@gmail.com> + Hu Haowen <2023002089@link.tyut.edu.cn> .. _tw_kernel_licensing: diff --git a/Documentation/translations/zh_TW/process/magic-number.rst b/Documentation/translations/zh_TW/process/magic-number.rst index 5657d5cd18d4..199cd5d63973 100644 --- a/Documentation/translations/zh_TW/process/magic-number.rst +++ b/Documentation/translations/zh_TW/process/magic-number.rst @@ -12,7 +12,7 @@ ä¸æ–‡ç‰ˆç¶è·è€…： 賈å¨å¨ Jia Wei Wei <harryxiyou@gmail.com> ä¸æ–‡ç‰ˆç¿»è¯è€…： 賈å¨å¨ Jia Wei Wei <harryxiyou@gmail.com> ä¸æ–‡ç‰ˆæ ¡è¯è€…： 賈å¨å¨ Jia Wei Wei <harryxiyou@gmail.com> - 胡皓文 Hu Haowen <src.res.211@gmail.com> + 胡皓文 Hu Haowen <2023002089@link.tyut.edu.cn> Linux é”術數 ============ diff --git a/Documentation/translations/zh_TW/process/management-style.rst b/Documentation/translations/zh_TW/process/management-style.rst index f3913e3c159d..7cb912e89032 100644 --- a/Documentation/translations/zh_TW/process/management-style.rst +++ b/Documentation/translations/zh_TW/process/management-style.rst @@ -4,7 +4,7 @@ :Original: :ref:`Documentation/process/management-style.rst <managementstyle>` :Translator: Alex Shi <alex.shi@linux.alibaba.com> - Hu Haowen <src.res.211@gmail.com> + Hu Haowen <2023002089@link.tyut.edu.cn> .. _tw_managementstyle: diff --git a/Documentation/translations/zh_TW/process/programming-language.rst b/Documentation/translations/zh_TW/process/programming-language.rst index e33389676eed..d2c64a5599e8 100644 --- a/Documentation/translations/zh_TW/process/programming-language.rst +++ b/Documentation/translations/zh_TW/process/programming-language.rst @@ -4,7 +4,7 @@ :Original: :ref:`Documentation/process/programming-language.rst <programming_language>` :Translator: Alex Shi <alex.shi@linux.alibaba.com> - Hu Haowen <src.res.211@gmail.com> + Hu Haowen <2023002089@link.tyut.edu.cn> .. _tw_programming_language: diff --git a/Documentation/translations/zh_TW/process/stable-api-nonsense.rst b/Documentation/translations/zh_TW/process/stable-api-nonsense.rst index 6839d25bb22a..4b8597fed5ae 100644 --- a/Documentation/translations/zh_TW/process/stable-api-nonsense.rst +++ b/Documentation/translations/zh_TW/process/stable-api-nonsense.rst @@ -12,7 +12,7 @@ ä¸æ–‡ç‰ˆç¶è·è€…： é¾å®‡ TripleX Chung <xxx.phy@gmail.com> ä¸æ–‡ç‰ˆç¿»è¯è€…： é¾å®‡ TripleX Chung <xxx.phy@gmail.com> ä¸æ–‡ç‰ˆæ ¡è¯è€…： æŽé™½ Li Yang <leoyang.li@nxp.com> - 胡皓文 Hu Haowen <src.res.211@gmail.com> + 胡皓文 Hu Haowen <2023002089@link.tyut.edu.cn> Linux å…§æ ¸é©…å‹•æŽ¥å£ ================== diff --git a/Documentation/translations/zh_TW/process/stable-kernel-rules.rst b/Documentation/translations/zh_TW/process/stable-kernel-rules.rst index bd82a8ff3969..2f8f064f8629 100644 --- a/Documentation/translations/zh_TW/process/stable-kernel-rules.rst +++ b/Documentation/translations/zh_TW/process/stable-kernel-rules.rst @@ -15,7 +15,7 @@ ä¸æ–‡ç‰ˆæ ¡è¯è€…： - æŽé™½ Li Yang <leoyang.li@nxp.com> - Kangkai Yin <e12051@motorola.com> - - 胡皓文 Hu Haowen <src.res.211@gmail.com> + - 胡皓文 Hu Haowen <2023002089@link.tyut.edu.cn> æ‰€æœ‰ä½ æƒ³çŸ¥é“的事情 - 關於linux穩定版發佈 ======================================== diff --git a/Documentation/translations/zh_TW/process/submit-checklist.rst b/Documentation/translations/zh_TW/process/submit-checklist.rst index 942962d1e2f4..43f2e3c5b514 100644 --- a/Documentation/translations/zh_TW/process/submit-checklist.rst +++ b/Documentation/translations/zh_TW/process/submit-checklist.rst @@ -6,7 +6,7 @@ :Translator: - Alex Shi <alexs@kernel.org> - Wu XiangCheng <bobwxc@email.cn> - - Hu Haowen <src.res.211@gmail.com> + - Hu Haowen <2023002089@link.tyut.edu.cn> .. _tw_submitchecklist: @@ -56,8 +56,7 @@ Linuxå…§æ ¸è£œä¸æ交檢查單 9) é€šéŽ sparse 清查。 （åƒè¦‹ Documentation/translations/zh_CN/dev-tools/sparse.rst ） -10) 使用 ``make checkstack`` å’Œ ``make namespacecheck`` 並修復他們發ç¾çš„任何 - å•é¡Œã€‚ +10) 使用 ``make checkstack`` 並修復他們發ç¾çš„任何å•é¡Œã€‚ .. note:: diff --git a/Documentation/translations/zh_TW/process/submitting-patches.rst b/Documentation/translations/zh_TW/process/submitting-patches.rst index 8272b3218b54..99fa0f2fe6f4 100644 --- a/Documentation/translations/zh_TW/process/submitting-patches.rst +++ b/Documentation/translations/zh_TW/process/submitting-patches.rst @@ -14,7 +14,7 @@ :æ ¡è¯: - æŽé™½ Li Yang <leoyang.li@nxp.com> - çŽ‹è° Wang Cong <xiyou.wangcong@gmail.com> - - 胡皓文 Hu Haowen <src.res.211@gmail.com> + - 胡皓文 Hu Haowen <2023002089@link.tyut.edu.cn> æ交補ä¸ï¼šå¦‚ä½•è®“ä½ çš„æ”¹å‹•é€²å…¥å…§æ ¸ diff --git a/Documentation/translations/zh_TW/process/volatile-considered-harmful.rst b/Documentation/translations/zh_TW/process/volatile-considered-harmful.rst index a609620affb0..e2723f3cbbb0 100644 --- a/Documentation/translations/zh_TW/process/volatile-considered-harmful.rst +++ b/Documentation/translations/zh_TW/process/volatile-considered-harmful.rst @@ -17,7 +17,7 @@ ä¸æ–‡ç‰ˆæ ¡è¯è€…： å¼µæ¼¢è¼ Eugene Teo <eugeneteo@kernel.sg> 楊瑞 Dave Young <hidave.darkstar@gmail.com> 時奎亮 Alex Shi <alex.shi@linux.alibaba.com> - 胡皓文 Hu Haowen <src.res.211@gmail.com> + 胡皓文 Hu Haowen <2023002089@link.tyut.edu.cn> 爲什麼ä¸æ‡‰è©²ä½¿ç”¨â€œvolatileâ€é¡žåž‹ ============================== diff --git a/Documentation/driver-api/dcdbas.rst b/Documentation/userspace-api/dcdbas.rst index 309cc57a7c1c..309cc57a7c1c 100644 --- a/Documentation/driver-api/dcdbas.rst +++ b/Documentation/userspace-api/dcdbas.rst diff --git a/Documentation/userspace-api/index.rst b/Documentation/userspace-api/index.rst index 031df47a7c19..09f61bd2ac2e 100644 --- a/Documentation/userspace-api/index.rst +++ b/Documentation/userspace-api/index.rst @@ -9,11 +9,8 @@ While much of the kernel's user-space API is documented elsewhere also be found in the kernel tree itself. This manual is intended to be the place where this information is gathered. -.. class:: toc-title - - Table of contents - .. toctree:: + :caption: Table of contents :maxdepth: 2 no_new_privs @@ -33,6 +30,10 @@ place where this information is gathered. sysfs-platform_profile vduse futex2 + lsm + tee + isapnp + dcdbas .. only:: subproject and html diff --git a/Documentation/userspace-api/ioctl/ioctl-number.rst b/Documentation/userspace-api/ioctl/ioctl-number.rst index 4ea5b837399a..d8b6cb1a3636 100644 --- a/Documentation/userspace-api/ioctl/ioctl-number.rst +++ b/Documentation/userspace-api/ioctl/ioctl-number.rst @@ -349,6 +349,10 @@ Code Seq# Include File Comments <mailto:vgo@ratio.de> 0xB1 00-1F PPPoX <mailto:mostrows@styx.uwaterloo.ca> +0xB2 00 arch/powerpc/include/uapi/asm/papr-vpd.h powerpc/pseries VPD API + <mailto:linuxppc-dev> +0xB2 01-02 arch/powerpc/include/uapi/asm/papr-sysparm.h powerpc/pseries system parameter API + <mailto:linuxppc-dev> 0xB3 00 linux/mmc/ioctl.h 0xB4 00-0F linux/gpio.h <mailto:linux-gpio@vger.kernel.org> 0xB5 00-0F uapi/linux/rpmsg.h <mailto:linux-remoteproc@vger.kernel.org> diff --git a/Documentation/driver-api/isapnp.rst b/Documentation/userspace-api/isapnp.rst index 8d0840ac847b..d6fceb19b8ae 100644 --- a/Documentation/driver-api/isapnp.rst +++ b/Documentation/userspace-api/isapnp.rst @@ -1,11 +1,11 @@ -========================================================== -ISA Plug & Play support by Jaroslav Kysela <perex@suse.cz> -========================================================== +======================= +ISA Plug & Play support +======================= Interface /proc/isapnp ====================== -The interface has been removed. See pnp.txt for more details. +The interface was removed in kernel 2.5.53. See pnp.rst for more details. Interface /proc/bus/isapnp ========================== diff --git a/Documentation/userspace-api/lsm.rst b/Documentation/userspace-api/lsm.rst new file mode 100644 index 000000000000..a76da373841b --- /dev/null +++ b/Documentation/userspace-api/lsm.rst @@ -0,0 +1,73 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. Copyright (C) 2022 Casey Schaufler <casey@schaufler-ca.com> +.. Copyright (C) 2022 Intel Corporation + +===================================== +Linux Security Modules +===================================== + +:Author: Casey Schaufler +:Date: July 2023 + +Linux security modules (LSM) provide a mechanism to implement +additional access controls to the Linux security policies. + +The various security modules may support any of these attributes: + +``LSM_ATTR_CURRENT`` is the current, active security context of the +process. +The proc filesystem provides this value in ``/proc/self/attr/current``. +This is supported by the SELinux, Smack and AppArmor security modules. +Smack also provides this value in ``/proc/self/attr/smack/current``. +AppArmor also provides this value in ``/proc/self/attr/apparmor/current``. + +``LSM_ATTR_EXEC`` is the security context of the process at the time the +current image was executed. +The proc filesystem provides this value in ``/proc/self/attr/exec``. +This is supported by the SELinux and AppArmor security modules. +AppArmor also provides this value in ``/proc/self/attr/apparmor/exec``. + +``LSM_ATTR_FSCREATE`` is the security context of the process used when +creating file system objects. +The proc filesystem provides this value in ``/proc/self/attr/fscreate``. +This is supported by the SELinux security module. + +``LSM_ATTR_KEYCREATE`` is the security context of the process used when +creating key objects. +The proc filesystem provides this value in ``/proc/self/attr/keycreate``. +This is supported by the SELinux security module. + +``LSM_ATTR_PREV`` is the security context of the process at the time the +current security context was set. +The proc filesystem provides this value in ``/proc/self/attr/prev``. +This is supported by the SELinux and AppArmor security modules. +AppArmor also provides this value in ``/proc/self/attr/apparmor/prev``. + +``LSM_ATTR_SOCKCREATE`` is the security context of the process used when +creating socket objects. +The proc filesystem provides this value in ``/proc/self/attr/sockcreate``. +This is supported by the SELinux security module. + +Kernel interface +================ + +Set a security attribute of the current process +----------------------------------------------- + +.. kernel-doc:: security/lsm_syscalls.c + :identifiers: sys_lsm_set_self_attr + +Get the specified security attributes of the current process +------------------------------------------------------------ + +.. kernel-doc:: security/lsm_syscalls.c + :identifiers: sys_lsm_get_self_attr + +.. kernel-doc:: security/lsm_syscalls.c + :identifiers: sys_lsm_list_modules + +Additional documentation +======================== + +* Documentation/security/lsm.rst +* Documentation/security/lsm-development.rst diff --git a/Documentation/userspace-api/media/cec/cec-api.rst b/Documentation/userspace-api/media/cec/cec-api.rst index 4d229ed8a1d9..578303d484f3 100644 --- a/Documentation/userspace-api/media/cec/cec-api.rst +++ b/Documentation/userspace-api/media/cec/cec-api.rst @@ -10,13 +10,8 @@ Part V - Consumer Electronics Control API This part describes the CEC: Consumer Electronics Control -.. only:: html - - .. class:: toc-title - - Table of Contents - .. toctree:: + :caption: Table of Contents :maxdepth: 5 :numbered: diff --git a/Documentation/userspace-api/media/drivers/index.rst b/Documentation/userspace-api/media/drivers/index.rst index 1726f8ec86fa..e5e7deb0d392 100644 --- a/Documentation/userspace-api/media/drivers/index.rst +++ b/Documentation/userspace-api/media/drivers/index.rst @@ -21,13 +21,8 @@ more details. For more details see the file COPYING in the source distribution of Linux. -.. only:: html - - .. class:: toc-title - - Table of Contents - .. toctree:: + :caption: Table of Contents :maxdepth: 5 :numbered: diff --git a/Documentation/userspace-api/media/dvb/dvbapi.rst b/Documentation/userspace-api/media/dvb/dvbapi.rst index 1dda69343f34..4ac0c1bc54ca 100644 --- a/Documentation/userspace-api/media/dvb/dvbapi.rst +++ b/Documentation/userspace-api/media/dvb/dvbapi.rst @@ -27,13 +27,8 @@ Part II - Digital TV API **Version 5.10** -.. only:: html - - .. class:: toc-title - - Table of Contents - .. toctree:: + :caption: Table of Contents :maxdepth: 5 :numbered: diff --git a/Documentation/userspace-api/media/index.rst b/Documentation/userspace-api/media/index.rst index d839904be085..337ef6c7c47f 100644 --- a/Documentation/userspace-api/media/index.rst +++ b/Documentation/userspace-api/media/index.rst @@ -21,13 +21,8 @@ Documentation/driver-api/media/index.rst media devices; -.. only:: html - - .. class:: toc-title - - Table of Contents - .. toctree:: + :caption: Table of Contents :maxdepth: 1 intro diff --git a/Documentation/userspace-api/media/mediactl/media-controller.rst b/Documentation/userspace-api/media/mediactl/media-controller.rst index 508dd693bf6c..73a87f82f92d 100644 --- a/Documentation/userspace-api/media/mediactl/media-controller.rst +++ b/Documentation/userspace-api/media/mediactl/media-controller.rst @@ -7,13 +7,8 @@ Part IV - Media Controller API ############################## -.. only:: html - - .. class:: toc-title - - Table of Contents - .. toctree:: + :caption: Table of Contents :maxdepth: 5 :numbered: diff --git a/Documentation/userspace-api/media/rc/remote_controllers.rst b/Documentation/userspace-api/media/rc/remote_controllers.rst index f89291838637..483f9ae92a90 100644 --- a/Documentation/userspace-api/media/rc/remote_controllers.rst +++ b/Documentation/userspace-api/media/rc/remote_controllers.rst @@ -7,13 +7,8 @@ Part III - Remote Controller API ################################ -.. only:: html - - .. class:: toc-title - - Table of Contents - .. toctree:: + :caption: Table of Contents :maxdepth: 5 :numbered: diff --git a/Documentation/userspace-api/media/v4l/v4l2.rst b/Documentation/userspace-api/media/v4l/v4l2.rst index ad7a2bf0cf26..cf8ae56a008c 100644 --- a/Documentation/userspace-api/media/v4l/v4l2.rst +++ b/Documentation/userspace-api/media/v4l/v4l2.rst @@ -11,13 +11,8 @@ This part describes the Video for Linux API version 2 (V4L2 API) specification. **Revision 4.5** -.. only:: html - - .. class:: toc-title - - Table of Contents - .. toctree:: + :caption: Table of Contents :numbered: :maxdepth: 5 diff --git a/Documentation/userspace-api/netlink/index.rst b/Documentation/userspace-api/netlink/index.rst index 62725dafbbdb..c1b6765cc963 100644 --- a/Documentation/userspace-api/netlink/index.rst +++ b/Documentation/userspace-api/netlink/index.rst @@ -16,4 +16,6 @@ Netlink documentation for users. genetlink-legacy netlink-raw -See also :ref:`Documentation/core-api/netlink.rst <kernel_netlink>`. +See also: + - :ref:`Documentation/core-api/netlink.rst <kernel_netlink>` + - :ref:`Documentation/networking/netlink_spec/index.rst <specs>` diff --git a/Documentation/userspace-api/netlink/intro.rst b/Documentation/userspace-api/netlink/intro.rst index 7b1d401210ef..aacffade8f84 100644 --- a/Documentation/userspace-api/netlink/intro.rst +++ b/Documentation/userspace-api/netlink/intro.rst @@ -234,6 +234,10 @@ ACK attributes may be present:: | ** optionally extended ACK | ---------------------------------------------- +Note that some implementations may issue custom ``NLMSG_DONE`` messages +in reply to ``do`` action requests. In that case the payload is +implementation-specific and may also be absent. + .. _res_fam: Resolving the Family ID diff --git a/Documentation/userspace-api/netlink/netlink-raw.rst b/Documentation/userspace-api/netlink/netlink-raw.rst index f07fb9b9c101..1e14f5f22b8e 100644 --- a/Documentation/userspace-api/netlink/netlink-raw.rst +++ b/Documentation/userspace-api/netlink/netlink-raw.rst @@ -14,7 +14,8 @@ Specification The netlink-raw schema extends the :doc:`genetlink-legacy <genetlink-legacy>` schema with properties that are needed to specify the protocol numbers and multicast IDs used by raw netlink families. See :ref:`classic_netlink` for more -information. +information. The raw netlink families also make use of type-specific +sub-messages. Globals ------- @@ -56,3 +57,96 @@ group registration. - name: rtnlgrp-mctp-ifaddr value: 34 + +Sub-messages +------------ + +Several raw netlink families such as +:doc:`rt_link<../../networking/netlink_spec/rt_link>` and +:doc:`tc<../../networking/netlink_spec/tc>` use attribute nesting as an +abstraction to carry module specific information. + +Conceptually it looks as follows:: + + [OUTER NEST OR MESSAGE LEVEL] + [GENERIC ATTR 1] + [GENERIC ATTR 2] + [GENERIC ATTR 3] + [GENERIC ATTR - wrapper] + [MODULE SPECIFIC ATTR 1] + [MODULE SPECIFIC ATTR 2] + +The ``GENERIC ATTRs`` at the outer level are defined in the core (or rt_link or +core TC), while specific drivers, TC classifiers, qdiscs etc. can carry their +own information wrapped in the ``GENERIC ATTR - wrapper``. Even though the +example above shows attributes nesting inside the wrapper, the modules generally +have full freedom to define the format of the nest. In practice the payload of +the wrapper attr has very similar characteristics to a netlink message. It may +contain a fixed header / structure, netlink attributes, or both. Because of +those shared characteristics we refer to the payload of the wrapper attribute as +a sub-message. + +A sub-message attribute uses the value of another attribute as a selector key to +choose the right sub-message format. For example if the following attribute has +already been decoded: + +.. code-block:: json + + { "kind": "gre" } + +and we encounter the following attribute spec: + +.. code-block:: yaml + + - + name: data + type: sub-message + sub-message: linkinfo-data-msg + selector: kind + +Then we look for a sub-message definition called ``linkinfo-data-msg`` and use +the value of the ``kind`` attribute i.e. ``gre`` as the key to choose the +correct format for the sub-message: + +.. code-block:: yaml + + sub-messages: + name: linkinfo-data-msg + formats: + - + value: bridge + attribute-set: linkinfo-bridge-attrs + - + value: gre + attribute-set: linkinfo-gre-attrs + - + value: geneve + attribute-set: linkinfo-geneve-attrs + +This would decode the attribute value as a sub-message with the attribute-set +called ``linkinfo-gre-attrs`` as the attribute space. + +A sub-message can have an optional ``fixed-header`` followed by zero or more +attributes from an ``attribute-set``. For example the following +``tc-options-msg`` sub-message defines message formats that use a mixture of +``fixed-header``, ``attribute-set`` or both together: + +.. code-block:: yaml + + sub-messages: + - + name: tc-options-msg + formats: + - + value: bfifo + fixed-header: tc-fifo-qopt + - + value: cake + attribute-set: tc-cake-attrs + - + value: netem + fixed-header: tc-netem-qopt + attribute-set: tc-netem-attrs + +Note that a selector attribute must appear in a netlink message before any +sub-message attributes that depend on it. diff --git a/Documentation/userspace-api/netlink/specs.rst b/Documentation/userspace-api/netlink/specs.rst index c1b951649113..1b50d97d8d7c 100644 --- a/Documentation/userspace-api/netlink/specs.rst +++ b/Documentation/userspace-api/netlink/specs.rst @@ -15,7 +15,7 @@ kernel headers directly. Internally kernel uses the YAML specs to generate: - the C uAPI header - - documentation of the protocol as a ReST file + - documentation of the protocol as a ReST file - see :ref:`Documentation/networking/netlink_spec/index.rst <specs>` - policy tables for input attribute validation - operation tables diff --git a/Documentation/userspace-api/tee.rst b/Documentation/userspace-api/tee.rst new file mode 100644 index 000000000000..e2368dbc3451 --- /dev/null +++ b/Documentation/userspace-api/tee.rst @@ -0,0 +1,39 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. tee: + +================================================== +TEE (Trusted Execution Environment) Userspace API +================================================== + +include/uapi/linux/tee.h defines the generic interface to a TEE. + +User space (the client) connects to the driver by opening /dev/tee[0-9]* or +/dev/teepriv[0-9]*. + +- TEE_IOC_SHM_ALLOC allocates shared memory and returns a file descriptor + which user space can mmap. When user space doesn't need the file + descriptor any more, it should be closed. When shared memory isn't needed + any longer it should be unmapped with munmap() to allow the reuse of + memory. + +- TEE_IOC_VERSION lets user space know which TEE this driver handles and + its capabilities. + +- TEE_IOC_OPEN_SESSION opens a new session to a Trusted Application. + +- TEE_IOC_INVOKE invokes a function in a Trusted Application. + +- TEE_IOC_CANCEL may cancel an ongoing TEE_IOC_OPEN_SESSION or TEE_IOC_INVOKE. + +- TEE_IOC_CLOSE_SESSION closes a session to a Trusted Application. + +There are two classes of clients, normal clients and supplicants. The latter is +a helper process for the TEE to access resources in Linux, for example file +system access. A normal client opens /dev/tee[0-9]* and a supplicant opens +/dev/teepriv[0-9]. + +Much of the communication between clients and the TEE is opaque to the +driver. The main job for the driver is to receive requests from the +clients, forward them to the TEE and send back the results. In the case of +supplicants the communication goes in the other direction, the TEE sends +requests to the supplicant which then sends back the result. |