diff options
Diffstat (limited to 'Documentation')
207 files changed, 7662 insertions, 1158 deletions
diff --git a/Documentation/ABI/stable/sysfs-driver-dma-idxd b/Documentation/ABI/stable/sysfs-driver-dma-idxd index f4be46cc6cb6..b5bebf642db6 100644 --- a/Documentation/ABI/stable/sysfs-driver-dma-idxd +++ b/Documentation/ABI/stable/sysfs-driver-dma-idxd @@ -1,3 +1,9 @@ +What: sys/bus/dsa/devices/dsa<m>/version +Date: Apr 15, 2020 +KernelVersion: 5.8.0 +Contact: dmaengine@vger.kernel.org +Description: The hardware version number. + What: sys/bus/dsa/devices/dsa<m>/cdev_major Date: Oct 25, 2019 KernelVersion: 5.6.0 diff --git a/Documentation/ABI/testing/sysfs-class-power b/Documentation/ABI/testing/sysfs-class-power index bf3b48f022dc..216d61a22f1e 100644 --- a/Documentation/ABI/testing/sysfs-class-power +++ b/Documentation/ABI/testing/sysfs-class-power @@ -74,6 +74,21 @@ Description: Access: Read, Write Valid values: 0 - 100 (percent) +What: /sys/class/power_supply/<supply_name>/capacity_error_margin +Date: April 2019 +Contact: linux-pm@vger.kernel.org +Description: + Battery capacity measurement becomes unreliable without + recalibration. This values provides the maximum error + margin expected to exist by the fuel gauge in percent. + Values close to 0% will be returned after (re-)calibration + has happened. Over time the error margin will increase. + 100% means, that the capacity related values are basically + completely useless. + + Access: Read + Valid values: 0 - 100 (percent) + What: /sys/class/power_supply/<supply_name>/capacity_level Date: June 2009 Contact: linux-pm@vger.kernel.org @@ -190,7 +205,7 @@ Description: Valid values: "Unknown", "Good", "Overheat", "Dead", "Over voltage", "Unspecified failure", "Cold", "Watchdog timer expire", "Safety timer expire", - "Over current" + "Over current", "Calibration required" What: /sys/class/power_supply/<supply_name>/precharge_current Date: June 2017 @@ -665,3 +680,31 @@ Description: Valid values: - 1: enabled - 0: disabled + +What: /sys/class/power_supply/<supply_name>/manufacture_year +Date: January 2020 +Contact: linux-pm@vger.kernel.org +Description: + Reports the year (following Gregorian calendar) when the device has been + manufactured. + + Access: Read + Valid values: Reported as integer + +What: /sys/class/power_supply/<supply_name>/manufacture_month +Date: January 2020 +Contact: linux-pm@vger.kernel.org +Description: + Reports the month when the device has been manufactured. + + Access: Read + Valid values: 1-12 + +What: /sys/class/power_supply/<supply_name>/manufacture_day +Date: January 2020 +Contact: linux-pm@vger.kernel.org +Description: + Reports the day of month when the device has been manufactured. + + Access: Read + Valid values: 1-31 diff --git a/Documentation/ABI/testing/sysfs-devices-system-cpu b/Documentation/ABI/testing/sysfs-devices-system-cpu index 77caf3ef82d3..b555df825447 100644 --- a/Documentation/ABI/testing/sysfs-devices-system-cpu +++ b/Documentation/ABI/testing/sysfs-devices-system-cpu @@ -486,6 +486,7 @@ What: /sys/devices/system/cpu/vulnerabilities /sys/devices/system/cpu/vulnerabilities/spec_store_bypass /sys/devices/system/cpu/vulnerabilities/l1tf /sys/devices/system/cpu/vulnerabilities/mds + /sys/devices/system/cpu/vulnerabilities/srbds /sys/devices/system/cpu/vulnerabilities/tsx_async_abort /sys/devices/system/cpu/vulnerabilities/itlb_multihit Date: January 2018 diff --git a/Documentation/ABI/testing/sysfs-fs-f2fs b/Documentation/ABI/testing/sysfs-fs-f2fs index bd8a0d19abe6..4bb93a06d8ab 100644 --- a/Documentation/ABI/testing/sysfs-fs-f2fs +++ b/Documentation/ABI/testing/sysfs-fs-f2fs @@ -323,3 +323,27 @@ What: /sys/fs/f2fs/<disk>/mounted_time_sec Date: February 2020 Contact: "Jaegeuk Kim" <jaegeuk@kernel.org> Description: Show the mounted time in secs of this partition. + +What: /sys/fs/f2fs/<disk>/data_io_flag +Date: April 2020 +Contact: "Jaegeuk Kim" <jaegeuk@kernel.org> +Description: Give a way to attach REQ_META|FUA to data writes + given temperature-based bits. Now the bits indicate: + * REQ_META | REQ_FUA | + * 5 | 4 | 3 | 2 | 1 | 0 | + * Cold | Warm | Hot | Cold | Warm | Hot | + +What: /sys/fs/f2fs/<disk>/node_io_flag +Date: June 2020 +Contact: "Jaegeuk Kim" <jaegeuk@kernel.org> +Description: Give a way to attach REQ_META|FUA to node writes + given temperature-based bits. Now the bits indicate: + * REQ_META | REQ_FUA | + * 5 | 4 | 3 | 2 | 1 | 0 | + * Cold | Warm | Hot | Cold | Warm | Hot | + +What: /sys/fs/f2fs/<disk>/iostat_period_ms +Date: April 2020 +Contact: "Daeho Jeong" <daehojeong@google.com> +Description: Give a way to change iostat_period time. 3secs by default. + The new iostat trace gives stats gap given the period. diff --git a/Documentation/COPYING-logo b/Documentation/COPYING-logo index 296f0f7f67eb..b21c7cf7d9f6 100644 --- a/Documentation/COPYING-logo +++ b/Documentation/COPYING-logo @@ -9,5 +9,5 @@ scale down to smaller sizes and are better for letterheads or whatever you want to use it for: for the full range of logos take a look at Larry's web-page: - http://www.isc.tamu.edu/~lewing/linux/ + https://www.isc.tamu.edu/~lewing/linux/ diff --git a/Documentation/admin-guide/LSM/tomoyo.rst b/Documentation/admin-guide/LSM/tomoyo.rst index e2d6b6e15082..4bc9c2b4da6f 100644 --- a/Documentation/admin-guide/LSM/tomoyo.rst +++ b/Documentation/admin-guide/LSM/tomoyo.rst @@ -27,29 +27,29 @@ Where is documentation? ======================= User <-> Kernel interface documentation is available at -http://tomoyo.osdn.jp/2.5/policy-specification/index.html . +https://tomoyo.osdn.jp/2.5/policy-specification/index.html . Materials we prepared for seminars and symposiums are available at -http://osdn.jp/projects/tomoyo/docs/?category_id=532&language_id=1 . +https://osdn.jp/projects/tomoyo/docs/?category_id=532&language_id=1 . Below lists are chosen from three aspects. What is TOMOYO? TOMOYO Linux Overview - http://osdn.jp/projects/tomoyo/docs/lca2009-takeda.pdf + https://osdn.jp/projects/tomoyo/docs/lca2009-takeda.pdf TOMOYO Linux: pragmatic and manageable security for Linux - http://osdn.jp/projects/tomoyo/docs/freedomhectaipei-tomoyo.pdf + https://osdn.jp/projects/tomoyo/docs/freedomhectaipei-tomoyo.pdf TOMOYO Linux: A Practical Method to Understand and Protect Your Own Linux Box - http://osdn.jp/projects/tomoyo/docs/PacSec2007-en-no-demo.pdf + https://osdn.jp/projects/tomoyo/docs/PacSec2007-en-no-demo.pdf What can TOMOYO do? Deep inside TOMOYO Linux - http://osdn.jp/projects/tomoyo/docs/lca2009-kumaneko.pdf + https://osdn.jp/projects/tomoyo/docs/lca2009-kumaneko.pdf The role of "pathname based access control" in security. - http://osdn.jp/projects/tomoyo/docs/lfj2008-bof.pdf + https://osdn.jp/projects/tomoyo/docs/lfj2008-bof.pdf History of TOMOYO? Realities of Mainlining - http://osdn.jp/projects/tomoyo/docs/lfj2008.pdf + https://osdn.jp/projects/tomoyo/docs/lfj2008.pdf What is future plan? ==================== diff --git a/Documentation/admin-guide/acpi/initrd_table_override.rst b/Documentation/admin-guide/acpi/initrd_table_override.rst index cbd768207631..bb24fa6b5fbe 100644 --- a/Documentation/admin-guide/acpi/initrd_table_override.rst +++ b/Documentation/admin-guide/acpi/initrd_table_override.rst @@ -102,7 +102,7 @@ Where to retrieve userspace tools ================================= iasl and acpixtract are part of Intel's ACPICA project: -http://acpica.org/ +https://acpica.org/ and should be packaged by distributions (for example in the acpica package on SUSE). diff --git a/Documentation/admin-guide/bcache.rst b/Documentation/admin-guide/bcache.rst index c0ce64d75bbf..1eccf952876d 100644 --- a/Documentation/admin-guide/bcache.rst +++ b/Documentation/admin-guide/bcache.rst @@ -7,9 +7,9 @@ nice if you could use them as cache... Hence bcache. Wiki and git repositories are at: - - http://bcache.evilpiepirate.org + - https://bcache.evilpiepirate.org - http://evilpiepirate.org/git/linux-bcache.git - - http://evilpiepirate.org/git/bcache-tools.git + - https://evilpiepirate.org/git/bcache-tools.git It's designed around the performance characteristics of SSDs - it only allocates in erase block sized buckets, and it uses a hybrid btree/log to track cached diff --git a/Documentation/admin-guide/cgroup-v2.rst b/Documentation/admin-guide/cgroup-v2.rst index c2a4b652bd1a..ce3e05e41724 100644 --- a/Documentation/admin-guide/cgroup-v2.rst +++ b/Documentation/admin-guide/cgroup-v2.rst @@ -1170,6 +1170,13 @@ PAGE_SIZE multiple when read back. Under certain circumstances, the usage may go over the limit temporarily. + In default configuration regular 0-order allocations always + succeed unless OOM killer chooses current task as a victim. + + Some kinds of allocations don't invoke the OOM killer. + Caller could retry them differently, return into userspace + as -ENOMEM or silently ignore in cases like disk readahead. + This is the ultimate protection mechanism. As long as the high limit is used and monitored properly, this limit's utility is limited to providing the final safety net. @@ -1226,17 +1233,9 @@ PAGE_SIZE multiple when read back. The number of time the cgroup's memory usage was reached the limit and allocation was about to fail. - Depending on context result could be invocation of OOM - killer and retrying allocation or failing allocation. - - Failed allocation in its turn could be returned into - userspace as -ENOMEM or silently ignored in cases like - disk readahead. For now OOM in memory cgroup kills - tasks iff shortage has happened inside page fault. - This event is not raised if the OOM killer is not considered as an option, e.g. for failed high-order - allocations. + allocations or if caller asked to not retry attempts. oom_kill The number of processes belonging to this cgroup diff --git a/Documentation/admin-guide/devices.rst b/Documentation/admin-guide/devices.rst index d41671aeaef0..035275fedbdd 100644 --- a/Documentation/admin-guide/devices.rst +++ b/Documentation/admin-guide/devices.rst @@ -17,7 +17,7 @@ Specifically explore the sections titled "CHAR and MISC DRIVERS", and to involve for character and block devices. This document is included by reference into the Filesystem Hierarchy -Standard (FHS). The FHS is available from http://www.pathname.com/fhs/. +Standard (FHS). The FHS is available from https://www.pathname.com/fhs/. Allocations marked (68k/Amiga) apply to Linux/68k on the Amiga platform only. Allocations marked (68k/Atari) apply to Linux/68k on diff --git a/Documentation/admin-guide/dynamic-debug-howto.rst b/Documentation/admin-guide/dynamic-debug-howto.rst index 0dc2eb8e44e5..1012bd9305e9 100644 --- a/Documentation/admin-guide/dynamic-debug-howto.rst +++ b/Documentation/admin-guide/dynamic-debug-howto.rst @@ -13,6 +13,11 @@ kernel code to obtain additional kernel information. Currently, if ``print_hex_dump_debug()``/``print_hex_dump_bytes()`` calls can be dynamically enabled per-callsite. +If you do not want to enable dynamic debug globally (i.e. in some embedded +system), you may set ``CONFIG_DYNAMIC_DEBUG_CORE`` as basic support of dynamic +debug and add ``ccflags := -DDYNAMIC_DEBUG_MODULE`` into the Makefile of any +modules which you'd like to dynamically debug later. + If ``CONFIG_DYNAMIC_DEBUG`` is not set, ``print_hex_dump_debug()`` is just shortcut for ``print_hex_dump(KERN_DEBUG)``. diff --git a/Documentation/admin-guide/hw-vuln/index.rst b/Documentation/admin-guide/hw-vuln/index.rst index 0795e3c2643f..ca4dbdd9016d 100644 --- a/Documentation/admin-guide/hw-vuln/index.rst +++ b/Documentation/admin-guide/hw-vuln/index.rst @@ -14,3 +14,4 @@ are configurable at compile, boot or run time. mds tsx_async_abort multihit.rst + special-register-buffer-data-sampling.rst diff --git a/Documentation/admin-guide/hw-vuln/special-register-buffer-data-sampling.rst b/Documentation/admin-guide/hw-vuln/special-register-buffer-data-sampling.rst new file mode 100644 index 000000000000..47b1b3afac99 --- /dev/null +++ b/Documentation/admin-guide/hw-vuln/special-register-buffer-data-sampling.rst @@ -0,0 +1,149 @@ +.. SPDX-License-Identifier: GPL-2.0 + +SRBDS - Special Register Buffer Data Sampling +============================================= + +SRBDS is a hardware vulnerability that allows MDS :doc:`mds` techniques to +infer values returned from special register accesses. Special register +accesses are accesses to off core registers. According to Intel's evaluation, +the special register reads that have a security expectation of privacy are +RDRAND, RDSEED and SGX EGETKEY. + +When RDRAND, RDSEED and EGETKEY instructions are used, the data is moved +to the core through the special register mechanism that is susceptible +to MDS attacks. + +Affected processors +-------------------- +Core models (desktop, mobile, Xeon-E3) that implement RDRAND and/or RDSEED may +be affected. + +A processor is affected by SRBDS if its Family_Model and stepping is +in the following list, with the exception of the listed processors +exporting MDS_NO while Intel TSX is available yet not enabled. The +latter class of processors are only affected when Intel TSX is enabled +by software using TSX_CTRL_MSR otherwise they are not affected. + + ============= ============ ======== + common name Family_Model Stepping + ============= ============ ======== + IvyBridge 06_3AH All + + Haswell 06_3CH All + Haswell_L 06_45H All + Haswell_G 06_46H All + + Broadwell_G 06_47H All + Broadwell 06_3DH All + + Skylake_L 06_4EH All + Skylake 06_5EH All + + Kabylake_L 06_8EH <= 0xC + Kabylake 06_9EH <= 0xD + ============= ============ ======== + +Related CVEs +------------ + +The following CVE entry is related to this SRBDS issue: + + ============== ===== ===================================== + CVE-2020-0543 SRBDS Special Register Buffer Data Sampling + ============== ===== ===================================== + +Attack scenarios +---------------- +An unprivileged user can extract values returned from RDRAND and RDSEED +executed on another core or sibling thread using MDS techniques. + + +Mitigation mechanism +------------------- +Intel will release microcode updates that modify the RDRAND, RDSEED, and +EGETKEY instructions to overwrite secret special register data in the shared +staging buffer before the secret data can be accessed by another logical +processor. + +During execution of the RDRAND, RDSEED, or EGETKEY instructions, off-core +accesses from other logical processors will be delayed until the special +register read is complete and the secret data in the shared staging buffer is +overwritten. + +This has three effects on performance: + +#. RDRAND, RDSEED, or EGETKEY instructions have higher latency. + +#. Executing RDRAND at the same time on multiple logical processors will be + serialized, resulting in an overall reduction in the maximum RDRAND + bandwidth. + +#. Executing RDRAND, RDSEED or EGETKEY will delay memory accesses from other + logical processors that miss their core caches, with an impact similar to + legacy locked cache-line-split accesses. + +The microcode updates provide an opt-out mechanism (RNGDS_MITG_DIS) to disable +the mitigation for RDRAND and RDSEED instructions executed outside of Intel +Software Guard Extensions (Intel SGX) enclaves. On logical processors that +disable the mitigation using this opt-out mechanism, RDRAND and RDSEED do not +take longer to execute and do not impact performance of sibling logical +processors memory accesses. The opt-out mechanism does not affect Intel SGX +enclaves (including execution of RDRAND or RDSEED inside an enclave, as well +as EGETKEY execution). + +IA32_MCU_OPT_CTRL MSR Definition +-------------------------------- +Along with the mitigation for this issue, Intel added a new thread-scope +IA32_MCU_OPT_CTRL MSR, (address 0x123). The presence of this MSR and +RNGDS_MITG_DIS (bit 0) is enumerated by CPUID.(EAX=07H,ECX=0).EDX[SRBDS_CTRL = +9]==1. This MSR is introduced through the microcode update. + +Setting IA32_MCU_OPT_CTRL[0] (RNGDS_MITG_DIS) to 1 for a logical processor +disables the mitigation for RDRAND and RDSEED executed outside of an Intel SGX +enclave on that logical processor. Opting out of the mitigation for a +particular logical processor does not affect the RDRAND and RDSEED mitigations +for other logical processors. + +Note that inside of an Intel SGX enclave, the mitigation is applied regardless +of the value of RNGDS_MITG_DS. + +Mitigation control on the kernel command line +--------------------------------------------- +The kernel command line allows control over the SRBDS mitigation at boot time +with the option "srbds=". The option for this is: + + ============= ============================================================= + off This option disables SRBDS mitigation for RDRAND and RDSEED on + affected platforms. + ============= ============================================================= + +SRBDS System Information +----------------------- +The Linux kernel provides vulnerability status information through sysfs. For +SRBDS this can be accessed by the following sysfs file: +/sys/devices/system/cpu/vulnerabilities/srbds + +The possible values contained in this file are: + + ============================== ============================================= + Not affected Processor not vulnerable + Vulnerable Processor vulnerable and mitigation disabled + Vulnerable: No microcode Processor vulnerable and microcode is missing + mitigation + Mitigation: Microcode Processor is vulnerable and mitigation is in + effect. + Mitigation: TSX disabled Processor is only vulnerable when TSX is + enabled while this system was booted with TSX + disabled. + Unknown: Dependent on + hypervisor status Running on virtual guest processor that is + affected but with no way to know if host + processor is mitigated or vulnerable. + ============================== ============================================= + +SRBDS Default mitigation +------------------------ +This new microcode serializes processor access during execution of RDRAND, +RDSEED ensures that the shared buffer is overwritten before it is released for +reuse. Use the "srbds=off" kernel command line to disable the mitigation for +RDRAND and RDSEED. diff --git a/Documentation/admin-guide/initrd.rst b/Documentation/admin-guide/initrd.rst index a03dabaaf3a3..67bbad8806e8 100644 --- a/Documentation/admin-guide/initrd.rst +++ b/Documentation/admin-guide/initrd.rst @@ -376,7 +376,7 @@ Resources --------- .. [#f1] Almesberger, Werner; "Booting Linux: The History and the Future" - http://www.almesberger.net/cv/papers/ols2k-9.ps.gz + https://www.almesberger.net/cv/papers/ols2k-9.ps.gz .. [#f2] newlib package (experimental), with initrd example https://www.sourceware.org/newlib/ .. [#f3] util-linux: Miscellaneous utilities for Linux diff --git a/Documentation/admin-guide/kdump/kdump.rst b/Documentation/admin-guide/kdump/kdump.rst index ac7e131d2935..2da65fef2a1c 100644 --- a/Documentation/admin-guide/kdump/kdump.rst +++ b/Documentation/admin-guide/kdump/kdump.rst @@ -521,6 +521,14 @@ will cause a kdump to occur at the panic() call. In cases where a user wants to specify this during runtime, /proc/sys/kernel/panic_on_warn can be set to 1 to achieve the same behaviour. +Trigger Kdump on add_taint() +============================ + +The kernel parameter panic_on_taint facilitates a conditional call to panic() +from within add_taint() whenever the value set in this bitmask matches with the +bit flag being set by add_taint(). +This will cause a kdump to occur at the add_taint()->panic() call. + Contact ======= diff --git a/Documentation/admin-guide/kernel-parameters.txt b/Documentation/admin-guide/kernel-parameters.txt index f3eeecbb3f63..fb95fad81c79 100644 --- a/Documentation/admin-guide/kernel-parameters.txt +++ b/Documentation/admin-guide/kernel-parameters.txt @@ -1445,7 +1445,7 @@ hardlockup_all_cpu_backtrace= [KNL] Should the hard-lockup detector generate backtraces on all cpus. - Format: <integer> + Format: 0 | 1 hashdist= [KNL,NUMA] Large hashes allocated during boot are distributed across NUMA nodes. Defaults on @@ -1513,9 +1513,9 @@ hung_task_panic= [KNL] Should the hung task detector generate panics. - Format: <integer> + Format: 0 | 1 - A nonzero value instructs the kernel to panic when a + A value of 1 instructs the kernel to panic when a hung task is detected. The default value is controlled by the CONFIG_BOOTPARAM_HUNG_TASK_PANIC build-time option. The value selected by this boot parameter can @@ -3447,6 +3447,19 @@ bit 4: print ftrace buffer bit 5: print all printk messages in buffer + panic_on_taint= Bitmask for conditionally calling panic() in add_taint() + Format: <hex>[,nousertaint] + Hexadecimal bitmask representing the set of TAINT flags + that will cause the kernel to panic when add_taint() is + called with any of the flags in this set. + The optional switch "nousertaint" can be utilized to + prevent userspace forced crashes by writing to sysctl + /proc/sys/kernel/tainted any flagset matching with the + bitmask set on panic_on_taint. + See Documentation/admin-guide/tainted-kernels.rst for + extra details on the taint flags that users can pick + to compose the bitmask to assign to panic_on_taint. + panic_on_warn panic() instead of WARN(). Useful to cause kdump on a WARN(). @@ -3715,6 +3728,8 @@ may put more devices in an IOMMU group. force_floating [S390] Force usage of floating interrupts. nomio [S390] Do not use MIO instructions. + norid [S390] ignore the RID field and force use of + one PCI domain per PCI function pcie_aspm= [PCIE] Forcibly enable or disable PCIe Active State Power Management. @@ -4652,9 +4667,9 @@ softlockup_panic= [KNL] Should the soft-lockup detector generate panics. - Format: <integer> + Format: 0 | 1 - A nonzero value instructs the soft-lockup detector + A value of 1 instructs the soft-lockup detector to panic the machine when a soft-lockup occurs. It is also controlled by the kernel.softlockup_panic sysctl and CONFIG_BOOTPARAM_SOFTLOCKUP_PANIC, which is the @@ -4663,7 +4678,7 @@ softlockup_all_cpu_backtrace= [KNL] Should the soft-lockup detector generate backtraces on all cpus. - Format: <integer> + Format: 0 | 1 sonypi.*= [HW] Sony Programmable I/O Control Device driver See Documentation/admin-guide/laptops/sonypi.rst @@ -4822,6 +4837,26 @@ the kernel will oops in either "warn" or "fatal" mode. + srbds= [X86,INTEL] + Control the Special Register Buffer Data Sampling + (SRBDS) mitigation. + + Certain CPUs are vulnerable to an MDS-like + exploit which can leak bits from the random + number generator. + + By default, this issue is mitigated by + microcode. However, the microcode fix can cause + the RDRAND and RDSEED instructions to become + much slower. Among other effects, this will + result in reduced throughput from /dev/urandom. + + The microcode mitigation can be disabled with + the following option: + + off: Disable mitigation and remove + performance impact to RDRAND and RDSEED + srcutree.counter_wrap_check [KNL] Specifies how frequently to check for grace-period sequence counter wrap for the @@ -4956,6 +4991,15 @@ switches= [HW,M68k] + sysctl.*= [KNL] + Set a sysctl parameter, right before loading the init + process, as if the value was written to the respective + /proc/sys/... file. Both '.' and '/' are recognized as + separators. Unrecognized parameters and invalid values + are reported in the kernel log. Sysctls registered + later by a loaded module cannot be set this way. + Example: sysctl.vm.swappiness=40 + sysfs.deprecated=0|1 [KNL] Enable/disable old style sysfs layout for old udev on older distributions. When this option is enabled diff --git a/Documentation/admin-guide/md.rst b/Documentation/admin-guide/md.rst index 3c51084ffd37..d973d469ffc4 100644 --- a/Documentation/admin-guide/md.rst +++ b/Documentation/admin-guide/md.rst @@ -5,7 +5,7 @@ Boot time assembly of RAID arrays --------------------------------- Tools that manage md devices can be found at - http://www.kernel.org/pub/linux/utils/raid/ + https://www.kernel.org/pub/linux/utils/raid/ You can boot with your md device with the following kernel command diff --git a/Documentation/admin-guide/mm/numa_memory_policy.rst b/Documentation/admin-guide/mm/numa_memory_policy.rst index 8463f5538fda..067a90a1499c 100644 --- a/Documentation/admin-guide/mm/numa_memory_policy.rst +++ b/Documentation/admin-guide/mm/numa_memory_policy.rst @@ -364,19 +364,19 @@ follows: 2) for querying the policy, we do not need to take an extra reference on the target task's task policy nor vma policies because we always acquire the - task's mm's mmap_sem for read during the query. The set_mempolicy() and - mbind() APIs [see below] always acquire the mmap_sem for write when + task's mm's mmap_lock for read during the query. The set_mempolicy() and + mbind() APIs [see below] always acquire the mmap_lock for write when installing or replacing task or vma policies. Thus, there is no possibility of a task or thread freeing a policy while another task or thread is querying it. 3) Page allocation usage of task or vma policy occurs in the fault path where - we hold them mmap_sem for read. Again, because replacing the task or vma - policy requires that the mmap_sem be held for write, the policy can't be + we hold them mmap_lock for read. Again, because replacing the task or vma + policy requires that the mmap_lock be held for write, the policy can't be freed out from under us while we're using it for page allocation. 4) Shared policies require special consideration. One task can replace a - shared memory policy while another task, with a distinct mmap_sem, is + shared memory policy while another task, with a distinct mmap_lock, is querying or allocating a page based on the policy. To resolve this potential race, the shared policy infrastructure adds an extra reference to the shared policy during lookup while holding a spin lock on the shared diff --git a/Documentation/admin-guide/mm/userfaultfd.rst b/Documentation/admin-guide/mm/userfaultfd.rst index 0bf49d7313ad..1dc2d5f823b4 100644 --- a/Documentation/admin-guide/mm/userfaultfd.rst +++ b/Documentation/admin-guide/mm/userfaultfd.rst @@ -33,7 +33,7 @@ memory ranges) provides two primary functionalities: The real advantage of userfaults if compared to regular virtual memory management of mremap/mprotect is that the userfaults in all their operations never involve heavyweight structures like vmas (in fact the -``userfaultfd`` runtime load never takes the mmap_sem for writing). +``userfaultfd`` runtime load never takes the mmap_lock for writing). Vmas are not suitable for page- (or hugepage) granular fault tracking when dealing with virtual address spaces that could span diff --git a/Documentation/admin-guide/mono.rst b/Documentation/admin-guide/mono.rst index 59e6d59f0ed9..c6dab5680065 100644 --- a/Documentation/admin-guide/mono.rst +++ b/Documentation/admin-guide/mono.rst @@ -12,11 +12,11 @@ other program after you have done the following: a binary package, a source tarball or by installing from Git. Binary packages for several distributions can be found at: - http://www.mono-project.com/download/ + https://www.mono-project.com/download/ Instructions for compiling Mono can be found at: - http://www.mono-project.com/docs/compiling-mono/linux/ + https://www.mono-project.com/docs/compiling-mono/linux/ Once the Mono CLR support has been installed, just check that ``/usr/bin/mono`` (which could be located elsewhere, for example diff --git a/Documentation/admin-guide/reporting-bugs.rst b/Documentation/admin-guide/reporting-bugs.rst index 49ac8dc3594d..42481ea7b41d 100644 --- a/Documentation/admin-guide/reporting-bugs.rst +++ b/Documentation/admin-guide/reporting-bugs.rst @@ -75,7 +75,7 @@ Tips for reporting bugs If you haven't reported a bug before, please read: - http://www.chiark.greenend.org.uk/~sgtatham/bugs.html + https://www.chiark.greenend.org.uk/~sgtatham/bugs.html http://www.catb.org/esr/faqs/smart-questions.html diff --git a/Documentation/admin-guide/sysctl/kernel.rst b/Documentation/admin-guide/sysctl/kernel.rst index 1ebf68d01141..83acf5025488 100644 --- a/Documentation/admin-guide/sysctl/kernel.rst +++ b/Documentation/admin-guide/sysctl/kernel.rst @@ -335,6 +335,20 @@ Path for the hotplug policy agent. Default value is "``/sbin/hotplug``". +hung_task_all_cpu_backtrace: +================ + +If this option is set, the kernel will send an NMI to all CPUs to dump +their backtraces when a hung task is detected. This file shows up if +CONFIG_DETECT_HUNG_TASK and CONFIG_SMP are enabled. + +0: Won't show all CPUs backtraces when a hung task is detected. +This is the default behavior. + +1: Will non-maskably interrupt all CPUs and dump their backtraces when +a hung task is detected. + + hung_task_panic =============== @@ -632,6 +646,22 @@ rate for each task. scanned for a given scan. +oops_all_cpu_backtrace: +================ + +If this option is set, the kernel will send an NMI to all CPUs to dump +their backtraces when an oops event occurs. It should be used as a last +resort in case a panic cannot be triggered (to protect VMs running, for +example) or kdump can't be collected. This file shows up if CONFIG_SMP +is enabled. + +0: Won't show all CPUs backtraces when an oops is detected. +This is the default behavior. + +1: Will non-maskably interrupt all CPUs and dump their backtraces when +an oops event is detected. + + osrelease, ostype & version =========================== @@ -1239,6 +1269,13 @@ ORed together. The letters are seen in "Tainted" line of Oops reports. See :doc:`/admin-guide/tainted-kernels` for more information. +Note: + writes to this sysctl interface will fail with ``EINVAL`` if the kernel is + booted with the command line option ``panic_on_taint=<bitmask>,nousertaint`` + and any of the ORed together values being written to ``tainted`` match with + the bitmask declared on panic_on_taint. + See :doc:`/admin-guide/kernel-parameters` for more details on that particular + kernel command line option and its optional ``nousertaint`` switch. threads-max =========== diff --git a/Documentation/admin-guide/unicode.rst b/Documentation/admin-guide/unicode.rst index 7425a3351321..290fe83ebe82 100644 --- a/Documentation/admin-guide/unicode.rst +++ b/Documentation/admin-guide/unicode.rst @@ -114,7 +114,7 @@ Unicode practice. This range is now officially managed by the ConScript Unicode Registry. The normative reference is at: - http://www.evertype.com/standards/csur/klingon.html + https://www.evertype.com/standards/csur/klingon.html Klingon has an alphabet of 26 characters, a positional numeric writing system with 10 digits, and is written left-to-right, top-to-bottom. @@ -178,7 +178,7 @@ fictional and artificial scripts has been established by John Cowan <jcowan@reutershealth.com> and Michael Everson <everson@evertype.com>. The ConScript Unicode Registry is accessible at: - http://www.evertype.com/standards/csur/ + https://www.evertype.com/standards/csur/ The ranges used fall at the low end of the End User Zone and can hence not be normatively assigned, but it is recommended that people who diff --git a/Documentation/conf.py b/Documentation/conf.py index f6a1bc07c410..c503188880d9 100644 --- a/Documentation/conf.py +++ b/Documentation/conf.py @@ -538,7 +538,7 @@ epub_exclude_files = ['search.html'] # Grouping the document tree into PDF files. List of tuples # (source start file, target name, title, author, options). # -# See the Sphinx chapter of http://ralsina.me/static/manual.pdf +# See the Sphinx chapter of https://ralsina.me/static/manual.pdf # # FIXME: Do not add the index file here; the result will be too big. Adding # multiple PDF files here actually tries to get the cross-referencing right diff --git a/Documentation/core-api/pin_user_pages.rst b/Documentation/core-api/pin_user_pages.rst index 2e939ff10b86..6068266dd303 100644 --- a/Documentation/core-api/pin_user_pages.rst +++ b/Documentation/core-api/pin_user_pages.rst @@ -148,23 +148,46 @@ NOTE: Some pages, such as DAX pages, cannot be pinned with longterm pins. That's because DAX pages do not have a separate page cache, and so "pinning" implies locking down file system blocks, which is not (yet) supported in that way. -CASE 3: Hardware with page faulting support -------------------------------------------- -Here, a well-written driver doesn't normally need to pin pages at all. However, -if the driver does choose to do so, it can register MMU notifiers for the range, -and will be called back upon invalidation. Either way (avoiding page pinning, or -using MMU notifiers to unpin upon request), there is proper synchronization with -both filesystem and mm (page_mkclean(), munmap(), etc). - -Therefore, neither flag needs to be set. - -In this case, ideally, neither get_user_pages() nor pin_user_pages() should be -called. Instead, the software should be written so that it does not pin pages. -This allows mm and filesystems to operate more efficiently and reliably. +CASE 3: MMU notifier registration, with or without page faulting hardware +------------------------------------------------------------------------- +Device drivers can pin pages via get_user_pages*(), and register for mmu +notifier callbacks for the memory range. Then, upon receiving a notifier +"invalidate range" callback , stop the device from using the range, and unpin +the pages. There may be other possible schemes, such as for example explicitly +synchronizing against pending IO, that accomplish approximately the same thing. + +Or, if the hardware supports replayable page faults, then the device driver can +avoid pinning entirely (this is ideal), as follows: register for mmu notifier +callbacks as above, but instead of stopping the device and unpinning in the +callback, simply remove the range from the device's page tables. + +Either way, as long as the driver unpins the pages upon mmu notifier callback, +then there is proper synchronization with both filesystem and mm +(page_mkclean(), munmap(), etc). Therefore, neither flag needs to be set. CASE 4: Pinning for struct page manipulation only ------------------------------------------------- -Here, normal GUP calls are sufficient, so neither flag needs to be set. +If only struct page data (as opposed to the actual memory contents that a page +is tracking) is affected, then normal GUP calls are sufficient, and neither flag +needs to be set. + +CASE 5: Pinning in order to write to the data within the page +------------------------------------------------------------- +Even though neither DMA nor Direct IO is involved, just a simple case of "pin, +write to a page's data, unpin" can cause a problem. Case 5 may be considered a +superset of Case 1, plus Case 2, plus anything that invokes that pattern. In +other words, if the code is neither Case 1 nor Case 2, it may still require +FOLL_PIN, for patterns like this: + +Correct (uses FOLL_PIN calls): + pin_user_pages() + write to the data within the pages + unpin_user_pages() + +INCORRECT (uses FOLL_GET calls): + get_user_pages() + write to the data within the pages + put_page() page_maybe_dma_pinned(): the whole point of pinning =================================================== diff --git a/Documentation/core-api/rbtree.rst b/Documentation/core-api/rbtree.rst index 523d54b60087..6b88837fbf82 100644 --- a/Documentation/core-api/rbtree.rst +++ b/Documentation/core-api/rbtree.rst @@ -36,10 +36,10 @@ This document covers use of the Linux rbtree implementation. For more information on the nature and implementation of Red Black Trees, see: Linux Weekly News article on red-black trees - http://lwn.net/Articles/184495/ + https://lwn.net/Articles/184495/ Wikipedia entry on red-black trees - http://en.wikipedia.org/wiki/Red-black_tree + https://en.wikipedia.org/wiki/Red-black_tree Linux implementation of red-black trees --------------------------------------- diff --git a/Documentation/dev-tools/coccinelle.rst b/Documentation/dev-tools/coccinelle.rst index 00a3409b0c28..70274c3f5f5a 100644 --- a/Documentation/dev-tools/coccinelle.rst +++ b/Documentation/dev-tools/coccinelle.rst @@ -14,7 +14,7 @@ many uses in kernel development, including the application of complex, tree-wide patches and detection of problematic programming patterns. Getting Coccinelle -------------------- +------------------ The semantic patches included in the kernel use features and options which are provided by Coccinelle version 1.0.0-rc11 and above. @@ -56,7 +56,7 @@ found at: https://github.com/coccinelle/coccinelle/blob/master/install.txt Supplemental documentation ---------------------------- +-------------------------- For supplemental documentation refer to the wiki: @@ -128,7 +128,7 @@ To enable verbose messages set the V= variable, for example:: make coccicheck MODE=report V=1 Coccinelle parallelization ---------------------------- +-------------------------- By default, coccicheck tries to run as parallel as possible. To change the parallelism, set the J= variable. For example, to run across 4 CPUs:: @@ -333,7 +333,7 @@ as an example if requiring at least Coccinelle >= 1.0.5:: // Requires: 1.0.5 Proposing new semantic patches -------------------------------- +------------------------------ New semantic patches can be proposed and submitted by kernel developers. For sake of clarity, they should be organized in the diff --git a/Documentation/dev-tools/gdb-kernel-debugging.rst b/Documentation/dev-tools/gdb-kernel-debugging.rst index 19df79286f00..4756f6b3a04e 100644 --- a/Documentation/dev-tools/gdb-kernel-debugging.rst +++ b/Documentation/dev-tools/gdb-kernel-debugging.rst @@ -24,7 +24,7 @@ Setup - Create a virtual Linux machine for QEMU/KVM (see www.linux-kvm.org and www.qemu.org for more details). For cross-development, - http://landley.net/aboriginal/bin keeps a pool of machine images and + https://landley.net/aboriginal/bin keeps a pool of machine images and toolchains that can be helpful to start from. - Build the kernel with CONFIG_GDB_SCRIPTS enabled, but leave diff --git a/Documentation/dev-tools/index.rst b/Documentation/dev-tools/index.rst index 09dee10d2592..f7809c7b1ba9 100644 --- a/Documentation/dev-tools/index.rst +++ b/Documentation/dev-tools/index.rst @@ -21,6 +21,7 @@ whole; patches welcome! kasan ubsan kmemleak + kcsan gdb-kernel-debugging kgdb kselftest diff --git a/Documentation/dev-tools/kcsan.rst b/Documentation/dev-tools/kcsan.rst new file mode 100644 index 000000000000..ce4bbd918648 --- /dev/null +++ b/Documentation/dev-tools/kcsan.rst @@ -0,0 +1,321 @@ +The Kernel Concurrency Sanitizer (KCSAN) +======================================== + +The Kernel Concurrency Sanitizer (KCSAN) is a dynamic race detector, which +relies on compile-time instrumentation, and uses a watchpoint-based sampling +approach to detect races. KCSAN's primary purpose is to detect `data races`_. + +Usage +----- + +KCSAN requires Clang version 11 or later. + +To enable KCSAN configure the kernel with:: + + CONFIG_KCSAN = y + +KCSAN provides several other configuration options to customize behaviour (see +the respective help text in ``lib/Kconfig.kcsan`` for more info). + +Error reports +~~~~~~~~~~~~~ + +A typical data race report looks like this:: + + ================================================================== + BUG: KCSAN: data-race in generic_permission / kernfs_refresh_inode + + write to 0xffff8fee4c40700c of 4 bytes by task 175 on cpu 4: + kernfs_refresh_inode+0x70/0x170 + kernfs_iop_permission+0x4f/0x90 + inode_permission+0x190/0x200 + link_path_walk.part.0+0x503/0x8e0 + path_lookupat.isra.0+0x69/0x4d0 + filename_lookup+0x136/0x280 + user_path_at_empty+0x47/0x60 + vfs_statx+0x9b/0x130 + __do_sys_newlstat+0x50/0xb0 + __x64_sys_newlstat+0x37/0x50 + do_syscall_64+0x85/0x260 + entry_SYSCALL_64_after_hwframe+0x44/0xa9 + + read to 0xffff8fee4c40700c of 4 bytes by task 166 on cpu 6: + generic_permission+0x5b/0x2a0 + kernfs_iop_permission+0x66/0x90 + inode_permission+0x190/0x200 + link_path_walk.part.0+0x503/0x8e0 + path_lookupat.isra.0+0x69/0x4d0 + filename_lookup+0x136/0x280 + user_path_at_empty+0x47/0x60 + do_faccessat+0x11a/0x390 + __x64_sys_access+0x3c/0x50 + do_syscall_64+0x85/0x260 + entry_SYSCALL_64_after_hwframe+0x44/0xa9 + + Reported by Kernel Concurrency Sanitizer on: + CPU: 6 PID: 166 Comm: systemd-journal Not tainted 5.3.0-rc7+ #1 + Hardware name: QEMU Standard PC (i440FX + PIIX, 1996), BIOS 1.12.0-1 04/01/2014 + ================================================================== + +The header of the report provides a short summary of the functions involved in +the race. It is followed by the access types and stack traces of the 2 threads +involved in the data race. + +The other less common type of data race report looks like this:: + + ================================================================== + BUG: KCSAN: data-race in e1000_clean_rx_irq+0x551/0xb10 + + race at unknown origin, with read to 0xffff933db8a2ae6c of 1 bytes by interrupt on cpu 0: + e1000_clean_rx_irq+0x551/0xb10 + e1000_clean+0x533/0xda0 + net_rx_action+0x329/0x900 + __do_softirq+0xdb/0x2db + irq_exit+0x9b/0xa0 + do_IRQ+0x9c/0xf0 + ret_from_intr+0x0/0x18 + default_idle+0x3f/0x220 + arch_cpu_idle+0x21/0x30 + do_idle+0x1df/0x230 + cpu_startup_entry+0x14/0x20 + rest_init+0xc5/0xcb + arch_call_rest_init+0x13/0x2b + start_kernel+0x6db/0x700 + + Reported by Kernel Concurrency Sanitizer on: + CPU: 0 PID: 0 Comm: swapper/0 Not tainted 5.3.0-rc7+ #2 + Hardware name: QEMU Standard PC (i440FX + PIIX, 1996), BIOS 1.12.0-1 04/01/2014 + ================================================================== + +This report is generated where it was not possible to determine the other +racing thread, but a race was inferred due to the data value of the watched +memory location having changed. These can occur either due to missing +instrumentation or e.g. DMA accesses. These reports will only be generated if +``CONFIG_KCSAN_REPORT_RACE_UNKNOWN_ORIGIN=y`` (selected by default). + +Selective analysis +~~~~~~~~~~~~~~~~~~ + +It may be desirable to disable data race detection for specific accesses, +functions, compilation units, or entire subsystems. For static blacklisting, +the below options are available: + +* KCSAN understands the ``data_race(expr)`` annotation, which tells KCSAN that + any data races due to accesses in ``expr`` should be ignored and resulting + behaviour when encountering a data race is deemed safe. + +* Disabling data race detection for entire functions can be accomplished by + using the function attribute ``__no_kcsan``:: + + __no_kcsan + void foo(void) { + ... + + To dynamically limit for which functions to generate reports, see the + `DebugFS interface`_ blacklist/whitelist feature. + + For ``__always_inline`` functions, replace ``__always_inline`` with + ``__no_kcsan_or_inline`` (which implies ``__always_inline``):: + + static __no_kcsan_or_inline void foo(void) { + ... + +* To disable data race detection for a particular compilation unit, add to the + ``Makefile``:: + + KCSAN_SANITIZE_file.o := n + +* To disable data race detection for all compilation units listed in a + ``Makefile``, add to the respective ``Makefile``:: + + KCSAN_SANITIZE := n + +Furthermore, it is possible to tell KCSAN to show or hide entire classes of +data races, depending on preferences. These can be changed via the following +Kconfig options: + +* ``CONFIG_KCSAN_REPORT_VALUE_CHANGE_ONLY``: If enabled and a conflicting write + is observed via a watchpoint, but the data value of the memory location was + observed to remain unchanged, do not report the data race. + +* ``CONFIG_KCSAN_ASSUME_PLAIN_WRITES_ATOMIC``: Assume that plain aligned writes + up to word size are atomic by default. Assumes that such writes are not + subject to unsafe compiler optimizations resulting in data races. The option + causes KCSAN to not report data races due to conflicts where the only plain + accesses are aligned writes up to word size. + +DebugFS interface +~~~~~~~~~~~~~~~~~ + +The file ``/sys/kernel/debug/kcsan`` provides the following interface: + +* Reading ``/sys/kernel/debug/kcsan`` returns various runtime statistics. + +* Writing ``on`` or ``off`` to ``/sys/kernel/debug/kcsan`` allows turning KCSAN + on or off, respectively. + +* Writing ``!some_func_name`` to ``/sys/kernel/debug/kcsan`` adds + ``some_func_name`` to the report filter list, which (by default) blacklists + reporting data races where either one of the top stackframes are a function + in the list. + +* Writing either ``blacklist`` or ``whitelist`` to ``/sys/kernel/debug/kcsan`` + changes the report filtering behaviour. For example, the blacklist feature + can be used to silence frequently occurring data races; the whitelist feature + can help with reproduction and testing of fixes. + +Tuning performance +~~~~~~~~~~~~~~~~~~ + +Core parameters that affect KCSAN's overall performance and bug detection +ability are exposed as kernel command-line arguments whose defaults can also be +changed via the corresponding Kconfig options. + +* ``kcsan.skip_watch`` (``CONFIG_KCSAN_SKIP_WATCH``): Number of per-CPU memory + operations to skip, before another watchpoint is set up. Setting up + watchpoints more frequently will result in the likelihood of races to be + observed to increase. This parameter has the most significant impact on + overall system performance and race detection ability. + +* ``kcsan.udelay_task`` (``CONFIG_KCSAN_UDELAY_TASK``): For tasks, the + microsecond delay to stall execution after a watchpoint has been set up. + Larger values result in the window in which we may observe a race to + increase. + +* ``kcsan.udelay_interrupt`` (``CONFIG_KCSAN_UDELAY_INTERRUPT``): For + interrupts, the microsecond delay to stall execution after a watchpoint has + been set up. Interrupts have tighter latency requirements, and their delay + should generally be smaller than the one chosen for tasks. + +They may be tweaked at runtime via ``/sys/module/kcsan/parameters/``. + +Data Races +---------- + +In an execution, two memory accesses form a *data race* if they *conflict*, +they happen concurrently in different threads, and at least one of them is a +*plain access*; they *conflict* if both access the same memory location, and at +least one is a write. For a more thorough discussion and definition, see `"Plain +Accesses and Data Races" in the LKMM`_. + +.. _"Plain Accesses and Data Races" in the LKMM: https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/tools/memory-model/Documentation/explanation.txt#n1922 + +Relationship with the Linux-Kernel Memory Consistency Model (LKMM) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The LKMM defines the propagation and ordering rules of various memory +operations, which gives developers the ability to reason about concurrent code. +Ultimately this allows to determine the possible executions of concurrent code, +and if that code is free from data races. + +KCSAN is aware of *marked atomic operations* (``READ_ONCE``, ``WRITE_ONCE``, +``atomic_*``, etc.), but is oblivious of any ordering guarantees and simply +assumes that memory barriers are placed correctly. In other words, KCSAN +assumes that as long as a plain access is not observed to race with another +conflicting access, memory operations are correctly ordered. + +This means that KCSAN will not report *potential* data races due to missing +memory ordering. Developers should therefore carefully consider the required +memory ordering requirements that remain unchecked. If, however, missing +memory ordering (that is observable with a particular compiler and +architecture) leads to an observable data race (e.g. entering a critical +section erroneously), KCSAN would report the resulting data race. + +Race Detection Beyond Data Races +-------------------------------- + +For code with complex concurrency design, race-condition bugs may not always +manifest as data races. Race conditions occur if concurrently executing +operations result in unexpected system behaviour. On the other hand, data races +are defined at the C-language level. The following macros can be used to check +properties of concurrent code where bugs would not manifest as data races. + +.. kernel-doc:: include/linux/kcsan-checks.h + :functions: ASSERT_EXCLUSIVE_WRITER ASSERT_EXCLUSIVE_WRITER_SCOPED + ASSERT_EXCLUSIVE_ACCESS ASSERT_EXCLUSIVE_ACCESS_SCOPED + ASSERT_EXCLUSIVE_BITS + +Implementation Details +---------------------- + +KCSAN relies on observing that two accesses happen concurrently. Crucially, we +want to (a) increase the chances of observing races (especially for races that +manifest rarely), and (b) be able to actually observe them. We can accomplish +(a) by injecting various delays, and (b) by using address watchpoints (or +breakpoints). + +If we deliberately stall a memory access, while we have a watchpoint for its +address set up, and then observe the watchpoint to fire, two accesses to the +same address just raced. Using hardware watchpoints, this is the approach taken +in `DataCollider +<http://usenix.org/legacy/events/osdi10/tech/full_papers/Erickson.pdf>`_. +Unlike DataCollider, KCSAN does not use hardware watchpoints, but instead +relies on compiler instrumentation and "soft watchpoints". + +In KCSAN, watchpoints are implemented using an efficient encoding that stores +access type, size, and address in a long; the benefits of using "soft +watchpoints" are portability and greater flexibility. KCSAN then relies on the +compiler instrumenting plain accesses. For each instrumented plain access: + +1. Check if a matching watchpoint exists; if yes, and at least one access is a + write, then we encountered a racing access. + +2. Periodically, if no matching watchpoint exists, set up a watchpoint and + stall for a small randomized delay. + +3. Also check the data value before the delay, and re-check the data value + after delay; if the values mismatch, we infer a race of unknown origin. + +To detect data races between plain and marked accesses, KCSAN also annotates +marked accesses, but only to check if a watchpoint exists; i.e. KCSAN never +sets up a watchpoint on marked accesses. By never setting up watchpoints for +marked operations, if all accesses to a variable that is accessed concurrently +are properly marked, KCSAN will never trigger a watchpoint and therefore never +report the accesses. + +Key Properties +~~~~~~~~~~~~~~ + +1. **Memory Overhead:** The overall memory overhead is only a few MiB + depending on configuration. The current implementation uses a small array of + longs to encode watchpoint information, which is negligible. + +2. **Performance Overhead:** KCSAN's runtime aims to be minimal, using an + efficient watchpoint encoding that does not require acquiring any shared + locks in the fast-path. For kernel boot on a system with 8 CPUs: + + - 5.0x slow-down with the default KCSAN config; + - 2.8x slow-down from runtime fast-path overhead only (set very large + ``KCSAN_SKIP_WATCH`` and unset ``KCSAN_SKIP_WATCH_RANDOMIZE``). + +3. **Annotation Overheads:** Minimal annotations are required outside the KCSAN + runtime. As a result, maintenance overheads are minimal as the kernel + evolves. + +4. **Detects Racy Writes from Devices:** Due to checking data values upon + setting up watchpoints, racy writes from devices can also be detected. + +5. **Memory Ordering:** KCSAN is *not* explicitly aware of the LKMM's ordering + rules; this may result in missed data races (false negatives). + +6. **Analysis Accuracy:** For observed executions, due to using a sampling + strategy, the analysis is *unsound* (false negatives possible), but aims to + be complete (no false positives). + +Alternatives Considered +----------------------- + +An alternative data race detection approach for the kernel can be found in the +`Kernel Thread Sanitizer (KTSAN) <https://github.com/google/ktsan/wiki>`_. +KTSAN is a happens-before data race detector, which explicitly establishes the +happens-before order between memory operations, which can then be used to +determine data races as defined in `Data Races`_. + +To build a correct happens-before relation, KTSAN must be aware of all ordering +rules of the LKMM and synchronization primitives. Unfortunately, any omission +leads to large numbers of false positives, which is especially detrimental in +the context of the kernel which includes numerous custom synchronization +mechanisms. To track the happens-before relation, KTSAN's implementation +requires metadata for each memory location (shadow memory), which for each page +corresponds to 4 pages of shadow memory, and can translate into overhead of +tens of GiB on a large system. diff --git a/Documentation/dev-tools/kselftest.rst b/Documentation/dev-tools/kselftest.rst index 5d1f56fcd2e7..469d115a95f1 100644 --- a/Documentation/dev-tools/kselftest.rst +++ b/Documentation/dev-tools/kselftest.rst @@ -151,6 +151,29 @@ note some tests will require root privileges:: $ cd kselftest $ ./run_kselftest.sh +Packaging selftests +=================== + +In some cases packaging is desired, such as when tests need to run on a +different system. To package selftests, run:: + + $ make -C tools/testing/selftests gen_tar + +This generates a tarball in the `INSTALL_PATH/kselftest-packages` directory. By +default, `.gz` format is used. The tar format can be overridden by specifying +a `FORMAT` make variable. Any value recognized by `tar's auto-compress`_ option +is supported, such as:: + + $ make -C tools/testing/selftests gen_tar FORMAT=.xz + +`make gen_tar` invokes `make install` so you can use it to package a subset of +tests by using variables specified in `Running a subset of selftests`_ +section:: + + $ make -C tools/testing/selftests gen_tar TARGETS="bpf" FORMAT=.xz + +.. _tar's auto-compress: https://www.gnu.org/software/tar/manual/html_node/gzip.html#auto_002dcompress + Contributing new tests ====================== diff --git a/Documentation/dev-tools/kunit/start.rst b/Documentation/dev-tools/kunit/start.rst index e1c5ce80ce12..bb112cf70624 100644 --- a/Documentation/dev-tools/kunit/start.rst +++ b/Documentation/dev-tools/kunit/start.rst @@ -32,15 +32,17 @@ test targets as well. The ``.kunitconfig`` should also contain any other config options required by the tests. A good starting point for a ``.kunitconfig`` is the KUnit defconfig: + .. code-block:: bash cd $PATH_TO_LINUX_REPO cp arch/um/configs/kunit_defconfig .kunitconfig You can then add any other Kconfig options you wish, e.g.: + .. code-block:: none - CONFIG_LIST_KUNIT_TEST=y + CONFIG_LIST_KUNIT_TEST=y :doc:`kunit_tool <kunit-tool>` will ensure that all config options set in ``.kunitconfig`` are set in the kernel ``.config`` before running the tests. @@ -54,8 +56,8 @@ using. other tools (such as make menuconfig) to adjust other config options. -Running the tests ------------------ +Running the tests (KUnit Wrapper) +--------------------------------- To make sure that everything is set up correctly, simply invoke the Python wrapper from your kernel repo: @@ -105,8 +107,9 @@ have config options ending in ``_KUNIT_TEST``. KUnit and KUnit tests can be compiled as modules: in this case the tests in a module will be run when the module is loaded. -Running the tests ------------------ + +Running the tests (w/o KUnit Wrapper) +------------------------------------- Build and run your kernel as usual. Test output will be written to the kernel log in `TAP <https://testanything.org/>`_ format. diff --git a/Documentation/dev-tools/kunit/usage.rst b/Documentation/dev-tools/kunit/usage.rst index 473a2361ec37..3c3fe8b5fecc 100644 --- a/Documentation/dev-tools/kunit/usage.rst +++ b/Documentation/dev-tools/kunit/usage.rst @@ -595,7 +595,7 @@ able to run one test case per invocation. KUnit debugfs representation ============================ When kunit test suites are initialized, they create an associated directory -in /sys/kernel/debug/kunit/<test-suite>. The directory contains one file +in ``/sys/kernel/debug/kunit/<test-suite>``. The directory contains one file - results: "cat results" displays results of each test case and the results of the entire suite for the last test run. @@ -604,4 +604,4 @@ The debugfs representation is primarily of use when kunit test suites are run in a native environment, either as modules or builtin. Having a way to display results like this is valuable as otherwise results can be intermixed with other events in dmesg output. The maximum size of each -results file is KUNIT_LOG_SIZE bytes (defined in include/kunit/test.h). +results file is KUNIT_LOG_SIZE bytes (defined in ``include/kunit/test.h``). diff --git a/Documentation/devicetree/bindings/arm/mediatek/mediatek,apmixedsys.txt b/Documentation/devicetree/bindings/arm/mediatek/mediatek,apmixedsys.txt index ff000ccade78..bd7a0fa5801b 100644 --- a/Documentation/devicetree/bindings/arm/mediatek/mediatek,apmixedsys.txt +++ b/Documentation/devicetree/bindings/arm/mediatek/mediatek,apmixedsys.txt @@ -8,6 +8,7 @@ Required Properties: - compatible: Should be one of: - "mediatek,mt2701-apmixedsys" - "mediatek,mt2712-apmixedsys", "syscon" + - "mediatek,mt6765-apmixedsys", "syscon" - "mediatek,mt6779-apmixedsys", "syscon" - "mediatek,mt6797-apmixedsys" - "mediatek,mt7622-apmixedsys" diff --git a/Documentation/devicetree/bindings/arm/mediatek/mediatek,audsys.txt b/Documentation/devicetree/bindings/arm/mediatek/mediatek,audsys.txt index e4ca7b703123..38309db115f5 100644 --- a/Documentation/devicetree/bindings/arm/mediatek/mediatek,audsys.txt +++ b/Documentation/devicetree/bindings/arm/mediatek/mediatek,audsys.txt @@ -7,6 +7,7 @@ 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" diff --git a/Documentation/devicetree/bindings/arm/mediatek/mediatek,camsys.txt b/Documentation/devicetree/bindings/arm/mediatek/mediatek,camsys.txt index 1f4aaa15a37e..a0ce82085ad0 100644 --- a/Documentation/devicetree/bindings/arm/mediatek/mediatek,camsys.txt +++ b/Documentation/devicetree/bindings/arm/mediatek/mediatek,camsys.txt @@ -6,6 +6,7 @@ The MediaTek camsys controller provides various clocks to the system. Required Properties: - compatible: Should be one of: + - "mediatek,mt6765-camsys", "syscon" - "mediatek,mt6779-camsys", "syscon" - "mediatek,mt8183-camsys", "syscon" - #clock-cells: Must be 1 diff --git a/Documentation/devicetree/bindings/arm/mediatek/mediatek,imgsys.txt b/Documentation/devicetree/bindings/arm/mediatek/mediatek,imgsys.txt index 2b693e343c56..1e1f00718a7d 100644 --- a/Documentation/devicetree/bindings/arm/mediatek/mediatek,imgsys.txt +++ b/Documentation/devicetree/bindings/arm/mediatek/mediatek,imgsys.txt @@ -8,6 +8,7 @@ Required Properties: - compatible: Should be one of: - "mediatek,mt2701-imgsys", "syscon" - "mediatek,mt2712-imgsys", "syscon" + - "mediatek,mt6765-imgsys", "syscon" - "mediatek,mt6779-imgsys", "syscon" - "mediatek,mt6797-imgsys", "syscon" - "mediatek,mt7623-imgsys", "mediatek,mt2701-imgsys", "syscon" diff --git a/Documentation/devicetree/bindings/arm/mediatek/mediatek,infracfg.txt b/Documentation/devicetree/bindings/arm/mediatek/mediatek,infracfg.txt index db2f4fd754e7..49a968be1a80 100644 --- a/Documentation/devicetree/bindings/arm/mediatek/mediatek,infracfg.txt +++ b/Documentation/devicetree/bindings/arm/mediatek/mediatek,infracfg.txt @@ -9,6 +9,7 @@ Required Properties: - compatible: Should be one of: - "mediatek,mt2701-infracfg", "syscon" - "mediatek,mt2712-infracfg", "syscon" + - "mediatek,mt6765-infracfg", "syscon" - "mediatek,mt6779-infracfg_ao", "syscon" - "mediatek,mt6797-infracfg", "syscon" - "mediatek,mt7622-infracfg", "syscon" diff --git a/Documentation/devicetree/bindings/arm/mediatek/mediatek,mipi0a.txt b/Documentation/devicetree/bindings/arm/mediatek/mediatek,mipi0a.txt new file mode 100644 index 000000000000..8be5978f388d --- /dev/null +++ b/Documentation/devicetree/bindings/arm/mediatek/mediatek,mipi0a.txt @@ -0,0 +1,28 @@ +Mediatek mipi0a (mipi_rx_ana_csi0a) controller +============================ + +The Mediatek mipi0a controller provides various clocks +to the system. + +Required Properties: + +- compatible: Should be one of: + - "mediatek,mt6765-mipi0a", "syscon" +- #clock-cells: Must be 1 + +The mipi0a 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. + +The mipi0a controller also uses the common power domain from +Documentation/devicetree/bindings/soc/mediatek/scpsys.txt +The available power doamins are defined in dt-bindings/power/mt*-power.h. + +Example: + +mipi0a: clock-controller@11c10000 { + compatible = "mediatek,mt6765-mipi0a", "syscon"; + reg = <0 0x11c10000 0 0x1000>; + power-domains = <&scpsys MT6765_POWER_DOMAIN_CAM>; + #clock-cells = <1>; +}; diff --git a/Documentation/devicetree/bindings/arm/mediatek/mediatek,mmsys.txt b/Documentation/devicetree/bindings/arm/mediatek/mediatek,mmsys.txt index 8d6a9d98e7a6..d8c9108c3b4a 100644 --- a/Documentation/devicetree/bindings/arm/mediatek/mediatek,mmsys.txt +++ b/Documentation/devicetree/bindings/arm/mediatek/mediatek,mmsys.txt @@ -9,6 +9,7 @@ Required Properties: - compatible: Should be one of: - "mediatek,mt2701-mmsys", "syscon" - "mediatek,mt2712-mmsys", "syscon" + - "mediatek,mt6765-mmsys", "syscon" - "mediatek,mt6779-mmsys", "syscon" - "mediatek,mt6797-mmsys", "syscon" - "mediatek,mt7623-mmsys", "mediatek,mt2701-mmsys", "syscon" diff --git a/Documentation/devicetree/bindings/arm/mediatek/mediatek,pericfg.yaml b/Documentation/devicetree/bindings/arm/mediatek/mediatek,pericfg.yaml index 55209a2baedc..e271c4682ebc 100644 --- a/Documentation/devicetree/bindings/arm/mediatek/mediatek,pericfg.yaml +++ b/Documentation/devicetree/bindings/arm/mediatek/mediatek,pericfg.yaml @@ -20,6 +20,7 @@ properties: - enum: - mediatek,mt2701-pericfg - mediatek,mt2712-pericfg + - mediatek,mt6765-pericfg - mediatek,mt7622-pericfg - mediatek,mt7629-pericfg - mediatek,mt8135-pericfg diff --git a/Documentation/devicetree/bindings/arm/mediatek/mediatek,topckgen.txt b/Documentation/devicetree/bindings/arm/mediatek/mediatek,topckgen.txt index 0293d693ce0c..9b0394cbbdc9 100644 --- a/Documentation/devicetree/bindings/arm/mediatek/mediatek,topckgen.txt +++ b/Documentation/devicetree/bindings/arm/mediatek/mediatek,topckgen.txt @@ -8,6 +8,7 @@ Required Properties: - compatible: Should be one of: - "mediatek,mt2701-topckgen" - "mediatek,mt2712-topckgen", "syscon" + - "mediatek,mt6765-topckgen", "syscon" - "mediatek,mt6779-topckgen", "syscon" - "mediatek,mt6797-topckgen" - "mediatek,mt7622-topckgen" diff --git a/Documentation/devicetree/bindings/arm/mediatek/mediatek,vcodecsys.txt b/Documentation/devicetree/bindings/arm/mediatek/mediatek,vcodecsys.txt new file mode 100644 index 000000000000..c877bcc1a5c5 --- /dev/null +++ b/Documentation/devicetree/bindings/arm/mediatek/mediatek,vcodecsys.txt @@ -0,0 +1,27 @@ +Mediatek vcodecsys controller +============================ + +The Mediatek vcodecsys controller provides various clocks to the system. + +Required Properties: + +- compatible: Should be one of: + - "mediatek,mt6765-vcodecsys", "syscon" +- #clock-cells: Must be 1 + +The vcodecsys 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. + +The vcodecsys controller also uses the common power domain from +Documentation/devicetree/bindings/soc/mediatek/scpsys.txt +The available power doamins are defined in dt-bindings/power/mt*-power.h. + +Example: + +venc_gcon: clock-controller@17000000 { + compatible = "mediatek,mt6765-vcodecsys", "syscon"; + reg = <0 0x17000000 0 0x10000>; + power-domains = <&scpsys MT6765_POWER_DOMAIN_VCODEC>; + #clock-cells = <1>; +}; diff --git a/Documentation/devicetree/bindings/arm/tegra/nvidia,tegra20-pmc.yaml b/Documentation/devicetree/bindings/arm/tegra/nvidia,tegra20-pmc.yaml index 81534d04094b..b71a20af5f70 100644 --- a/Documentation/devicetree/bindings/arm/tegra/nvidia,tegra20-pmc.yaml +++ b/Documentation/devicetree/bindings/arm/tegra/nvidia,tegra20-pmc.yaml @@ -85,9 +85,8 @@ properties: CPU power good signal from external PMIC to PMC is enabled. nvidia,suspend-mode: - allOf: - - $ref: /schemas/types.yaml#/definitions/uint32 - - enum: [0, 1, 2] + $ref: /schemas/types.yaml#/definitions/uint32 + enum: [0, 1, 2] description: The suspend mode that the platform should use. Mode 0 is for LP0, CPU + Core voltage off and DRAM in self-refresh diff --git a/Documentation/devicetree/bindings/ata/sata_highbank.yaml b/Documentation/devicetree/bindings/ata/sata_highbank.yaml index b195457006cc..5e2a2394e600 100644 --- a/Documentation/devicetree/bindings/ata/sata_highbank.yaml +++ b/Documentation/devicetree/bindings/ata/sata_highbank.yaml @@ -40,28 +40,25 @@ properties: calxeda,led-order: description: Maps port numbers to offsets within the SGPIO bitstream. - allOf: - - $ref: /schemas/types.yaml#/definitions/uint32-array - - minItems: 1 - maxItems: 8 + $ref: /schemas/types.yaml#/definitions/uint32-array + minItems: 1 + maxItems: 8 calxeda,port-phys: description: | phandle-combophy and lane assignment, which maps each SATA port to a combophy and a lane within that combophy - allOf: - - $ref: /schemas/types.yaml#/definitions/phandle-array - - minItems: 1 - maxItems: 8 + $ref: /schemas/types.yaml#/definitions/phandle-array + minItems: 1 + maxItems: 8 calxeda,tx-atten: description: | Contains TX attenuation override codes, one per port. The upper 24 bits of each entry are always 0 and thus ignored. - allOf: - - $ref: /schemas/types.yaml#/definitions/uint32-array - - minItems: 1 - maxItems: 8 + $ref: /schemas/types.yaml#/definitions/uint32-array + minItems: 1 + maxItems: 8 calxeda,sgpio-gpio: description: | diff --git a/Documentation/devicetree/bindings/bus/baikal,bt1-apb.yaml b/Documentation/devicetree/bindings/bus/baikal,bt1-apb.yaml index d6a3b71ea835..68b0131a31d0 100644 --- a/Documentation/devicetree/bindings/bus/baikal,bt1-apb.yaml +++ b/Documentation/devicetree/bindings/bus/baikal,bt1-apb.yaml @@ -71,8 +71,8 @@ examples: bus@1f059000 { compatible = "baikal,bt1-apb", "simple-bus"; - reg = <0 0x1f059000 0 0x1000>, - <0 0x1d000000 0 0x2040000>; + reg = <0x1f059000 0x1000>, + <0x1d000000 0x2040000>; reg-names = "ehb", "nodev"; #address-cells = <1>; #size-cells = <1>; diff --git a/Documentation/devicetree/bindings/bus/baikal,bt1-axi.yaml b/Documentation/devicetree/bindings/bus/baikal,bt1-axi.yaml index 203bc0e5346b..29e1aaea132b 100644 --- a/Documentation/devicetree/bindings/bus/baikal,bt1-axi.yaml +++ b/Documentation/devicetree/bindings/bus/baikal,bt1-axi.yaml @@ -85,8 +85,8 @@ examples: bus@1f05a000 { compatible = "baikal,bt1-axi", "simple-bus"; - reg = <0 0x1f05a000 0 0x1000>, - <0 0x1f04d110 0 0x8>; + reg = <0x1f05a000 0x1000>, + <0x1f04d110 0x8>; reg-names = "qos", "ehb"; #address-cells = <1>; #size-cells = <1>; diff --git a/Documentation/devicetree/bindings/clock/baikal,bt1-ccu-div.yaml b/Documentation/devicetree/bindings/clock/baikal,bt1-ccu-div.yaml new file mode 100644 index 000000000000..2821425ee445 --- /dev/null +++ b/Documentation/devicetree/bindings/clock/baikal,bt1-ccu-div.yaml @@ -0,0 +1,188 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +# Copyright (C) 2020 BAIKAL ELECTRONICS, JSC +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/clock/baikal,bt1-ccu-div.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Baikal-T1 Clock Control Unit Dividers + +maintainers: + - Serge Semin <fancer.lancer@gmail.com> + +description: | + Clocks Control Unit is the core of Baikal-T1 SoC System Controller + responsible for the chip subsystems clocking and resetting. The CCU is + connected with an external fixed rate oscillator, which signal is transformed + into clocks of various frequencies and then propagated to either individual + IP-blocks or to groups of blocks (clock domains). The transformation is done + by means of an embedded into CCU PLLs and gateable/non-gateable dividers. The + later ones are described in this binding. Each clock domain can be also + individually reset by using the domain clocks divider configuration + registers. Baikal-T1 CCU is logically divided into the next components: + 1) External oscillator (normally XTAL's 25 MHz crystal oscillator, but + in general can provide any frequency supported by the CCU PLLs). + 2) PLLs clocks generators (PLLs). + 3) AXI-bus clock dividers (AXI) - described in this binding file. + 4) System devices reference clock dividers (SYS) - described in this binding + file. + which are connected with each other as shown on the next figure: + + +---------------+ + | Baikal-T1 CCU | + | +----+------|- MIPS P5600 cores + | +-|PLLs|------|- DDR controller + | | +----+ | + +----+ | | | | | + |XTAL|--|-+ | | +---+-| + +----+ | | | +-|AXI|-|- AXI-bus + | | | +---+-| + | | | | + | | +----+---+-|- APB-bus + | +-------|SYS|-|- Low-speed Devices + | +---+-|- High-speed Devices + +---------------+ + + Each sub-block is represented as a separate DT node and has an individual + driver to be bound with. + + In order to create signals of wide range frequencies the external oscillator + output is primarily connected to a set of CCU PLLs. Some of PLLs CLKOUT are + then passed over CCU dividers to create signals required for the target clock + domain (like AXI-bus or System Device consumers). The dividers have the + following structure: + + +--------------+ + CLKIN --|->+----+ 1|\ | + SETCLK--|--|/DIV|->| | | + CLKDIV--|--| | | |-|->CLKLOUT + LOCK----|--+----+ | | | + | |/ | + | | | + EN------|-----------+ | + RST-----|--------------|->RSTOUT + +--------------+ + + where CLKIN is the reference clock coming either from CCU PLLs or from an + external clock oscillator, SETCLK - a command to update the output clock in + accordance with a set divider, CLKDIV - clocks divider, LOCK - a signal of + the output clock stabilization, EN - enable/disable the divider block, + RST/RSTOUT - reset clocks domain signal. Depending on the consumer IP-core + peculiarities the dividers may lack of some functionality depicted on the + figure above (like EN, CLKDIV/LOCK/SETCLK). In this case the corresponding + clock provider just doesn't expose either switching functions, or the rate + configuration, or both of them. + + The clock dividers, which output clock is then consumed by the SoC individual + devices, are united into a single clocks provider called System Devices CCU. + Similarly the dividers with output clocks utilized as AXI-bus reference clocks + are called AXI-bus CCU. Both of them use the common clock bindings with no + custom properties. The list of exported clocks and reset signals can be found + in the files: 'include/dt-bindings/clock/bt1-ccu.h' and + 'include/dt-bindings/reset/bt1-ccu.h'. Since System Devices and AXI-bus CCU + are a part of the Baikal-T1 SoC System Controller their DT nodes are supposed + to be a children of later one. + +if: + properties: + compatible: + contains: + const: baikal,bt1-ccu-axi + +then: + properties: + clocks: + items: + - description: CCU SATA PLL output clock + - description: CCU PCIe PLL output clock + - description: CCU Ethernet PLL output clock + + clock-names: + items: + - const: sata_clk + - const: pcie_clk + - const: eth_clk + +else: + properties: + clocks: + items: + - description: External reference clock + - description: CCU SATA PLL output clock + - description: CCU PCIe PLL output clock + - description: CCU Ethernet PLL output clock + + clock-names: + items: + - const: ref_clk + - const: sata_clk + - const: pcie_clk + - const: eth_clk + +properties: + compatible: + enum: + - baikal,bt1-ccu-axi + - baikal,bt1-ccu-sys + + reg: + maxItems: 1 + + "#clock-cells": + const: 1 + + "#reset-cells": + const: 1 + +unevaluatedProperties: false + +required: + - compatible + - "#clock-cells" + - clocks + - clock-names + +examples: + # AXI-bus Clock Control Unit node: + - | + #include <dt-bindings/clock/bt1-ccu.h> + + clock-controller@1f04d030 { + compatible = "baikal,bt1-ccu-axi"; + reg = <0x1f04d030 0x030>; + #clock-cells = <1>; + #reset-cells = <1>; + + clocks = <&ccu_pll CCU_SATA_PLL>, + <&ccu_pll CCU_PCIE_PLL>, + <&ccu_pll CCU_ETH_PLL>; + clock-names = "sata_clk", "pcie_clk", "eth_clk"; + }; + # System Devices Clock Control Unit node: + - | + #include <dt-bindings/clock/bt1-ccu.h> + + clock-controller@1f04d060 { + compatible = "baikal,bt1-ccu-sys"; + reg = <0x1f04d060 0x0a0>; + #clock-cells = <1>; + #reset-cells = <1>; + + clocks = <&clk25m>, + <&ccu_pll CCU_SATA_PLL>, + <&ccu_pll CCU_PCIE_PLL>, + <&ccu_pll CCU_ETH_PLL>; + clock-names = "ref_clk", "sata_clk", "pcie_clk", + "eth_clk"; + }; + # Required Clock Control Unit PLL node: + - | + ccu_pll: clock-controller@1f04d000 { + compatible = "baikal,bt1-ccu-pll"; + reg = <0x1f04d000 0x028>; + #clock-cells = <1>; + + clocks = <&clk25m>; + clock-names = "ref_clk"; + }; +... diff --git a/Documentation/devicetree/bindings/clock/baikal,bt1-ccu-pll.yaml b/Documentation/devicetree/bindings/clock/baikal,bt1-ccu-pll.yaml new file mode 100644 index 000000000000..97131bfa6f87 --- /dev/null +++ b/Documentation/devicetree/bindings/clock/baikal,bt1-ccu-pll.yaml @@ -0,0 +1,131 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +# Copyright (C) 2020 BAIKAL ELECTRONICS, JSC +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/clock/baikal,bt1-ccu-pll.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Baikal-T1 Clock Control Unit PLL + +maintainers: + - Serge Semin <fancer.lancer@gmail.com> + +description: | + Clocks Control Unit is the core of Baikal-T1 SoC System Controller + responsible for the chip subsystems clocking and resetting. The CCU is + connected with an external fixed rate oscillator, which signal is transformed + into clocks of various frequencies and then propagated to either individual + IP-blocks or to groups of blocks (clock domains). The transformation is done + by means of PLLs and gateable/non-gateable dividers embedded into the CCU. + It's logically divided into the next components: + 1) External oscillator (normally XTAL's 25 MHz crystal oscillator, but + in general can provide any frequency supported by the CCU PLLs). + 2) PLLs clocks generators (PLLs) - described in this binding file. + 3) AXI-bus clock dividers (AXI). + 4) System devices reference clock dividers (SYS). + which are connected with each other as shown on the next figure: + + +---------------+ + | Baikal-T1 CCU | + | +----+------|- MIPS P5600 cores + | +-|PLLs|------|- DDR controller + | | +----+ | + +----+ | | | | | + |XTAL|--|-+ | | +---+-| + +----+ | | | +-|AXI|-|- AXI-bus + | | | +---+-| + | | | | + | | +----+---+-|- APB-bus + | +-------|SYS|-|- Low-speed Devices + | +---+-|- High-speed Devices + +---------------+ + + Each CCU sub-block is represented as a separate dts-node and has an + individual driver to be bound with. + + In order to create signals of wide range frequencies the external oscillator + output is primarily connected to a set of CCU PLLs. There are five PLLs + to create a clock for the MIPS P5600 cores, the embedded DDR controller, + SATA, Ethernet and PCIe domains. The last three domains though named by the + biggest system interfaces in fact include nearly all of the rest SoC + peripherals. Each of the PLLs is based on True Circuits TSMC CLN28HPM core + with an interface wrapper (so called safe PLL' clocks switcher) to simplify + the PLL configuration procedure. The PLLs work as depicted on the next + diagram: + + +--------------------------+ + | | + +-->+---+ +---+ +---+ | +---+ 0|\ + CLKF--->|/NF|--->|PFD|...|VCO|-+->|/OD|--->| | + +---+ +->+---+ +---+ /->+---+ | |--->CLKOUT + CLKOD---------C----------------+ 1| | + +--------C--------------------------->|/ + | | ^ + Rclk-+->+---+ | | + CLKR--->|/NR|-+ | + +---+ | + BYPASS--------------------------------------+ + BWADJ---> + + where Rclk is the reference clock coming from XTAL, NR - reference clock + divider, NF - PLL clock multiplier, OD - VCO output clock divider, CLKOUT - + output clock, BWADJ is the PLL bandwidth adjustment parameter. At this moment + the binding supports the PLL dividers configuration in accordance with a + requested rate, while bypassing and bandwidth adjustment settings can be + added in future if it gets to be necessary. + + The PLLs CLKOUT is then either directly connected with the corresponding + clocks consumer (like P5600 cores or DDR controller) or passed over a CCU + divider to create a signal required for the clock domain. + + The CCU PLL dts-node uses the common clock bindings with no custom + parameters. The list of exported clocks can be found in + 'include/dt-bindings/clock/bt1-ccu.h'. Since CCU PLL is a part of the + Baikal-T1 SoC System Controller its DT node is supposed to be a child of + later one. + +properties: + compatible: + const: baikal,bt1-ccu-pll + + reg: + maxItems: 1 + + "#clock-cells": + const: 1 + + clocks: + description: External reference clock + maxItems: 1 + + clock-names: + const: ref_clk + +unevaluatedProperties: false + +required: + - compatible + - "#clock-cells" + - clocks + - clock-names + +examples: + # Clock Control Unit PLL node: + - | + clock-controller@1f04d000 { + compatible = "baikal,bt1-ccu-pll"; + reg = <0x1f04d000 0x028>; + #clock-cells = <1>; + + clocks = <&clk25m>; + clock-names = "ref_clk"; + }; + # Required external oscillator: + - | + clk25m: clock-oscillator-25m { + compatible = "fixed-clock"; + #clock-cells = <0>; + clock-frequency = <25000000>; + clock-output-names = "clk25m"; + }; +... diff --git a/Documentation/devicetree/bindings/clock/idt,versaclock5.txt b/Documentation/devicetree/bindings/clock/idt,versaclock5.txt index 05a245c9df08..bcff681a4bd0 100644 --- a/Documentation/devicetree/bindings/clock/idt,versaclock5.txt +++ b/Documentation/devicetree/bindings/clock/idt,versaclock5.txt @@ -12,6 +12,7 @@ Required properties: "idt,5p49v5933" "idt,5p49v5935" "idt,5p49v6901" + "idt,5p49v6965" - reg: i2c device address, shall be 0x68 or 0x6a. - #clock-cells: from common clock binding; shall be set to 1. - clocks: from common clock binding; list of parent clock handles, diff --git a/Documentation/devicetree/bindings/clock/imx6q-clock.yaml b/Documentation/devicetree/bindings/clock/imx6q-clock.yaml index 429e3b62b965..92a8e545e212 100644 --- a/Documentation/devicetree/bindings/clock/imx6q-clock.yaml +++ b/Documentation/devicetree/bindings/clock/imx6q-clock.yaml @@ -23,7 +23,6 @@ properties: items: - description: CCM interrupt request 1 - description: CCM interrupt request 2 - maxItems: 2 '#clock-cells': const: 1 diff --git a/Documentation/devicetree/bindings/clock/imx6sl-clock.yaml b/Documentation/devicetree/bindings/clock/imx6sl-clock.yaml index 135568c46350..c97bf95b4150 100644 --- a/Documentation/devicetree/bindings/clock/imx6sl-clock.yaml +++ b/Documentation/devicetree/bindings/clock/imx6sl-clock.yaml @@ -23,7 +23,6 @@ properties: items: - description: CCM interrupt request 1 - description: CCM interrupt request 2 - maxItems: 2 '#clock-cells': const: 1 diff --git a/Documentation/devicetree/bindings/clock/imx6sll-clock.yaml b/Documentation/devicetree/bindings/clock/imx6sll-clock.yaml index fa55f1ce3e57..de48924be191 100644 --- a/Documentation/devicetree/bindings/clock/imx6sll-clock.yaml +++ b/Documentation/devicetree/bindings/clock/imx6sll-clock.yaml @@ -23,7 +23,6 @@ properties: items: - description: CCM interrupt request 1 - description: CCM interrupt request 2 - maxItems: 2 '#clock-cells': const: 1 diff --git a/Documentation/devicetree/bindings/clock/imx6sx-clock.yaml b/Documentation/devicetree/bindings/clock/imx6sx-clock.yaml index 982d698e8c54..e50cddee43c3 100644 --- a/Documentation/devicetree/bindings/clock/imx6sx-clock.yaml +++ b/Documentation/devicetree/bindings/clock/imx6sx-clock.yaml @@ -23,7 +23,6 @@ properties: items: - description: CCM interrupt request 1 - description: CCM interrupt request 2 - maxItems: 2 '#clock-cells': const: 1 diff --git a/Documentation/devicetree/bindings/clock/imx6ul-clock.yaml b/Documentation/devicetree/bindings/clock/imx6ul-clock.yaml index 3c779eea6394..36ce7667c972 100644 --- a/Documentation/devicetree/bindings/clock/imx6ul-clock.yaml +++ b/Documentation/devicetree/bindings/clock/imx6ul-clock.yaml @@ -23,7 +23,6 @@ properties: items: - description: CCM interrupt request 1 - description: CCM interrupt request 2 - maxItems: 2 '#clock-cells': const: 1 diff --git a/Documentation/devicetree/bindings/clock/intel,agilex.yaml b/Documentation/devicetree/bindings/clock/intel,agilex.yaml new file mode 100644 index 000000000000..cf5a9eb803e6 --- /dev/null +++ b/Documentation/devicetree/bindings/clock/intel,agilex.yaml @@ -0,0 +1,46 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/clock/intel,agilex.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Intel SoCFPGA Agilex platform clock controller binding + +maintainers: + - Dinh Nguyen <dinguyen@kernel.org> + +description: + The Intel Agilex Clock controller is an integrated clock controller, which + generates and supplies to all modules. + +properties: + compatible: + const: intel,agilex-clkmgr + + '#clock-cells': + const: 1 + + reg: + maxItems: 1 + + clocks: + maxItems: 1 + +required: + - compatible + - reg + - clocks + - '#clock-cells' + +additionalProperties: false + +examples: + # Clock controller node: + - | + clkmgr: clock-controller@ffd10000 { + compatible = "intel,agilex-clkmgr"; + reg = <0xffd10000 0x1000>; + clocks = <&osc1>; + #clock-cells = <1>; + }; +... diff --git a/Documentation/devicetree/bindings/clock/intel,cgu-lgm.yaml b/Documentation/devicetree/bindings/clock/intel,cgu-lgm.yaml new file mode 100644 index 000000000000..6dc1414bfb7f --- /dev/null +++ b/Documentation/devicetree/bindings/clock/intel,cgu-lgm.yaml @@ -0,0 +1,44 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/clock/intel,cgu-lgm.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Intel Lightning Mountain SoC's Clock Controller(CGU) Binding + +maintainers: + - Rahul Tanwar <rahul.tanwar@linux.intel.com> + +description: | + Lightning Mountain(LGM) SoC's Clock Generation Unit(CGU) driver provides + all means to access the CGU hardware module in order to generate a series + of clocks for the whole system and individual peripherals. + + Please refer to include/dt-bindings/clock/intel,lgm-clk.h header file, it + defines all available clocks as macros. These macros can be used in device + tree sources. + +properties: + compatible: + const: intel,cgu-lgm + + reg: + maxItems: 1 + + '#clock-cells': + const: 1 + +required: + - compatible + - reg + - '#clock-cells' + +examples: + - | + cgu: clock-controller@e0200000 { + compatible = "intel,cgu-lgm"; + reg = <0xe0200000 0x33c>; + #clock-cells = <1>; + }; + +... diff --git a/Documentation/devicetree/bindings/clock/marvell,mmp2-audio-clock.yaml b/Documentation/devicetree/bindings/clock/marvell,mmp2-audio-clock.yaml new file mode 100644 index 000000000000..dffa73402da9 --- /dev/null +++ b/Documentation/devicetree/bindings/clock/marvell,mmp2-audio-clock.yaml @@ -0,0 +1,75 @@ +# SPDX-License-Identifier: (GPL-2.0+ OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/clock/marvell,mmp2-audio-clock.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Marvell MMP2 Audio Clock Controller + +maintainers: + - Lubomir Rintel <lkundrak@v3.sk> + +description: | + The audio clock controller generates and supplies the clocks to the audio + codec. + + Each clock is assigned an identifier and client nodes use this identifier + to specify the clock which they consume. + + All these identifiers could be found in + <dt-bindings/clock/marvell,mmp2-audio.h>. + +properties: + compatible: + enum: + - marvell,mmp2-audio-clock + + reg: + maxItems: 1 + + clocks: + items: + - description: Audio subsystem clock + - description: The crystal oscillator clock + - description: First I2S clock + - description: Second I2S clock + + clock-names: + items: + - const: audio + - const: vctcxo + - const: i2s0 + - const: i2s1 + + '#clock-cells': + const: 1 + + power-domains: + maxItems: 1 + +required: + - compatible + - reg + - clocks + - clock-names + - '#clock-cells' + +additionalProperties: false + +examples: + - | + #include <dt-bindings/clock/marvell,mmp2-audio.h> + #include <dt-bindings/clock/marvell,mmp2.h> + #include <dt-bindings/power/marvell,mmp2.h> + + clock-controller@d42a0c30 { + compatible = "marvell,mmp2-audio-clock"; + reg = <0xd42a0c30 0x10>; + clock-names = "audio", "vctcxo", "i2s0", "i2s1"; + clocks = <&soc_clocks MMP2_CLK_AUDIO>, + <&soc_clocks MMP2_CLK_VCTCXO>, + <&soc_clocks MMP2_CLK_I2S0>, + <&soc_clocks MMP2_CLK_I2S1>; + power-domains = <&soc_clocks MMP2_POWER_DOMAIN_AUDIO>; + #clock-cells = <1>; + }; diff --git a/Documentation/devicetree/bindings/clock/marvell,mmp2-clock.yaml b/Documentation/devicetree/bindings/clock/marvell,mmp2-clock.yaml index e2b6ac96bbcb..d68f0d196e7d 100644 --- a/Documentation/devicetree/bindings/clock/marvell,mmp2-clock.yaml +++ b/Documentation/devicetree/bindings/clock/marvell,mmp2-clock.yaml @@ -42,12 +42,16 @@ properties: '#reset-cells': const: 1 + '#power-domain-cells': + const: 1 + required: - compatible - reg - reg-names - '#clock-cells' - '#reset-cells' + - '#power-domain-cells' additionalProperties: false @@ -61,4 +65,5 @@ examples: reg-names = "mpmu", "apmu", "apbc"; #clock-cells = <1>; #reset-cells = <1>; + #power-domain-cells = <1>; }; diff --git a/Documentation/devicetree/bindings/clock/qcom,a53pll.txt b/Documentation/devicetree/bindings/clock/qcom,a53pll.txt deleted file mode 100644 index e3fa8118eaee..000000000000 --- a/Documentation/devicetree/bindings/clock/qcom,a53pll.txt +++ /dev/null @@ -1,22 +0,0 @@ -Qualcomm MSM8916 A53 PLL Binding --------------------------------- -The A53 PLL on MSM8916 platforms is the main CPU PLL used used for frequencies -above 1GHz. - -Required properties : -- compatible : Shall contain only one of the following: - - "qcom,msm8916-a53pll" - -- reg : shall contain base register location and length - -- #clock-cells : must be set to <0> - -Example: - - a53pll: clock@b016000 { - compatible = "qcom,msm8916-a53pll"; - reg = <0xb016000 0x40>; - #clock-cells = <0>; - }; - diff --git a/Documentation/devicetree/bindings/clock/qcom,a53pll.yaml b/Documentation/devicetree/bindings/clock/qcom,a53pll.yaml new file mode 100644 index 000000000000..20d2638b4cd2 --- /dev/null +++ b/Documentation/devicetree/bindings/clock/qcom,a53pll.yaml @@ -0,0 +1,40 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/clock/qcom,a53pll.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Qualcomm A53 PLL Binding + +maintainers: + - Sivaprakash Murugesan <sivaprak@codeaurora.org> + +description: + The A53 PLL on few Qualcomm platforms is the main CPU PLL used used for + frequencies above 1GHz. + +properties: + compatible: + const: qcom,msm8916-a53pll + + reg: + maxItems: 1 + + '#clock-cells': + const: 0 + +required: + - compatible + - reg + - '#clock-cells' + +additionalProperties: false + +examples: + #Example 1 - A53 PLL found on MSM8916 devices + - | + a53pll: clock@b016000 { + compatible = "qcom,msm8916-a53pll"; + reg = <0xb016000 0x40>; + #clock-cells = <0>; + }; diff --git a/Documentation/devicetree/bindings/clock/qcom,gcc.yaml b/Documentation/devicetree/bindings/clock/qcom,gcc.yaml index e533bb0cfd2b..ee0467fb5e31 100644 --- a/Documentation/devicetree/bindings/clock/qcom,gcc.yaml +++ b/Documentation/devicetree/bindings/clock/qcom,gcc.yaml @@ -22,6 +22,8 @@ description: | - dt-bindings/reset/qcom,gcc-ipq6018.h - dt-bindings/clock/qcom,gcc-ipq806x.h (qcom,gcc-ipq8064) - dt-bindings/reset/qcom,gcc-ipq806x.h (qcom,gcc-ipq8064) + - dt-bindings/clock/qcom,gcc-msm8939.h + - dt-bindings/reset/qcom,gcc-msm8939.h - dt-bindings/clock/qcom,gcc-msm8660.h - dt-bindings/reset/qcom,gcc-msm8660.h - dt-bindings/clock/qcom,gcc-msm8974.h @@ -41,6 +43,7 @@ properties: - qcom,gcc-ipq8064 - qcom,gcc-msm8660 - qcom,gcc-msm8916 + - qcom,gcc-msm8939 - qcom,gcc-msm8960 - qcom,gcc-msm8974 - qcom,gcc-msm8974pro diff --git a/Documentation/devicetree/bindings/clock/qcom,mmcc.yaml b/Documentation/devicetree/bindings/clock/qcom,mmcc.yaml index acc31b3991bd..1b16a863b355 100644 --- a/Documentation/devicetree/bindings/clock/qcom,mmcc.yaml +++ b/Documentation/devicetree/bindings/clock/qcom,mmcc.yaml @@ -67,6 +67,10 @@ properties: description: Protected clock specifier list as per common clock binding + vdd-gfx-supply: + description: + Regulator supply for the GPU_GX GDSC + required: - compatible - reg diff --git a/Documentation/devicetree/bindings/clock/renesas,cpg-div6-clock.yaml b/Documentation/devicetree/bindings/clock/renesas,cpg-div6-clock.yaml new file mode 100644 index 000000000000..c55a7c494e01 --- /dev/null +++ b/Documentation/devicetree/bindings/clock/renesas,cpg-div6-clock.yaml @@ -0,0 +1,60 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/clock/renesas,cpg-div6-clock.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Renesas CPG DIV6 Clock + +maintainers: + - Geert Uytterhoeven <geert+renesas@glider.be> + +description: + The CPG DIV6 clocks are variable factor clocks provided by the Clock Pulse + Generator (CPG). Their clock input is divided by a configurable factor from 1 + to 64. + +properties: + compatible: + items: + - enum: + - renesas,r8a73a4-div6-clock # R-Mobile APE6 + - renesas,r8a7740-div6-clock # R-Mobile A1 + - renesas,sh73a0-div6-clock # SH-Mobile AG5 + - const: renesas,cpg-div6-clock + + reg: + maxItems: 1 + + clocks: + oneOf: + - maxItems: 1 + - maxItems: 4 + - maxItems: 8 + description: + For clocks with multiple parents, invalid settings must be specified as + "<0>". + + '#clock-cells': + const: 0 + + clock-output-names: true + +required: + - compatible + - reg + - clocks + - '#clock-cells' + +additionalProperties: false + +examples: + - | + #include <dt-bindings/clock/r8a73a4-clock.h> + sdhi2_clk: sdhi2_clk@e615007c { + compatible = "renesas,r8a73a4-div6-clock", "renesas,cpg-div6-clock"; + reg = <0xe615007c 4>; + clocks = <&pll1_div2_clk>, <&cpg_clocks R8A73A4_CLK_PLL2S>, <0>, + <&extal2_clk>; + #clock-cells = <0>; + }; diff --git a/Documentation/devicetree/bindings/clock/renesas,cpg-div6-clocks.txt b/Documentation/devicetree/bindings/clock/renesas,cpg-div6-clocks.txt deleted file mode 100644 index ae36ab842919..000000000000 --- a/Documentation/devicetree/bindings/clock/renesas,cpg-div6-clocks.txt +++ /dev/null @@ -1,40 +0,0 @@ -* Renesas CPG DIV6 Clock - -The CPG DIV6 clocks are variable factor clocks provided by the Clock Pulse -Generator (CPG). Their clock input is divided by a configurable factor from 1 -to 64. - -Required Properties: - - - compatible: Must be one of the following - - "renesas,r8a73a4-div6-clock" for R8A73A4 (R-Mobile APE6) DIV6 clocks - - "renesas,r8a7740-div6-clock" for R8A7740 (R-Mobile A1) DIV6 clocks - - "renesas,r8a7790-div6-clock" for R8A7790 (R-Car H2) DIV6 clocks - - "renesas,r8a7791-div6-clock" for R8A7791 (R-Car M2-W) DIV6 clocks - - "renesas,r8a7793-div6-clock" for R8A7793 (R-Car M2-N) DIV6 clocks - - "renesas,r8a7794-div6-clock" for R8A7794 (R-Car E2) DIV6 clocks - - "renesas,sh73a0-div6-clock" for SH73A0 (SH-Mobile AG5) DIV6 clocks - and "renesas,cpg-div6-clock" as a fallback. - - reg: Base address and length of the memory resource used by the DIV6 clock - - clocks: Reference to the parent clock(s); either one, four, or eight - clocks must be specified. For clocks with multiple parents, invalid - settings must be specified as "<0>". - - #clock-cells: Must be 0 - - -Optional Properties: - - - clock-output-names: The name of the clock as a free-form string - - -Example -------- - - sdhi2_clk: sdhi2_clk@e615007c { - compatible = "renesas,r8a73a4-div6-clock", "renesas,cpg-div6-clock"; - reg = <0 0xe615007c 0 4>; - clocks = <&pll1_div2_clk>, <&cpg_clocks R8A73A4_CLK_PLL2S>, - <0>, <&extal2_clk>; - #clock-cells = <0>; - clock-output-names = "sdhi2ck"; - }; diff --git a/Documentation/devicetree/bindings/clock/renesas,cpg-mssr.yaml b/Documentation/devicetree/bindings/clock/renesas,cpg-mssr.yaml index 9cd102e5fed5..c745bd60719a 100644 --- a/Documentation/devicetree/bindings/clock/renesas,cpg-mssr.yaml +++ b/Documentation/devicetree/bindings/clock/renesas,cpg-mssr.yaml @@ -25,6 +25,7 @@ properties: compatible: enum: - renesas,r7s9210-cpg-mssr # RZ/A2 + - renesas,r8a7742-cpg-mssr # RZ/G1H - renesas,r8a7743-cpg-mssr # RZ/G1M - renesas,r8a7744-cpg-mssr # RZ/G1N - renesas,r8a7745-cpg-mssr # RZ/G1E diff --git a/Documentation/devicetree/bindings/clock/renesas,cpg-mstp-clocks.txt b/Documentation/devicetree/bindings/clock/renesas,cpg-mstp-clocks.txt deleted file mode 100644 index da578ebdda28..000000000000 --- a/Documentation/devicetree/bindings/clock/renesas,cpg-mstp-clocks.txt +++ /dev/null @@ -1,60 +0,0 @@ -* Renesas CPG Module Stop (MSTP) Clocks - -The CPG can gate SoC device clocks. The gates are organized in groups of up to -32 gates. - -This device tree binding describes a single 32 gate clocks group per node. -Clocks are referenced by user nodes by the MSTP node phandle and the clock -index in the group, from 0 to 31. - -Required Properties: - - - compatible: Must be one of the following - - "renesas,r7s72100-mstp-clocks" for R7S72100 (RZ) MSTP gate clocks - - "renesas,r8a73a4-mstp-clocks" for R8A73A4 (R-Mobile APE6) MSTP gate clocks - - "renesas,r8a7740-mstp-clocks" for R8A7740 (R-Mobile A1) MSTP gate clocks - - "renesas,r8a7778-mstp-clocks" for R8A7778 (R-Car M1) MSTP gate clocks - - "renesas,r8a7779-mstp-clocks" for R8A7779 (R-Car H1) MSTP gate clocks - - "renesas,r8a7790-mstp-clocks" for R8A7790 (R-Car H2) MSTP gate clocks - - "renesas,r8a7791-mstp-clocks" for R8A7791 (R-Car M2-W) MSTP gate clocks - - "renesas,r8a7792-mstp-clocks" for R8A7792 (R-Car V2H) MSTP gate clocks - - "renesas,r8a7793-mstp-clocks" for R8A7793 (R-Car M2-N) MSTP gate clocks - - "renesas,r8a7794-mstp-clocks" for R8A7794 (R-Car E2) MSTP gate clocks - - "renesas,sh73a0-mstp-clocks" for SH73A0 (SH-MobileAG5) MSTP gate clocks - and "renesas,cpg-mstp-clocks" as a fallback. - - reg: Base address and length of the I/O mapped registers used by the MSTP - clocks. The first register is the clock control register and is mandatory. - The second register is the clock status register and is optional when not - implemented in hardware. - - clocks: Reference to the parent clocks, one per output clock. The parents - must appear in the same order as the output clocks. - - #clock-cells: Must be 1 - - clock-output-names: The name of the clocks as free-form strings - - clock-indices: Indices of the gate clocks into the group (0 to 31) - -The clocks, clock-output-names and clock-indices properties contain one entry -per gate clock. The MSTP groups are sparsely populated. Unimplemented gate -clocks must not be declared. - - -Example -------- - - #include <dt-bindings/clock/r8a7790-clock.h> - - mstp3_clks: mstp3_clks@e615013c { - compatible = "renesas,r8a7790-mstp-clocks", "renesas,cpg-mstp-clocks"; - reg = <0 0xe615013c 0 4>, <0 0xe6150048 0 4>; - clocks = <&cp_clk>, <&mmc1_clk>, <&sd3_clk>, <&sd2_clk>, - <&cpg_clocks R8A7790_CLK_SD1>, <&cpg_clocks R8A7790_CLK_SD0>, - <&mmc0_clk>; - #clock-cells = <1>; - clock-output-names = - "tpu0", "mmcif1", "sdhi3", "sdhi2", - "sdhi1", "sdhi0", "mmcif0"; - clock-indices = < - R8A7790_CLK_TPU0 R8A7790_CLK_MMCIF1 R8A7790_CLK_SDHI3 - R8A7790_CLK_SDHI2 R8A7790_CLK_SDHI1 R8A7790_CLK_SDHI0 - R8A7790_CLK_MMCIF0 - >; - }; diff --git a/Documentation/devicetree/bindings/clock/renesas,cpg-mstp-clocks.yaml b/Documentation/devicetree/bindings/clock/renesas,cpg-mstp-clocks.yaml new file mode 100644 index 000000000000..9752ac63288b --- /dev/null +++ b/Documentation/devicetree/bindings/clock/renesas,cpg-mstp-clocks.yaml @@ -0,0 +1,82 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/clock/renesas,cpg-mstp-clocks.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Renesas Clock Pulse Generator (CPG) Module Stop (MSTP) Clocks + +maintainers: + - Geert Uytterhoeven <geert+renesas@glider.be> + +description: + The Clock Pulse Generator (CPG) can gate SoC device clocks. The gates are + organized in groups of up to 32 gates. + + This device tree binding describes a single 32 gate clocks group per node. + Clocks are referenced by user nodes by the Module Stop (MSTP) node phandle + and the clock index in the group, from 0 to 31. + +properties: + compatible: + items: + - enum: + - renesas,r7s72100-mstp-clocks # RZ/A1 + - renesas,r8a73a4-mstp-clocks # R-Mobile APE6 + - renesas,r8a7740-mstp-clocks # R-Mobile A1 + - renesas,r8a7778-mstp-clocks # R-Car M1 + - renesas,r8a7779-mstp-clocks # R-Car H1 + - renesas,sh73a0-mstp-clocks # SH-Mobile AG5 + - const: renesas,cpg-mstp-clocks + + reg: + minItems: 1 + items: + - description: Module Stop Control Register (MSTPCR) + - description: Module Stop Status Register (MSTPSR) + + clocks: + minItems: 1 + maxItems: 32 + + '#clock-cells': + const: 1 + + clock-indices: + minItems: 1 + maxItems: 32 + + clock-output-names: + minItems: 1 + maxItems: 32 + +required: + - compatible + - reg + - clocks + - '#clock-cells' + - clock-indices + - clock-output-names + +additionalProperties: false + +examples: + - | + #include <dt-bindings/clock/r8a73a4-clock.h> + mstp2_clks: mstp2_clks@e6150138 { + compatible = "renesas,r8a73a4-mstp-clocks", + "renesas,cpg-mstp-clocks"; + reg = <0xe6150138 4>, <0xe6150040 4>; + clocks = <&mp_clk>, <&mp_clk>, <&mp_clk>, <&mp_clk>, <&mp_clk>, + <&mp_clk>, <&cpg_clocks R8A73A4_CLK_HP>; + #clock-cells = <1>; + clock-indices = < + R8A73A4_CLK_SCIFA0 R8A73A4_CLK_SCIFA1 + R8A73A4_CLK_SCIFB0 R8A73A4_CLK_SCIFB1 + R8A73A4_CLK_SCIFB2 R8A73A4_CLK_SCIFB3 + R8A73A4_CLK_DMAC + >; + clock-output-names = + "scifa0", "scifa1", "scifb0", "scifb1", "scifb2", "scifb3", + "dmac"; + }; diff --git a/Documentation/devicetree/bindings/clock/renesas,rcar-usb2-clock-sel.txt b/Documentation/devicetree/bindings/clock/renesas,rcar-usb2-clock-sel.txt index 4bf6f53bd95e..da92f5748dee 100644 --- a/Documentation/devicetree/bindings/clock/renesas,rcar-usb2-clock-sel.txt +++ b/Documentation/devicetree/bindings/clock/renesas,rcar-usb2-clock-sel.txt @@ -27,7 +27,9 @@ Required properties: - compatible: "renesas,r8a7795-rcar-usb2-clock-sel" if the device is a part of an R8A7795 SoC. "renesas,r8a7796-rcar-usb2-clock-sel" if the device if a part of - an R8A7796 SoC. + an R8A77960 SoC. + "renesas,r8a77961-rcar-usb2-clock-sel" if the device if a part of + an R8A77961 SoC. "renesas,rcar-gen3-usb2-clock-sel" for a generic R-Car Gen3 compatible device. diff --git a/Documentation/devicetree/bindings/clock/silabs,si5341.txt b/Documentation/devicetree/bindings/clock/silabs,si5341.txt index a70c333e4cd4..504cce3abe46 100644 --- a/Documentation/devicetree/bindings/clock/silabs,si5341.txt +++ b/Documentation/devicetree/bindings/clock/silabs,si5341.txt @@ -1,15 +1,21 @@ -Binding for Silicon Labs Si5341 and Si5340 programmable i2c clock generator. +Binding for Silicon Labs Si5340, Si5341 Si5342, Si5344 and Si5345 programmable +i2c clock generator. Reference [1] Si5341 Data Sheet https://www.silabs.com/documents/public/data-sheets/Si5341-40-D-DataSheet.pdf [2] Si5341 Reference Manual https://www.silabs.com/documents/public/reference-manuals/Si5341-40-D-RM.pdf +[3] Si5345 Reference Manual + https://www.silabs.com/documents/public/reference-manuals/Si5345-44-42-D-RM.pdf The Si5341 and Si5340 are programmable i2c clock generators with up to 10 output clocks. The chip contains a PLL that sources 5 (or 4) multisynth clocks, which in turn can be directed to any of the 10 (or 4) outputs through a divider. The internal structure of the clock generators can be found in [2]. +The Si5345 is similar to the Si5341 with the addition of fractional input +dividers and automatic input selection, as described in [3]. +The Si5342 and Si5344 are smaller versions of the Si5345, with 2 or 4 outputs. The driver can be used in "as is" mode, reading the current settings from the chip at boot, in case you have a (pre-)programmed device. If the PLL is not @@ -28,6 +34,9 @@ Required properties: - compatible: shall be one of the following: "silabs,si5340" - Si5340 A/B/C/D "silabs,si5341" - Si5341 A/B/C/D + "silabs,si5342" - Si5342 A/B/C/D + "silabs,si5344" - Si5344 A/B/C/D + "silabs,si5345" - Si5345 A/B/C/D - reg: i2c device address, usually 0x74 - #clock-cells: from common clock binding; shall be set to 2. The first value is "0" for outputs, "1" for synthesizers. diff --git a/Documentation/devicetree/bindings/clock/sprd,sc9863a-clk.yaml b/Documentation/devicetree/bindings/clock/sprd,sc9863a-clk.yaml index 14ae4ea3bc20..29813873cfbc 100644 --- a/Documentation/devicetree/bindings/clock/sprd,sc9863a-clk.yaml +++ b/Documentation/devicetree/bindings/clock/sprd,sc9863a-clk.yaml @@ -28,6 +28,7 @@ properties: - sprd,sc9863a-rpll - sprd,sc9863a-dpll - sprd,sc9863a-mm-gate + - sprd,sc9863a-mm-clk - sprd,sc9863a-apapb-gate clocks: diff --git a/Documentation/devicetree/bindings/display/rockchip/rockchip-vop.yaml b/Documentation/devicetree/bindings/display/rockchip/rockchip-vop.yaml index 1695e3e4bcec..ed8148e26e24 100644 --- a/Documentation/devicetree/bindings/display/rockchip/rockchip-vop.yaml +++ b/Documentation/devicetree/bindings/display/rockchip/rockchip-vop.yaml @@ -106,8 +106,8 @@ examples: #include <dt-bindings/power/rk3288-power.h> vopb: vopb@ff930000 { compatible = "rockchip,rk3288-vop"; - reg = <0x0 0xff930000 0x0 0x19c>, - <0x0 0xff931000 0x0 0x1000>; + reg = <0xff930000 0x19c>, + <0xff931000 0x1000>; interrupts = <GIC_SPI 15 IRQ_TYPE_LEVEL_HIGH>; clocks = <&cru ACLK_VOP0>, <&cru DCLK_VOP0>, diff --git a/Documentation/devicetree/bindings/dma/renesas,rcar-dmac.txt b/Documentation/devicetree/bindings/dma/renesas,rcar-dmac.txt deleted file mode 100644 index b7f81c63be8b..000000000000 --- a/Documentation/devicetree/bindings/dma/renesas,rcar-dmac.txt +++ /dev/null @@ -1,117 +0,0 @@ -* Renesas R-Car (RZ/G) DMA Controller Device Tree bindings - -Renesas R-Car (Gen 2/3) and RZ/G SoCs have multiple multi-channel DMA -controller instances named DMAC capable of serving multiple clients. Channels -can be dedicated to specific clients or shared between a large number of -clients. - -Each DMA client is connected to one dedicated port of the DMAC, identified by -an 8-bit port number called the MID/RID. A DMA controller can thus serve up to -256 clients in total. When the number of hardware channels is lower than the -number of clients to be served, channels must be shared between multiple DMA -clients. The association of DMA clients to DMAC channels is fully dynamic and -not described in these device tree bindings. - -Required Properties: - -- compatible: "renesas,dmac-<soctype>", "renesas,rcar-dmac" as fallback. - Examples with soctypes are: - - "renesas,dmac-r8a7743" (RZ/G1M) - - "renesas,dmac-r8a7744" (RZ/G1N) - - "renesas,dmac-r8a7745" (RZ/G1E) - - "renesas,dmac-r8a77470" (RZ/G1C) - - "renesas,dmac-r8a774a1" (RZ/G2M) - - "renesas,dmac-r8a774b1" (RZ/G2N) - - "renesas,dmac-r8a774c0" (RZ/G2E) - - "renesas,dmac-r8a7790" (R-Car H2) - - "renesas,dmac-r8a7791" (R-Car M2-W) - - "renesas,dmac-r8a7792" (R-Car V2H) - - "renesas,dmac-r8a7793" (R-Car M2-N) - - "renesas,dmac-r8a7794" (R-Car E2) - - "renesas,dmac-r8a7795" (R-Car H3) - - "renesas,dmac-r8a7796" (R-Car M3-W) - - "renesas,dmac-r8a77961" (R-Car M3-W+) - - "renesas,dmac-r8a77965" (R-Car M3-N) - - "renesas,dmac-r8a77970" (R-Car V3M) - - "renesas,dmac-r8a77980" (R-Car V3H) - - "renesas,dmac-r8a77990" (R-Car E3) - - "renesas,dmac-r8a77995" (R-Car D3) - -- reg: base address and length of the registers block for the DMAC - -- interrupts: interrupt specifiers for the DMAC, one for each entry in - interrupt-names. -- interrupt-names: one entry for the error interrupt, named "error", plus one - entry per channel, named "ch%u", where %u is the channel number ranging from - zero to the number of channels minus one. - -- clock-names: "fck" for the functional clock -- clocks: a list of phandle + clock-specifier pairs, one for each entry - in clock-names. -- clock-names: must contain "fck" for the functional clock. - -- #dma-cells: must be <1>, the cell specifies the MID/RID of the DMAC port - connected to the DMA client -- dma-channels: number of DMA channels - -Example: R8A7790 (R-Car H2) SYS-DMACs - - dmac0: dma-controller@e6700000 { - compatible = "renesas,dmac-r8a7790", "renesas,rcar-dmac"; - reg = <0 0xe6700000 0 0x20000>; - interrupts = <0 197 IRQ_TYPE_LEVEL_HIGH - 0 200 IRQ_TYPE_LEVEL_HIGH - 0 201 IRQ_TYPE_LEVEL_HIGH - 0 202 IRQ_TYPE_LEVEL_HIGH - 0 203 IRQ_TYPE_LEVEL_HIGH - 0 204 IRQ_TYPE_LEVEL_HIGH - 0 205 IRQ_TYPE_LEVEL_HIGH - 0 206 IRQ_TYPE_LEVEL_HIGH - 0 207 IRQ_TYPE_LEVEL_HIGH - 0 208 IRQ_TYPE_LEVEL_HIGH - 0 209 IRQ_TYPE_LEVEL_HIGH - 0 210 IRQ_TYPE_LEVEL_HIGH - 0 211 IRQ_TYPE_LEVEL_HIGH - 0 212 IRQ_TYPE_LEVEL_HIGH - 0 213 IRQ_TYPE_LEVEL_HIGH - 0 214 IRQ_TYPE_LEVEL_HIGH>; - interrupt-names = "error", - "ch0", "ch1", "ch2", "ch3", - "ch4", "ch5", "ch6", "ch7", - "ch8", "ch9", "ch10", "ch11", - "ch12", "ch13", "ch14"; - clocks = <&mstp2_clks R8A7790_CLK_SYS_DMAC0>; - clock-names = "fck"; - #dma-cells = <1>; - dma-channels = <15>; - }; - - dmac1: dma-controller@e6720000 { - compatible = "renesas,dmac-r8a7790", "renesas,rcar-dmac"; - reg = <0 0xe6720000 0 0x20000>; - interrupts = <0 220 IRQ_TYPE_LEVEL_HIGH - 0 216 IRQ_TYPE_LEVEL_HIGH - 0 217 IRQ_TYPE_LEVEL_HIGH - 0 218 IRQ_TYPE_LEVEL_HIGH - 0 219 IRQ_TYPE_LEVEL_HIGH - 0 308 IRQ_TYPE_LEVEL_HIGH - 0 309 IRQ_TYPE_LEVEL_HIGH - 0 310 IRQ_TYPE_LEVEL_HIGH - 0 311 IRQ_TYPE_LEVEL_HIGH - 0 312 IRQ_TYPE_LEVEL_HIGH - 0 313 IRQ_TYPE_LEVEL_HIGH - 0 314 IRQ_TYPE_LEVEL_HIGH - 0 315 IRQ_TYPE_LEVEL_HIGH - 0 316 IRQ_TYPE_LEVEL_HIGH - 0 317 IRQ_TYPE_LEVEL_HIGH - 0 318 IRQ_TYPE_LEVEL_HIGH>; - interrupt-names = "error", - "ch0", "ch1", "ch2", "ch3", - "ch4", "ch5", "ch6", "ch7", - "ch8", "ch9", "ch10", "ch11", - "ch12", "ch13", "ch14"; - clocks = <&mstp2_clks R8A7790_CLK_SYS_DMAC1>; - clock-names = "fck"; - #dma-cells = <1>; - dma-channels = <15>; - }; diff --git a/Documentation/devicetree/bindings/dma/renesas,rcar-dmac.yaml b/Documentation/devicetree/bindings/dma/renesas,rcar-dmac.yaml new file mode 100644 index 000000000000..b842dfd96a89 --- /dev/null +++ b/Documentation/devicetree/bindings/dma/renesas,rcar-dmac.yaml @@ -0,0 +1,150 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/dma/renesas,rcar-dmac.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Renesas R-Car and RZ/G DMA Controller + +maintainers: + - Yoshihiro Shimoda <yoshihiro.shimoda.uh@renesas.com> + +allOf: + - $ref: "dma-controller.yaml#" + +properties: + compatible: + items: + - enum: + - renesas,dmac-r8a7743 # RZ/G1M + - renesas,dmac-r8a7744 # RZ/G1N + - renesas,dmac-r8a7745 # RZ/G1E + - renesas,dmac-r8a77470 # RZ/G1C + - renesas,dmac-r8a774a1 # RZ/G2M + - renesas,dmac-r8a774b1 # RZ/G2N + - renesas,dmac-r8a774c0 # RZ/G2E + - renesas,dmac-r8a7790 # R-Car H2 + - renesas,dmac-r8a7791 # R-Car M2-W + - renesas,dmac-r8a7792 # R-Car V2H + - renesas,dmac-r8a7793 # R-Car M2-N + - renesas,dmac-r8a7794 # R-Car E2 + - renesas,dmac-r8a7795 # R-Car H3 + - renesas,dmac-r8a7796 # R-Car M3-W + - renesas,dmac-r8a77961 # R-Car M3-W+ + - renesas,dmac-r8a77965 # R-Car M3-N + - renesas,dmac-r8a77970 # R-Car V3M + - renesas,dmac-r8a77980 # R-Car V3H + - renesas,dmac-r8a77990 # R-Car E3 + - renesas,dmac-r8a77995 # R-Car D3 + - const: renesas,rcar-dmac + + reg: + maxItems: 1 + + interrupts: + minItems: 9 + maxItems: 17 + + interrupt-names: + minItems: 9 + maxItems: 17 + items: + - const: error + - pattern: "^ch([0-9]|1[0-5])$" + - pattern: "^ch([0-9]|1[0-5])$" + - pattern: "^ch([0-9]|1[0-5])$" + - pattern: "^ch([0-9]|1[0-5])$" + - pattern: "^ch([0-9]|1[0-5])$" + - pattern: "^ch([0-9]|1[0-5])$" + - pattern: "^ch([0-9]|1[0-5])$" + - pattern: "^ch([0-9]|1[0-5])$" + - pattern: "^ch([0-9]|1[0-5])$" + - pattern: "^ch([0-9]|1[0-5])$" + - pattern: "^ch([0-9]|1[0-5])$" + - pattern: "^ch([0-9]|1[0-5])$" + - pattern: "^ch([0-9]|1[0-5])$" + - pattern: "^ch([0-9]|1[0-5])$" + - pattern: "^ch([0-9]|1[0-5])$" + - pattern: "^ch([0-9]|1[0-5])$" + + clocks: + maxItems: 1 + + clock-names: + maxItems: 1 + items: + - const: fck + + '#dma-cells': + const: 1 + description: + The cell specifies the MID/RID of the DMAC port connected to + the DMA client. + + dma-channels: + minimum: 8 + maximum: 16 + + dma-channel-mask: true + + iommus: + minItems: 8 + maxItems: 16 + + power-domains: + maxItems: 1 + + resets: + maxItems: 1 + +required: + - compatible + - reg + - interrupts + - interrupt-names + - clocks + - clock-names + - '#dma-cells' + - dma-channels + - power-domains + - resets + +additionalProperties: false + +examples: + - | + #include <dt-bindings/clock/r8a7790-cpg-mssr.h> + #include <dt-bindings/interrupt-controller/arm-gic.h> + #include <dt-bindings/power/r8a7790-sysc.h> + + dmac0: dma-controller@e6700000 { + compatible = "renesas,dmac-r8a7790", "renesas,rcar-dmac"; + reg = <0xe6700000 0x20000>; + interrupts = <GIC_SPI 197 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 200 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 201 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 202 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 203 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 204 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 205 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 206 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 207 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 208 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 209 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 210 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 211 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 212 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 213 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 214 IRQ_TYPE_LEVEL_HIGH>; + interrupt-names = "error", + "ch0", "ch1", "ch2", "ch3", + "ch4", "ch5", "ch6", "ch7", + "ch8", "ch9", "ch10", "ch11", + "ch12", "ch13", "ch14"; + clocks = <&cpg CPG_MOD 219>; + clock-names = "fck"; + power-domains = <&sysc R8A7790_PD_ALWAYS_ON>; + resets = <&cpg 219>; + #dma-cells = <1>; + dma-channels = <15>; + }; diff --git a/Documentation/devicetree/bindings/dma/renesas,usb-dmac.txt b/Documentation/devicetree/bindings/dma/renesas,usb-dmac.txt deleted file mode 100644 index e8f6c42e80f2..000000000000 --- a/Documentation/devicetree/bindings/dma/renesas,usb-dmac.txt +++ /dev/null @@ -1,55 +0,0 @@ -* Renesas USB DMA Controller Device Tree bindings - -Required Properties: --compatible: "renesas,<soctype>-usb-dmac", "renesas,usb-dmac" as fallback. - Examples with soctypes are: - - "renesas,r8a7743-usb-dmac" (RZ/G1M) - - "renesas,r8a7744-usb-dmac" (RZ/G1N) - - "renesas,r8a7745-usb-dmac" (RZ/G1E) - - "renesas,r8a77470-usb-dmac" (RZ/G1C) - - "renesas,r8a774a1-usb-dmac" (RZ/G2M) - - "renesas,r8a774b1-usb-dmac" (RZ/G2N) - - "renesas,r8a774c0-usb-dmac" (RZ/G2E) - - "renesas,r8a7790-usb-dmac" (R-Car H2) - - "renesas,r8a7791-usb-dmac" (R-Car M2-W) - - "renesas,r8a7793-usb-dmac" (R-Car M2-N) - - "renesas,r8a7794-usb-dmac" (R-Car E2) - - "renesas,r8a7795-usb-dmac" (R-Car H3) - - "renesas,r8a7796-usb-dmac" (R-Car M3-W) - - "renesas,r8a77961-usb-dmac" (R-Car M3-W+) - - "renesas,r8a77965-usb-dmac" (R-Car M3-N) - - "renesas,r8a77990-usb-dmac" (R-Car E3) - - "renesas,r8a77995-usb-dmac" (R-Car D3) -- reg: base address and length of the registers block for the DMAC -- interrupts: interrupt specifiers for the DMAC, one for each entry in - interrupt-names. -- interrupt-names: one entry per channel, named "ch%u", where %u is the - channel number ranging from zero to the number of channels minus one. -- clocks: a list of phandle + clock-specifier pairs. -- #dma-cells: must be <1>, the cell specifies the channel number of the DMAC - port connected to the DMA client. -- dma-channels: number of DMA channels - -Example: R8A7790 (R-Car H2) USB-DMACs - - usb_dmac0: dma-controller@e65a0000 { - compatible = "renesas,r8a7790-usb-dmac", "renesas,usb-dmac"; - reg = <0 0xe65a0000 0 0x100>; - interrupts = <0 109 IRQ_TYPE_LEVEL_HIGH - 0 109 IRQ_TYPE_LEVEL_HIGH>; - interrupt-names = "ch0", "ch1"; - clocks = <&mstp3_clks R8A7790_CLK_USBDMAC0>; - #dma-cells = <1>; - dma-channels = <2>; - }; - - usb_dmac1: dma-controller@e65b0000 { - compatible = "renesas,usb-dmac"; - reg = <0 0xe65b0000 0 0x100>; - interrupts = <0 110 IRQ_TYPE_LEVEL_HIGH - 0 110 IRQ_TYPE_LEVEL_HIGH>; - interrupt-names = "ch0", "ch1"; - clocks = <&mstp3_clks R8A7790_CLK_USBDMAC1>; - #dma-cells = <1>; - dma-channels = <2>; - }; diff --git a/Documentation/devicetree/bindings/dma/renesas,usb-dmac.yaml b/Documentation/devicetree/bindings/dma/renesas,usb-dmac.yaml new file mode 100644 index 000000000000..9ca6d8ddf232 --- /dev/null +++ b/Documentation/devicetree/bindings/dma/renesas,usb-dmac.yaml @@ -0,0 +1,102 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/dma/renesas,usb-dmac.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Renesas USB DMA Controller + +maintainers: + - Yoshihiro Shimoda <yoshihiro.shimoda.uh@renesas.com> + +allOf: + - $ref: "dma-controller.yaml#" + +properties: + compatible: + items: + - enum: + - renesas,r8a7743-usb-dmac # RZ/G1M + - renesas,r8a7744-usb-dmac # RZ/G1N + - renesas,r8a7745-usb-dmac # RZ/G1E + - renesas,r8a77470-usb-dmac # RZ/G1C + - renesas,r8a774a1-usb-dmac # RZ/G2M + - renesas,r8a774b1-usb-dmac # RZ/G2N + - renesas,r8a774c0-usb-dmac # RZ/G2E + - renesas,r8a7790-usb-dmac # R-Car H2 + - renesas,r8a7791-usb-dmac # R-Car M2-W + - renesas,r8a7793-usb-dmac # R-Car M2-N + - renesas,r8a7794-usb-dmac # R-Car E2 + - renesas,r8a7795-usb-dmac # R-Car H3 + - renesas,r8a7796-usb-dmac # R-Car M3-W + - renesas,r8a77961-usb-dmac # R-Car M3-W+ + - renesas,r8a77965-usb-dmac # R-Car M3-N + - renesas,r8a77990-usb-dmac # R-Car E3 + - renesas,r8a77995-usb-dmac # R-Car D3 + - const: renesas,usb-dmac + + reg: + maxItems: 1 + + interrupts: + minItems: 2 + maxItems: 2 + + interrupt-names: + items: + - pattern: ch0 + - pattern: ch1 + + clocks: + maxItems: 1 + + '#dma-cells': + const: 1 + description: + The cell specifies the channel number of the DMAC port connected to + the DMA client. + + dma-channels: + const: 2 + + iommus: + minItems: 2 + maxItems: 2 + + power-domains: + maxItems: 1 + + resets: + maxItems: 1 + +required: + - compatible + - reg + - interrupts + - interrupt-names + - clocks + - '#dma-cells' + - dma-channels + - power-domains + - resets + +additionalProperties: false + +examples: + - | + #include <dt-bindings/clock/r8a7790-cpg-mssr.h> + #include <dt-bindings/interrupt-controller/arm-gic.h> + #include <dt-bindings/power/r8a7790-sysc.h> + + usb_dmac0: dma-controller@e65a0000 { + compatible = "renesas,r8a7790-usb-dmac", "renesas,usb-dmac"; + reg = <0xe65a0000 0x100>; + interrupts = <GIC_SPI 109 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 109 IRQ_TYPE_LEVEL_HIGH>; + interrupt-names = "ch0", "ch1"; + clocks = <&cpg CPG_MOD 330>; + power-domains = <&sysc R8A7790_PD_ALWAYS_ON>; + resets = <&cpg 330>; + #dma-cells = <1>; + dma-channels = <2>; + }; diff --git a/Documentation/devicetree/bindings/dma/st,stm32-dma.yaml b/Documentation/devicetree/bindings/dma/st,stm32-dma.yaml index 0c0ac11ad55f..71987878e4ae 100644 --- a/Documentation/devicetree/bindings/dma/st,stm32-dma.yaml +++ b/Documentation/devicetree/bindings/dma/st,stm32-dma.yaml @@ -36,6 +36,11 @@ description: | 0x1: 1/2 full FIFO 0x2: 3/4 full FIFO 0x3: full FIFO + -bit 2: DMA direct mode + 0x0: FIFO mode with threshold selectable with bit 0-1 + 0x1: Direct mode: each DMA request immediately initiates a transfer + from/to the memory, FIFO is bypassed. + maintainers: - Amelie Delaunay <amelie.delaunay@st.com> diff --git a/Documentation/devicetree/bindings/gpio/snps,dw-apb-gpio.yaml b/Documentation/devicetree/bindings/gpio/snps,dw-apb-gpio.yaml index 04a3c51e1dc1..1240f6289249 100644 --- a/Documentation/devicetree/bindings/gpio/snps,dw-apb-gpio.yaml +++ b/Documentation/devicetree/bindings/gpio/snps,dw-apb-gpio.yaml @@ -63,11 +63,10 @@ patternProperties: snps,nr-gpios: description: The number of GPIO pins exported by the port. + $ref: /schemas/types.yaml#/definitions/uint32 default: 32 - allOf: - - $ref: /schemas/types.yaml#/definitions/uint32 - - minimum: 1 - maximum: 32 + minimum: 1 + maximum: 32 interrupts: description: | diff --git a/Documentation/devicetree/bindings/i2c/i2c-designware.txt b/Documentation/devicetree/bindings/i2c/i2c-designware.txt deleted file mode 100644 index 08be4d3846e5..000000000000 --- a/Documentation/devicetree/bindings/i2c/i2c-designware.txt +++ /dev/null @@ -1,73 +0,0 @@ -* Synopsys DesignWare I2C - -Required properties : - - - compatible : should be "snps,designware-i2c" - or "mscc,ocelot-i2c" with "snps,designware-i2c" for fallback - - reg : Offset and length of the register set for the device - - interrupts : <IRQ> where IRQ is the interrupt number. - - clocks : phandles for the clocks, see the description of clock-names below. - The phandle for the "ic_clk" clock is required. The phandle for the "pclk" - clock is optional. If a single clock is specified but no clock-name, it is - the "ic_clk" clock. If both clocks are listed, the "ic_clk" must be first. - -Recommended properties : - - - clock-frequency : desired I2C bus clock frequency in Hz. - -Optional properties : - - - clock-names : Contains the names of the clocks: - "ic_clk", for the core clock used to generate the external I2C clock. - "pclk", the interface clock, required for register access. - - - reg : for "mscc,ocelot-i2c", a second register set to configure the SDA hold - time, named ICPU_CFG:TWI_DELAY in the datasheet. - - - i2c-sda-hold-time-ns : should contain the SDA hold time in nanoseconds. - This option is only supported in hardware blocks version 1.11a or newer and - on Microsemi SoCs ("mscc,ocelot-i2c" compatible). - - - i2c-scl-falling-time-ns : should contain the SCL falling time in nanoseconds. - This value which is by default 300ns is used to compute the tLOW period. - - - i2c-sda-falling-time-ns : should contain the SDA falling time in nanoseconds. - This value which is by default 300ns is used to compute the tHIGH period. - -Examples : - - i2c@f0000 { - #address-cells = <1>; - #size-cells = <0>; - compatible = "snps,designware-i2c"; - reg = <0xf0000 0x1000>; - interrupts = <11>; - clock-frequency = <400000>; - }; - - i2c@1120000 { - #address-cells = <1>; - #size-cells = <0>; - compatible = "snps,designware-i2c"; - reg = <0x1120000 0x1000>; - interrupt-parent = <&ictl>; - interrupts = <12 1>; - clock-frequency = <400000>; - i2c-sda-hold-time-ns = <300>; - i2c-sda-falling-time-ns = <300>; - i2c-scl-falling-time-ns = <300>; - }; - - i2c@1120000 { - #address-cells = <1>; - #size-cells = <0>; - reg = <0x2000 0x100>; - clock-frequency = <400000>; - clocks = <&i2cclk>; - interrupts = <0>; - - eeprom@64 { - compatible = "linux,slave-24c02"; - reg = <0x40000064>; - }; - }; diff --git a/Documentation/devicetree/bindings/i2c/i2c-qcom-cci.txt b/Documentation/devicetree/bindings/i2c/i2c-qcom-cci.txt new file mode 100644 index 000000000000..c6668b7c66e6 --- /dev/null +++ b/Documentation/devicetree/bindings/i2c/i2c-qcom-cci.txt @@ -0,0 +1,92 @@ +Qualcomm Camera Control Interface (CCI) I2C controller + +PROPERTIES: + +- compatible: + Usage: required + Value type: <string> + Definition: must be one of: + "qcom,msm8916-cci" + "qcom,msm8996-cci" + "qcom,sdm845-cci" + +- reg + Usage: required + Value type: <prop-encoded-array> + Definition: base address CCI I2C controller and length of memory + mapped region. + +- interrupts: + Usage: required + Value type: <prop-encoded-array> + Definition: specifies the CCI I2C interrupt. The format of the + specifier is defined by the binding document describing + the node's interrupt parent. + +- clocks: + Usage: required + Value type: <prop-encoded-array> + Definition: a list of phandle, should contain an entry for each + entries in clock-names. + +- clock-names + Usage: required + Value type: <string> + Definition: a list of clock names, must include "cci" clock. + +- power-domains + Usage: required for "qcom,msm8996-cci" + Value type: <prop-encoded-array> + Definition: + +SUBNODES: + +The CCI provides I2C masters for one (msm8916) or two i2c busses (msm8996 and +sdm845), described as subdevices named "i2c-bus@0" and "i2c-bus@1". + +PROPERTIES: + +- reg: + Usage: required + Value type: <u32> + Definition: Index of the CCI bus/master + +- clock-frequency: + Usage: optional + Value type: <u32> + Definition: Desired I2C bus clock frequency in Hz, defaults to 100 + kHz if omitted. + +Example: + + cci@a0c000 { + compatible = "qcom,msm8996-cci"; + #address-cells = <1>; + #size-cells = <0>; + reg = <0xa0c000 0x1000>; + interrupts = <GIC_SPI 295 IRQ_TYPE_EDGE_RISING>; + clocks = <&mmcc MMSS_MMAGIC_AHB_CLK>, + <&mmcc CAMSS_TOP_AHB_CLK>, + <&mmcc CAMSS_CCI_AHB_CLK>, + <&mmcc CAMSS_CCI_CLK>, + <&mmcc CAMSS_AHB_CLK>; + clock-names = "mmss_mmagic_ahb", + "camss_top_ahb", + "cci_ahb", + "cci", + "camss_ahb"; + + i2c-bus@0 { + reg = <0>; + clock-frequency = <400000>; + #address-cells = <1>; + #size-cells = <0>; + }; + + i2c-bus@1 { + reg = <1>; + clock-frequency = <400000>; + #address-cells = <1>; + #size-cells = <0>; + }; + }; diff --git a/Documentation/devicetree/bindings/i2c/i2c.txt b/Documentation/devicetree/bindings/i2c/i2c.txt index 9a53df4243c6..438ae123107e 100644 --- a/Documentation/devicetree/bindings/i2c/i2c.txt +++ b/Documentation/devicetree/bindings/i2c/i2c.txt @@ -2,32 +2,26 @@ Generic device tree bindings for I2C busses =========================================== This document describes generic bindings which can be used to describe I2C -busses in a device tree. +busses and their child devices in a device tree. -Required properties -------------------- +Required properties (per bus) +----------------------------- - #address-cells - should be <1>. Read more about addresses below. - #size-cells - should be <0>. -- compatible - name of I2C bus controller following generic names - recommended practice. +- compatible - name of I2C bus controller For other required properties e.g. to describe register sets, clocks, etc. check the binding documentation of the specific driver. The cells properties above define that an address of children of an I2C bus -are described by a single value. This is usually a 7 bit address. However, -flags can be attached to the address. I2C_TEN_BIT_ADDRESS is used to mark a 10 -bit address. It is needed to avoid the ambiguity between e.g. a 7 bit address -of 0x50 and a 10 bit address of 0x050 which, in theory, can be on the same bus. -Another flag is I2C_OWN_SLAVE_ADDRESS to mark addresses on which we listen to -be devices ourselves. +are described by a single value. -Optional properties -------------------- +Optional properties (per bus) +----------------------------- These properties may not be supported by all drivers. However, if a driver -wants to support one of the below features, it should adapt the bindings below. +wants to support one of the below features, it should adapt these bindings. - clock-frequency frequency of bus clock in Hz. @@ -73,31 +67,54 @@ wants to support one of the below features, it should adapt the bindings below. i2c bus clock frequency (clock-frequency). Specified in Hz. -- interrupts - interrupts used by the device. - -- interrupt-names - "irq", "wakeup" and "smbus_alert" names are recognized by I2C core, - other names are left to individual drivers. - -- host-notify - device uses SMBus host notify protocol instead of interrupt line. - - multi-master states that there is another master active on this bus. The OS can use this information to adapt power management to keep the arbitration awake - all the time, for example. + all the time, for example. Can not be combined with 'single-master'. -- wakeup-source - device can be used as a wakeup source. +- single-master + states that there is no other master active on this bus. The OS can use + this information to detect a stalled bus more reliably, for example. + Can not be combined with 'multi-master'. + +Required properties (per child device) +-------------------------------------- + +- compatible + name of I2C slave device - reg - I2C slave addresses + One or many I2C slave addresses. These are usually a 7 bit addresses. + However, flags can be attached to an address. I2C_TEN_BIT_ADDRESS is + used to mark a 10 bit address. It is needed to avoid the ambiguity + between e.g. a 7 bit address of 0x50 and a 10 bit address of 0x050 + which, in theory, can be on the same bus. + Another flag is I2C_OWN_SLAVE_ADDRESS to mark addresses on which we + listen to be devices ourselves. + +Optional properties (per child device) +-------------------------------------- + +These properties may not be supported by all drivers. However, if a driver +wants to support one of the below features, it should adapt these bindings. + +- host-notify + device uses SMBus host notify protocol instead of interrupt line. + +- interrupts + interrupts used by the device. + +- interrupt-names + "irq", "wakeup" and "smbus_alert" names are recognized by I2C core, + other names are left to individual drivers. - reg-names Names of map programmable addresses. It can contain any map needing another address than default one. +- wakeup-source + device can be used as a wakeup source. + Binding may contain optional "interrupts" property, describing interrupts used by the device. I2C core will assign "irq" interrupt (or the very first interrupt if not using interrupt names) as primary interrupt for the slave. diff --git a/Documentation/devicetree/bindings/i2c/nuvoton,npcm7xx-i2c.yaml b/Documentation/devicetree/bindings/i2c/nuvoton,npcm7xx-i2c.yaml new file mode 100644 index 000000000000..e3ef2d36f372 --- /dev/null +++ b/Documentation/devicetree/bindings/i2c/nuvoton,npcm7xx-i2c.yaml @@ -0,0 +1,62 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/i2c/nuvoton,npcm7xx-i2c.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: nuvoton NPCM7XX I2C Controller Device Tree Bindings + +description: | + The NPCM750x includes sixteen I2C bus controllers. All Controllers support + both master and slave mode. Each controller can switch between master and slave + at run time (i.e. IPMB mode). Each controller has two 16 byte HW FIFO for TX and + RX. + +maintainers: + - Tali Perry <tali.perry1@gmail.com> + +properties: + compatible: + const: nuvoton,npcm7xx-i2c + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + clocks: + maxItems: 1 + description: Reference clock for the I2C bus + + clock-frequency: + description: Desired I2C bus clock frequency in Hz. If not specified, + the default 100 kHz frequency will be used. + possible values are 100000, 400000 and 1000000. + default: 100000 + enum: [100000, 400000, 1000000] + +required: + - compatible + - reg + - interrupts + - clocks + +allOf: + - $ref: /schemas/i2c/i2c-controller.yaml# + +unevaluatedProperties: false + +examples: + - | + #include <dt-bindings/clock/nuvoton,npcm7xx-clock.h> + #include <dt-bindings/interrupt-controller/arm-gic.h> + i2c0: i2c@80000 { + reg = <0x80000 0x1000>; + clocks = <&clk NPCM7XX_CLK_APB2>; + clock-frequency = <100000>; + interrupts = <GIC_SPI 64 IRQ_TYPE_LEVEL_HIGH>; + compatible = "nuvoton,npcm750-i2c"; + }; + +... diff --git a/Documentation/devicetree/bindings/i2c/snps,designware-i2c.yaml b/Documentation/devicetree/bindings/i2c/snps,designware-i2c.yaml new file mode 100644 index 000000000000..4f746bef2374 --- /dev/null +++ b/Documentation/devicetree/bindings/i2c/snps,designware-i2c.yaml @@ -0,0 +1,156 @@ +# SPDX-License-Identifier: GPL-2.0-only +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/i2c/snps,designware-i2c.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Synopsys DesignWare APB I2C Controller + +maintainers: + - Jarkko Nikula <jarkko.nikula@linux.intel.com> + +allOf: + - $ref: /schemas/i2c/i2c-controller.yaml# + - if: + properties: + compatible: + not: + contains: + const: mscc,ocelot-i2c + then: + properties: + reg: + maxItems: 1 + +properties: + compatible: + oneOf: + - description: Generic Synopsys DesignWare I2C controller + const: snps,designware-i2c + - description: Microsemi Ocelot SoCs I2C controller + items: + - const: mscc,ocelot-i2c + - const: snps,designware-i2c + - description: Baikal-T1 SoC System I2C controller + const: baikal,bt1-sys-i2c + + reg: + minItems: 1 + items: + - description: DW APB I2C controller memory mapped registers + - description: | + ICPU_CFG:TWI_DELAY registers to setup the SDA hold time. + This registers are specific to the Ocelot I2C-controller. + + interrupts: + maxItems: 1 + + clocks: + minItems: 1 + items: + - description: I2C controller reference clock source + - description: APB interface clock source + + clock-names: + minItems: 1 + items: + - const: ref + - const: pclk + + resets: + maxItems: 1 + + clock-frequency: + description: Desired I2C bus clock frequency in Hz + enum: [100000, 400000, 1000000, 3400000] + default: 400000 + + i2c-sda-hold-time-ns: + maxItems: 1 + description: | + The property should contain the SDA hold time in nanoseconds. This option + is only supported in hardware blocks version 1.11a or newer or on + Microsemi SoCs. + + i2c-scl-falling-time-ns: + maxItems: 1 + description: | + The property should contain the SCL falling time in nanoseconds. + This value is used to compute the tLOW period. + default: 300 + + i2c-sda-falling-time-ns: + maxItems: 1 + description: | + The property should contain the SDA falling time in nanoseconds. + This value is used to compute the tHIGH period. + default: 300 + + dmas: + items: + - description: TX DMA Channel + - description: RX DMA Channel + + dma-names: + items: + - const: tx + - const: rx + +unevaluatedProperties: false + +required: + - compatible + - reg + - "#address-cells" + - "#size-cells" + - interrupts + +examples: + - | + i2c@f0000 { + compatible = "snps,designware-i2c"; + reg = <0xf0000 0x1000>; + #address-cells = <1>; + #size-cells = <0>; + interrupts = <11>; + clock-frequency = <400000>; + }; + - | + i2c@1120000 { + compatible = "snps,designware-i2c"; + reg = <0x1120000 0x1000>; + #address-cells = <1>; + #size-cells = <0>; + interrupts = <12 1>; + clock-frequency = <400000>; + i2c-sda-hold-time-ns = <300>; + i2c-sda-falling-time-ns = <300>; + i2c-scl-falling-time-ns = <300>; + }; + - | + i2c@2000 { + compatible = "snps,designware-i2c"; + reg = <0x2000 0x100>; + #address-cells = <1>; + #size-cells = <0>; + clock-frequency = <400000>; + clocks = <&i2cclk>; + interrupts = <0>; + + eeprom@64 { + compatible = "atmel,24c02"; + reg = <0x64>; + }; + }; + - | + i2c@100400 { + compatible = "mscc,ocelot-i2c", "snps,designware-i2c"; + reg = <0x100400 0x100>, <0x198 0x8>; + pinctrl-0 = <&i2c_pins>; + pinctrl-names = "default"; + #address-cells = <1>; + #size-cells = <0>; + interrupts = <8>; + clocks = <&ahb_clk>; + }; +... diff --git a/Documentation/devicetree/bindings/i2c/st,stm32-i2c.yaml b/Documentation/devicetree/bindings/i2c/st,stm32-i2c.yaml index 7b3342354bbb..f2fcbb361180 100644 --- a/Documentation/devicetree/bindings/i2c/st,stm32-i2c.yaml +++ b/Documentation/devicetree/bindings/i2c/st,stm32-i2c.yaml @@ -81,11 +81,11 @@ properties: clock-frequency: description: Desired I2C bus clock frequency in Hz. If not specified, the default 100 kHz frequency will be used. - For STM32F7, STM32H7 and STM32MP1 SoCs, Standard-mode, - Fast-mode and Fast-mode Plus are supported, possible - values are 100000, 400000 and 1000000. + For STM32F7, STM32H7 and STM32MP1 SoCs, if timing parameters + match, the bus clock frequency can be from 1Hz to 1MHz. default: 100000 - enum: [100000, 400000, 1000000] + minimum: 1 + maximum: 1000000 required: - compatible diff --git a/Documentation/devicetree/bindings/iio/imu/adi,adis16475.yaml b/Documentation/devicetree/bindings/iio/imu/adi,adis16475.yaml index 98baecb4b98a..208faaffa58d 100644 --- a/Documentation/devicetree/bindings/iio/imu/adi,adis16475.yaml +++ b/Documentation/devicetree/bindings/iio/imu/adi,adis16475.yaml @@ -67,8 +67,7 @@ properties: 1 - direct_sync 2 - scaled_sync 3 - pulse_sync - allOf: - - $ref: /schemas/types.yaml#/definitions/uint32 + $ref: /schemas/types.yaml#/definitions/uint32 minimum: 0 maximum: 3 diff --git a/Documentation/devicetree/bindings/iio/light/amstaos,tsl2563.yaml b/Documentation/devicetree/bindings/iio/light/amstaos,tsl2563.yaml index efd2eba5f23c..e201a06d8fdc 100644 --- a/Documentation/devicetree/bindings/iio/light/amstaos,tsl2563.yaml +++ b/Documentation/devicetree/bindings/iio/light/amstaos,tsl2563.yaml @@ -25,9 +25,8 @@ properties: amstaos,cover-comp-gain: description: Multiplier for gain compensation - allOf: - - $ref: /schemas/types.yaml#/definitions/uint32 - - enum: [1, 16] + $ref: /schemas/types.yaml#/definitions/uint32 + enum: [1, 16] required: - compatible diff --git a/Documentation/devicetree/bindings/input/elants_i2c.txt b/Documentation/devicetree/bindings/input/elants_i2c.txt deleted file mode 100644 index 5edac8be0802..000000000000 --- a/Documentation/devicetree/bindings/input/elants_i2c.txt +++ /dev/null @@ -1,34 +0,0 @@ -Elantech I2C Touchscreen - -Required properties: -- compatible: must be "elan,ekth3500". -- reg: I2C address of the chip. -- interrupts: interrupt to which the chip is connected (see interrupt - binding[0]). - -Optional properties: -- wakeup-source: touchscreen can be used as a wakeup source. -- pinctrl-names: should be "default" (see pinctrl binding [1]). -- pinctrl-0: a phandle pointing to the pin settings for the device (see - pinctrl binding [1]). -- reset-gpios: reset gpio the chip is connected to. -- vcc33-supply: a phandle for the regulator supplying 3.3V power. -- vccio-supply: a phandle for the regulator supplying IO power. - -[0]: Documentation/devicetree/bindings/interrupt-controller/interrupts.txt -[1]: Documentation/devicetree/bindings/pinctrl/pinctrl-bindings.txt - -Example: - &i2c1 { - /* ... */ - - touchscreen@10 { - compatible = "elan,ekth3500"; - reg = <0x10>; - interrupt-parent = <&gpio4>; - interrupts = <0x0 IRQ_TYPE_EDGE_FALLING>; - wakeup-source; - }; - - /* ... */ - }; diff --git a/Documentation/devicetree/bindings/input/iqs269a.yaml b/Documentation/devicetree/bindings/input/iqs269a.yaml new file mode 100644 index 000000000000..9c154e5e1a91 --- /dev/null +++ b/Documentation/devicetree/bindings/input/iqs269a.yaml @@ -0,0 +1,555 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/input/iqs269a.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Azoteq IQS269A Capacitive Touch Controller + +maintainers: + - Jeff LaBundy <jeff@labundy.com> + +description: | + The Azoteq IQS269A is an 8-channel capacitive touch controller that features + additional Hall-effect and inductive sensing capabilities. + + Link to datasheet: https://www.azoteq.com/ + +properties: + compatible: + const: azoteq,iqs269a + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + "#address-cells": + const: 1 + + "#size-cells": + const: 0 + + azoteq,hall-enable: + type: boolean + description: + Enables Hall-effect sensing on channels 6 and 7. In this case, keycodes + assigned to channel 6 are ignored and keycodes assigned to channel 7 are + interpreted as switch codes. Refer to the datasheet for requirements im- + posed on channels 6 and 7 by Hall-effect sensing. + + azoteq,suspend-mode: + $ref: /schemas/types.yaml#/definitions/uint32 + enum: [0, 1, 2, 3] + default: 0 + description: | + Specifies the power mode during suspend as follows: + 0: Automatic (same as normal runtime, i.e. suspend/resume disabled) + 1: Low power (all sensing at a reduced reporting rate) + 2: Ultra-low power (channel 0 proximity sensing) + 3: Halt (no sensing) + + azoteq,clk-div: + type: boolean + description: Divides the device's core clock by a factor of 4. + + azoteq,ulp-update: + $ref: /schemas/types.yaml#/definitions/uint32 + minimum: 0 + maximum: 7 + default: 3 + description: Specifies the ultra-low-power mode update rate. + + azoteq,reseed-offset: + type: boolean + description: + Applies an 8-count offset to all long-term averages upon either ATI or + reseed events. + + azoteq,filt-str-lp-lta: + $ref: /schemas/types.yaml#/definitions/uint32 + enum: [0, 1, 2, 3] + default: 0 + description: + Specifies the long-term average filter strength during low-power mode. + + azoteq,filt-str-lp-cnt: + $ref: /schemas/types.yaml#/definitions/uint32 + enum: [0, 1, 2, 3] + default: 0 + description: + Specifies the raw count filter strength during low-power mode. + + azoteq,filt-str-np-lta: + $ref: /schemas/types.yaml#/definitions/uint32 + enum: [0, 1, 2, 3] + default: 0 + description: + Specifies the long-term average filter strength during normal-power mode. + + azoteq,filt-str-np-cnt: + $ref: /schemas/types.yaml#/definitions/uint32 + enum: [0, 1, 2, 3] + default: 0 + description: + Specifies the raw count filter strength during normal-power mode. + + azoteq,rate-np-ms: + minimum: 0 + maximum: 255 + default: 16 + description: Specifies the report rate (in ms) during normal-power mode. + + azoteq,rate-lp-ms: + minimum: 0 + maximum: 255 + default: 160 + description: Specifies the report rate (in ms) during low-power mode. + + azoteq,rate-ulp-ms: + multipleOf: 16 + minimum: 0 + maximum: 4080 + default: 160 + description: Specifies the report rate (in ms) during ultra-low-power mode. + + azoteq,timeout-pwr-ms: + multipleOf: 512 + minimum: 0 + maximum: 130560 + default: 2560 + description: + Specifies the length of time (in ms) to wait for an event during normal- + power mode before transitioning to low-power mode. + + azoteq,timeout-lta-ms: + multipleOf: 512 + minimum: 0 + maximum: 130560 + default: 32768 + description: + Specifies the length of time (in ms) to wait before resetting the long- + term average of all channels. Specify the maximum timeout to disable it + altogether. + + azoteq,ati-band-disable: + type: boolean + description: Disables the ATI band check. + + azoteq,ati-lp-only: + type: boolean + description: Limits automatic ATI to low-power mode. + + azoteq,ati-band-tighten: + type: boolean + description: Tightens the ATI band from 1/8 to 1/16 of the desired target. + + azoteq,filt-disable: + type: boolean + description: Disables all raw count filtering. + + azoteq,gpio3-select: + $ref: /schemas/types.yaml#/definitions/uint32 + minimum: 0 + maximum: 7 + default: 0 + description: + Selects the channel for which the GPIO3 pin represents touch state. + + azoteq,dual-direction: + type: boolean + description: + Specifies that long-term averages are to freeze in the presence of either + increasing or decreasing counts, thereby permitting events to be reported + in either direction. + + azoteq,tx-freq: + $ref: /schemas/types.yaml#/definitions/uint32 + enum: [0, 1, 2, 3] + default: 0 + description: | + Specifies the inductive sensing excitation frequency as follows (paren- + thesized numbers represent the frequency if 'azoteq,clk-div' is present): + 0: 16 MHz (4 MHz) + 1: 8 MHz (2 MHz) + 2: 4 MHz (1 MHz) + 3: 2 MHz (500 kHz) + + azoteq,global-cap-increase: + type: boolean + description: Increases the global capacitance adder from 0.5 pF to 1.5 pF. + + azoteq,reseed-select: + $ref: /schemas/types.yaml#/definitions/uint32 + enum: [0, 1, 2, 3] + default: 0 + description: | + Specifies the event(s) that prompt the device to reseed (i.e. reset the + long-term average) of an associated channel as follows: + 0: None + 1: Proximity + 2: Proximity or touch + 3: Proximity, touch or deep touch + + azoteq,tracking-enable: + type: boolean + description: + Enables all associated channels to track their respective reference + channels. + + azoteq,filt-str-slider: + $ref: /schemas/types.yaml#/definitions/uint32 + enum: [0, 1, 2, 3] + default: 1 + description: Specifies the slider coordinate filter strength. + +patternProperties: + "^channel@[0-7]$": + type: object + description: + Represents a single sensing channel. A channel is active if defined and + inactive otherwise. + + properties: + reg: + minimum: 0 + maximum: 7 + description: Index of the channel. + + azoteq,reseed-disable: + type: boolean + description: + Prevents the channel from being reseeded if the long-term average + timeout (defined in 'azoteq,timeout-lta') expires. + + azoteq,blocking-enable: + type: boolean + description: Specifies that the channel is a blocking channel. + + azoteq,slider0-select: + type: boolean + description: Specifies that the channel participates in slider 0. + + azoteq,slider1-select: + type: boolean + description: Specifies that the channel participates in slider 1. + + azoteq,rx-enable: + $ref: /schemas/types.yaml#/definitions/uint32-array + minItems: 1 + maxItems: 8 + items: + minimum: 0 + maximum: 7 + description: + Specifies the CRX pin(s) associated with the channel. By default, only + the CRX pin corresponding to the channel's index is enabled (e.g. CRX0 + for channel 0). + + azoteq,tx-enable: + $ref: /schemas/types.yaml#/definitions/uint32-array + minItems: 1 + maxItems: 8 + items: + minimum: 0 + maximum: 7 + default: [0, 1, 2, 3, 4, 5, 6, 7] + description: Specifies the TX pin(s) associated with the channel. + + azoteq,meas-cap-decrease: + type: boolean + description: + Decreases the internal measurement capacitance from 60 pF to 15 pF. + + azoteq,rx-float-inactive: + type: boolean + description: Floats any inactive CRX pins instead of grounding them. + + azoteq,local-cap-size: + $ref: /schemas/types.yaml#/definitions/uint32 + enum: [0, 1, 2] + default: 0 + description: | + Specifies the capacitance to be added to the channel as follows: + 0: None + 1: Global adder (based on 'azoteq,global-cap-increase') + 2: Global adder + 0.5 pF + + azoteq,invert-enable: + type: boolean + description: + Inverts the polarity of the states reported for proximity, touch and + deep-touch events relative to their respective thresholds. + + azoteq,proj-bias: + $ref: /schemas/types.yaml#/definitions/uint32 + enum: [0, 1, 2, 3] + default: 2 + description: | + Specifies the bias current applied during projected-capacitance + sensing as follows: + 0: 2.5 uA + 1: 5 uA + 2: 10 uA + 3: 20 uA + + azoteq,sense-mode: + $ref: /schemas/types.yaml#/definitions/uint32 + enum: [0, 1, 9, 14, 15] + default: 0 + description: | + Specifies the channel's sensing mode as follows: + 0: Self capacitance + 1: Projected capacitance + 9: Self or mutual inductance + 14: Hall effect + 15: Temperature + + azoteq,sense-freq: + $ref: /schemas/types.yaml#/definitions/uint32 + enum: [0, 1, 2, 3] + default: 1 + description: | + Specifies the channel's sensing frequency as follows (parenthesized + numbers represent the frequency if 'azoteq,clk-div' is present): + 0: 4 MHz (1 MHz) + 1: 2 MHz (500 kHz) + 2: 1 MHz (250 kHz) + 3: 500 kHz (125 kHz) + + azoteq,static-enable: + type: boolean + description: Enables the static front-end for the channel. + + azoteq,ati-mode: + $ref: /schemas/types.yaml#/definitions/uint32 + enum: [0, 1, 2, 3] + default: 3 + description: | + Specifies the channel's ATI mode as follows: + 0: Disabled + 1: Semi-partial + 2: Partial + 3: Full + + azoteq,ati-base: + $ref: /schemas/types.yaml#/definitions/uint32 + enum: [75, 100, 150, 200] + default: 100 + description: Specifies the channel's ATI base. + + azoteq,ati-target: + $ref: /schemas/types.yaml#/definitions/uint32 + multipleOf: 32 + minimum: 0 + maximum: 2016 + default: 512 + description: Specifies the channel's ATI target. + + azoteq,assoc-select: + $ref: /schemas/types.yaml#/definitions/uint32-array + minItems: 1 + maxItems: 8 + items: + minimum: 0 + maximum: 7 + description: + Specifies the associated channels for which the channel serves as a + reference channel. By default, no channels are selected. + + azoteq,assoc-weight: + $ref: /schemas/types.yaml#/definitions/uint32 + minimum: 0 + maximum: 255 + default: 0 + description: + Specifies the channel's impact weight if it acts as an associated + channel (0 = 0% impact, 255 = 200% impact). + + patternProperties: + "^event-prox(-alt)?$": + type: object + description: + Represents a proximity event reported by the channel in response to + a decrease in counts. Node names suffixed with '-alt' instead corre- + spond to an increase in counts. + + By default, the long-term average tracks an increase in counts such + that only events corresponding to a decrease in counts are reported + (refer to the datasheet for more information). + + Specify 'azoteq,dual-direction' to freeze the long-term average when + the counts increase or decrease such that events of either direction + can be reported. Alternatively, specify 'azoteq,invert-enable' to in- + vert the polarity of the states reported by the channel. + + Complementary events (e.g. event-touch and event-touch-alt) can both + be present and specify different key or switch codes, but not differ- + ent thresholds or hysteresis (if applicable). + + properties: + azoteq,thresh: + $ref: /schemas/types.yaml#/definitions/uint32 + minimum: 0 + maximum: 255 + default: 10 + description: Specifies the threshold for the event. + + linux,code: + $ref: /schemas/types.yaml#/definitions/uint32 + description: Numeric key or switch code associated with the event. + + additionalProperties: false + + "^event-touch(-alt)?$": + type: object + description: Represents a touch event reported by the channel. + + properties: + azoteq,thresh: + $ref: /schemas/types.yaml#/definitions/uint32 + minimum: 0 + maximum: 255 + default: 8 + description: Specifies the threshold for the event. + + azoteq,hyst: + $ref: /schemas/types.yaml#/definitions/uint32 + minimum: 0 + maximum: 15 + default: 4 + description: Specifies the hysteresis for the event. + + linux,code: + $ref: /schemas/types.yaml#/definitions/uint32 + description: Numeric key or switch code associated with the event. + + additionalProperties: false + + "^event-deep(-alt)?$": + type: object + description: Represents a deep-touch event reported by the channel. + + properties: + azoteq,thresh: + $ref: /schemas/types.yaml#/definitions/uint32 + minimum: 0 + maximum: 255 + default: 26 + description: Specifies the threshold for the event. + + azoteq,hyst: + $ref: /schemas/types.yaml#/definitions/uint32 + minimum: 0 + maximum: 15 + default: 0 + description: Specifies the hysteresis for the event. + + linux,code: + $ref: /schemas/types.yaml#/definitions/uint32 + description: Numeric key or switch code associated with the event. + + additionalProperties: false + + required: + - reg + + additionalProperties: false + +required: + - compatible + - reg + - interrupts + - "#address-cells" + - "#size-cells" + +additionalProperties: false + +examples: + - | + #include <dt-bindings/input/input.h> + #include <dt-bindings/interrupt-controller/irq.h> + + i2c { + #address-cells = <1>; + #size-cells = <0>; + + iqs269a@44 { + #address-cells = <1>; + #size-cells = <0>; + + compatible = "azoteq,iqs269a"; + reg = <0x44>; + interrupt-parent = <&gpio>; + interrupts = <17 IRQ_TYPE_LEVEL_LOW>; + + azoteq,hall-enable; + azoteq,suspend-mode = <2>; + + channel@0 { + reg = <0x0>; + + event-prox { + linux,code = <KEY_POWER>; + }; + }; + + channel@1 { + reg = <0x1>; + azoteq,slider0-select; + }; + + channel@2 { + reg = <0x2>; + azoteq,slider0-select; + }; + + channel@3 { + reg = <0x3>; + azoteq,slider0-select; + }; + + channel@4 { + reg = <0x4>; + azoteq,slider0-select; + }; + + channel@5 { + reg = <0x5>; + azoteq,slider0-select; + }; + + channel@6 { + reg = <0x6>; + azoteq,invert-enable; + azoteq,static-enable; + azoteq,reseed-disable; + azoteq,rx-enable = <0>; + azoteq,sense-freq = <0x0>; + azoteq,sense-mode = <0xE>; + azoteq,ati-mode = <0x0>; + azoteq,ati-base = <200>; + azoteq,ati-target = <320>; + }; + + channel@7 { + reg = <0x7>; + azoteq,invert-enable; + azoteq,static-enable; + azoteq,reseed-disable; + azoteq,rx-enable = <0>, <6>; + azoteq,sense-freq = <0x0>; + azoteq,sense-mode = <0xE>; + azoteq,ati-mode = <0x3>; + azoteq,ati-base = <200>; + azoteq,ati-target = <320>; + + event-touch { + linux,code = <SW_LID>; + }; + }; + }; + }; + +... diff --git a/Documentation/devicetree/bindings/input/msm-vibrator.txt b/Documentation/devicetree/bindings/input/msm-vibrator.txt deleted file mode 100644 index 8dcf014ef2e5..000000000000 --- a/Documentation/devicetree/bindings/input/msm-vibrator.txt +++ /dev/null @@ -1,36 +0,0 @@ -* Device tree bindings for the Qualcomm MSM vibrator - -Required properties: - - - compatible: Should be one of - "qcom,msm8226-vibrator" - "qcom,msm8974-vibrator" - - reg: the base address and length of the IO memory for the registers. - - pinctrl-names: set to default. - - pinctrl-0: phandles pointing to pin configuration nodes. See - Documentation/devicetree/bindings/pinctrl/pinctrl-bindings.txt - - clock-names: set to pwm - - clocks: phandle of the clock. See - Documentation/devicetree/bindings/clock/clock-bindings.txt - - enable-gpios: GPIO that enables the vibrator. - -Optional properties: - - - vcc-supply: phandle to the regulator that provides power to the sensor. - -Example from a LG Nexus 5 (hammerhead) phone: - -vibrator@fd8c3450 { - reg = <0xfd8c3450 0x400>; - compatible = "qcom,msm8974-vibrator"; - - vcc-supply = <&pm8941_l19>; - - clocks = <&mmcc CAMSS_GP1_CLK>; - clock-names = "pwm"; - - enable-gpios = <&msmgpio 60 GPIO_ACTIVE_HIGH>; - - pinctrl-names = "default"; - pinctrl-0 = <&vibrator_pin>; -}; diff --git a/Documentation/devicetree/bindings/input/touchscreen/cypress,cy8ctma140.yaml b/Documentation/devicetree/bindings/input/touchscreen/cypress,cy8ctma140.yaml new file mode 100644 index 000000000000..8c73e5264312 --- /dev/null +++ b/Documentation/devicetree/bindings/input/touchscreen/cypress,cy8ctma140.yaml @@ -0,0 +1,72 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/input/touchscreen/cypress,cy8ctma140.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Cypress CY8CTMA140 series touchscreen controller bindings + +maintainers: + - Linus Walleij <linus.walleij@linaro.org> + +allOf: + - $ref: touchscreen.yaml# + +properties: + compatible: + const: cypress,cy8ctma140 + + reg: + const: 0x20 + + clock-frequency: + description: I2C client clock frequency, defined for host + minimum: 100000 + maximum: 400000 + + interrupts: + maxItems: 1 + + vcpin-supply: + description: Analog power supply regulator on VCPIN pin + + vdd-supply: + description: Digital power supply regulator on VDD pin + + touchscreen-inverted-x: true + touchscreen-inverted-y: true + touchscreen-size-x: true + touchscreen-size-y: true + touchscreen-swapped-x-y: true + touchscreen-max-pressure: true + +additionalProperties: false + +required: + - compatible + - reg + - interrupts + - touchscreen-size-x + - touchscreen-size-y + - touchscreen-max-pressure + +examples: +- | + #include <dt-bindings/interrupt-controller/irq.h> + i2c { + #address-cells = <1>; + #size-cells = <0>; + touchscreen@20 { + compatible = "cypress,cy8ctma140"; + reg = <0x20>; + touchscreen-size-x = <480>; + touchscreen-size-y = <800>; + touchscreen-max-pressure = <255>; + interrupt-parent = <&gpio6>; + interrupts = <26 IRQ_TYPE_EDGE_FALLING>; + vdd-supply = <&ab8500_ldo_aux2_reg>; + vcpin-supply = <&ab8500_ldo_aux2_reg>; + }; + }; + +... diff --git a/Documentation/devicetree/bindings/input/touchscreen/elan,elants_i2c.yaml b/Documentation/devicetree/bindings/input/touchscreen/elan,elants_i2c.yaml new file mode 100644 index 000000000000..a792d6377b1d --- /dev/null +++ b/Documentation/devicetree/bindings/input/touchscreen/elan,elants_i2c.yaml @@ -0,0 +1,69 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: "http://devicetree.org/schemas/input/touchscreen/elan,elants_i2c.yaml#" +$schema: "http://devicetree.org/meta-schemas/core.yaml#" + +title: Elantech I2C Touchscreen + +maintainers: + - David Heidelberg <david@ixit.cz> + +allOf: + - $ref: touchscreen.yaml# + +properties: + compatible: + enum: + - elan,ektf3624 + - elan,ekth3500 + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + wakeup-source: + type: boolean + description: touchscreen can be used as a wakeup source. + + reset-gpios: + description: reset gpio the chip is connected to. + + vcc33-supply: + description: a phandle for the regulator supplying 3.3V power. + + vccio-supply: + description: a phandle for the regulator supplying IO power. + + touchscreen-inverted-x: true + touchscreen-inverted-y: true + touchscreen-size-x: true + touchscreen-size-y: true + touchscreen-swapped-x-y: true + +additionalProperties: false + +required: + - compatible + - reg + - interrupts + +examples: + - | + #include <dt-bindings/interrupt-controller/irq.h> + + i2c { + #address-cells = <1>; + #size-cells = <0>; + + touchscreen@10 { + compatible = "elan,ekth3500"; + reg = <0x10>; + + interrupt-parent = <&gpio4>; + interrupts = <0x0 IRQ_TYPE_EDGE_FALLING>; + wakeup-source; + }; + }; diff --git a/Documentation/devicetree/bindings/input/touchscreen/mms114.txt b/Documentation/devicetree/bindings/input/touchscreen/mms114.txt index 2cd954051d29..707234cfd7e6 100644 --- a/Documentation/devicetree/bindings/input/touchscreen/mms114.txt +++ b/Documentation/devicetree/bindings/input/touchscreen/mms114.txt @@ -1,9 +1,10 @@ -* MELFAS MMS114/MMS152 touchscreen controller +* MELFAS MMS114/MMS152/MMS345L touchscreen controller Required properties: - compatible: should be one of: - "melfas,mms114" - "melfas,mms152" + - "melfas,mms345l" - reg: I2C address of the chip - interrupts: interrupt to which the chip is connected - touchscreen-size-x: See [1] diff --git a/Documentation/devicetree/bindings/interrupt-controller/loongson,pch-msi.yaml b/Documentation/devicetree/bindings/interrupt-controller/loongson,pch-msi.yaml index 1a5ebbdd219a..1b256d9dd92a 100644 --- a/Documentation/devicetree/bindings/interrupt-controller/loongson,pch-msi.yaml +++ b/Documentation/devicetree/bindings/interrupt-controller/loongson,pch-msi.yaml @@ -25,19 +25,17 @@ properties: description: u32 value of the base of parent HyperTransport vector allocated to PCH MSI. - allOf: - - $ref: "/schemas/types.yaml#/definitions/uint32" - - minimum: 0 - maximum: 255 + $ref: "/schemas/types.yaml#/definitions/uint32" + minimum: 0 + maximum: 255 loongson,msi-num-vecs: description: u32 value of the number of parent HyperTransport vectors allocated to PCH MSI. - allOf: - - $ref: "/schemas/types.yaml#/definitions/uint32" - - minimum: 1 - maximum: 256 + $ref: "/schemas/types.yaml#/definitions/uint32" + minimum: 1 + maximum: 256 msi-controller: true diff --git a/Documentation/devicetree/bindings/interrupt-controller/loongson,pch-pic.yaml b/Documentation/devicetree/bindings/interrupt-controller/loongson,pch-pic.yaml index 274adea13f33..a6dcbb2971a9 100644 --- a/Documentation/devicetree/bindings/interrupt-controller/loongson,pch-pic.yaml +++ b/Documentation/devicetree/bindings/interrupt-controller/loongson,pch-pic.yaml @@ -25,10 +25,9 @@ properties: description: u32 value of the base of parent HyperTransport vector allocated to PCH PIC. - allOf: - - $ref: "/schemas/types.yaml#/definitions/uint32" - - minimum: 0 - maximum: 192 + $ref: "/schemas/types.yaml#/definitions/uint32" + minimum: 0 + maximum: 192 interrupt-controller: true diff --git a/Documentation/devicetree/bindings/iommu/allwinner,sun50i-h6-iommu.yaml b/Documentation/devicetree/bindings/iommu/allwinner,sun50i-h6-iommu.yaml new file mode 100644 index 000000000000..5e125cf2a88b --- /dev/null +++ b/Documentation/devicetree/bindings/iommu/allwinner,sun50i-h6-iommu.yaml @@ -0,0 +1,61 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/iommu/allwinner,sun50i-h6-iommu.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Allwinner H6 IOMMU Device Tree Bindings + +maintainers: + - Chen-Yu Tsai <wens@csie.org> + - Maxime Ripard <mripard@kernel.org> + +properties: + "#iommu-cells": + const: 1 + description: + The content of the cell is the master ID. + + compatible: + const: allwinner,sun50i-h6-iommu + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + clocks: + maxItems: 1 + + resets: + maxItems: 1 + +required: + - "#iommu-cells" + - compatible + - reg + - interrupts + - clocks + - resets + +additionalProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/arm-gic.h> + #include <dt-bindings/interrupt-controller/irq.h> + + #include <dt-bindings/clock/sun50i-h6-ccu.h> + #include <dt-bindings/reset/sun50i-h6-ccu.h> + + iommu: iommu@30f0000 { + compatible = "allwinner,sun50i-h6-iommu"; + reg = <0x030f0000 0x10000>; + interrupts = <GIC_SPI 57 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&ccu CLK_BUS_IOMMU>; + resets = <&ccu RST_BUS_IOMMU>; + #iommu-cells = <1>; + }; + +... diff --git a/Documentation/devicetree/bindings/iommu/arm,smmu.yaml b/Documentation/devicetree/bindings/iommu/arm,smmu.yaml index 218f7ecb4703..d7ceb4c34423 100644 --- a/Documentation/devicetree/bindings/iommu/arm,smmu.yaml +++ b/Documentation/devicetree/bindings/iommu/arm,smmu.yaml @@ -42,7 +42,9 @@ properties: - const: arm,mmu-500 - const: arm,smmu-v2 - items: - - const: arm,mmu-401 + - enum: + - arm,mmu-400 + - arm,mmu-401 - const: arm,smmu-v1 - enum: - arm,smmu-v1 diff --git a/Documentation/devicetree/bindings/ipmi/ipmi-smic.yaml b/Documentation/devicetree/bindings/ipmi/ipmi-smic.yaml index f0bb157e9417..58fa76ee6176 100644 --- a/Documentation/devicetree/bindings/ipmi/ipmi-smic.yaml +++ b/Documentation/devicetree/bindings/ipmi/ipmi-smic.yaml @@ -31,9 +31,8 @@ properties: reg-size: description: The access width of the register in bytes. Defaults to 1. - allOf: - - $ref: /schemas/types.yaml#/definitions/uint32 - - enum: [1, 2, 4, 8] + $ref: /schemas/types.yaml#/definitions/uint32 + enum: [1, 2, 4, 8] reg-spacing: $ref: /schemas/types.yaml#/definitions/uint32 @@ -43,9 +42,8 @@ properties: description: | The amount of bits to shift the register content to the right to get the data into bit zero. - allOf: - - $ref: /schemas/types.yaml#/definitions/uint32 - - maximum: 56 + $ref: /schemas/types.yaml#/definitions/uint32 + maximum: 56 required: - compatible diff --git a/Documentation/devicetree/bindings/leds/backlight/qcom-wled.yaml b/Documentation/devicetree/bindings/leds/backlight/qcom-wled.yaml index 01c7d93dc658..32e0896c6bc1 100644 --- a/Documentation/devicetree/bindings/leds/backlight/qcom-wled.yaml +++ b/Documentation/devicetree/bindings/leds/backlight/qcom-wled.yaml @@ -57,8 +57,7 @@ properties: description: | mA; per-string current limit. This property is supported only for WLED3. - allOf: - - $ref: /schemas/types.yaml#/definitions/uint32 + $ref: /schemas/types.yaml#/definitions/uint32 default: 20 minimum: 0 maximum: 25 @@ -74,38 +73,33 @@ properties: qcom,current-boost-limit: description: | mA; boost current limit. - allOf: - - $ref: /schemas/types.yaml#/definitions/uint32 + $ref: /schemas/types.yaml#/definitions/uint32 qcom,switching-freq: description: | kHz; switching frequency. - allOf: - - $ref: /schemas/types.yaml#/definitions/uint32 - - enum: [ 600, 640, 685, 738, 800, 872, 960, 1066, 1200, 1371, 1600, 1920, 2400, 3200, 4800, 9600 ] + $ref: /schemas/types.yaml#/definitions/uint32 + enum: [ 600, 640, 685, 738, 800, 872, 960, 1066, 1200, 1371, 1600, 1920, 2400, 3200, 4800, 9600 ] qcom,ovp: description: | V; Over-voltage protection limit. This property is supported only for WLED3. - allOf: - - $ref: /schemas/types.yaml#/definitions/uint32 - - enum: [ 27, 29, 32, 35 ] - - default: 29 + $ref: /schemas/types.yaml#/definitions/uint32 + enum: [ 27, 29, 32, 35 ] + default: 29 qcom,ovp-millivolt: description: | Over-voltage protection limit. This property is for WLED4 only. - allOf: - - $ref: /schemas/types.yaml#/definitions/uint32 - - enum: [ 18100, 19600, 29600, 31100 ] - - default: 29600 + $ref: /schemas/types.yaml#/definitions/uint32 + enum: [ 18100, 19600, 29600, 31100 ] + default: 29600 qcom,num-strings: description: | number of led strings attached. - allOf: - - $ref: /schemas/types.yaml#/definitions/uint32 + $ref: /schemas/types.yaml#/definitions/uint32 qcom,enabled-strings: description: | @@ -113,8 +107,7 @@ properties: string of leds are operated individually. Specify the list of strings used by the device. Any combination of led strings can be used. - allOf: - - $ref: /schemas/types.yaml#/definitions/uint32-array + $ref: /schemas/types.yaml#/definitions/uint32-array minItems: 1 maxItems: 4 @@ -150,10 +143,9 @@ properties: 0 - Modulator A 1 - Modulator B This property is applicable only to WLED5 peripheral. - allOf: - - $ref: /schemas/types.yaml#/definitions/uint32 - - enum: [ 0, 1 ] - - default: 0 + $ref: /schemas/types.yaml#/definitions/uint32 + enum: [ 0, 1 ] + default: 0 qcom,cabc-sel: description: | @@ -164,9 +156,8 @@ properties: 2 - CABC 2 3 - External signal (e.g. LPG) is used for dimming This property is applicable only to WLED5 peripheral. - allOf: - - $ref: /schemas/types.yaml#/definitions/uint32 - - enum: [ 0, 1, 2, 3 ] + $ref: /schemas/types.yaml#/definitions/uint32 + enum: [ 0, 1, 2, 3 ] allOf: - if: diff --git a/Documentation/devicetree/bindings/leds/leds-aw2013.yaml b/Documentation/devicetree/bindings/leds/leds-aw2013.yaml index f118721df1e8..e24b0d15ef01 100644 --- a/Documentation/devicetree/bindings/leds/leds-aw2013.yaml +++ b/Documentation/devicetree/bindings/leds/leds-aw2013.yaml @@ -32,8 +32,7 @@ properties: patternProperties: "^led@[0-2]$": type: object - allOf: - - $ref: common.yaml# + $ref: common.yaml# properties: reg: diff --git a/Documentation/devicetree/bindings/leds/leds-sgm3140.yaml b/Documentation/devicetree/bindings/leds/leds-sgm3140.yaml index ecf7ac9ab067..f68259619488 100644 --- a/Documentation/devicetree/bindings/leds/leds-sgm3140.yaml +++ b/Documentation/devicetree/bindings/leds/leds-sgm3140.yaml @@ -33,8 +33,7 @@ properties: led: type: object - allOf: - - $ref: common.yaml# + $ref: common.yaml# required: - compatible diff --git a/Documentation/devicetree/bindings/mailbox/qcom,apcs-kpss-global.txt b/Documentation/devicetree/bindings/mailbox/qcom,apcs-kpss-global.txt deleted file mode 100644 index beec612dbe6a..000000000000 --- a/Documentation/devicetree/bindings/mailbox/qcom,apcs-kpss-global.txt +++ /dev/null @@ -1,88 +0,0 @@ -Binding for the Qualcomm APCS global block -========================================== - -This binding describes the APCS "global" block found in various Qualcomm -platforms. - -- compatible: - Usage: required - Value type: <string> - Definition: must be one of: - "qcom,msm8916-apcs-kpss-global", - "qcom,msm8996-apcs-hmss-global" - "qcom,msm8998-apcs-hmss-global" - "qcom,qcs404-apcs-apps-global" - "qcom,sc7180-apss-shared" - "qcom,sdm845-apss-shared" - "qcom,sm8150-apss-shared" - "qcom,ipq8074-apcs-apps-global" - -- reg: - Usage: required - Value type: <prop-encoded-array> - Definition: must specify the base address and size of the global block - -- clocks: - Usage: required if #clock-names property is present - Value type: <phandle array> - Definition: phandles to the two parent clocks of the clock driver. - -- #mbox-cells: - Usage: required - Value type: <u32> - Definition: as described in mailbox.txt, must be 1 - -- #clock-cells: - Usage: optional - Value type: <u32> - Definition: as described in clock.txt, must be 0 - -- clock-names: - Usage: required if the platform data based clock driver needs to - retrieve the parent clock names from device tree. - This will requires two mandatory clocks to be defined. - Value type: <string-array> - Definition: must be "pll" and "aux" - -= EXAMPLE -The following example describes the APCS HMSS found in MSM8996 and part of the -GLINK RPM referencing the "rpm_hlos" doorbell therein. - - apcs_glb: mailbox@9820000 { - compatible = "qcom,msm8996-apcs-hmss-global"; - reg = <0x9820000 0x1000>; - - #mbox-cells = <1>; - }; - - rpm-glink { - compatible = "qcom,glink-rpm"; - - interrupts = <GIC_SPI 168 IRQ_TYPE_EDGE_RISING>; - - qcom,rpm-msg-ram = <&rpm_msg_ram>; - - mboxes = <&apcs_glb 0>; - mbox-names = "rpm_hlos"; - }; - -Below is another example of the APCS binding on MSM8916 platforms: - - apcs: mailbox@b011000 { - compatible = "qcom,msm8916-apcs-kpss-global"; - reg = <0xb011000 0x1000>; - #mbox-cells = <1>; - clocks = <&a53pll>; - #clock-cells = <0>; - }; - -Below is another example of the APCS binding on QCS404 platforms: - - apcs_glb: mailbox@b011000 { - compatible = "qcom,qcs404-apcs-apps-global", "syscon"; - reg = <0x0b011000 0x1000>; - #mbox-cells = <1>; - clocks = <&apcs_hfpll>, <&gcc GCC_GPLL0_AO_OUT_MAIN>; - clock-names = "pll", "aux"; - #clock-cells = <0>; - }; diff --git a/Documentation/devicetree/bindings/mailbox/qcom,apcs-kpss-global.yaml b/Documentation/devicetree/bindings/mailbox/qcom,apcs-kpss-global.yaml new file mode 100644 index 000000000000..12eff942708d --- /dev/null +++ b/Documentation/devicetree/bindings/mailbox/qcom,apcs-kpss-global.yaml @@ -0,0 +1,86 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: "http://devicetree.org/schemas/mailbox/qcom,apcs-kpss-global.yaml#" +$schema: "http://devicetree.org/meta-schemas/core.yaml#" + +title: Qualcomm APCS global block bindings + +description: + This binding describes the APCS "global" block found in various Qualcomm + platforms. + +maintainers: + - Sivaprakash Murugesan <sivaprak@codeaurora.org> + +properties: + compatible: + enum: + - qcom,ipq8074-apcs-apps-global + - qcom,msm8916-apcs-kpss-global + - qcom,msm8996-apcs-hmss-global + - qcom,msm8998-apcs-hmss-global + - qcom,qcs404-apcs-apps-global + - qcom,sc7180-apss-shared + - qcom,sdm845-apss-shared + - qcom,sm8150-apss-shared + + reg: + maxItems: 1 + + clocks: + description: phandles to the parent clocks of the clock driver + items: + - description: primary pll parent of the clock driver + - description: auxiliary parent + + '#mbox-cells': + const: 1 + + '#clock-cells': + const: 0 + + clock-names: + items: + - const: pll + - const: aux + +required: + - compatible + - reg + - '#mbox-cells' + +additionalProperties: false + +examples: + + # Example apcs with msm8996 + - | + #include <dt-bindings/interrupt-controller/arm-gic.h> + apcs_glb: mailbox@9820000 { + compatible = "qcom,msm8996-apcs-hmss-global"; + reg = <0x9820000 0x1000>; + + #mbox-cells = <1>; + }; + + rpm-glink { + compatible = "qcom,glink-rpm"; + interrupts = <GIC_SPI 168 IRQ_TYPE_EDGE_RISING>; + qcom,rpm-msg-ram = <&rpm_msg_ram>; + mboxes = <&apcs_glb 0>; + mbox-names = "rpm_hlos"; + }; + + # Example apcs with qcs404 + - | + #define GCC_APSS_AHB_CLK_SRC 1 + #define GCC_GPLL0_AO_OUT_MAIN 123 + apcs: mailbox@b011000 { + compatible = "qcom,qcs404-apcs-apps-global"; + reg = <0x0b011000 0x1000>; + #mbox-cells = <1>; + clocks = <&apcs_hfpll>, <&gcc GCC_GPLL0_AO_OUT_MAIN>; + clock-names = "pll", "aux"; + #clock-cells = <0>; + }; diff --git a/Documentation/devicetree/bindings/mailbox/qcom-ipcc.yaml b/Documentation/devicetree/bindings/mailbox/qcom-ipcc.yaml new file mode 100644 index 000000000000..4ac2123d9193 --- /dev/null +++ b/Documentation/devicetree/bindings/mailbox/qcom-ipcc.yaml @@ -0,0 +1,80 @@ +# SPDX-License-Identifier: GPL-2.0 OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/mailbox/qcom-ipcc.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Qualcomm Technologies, Inc. Inter-Processor Communication Controller + +maintainers: + - Manivannan Sadhasivam <manivannan.sadhasivam@linaro.org> + +description: + The Inter-Processor Communication Controller (IPCC) is a centralized hardware + to route interrupts across various subsystems. It involves a three-level + addressing scheme called protocol, client and signal. For example, consider an + entity on the Application Processor Subsystem (APSS) that wants to listen to + Modem's interrupts via Shared Memory Point to Point (SMP2P) interface. In such + a case, the client would be Modem (client-id is 2) and the signal would be + SMP2P (signal-id is 2). The SMP2P itself falls under the Multiprocessor (MPROC) + protocol (protocol-id is 0). Refer include/dt-bindings/mailbox/qcom-ipcc.h + for the list of such IDs. + +properties: + compatible: + items: + - enum: + - qcom,sm8250-ipcc + - const: qcom,ipcc + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + interrupt-controller: true + + "#interrupt-cells": + const: 3 + description: + The first cell is the client-id, the second cell is the signal-id and the + third cell is the interrupt type. + + "#mbox-cells": + const: 2 + description: + The first cell is the client-id, and the second cell is the signal-id. + +required: + - compatible + - reg + - interrupts + - interrupt-controller + - "#interrupt-cells" + - "#mbox-cells" + +additionalProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/arm-gic.h> + #include <dt-bindings/mailbox/qcom-ipcc.h> + + mailbox@408000 { + compatible = "qcom,sm8250-ipcc", "qcom,ipcc"; + reg = <0x408000 0x1000>; + interrupts = <GIC_SPI 229 IRQ_TYPE_LEVEL_HIGH>; + interrupt-controller; + #interrupt-cells = <3>; + #mbox-cells = <2>; + }; + + smp2p-modem { + compatible = "qcom,smp2p"; + interrupts-extended = <&ipcc_mproc IPCC_CLIENT_MPSS + IPCC_MPROC_SIGNAL_SMP2P IRQ_TYPE_EDGE_RISING>; + mboxes = <&ipcc_mproc IPCC_CLIENT_MPSS IPCC_MPROC_SIGNAL_SMP2P>; + + /* Other SMP2P fields */ + }; diff --git a/Documentation/devicetree/bindings/mailbox/sprd-mailbox.yaml b/Documentation/devicetree/bindings/mailbox/sprd-mailbox.yaml new file mode 100644 index 000000000000..26a5cca3f838 --- /dev/null +++ b/Documentation/devicetree/bindings/mailbox/sprd-mailbox.yaml @@ -0,0 +1,60 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: "http://devicetree.org/schemas/mailbox/sprd-mailbox.yaml#" +$schema: "http://devicetree.org/meta-schemas/core.yaml#" + +title: Spreadtrum mailbox controller bindings + +maintainers: + - Orson Zhai <orsonzhai@gmail.com> + - Baolin Wang <baolin.wang7@gmail.com> + - Chunyan Zhang <zhang.lyra@gmail.com> + +properties: + compatible: + enum: + - sprd,sc9860-mailbox + + reg: + items: + - description: inbox registers' base address + - description: outbox registers' base address + + interrupts: + items: + - description: inbox interrupt + - description: outbox interrupt + + clocks: + maxItems: 1 + + clock-names: + items: + - const: enable + + "#mbox-cells": + const: 1 + +required: + - compatible + - reg + - interrupts + - "#mbox-cells" + - clocks + - clock-names + +additionalProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/arm-gic.h> + mailbox: mailbox@400a0000 { + compatible = "sprd,sc9860-mailbox"; + reg = <0x400a0000 0x8000>, <0x400a8000 0x8000>; + #mbox-cells = <1>; + clock-names = "enable"; + clocks = <&aon_gate 53>; + interrupts = <GIC_SPI 28 IRQ_TYPE_LEVEL_HIGH>, <GIC_SPI 29 IRQ_TYPE_LEVEL_HIGH>; + }; +... diff --git a/Documentation/devicetree/bindings/media/i2c/ov8856.yaml b/Documentation/devicetree/bindings/media/i2c/ov8856.yaml index d6af685ad3ca..1956b2a32bf4 100644 --- a/Documentation/devicetree/bindings/media/i2c/ov8856.yaml +++ b/Documentation/devicetree/bindings/media/i2c/ov8856.yaml @@ -79,8 +79,7 @@ properties: - const: 4 link-frequencies: - allOf: - - $ref: /schemas/types.yaml#/definitions/uint64-array + $ref: /schemas/types.yaml#/definitions/uint64-array description: Allowed data bus frequencies. 360000000, 180000000 Hz or both are supported by the driver. diff --git a/Documentation/devicetree/bindings/media/rockchip,vdec.yaml b/Documentation/devicetree/bindings/media/rockchip,vdec.yaml index 0c68cdad9a31..8d35c327018b 100644 --- a/Documentation/devicetree/bindings/media/rockchip,vdec.yaml +++ b/Documentation/devicetree/bindings/media/rockchip,vdec.yaml @@ -61,7 +61,7 @@ examples: vdec: video-codec@ff660000 { compatible = "rockchip,rk3399-vdec"; - reg = <0x0 0xff660000 0x0 0x400>; + reg = <0xff660000 0x400>; interrupts = <GIC_SPI 116 IRQ_TYPE_LEVEL_HIGH 0>; clocks = <&cru ACLK_VDU>, <&cru HCLK_VDU>, <&cru SCLK_VDU_CA>, <&cru SCLK_VDU_CORE>; diff --git a/Documentation/devicetree/bindings/media/rockchip-vpu.yaml b/Documentation/devicetree/bindings/media/rockchip-vpu.yaml index 27df18ad6a81..2b629456d75f 100644 --- a/Documentation/devicetree/bindings/media/rockchip-vpu.yaml +++ b/Documentation/devicetree/bindings/media/rockchip-vpu.yaml @@ -66,7 +66,7 @@ examples: vpu: video-codec@ff9a0000 { compatible = "rockchip,rk3288-vpu"; - reg = <0x0 0xff9a0000 0x0 0x800>; + reg = <0xff9a0000 0x800>; interrupts = <GIC_SPI 9 IRQ_TYPE_LEVEL_HIGH>, <GIC_SPI 10 IRQ_TYPE_LEVEL_HIGH>; interrupt-names = "vepu", "vdpu"; diff --git a/Documentation/devicetree/bindings/memory-controllers/ingenic,nemc.yaml b/Documentation/devicetree/bindings/memory-controllers/ingenic,nemc.yaml index 9b478da0c479..17ba45a6c260 100644 --- a/Documentation/devicetree/bindings/memory-controllers/ingenic,nemc.yaml +++ b/Documentation/devicetree/bindings/memory-controllers/ingenic,nemc.yaml @@ -45,9 +45,8 @@ patternProperties: maxItems: 255 ingenic,nemc-bus-width: - allOf: - - $ref: /schemas/types.yaml#/definitions/uint32 - - enum: [8, 16] + $ref: /schemas/types.yaml#/definitions/uint32 + enum: [8, 16] description: Specifies the bus width in bits. ingenic,nemc-tAS: diff --git a/Documentation/devicetree/bindings/mtd/arasan,nand-controller.yaml b/Documentation/devicetree/bindings/mtd/arasan,nand-controller.yaml new file mode 100644 index 000000000000..cb9794edff24 --- /dev/null +++ b/Documentation/devicetree/bindings/mtd/arasan,nand-controller.yaml @@ -0,0 +1,63 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/mtd/arasan,nand-controller.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Arasan NAND Flash Controller with ONFI 3.1 support device tree bindings + +allOf: + - $ref: "nand-controller.yaml" + +maintainers: + - Naga Sureshkumar Relli <naga.sureshkumar.relli@xilinx.com> + +properties: + compatible: + oneOf: + - items: + - enum: + - xlnx,zynqmp-nand-controller + - enum: + - arasan,nfc-v3p10 + + reg: + maxItems: 1 + + clocks: + items: + - description: Controller clock + - description: NAND bus clock + + clock-names: + items: + - const: controller + - const: bus + + interrupts: + maxItems: 1 + + "#address-cells": true + "#size-cells": true + +required: + - compatible + - reg + - clocks + - clock-names + - interrupts + +additionalProperties: true + +examples: + - | + nfc: nand-controller@ff100000 { + compatible = "xlnx,zynqmp-nand-controller", "arasan,nfc-v3p10"; + reg = <0xff100000 0x1000>; + clock-names = "controller", "bus"; + clocks = <&clk200>, <&clk100>; + interrupt-parent = <&gic>; + interrupts = <0 14 4>; + #address-cells = <1>; + #size-cells = <0>; + }; diff --git a/Documentation/devicetree/bindings/mtd/brcm,brcmnand.txt b/Documentation/devicetree/bindings/mtd/brcm,brcmnand.txt index 05651a654c66..44335a4f8bfb 100644 --- a/Documentation/devicetree/bindings/mtd/brcm,brcmnand.txt +++ b/Documentation/devicetree/bindings/mtd/brcm,brcmnand.txt @@ -20,6 +20,8 @@ Required properties: "brcm,brcmnand" and an appropriate version compatibility string, like "brcm,brcmnand-v7.0" Possible values: + brcm,brcmnand-v2.1 + brcm,brcmnand-v2.2 brcm,brcmnand-v4.0 brcm,brcmnand-v5.0 brcm,brcmnand-v6.0 diff --git a/Documentation/devicetree/bindings/mtd/partition.txt b/Documentation/devicetree/bindings/mtd/partition.txt index afbbd870496d..4a39698221a2 100644 --- a/Documentation/devicetree/bindings/mtd/partition.txt +++ b/Documentation/devicetree/bindings/mtd/partition.txt @@ -61,6 +61,9 @@ Optional properties: clobbered. - lock : Do not unlock the partition at initialization time (not supported on all devices) +- slc-mode: This parameter, if present, allows one to emulate SLC mode on a + partition attached to an MLC NAND thus making this partition immune to + paired-pages corruptions Examples: diff --git a/Documentation/devicetree/bindings/net/ti,k3-am654-cpsw-nuss.yaml b/Documentation/devicetree/bindings/net/ti,k3-am654-cpsw-nuss.yaml index 71d9e6c1c72e..174579370a22 100644 --- a/Documentation/devicetree/bindings/net/ti,k3-am654-cpsw-nuss.yaml +++ b/Documentation/devicetree/bindings/net/ti,k3-am654-cpsw-nuss.yaml @@ -145,8 +145,7 @@ patternProperties: "^cpts@[0-9a-f]+": type: object - allOf: - - $ref: "ti,k3-am654-cpts.yaml#" + $ref: "ti,k3-am654-cpts.yaml#" description: CPSW Common Platform Time Sync (CPTS) module. diff --git a/Documentation/devicetree/bindings/net/ti,k3-am654-cpts.yaml b/Documentation/devicetree/bindings/net/ti,k3-am654-cpts.yaml index 50e027911dd4..9b7117920d90 100644 --- a/Documentation/devicetree/bindings/net/ti,k3-am654-cpts.yaml +++ b/Documentation/devicetree/bindings/net/ti,k3-am654-cpts.yaml @@ -74,15 +74,13 @@ properties: - const: cpts ti,cpts-ext-ts-inputs: - allOf: - - $ref: /schemas/types.yaml#/definitions/uint32 + $ref: /schemas/types.yaml#/definitions/uint32 maximum: 8 description: Number of hardware timestamp push inputs (HWx_TS_PUSH) ti,cpts-periodic-outputs: - allOf: - - $ref: /schemas/types.yaml#/definitions/uint32 + $ref: /schemas/types.yaml#/definitions/uint32 maximum: 8 description: Number of timestamp Generator function outputs (TS_GENFx) @@ -123,7 +121,7 @@ examples: cpts@310d0000 { compatible = "ti,am65-cpts"; - reg = <0x0 0x310d0000 0x0 0x400>; + reg = <0x310d0000 0x400>; reg-names = "cpts"; clocks = <&main_cpts_mux>; clock-names = "cpts"; diff --git a/Documentation/devicetree/bindings/opp/opp.txt b/Documentation/devicetree/bindings/opp/opp.txt index 68592271461f..9d16d417e9be 100644 --- a/Documentation/devicetree/bindings/opp/opp.txt +++ b/Documentation/devicetree/bindings/opp/opp.txt @@ -83,9 +83,14 @@ properties. Required properties: - opp-hz: Frequency in Hz, expressed as a 64-bit big-endian integer. This is a - required property for all device nodes but devices like power domains. The - power domain nodes must have another (implementation dependent) property which - uniquely identifies the OPP nodes. + required property for all device nodes, unless another "required" property to + uniquely identify the OPP nodes exists. Devices like power domains must have + another (implementation dependent) property. + +- opp-peak-kBps: Peak bandwidth in kilobytes per second, expressed as an array + of 32-bit big-endian integers. Each element of the array represents the + peak bandwidth value of each interconnect path. The number of elements should + match the number of interconnect paths. Optional properties: - opp-microvolt: voltage in micro Volts. @@ -132,6 +137,12 @@ Optional properties: - opp-level: A value representing the performance level of the device, expressed as a 32-bit integer. +- opp-avg-kBps: Average bandwidth in kilobytes per second, expressed as an array + of 32-bit big-endian integers. Each element of the array represents the + average bandwidth value of each interconnect path. The number of elements + should match the number of interconnect paths. This property is only + meaningful in OPP tables where opp-peak-kBps is present. + - clock-latency-ns: Specifies the maximum possible transition latency (in nanoseconds) for switching to this OPP from any other OPP. diff --git a/Documentation/devicetree/bindings/pci/cdns-pcie-ep.yaml b/Documentation/devicetree/bindings/pci/cdns-pcie-ep.yaml index 6150a7a7bdbf..016a5f61592d 100644 --- a/Documentation/devicetree/bindings/pci/cdns-pcie-ep.yaml +++ b/Documentation/devicetree/bindings/pci/cdns-pcie-ep.yaml @@ -15,8 +15,7 @@ allOf: properties: cdns,max-outbound-regions: description: maximum number of outbound regions - allOf: - - $ref: /schemas/types.yaml#/definitions/uint32 + $ref: /schemas/types.yaml#/definitions/uint32 minimum: 1 maximum: 32 default: 32 diff --git a/Documentation/devicetree/bindings/pci/cdns-pcie-host.yaml b/Documentation/devicetree/bindings/pci/cdns-pcie-host.yaml index c87a3a36ccd2..303078a7b7a8 100644 --- a/Documentation/devicetree/bindings/pci/cdns-pcie-host.yaml +++ b/Documentation/devicetree/bindings/pci/cdns-pcie-host.yaml @@ -16,8 +16,7 @@ allOf: properties: cdns,max-outbound-regions: description: maximum number of outbound regions - allOf: - - $ref: /schemas/types.yaml#/definitions/uint32 + $ref: /schemas/types.yaml#/definitions/uint32 minimum: 1 maximum: 32 default: 32 diff --git a/Documentation/devicetree/bindings/phy/calxeda-combophy.yaml b/Documentation/devicetree/bindings/phy/calxeda-combophy.yaml index 16a8bd7644bf..41ee16e21f8d 100644 --- a/Documentation/devicetree/bindings/phy/calxeda-combophy.yaml +++ b/Documentation/devicetree/bindings/phy/calxeda-combophy.yaml @@ -29,9 +29,8 @@ properties: phydev: description: device ID for programming the ComboPHY. - allOf: - - $ref: /schemas/types.yaml#/definitions/uint32 - - maximum: 31 + $ref: /schemas/types.yaml#/definitions/uint32 + maximum: 31 required: - compatible diff --git a/Documentation/devicetree/bindings/phy/qcom,qmp-phy.yaml b/Documentation/devicetree/bindings/phy/qcom,qmp-phy.yaml index 973b2d196f46..f80f8896d527 100644 --- a/Documentation/devicetree/bindings/phy/qcom,qmp-phy.yaml +++ b/Documentation/devicetree/bindings/phy/qcom,qmp-phy.yaml @@ -44,6 +44,8 @@ properties: "#size-cells": enum: [ 1, 2 ] + ranges: true + clocks: minItems: 1 maxItems: 4 @@ -87,6 +89,7 @@ required: - "#clock-cells" - "#address-cells" - "#size-cells" + - ranges - clocks - clock-names - resets @@ -281,10 +284,11 @@ examples: #include <dt-bindings/clock/qcom,gcc-sdm845.h> usb_2_qmpphy: phy-wrapper@88eb000 { compatible = "qcom,sdm845-qmp-usb3-uni-phy"; - reg = <0 0x088eb000 0 0x18c>; + reg = <0x088eb000 0x18c>; #clock-cells = <1>; - #address-cells = <2>; - #size-cells = <2>; + #address-cells = <1>; + #size-cells = <1>; + ranges = <0x0 0x088eb000 0x2000>; clocks = <&gcc GCC_USB3_SEC_PHY_AUX_CLK >, <&gcc GCC_USB_PHY_CFG_AHB2PHY_CLK>, @@ -299,11 +303,11 @@ examples: vdda-phy-supply = <&vdda_usb2_ss_1p2>; vdda-pll-supply = <&vdda_usb2_ss_core>; - usb_2_ssphy: phy@88eb200 { - reg = <0 0x088eb200 0 0x128>, - <0 0x088eb400 0 0x1fc>, - <0 0x088eb800 0 0x218>, - <0 0x088eb600 0 0x70>; + usb_2_ssphy: phy@200 { + reg = <0x200 0x128>, + <0x400 0x1fc>, + <0x800 0x218>, + <0x600 0x70>; #clock-cells = <0>; #phy-cells = <0>; clocks = <&gcc GCC_USB3_SEC_PHY_PIPE_CLK>; diff --git a/Documentation/devicetree/bindings/phy/qcom,qmp-usb3-dp-phy.yaml b/Documentation/devicetree/bindings/phy/qcom,qmp-usb3-dp-phy.yaml index b770e637df1d..6e2487501457 100644 --- a/Documentation/devicetree/bindings/phy/qcom,qmp-usb3-dp-phy.yaml +++ b/Documentation/devicetree/bindings/phy/qcom,qmp-usb3-dp-phy.yaml @@ -34,6 +34,8 @@ properties: "#size-cells": enum: [ 1, 2 ] + ranges: true + clocks: items: - description: Phy aux clock. @@ -86,6 +88,7 @@ required: - "#clock-cells" - "#address-cells" - "#size-cells" + - ranges - clocks - clock-names - resets @@ -100,12 +103,13 @@ examples: #include <dt-bindings/clock/qcom,gcc-sdm845.h> usb_1_qmpphy: phy-wrapper@88e9000 { compatible = "qcom,sdm845-qmp-usb3-phy"; - reg = <0 0x088e9000 0 0x18c>, - <0 0x088e8000 0 0x10>; + reg = <0x088e9000 0x18c>, + <0x088e8000 0x10>; reg-names = "reg-base", "dp_com"; #clock-cells = <1>; - #address-cells = <2>; - #size-cells = <2>; + #address-cells = <1>; + #size-cells = <1>; + ranges = <0x0 0x088e9000 0x1000>; clocks = <&gcc GCC_USB3_PRIM_PHY_AUX_CLK>, <&gcc GCC_USB_PHY_CFG_AHB2PHY_CLK>, @@ -120,17 +124,17 @@ examples: vdda-phy-supply = <&vdda_usb2_ss_1p2>; vdda-pll-supply = <&vdda_usb2_ss_core>; - usb_1_ssphy: phy@88e9200 { - reg = <0 0x088e9200 0 0x128>, - <0 0x088e9400 0 0x200>, - <0 0x088e9c00 0 0x218>, - <0 0x088e9600 0 0x128>, - <0 0x088e9800 0 0x200>, - <0 0x088e9a00 0 0x100>; - #clock-cells = <0>; - #phy-cells = <0>; - clocks = <&gcc GCC_USB3_PRIM_PHY_PIPE_CLK>; - clock-names = "pipe0"; - clock-output-names = "usb3_phy_pipe_clk_src"; - }; + phy@200 { + reg = <0x200 0x128>, + <0x400 0x200>, + <0xc00 0x218>, + <0x600 0x128>, + <0x800 0x200>, + <0xa00 0x100>; + #clock-cells = <0>; + #phy-cells = <0>; + clocks = <&gcc GCC_USB3_PRIM_PHY_PIPE_CLK>; + clock-names = "pipe0"; + clock-output-names = "usb3_phy_pipe_clk_src"; }; + }; diff --git a/Documentation/devicetree/bindings/phy/qcom,usb-snps-femto-v2.yaml b/Documentation/devicetree/bindings/phy/qcom,usb-snps-femto-v2.yaml index 574f890fab1d..4949a2851532 100644 --- a/Documentation/devicetree/bindings/phy/qcom,usb-snps-femto-v2.yaml +++ b/Documentation/devicetree/bindings/phy/qcom,usb-snps-femto-v2.yaml @@ -65,7 +65,7 @@ examples: #include <dt-bindings/clock/qcom,gcc-sm8150.h> phy@88e2000 { compatible = "qcom,sm8150-usb-hs-phy"; - reg = <0 0x088e2000 0 0x400>; + reg = <0x088e2000 0x400>; #phy-cells = <0>; clocks = <&rpmhcc RPMH_CXO_CLK>; diff --git a/Documentation/devicetree/bindings/phy/renesas,usb3-phy.yaml b/Documentation/devicetree/bindings/phy/renesas,usb3-phy.yaml index f459eaf55278..68cf9dd0390d 100644 --- a/Documentation/devicetree/bindings/phy/renesas,usb3-phy.yaml +++ b/Documentation/devicetree/bindings/phy/renesas,usb3-phy.yaml @@ -52,9 +52,8 @@ properties: description: | Enable/disable spread spectrum clock (ssc). 0 or the property doesn't exist means disabling the ssc. The actual value will be -<value> ppm. - allOf: - - $ref: /schemas/types.yaml#/definitions/uint32 - - enum: [ 0, 4003, 4492, 4980 ] + $ref: /schemas/types.yaml#/definitions/uint32 + enum: [ 0, 4003, 4492, 4980 ] required: - compatible diff --git a/Documentation/devicetree/bindings/power/reset/syscon-reboot-mode.txt b/Documentation/devicetree/bindings/power/reset/syscon-reboot-mode.txt deleted file mode 100644 index f7ce1d8af04a..000000000000 --- a/Documentation/devicetree/bindings/power/reset/syscon-reboot-mode.txt +++ /dev/null @@ -1,35 +0,0 @@ -SYSCON reboot mode driver - -This driver gets reboot mode magic value form reboot-mode driver -and stores it in a SYSCON mapped register. Then the bootloader -can read it and take different action according to the magic -value stored. - -This DT node should be represented as a sub-node of a "syscon", "simple-mfd" -node. - -Required properties: -- compatible: should be "syscon-reboot-mode" -- offset: offset in the register map for the storage register (in bytes) - -Optional property: -- mask: bits mask of the bits in the register to store the reboot mode magic value, - default set to 0xffffffff if missing. - -The rest of the properties should follow the generic reboot-mode description -found in reboot-mode.txt - -Example: - pmu: pmu@20004000 { - compatible = "rockchip,rk3066-pmu", "syscon", "simple-mfd"; - reg = <0x20004000 0x100>; - - reboot-mode { - compatible = "syscon-reboot-mode"; - offset = <0x40>; - mode-normal = <BOOT_NORMAL>; - mode-recovery = <BOOT_RECOVERY>; - mode-bootloader = <BOOT_FASTBOOT>; - mode-loader = <BOOT_BL_DOWNLOAD>; - }; - }; diff --git a/Documentation/devicetree/bindings/power/reset/syscon-reboot-mode.yaml b/Documentation/devicetree/bindings/power/reset/syscon-reboot-mode.yaml new file mode 100644 index 000000000000..9b1ffceefe3d --- /dev/null +++ b/Documentation/devicetree/bindings/power/reset/syscon-reboot-mode.yaml @@ -0,0 +1,55 @@ +# SPDX-License-Identifier: GPL-2.0-only +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/power/reset/syscon-reboot-mode.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Generic SYSCON reboot mode driver + +maintainers: + - Sebastian Reichel <sre@kernel.org> + +description: | + This driver gets reboot mode magic value from reboot-mode driver + and stores it in a SYSCON mapped register. Then the bootloader + can read it and take different action according to the magic + value stored. The SYSCON mapped register is retrieved from the + parental dt-node plus the offset. So the SYSCON reboot-mode node + should be represented as a sub-node of a "syscon", "simple-mfd" node. + +properties: + compatible: + const: syscon-reboot-mode + + mask: + $ref: /schemas/types.yaml#/definitions/uint32 + description: Update only the register bits defined by the mask (32 bit) + + offset: + $ref: /schemas/types.yaml#/definitions/uint32 + description: Offset in the register map for the mode register (in bytes) + +patternProperties: + "^mode-.+": + $ref: /schemas/types.yaml#/definitions/uint32 + description: Vendor-specific mode value written to the mode register + +additionalProperties: false + +required: + - compatible + - offset + +examples: + - | + #include <dt-bindings/soc/rockchip,boot-mode.h> + + reboot-mode { + compatible = "syscon-reboot-mode"; + offset = <0x40>; + mode-normal = <BOOT_NORMAL>; + mode-recovery = <BOOT_RECOVERY>; + mode-bootloader = <BOOT_FASTBOOT>; + mode-loader = <BOOT_BL_DOWNLOAD>; + }; +... diff --git a/Documentation/devicetree/bindings/power/reset/syscon-reboot.yaml b/Documentation/devicetree/bindings/power/reset/syscon-reboot.yaml index b80772cb9f06..da2509724812 100644 --- a/Documentation/devicetree/bindings/power/reset/syscon-reboot.yaml +++ b/Documentation/devicetree/bindings/power/reset/syscon-reboot.yaml @@ -12,9 +12,12 @@ maintainers: description: |+ This is a generic reset driver using syscon to map the reset register. The reset is generally performed with a write to the reset register - defined by the register map pointed by syscon reference plus the offset - with the value and mask defined in the reboot node. - Default will be little endian mode, 32 bit access only. + defined by the SYSCON register map base plus the offset with the value and + mask defined in the reboot node. Default will be little endian mode, 32 bit + access only. The SYSCON registers map is normally retrieved from the + parental dt-node. So the SYSCON reboot node should be represented as a + sub-node of a "syscon", "simple-mfd" node. Though the regmap property + pointing to the system controller node is also supported. properties: compatible: @@ -30,7 +33,10 @@ properties: regmap: $ref: /schemas/types.yaml#/definitions/phandle - description: Phandle to the register map node. + deprecated: true + description: | + Phandle to the register map node. This property is deprecated in favor of + the syscon-reboot node been a child of a system controller node. value: $ref: /schemas/types.yaml#/definitions/uint32 @@ -38,7 +44,6 @@ properties: required: - compatible - - regmap - offset additionalProperties: false diff --git a/Documentation/devicetree/bindings/power/supply/battery.txt b/Documentation/devicetree/bindings/power/supply/battery.txt index 3049cf88bdcf..5e29595edd74 100644 --- a/Documentation/devicetree/bindings/power/supply/battery.txt +++ b/Documentation/devicetree/bindings/power/supply/battery.txt @@ -11,15 +11,21 @@ different type. This prevents unpredictable, potentially harmful, behavior should a replacement that changes the battery type occur without a corresponding update to the dtb. +Please note that not all charger drivers respect all of the properties. + Required Properties: - compatible: Must be "simple-battery" Optional Properties: + - over-voltage-threshold-microvolt: battery over-voltage limit + - re-charge-voltage-microvolt: limit to automatically start charging again - voltage-min-design-microvolt: drained battery voltage - voltage-max-design-microvolt: fully charged battery voltage - energy-full-design-microwatt-hours: battery design energy - charge-full-design-microamp-hours: battery design capacity + - trickle-charge-current-microamp: current for trickle-charge phase - precharge-current-microamp: current for pre-charge phase + - precharge-upper-limit-microvolt: limit when to change to constant charging - charge-term-current-microamp: current for charge termination phase - constant-charge-current-max-microamp: maximum constant input current - constant-charge-voltage-max-microvolt: maximum constant input voltage diff --git a/Documentation/devicetree/bindings/power/supply/bq27xxx.txt b/Documentation/devicetree/bindings/power/supply/bq27xxx.txt deleted file mode 100644 index 4fa8e08df2b6..000000000000 --- a/Documentation/devicetree/bindings/power/supply/bq27xxx.txt +++ /dev/null @@ -1,56 +0,0 @@ -TI BQ27XXX fuel gauge family - -Required properties: -- compatible: contains one of the following: - * "ti,bq27200" - BQ27200 - * "ti,bq27210" - BQ27210 - * "ti,bq27500" - deprecated, use revision specific property below - * "ti,bq27510" - deprecated, use revision specific property below - * "ti,bq27520" - deprecated, use revision specific property below - * "ti,bq27500-1" - BQ27500/1 - * "ti,bq27510g1" - BQ27510-g1 - * "ti,bq27510g2" - BQ27510-g2 - * "ti,bq27510g3" - BQ27510-g3 - * "ti,bq27520g1" - BQ27520-g1 - * "ti,bq27520g2" - BQ27520-g2 - * "ti,bq27520g3" - BQ27520-g3 - * "ti,bq27520g4" - BQ27520-g4 - * "ti,bq27521" - BQ27521 - * "ti,bq27530" - BQ27530 - * "ti,bq27531" - BQ27531 - * "ti,bq27541" - BQ27541 - * "ti,bq27542" - BQ27542 - * "ti,bq27546" - BQ27546 - * "ti,bq27742" - BQ27742 - * "ti,bq27545" - BQ27545 - * "ti,bq27411" - BQ27411 - * "ti,bq27421" - BQ27421 - * "ti,bq27425" - BQ27425 - * "ti,bq27426" - BQ27426 - * "ti,bq27441" - BQ27441 - * "ti,bq27621" - BQ27621 -- reg: integer, I2C address of the fuel gauge. - -Optional properties: -- monitored-battery: phandle of battery characteristics node - The fuel gauge uses the following battery properties: - + energy-full-design-microwatt-hours - + charge-full-design-microamp-hours - + voltage-min-design-microvolt - Both or neither of the *-full-design-*-hours properties must be set. - See Documentation/devicetree/bindings/power/supply/battery.txt - -Example: - - bat: battery { - compatible = "simple-battery"; - voltage-min-design-microvolt = <3200000>; - energy-full-design-microwatt-hours = <5290000>; - charge-full-design-microamp-hours = <1430000>; - }; - - bq27510g3: fuel-gauge@55 { - compatible = "ti,bq27510g3"; - reg = <0x55>; - monitored-battery = <&bat>; - }; diff --git a/Documentation/devicetree/bindings/power/supply/bq27xxx.yaml b/Documentation/devicetree/bindings/power/supply/bq27xxx.yaml new file mode 100644 index 000000000000..03d1020a2e47 --- /dev/null +++ b/Documentation/devicetree/bindings/power/supply/bq27xxx.yaml @@ -0,0 +1,91 @@ +# SPDX-License-Identifier: GPL-2.0 +# Copyright (C) 2020 Texas Instruments Incorporated +%YAML 1.2 +--- +$id: "http://devicetree.org/schemas/power/supply/bq27xxx.yaml#" +$schema: "http://devicetree.org/meta-schemas/core.yaml#" + +title: TI BQ27XXX fuel gauge family + +maintainers: + - Pali Rohár <pali@kernel.org> + - Andrew F. Davis <afd@ti.com> + - Sebastian Reichel <sre@kernel.org> + +description: | + Support various Texas Instruments fuel gauge devices that share similar + register maps and power supply properties + +allOf: + - $ref: power-supply.yaml# + +properties: + compatible: + enum: + - ti,bq27200 + - ti,bq27210 + - ti,bq27500 # deprecated, use revision specific property below + - ti,bq27510 # deprecated, use revision specific property below + - ti,bq27520 # deprecated, use revision specific property below + - ti,bq27500-1 + - ti,bq27510g1 + - ti,bq27510g2 + - ti,bq27510g3 + - ti,bq27520g1 + - ti,bq27520g2 + - ti,bq27520g3 + - ti,bq27520g4 + - ti,bq27521 + - ti,bq27530 + - ti,bq27531 + - ti,bq27541 + - ti,bq27542 + - ti,bq27546 + - ti,bq27742 + - ti,bq27545 + - ti,bq27411 + - ti,bq27421 + - ti,bq27425 + - ti,bq27426 + - ti,bq27441 + - ti,bq27621 + + reg: + maxItems: 1 + description: integer, I2C address of the fuel gauge. + + monitored-battery: + description: | + phandle of battery characteristics node. + The fuel gauge uses the following battery properties: + - energy-full-design-microwatt-hours + - charge-full-design-microamp-hours + - voltage-min-design-microvolt + Both or neither of the *-full-design-*-hours properties must be set. + See Documentation/devicetree/bindings/power/supply/battery.txt + + power-supplies: true + +required: + - compatible + - reg +additionalProperties: false + +examples: + - | + i2c0 { + #address-cells = <1>; + #size-cells = <0>; + bat: battery { + compatible = "simple-battery"; + voltage-min-design-microvolt = <3200000>; + energy-full-design-microwatt-hours = <5290000>; + charge-full-design-microamp-hours = <1430000>; + }; + + bq27510g3: fuel-gauge@55 { + compatible = "ti,bq27510g3"; + reg = <0x55>; + monitored-battery = <&bat>; + }; + }; diff --git a/Documentation/devicetree/bindings/power/supply/cw2015_battery.yaml b/Documentation/devicetree/bindings/power/supply/cw2015_battery.yaml new file mode 100644 index 000000000000..2036977ecc2f --- /dev/null +++ b/Documentation/devicetree/bindings/power/supply/cw2015_battery.yaml @@ -0,0 +1,79 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/power/supply/cw2015_battery.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Battery driver for CW2015 shuntless fuel gauge by CellWise. + +maintainers: + - Tobias Schramm <t.schramm@manjaro.org> + +description: | + The driver can utilize information from a simple-battery linked via a + phandle in monitored-battery. If specified the driver uses the + charge-full-design-microamp-hours property of the battery. + +properties: + compatible: + const: cellwise,cw2015 + + reg: + maxItems: 1 + + cellwise,battery-profile: + description: | + This property specifies characteristics of the battery used. The format + of this binary blob is kept secret by CellWise. The only way to obtain + it is to mail two batteries to a test facility of CellWise and receive + back a test report with the binary blob. + $ref: /schemas/types.yaml#definitions/uint8-array + minItems: 64 + maxItems: 64 + + cellwise,monitor-interval-ms: + description: + Specifies the interval in milliseconds gauge values are polled at + minimum: 250 + + power-supplies: + description: + Specifies supplies used for charging the battery connected to this gauge + $ref: /schemas/types.yaml#/definitions/phandle-array + minItems: 1 + maxItems: 8 # Should be enough + + monitored-battery: + description: + Specifies the phandle of a simple-battery connected to this gauge + $ref: /schemas/types.yaml#/definitions/phandle + +required: + - compatible + - reg + +examples: + - | + i2c { + #address-cells = <1>; + #size-cells = <0>; + + cw2015@62 { + compatible = "cellwise,cw201x"; + reg = <0x62>; + cellwise,battery-profile = /bits/ 8 < + 0x17 0x67 0x80 0x73 0x6E 0x6C 0x6B 0x63 + 0x77 0x51 0x5C 0x58 0x50 0x4C 0x48 0x36 + 0x15 0x0C 0x0C 0x19 0x5B 0x7D 0x6F 0x69 + 0x69 0x5B 0x0C 0x29 0x20 0x40 0x52 0x59 + 0x57 0x56 0x54 0x4F 0x3B 0x1F 0x7F 0x17 + 0x06 0x1A 0x30 0x5A 0x85 0x93 0x96 0x2D + 0x48 0x77 0x9C 0xB3 0x80 0x52 0x94 0xCB + 0x2F 0x00 0x64 0xA5 0xB5 0x11 0xF0 0x11 + >; + cellwise,monitor-interval-ms = <5000>; + monitored-battery = <&bat>; + power-supplies = <&mains_charger>, <&usb_charger>; + }; + }; + diff --git a/Documentation/devicetree/bindings/power/supply/power-supply.yaml b/Documentation/devicetree/bindings/power/supply/power-supply.yaml new file mode 100644 index 000000000000..3bb02bb3a2d8 --- /dev/null +++ b/Documentation/devicetree/bindings/power/supply/power-supply.yaml @@ -0,0 +1,40 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: "http://devicetree.org/schemas/power/supply/power-supply.yaml#" +$schema: "http://devicetree.org/meta-schemas/core.yaml#" + +title: Power Supply Core Support + +maintainers: + - Sebastian Reichel <sre@kernel.org> + +properties: + power-supplies: + $ref: /schemas/types.yaml#/definitions/phandle-array + description: + This property is added to a supply in order to list the devices which + supply it power, referenced by their phandles. + +examples: + - | + power { + #address-cells = <1>; + #size-cells = <0>; + + usb_charger:charger@e { + compatible = "some,usb-charger"; + reg = <0xe>; + }; + + ac_charger:charger@c { + compatible = "some,ac-charger"; + reg = <0xc>; + }; + + battery:battery@b { + compatible = "some,battery"; + reg = <0xb>; + power-supplies = <&usb_charger>, <&ac_charger>; + }; + }; diff --git a/Documentation/devicetree/bindings/power/supply/power_supply.txt b/Documentation/devicetree/bindings/power/supply/power_supply.txt index 8391bfa0edac..d9693e054509 100644 --- a/Documentation/devicetree/bindings/power/supply/power_supply.txt +++ b/Documentation/devicetree/bindings/power/supply/power_supply.txt @@ -1,23 +1,2 @@ -Power Supply Core Support - -Optional Properties: - - power-supplies : This property is added to a supply in order to list the - devices which supply it power, referenced by their phandles. - -Example: - - usb-charger: power@e { - compatible = "some,usb-charger"; - ... - }; - - ac-charger: power@c { - compatible = "some,ac-charger"; - ... - }; - - battery@b { - compatible = "some,battery"; - ... - power-supplies = <&usb-charger>, <&ac-charger>; - }; +This binding has been converted to yaml please see power-supply.yaml in this +directory. diff --git a/Documentation/devicetree/bindings/power/supply/rohm,bd99954.yaml b/Documentation/devicetree/bindings/power/supply/rohm,bd99954.yaml new file mode 100644 index 000000000000..7e0f73a898c7 --- /dev/null +++ b/Documentation/devicetree/bindings/power/supply/rohm,bd99954.yaml @@ -0,0 +1,155 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/power/supply/rohm,bd99954.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: ROHM BD99954 Battery charger + +maintainers: + - Matti Vaittinen <matti.vaittinen@fi.rohmeurope.com> + - Markus Laine <markus.laine@fi.rohmeurope.com> + - Mikko Mutanen <mikko.mutanen@fi.rohmeurope.com> + +description: | + The ROHM BD99954 is a Battery Management LSI for 1-4 cell Lithium-Ion + secondary battery intended to be used in space-constraint equipment such + as Low profile Notebook PC, Tablets and other applications. BD99954 + provides a Dual-source Battery Charger, two port BC1.2 detection and a + Battery Monitor. + + +properties: + compatible: + const: rohm,bd99954 +# +# The battery charging profile of BD99954. +# +# Curve (1) represents charging current. +# Curve (2) represents battery voltage. +# +# The BD99954 data sheet divides charging to three phases. +# a) Trickle-charge with constant current (8). +# b) pre-charge with constant current (6) +# c) fast-charge with: +# First a constant current (5) phase (CC) +# Then constant voltage (CV) phase (after the battery voltage has reached +# target level - until charging current has dropped to termination +# level (7) +# +# V ^ ^ I +# . . +# . . +# (4)- -.- - - - - - - - - - - - - - +++++++++++++++++++++++++++. +# . / . +# . ++++++/++ - - - - - - - - - - - - -.- - (5) +# . + / + . +# . + - -- . +# . + - + . +# . +.- -: . +# . .+ +` . +# . .- + | `/ . +# . .." + .: . +# . -" + -- . +# . (2) ..." + | :- . +# . ..."" + -: . +# (3)- -.-.""- - - - -+++++++++ - - - - - - -.:- - - - - - - - - .- - (6) +# . + `:. . +# . + | -: . +# . + -: . +# . + .. . +# . (1) + | "+++- - - -.- - (7) +# -++++++++++++++- - - - - - - - - - - - - - - - - + - - - .- - (8) +# . + - +# -------------------------------------------------+++++++++--> +# | | | CC | CV | +# | --trickle-- | -pre- | ---------fast----------- | +# +# The charger uses the following battery properties +# - trickle-charge-current-microamp: +# Current used at trickle-charge phase (8 in above chart) +# minimum: 64000 +# maximum: 1024000 +# multipleOf: 64000 +# - precharge-current-microamp: +# Current used at pre-charge phase (6 in above chart) +# minimum: 64000 +# maximum: 1024000 +# multipleOf: 64000 +# - constant-charge-current-max-microamp +# Current used at fast charge constant current phase (5 in above chart) +# minimum: 64000 +# maximum: 1024000 +# multipleOf: 64000 +# - constant-charge-voltage-max-microvolt +# The constant voltage used in fast charging phase (4 in above chart) +# minimum: 2560000 +# maximum: 19200000 +# multipleOf: 16000 +# - precharge-upper-limit-microvolt +# charging mode is changed from trickle charging to pre-charging +# when battery voltage exceeds this limit voltage (3 in above chart) +# minimum: 2048000 +# maximum: 19200000 +# multipleOf: 64000 +# - re-charge-voltage-microvolt +# minimum: 2560000 +# maximum: 19200000 +# multipleOf: 16000 +# re-charging is automatically started when battry has been discharging +# to the point where the battery voltage drops below this limit +# - over-voltage-threshold-microvolt +# battery is expected to be faulty if battery voltage exceeds this limit. +# Charger will then enter to a "battery faulty" -state +# minimum: 2560000 +# maximum: 19200000 +# multipleOf: 16000 +# - charge-term-current-microamp +# minimum: 0 +# maximum: 1024000 +# multipleOf: 64000 +# a charge cycle terminates when the battery voltage is above recharge +# threshold, and the current is below this setting (7 in above chart) +# See also Documentation/devicetree/bindings/power/supply/battery.txt + + monitored-battery: + description: + phandle of battery characteristics devicetree node + + rohm,vsys-regulation-microvolt: + description: system specific lower limit for system voltage. + minimum: 2560000 + maximum: 19200000 + multipleOf: 64000 + + rohm,vbus-input-current-limit-microamp: + description: system specific VBUS input current limit (in microamps). + minimum: 32000 + maximum: 16352000 + multipleOf: 32000 + + rohm,vcc-input-current-limit-microamp: + description: system specific VCC/VACP input current limit (in microamps). + minimum: 32000 + maximum: 16352000 + multipleOf: 32000 + +required: + - compatible + +examples: + - | + i2c { + #address-cells = <1>; + #size-cells = <0>; + charger@9 { + compatible = "rohm,bd99954"; + monitored-battery = <&battery>; + reg = <0x9>; + interrupt-parent = <&gpio1>; + interrupts = <29 8>; + rohm,vsys-regulation-microvolt = <8960000>; + rohm,vbus-input-current-limit-microamp = <1472000>; + rohm,vcc-input-current-limit-microamp = <1472000>; + }; + }; diff --git a/Documentation/devicetree/bindings/power/supply/sbs,sbs-battery.yaml b/Documentation/devicetree/bindings/power/supply/sbs,sbs-battery.yaml new file mode 100644 index 000000000000..a90b3601e695 --- /dev/null +++ b/Documentation/devicetree/bindings/power/supply/sbs,sbs-battery.yaml @@ -0,0 +1,81 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/power/supply/sbs,sbs-battery.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: SBS compliant battery + +maintainers: + - Sebastian Reichel <sre@kernel.org> + +description: | + Battery compatible with the smart battery system specifications + +properties: + + compatible: + oneOf: + - items: + - enum: + - ti,bq20z65 + - ti,bq20z75 + - enum: + - sbs,sbs-battery + - items: + - const: sbs,sbs-battery + + reg: + maxItems: 1 + + sbs,i2c-retry-count: + description: + The number of times to retry I2C transactions on I2C IO failure. + default: 0 + $ref: /schemas/types.yaml#/definitions/uint32 + + sbs,poll-retry-count: + description: + The number of times to try looking for new status after an external + change notification. + default: 0 + $ref: /schemas/types.yaml#/definitions/uint32 + + sbs,battery-detect-gpios: + description: + GPIO which signals battery detection. If this is not supplied, the bus + needs to be polled to detect the battery. + maxItems: 1 + + sbs,disable-charger-broadcasts: + description: + SBS batteries by default send broadcast messages to SBS compliant chargers to + configure max. charge current/voltage. If your hardware does not have an SBS + compliant charger it should be disabled via this property to avoid blocking + the bus. Also some SBS battery fuel gauges are known to have a buggy multi- + master implementation. + type: boolean + +required: + - compatible + - reg + +additionalProperties: false + +examples: + - | + #include <dt-bindings/gpio/gpio.h> + + i2c { + #address-cells = <1>; + #size-cells = <0>; + + battery@b { + compatible = "ti,bq20z75", "sbs,sbs-battery"; + reg = <0xb>; + sbs,i2c-retry-count = <2>; + sbs,poll-retry-count = <10>; + sbs,battery-detect-gpios = <&gpio 122 GPIO_ACTIVE_HIGH>; + sbs,disable-charger-broadcasts; + }; + }; diff --git a/Documentation/devicetree/bindings/power/supply/sbs_sbs-battery.txt b/Documentation/devicetree/bindings/power/supply/sbs_sbs-battery.txt deleted file mode 100644 index 4e78e51018eb..000000000000 --- a/Documentation/devicetree/bindings/power/supply/sbs_sbs-battery.txt +++ /dev/null @@ -1,27 +0,0 @@ -SBS sbs-battery -~~~~~~~~~~ - -Required properties : - - compatible: "<vendor>,<part-number>", "sbs,sbs-battery" as fallback. The - part number compatible string might be used in order to take care of - vendor specific registers. - Known <vendor>,<part-number>: - ti,bq20z75 - -Optional properties : - - sbs,i2c-retry-count : The number of times to retry i2c transactions on i2c - IO failure. - - sbs,poll-retry-count : The number of times to try looking for new status - after an external change notification. - - sbs,battery-detect-gpios : The gpio which signals battery detection and - a flag specifying its polarity. - -Example: - - battery@b { - compatible = "ti,bq20z75", "sbs,sbs-battery"; - reg = <0xb>; - sbs,i2c-retry-count = <2>; - sbs,poll-retry-count = <10>; - sbs,battery-detect-gpios = <&gpio-controller 122 1>; - } diff --git a/Documentation/devicetree/bindings/property-units.txt b/Documentation/devicetree/bindings/property-units.txt index e9b8360b3288..c80a110c1e26 100644 --- a/Documentation/devicetree/bindings/property-units.txt +++ b/Documentation/devicetree/bindings/property-units.txt @@ -41,3 +41,7 @@ Temperature Pressure ---------------------------------------- -kpascal : kilopascal + +Throughput +---------------------------------------- +-kBps : kilobytes per second diff --git a/Documentation/devicetree/bindings/pwm/imx-pwm.yaml b/Documentation/devicetree/bindings/pwm/imx-pwm.yaml index 4b62af27d4b3..01df06777cba 100644 --- a/Documentation/devicetree/bindings/pwm/imx-pwm.yaml +++ b/Documentation/devicetree/bindings/pwm/imx-pwm.yaml @@ -30,13 +30,11 @@ properties: items: - description: SoC PWM ipg clock - description: SoC PWM per clock - maxItems: 2 clock-names: items: - const: ipg - const: per - maxItems: 2 interrupts: maxItems: 1 diff --git a/Documentation/devicetree/bindings/pwm/renesas,pwm-rcar.yaml b/Documentation/devicetree/bindings/pwm/renesas,pwm-rcar.yaml index 461afb4c1f5d..daadde9ff9c4 100644 --- a/Documentation/devicetree/bindings/pwm/renesas,pwm-rcar.yaml +++ b/Documentation/devicetree/bindings/pwm/renesas,pwm-rcar.yaml @@ -27,6 +27,7 @@ properties: - renesas,pwm-r8a7794 # R-Car E2 - renesas,pwm-r8a7795 # R-Car H3 - renesas,pwm-r8a7796 # R-Car M3-W + - renesas,pwm-r8a77961 # R-Car M3-W+ - renesas,pwm-r8a77965 # R-Car M3-N - renesas,pwm-r8a77970 # R-Car V3M - renesas,pwm-r8a77980 # R-Car V3H diff --git a/Documentation/devicetree/bindings/regulator/maxim,max77826.yaml b/Documentation/devicetree/bindings/regulator/maxim,max77826.yaml index 19cbd5eb2897..78c0b63243f7 100644 --- a/Documentation/devicetree/bindings/regulator/maxim,max77826.yaml +++ b/Documentation/devicetree/bindings/regulator/maxim,max77826.yaml @@ -21,8 +21,7 @@ properties: regulators: type: object - allOf: - - $ref: regulator.yaml# + $ref: regulator.yaml# description: | list of regulators provided by this controller, must be named after their hardware counterparts LDO[1-15], BUCK and BUCKBOOST @@ -30,13 +29,11 @@ properties: patternProperties: "^LDO([1-9]|1[0-5])$": type: object - allOf: - - $ref: regulator.yaml# + $ref: regulator.yaml# "^BUCK|BUCKBOOST$": type: object - allOf: - - $ref: regulator.yaml# + $ref: regulator.yaml# additionalProperties: false diff --git a/Documentation/devicetree/bindings/regulator/rohm,bd71847-regulator.yaml b/Documentation/devicetree/bindings/regulator/rohm,bd71847-regulator.yaml index d797cc23406f..07256a4b50b9 100644 --- a/Documentation/devicetree/bindings/regulator/rohm,bd71847-regulator.yaml +++ b/Documentation/devicetree/bindings/regulator/rohm,bd71847-regulator.yaml @@ -29,8 +29,7 @@ description: | patternProperties: "^LDO[1-6]$": type: object - allOf: - - $ref: regulator.yaml# + $ref: regulator.yaml# description: Properties for single LDO regulator. @@ -44,8 +43,7 @@ patternProperties: "^BUCK[1-6]$": type: object - allOf: - - $ref: regulator.yaml# + $ref: regulator.yaml# description: Properties for single BUCK regulator. @@ -56,28 +54,25 @@ patternProperties: should be "buck1", ..., "buck6" rohm,dvs-run-voltage: - allOf: - - $ref: "/schemas/types.yaml#/definitions/uint32" - - minimum: 0 - maximum: 1300000 + $ref: "/schemas/types.yaml#/definitions/uint32" + minimum: 0 + maximum: 1300000 description: PMIC default "RUN" state voltage in uV. See below table for bucks which support this. 0 means disabled. rohm,dvs-idle-voltage: - allOf: - - $ref: "/schemas/types.yaml#/definitions/uint32" - - minimum: 0 - maximum: 1300000 + $ref: "/schemas/types.yaml#/definitions/uint32" + minimum: 0 + maximum: 1300000 description: PMIC default "IDLE" state voltage in uV. See below table for bucks which support this. 0 means disabled. rohm,dvs-suspend-voltage: - allOf: - - $ref: "/schemas/types.yaml#/definitions/uint32" - - minimum: 0 - maximum: 1300000 + $ref: "/schemas/types.yaml#/definitions/uint32" + minimum: 0 + maximum: 1300000 description: PMIC default "SUSPEND" state voltage in uV. See below table for bucks which support this. 0 means disabled. diff --git a/Documentation/devicetree/bindings/remoteproc/ingenic,vpu.yaml b/Documentation/devicetree/bindings/remoteproc/ingenic,vpu.yaml new file mode 100644 index 000000000000..c019f9fbe916 --- /dev/null +++ b/Documentation/devicetree/bindings/remoteproc/ingenic,vpu.yaml @@ -0,0 +1,77 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: "http://devicetree.org/schemas/remoteproc/ingenic,vpu.yaml#" +$schema: "http://devicetree.org/meta-schemas/core.yaml#" + +title: Ingenic Video Processing Unit bindings + +description: + Inside the Video Processing Unit (VPU) of the recent JZ47xx SoCs from + Ingenic is a second Xburst MIPS CPU very similar to the main core. + This document describes the devicetree bindings for this auxiliary + processor. + +maintainers: + - Paul Cercueil <paul@crapouillou.net> + +properties: + compatible: + const: ingenic,jz4770-vpu-rproc + + reg: + items: + - description: aux registers + - description: tcsm0 registers + - description: tcsm1 registers + - description: sram registers + + reg-names: + items: + - const: aux + - const: tcsm0 + - const: tcsm1 + - const: sram + + clocks: + items: + - description: aux clock + - description: vpu clock + + clock-names: + items: + - const: aux + - const: vpu + + interrupts: + description: VPU hardware interrupt + +required: + - compatible + - reg + - reg-names + - clocks + - clock-names + - interrupts + +additionalProperties: false + +examples: + - | + #include <dt-bindings/clock/jz4770-cgu.h> + + vpu: video-decoder@132a0000 { + compatible = "ingenic,jz4770-vpu-rproc"; + + reg = <0x132a0000 0x20>, /* AUX */ + <0x132b0000 0x4000>, /* TCSM0 */ + <0x132c0000 0xc000>, /* TCSM1 */ + <0x132f0000 0x7000>; /* SRAM */ + reg-names = "aux", "tcsm0", "tcsm1", "sram"; + + clocks = <&cgu JZ4770_CLK_AUX>, <&cgu JZ4770_CLK_VPU>; + clock-names = "aux", "vpu"; + + interrupt-parent = <&cpuintc>; + interrupts = <3>; + }; diff --git a/Documentation/devicetree/bindings/remoteproc/qcom,adsp.txt b/Documentation/devicetree/bindings/remoteproc/qcom,adsp.txt index 9938918b2fea..54737024da20 100644 --- a/Documentation/devicetree/bindings/remoteproc/qcom,adsp.txt +++ b/Documentation/devicetree/bindings/remoteproc/qcom,adsp.txt @@ -15,12 +15,16 @@ on the Qualcomm ADSP Hexagon core. "qcom,qcs404-adsp-pas" "qcom,qcs404-cdsp-pas" "qcom,qcs404-wcss-pas" + "qcom,sc7180-mpss-pas" "qcom,sdm845-adsp-pas" "qcom,sdm845-cdsp-pas" "qcom,sm8150-adsp-pas" "qcom,sm8150-cdsp-pas" "qcom,sm8150-mpss-pas" "qcom,sm8150-slpi-pas" + "qcom,sm8250-adsp-pas" + "qcom,sm8250-cdsp-pas" + "qcom,sm8250-slpi-pas" - interrupts-extended: Usage: required @@ -44,8 +48,12 @@ on the Qualcomm ADSP Hexagon core. qcom,sm8150-adsp-pas: qcom,sm8150-cdsp-pas: qcom,sm8150-slpi-pas: + qcom,sm8250-adsp-pas: + qcom,sm8250-cdsp-pas: + qcom,sm8250-slpi-pas: must be "wdog", "fatal", "ready", "handover", "stop-ack" qcom,qcs404-wcss-pas: + qcom,sc7180-mpss-pas: qcom,sm8150-mpss-pas: must be "wdog", "fatal", "ready", "handover", "stop-ack", "shutdown-ack" @@ -105,10 +113,14 @@ on the Qualcomm ADSP Hexagon core. qcom,sdm845-cdsp-pas: qcom,sm8150-adsp-pas: qcom,sm8150-cdsp-pas: + qcom,sm8250-cdsp-pas: must be "cx", "load_state" + qcom,sc7180-mpss-pas: qcom,sm8150-mpss-pas: must be "cx", "load_state", "mss" + qcom,sm8250-adsp-pas: qcom,sm8150-slpi-pas: + qcom,sm8250-slpi-pas: must be "lcx", "lmx", "load_state" - memory-region: diff --git a/Documentation/devicetree/bindings/remoteproc/qcom,q6v5.txt b/Documentation/devicetree/bindings/remoteproc/qcom,q6v5.txt index 88dfa3fc15f7..1f9a62e13ebe 100644 --- a/Documentation/devicetree/bindings/remoteproc/qcom,q6v5.txt +++ b/Documentation/devicetree/bindings/remoteproc/qcom,q6v5.txt @@ -79,7 +79,7 @@ on the Qualcomm Hexagon core. "snoc_axi", "mnoc_axi", "qdss" qcom,sc7180-mss-pil: must be "iface", "bus", "xo", "snoc_axi", "mnoc_axi", - "mss_crypto", "mss_nav", "nav" + "nav" qcom,sdm845-mss-pil: must be "iface", "bus", "mem", "xo", "gpll0_mss", "snoc_axi", "mnoc_axi", "prng" @@ -102,6 +102,14 @@ on the Qualcomm Hexagon core. must be "mss_restart", "pdc_reset" for the modem sub-system on SC7180, SDM845 SoCs +For devices where the mba and mpss sub-nodes are not specified, mba/mpss region +should be referenced as follows: +- memory-region: + Usage: required + Value type: <phandle> + Definition: reference to the reserved-memory for the mba region followed + by the mpss region + For the compatible strings below the following supplies are required: "qcom,q6v5-pil" "qcom,msm8916-mss-pil", @@ -173,16 +181,15 @@ For the compatible string below the following supplies are required: For the compatible strings below the following phandle references are required: "qcom,sc7180-mss-pil" -- qcom,halt-nav-regs: +- qcom,spare-regs: Usage: required Value type: <prop-encoded-array> - Definition: reference to a list of 2 phandles with one offset each for - the modem sub-system running on SC7180 SoC. The first - phandle reference is to the mss clock node followed by the - offset within register space for nav halt register. The - second phandle reference is to a syscon representing TCSR - followed by the offset within syscon for conn_box_spare0 - register. + Definition: a phandle reference to a syscon representing TCSR followed + by the offset within syscon for conn_box_spare0 register + used by the modem sub-system running on SC7180 SoC. + +The Hexagon node must contain iommus property as described in ../iommu/iommu.txt +on platforms which do not have TrustZone. = SUBNODES: The Hexagon node must contain two subnodes, named "mba" and "mpss" representing diff --git a/Documentation/devicetree/bindings/rng/arm-cctrng.yaml b/Documentation/devicetree/bindings/rng/arm-cctrng.yaml index ca6aad19b6ba..c471e4c10558 100644 --- a/Documentation/devicetree/bindings/rng/arm-cctrng.yaml +++ b/Documentation/devicetree/bindings/rng/arm-cctrng.yaml @@ -28,10 +28,8 @@ properties: description: Arm TrustZone CryptoCell TRNG engine has 4 ring oscillators. Sampling ratio values for these 4 ring oscillators. (from calibration) - allOf: - - $ref: /schemas/types.yaml#/definitions/uint32-array - - items: - maxItems: 4 + $ref: /schemas/types.yaml#/definitions/uint32-array + maxItems: 4 clocks: maxItems: 1 diff --git a/Documentation/devicetree/bindings/serial/samsung_uart.yaml b/Documentation/devicetree/bindings/serial/samsung_uart.yaml index 32a5e1e30833..96414ac65d06 100644 --- a/Documentation/devicetree/bindings/serial/samsung_uart.yaml +++ b/Documentation/devicetree/bindings/serial/samsung_uart.yaml @@ -33,9 +33,8 @@ properties: description: | The size (in bytes) of the IO accesses that should be performed on the device. - allOf: - - $ref: /schemas/types.yaml#/definitions/uint32 - - enum: [ 1, 4 ] + $ref: /schemas/types.yaml#/definitions/uint32 + enum: [ 1, 4 ] clocks: minItems: 2 diff --git a/Documentation/devicetree/bindings/soc/qcom/qcom,geni-se.yaml b/Documentation/devicetree/bindings/soc/qcom/qcom,geni-se.yaml index dee8bb2b69fe..a2b29cc3e93b 100644 --- a/Documentation/devicetree/bindings/soc/qcom/qcom,geni-se.yaml +++ b/Documentation/devicetree/bindings/soc/qcom/qcom,geni-se.yaml @@ -100,8 +100,7 @@ patternProperties: supports up to 50MHz, up to four chip selects, programmable data path from 4 bits to 32 bits and numerous protocol variants. - allOf: - - $ref: /spi/spi-controller.yaml# + $ref: /spi/spi-controller.yaml# properties: compatible: @@ -126,8 +125,7 @@ patternProperties: "i2c@[0-9a-f]+$": type: object description: GENI serial engine based I2C controller. - allOf: - - $ref: /schemas/i2c/i2c-controller.yaml# + $ref: /schemas/i2c/i2c-controller.yaml# properties: compatible: @@ -156,8 +154,7 @@ patternProperties: "serial@[0-9a-f]+$": type: object description: GENI Serial Engine based UART Controller. - allOf: - - $ref: /schemas/serial.yaml# + $ref: /schemas/serial.yaml# properties: compatible: diff --git a/Documentation/devicetree/bindings/sound/fsl,easrc.yaml b/Documentation/devicetree/bindings/sound/fsl,easrc.yaml index 73cdcf053a9c..32d547af9ce7 100644 --- a/Documentation/devicetree/bindings/sound/fsl,easrc.yaml +++ b/Documentation/devicetree/bindings/sound/fsl,easrc.yaml @@ -45,23 +45,20 @@ properties: - const: ctx3_tx firmware-name: - allOf: - - $ref: /schemas/types.yaml#/definitions/string - - const: imx/easrc/easrc-imx8mn.bin + $ref: /schemas/types.yaml#/definitions/string + const: imx/easrc/easrc-imx8mn.bin description: The coefficient table for the filters fsl,asrc-rate: - allOf: - - $ref: /schemas/types.yaml#/definitions/uint32 - - minimum: 8000 - - maximum: 192000 + $ref: /schemas/types.yaml#/definitions/uint32 + minimum: 8000 + maximum: 192000 description: Defines a mutual sample rate used by DPCM Back Ends fsl,asrc-format: - allOf: - - $ref: /schemas/types.yaml#/definitions/uint32 - - enum: [2, 6, 10, 32, 36] - default: 2 + $ref: /schemas/types.yaml#/definitions/uint32 + enum: [2, 6, 10, 32, 36] + default: 2 description: Defines a mutual sample format used by DPCM Back Ends @@ -83,7 +80,7 @@ examples: easrc: easrc@300c0000 { compatible = "fsl,imx8mn-easrc"; - reg = <0x0 0x300c0000 0x0 0x10000>; + reg = <0x300c0000 0x10000>; interrupts = <0x0 122 0x4>; clocks = <&clk IMX8MN_CLK_ASRC_ROOT>; clock-names = "mem"; diff --git a/Documentation/devicetree/bindings/sound/simple-card.yaml b/Documentation/devicetree/bindings/sound/simple-card.yaml index cb2bb5fac0e1..8132d0c0f00a 100644 --- a/Documentation/devicetree/bindings/sound/simple-card.yaml +++ b/Documentation/devicetree/bindings/sound/simple-card.yaml @@ -13,15 +13,13 @@ definitions: frame-master: description: Indicates dai-link frame master. - allOf: - - $ref: /schemas/types.yaml#/definitions/phandle-array - - maxItems: 1 + $ref: /schemas/types.yaml#/definitions/phandle-array + maxItems: 1 bitclock-master: description: Indicates dai-link bit clock master - allOf: - - $ref: /schemas/types.yaml#/definitions/phandle-array - - maxItems: 1 + $ref: /schemas/types.yaml#/definitions/phandle-array + maxItems: 1 frame-inversion: description: dai-link uses frame clock inversion diff --git a/Documentation/devicetree/bindings/sound/tdm-slot.txt b/Documentation/devicetree/bindings/sound/tdm-slot.txt index 34cf70e2cbc4..4bb513ae62fc 100644 --- a/Documentation/devicetree/bindings/sound/tdm-slot.txt +++ b/Documentation/devicetree/bindings/sound/tdm-slot.txt @@ -14,8 +14,8 @@ For instance: dai-tdm-slot-tx-mask = <0 1>; dai-tdm-slot-rx-mask = <1 0>; -And for each spcified driver, there could be one .of_xlate_tdm_slot_mask() -to specify a explicit mapping of the channels and the slots. If it's absent +And for each specified driver, there could be one .of_xlate_tdm_slot_mask() +to specify an explicit mapping of the channels and the slots. If it's absent the default snd_soc_of_xlate_tdm_slot_mask() will be used to generating the tx and rx masks. diff --git a/Documentation/devicetree/bindings/sound/tlv320adcx140.yaml b/Documentation/devicetree/bindings/sound/tlv320adcx140.yaml index c5b5b4260496..2e6ac5d2ee96 100644 --- a/Documentation/devicetree/bindings/sound/tlv320adcx140.yaml +++ b/Documentation/devicetree/bindings/sound/tlv320adcx140.yaml @@ -76,13 +76,12 @@ properties: PDMIN3 - PDMCLK latching edge used for channel 5 and 6 data PDMIN4 - PDMCLK latching edge used for channel 7 and 8 data - allOf: - - $ref: /schemas/types.yaml#/definitions/uint32-array - - minItems: 1 - maxItems: 4 - items: - maximum: 1 - default: [0, 0, 0, 0] + $ref: /schemas/types.yaml#/definitions/uint32-array + minItems: 1 + maxItems: 4 + items: + maximum: 1 + default: [0, 0, 0, 0] ti,gpi-config: description: | @@ -102,13 +101,12 @@ properties: 7 - GPIX is configured as a PDM data input for channel 7 and channel (PDMDIN4) - allOf: - - $ref: /schemas/types.yaml#/definitions/uint32-array - - minItems: 1 - maxItems: 4 - items: - maximum: 7 - default: [0, 0, 0, 0] + $ref: /schemas/types.yaml#/definitions/uint32-array + minItems: 1 + maxItems: 4 + items: + maximum: 7 + default: [0, 0, 0, 0] required: - compatible diff --git a/Documentation/devicetree/bindings/thermal/socionext,uniphier-thermal.yaml b/Documentation/devicetree/bindings/thermal/socionext,uniphier-thermal.yaml index bb9594bb2cf1..553c9dcdaeeb 100644 --- a/Documentation/devicetree/bindings/thermal/socionext,uniphier-thermal.yaml +++ b/Documentation/devicetree/bindings/thermal/socionext,uniphier-thermal.yaml @@ -28,9 +28,8 @@ properties: const: 0 socionext,tmod-calibration: - allOf: - - $ref: /schemas/types.yaml#/definitions/uint32-array - - maxItems: 2 + $ref: /schemas/types.yaml#/definitions/uint32-array + maxItems: 2 description: A pair of calibrated values referred from PVT, in case that the values aren't set on SoC, like a reference board. diff --git a/Documentation/devicetree/bindings/thermal/thermal-cooling-devices.yaml b/Documentation/devicetree/bindings/thermal/thermal-cooling-devices.yaml new file mode 100644 index 000000000000..5145883d932e --- /dev/null +++ b/Documentation/devicetree/bindings/thermal/thermal-cooling-devices.yaml @@ -0,0 +1,116 @@ +# SPDX-License-Identifier: (GPL-2.0) +# Copyright 2020 Linaro Ltd. +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/thermal/thermal-cooling-devices.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Thermal cooling device binding + +maintainers: + - Amit Kucheria <amitk@kernel.org> + +description: | + Thermal management is achieved in devicetree by describing the sensor hardware + and the software abstraction of cooling devices and thermal zones required to + take appropriate action to mitigate thermal overload. + + The following node types are used to completely describe a thermal management + system in devicetree: + - thermal-sensor: device that measures temperature, has SoC-specific bindings + - cooling-device: device used to dissipate heat either passively or actively + - thermal-zones: a container of the following node types used to describe all + thermal data for the platform + + This binding describes the cooling devices. + + There are essentially two ways to provide control on power dissipation: + - Passive cooling: by means of regulating device performance. A typical + passive cooling mechanism is a CPU that has dynamic voltage and frequency + scaling (DVFS), and uses lower frequencies as cooling states. + - Active cooling: by means of activating devices in order to remove the + dissipated heat, e.g. regulating fan speeds. + + Any cooling device has a range of cooling states (i.e. different levels of + heat dissipation). They also have a way to determine the state of cooling in + which the device is. For example, a fan's cooling states correspond to the + different fan speeds possible. Cooling states are referred to by single + unsigned integers, where larger numbers mean greater heat dissipation. The + precise set of cooling states associated with a device should be defined in + a particular device's binding. + +select: true + +properties: + "#cooling-cells": + description: + Must be 2, in order to specify minimum and maximum cooling state used in + the cooling-maps reference. The first cell is the minimum cooling state + and the second cell is the maximum cooling state requested. + const: 2 + +examples: + - | + #include <dt-bindings/interrupt-controller/arm-gic.h> + #include <dt-bindings/thermal/thermal.h> + + // Example 1: Cpufreq cooling device on CPU0 + cpus { + #address-cells = <2>; + #size-cells = <0>; + + CPU0: cpu@0 { + device_type = "cpu"; + compatible = "qcom,kryo385"; + reg = <0x0 0x0>; + enable-method = "psci"; + cpu-idle-states = <&LITTLE_CPU_SLEEP_0 + &LITTLE_CPU_SLEEP_1 + &CLUSTER_SLEEP_0>; + capacity-dmips-mhz = <607>; + dynamic-power-coefficient = <100>; + qcom,freq-domain = <&cpufreq_hw 0>; + #cooling-cells = <2>; + next-level-cache = <&L2_0>; + L2_0: l2-cache { + compatible = "cache"; + next-level-cache = <&L3_0>; + L3_0: l3-cache { + compatible = "cache"; + }; + }; + }; + + /* ... */ + + }; + + /* ... */ + + thermal-zones { + cpu0-thermal { + polling-delay-passive = <250>; + polling-delay = <1000>; + + thermal-sensors = <&tsens0 1>; + + trips { + cpu0_alert0: trip-point0 { + temperature = <90000>; + hysteresis = <2000>; + type = "passive"; + }; + }; + + cooling-maps { + map0 { + trip = <&cpu0_alert0>; + /* Corresponds to 1000MHz in OPP table */ + cooling-device = <&CPU0 5 5>; + }; + }; + }; + + /* ... */ + }; +... diff --git a/Documentation/devicetree/bindings/thermal/thermal-idle.yaml b/Documentation/devicetree/bindings/thermal/thermal-idle.yaml new file mode 100644 index 000000000000..7a922f540934 --- /dev/null +++ b/Documentation/devicetree/bindings/thermal/thermal-idle.yaml @@ -0,0 +1,145 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +# Copyright 2020 Linaro Ltd. +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/thermal/thermal-idle.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Thermal idle cooling device binding + +maintainers: + - Daniel Lezcano <daniel.lezcano@linaro.org> + +description: | + The thermal idle cooling device allows the system to passively + mitigate the temperature on the device by injecting idle cycles, + forcing it to cool down. + + This binding describes the thermal idle node. + +properties: + $nodename: + const: thermal-idle + description: | + A thermal-idle node describes the idle cooling device properties to + cool down efficiently the attached thermal zone. + + '#cooling-cells': + const: 2 + description: | + Must be 2, in order to specify minimum and maximum cooling state used in + the cooling-maps reference. The first cell is the minimum cooling state + and the second cell is the maximum cooling state requested. + + duration-us: + description: | + The idle duration in microsecond the device should cool down. + + exit-latency-us: + description: | + The exit latency constraint in microsecond for the injected + idle state for the device. It is the latency constraint to + apply when selecting an idle state from among all the present + ones. + +required: + - '#cooling-cells' + +examples: + - | + #include <dt-bindings/thermal/thermal.h> + + // Example: Combining idle cooling device on big CPUs with cpufreq cooling device + cpus { + #address-cells = <2>; + #size-cells = <0>; + + /* ... */ + + cpu_b0: cpu@100 { + device_type = "cpu"; + compatible = "arm,cortex-a72"; + reg = <0x0 0x100>; + enable-method = "psci"; + capacity-dmips-mhz = <1024>; + dynamic-power-coefficient = <436>; + #cooling-cells = <2>; /* min followed by max */ + cpu-idle-states = <&CPU_SLEEP &CLUSTER_SLEEP>; + thermal-idle { + #cooling-cells = <2>; + duration-us = <10000>; + exit-latency-us = <500>; + }; + }; + + cpu_b1: cpu@101 { + device_type = "cpu"; + compatible = "arm,cortex-a72"; + reg = <0x0 0x101>; + enable-method = "psci"; + capacity-dmips-mhz = <1024>; + dynamic-power-coefficient = <436>; + #cooling-cells = <2>; /* min followed by max */ + cpu-idle-states = <&CPU_SLEEP &CLUSTER_SLEEP>; + thermal-idle { + #cooling-cells = <2>; + duration-us = <10000>; + exit-latency-us = <500>; + }; + }; + + /* ... */ + + }; + + /* ... */ + + thermal_zones { + cpu_thermal: cpu { + polling-delay-passive = <100>; + polling-delay = <1000>; + + /* ... */ + + trips { + cpu_alert0: cpu_alert0 { + temperature = <65000>; + hysteresis = <2000>; + type = "passive"; + }; + + cpu_alert1: cpu_alert1 { + temperature = <70000>; + hysteresis = <2000>; + type = "passive"; + }; + + cpu_alert2: cpu_alert2 { + temperature = <75000>; + hysteresis = <2000>; + type = "passive"; + }; + + cpu_crit: cpu_crit { + temperature = <95000>; + hysteresis = <2000>; + type = "critical"; + }; + }; + + cooling-maps { + map0 { + trip = <&cpu_alert1>; + cooling-device = <&{/cpus/cpu@100/thermal-idle} 0 15 >, + <&{/cpus/cpu@101/thermal-idle} 0 15>; + }; + + map1 { + trip = <&cpu_alert2>; + cooling-device = + <&cpu_b0 THERMAL_NO_LIMIT THERMAL_NO_LIMIT>, + <&cpu_b1 THERMAL_NO_LIMIT THERMAL_NO_LIMIT>; + }; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/thermal/thermal-sensor.yaml b/Documentation/devicetree/bindings/thermal/thermal-sensor.yaml new file mode 100644 index 000000000000..fcd25a0af38c --- /dev/null +++ b/Documentation/devicetree/bindings/thermal/thermal-sensor.yaml @@ -0,0 +1,72 @@ +# SPDX-License-Identifier: (GPL-2.0) +# Copyright 2020 Linaro Ltd. +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/thermal/thermal-sensor.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Thermal sensor binding + +maintainers: + - Amit Kucheria <amitk@kernel.org> + +description: | + Thermal management is achieved in devicetree by describing the sensor hardware + and the software abstraction of thermal zones required to take appropriate + action to mitigate thermal overloads. + + The following node types are used to completely describe a thermal management + system in devicetree: + - thermal-sensor: device that measures temperature, has SoC-specific bindings + - cooling-device: device used to dissipate heat either passively or actively + - thermal-zones: a container of the following node types used to describe all + thermal data for the platform + + This binding describes the thermal-sensor. + + Thermal sensor devices provide temperature sensing capabilities on thermal + zones. Typical devices are I2C ADC converters and bandgaps. Thermal sensor + devices may control one or more internal sensors. + +properties: + "#thermal-sensor-cells": + description: + Used to uniquely identify a thermal sensor instance within an IC. Will be + 0 on sensor nodes with only a single sensor and at least 1 on nodes + containing several internal sensors. + enum: [0, 1] + +examples: + - | + #include <dt-bindings/interrupt-controller/arm-gic.h> + + // Example 1: SDM845 TSENS + soc: soc@0 { + #address-cells = <2>; + #size-cells = <2>; + + /* ... */ + + tsens0: thermal-sensor@c263000 { + compatible = "qcom,sdm845-tsens", "qcom,tsens-v2"; + reg = <0 0x0c263000 0 0x1ff>, /* TM */ + <0 0x0c222000 0 0x1ff>; /* SROT */ + #qcom,sensors = <13>; + interrupts = <GIC_SPI 506 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 508 IRQ_TYPE_LEVEL_HIGH>; + interrupt-names = "uplow", "critical"; + #thermal-sensor-cells = <1>; + }; + + tsens1: thermal-sensor@c265000 { + compatible = "qcom,sdm845-tsens", "qcom,tsens-v2"; + reg = <0 0x0c265000 0 0x1ff>, /* TM */ + <0 0x0c223000 0 0x1ff>; /* SROT */ + #qcom,sensors = <8>; + interrupts = <GIC_SPI 507 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 509 IRQ_TYPE_LEVEL_HIGH>; + interrupt-names = "uplow", "critical"; + #thermal-sensor-cells = <1>; + }; + }; +... diff --git a/Documentation/devicetree/bindings/thermal/thermal-zones.yaml b/Documentation/devicetree/bindings/thermal/thermal-zones.yaml new file mode 100644 index 000000000000..b8515d3eeaa2 --- /dev/null +++ b/Documentation/devicetree/bindings/thermal/thermal-zones.yaml @@ -0,0 +1,341 @@ +# SPDX-License-Identifier: (GPL-2.0) +# Copyright 2020 Linaro Ltd. +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/thermal/thermal-zones.yaml# +$schema: http://devicetree.org/meta-schemas/base.yaml# + +title: Thermal zone binding + +maintainers: + - Amit Kucheria <amitk@kernel.org> + +description: | + Thermal management is achieved in devicetree by describing the sensor hardware + and the software abstraction of cooling devices and thermal zones required to + take appropriate action to mitigate thermal overloads. + + The following node types are used to completely describe a thermal management + system in devicetree: + - thermal-sensor: device that measures temperature, has SoC-specific bindings + - cooling-device: device used to dissipate heat either passively or actively + - thermal-zones: a container of the following node types used to describe all + thermal data for the platform + + This binding describes the thermal-zones. + + The polling-delay properties of a thermal-zone are bound to the maximum dT/dt + (temperature derivative over time) in two situations for a thermal zone: + 1. when passive cooling is activated (polling-delay-passive) + 2. when the zone just needs to be monitored (polling-delay) or when + active cooling is activated. + + The maximum dT/dt is highly bound to hardware power consumption and + dissipation capability. The delays should be chosen to account for said + max dT/dt, such that a device does not cross several trip boundaries + unexpectedly between polls. Choosing the right polling delays shall avoid + having the device in temperature ranges that may damage the silicon structures + and reduce silicon lifetime. + +properties: + $nodename: + const: thermal-zones + description: + A /thermal-zones node is required in order to use the thermal framework to + manage input from the various thermal zones in the system in order to + mitigate thermal overload conditions. It does not represent a real device + in the system, but acts as a container to link a thermal sensor device, + platform-data regarding temperature thresholds and the mitigation actions + to take when the temperature crosses those thresholds. + +patternProperties: + "^[a-zA-Z][a-zA-Z0-9\\-]{1,12}-thermal$": + type: object + description: + Each thermal zone node contains information about how frequently it + must be checked, the sensor responsible for reporting temperature for + this zone, one sub-node containing the various trip points for this + zone and one sub-node containing all the zone cooling-maps. + + properties: + polling-delay: + $ref: /schemas/types.yaml#/definitions/uint32 + description: + The maximum number of milliseconds to wait between polls when + checking this thermal zone. Setting this to 0 disables the polling + timers setup by the thermal framework and assumes that the thermal + sensors in this zone support interrupts. + + polling-delay-passive: + $ref: /schemas/types.yaml#/definitions/uint32 + description: + The maximum number of milliseconds to wait between polls when + checking this thermal zone while doing passive cooling. Setting + this to 0 disables the polling timers setup by the thermal + framework and assumes that the thermal sensors in this zone + support interrupts. + + thermal-sensors: + $ref: /schemas/types.yaml#/definitions/phandle-array + maxItems: 1 + description: + The thermal sensor phandle and sensor specifier used to monitor this + thermal zone. + + coefficients: + $ref: /schemas/types.yaml#/definitions/uint32-array + description: + An array of integers containing the coefficients of a linear equation + that binds all the sensors listed in this thermal zone. + + The linear equation used is as follows, + z = c0 * x0 + c1 * x1 + ... + c(n-1) * x(n-1) + cn + where c0, c1, .., cn are the coefficients. + + Coefficients default to 1 in case this property is not specified. The + coefficients are ordered and are matched with sensors by means of the + sensor ID. Additional coefficients are interpreted as constant offset. + + sustainable-power: + $ref: /schemas/types.yaml#/definitions/uint32 + description: + An estimate of the sustainable power (in mW) that this thermal zone + can dissipate at the desired control temperature. For reference, the + sustainable power of a 4-inch phone is typically 2000mW, while on a + 10-inch tablet is around 4500mW. + + trips: + type: object + description: + This node describes a set of points in the temperature domain at + which the thermal framework needs to take action. The actions to + be taken are defined in another node called cooling-maps. + + patternProperties: + "^[a-zA-Z][a-zA-Z0-9\\-_]{0,63}$": + type: object + + properties: + temperature: + $ref: /schemas/types.yaml#/definitions/int32 + minimum: -273000 + maximum: 200000 + description: + An integer expressing the trip temperature in millicelsius. + + hysteresis: + $ref: /schemas/types.yaml#/definitions/uint32 + description: + An unsigned integer expressing the hysteresis delta with + respect to the trip temperature property above, also in + millicelsius. Any cooling action initiated by the framework is + maintained until the temperature falls below + (trip temperature - hysteresis). This potentially prevents a + situation where the trip gets constantly triggered soon after + cooling action is removed. + + type: + $ref: /schemas/types.yaml#/definitions/string + enum: + - active # enable active cooling e.g. fans + - passive # enable passive cooling e.g. throttling cpu + - hot # send notification to driver + - critical # send notification to driver, trigger shutdown + description: | + There are four valid trip types: active, passive, hot, + critical. + + The critical trip type is used to set the maximum + temperature threshold above which the HW becomes + unstable and underlying firmware might even trigger a + reboot. Hitting the critical threshold triggers a system + shutdown. + + The hot trip type can be used to send a notification to + the thermal driver (if a .notify callback is registered). + The action to be taken is left to the driver. + + The passive trip type can be used to slow down HW e.g. run + the CPU, GPU, bus at a lower frequency. + + The active trip type can be used to control other HW to + help in cooling e.g. fans can be sped up or slowed down + + required: + - temperature + - hysteresis + - type + additionalProperties: false + + additionalProperties: false + + cooling-maps: + type: object + description: + This node describes the action to be taken when a thermal zone + crosses one of the temperature thresholds described in the trips + node. The action takes the form of a mapping relation between a + trip and the target cooling device state. + + patternProperties: + "^map[-a-zA-Z0-9]*$": + type: object + + properties: + trip: + $ref: /schemas/types.yaml#/definitions/phandle + description: + A phandle of a trip point node within this thermal zone. + + cooling-device: + $ref: /schemas/types.yaml#/definitions/phandle-array + description: + A list of cooling device phandles along with the minimum + and maximum cooling state specifiers for each cooling + device. Using the THERMAL_NO_LIMIT (-1UL) constant in the + cooling-device phandle limit specifier lets the framework + use the minimum and maximum cooling state for that cooling + device automatically. + + contribution: + $ref: /schemas/types.yaml#/definitions/uint32 + minimum: 0 + maximum: 100 + description: + The percentage contribution of the cooling devices at the + specific trip temperature referenced in this map + to this thermal zone + + required: + - trip + - cooling-device + additionalProperties: false + + required: + - polling-delay + - polling-delay-passive + - thermal-sensors + - trips + additionalProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/arm-gic.h> + #include <dt-bindings/thermal/thermal.h> + + // Example 1: SDM845 TSENS + soc: soc@0 { + #address-cells = <2>; + #size-cells = <2>; + + /* ... */ + + tsens0: thermal-sensor@c263000 { + compatible = "qcom,sdm845-tsens", "qcom,tsens-v2"; + reg = <0 0x0c263000 0 0x1ff>, /* TM */ + <0 0x0c222000 0 0x1ff>; /* SROT */ + #qcom,sensors = <13>; + interrupts = <GIC_SPI 506 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 508 IRQ_TYPE_LEVEL_HIGH>; + interrupt-names = "uplow", "critical"; + #thermal-sensor-cells = <1>; + }; + + tsens1: thermal-sensor@c265000 { + compatible = "qcom,sdm845-tsens", "qcom,tsens-v2"; + reg = <0 0x0c265000 0 0x1ff>, /* TM */ + <0 0x0c223000 0 0x1ff>; /* SROT */ + #qcom,sensors = <8>; + interrupts = <GIC_SPI 507 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 509 IRQ_TYPE_LEVEL_HIGH>; + interrupt-names = "uplow", "critical"; + #thermal-sensor-cells = <1>; + }; + }; + + /* ... */ + + thermal-zones { + cpu0-thermal { + polling-delay-passive = <250>; + polling-delay = <1000>; + + thermal-sensors = <&tsens0 1>; + + trips { + cpu0_alert0: trip-point0 { + temperature = <90000>; + hysteresis = <2000>; + type = "passive"; + }; + + cpu0_alert1: trip-point1 { + temperature = <95000>; + hysteresis = <2000>; + type = "passive"; + }; + + cpu0_crit: cpu_crit { + temperature = <110000>; + hysteresis = <1000>; + type = "critical"; + }; + }; + + cooling-maps { + map0 { + trip = <&cpu0_alert0>; + /* Corresponds to 1400MHz in OPP table */ + cooling-device = <&CPU0 3 3>, <&CPU1 3 3>, + <&CPU2 3 3>, <&CPU3 3 3>; + }; + + map1 { + trip = <&cpu0_alert1>; + /* Corresponds to 1000MHz in OPP table */ + cooling-device = <&CPU0 5 5>, <&CPU1 5 5>, + <&CPU2 5 5>, <&CPU3 5 5>; + }; + }; + }; + + /* ... */ + + cluster0-thermal { + polling-delay-passive = <250>; + polling-delay = <1000>; + + thermal-sensors = <&tsens0 5>; + + trips { + cluster0_alert0: trip-point0 { + temperature = <90000>; + hysteresis = <2000>; + type = "hot"; + }; + cluster0_crit: cluster0_crit { + temperature = <110000>; + hysteresis = <2000>; + type = "critical"; + }; + }; + }; + + /* ... */ + + gpu-top-thermal { + polling-delay-passive = <250>; + polling-delay = <1000>; + + thermal-sensors = <&tsens0 11>; + + trips { + gpu1_alert0: trip-point0 { + temperature = <90000>; + hysteresis = <2000>; + type = "hot"; + }; + }; + }; + }; +... diff --git a/Documentation/devicetree/bindings/thermal/ti,am654-thermal.yaml b/Documentation/devicetree/bindings/thermal/ti,am654-thermal.yaml new file mode 100644 index 000000000000..25b9209c2e5d --- /dev/null +++ b/Documentation/devicetree/bindings/thermal/ti,am654-thermal.yaml @@ -0,0 +1,56 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/thermal/ti,am654-thermal.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Texas Instruments AM654 VTM (DTS) binding + +maintainers: + - Keerthy <j-keerthy@ti.com> + +properties: + compatible: + const: ti,am654-vtm + + reg: + maxItems: 1 + + power-domains: + maxItems: 1 + + "#thermal-sensor-cells": + const: 1 + +required: + - compatible + - reg + - power-domains + - "#thermal-sensor-cells" + +additionalProperties: false + +examples: + - | + #include <dt-bindings/soc/ti,sci_pm_domain.h> + vtm: thermal@42050000 { + compatible = "ti,am654-vtm"; + reg = <0x0 0x42050000 0x0 0x25c>; + power-domains = <&k3_pds 80 TI_SCI_PD_EXCLUSIVE>; + #thermal-sensor-cells = <1>; + }; + + mpu0_thermal: mpu0_thermal { + polling-delay-passive = <250>; /* milliseconds */ + polling-delay = <500>; /* milliseconds */ + thermal-sensors = <&vtm0 0>; + + trips { + mpu0_crit: mpu0_crit { + temperature = <125000>; /* milliCelsius */ + hysteresis = <2000>; /* milliCelsius */ + type = "critical"; + }; + }; + }; +... diff --git a/Documentation/devicetree/bindings/usb/aspeed,usb-vhub.yaml b/Documentation/devicetree/bindings/usb/aspeed,usb-vhub.yaml index ccc67d03d4bb..e4e83d3971ac 100644 --- a/Documentation/devicetree/bindings/usb/aspeed,usb-vhub.yaml +++ b/Documentation/devicetree/bindings/usb/aspeed,usb-vhub.yaml @@ -52,21 +52,18 @@ properties: vhub-vendor-id: description: vhub Vendor ID - allOf: - - $ref: /schemas/types.yaml#/definitions/uint32 - - maximum: 65535 + $ref: /schemas/types.yaml#/definitions/uint32 + maximum: 65535 vhub-product-id: description: vhub Product ID - allOf: - - $ref: /schemas/types.yaml#/definitions/uint32 - - maximum: 65535 + $ref: /schemas/types.yaml#/definitions/uint32 + maximum: 65535 vhub-device-revision: description: vhub Device Revision in binary-coded decimal - allOf: - - $ref: /schemas/types.yaml#/definitions/uint32 - - maximum: 65535 + $ref: /schemas/types.yaml#/definitions/uint32 + maximum: 65535 vhub-strings: type: object @@ -90,18 +87,15 @@ properties: manufacturer: description: vhub manufacturer - allOf: - - $ref: /schemas/types.yaml#/definitions/string + $ref: /schemas/types.yaml#/definitions/string product: description: vhub product name - allOf: - - $ref: /schemas/types.yaml#/definitions/string + $ref: /schemas/types.yaml#/definitions/string serial-number: description: vhub device serial number - allOf: - - $ref: /schemas/types.yaml#/definitions/string + $ref: /schemas/types.yaml#/definitions/string required: - compatible diff --git a/Documentation/devicetree/bindings/usb/nvidia,tegra-xudc.yaml b/Documentation/devicetree/bindings/usb/nvidia,tegra-xudc.yaml index c4ddc0adf101..0073763a30d8 100644 --- a/Documentation/devicetree/bindings/usb/nvidia,tegra-xudc.yaml +++ b/Documentation/devicetree/bindings/usb/nvidia,tegra-xudc.yaml @@ -64,13 +64,11 @@ properties: - const: hs_src power-domains: - maxItems: 2 items: - description: XUSBB(device) power-domain - description: XUSBA(superspeed) power-domain power-domain-names: - maxItems: 2 items: - const: dev - const: ss diff --git a/Documentation/devicetree/bindings/vendor-prefixes.yaml b/Documentation/devicetree/bindings/vendor-prefixes.yaml index ef6d75b9113a..9aeab66be85f 100644 --- a/Documentation/devicetree/bindings/vendor-prefixes.yaml +++ b/Documentation/devicetree/bindings/vendor-prefixes.yaml @@ -187,6 +187,8 @@ patternProperties: description: Cadence Design Systems Inc. "^cdtech,.*": description: CDTech(H.K.) Electronics Limited + "^cellwise,.*": + description: CellWise Microelectronics Co., Ltd "^ceva,.*": description: Ceva, Inc. "^checkpoint,.*": diff --git a/Documentation/devicetree/bindings/watchdog/arm-smc-wdt.yaml b/Documentation/devicetree/bindings/watchdog/arm-smc-wdt.yaml index bec651541e0c..8e4c7c69bc1c 100644 --- a/Documentation/devicetree/bindings/watchdog/arm-smc-wdt.yaml +++ b/Documentation/devicetree/bindings/watchdog/arm-smc-wdt.yaml @@ -17,8 +17,7 @@ properties: enum: - arm,smc-wdt arm,smc-id: - allOf: - - $ref: /schemas/types.yaml#/definitions/uint32 + $ref: /schemas/types.yaml#/definitions/uint32 description: | The ATF smc function id used by the firmware. Defaults to 0x82003D06 if unset. diff --git a/Documentation/doc-guide/parse-headers.rst b/Documentation/doc-guide/parse-headers.rst index f7135b058246..5da0046f7059 100644 --- a/Documentation/doc-guide/parse-headers.rst +++ b/Documentation/doc-guide/parse-headers.rst @@ -186,7 +186,7 @@ COPYRIGHT Copyright (c) 2016 by Mauro Carvalho Chehab <mchehab+samsung@kernel.org>. -License GPLv2: GNU GPL version 2 <http://gnu.org/licenses/gpl.html>. +License GPLv2: GNU GPL version 2 <https://gnu.org/licenses/gpl.html>. This is free software: you are free to change and redistribute it. There is NO WARRANTY, to the extent permitted by law. diff --git a/Documentation/driver-api/acpi/linuxized-acpica.rst b/Documentation/driver-api/acpi/linuxized-acpica.rst index 0ca8f1538519..6bee03383225 100644 --- a/Documentation/driver-api/acpi/linuxized-acpica.rst +++ b/Documentation/driver-api/acpi/linuxized-acpica.rst @@ -175,9 +175,9 @@ illustrated in the following figure:: B. acpica / master - "master" branch of the git repository at <https://github.com/acpica/acpica.git>. C. linux-pm / linux-next - "linux-next" branch of the git repository at - <http://git.kernel.org/pub/scm/linux/kernel/git/rafael/linux-pm.git>. + <https://git.kernel.org/pub/scm/linux/kernel/git/rafael/linux-pm.git>. D. linux / master - "master" branch of the git repository at - <http://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git>. + <https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git>. Before the linuxized ACPICA patches are sent to the Linux ACPI community for review, there is a quality assurance build test process to reduce @@ -274,6 +274,6 @@ before they become available from the ACPICA release process. a diff file indicating the state of the current divergences:: # git clone https://github.com/acpica/acpica - # git clone http://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git + # git clone https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git # cd acpica # generate/linux/divergences.sh -s ../linux diff --git a/Documentation/driver-api/driver-model/devres.rst b/Documentation/driver-api/driver-model/devres.rst index 644078332354..e0b58c392e4f 100644 --- a/Documentation/driver-api/driver-model/devres.rst +++ b/Documentation/driver-api/driver-model/devres.rst @@ -314,6 +314,7 @@ IOMAP devm_platform_ioremap_resource() : calls devm_ioremap_resource() for platform device devm_platform_ioremap_resource_wc() devm_platform_ioremap_resource_byname() + devm_platform_get_and_ioremap_resource() devm_iounmap() pcim_iomap() pcim_iomap_regions() : do request_region() and iomap() on multiple BARs diff --git a/Documentation/driver-api/media/v4l2-subdev.rst b/Documentation/driver-api/media/v4l2-subdev.rst index 6ced2381952a..6e71f67455bb 100644 --- a/Documentation/driver-api/media/v4l2-subdev.rst +++ b/Documentation/driver-api/media/v4l2-subdev.rst @@ -319,8 +319,7 @@ The device node handles a subset of the V4L2 API. events can also be reported by one (or several) V4L2 device nodes. Sub-device drivers that want to use events need to set the - ``V4L2_SUBDEV_USES_EVENTS`` :c:type:`v4l2_subdev`.flags and initialize - :c:type:`v4l2_subdev`.nevents to events queue depth before registering + ``V4L2_SUBDEV_FL_HAS_EVENTS`` :c:type:`v4l2_subdev`.flags before registering the sub-device. After registration events can be queued as usual on the :c:type:`v4l2_subdev`.devnode device node. diff --git a/Documentation/driver-api/mtdnand.rst b/Documentation/driver-api/mtdnand.rst index 55447659b81f..0bf8d6ec3f54 100644 --- a/Documentation/driver-api/mtdnand.rst +++ b/Documentation/driver-api/mtdnand.rst @@ -276,8 +276,10 @@ unregisters the partitions in the MTD layer. #ifdef MODULE static void __exit board_cleanup (void) { - /* Release resources, unregister device */ - nand_release (mtd_to_nand(board_mtd)); + /* Unregister device */ + WARN_ON(mtd_device_unregister(board_mtd)); + /* Release resources */ + nand_cleanup(mtd_to_nand(board_mtd)); /* unmap physical address */ iounmap(baseaddr); diff --git a/Documentation/driver-api/usb/bulk-streams.rst b/Documentation/driver-api/usb/bulk-streams.rst index 99b515babdeb..eeefe582f8ff 100644 --- a/Documentation/driver-api/usb/bulk-streams.rst +++ b/Documentation/driver-api/usb/bulk-streams.rst @@ -9,9 +9,9 @@ device driver to overload a bulk endpoint so that multiple transfers can be queued at once. Streams are defined in sections 4.4.6.4 and 8.12.1.4 of the Universal Serial Bus -3.0 specification at http://www.usb.org/developers/docs/ The USB Attached SCSI +3.0 specification at https://www.usb.org/developers/docs/ The USB Attached SCSI Protocol, which uses streams to queue multiple SCSI commands, can be found on -the T10 website (http://t10.org/). +the T10 website (https://t10.org/). Device-side implications diff --git a/Documentation/driver-api/usb/writing_musb_glue_layer.rst b/Documentation/driver-api/usb/writing_musb_glue_layer.rst index 5bf7152fd76f..10416cc11cd5 100644 --- a/Documentation/driver-api/usb/writing_musb_glue_layer.rst +++ b/Documentation/driver-api/usb/writing_musb_glue_layer.rst @@ -707,12 +707,12 @@ cheerful guidance and support. Resources ========= -USB Home Page: http://www.usb.org +USB Home Page: https://www.usb.org -linux-usb Mailing List Archives: http://marc.info/?l=linux-usb +linux-usb Mailing List Archives: https://marc.info/?l=linux-usb USB On-the-Go Basics: -http://www.maximintegrated.com/app-notes/index.mvp/id/1822 +https://www.maximintegrated.com/app-notes/index.mvp/id/1822 :ref:`Writing USB Device Drivers <writing-usb-driver>` diff --git a/Documentation/filesystems/f2fs.rst b/Documentation/filesystems/f2fs.rst index 4218ac658629..099d45ac8d8f 100644 --- a/Documentation/filesystems/f2fs.rst +++ b/Documentation/filesystems/f2fs.rst @@ -248,7 +248,7 @@ checkpoint=%s[:%u[%]] Set to "disable" to turn off checkpointing. Set to "enabl would be unusable can be viewed at /sys/fs/f2fs/<disk>/unusable This space is reclaimed once checkpoint=enable. compress_algorithm=%s Control compress algorithm, currently f2fs supports "lzo", - "lz4" and "zstd" algorithm. + "lz4", "zstd" and "lzo-rle" algorithm. compress_log_size=%u Support configuring compress cluster size, the size will be 4KB * (1 << %u), 16KB is minimum size, also it's default size. diff --git a/Documentation/filesystems/gfs2-glocks.txt b/Documentation/filesystems/gfs2-glocks.rst index 7059623635b2..d14f230f0b12 100644 --- a/Documentation/filesystems/gfs2-glocks.txt +++ b/Documentation/filesystems/gfs2-glocks.rst @@ -1,5 +1,8 @@ - Glock internal locking rules - ------------------------------ +.. SPDX-License-Identifier: GPL-2.0 + +============================ +Glock internal locking rules +============================ This documents the basic principles of the glock state machine internals. Each glock (struct gfs2_glock in fs/gfs2/incore.h) @@ -24,24 +27,28 @@ There are three lock states that users of the glock layer can request, namely shared (SH), deferred (DF) and exclusive (EX). Those translate to the following DLM lock modes: -Glock mode | DLM lock mode ------------------------------- - UN | IV/NL Unlocked (no DLM lock associated with glock) or NL - SH | PR (Protected read) - DF | CW (Concurrent write) - EX | EX (Exclusive) +========== ====== ===================================================== +Glock mode DLM lock mode +========== ====== ===================================================== + UN IV/NL Unlocked (no DLM lock associated with glock) or NL + SH PR (Protected read) + DF CW (Concurrent write) + EX EX (Exclusive) +========== ====== ===================================================== Thus DF is basically a shared mode which is incompatible with the "normal" shared lock mode, SH. In GFS2 the DF mode is used exclusively for direct I/O operations. The glocks are basically a lock plus some routines which deal with cache management. The following rules apply for the cache: -Glock mode | Cache data | Cache Metadata | Dirty Data | Dirty Metadata --------------------------------------------------------------------------- - UN | No | No | No | No - SH | Yes | Yes | No | No - DF | No | Yes | No | No - EX | Yes | Yes | Yes | Yes +========== ========== ============== ========== ============== +Glock mode Cache data Cache Metadata Dirty Data Dirty Metadata +========== ========== ============== ========== ============== + UN No No No No + SH Yes Yes No No + DF No Yes No No + EX Yes Yes Yes Yes +========== ========== ============== ========== ============== These rules are implemented using the various glock operations which are defined for each type of glock. Not all types of glocks use @@ -49,21 +56,23 @@ all the modes. Only inode glocks use the DF mode for example. Table of glock operations and per type constants: -Field | Purpose ----------------------------------------------------------------------------- -go_xmote_th | Called before remote state change (e.g. to sync dirty data) -go_xmote_bh | Called after remote state change (e.g. to refill cache) -go_inval | Called if remote state change requires invalidating the cache -go_demote_ok | Returns boolean value of whether its ok to demote a glock - | (e.g. checks timeout, and that there is no cached data) -go_lock | Called for the first local holder of a lock -go_unlock | Called on the final local unlock of a lock -go_dump | Called to print content of object for debugfs file, or on - | error to dump glock to the log. -go_type | The type of the glock, LM_TYPE_..... -go_callback | Called if the DLM sends a callback to drop this lock -go_flags | GLOF_ASPACE is set, if the glock has an address space - | associated with it +============= ============================================================= +Field Purpose +============= ============================================================= +go_xmote_th Called before remote state change (e.g. to sync dirty data) +go_xmote_bh Called after remote state change (e.g. to refill cache) +go_inval Called if remote state change requires invalidating the cache +go_demote_ok Returns boolean value of whether its ok to demote a glock + (e.g. checks timeout, and that there is no cached data) +go_lock Called for the first local holder of a lock +go_unlock Called on the final local unlock of a lock +go_dump Called to print content of object for debugfs file, or on + error to dump glock to the log. +go_type The type of the glock, ``LM_TYPE_*`` +go_callback Called if the DLM sends a callback to drop this lock +go_flags GLOF_ASPACE is set, if the glock has an address space + associated with it +============= ============================================================= The minimum hold time for each lock is the time after a remote lock grant for which we ignore remote demote requests. This is in order to @@ -82,21 +91,25 @@ rather than via the glock. Locking rules for glock operations: -Operation | GLF_LOCK bit lock held | gl_lockref.lock spinlock held -------------------------------------------------------------------------- -go_xmote_th | Yes | No -go_xmote_bh | Yes | No -go_inval | Yes | No -go_demote_ok | Sometimes | Yes -go_lock | Yes | No -go_unlock | Yes | No -go_dump | Sometimes | Yes -go_callback | Sometimes (N/A) | Yes - -N.B. Operations must not drop either the bit lock or the spinlock -if its held on entry. go_dump and do_demote_ok must never block. -Note that go_dump will only be called if the glock's state -indicates that it is caching uptodate data. +============= ====================== ============================= +Operation GLF_LOCK bit lock held gl_lockref.lock spinlock held +============= ====================== ============================= +go_xmote_th Yes No +go_xmote_bh Yes No +go_inval Yes No +go_demote_ok Sometimes Yes +go_lock Yes No +go_unlock Yes No +go_dump Sometimes Yes +go_callback Sometimes (N/A) Yes +============= ====================== ============================= + +.. Note:: + + Operations must not drop either the bit lock or the spinlock + if its held on entry. go_dump and do_demote_ok must never block. + Note that go_dump will only be called if the glock's state + indicates that it is caching uptodate data. Glock locking order within GFS2: @@ -104,7 +117,7 @@ Glock locking order within GFS2: 2. Rename glock (for rename only) 3. Inode glock(s) (Parents before children, inodes at "same level" with same parent in - lock number order) + lock number order) 4. Rgrp glock(s) (for (de)allocation operations) 5. Transaction glock (via gfs2_trans_begin) for non-read operations 6. i_rw_mutex (if required) @@ -117,8 +130,8 @@ determine the lifetime of the inode in question. Locking of inodes is on a per-inode basis. Locking of rgrps is on a per rgrp basis. In general we prefer to lock local locks prior to cluster locks. - Glock Statistics - ------------------ +Glock Statistics +---------------- The stats are divided into two sets: those relating to the super block and those relating to an individual glock. The @@ -173,8 +186,8 @@ we'd like to get a better idea of these timings: 1. To be able to better set the glock "min hold time" 2. To spot performance issues more easily 3. To improve the algorithm for selecting resource groups for -allocation (to base it on lock wait time, rather than blindly -using a "try lock") + allocation (to base it on lock wait time, rather than blindly + using a "try lock") Due to the smoothing action of the updates, a step change in some input quantity being sampled will only fully be taken @@ -195,10 +208,13 @@ as possible. There are always inaccuracies in any measuring system, but I hope this is as accurate as we can reasonably make it. -Per sb stats can be found here: -/sys/kernel/debug/gfs2/<fsname>/sbstats -Per glock stats can be found here: -/sys/kernel/debug/gfs2/<fsname>/glstats +Per sb stats can be found here:: + + /sys/kernel/debug/gfs2/<fsname>/sbstats + +Per glock stats can be found here:: + + /sys/kernel/debug/gfs2/<fsname>/glstats Assuming that debugfs is mounted on /sys/kernel/debug and also that <fsname> is replaced with the name of the gfs2 filesystem @@ -206,14 +222,16 @@ in question. The abbreviations used in the output as are follows: -srtt - Smoothed round trip time for non-blocking dlm requests -srttvar - Variance estimate for srtt -srttb - Smoothed round trip time for (potentially) blocking dlm requests -srttvarb - Variance estimate for srttb -sirt - Smoothed inter-request time (for dlm requests) -sirtvar - Variance estimate for sirt -dlm - Number of dlm requests made (dcnt in glstats file) -queue - Number of glock requests queued (qcnt in glstats file) +========= ================================================================ +srtt Smoothed round trip time for non blocking dlm requests +srttvar Variance estimate for srtt +srttb Smoothed round trip time for (potentially) blocking dlm requests +srttvarb Variance estimate for srttb +sirt Smoothed inter request time (for dlm requests) +sirtvar Variance estimate for sirt +dlm Number of dlm requests made (dcnt in glstats file) +queue Number of glock requests queued (qcnt in glstats file) +========= ================================================================ The sbstats file contains a set of these stats for each glock type (so 8 lines for each type) and for each cpu (one column per cpu). The glstats file contains @@ -224,9 +242,12 @@ The gfs2_glock_lock_time tracepoint prints out the current values of the stats for the glock in question, along with some addition information on each dlm reply that is received: -status - The status of the dlm request -flags - The dlm request flags -tdiff - The time taken by this specific request +====== ======================================= +status The status of the dlm request +flags The dlm request flags +tdiff The time taken by this specific request +====== ======================================= + (remaining fields as per above list) diff --git a/Documentation/filesystems/index.rst b/Documentation/filesystems/index.rst index 17795341e0a3..4c536e66dc4c 100644 --- a/Documentation/filesystems/index.rst +++ b/Documentation/filesystems/index.rst @@ -88,6 +88,7 @@ Documentation for filesystem implementations. f2fs gfs2 gfs2-uevents + gfs2-glocks hfs hfsplus hpfs diff --git a/Documentation/filesystems/locking.rst b/Documentation/filesystems/locking.rst index 0af2e0e11461..318605de83f3 100644 --- a/Documentation/filesystems/locking.rst +++ b/Documentation/filesystems/locking.rst @@ -429,6 +429,7 @@ prototypes:: int (*lm_grant)(struct file_lock *, struct file_lock *, int); void (*lm_break)(struct file_lock *); /* break_lease callback */ int (*lm_change)(struct file_lock **, int); + bool (*lm_breaker_owns_lease)(struct file_lock *); locking rules: @@ -439,6 +440,7 @@ lm_notify: yes yes no lm_grant: no no no lm_break: yes no no lm_change yes no no +lm_breaker_owns_lease: no no no ========== ============= ================= ========= buffer_head @@ -615,7 +617,7 @@ prototypes:: locking rules: ============= ======== =========================== -ops mmap_sem PageLocked(page) +ops mmap_lock PageLocked(page) ============= ======== =========================== open: yes close: yes diff --git a/Documentation/filesystems/overlayfs.rst b/Documentation/filesystems/overlayfs.rst index c9d2bf96b02d..660dbaf0b9b8 100644 --- a/Documentation/filesystems/overlayfs.rst +++ b/Documentation/filesystems/overlayfs.rst @@ -365,8 +365,8 @@ pointed by REDIRECT. This should not be possible on local system as setting "trusted." xattrs will require CAP_SYS_ADMIN. But it should be possible for untrusted layers like from a pen drive. -Note: redirect_dir={off|nofollow|follow[*]} conflicts with metacopy=on, and -results in an error. +Note: redirect_dir={off|nofollow|follow[*]} and nfs_export=on mount options +conflict with metacopy=on, and will result in an error. [*] redirect_dir=follow only conflicts with metacopy=on if upperdir=... is given. @@ -560,6 +560,9 @@ When the NFS export feature is enabled, all directory index entries are verified on mount time to check that upper file handles are not stale. This verification may cause significant overhead in some cases. +Note: the mount options index=off,nfs_export=on are conflicting and will +result in an error. + Testsuite --------- diff --git a/Documentation/filesystems/path-lookup.txt b/Documentation/filesystems/path-lookup.txt index 9b8930f589d9..1aa7ce099f6f 100644 --- a/Documentation/filesystems/path-lookup.txt +++ b/Documentation/filesystems/path-lookup.txt @@ -375,7 +375,7 @@ common path elements, the more likely they will exist in dentry cache. Papers and other documentation on dcache locking ================================================ -1. Scaling dcache with RCU (http://linuxjournal.com/article.php?sid=7124). +1. Scaling dcache with RCU (https://linuxjournal.com/article.php?sid=7124). 2. http://lse.sourceforge.net/locking/dcache/dcache.html diff --git a/Documentation/filesystems/porting.rst b/Documentation/filesystems/porting.rst index 26c093969573..867036aa90b8 100644 --- a/Documentation/filesystems/porting.rst +++ b/Documentation/filesystems/porting.rst @@ -858,3 +858,10 @@ be misspelled d_alloc_anon(). [should've been added in 2016] stale comment in finish_open() nonwithstanding, failure exits in ->atomic_open() instances should *NOT* fput() the file, no matter what. Everything is handled by the caller. + +--- + +**mandatory** + +clone_private_mount() returns a longterm mount now, so the proper destructor of +its result is kern_unmount() or kern_unmount_array(). diff --git a/Documentation/filesystems/seq_file.rst b/Documentation/filesystems/seq_file.rst index fab302046b13..7f7ee06b2693 100644 --- a/Documentation/filesystems/seq_file.rst +++ b/Documentation/filesystems/seq_file.rst @@ -7,7 +7,7 @@ The seq_file Interface Copyright 2003 Jonathan Corbet <corbet@lwn.net> This file is originally from the LWN.net Driver Porting series at - http://lwn.net/Articles/driver-porting/ + https://lwn.net/Articles/driver-porting/ There are numerous ways for a device driver (or other kernel component) to @@ -57,7 +57,7 @@ Then concatenate the output files out1 and out2 and get the right result. Yes, it is a thoroughly useless module, but the point is to show how the mechanism works without getting lost in other details. (Those wanting to see the full source for this module can find it at -http://lwn.net/Articles/22359/). +https://lwn.net/Articles/22359/). Deprecated create_proc_entry ============================ diff --git a/Documentation/filesystems/virtiofs.rst b/Documentation/filesystems/virtiofs.rst index e06e4951cb39..fd4d2484e949 100644 --- a/Documentation/filesystems/virtiofs.rst +++ b/Documentation/filesystems/virtiofs.rst @@ -39,6 +39,20 @@ Mount file system with tag ``myfs`` on ``/mnt``: Please see https://virtio-fs.gitlab.io/ for details on how to configure QEMU and the virtiofsd daemon. +Mount options +------------- + +virtiofs supports general VFS mount options, for example, remount, +ro, rw, context, etc. It also supports FUSE mount options. + +atime behavior +^^^^^^^^^^^^^^ + +The atime-related mount options, for example, noatime, strictatime, +are ignored. The atime behavior for virtiofs is the same as the +underlying filesystem of the directory that has been exported +on the host. + Internals ========= Since the virtio-fs device uses the FUSE protocol for file system requests, the diff --git a/Documentation/lzo.txt b/Documentation/lzo.txt index ca983328976b..f65b51523014 100644 --- a/Documentation/lzo.txt +++ b/Documentation/lzo.txt @@ -159,11 +159,15 @@ Byte sequences distance = 16384 + (H << 14) + D state = S (copy S literals after this block) End of stream is reached if distance == 16384 + In version 1 only, to prevent ambiguity with the RLE case when + ((distance & 0x803f) == 0x803f) && (261 <= length <= 264), the + compressor must not emit block copies where distance and length + meet these conditions. In version 1 only, this instruction is also used to encode a run of - zeros if distance = 0xbfff, i.e. H = 1 and the D bits are all 1. + zeros if distance = 0xbfff, i.e. H = 1 and the D bits are all 1. In this case, it is followed by a fourth byte, X. - run length = ((X << 3) | (0 0 0 0 0 L L L)) + 4. + run length = ((X << 3) | (0 0 0 0 0 L L L)) + 4 0 0 1 L L L L L (32..63) Copy of small block within 16kB distance (preferably less than 34B) diff --git a/Documentation/misc-devices/c2port.txt b/Documentation/misc-devices/c2port.txt index ea7344465610..31351b1a5a1f 100644 --- a/Documentation/misc-devices/c2port.txt +++ b/Documentation/misc-devices/c2port.txt @@ -28,14 +28,14 @@ where the micro controller is connected via special GPIOs pins. References ---------- -The C2 Interface main references are at (http://www.silabs.com) +The C2 Interface main references are at (https://www.silabs.com) Silicon Laboratories site], see: - AN127: FLASH Programming via the C2 Interface at -http://www.silabs.com/Support Documents/TechnicalDocs/an127.pdf +https://www.silabs.com/Support Documents/TechnicalDocs/an127.pdf - C2 Specification at -http://www.silabs.com/pages/DownloadDoc.aspx?FILEURL=Support%20Documents/TechnicalDocs/an127.pdf&src=SearchResults +https://www.silabs.com/pages/DownloadDoc.aspx?FILEURL=Support%20Documents/TechnicalDocs/an127.pdf&src=SearchResults however it implements a two wire serial communication protocol (bit banging) designed to enable in-system programming, debugging, and diff --git a/Documentation/process/3.Early-stage.rst b/Documentation/process/3.Early-stage.rst index be00716071d4..6bfd60d77d1a 100644 --- a/Documentation/process/3.Early-stage.rst +++ b/Documentation/process/3.Early-stage.rst @@ -46,7 +46,7 @@ and posted this: to communicate user requirements to these people is a waste of time. They are much too "intelligent" to listen to lesser mortals. -(http://lwn.net/Articles/131776/). +(https://lwn.net/Articles/131776/). The reality of the situation was different; the kernel developers were far more concerned about system stability, long-term maintenance, and finding @@ -216,7 +216,7 @@ a non-disclosure agreement. The Linux Foundation operates an NDA program designed to help with this sort of situation; more information can be found at: - http://www.linuxfoundation.org/en/NDA_program + https://www.linuxfoundation.org/nda/ This kind of review is often enough to avoid serious problems later on without requiring public disclosure of the project. diff --git a/Documentation/process/7.AdvancedTopics.rst b/Documentation/process/7.AdvancedTopics.rst index 172733cff097..bf7cbfb4caa5 100644 --- a/Documentation/process/7.AdvancedTopics.rst +++ b/Documentation/process/7.AdvancedTopics.rst @@ -29,9 +29,9 @@ long document in its own right. Instead, the focus here will be on how git fits into the kernel development process in particular. Developers who wish to come up to speed with git will find more information at: - http://git-scm.com/ + https://git-scm.com/ - http://www.kernel.org/pub/software/scm/git/docs/user-manual.html + https://www.kernel.org/pub/software/scm/git/docs/user-manual.html and on various tutorials found on the web. @@ -55,7 +55,7 @@ server with git-daemon is relatively straightforward if you have a system which is accessible to the Internet. Otherwise, free, public hosting sites (Github, for example) are starting to appear on the net. Established developers can get an account on kernel.org, but those are not easy to come -by; see http://kernel.org/faq/ for more information. +by; see https://kernel.org/faq/ for more information. The normal git workflow involves the use of a lot of branches. Each line of development can be separated into a separate "topic branch" and @@ -125,7 +125,7 @@ can affect your ability to get trees pulled in the future. Quoting Linus: to trust things *without* then having to go and check every individual change by hand. -(http://lwn.net/Articles/224135/). +(https://lwn.net/Articles/224135/). To avoid this kind of situation, ensure that all patches within a given branch stick closely to the associated topic; a "driver fixes" branch diff --git a/Documentation/process/8.Conclusion.rst b/Documentation/process/8.Conclusion.rst index 8395aa2c1f3a..b32a40215858 100644 --- a/Documentation/process/8.Conclusion.rst +++ b/Documentation/process/8.Conclusion.rst @@ -16,24 +16,24 @@ distributions runs into internal limits and fails to process the documents properly). Various web sites discuss kernel development at all levels of detail. Your -author would like to humbly suggest http://lwn.net/ as a source; +author would like to humbly suggest https://lwn.net/ as a source; information on many specific kernel topics can be found via the LWN kernel index at: - http://lwn.net/Kernel/Index/ + https://lwn.net/Kernel/Index/ Beyond that, a valuable resource for kernel developers is: - http://kernelnewbies.org/ + https://kernelnewbies.org/ -And, of course, one should not forget http://kernel.org/, the definitive +And, of course, one should not forget https://kernel.org/, the definitive location for kernel release information. There are a number of books on kernel development: Linux Device Drivers, 3rd Edition (Jonathan Corbet, Alessandro Rubini, and Greg Kroah-Hartman). Online at - http://lwn.net/Kernel/LDD3/. + https://lwn.net/Kernel/LDD3/. Linux Kernel Development (Robert Love). @@ -46,9 +46,9 @@ information to be found there. Documentation for git can be found at: - http://www.kernel.org/pub/software/scm/git/docs/ + https://www.kernel.org/pub/software/scm/git/docs/ - http://www.kernel.org/pub/software/scm/git/docs/user-manual.html + https://www.kernel.org/pub/software/scm/git/docs/user-manual.html Conclusion diff --git a/Documentation/process/adding-syscalls.rst b/Documentation/process/adding-syscalls.rst index a6b4a3a5bf3f..a3ecb236576c 100644 --- a/Documentation/process/adding-syscalls.rst +++ b/Documentation/process/adding-syscalls.rst @@ -541,9 +541,9 @@ References and Sources :manpage:`syscall(2)` man-page: http://man7.org/linux/man-pages/man2/syscall.2.html#NOTES - Collated emails from Linus Torvalds discussing the problems with ``ioctl()``: - http://yarchive.net/comp/linux/ioctl.html + https://yarchive.net/comp/linux/ioctl.html - "How to not invent kernel interfaces", Arnd Bergmann, - http://www.ukuug.org/events/linux2007/2007/papers/Bergmann.pdf + https://www.ukuug.org/events/linux2007/2007/papers/Bergmann.pdf - LWN article from Michael Kerrisk on avoiding new uses of CAP_SYS_ADMIN: https://lwn.net/Articles/486306/ - Recommendation from Andrew Morton that all related information for a new diff --git a/Documentation/process/applying-patches.rst b/Documentation/process/applying-patches.rst index fbb9297e6360..2e7017bef4b8 100644 --- a/Documentation/process/applying-patches.rst +++ b/Documentation/process/applying-patches.rst @@ -229,7 +229,7 @@ Although interdiff may save you a step or two you are generally advised to do the additional steps since interdiff can get things wrong in some cases. Another alternative is ``ketchup``, which is a python script for automatic -downloading and applying of patches (http://www.selenic.com/ketchup/). +downloading and applying of patches (https://www.selenic.com/ketchup/). Other nice tools are diffstat, which shows a summary of changes made by a patch; lsdiff, which displays a short listing of affected files in a patch @@ -241,7 +241,7 @@ the patch contains a given regular expression. Where can I download the patches? ================================= -The patches are available at http://kernel.org/ +The patches are available at https://kernel.org/ Most recent patches are linked from the front page, but they also have specific homes. diff --git a/Documentation/process/changes.rst b/Documentation/process/changes.rst index 91c5ff8e161e..5cfb54c2aaa6 100644 --- a/Documentation/process/changes.rst +++ b/Documentation/process/changes.rst @@ -29,7 +29,7 @@ you probably needn't concern yourself with pcmciautils. ====================== =============== ======================================== Program Minimal version Command to check the version ====================== =============== ======================================== -GNU C 4.6 gcc --version +GNU C 4.8 gcc --version GNU make 3.81 make --version binutils 2.23 ld -v flex 2.5.35 flex --version diff --git a/Documentation/process/coding-style.rst b/Documentation/process/coding-style.rst index 17a8e584f15f..2657a55c6f12 100644 --- a/Documentation/process/coding-style.rst +++ b/Documentation/process/coding-style.rst @@ -90,7 +90,7 @@ Statements longer than 80 columns should be broken into sensible chunks, unless exceeding 80 columns significantly increases readability and does not hide information. -Descendants are always substantially shorter than the parent and are +Descendants are always substantially shorter than the parent and are placed substantially to the right. A very commonly used style is to align descendants to a function open parenthesis. diff --git a/Documentation/process/volatile-considered-harmful.rst b/Documentation/process/volatile-considered-harmful.rst index 4934e656a6f3..7eb6bd7c9214 100644 --- a/Documentation/process/volatile-considered-harmful.rst +++ b/Documentation/process/volatile-considered-harmful.rst @@ -109,9 +109,9 @@ been properly thought through. References ========== -[1] http://lwn.net/Articles/233481/ +[1] https://lwn.net/Articles/233481/ -[2] http://lwn.net/Articles/233482/ +[2] https://lwn.net/Articles/233482/ Credits ======= diff --git a/Documentation/s390/index.rst b/Documentation/s390/index.rst index f7af2061e406..cf71df5776b4 100644 --- a/Documentation/s390/index.rst +++ b/Documentation/s390/index.rst @@ -15,6 +15,7 @@ s390 Architecture vfio-ccw zfcpdump common_io + pci text_files diff --git a/Documentation/s390/pci.rst b/Documentation/s390/pci.rst new file mode 100644 index 000000000000..492850bff316 --- /dev/null +++ b/Documentation/s390/pci.rst @@ -0,0 +1,125 @@ +.. SPDX-License-Identifier: GPL-2.0 + +========= +S/390 PCI +========= + +Authors: + - Pierre Morel + +Copyright, IBM Corp. 2020 + + +Command line parameters and debugfs entries +=========================================== + +Command line parameters +----------------------- + +* nomio + + Do not use PCI Mapped I/O (MIO) instructions. + +* norid + + Ignore the RID field and force use of one PCI domain per PCI function. + +debugfs entries +--------------- + +The S/390 debug feature (s390dbf) generates views to hold various debug results in sysfs directories of the form: + + * /sys/kernel/debug/s390dbf/pci_*/ + +For example: + + - /sys/kernel/debug/s390dbf/pci_msg/sprintf + Holds messages from the processing of PCI events, like machine check handling + and setting of global functionality, like UID checking. + + Change the level of logging to be more or less verbose by piping + a number between 0 and 6 to /sys/kernel/debug/s390dbf/pci_*/level. For + details, see the documentation on the S/390 debug feature at + Documentation/s390/s390dbf.rst. + +Sysfs entries +============= + +Entries specific to zPCI functions and entries that hold zPCI information. + +* /sys/bus/pci/slots/XXXXXXXX + + The slot entries are set up using the function identifier (FID) of the + PCI function. + + - /sys/bus/pci/slots/XXXXXXXX/power + + A physical function that currently supports a virtual function cannot be + powered off until all virtual functions are removed with: + echo 0 > /sys/bus/pci/devices/XXXX:XX:XX.X/sriov_numvf + +* /sys/bus/pci/devices/XXXX:XX:XX.X/ + + - function_id + A zPCI function identifier that uniquely identifies the function in the Z server. + + - function_handle + Low-level identifier used for a configured PCI function. + It might be useful for debuging. + + - pchid + Model-dependent location of the I/O adapter. + + - pfgid + PCI function group ID, functions that share identical functionality + use a common identifier. + A PCI group defines interrupts, IOMMU, IOTLB, and DMA specifics. + + - vfn + The virtual function number, from 1 to N for virtual functions, + 0 for physical functions. + + - pft + The PCI function type + + - port + The port corresponds to the physical port the function is attached to. + It also gives an indication of the physical function a virtual function + is attached to. + + - uid + The unique identifier (UID) is defined when configuring an LPAR and is + unique in the LPAR. + + - pfip/segmentX + The segments determine the isolation of a function. + They correspond to the physical path to the function. + The more the segments are different, the more the functions are isolated. + +Enumeration and hotplug +======================= + +The PCI address consists of four parts: domain, bus, device and function, +and is of this form: DDDD:BB:dd.f + +* When not using multi-functions (norid is set, or the firmware does not + support multi-functions): + + - There is only one function per domain. + + - The domain is set from the zPCI function's UID as defined during the + LPAR creation. + +* When using multi-functions (norid parameter is not set), + zPCI functions are addressed differently: + + - There is still only one bus per domain. + + - There can be up to 256 functions per bus. + + - The domain part of the address of all functions for + a multi-Function device is set from the zPCI function's UID as defined + in the LPAR creation for the function zero. + + - New functions will only be ready for use after the function zero + (the function with devfn 0) has been enumerated. diff --git a/Documentation/s390/vfio-ccw.rst b/Documentation/s390/vfio-ccw.rst index fca9c4f5bd9c..8aad08a8b8a5 100644 --- a/Documentation/s390/vfio-ccw.rst +++ b/Documentation/s390/vfio-ccw.rst @@ -204,15 +204,44 @@ definition of the region is:: __u32 ret_code; } __packed; +This region is always available. + While starting an I/O request, orb_area should be filled with the guest ORB, and scsw_area should be filled with the SCSW of the Virtual Subchannel. irb_area stores the I/O result. -ret_code stores a return code for each access of the region. +ret_code stores a return code for each access of the region. The following +values may occur: + +``0`` + The operation was successful. + +``-EOPNOTSUPP`` + The orb specified transport mode or an unidentified IDAW format, or the + scsw specified a function other than the start function. + +``-EIO`` + A request was issued while the device was not in a state ready to accept + requests, or an internal error occurred. + +``-EBUSY`` + The subchannel was status pending or busy, or a request is already active. + +``-EAGAIN`` + A request was being processed, and the caller should retry. + +``-EACCES`` + The channel path(s) used for the I/O were found to be not operational. + +``-ENODEV`` + The device was found to be not operational. + +``-EINVAL`` + The orb specified a chain longer than 255 ccws, or an internal error + occurred. -This region is always available. vfio-ccw cmd region ------------------- @@ -231,6 +260,64 @@ This region is exposed via region type VFIO_REGION_SUBTYPE_CCW_ASYNC_CMD. Currently, CLEAR SUBCHANNEL and HALT SUBCHANNEL use this region. +command specifies the command to be issued; ret_code stores a return code +for each access of the region. The following values may occur: + +``0`` + The operation was successful. + +``-ENODEV`` + The device was found to be not operational. + +``-EINVAL`` + A command other than halt or clear was specified. + +``-EIO`` + A request was issued while the device was not in a state ready to accept + requests. + +``-EAGAIN`` + A request was being processed, and the caller should retry. + +``-EBUSY`` + The subchannel was status pending or busy while processing a halt request. + +vfio-ccw schib region +--------------------- + +The vfio-ccw schib region is used to return Subchannel-Information +Block (SCHIB) data to userspace:: + + struct ccw_schib_region { + #define SCHIB_AREA_SIZE 52 + __u8 schib_area[SCHIB_AREA_SIZE]; + } __packed; + +This region is exposed via region type VFIO_REGION_SUBTYPE_CCW_SCHIB. + +Reading this region triggers a STORE SUBCHANNEL to be issued to the +associated hardware. + +vfio-ccw crw region +--------------------- + +The vfio-ccw crw region is used to return Channel Report Word (CRW) +data to userspace:: + + struct ccw_crw_region { + __u32 crw; + __u32 pad; + } __packed; + +This region is exposed via region type VFIO_REGION_SUBTYPE_CCW_CRW. + +Reading this region returns a CRW if one that is relevant for this +subchannel (e.g. one reporting changes in channel path state) is +pending, or all zeroes if not. If multiple CRWs are pending (including +possibly chained CRWs), reading this region again will return the next +one, until no more CRWs are pending and zeroes are returned. This is +similar to how STORE CHANNEL REPORT WORD works. + vfio-ccw operation details -------------------------- @@ -333,7 +420,14 @@ through DASD/ECKD device online in a guest now and use it as a block device. The current code allows the guest to start channel programs via -START SUBCHANNEL, and to issue HALT SUBCHANNEL and CLEAR SUBCHANNEL. +START SUBCHANNEL, and to issue HALT SUBCHANNEL, CLEAR SUBCHANNEL, +and STORE SUBCHANNEL. + +Currently all channel programs are prefetched, regardless of the +p-bit setting in the ORB. As a result, self modifying channel +programs are not supported. For this reason, IPL has to be handled as +a special case by a userspace/guest program; this has been implemented +in QEMU's s390-ccw bios as of QEMU 4.1. vfio-ccw supports classic (command mode) channel I/O only. Transport mode (HPF) is not supported. diff --git a/Documentation/s390/zfcpdump.rst b/Documentation/s390/zfcpdump.rst index 54e8e7caf7e7..a61de7aa8778 100644 --- a/Documentation/s390/zfcpdump.rst +++ b/Documentation/s390/zfcpdump.rst @@ -46,5 +46,5 @@ initramfs with a user space application that writes the dump to a SCSI partition. For more information on how to use zfcpdump refer to the s390 'Using the Dump -Tools book', which is available from -http://www.ibm.com/developerworks/linux/linux390. +Tools' book, which is available from IBM Knowledge Center: +https://www.ibm.com/support/knowledgecenter/linuxonibm/liaaf/lnz_r_dt.html diff --git a/Documentation/security/SCTP.rst b/Documentation/security/SCTP.rst index d903eb97fcf3..0bcf6c1245ee 100644 --- a/Documentation/security/SCTP.rst +++ b/Documentation/security/SCTP.rst @@ -328,7 +328,7 @@ NOTES: label (see **netlabel-config**\(8) helper script for details). 5) The NetLabel SCTP peer labeling rules apply as discussed in the following - set of posts tagged "netlabel" at: http://www.paul-moore.com/blog/t. + set of posts tagged "netlabel" at: https://www.paul-moore.com/blog/t. 6) CIPSO is only supported for IPv4 addressing: ``socket(AF_INET, ...)`` CALIPSO is only supported for IPv6 addressing: ``socket(AF_INET6, ...)`` diff --git a/Documentation/security/keys/core.rst b/Documentation/security/keys/core.rst index 9367d0fe4a02..cdc42ccc12e4 100644 --- a/Documentation/security/keys/core.rst +++ b/Documentation/security/keys/core.rst @@ -1030,6 +1030,63 @@ The keyctl syscall functions are: written into the output buffer. Verification returns 0 on success. + * Watch a key or keyring for changes:: + + long keyctl(KEYCTL_WATCH_KEY, key_serial_t key, int queue_fd, + const struct watch_notification_filter *filter); + + This will set or remove a watch for changes on the specified key or + keyring. + + "key" is the ID of the key to be watched. + + "queue_fd" is a file descriptor referring to an open "/dev/watch_queue" + which manages the buffer into which notifications will be delivered. + + "filter" is either NULL to remove a watch or a filter specification to + indicate what events are required from the key. + + See Documentation/watch_queue.rst for more information. + + Note that only one watch may be emplaced for any particular { key, + queue_fd } combination. + + Notification records look like:: + + struct key_notification { + struct watch_notification watch; + __u32 key_id; + __u32 aux; + }; + + In this, watch::type will be "WATCH_TYPE_KEY_NOTIFY" and subtype will be + one of:: + + NOTIFY_KEY_INSTANTIATED + NOTIFY_KEY_UPDATED + NOTIFY_KEY_LINKED + NOTIFY_KEY_UNLINKED + NOTIFY_KEY_CLEARED + NOTIFY_KEY_REVOKED + NOTIFY_KEY_INVALIDATED + NOTIFY_KEY_SETATTR + + Where these indicate a key being instantiated/rejected, updated, a link + being made in a keyring, a link being removed from a keyring, a keyring + being cleared, a key being revoked, a key being invalidated or a key + having one of its attributes changed (user, group, perm, timeout, + restriction). + + If a watched key is deleted, a basic watch_notification will be issued + with "type" set to WATCH_TYPE_META and "subtype" set to + watch_meta_removal_notification. The watchpoint ID will be set in the + "info" field. + + This needs to be configured by enabling: + + "Provide key/keyring change notifications" (KEY_NOTIFICATIONS) + + Kernel Services =============== diff --git a/Documentation/sphinx/kfigure.py b/Documentation/sphinx/kfigure.py index fbfe6693bb60..788704886eec 100644 --- a/Documentation/sphinx/kfigure.py +++ b/Documentation/sphinx/kfigure.py @@ -29,7 +29,7 @@ u""" Used tools: - * ``dot(1)``: Graphviz (http://www.graphviz.org). If Graphviz is not + * ``dot(1)``: Graphviz (https://www.graphviz.org). If Graphviz is not available, the DOT language is inserted as literal-block. * SVG to PDF: To generate PDF, you need at least one of this tools: @@ -41,7 +41,7 @@ u""" * generate PDF from SVG / used by PDF (LaTeX) builder * generate SVG (html-builder) and PDF (latex-builder) from DOT files. - DOT: see http://www.graphviz.org/content/dot-language + DOT: see https://www.graphviz.org/content/dot-language """ @@ -182,7 +182,7 @@ def setupTools(app): kernellog.verbose(app, "use dot(1) from: " + dot_cmd) else: kernellog.warn(app, "dot(1) not found, for better output quality install " - "graphviz from http://www.graphviz.org") + "graphviz from https://www.graphviz.org") if convert_cmd: kernellog.verbose(app, "use convert(1) from: " + convert_cmd) else: diff --git a/Documentation/static-keys.txt b/Documentation/static-keys.txt index 9803e14639bf..38290b9f25eb 100644 --- a/Documentation/static-keys.txt +++ b/Documentation/static-keys.txt @@ -71,7 +71,7 @@ Solution gcc (v4.5) adds a new 'asm goto' statement that allows branching to a label: -http://gcc.gnu.org/ml/gcc-patches/2009-07/msg01556.html +https://gcc.gnu.org/ml/gcc-patches/2009-07/msg01556.html Using the 'asm goto', we can create branches that are either taken or not taken by default, without the need to check memory. Then, at run-time, we can patch diff --git a/Documentation/target/tcm_mod_builder.py b/Documentation/target/tcm_mod_builder.py index 95d6e31f1e3a..1548d8420499 100755 --- a/Documentation/target/tcm_mod_builder.py +++ b/Documentation/target/tcm_mod_builder.py @@ -568,8 +568,8 @@ def tcm_mod_build_kconfig(fabric_mod_dir_var, fabric_mod_name): buf += " tristate \"" + fabric_mod_name.upper() + " fabric module\"\n" buf += " depends on TARGET_CORE && CONFIGFS_FS\n" buf += " default n\n" - buf += " ---help---\n" - buf += " Say Y here to enable the " + fabric_mod_name.upper() + " fabric module\n" + buf += " help\n" + buf += " Say Y here to enable the " + fabric_mod_name.upper() + " fabric module\n" ret = p.write(buf) if ret: diff --git a/Documentation/trace/events-msr.rst b/Documentation/trace/events-msr.rst index e938aa0b6f4f..810481e530b6 100644 --- a/Documentation/trace/events-msr.rst +++ b/Documentation/trace/events-msr.rst @@ -4,7 +4,7 @@ MSR Trace Events The x86 kernel supports tracing most MSR (Model Specific Register) accesses. To see the definition of the MSRs on Intel systems please see the SDM -at http://www.intel.com/sdm (Volume 3) +at https://www.intel.com/sdm (Volume 3) Available trace points: diff --git a/Documentation/trace/histogram-design.rst b/Documentation/trace/histogram-design.rst new file mode 100644 index 000000000000..eef840043da9 --- /dev/null +++ b/Documentation/trace/histogram-design.rst @@ -0,0 +1,2115 @@ +.. SPDX-License-Identifier: GPL-2.0 + +====================== +Histogram Design Notes +====================== + +:Author: Tom Zanussi <zanussi@kernel.org> + +This document attempts to provide a description of how the ftrace +histograms work and how the individual pieces map to the data +structures used to implement them in trace_events_hist.c and +tracing_map.c. + +Note: All the ftrace histogram command examples assume the working + directory is the ftrace /tracing directory. For example:: + + # cd /sys/kernel/debug/tracing + +Also, the histogram output displayed for those commands will be +generally be truncated - only enough to make the point is displayed. + +'hist_debug' trace event files +============================== + +If the kernel is compiled with CONFIG_HIST_TRIGGERS_DEBUG set, an +event file named 'hist_debug' will appear in each event's +subdirectory. This file can be read at any time and will display some +of the hist trigger internals described in this document. Specific +examples and output will be described in test cases below. + +Basic histograms +================ + +First, basic histograms. Below is pretty much the simplest thing you +can do with histograms - create one with a single key on a single +event and cat the output:: + + # echo 'hist:keys=pid' >> events/sched/sched_waking/trigger + + # cat events/sched/sched_waking/hist + + { pid: 18249 } hitcount: 1 + { pid: 13399 } hitcount: 1 + { pid: 17973 } hitcount: 1 + { pid: 12572 } hitcount: 1 + ... + { pid: 10 } hitcount: 921 + { pid: 18255 } hitcount: 1444 + { pid: 25526 } hitcount: 2055 + { pid: 5257 } hitcount: 2055 + { pid: 27367 } hitcount: 2055 + { pid: 1728 } hitcount: 2161 + + Totals: + Hits: 21305 + Entries: 183 + Dropped: 0 + +What this does is create a histogram on the sched_waking event using +pid as a key and with a single value, hitcount, which even if not +explicitly specified, exists for every histogram regardless. + +The hitcount value is a per-bucket value that's automatically +incremented on every hit for the given key, which in this case is the +pid. + +So in this histogram, there's a separate bucket for each pid, and each +bucket contains a value for that bucket, counting the number of times +sched_waking was called for that pid. + +Each histogram is represented by a hist_data struct. + +To keep track of each key and value field in the histogram, hist_data +keeps an array of these fields named fields[]. The fields[] array is +an array containing struct hist_field representations of each +histogram val and key in the histogram (variables are also included +here, but are discussed later). So for the above histogram we have one +key and one value; in this case the one value is the hitcount value, +which all histograms have, regardless of whether they define that +value or not, which the above histogram does not. + +Each struct hist_field contains a pointer to the ftrace_event_field +from the event's trace_event_file along with various bits related to +that such as the size, offset, type, and a hist_field_fn_t function, +which is used to grab the field's data from the ftrace event buffer +(in most cases - some hist_fields such as hitcount don't directly map +to an event field in the trace buffer - in these cases the function +implementation gets its value from somewhere else). The flags field +indicates which type of field it is - key, value, variable, variable +reference, etc., with value being the default. + +The other important hist_data data structure in addition to the +fields[] array is the tracing_map instance created for the histogram, +which is held in the .map member. The tracing_map implements the +lock-free hash table used to implement histograms (see +kernel/trace/tracing_map.h for much more discussion about the +low-level data structures implementing the tracing_map). For the +purposes of this discussion, the tracing_map contains a number of +buckets, each bucket corresponding to a particular tracing_map_elt +object hashed by a given histogram key. + +Below is a diagram the first part of which describes the hist_data and +associated key and value fields for the histogram described above. As +you can see, there are two fields in the fields array, one val field +for the hitcount and one key field for the pid key. + +Below that is a diagram of a run-time snapshot of what the tracing_map +might look like for a given run. It attempts to show the +relationships between the hist_data fields and the tracing_map +elements for a couple hypothetical keys and values.:: + + +------------------+ + | hist_data | + +------------------+ +----------------+ + | .fields[] |---->| val = hitcount |----------------------------+ + +----------------+ +----------------+ | + | .map | | .size | | + +----------------+ +--------------+ | + | .offset | | + +--------------+ | + | .fn() | | + +--------------+ | + . | + . | + . | + +----------------+ <--- n_vals | + | key = pid |----------------------------|--+ + +----------------+ | | + | .size | | | + +--------------+ | | + | .offset | | | + +--------------+ | | + | .fn() | | | + +----------------+ <--- n_fields | | + | unused | | | + +----------------+ | | + | | | | + +--------------+ | | + | | | | + +--------------+ | | + | | | | + +--------------+ | | + n_keys = n_fields - n_vals | | + +The hist_data n_vals and n_fields delineate the extent of the fields[] | | +array and separate keys from values for the rest of the code. | | + +Below is a run-time representation of the tracing_map part of the | | +histogram, with pointers from various parts of the fields[] array | | +to corresponding parts of the tracing_map. | | + +The tracing_map consists of an array of tracing_map_entrys and a set | | +of preallocated tracing_map_elts (abbreviated below as map_entry and | | +map_elt). The total number of map_entrys in the hist_data.map array = | | +map->max_elts (actually map->map_size but only max_elts of those are | | +used. This is a property required by the map_insert() algorithm). | | + +If a map_entry is unused, meaning no key has yet hashed into it, its | | +.key value is 0 and its .val pointer is NULL. Once a map_entry has | | +been claimed, the .key value contains the key's hash value and the | | +.val member points to a map_elt containing the full key and an entry | | +for each key or value in the map_elt.fields[] array. There is an | | +entry in the map_elt.fields[] array corresponding to each hist_field | | +in the histogram, and this is where the continually aggregated sums | | +corresponding to each histogram value are kept. | | + +The diagram attempts to show the relationship between the | | +hist_data.fields[] and the map_elt.fields[] with the links drawn | | +between diagrams:: + + +-----------+ | | + | hist_data | | | + +-----------+ | | + | .fields | | | + +---------+ +-----------+ | | + | .map |---->| map_entry | | | + +---------+ +-----------+ | | + | .key |---> 0 | | + +---------+ | | + | .val |---> NULL | | + +-----------+ | | + | map_entry | | | + +-----------+ | | + | .key |---> pid = 999 | | + +---------+ +-----------+ | | + | .val |--->| map_elt | | | + +---------+ +-----------+ | | + . | .key |---> full key * | | + . +---------+ +---------------+ | | + . | .fields |--->| .sum (val) |<-+ | + +-----------+ +---------+ | 2345 | | | + | map_entry | +---------------+ | | + +-----------+ | .offset (key) |<----+ + | .key |---> 0 | 0 | | | + +---------+ +---------------+ | | + | .val |---> NULL . | | + +-----------+ . | | + | map_entry | . | | + +-----------+ +---------------+ | | + | .key | | .sum (val) or | | | + +---------+ +---------+ | .offset (key) | | | + | .val |--->| map_elt | +---------------+ | | + +-----------+ +---------+ | .sum (val) or | | | + | map_entry | | .offset (key) | | | + +-----------+ +---------------+ | | + | .key |---> pid = 4444 | | + +---------+ +-----------+ | | + | .val | | map_elt | | | + +---------+ +-----------+ | | + | .key |---> full key * | | + +---------+ +---------------+ | | + | .fields |--->| .sum (val) |<-+ | + +---------+ | 65523 | | + +---------------+ | + | .offset (key) |<----+ + | 0 | + +---------------+ + . + . + . + +---------------+ + | .sum (val) or | + | .offset (key) | + +---------------+ + | .sum (val) or | + | .offset (key) | + +---------------+ + +Abbreviations used in the diagrams:: + + hist_data = struct hist_trigger_data + hist_data.fields = struct hist_field + fn = hist_field_fn_t + map_entry = struct tracing_map_entry + map_elt = struct tracing_map_elt + map_elt.fields = struct tracing_map_field + +Whenever a new event occurs and it has a hist trigger associated with +it, event_hist_trigger() is called. event_hist_trigger() first deals +with the key: for each subkey in the key (in the above example, there +is just one subkey corresponding to pid), the hist_field that +represents that subkey is retrieved from hist_data.fields[] and the +hist_field_fn_t fn() associated with that field, along with the +field's size and offset, is used to grab that subkey's data from the +current trace record. + +Once the complete key has been retrieved, it's used to look that key +up in the tracing_map. If there's no tracing_map_elt associated with +that key, an empty one is claimed and inserted in the map for the new +key. In either case, the tracing_map_elt associated with that key is +returned. + +Once a tracing_map_elt available, hist_trigger_elt_update() is called. +As the name implies, this updates the element, which basically means +updating the element's fields. There's a tracing_map_field associated +with each key and value in the histogram, and each of these correspond +to the key and value hist_fields created when the histogram was +created. hist_trigger_elt_update() goes through each value hist_field +and, as for the keys, uses the hist_field's fn() and size and offset +to grab the field's value from the current trace record. Once it has +that value, it simply adds that value to that field's +continually-updated tracing_map_field.sum member. Some hist_field +fn()s, such as for the hitcount, don't actually grab anything from the +trace record (the hitcount fn() just increments the counter sum by 1), +but the idea is the same. + +Once all the values have been updated, hist_trigger_elt_update() is +done and returns. Note that there are also tracing_map_fields for +each subkey in the key, but hist_trigger_elt_update() doesn't look at +them or update anything - those exist only for sorting, which can +happen later. + +Basic histogram test +-------------------- + +This is a good example to try. It produces 3 value fields and 2 key +fields in the output:: + + # echo 'hist:keys=common_pid,call_site.sym:values=bytes_req,bytes_alloc,hitcount' >> events/kmem/kmalloc/trigger + +To see the debug data, cat the kmem/kmalloc's 'hist_debug' file. It +will show the trigger info of the histogram it corresponds to, along +with the address of the hist_data associated with the histogram, which +will become useful in later examples. It then displays the number of +total hist_fields associated with the histogram along with a count of +how many of those correspond to keys and how many correspond to values. + +It then goes on to display details for each field, including the +field's flags and the position of each field in the hist_data's +fields[] array, which is useful information for verifying that things +internally appear correct or not, and which again will become even +more useful in further examples:: + + # cat events/kmem/kmalloc/hist_debug + + # event histogram + # + # trigger info: hist:keys=common_pid,call_site.sym:vals=hitcount,bytes_req,bytes_alloc:sort=hitcount:size=2048 [active] + # + + hist_data: 000000005e48c9a5 + + n_vals: 3 + n_keys: 2 + n_fields: 5 + + val fields: + + hist_data->fields[0]: + flags: + VAL: HIST_FIELD_FL_HITCOUNT + type: u64 + size: 8 + is_signed: 0 + + hist_data->fields[1]: + flags: + VAL: normal u64 value + ftrace_event_field name: bytes_req + type: size_t + size: 8 + is_signed: 0 + + hist_data->fields[2]: + flags: + VAL: normal u64 value + ftrace_event_field name: bytes_alloc + type: size_t + size: 8 + is_signed: 0 + + key fields: + + hist_data->fields[3]: + flags: + HIST_FIELD_FL_KEY + ftrace_event_field name: common_pid + type: int + size: 8 + is_signed: 1 + + hist_data->fields[4]: + flags: + HIST_FIELD_FL_KEY + ftrace_event_field name: call_site + type: unsigned long + size: 8 + is_signed: 0 + +The commands below can be used to clean things up for the next test:: + + # echo '!hist:keys=common_pid,call_site.sym:values=bytes_req,bytes_alloc,hitcount' >> events/kmem/kmalloc/trigger + +Variables +========= + +Variables allow data from one hist trigger to be saved by one hist +trigger and retrieved by another hist trigger. For example, a trigger +on the sched_waking event can capture a timestamp for a particular +pid, and later a sched_switch event that switches to that pid event +can grab the timestamp and use it to calculate a time delta between +the two events:: + + # echo 'hist:keys=pid:ts0=common_timestamp.usecs' >> + events/sched/sched_waking/trigger + + # echo 'hist:keys=next_pid:wakeup_lat=common_timestamp.usecs-$ts0' >> + events/sched/sched_switch/trigger + +In terms of the histogram data structures, variables are implemented +as another type of hist_field and for a given hist trigger are added +to the hist_data.fields[] array just after all the val fields. To +distinguish them from the existing key and val fields, they're given a +new flag type, HIST_FIELD_FL_VAR (abbreviated FL_VAR) and they also +make use of a new .var.idx field member in struct hist_field, which +maps them to an index in a new map_elt.vars[] array added to the +map_elt specifically designed to store and retrieve variable values. +The diagram below shows those new elements and adds a new variable +entry, ts0, corresponding to the ts0 variable in the sched_waking +trigger above. + +sched_waking histogram +----------------------:: + + +------------------+ + | hist_data |<-------------------------------------------------------+ + +------------------+ +-------------------+ | + | .fields[] |-->| val = hitcount | | + +----------------+ +-------------------+ | + | .map | | .size | | + +----------------+ +-----------------+ | + | .offset | | + +-----------------+ | + | .fn() | | + +-----------------+ | + | .flags | | + +-----------------+ | + | .var.idx | | + +-------------------+ | + | var = ts0 | | + +-------------------+ | + | .size | | + +-----------------+ | + | .offset | | + +-----------------+ | + | .fn() | | + +-----------------+ | + | .flags & FL_VAR | | + +-----------------+ | + | .var.idx |----------------------------+-+ | + +-----------------+ | | | + . | | | + . | | | + . | | | + +-------------------+ <--- n_vals | | | + | key = pid | | | | + +-------------------+ | | | + | .size | | | | + +-----------------+ | | | + | .offset | | | | + +-----------------+ | | | + | .fn() | | | | + +-----------------+ | | | + | .flags & FL_KEY | | | | + +-----------------+ | | | + | .var.idx | | | | + +-------------------+ <--- n_fields | | | + | unused | | | | + +-------------------+ | | | + | | | | | + +-----------------+ | | | + | | | | | + +-----------------+ | | | + | | | | | + +-----------------+ | | | + | | | | | + +-----------------+ | | | + | | | | | + +-----------------+ | | | + n_keys = n_fields - n_vals | | | + | | | + +This is very similar to the basic case. In the above diagram, we can | | | +see a new .flags member has been added to the struct hist_field | | | +struct, and a new entry added to hist_data.fields representing the ts0 | | | +variable. For a normal val hist_field, .flags is just 0 (modulo | | | +modifier flags), but if the value is defined as a variable, the .flags | | | +contains a set FL_VAR bit. | | | + +As you can see, the ts0 entry's .var.idx member contains the index | | | +into the tracing_map_elts' .vars[] array containing variable values. | | | +This idx is used whenever the value of the variable is set or read. | | | +The map_elt.vars idx assigned to the given variable is assigned and | | | +saved in .var.idx by create_tracing_map_fields() after it calls | | | +tracing_map_add_var(). | | | + +Below is a representation of the histogram at run-time, which | | | +populates the map, along with correspondence to the above hist_data and | | | +hist_field data structures. | | | + +The diagram attempts to show the relationship between the | | | +hist_data.fields[] and the map_elt.fields[] and map_elt.vars[] with | | | +the links drawn between diagrams. For each of the map_elts, you can | | | +see that the .fields[] members point to the .sum or .offset of a key | | | +or val and the .vars[] members point to the value of a variable. The | | | +arrows between the two diagrams show the linkages between those | | | +tracing_map members and the field definitions in the corresponding | | | +hist_data fields[] members.:: + + +-----------+ | | | + | hist_data | | | | + +-----------+ | | | + | .fields | | | | + +---------+ +-----------+ | | | + | .map |---->| map_entry | | | | + +---------+ +-----------+ | | | + | .key |---> 0 | | | + +---------+ | | | + | .val |---> NULL | | | + +-----------+ | | | + | map_entry | | | | + +-----------+ | | | + | .key |---> pid = 999 | | | + +---------+ +-----------+ | | | + | .val |--->| map_elt | | | | + +---------+ +-----------+ | | | + . | .key |---> full key * | | | + . +---------+ +---------------+ | | | + . | .fields |--->| .sum (val) | | | | + . +---------+ | 2345 | | | | + . +--| .vars | +---------------+ | | | + . | +---------+ | .offset (key) | | | | + . | | 0 | | | | + . | +---------------+ | | | + . | . | | | + . | . | | | + . | . | | | + . | +---------------+ | | | + . | | .sum (val) or | | | | + . | | .offset (key) | | | | + . | +---------------+ | | | + . | | .sum (val) or | | | | + . | | .offset (key) | | | | + . | +---------------+ | | | + . | | | | + . +---------------->+---------------+ | | | + . | ts0 |<--+ | | + . | 113345679876 | | | | + . +---------------+ | | | + . | unused | | | | + . | | | | | + . +---------------+ | | | + . . | | | + . . | | | + . . | | | + . +---------------+ | | | + . | unused | | | | + . | | | | | + . +---------------+ | | | + . | unused | | | | + . | | | | | + . +---------------+ | | | + . | | | + +-----------+ | | | + | map_entry | | | | + +-----------+ | | | + | .key |---> pid = 4444 | | | + +---------+ +-----------+ | | | + | .val |--->| map_elt | | | | + +---------+ +-----------+ | | | + . | .key |---> full key * | | | + . +---------+ +---------------+ | | | + . | .fields |--->| .sum (val) | | | | + +---------+ | 2345 | | | | + +--| .vars | +---------------+ | | | + | +---------+ | .offset (key) | | | | + | | 0 | | | | + | +---------------+ | | | + | . | | | + | . | | | + | . | | | + | +---------------+ | | | + | | .sum (val) or | | | | + | | .offset (key) | | | | + | +---------------+ | | | + | | .sum (val) or | | | | + | | .offset (key) | | | | + | +---------------+ | | | + | | | | + | +---------------+ | | | + +---------------->| ts0 |<--+ | | + | 213499240729 | | | + +---------------+ | | + | unused | | | + | | | | + +---------------+ | | + . | | + . | | + . | | + +---------------+ | | + | unused | | | + | | | | + +---------------+ | | + | unused | | | + | | | | + +---------------+ | | + +For each used map entry, there's a map_elt pointing to an array of | | +.vars containing the current value of the variables associated with | | +that histogram entry. So in the above, the timestamp associated with | | +pid 999 is 113345679876, and the timestamp variable in the same | | +.var.idx for pid 4444 is 213499240729. | | + +sched_switch histogram | | +---------------------- | | + +The sched_switch histogram paired with the above sched_waking | | +histogram is shown below. The most important aspect of the | | +sched_switch histogram is that it references a variable on the | | +sched_waking histogram above. | | + +The histogram diagram is very similar to the others so far displayed, | | +but it adds variable references. You can see the normal hitcount and | | +key fields along with a new wakeup_lat variable implemented in the | | +same way as the sched_waking ts0 variable, but in addition there's an | | +entry with the new FL_VAR_REF (short for HIST_FIELD_FL_VAR_REF) flag. | | + +Associated with the new var ref field are a couple of new hist_field | | +members, var.hist_data and var_ref_idx. For a variable reference, the | | +var.hist_data goes with the var.idx, which together uniquely identify | | +a particular variable on a particular histogram. The var_ref_idx is | | +just the index into the var_ref_vals[] array that caches the values of | | +each variable whenever a hist trigger is updated. Those resulting | | +values are then finally accessed by other code such as trace action | | +code that uses the var_ref_idx values to assign param values. | | + +The diagram below describes the situation for the sched_switch | | +histogram referred to before:: + + # echo 'hist:keys=next_pid:wakeup_lat=common_timestamp.usecs-$ts0' >> | | + events/sched/sched_switch/trigger | | + | | + +------------------+ | | + | hist_data | | | + +------------------+ +-----------------------+ | | + | .fields[] |-->| val = hitcount | | | + +----------------+ +-----------------------+ | | + | .map | | .size | | | + +----------------+ +---------------------+ | | + +--| .var_refs[] | | .offset | | | + | +----------------+ +---------------------+ | | + | | .fn() | | | + | var_ref_vals[] +---------------------+ | | + | +-------------+ | .flags | | | + | | $ts0 |<---+ +---------------------+ | | + | +-------------+ | | .var.idx | | | + | | | | +---------------------+ | | + | +-------------+ | | .var.hist_data | | | + | | | | +---------------------+ | | + | +-------------+ | | .var_ref_idx | | | + | | | | +-----------------------+ | | + | +-------------+ | | var = wakeup_lat | | | + | . | +-----------------------+ | | + | . | | .size | | | + | . | +---------------------+ | | + | +-------------+ | | .offset | | | + | | | | +---------------------+ | | + | +-------------+ | | .fn() | | | + | | | | +---------------------+ | | + | +-------------+ | | .flags & FL_VAR | | | + | | +---------------------+ | | + | | | .var.idx | | | + | | +---------------------+ | | + | | | .var.hist_data | | | + | | +---------------------+ | | + | | | .var_ref_idx | | | + | | +---------------------+ | | + | | . | | + | | . | | + | | . | | + | | +-----------------------+ <--- n_vals | | + | | | key = pid | | | + | | +-----------------------+ | | + | | | .size | | | + | | +---------------------+ | | + | | | .offset | | | + | | +---------------------+ | | + | | | .fn() | | | + | | +---------------------+ | | + | | | .flags | | | + | | +---------------------+ | | + | | | .var.idx | | | + | | +-----------------------+ <--- n_fields | | + | | | unused | | | + | | +-----------------------+ | | + | | | | | | + | | +---------------------+ | | + | | | | | | + | | +---------------------+ | | + | | | | | | + | | +---------------------+ | | + | | | | | | + | | +---------------------+ | | + | | | | | | + | | +---------------------+ | | + | | n_keys = n_fields - n_vals | | + | | | | + | | | | + | | +-----------------------+ | | + +---------------------->| var_ref = $ts0 | | | + | +-----------------------+ | | + | | .size | | | + | +---------------------+ | | + | | .offset | | | + | +---------------------+ | | + | | .fn() | | | + | +---------------------+ | | + | | .flags & FL_VAR_REF | | | + | +---------------------+ | | + | | .var.idx |--------------------------+ | + | +---------------------+ | + | | .var.hist_data |----------------------------+ + | +---------------------+ + +---| .var_ref_idx | + +---------------------+ + +Abbreviations used in the diagrams:: + + hist_data = struct hist_trigger_data + hist_data.fields = struct hist_field + fn = hist_field_fn_t + FL_KEY = HIST_FIELD_FL_KEY + FL_VAR = HIST_FIELD_FL_VAR + FL_VAR_REF = HIST_FIELD_FL_VAR_REF + +When a hist trigger makes use of a variable, a new hist_field is +created with flag HIST_FIELD_FL_VAR_REF. For a VAR_REF field, the +var.idx and var.hist_data take the same values as the referenced +variable, as well as the referenced variable's size, type, and +is_signed values. The VAR_REF field's .name is set to the name of the +variable it references. If a variable reference was created using the +explicit system.event.$var_ref notation, the hist_field's system and +event_name variables are also set. + +So, in order to handle an event for the sched_switch histogram, +because we have a reference to a variable on another histogram, we +need to resolve all variable references first. This is done via the +resolve_var_refs() calls made from event_hist_trigger(). What this +does is grabs the var_refs[] array from the hist_data representing the +sched_switch histogram. For each one of those, the referenced +variable's var.hist_data along with the current key is used to look up +the corresponding tracing_map_elt in that histogram. Once found, the +referenced variable's var.idx is used to look up the variable's value +using tracing_map_read_var(elt, var.idx), which yields the value of +the variable for that element, ts0 in the case above. Note that both +the hist_fields representing both the variable and the variable +reference have the same var.idx, so this is straightforward. + +Variable and variable reference test +------------------------------------ + +This example creates a variable on the sched_waking event, ts0, and +uses it in the sched_switch trigger. The sched_switch trigger also +creates its own variable, wakeup_lat, but nothing yet uses it:: + + # echo 'hist:keys=pid:ts0=common_timestamp.usecs' >> events/sched/sched_waking/trigger + + # echo 'hist:keys=next_pid:wakeup_lat=common_timestamp.usecs-$ts0' >> events/sched/sched_switch/trigger + +Looking at the sched_waking 'hist_debug' output, in addition to the +normal key and value hist_fields, in the val fields section we see a +field with the HIST_FIELD_FL_VAR flag, which indicates that that field +represents a variable. Note that in addition to the variable name, +contained in the var.name field, it includes the var.idx, which is the +index into the tracing_map_elt.vars[] array of the actual variable +location. Note also that the output shows that variables live in the +same part of the hist_data->fields[] array as normal values:: + + # cat events/sched/sched_waking/hist_debug + + # event histogram + # + # trigger info: hist:keys=pid:vals=hitcount:ts0=common_timestamp.usecs:sort=hitcount:size=2048:clock=global [active] + # + + hist_data: 000000009536f554 + + n_vals: 2 + n_keys: 1 + n_fields: 3 + + val fields: + + hist_data->fields[0]: + flags: + VAL: HIST_FIELD_FL_HITCOUNT + type: u64 + size: 8 + is_signed: 0 + + hist_data->fields[1]: + flags: + HIST_FIELD_FL_VAR + var.name: ts0 + var.idx (into tracing_map_elt.vars[]): 0 + type: u64 + size: 8 + is_signed: 0 + + key fields: + + hist_data->fields[2]: + flags: + HIST_FIELD_FL_KEY + ftrace_event_field name: pid + type: pid_t + size: 8 + is_signed: 1 + +Moving on to the sched_switch trigger hist_debug output, in addition +to the unused wakeup_lat variable, we see a new section displaying +variable references. Variable references are displayed in a separate +section because in addition to to being logically separate from +variables and values, they actually live in a separate hist_data +array, var_refs[]. + +In this example, the sched_switch trigger has a reference to a +variable on the sched_waking trigger, $ts0. Looking at the details, +we can see that the var.hist_data value of the referenced variable +matches the previously displayed sched_waking trigger, and the var.idx +value matches the previously displayed var.idx value for that +variable. Also displayed is the var_ref_idx value for that variable +reference, which is where the value for that variable is cached for +use when the trigger is invoked:: + + # cat events/sched/sched_switch/hist_debug + + # event histogram + # + # trigger info: hist:keys=next_pid:vals=hitcount:wakeup_lat=common_timestamp.usecs-$ts0:sort=hitcount:size=2048:clock=global [active] + # + + hist_data: 00000000f4ee8006 + + n_vals: 2 + n_keys: 1 + n_fields: 3 + + val fields: + + hist_data->fields[0]: + flags: + VAL: HIST_FIELD_FL_HITCOUNT + type: u64 + size: 8 + is_signed: 0 + + hist_data->fields[1]: + flags: + HIST_FIELD_FL_VAR + var.name: wakeup_lat + var.idx (into tracing_map_elt.vars[]): 0 + type: u64 + size: 0 + is_signed: 0 + + key fields: + + hist_data->fields[2]: + flags: + HIST_FIELD_FL_KEY + ftrace_event_field name: next_pid + type: pid_t + size: 8 + is_signed: 1 + + variable reference fields: + + hist_data->var_refs[0]: + flags: + HIST_FIELD_FL_VAR_REF + name: ts0 + var.idx (into tracing_map_elt.vars[]): 0 + var.hist_data: 000000009536f554 + var_ref_idx (into hist_data->var_refs[]): 0 + type: u64 + size: 8 + is_signed: 0 + +The commands below can be used to clean things up for the next test:: + + # echo '!hist:keys=next_pid:wakeup_lat=common_timestamp.usecs-$ts0' >> events/sched/sched_switch/trigger + + # echo '!hist:keys=pid:ts0=common_timestamp.usecs' >> events/sched/sched_waking/trigger + +Actions and Handlers +==================== + +Adding onto the previous example, we will now do something with that +wakeup_lat variable, namely send it and another field as a synthetic +event. + +The onmatch() action below basically says that whenever we have a +sched_switch event, if we have a matching sched_waking event, in this +case if we have a pid in the sched_waking histogram that matches the +the next_pid field on this sched_switch event, we retrieve the +variables specified in the wakeup_latency() trace action, and use +them to generate a new wakeup_latency event into the trace stream. + +Note that the way the trace handlers such as wakeup_latency() (which +could equivalently be written trace(wakeup_latency,$wakeup_lat,next_pid) +are implemented, the parameters specified to the trace handler must be +variables. In this case, $wakeup_lat is obviously a variable, but +next_pid isn't, since it's just naming a field in the sched_switch +trace event. Since this is something that almost every trace() and +save() action does, a special shortcut is implemented to allow field +names to be used directly in those cases. How it works is that under +the covers, a temporary variable is created for the named field, and +this variable is what is actually passed to the trace handler. In the +code and documentation, this type of variable is called a 'field +variable'. + +Fields on other trace event's histograms can be used as well. In that +case we have to generate a new histogram and an unfortunately named +'synthetic_field' (the use of synthetic here has nothing to do with +synthetic events) and use that special histogram field as a variable. + +The diagram below illustrates the new elements described above in the +context of the sched_switch histogram using the onmatch() handler and +the trace() action. + +First, we define the wakeup_latency synthetic event:: + + # echo 'wakeup_latency u64 lat; pid_t pid' >> synthetic_events + +Next, the sched_waking hist trigger as before:: + + # echo 'hist:keys=pid:ts0=common_timestamp.usecs' >> + events/sched/sched_waking/trigger + +Finally, we create a hist trigger on the sched_switch event that +generates a wakeup_latency() trace event. In this case we pass +next_pid into the wakeup_latency synthetic event invocation, which +means it will be automatically converted into a field variable:: + + # echo 'hist:keys=next_pid:wakeup_lat=common_timestamp.usecs-$ts0: \ + onmatch(sched.sched_waking).wakeup_latency($wakeup_lat,next_pid)' >> + /sys/kernel/debug/tracing/events/sched/sched_switch/trigger + +The diagram for the sched_switch event is similar to previous examples +but shows the additional field_vars[] array for hist_data and shows +the linkages between the field_vars and the variables and references +created to implement the field variables. The details are discussed +below:: + + +------------------+ + | hist_data | + +------------------+ +-----------------------+ + | .fields[] |-->| val = hitcount | + +----------------+ +-----------------------+ + | .map | | .size | + +----------------+ +---------------------+ + +---| .field_vars[] | | .offset | + | +----------------+ +---------------------+ + |+--| .var_refs[] | | .offset | + || +----------------+ +---------------------+ + || | .fn() | + || var_ref_vals[] +---------------------+ + || +-------------+ | .flags | + || | $ts0 |<---+ +---------------------+ + || +-------------+ | | .var.idx | + || | $next_pid |<-+ | +---------------------+ + || +-------------+ | | | .var.hist_data | + ||+>| $wakeup_lat | | | +---------------------+ + ||| +-------------+ | | | .var_ref_idx | + ||| | | | | +-----------------------+ + ||| +-------------+ | | | var = wakeup_lat | + ||| . | | +-----------------------+ + ||| . | | | .size | + ||| . | | +---------------------+ + ||| +-------------+ | | | .offset | + ||| | | | | +---------------------+ + ||| +-------------+ | | | .fn() | + ||| | | | | +---------------------+ + ||| +-------------+ | | | .flags & FL_VAR | + ||| | | +---------------------+ + ||| | | | .var.idx | + ||| | | +---------------------+ + ||| | | | .var.hist_data | + ||| | | +---------------------+ + ||| | | | .var_ref_idx | + ||| | | +---------------------+ + ||| | | . + ||| | | . + ||| | | . + ||| | | . + ||| +--------------+ | | . + +-->| field_var | | | . + || +--------------+ | | . + || | var | | | . + || +------------+ | | . + || | val | | | . + || +--------------+ | | . + || | field_var | | | . + || +--------------+ | | . + || | var | | | . + || +------------+ | | . + || | val | | | . + || +------------+ | | . + || . | | . + || . | | . + || . | | +-----------------------+ <--- n_vals + || +--------------+ | | | key = pid | + || | field_var | | | +-----------------------+ + || +--------------+ | | | .size | + || | var |--+| +---------------------+ + || +------------+ ||| | .offset | + || | val |-+|| +---------------------+ + || +------------+ ||| | .fn() | + || ||| +---------------------+ + || ||| | .flags | + || ||| +---------------------+ + || ||| | .var.idx | + || ||| +---------------------+ <--- n_fields + || ||| + || ||| n_keys = n_fields - n_vals + || ||| +-----------------------+ + || |+->| var = next_pid | + || | | +-----------------------+ + || | | | .size | + || | | +---------------------+ + || | | | .offset | + || | | +---------------------+ + || | | | .flags & FL_VAR | + || | | +---------------------+ + || | | | .var.idx | + || | | +---------------------+ + || | | | .var.hist_data | + || | | +-----------------------+ + || +-->| val for next_pid | + || | | +-----------------------+ + || | | | .size | + || | | +---------------------+ + || | | | .offset | + || | | +---------------------+ + || | | | .fn() | + || | | +---------------------+ + || | | | .flags | + || | | +---------------------+ + || | | | | + || | | +---------------------+ + || | | + || | | + || | | +-----------------------+ + +|------------------|-|>| var_ref = $ts0 | + | | | +-----------------------+ + | | | | .size | + | | | +---------------------+ + | | | | .offset | + | | | +---------------------+ + | | | | .fn() | + | | | +---------------------+ + | | | | .flags & FL_VAR_REF | + | | | +---------------------+ + | | +---| .var_ref_idx | + | | +-----------------------+ + | | | var_ref = $next_pid | + | | +-----------------------+ + | | | .size | + | | +---------------------+ + | | | .offset | + | | +---------------------+ + | | | .fn() | + | | +---------------------+ + | | | .flags & FL_VAR_REF | + | | +---------------------+ + | +-----| .var_ref_idx | + | +-----------------------+ + | | var_ref = $wakeup_lat | + | +-----------------------+ + | | .size | + | +---------------------+ + | | .offset | + | +---------------------+ + | | .fn() | + | +---------------------+ + | | .flags & FL_VAR_REF | + | +---------------------+ + +------------------------| .var_ref_idx | + +---------------------+ + +As you can see, for a field variable, two hist_fields are created: one +representing the variable, in this case next_pid, and one to actually +get the value of the field from the trace stream, like a normal val +field does. These are created separately from normal variable +creation and are saved in the hist_data->field_vars[] array. See +below for how these are used. In addition, a reference hist_field is +also created, which is needed to reference the field variables such as +$next_pid variable in the trace() action. + +Note that $wakeup_lat is also a variable reference, referencing the +value of the expression common_timestamp-$ts0, and so also needs to +have a hist field entry representing that reference created. + +When hist_trigger_elt_update() is called to get the normal key and +value fields, it also calls update_field_vars(), which goes through +each field_var created for the histogram, and available from +hist_data->field_vars and calls val->fn() to get the data from the +current trace record, and then uses the var's var.idx to set the +variable at the var.idx offset in the appropriate tracing_map_elt's +variable at elt->vars[var.idx]. + +Once all the variables have been updated, resolve_var_refs() can be +called from event_hist_trigger(), and not only can our $ts0 and +$next_pid references be resolved but the $wakeup_lat reference as +well. At this point, the trace() action can simply access the values +assembled in the var_ref_vals[] array and generate the trace event. + +The same process occurs for the field variables associated with the +save() action. + +Abbreviations used in the diagram:: + + hist_data = struct hist_trigger_data + hist_data.fields = struct hist_field + field_var = struct field_var + fn = hist_field_fn_t + FL_KEY = HIST_FIELD_FL_KEY + FL_VAR = HIST_FIELD_FL_VAR + FL_VAR_REF = HIST_FIELD_FL_VAR_REF + +trace() action field variable test +---------------------------------- + +This example adds to the previous test example by finally making use +of the wakeup_lat variable, but in addition also creates a couple of +field variables that then are all passed to the wakeup_latency() trace +action via the onmatch() handler. + +First, we create the wakeup_latency synthetic event:: + + # echo 'wakeup_latency u64 lat; pid_t pid; char comm[16]' >> synthetic_events + +Next, the sched_waking trigger from previous examples:: + + # echo 'hist:keys=pid:ts0=common_timestamp.usecs' >> events/sched/sched_waking/trigger + +Finally, as in the previous test example, we calculate and assign the +wakeup latency using the $ts0 reference from the sched_waking trigger +to the wakeup_lat variable, and finally use it along with a couple +sched_switch event fields, next_pid and next_comm, to generate a +wakeup_latency trace event. The next_pid and next_comm event fields +are automatically converted into field variables for this purpose:: + + # echo 'hist:keys=next_pid:wakeup_lat=common_timestamp.usecs-$ts0:onmatch(sched.sched_waking).wakeup_latency($wakeup_lat,next_pid,next_comm)' >> /sys/kernel/debug/tracing/events/sched/sched_switch/trigger + +The sched_waking hist_debug output shows the same data as in the +previous test example:: + + # cat events/sched/sched_waking/hist_debug + + # event histogram + # + # trigger info: hist:keys=pid:vals=hitcount:ts0=common_timestamp.usecs:sort=hitcount:size=2048:clock=global [active] + # + + hist_data: 00000000d60ff61f + + n_vals: 2 + n_keys: 1 + n_fields: 3 + + val fields: + + hist_data->fields[0]: + flags: + VAL: HIST_FIELD_FL_HITCOUNT + type: u64 + size: 8 + is_signed: 0 + + hist_data->fields[1]: + flags: + HIST_FIELD_FL_VAR + var.name: ts0 + var.idx (into tracing_map_elt.vars[]): 0 + type: u64 + size: 8 + is_signed: 0 + + key fields: + + hist_data->fields[2]: + flags: + HIST_FIELD_FL_KEY + ftrace_event_field name: pid + type: pid_t + size: 8 + is_signed: 1 + +The sched_switch hist_debug output shows the same key and value fields +as in the previous test example - note that wakeup_lat is still in the +val fields section, but that the new field variables are not there - +although the field variables are variables, they're held separately in +the hist_data's field_vars[] array. Although the field variables and +the normal variables are located in separate places, you can see that +the actual variable locations for those variables in the +tracing_map_elt.vars[] do have increasing indices as expected: +wakeup_lat takes the var.idx = 0 slot, while the field variables for +next_pid and next_comm have values var.idx = 1, and var.idx = 2. Note +also that those are the same values displayed for the variable +references corresponding to those variables in the variable reference +fields section. Since there are two triggers and thus two hist_data +addresses, those addresses also need to be accounted for when doing +the matching - you can see that the first variable refers to the 0 +var.idx on the previous hist trigger (see the hist_data address +associated with that trigger), while the second variable refers to the +0 var.idx on the sched_switch hist trigger, as do all the remaining +variable references. + +Finally, the action tracking variables section just shows the system +and event name for the onmatch() handler:: + + # cat events/sched/sched_switch/hist_debug + + # event histogram + # + # trigger info: hist:keys=next_pid:vals=hitcount:wakeup_lat=common_timestamp.usecs-$ts0:sort=hitcount:size=2048:clock=global:onmatch(sched.sched_waking).wakeup_latency($wakeup_lat,next_pid,next_comm) [active] + # + + hist_data: 0000000008f551b7 + + n_vals: 2 + n_keys: 1 + n_fields: 3 + + val fields: + + hist_data->fields[0]: + flags: + VAL: HIST_FIELD_FL_HITCOUNT + type: u64 + size: 8 + is_signed: 0 + + hist_data->fields[1]: + flags: + HIST_FIELD_FL_VAR + var.name: wakeup_lat + var.idx (into tracing_map_elt.vars[]): 0 + type: u64 + size: 0 + is_signed: 0 + + key fields: + + hist_data->fields[2]: + flags: + HIST_FIELD_FL_KEY + ftrace_event_field name: next_pid + type: pid_t + size: 8 + is_signed: 1 + + variable reference fields: + + hist_data->var_refs[0]: + flags: + HIST_FIELD_FL_VAR_REF + name: ts0 + var.idx (into tracing_map_elt.vars[]): 0 + var.hist_data: 00000000d60ff61f + var_ref_idx (into hist_data->var_refs[]): 0 + type: u64 + size: 8 + is_signed: 0 + + hist_data->var_refs[1]: + flags: + HIST_FIELD_FL_VAR_REF + name: wakeup_lat + var.idx (into tracing_map_elt.vars[]): 0 + var.hist_data: 0000000008f551b7 + var_ref_idx (into hist_data->var_refs[]): 1 + type: u64 + size: 0 + is_signed: 0 + + hist_data->var_refs[2]: + flags: + HIST_FIELD_FL_VAR_REF + name: next_pid + var.idx (into tracing_map_elt.vars[]): 1 + var.hist_data: 0000000008f551b7 + var_ref_idx (into hist_data->var_refs[]): 2 + type: pid_t + size: 4 + is_signed: 0 + + hist_data->var_refs[3]: + flags: + HIST_FIELD_FL_VAR_REF + name: next_comm + var.idx (into tracing_map_elt.vars[]): 2 + var.hist_data: 0000000008f551b7 + var_ref_idx (into hist_data->var_refs[]): 3 + type: char[16] + size: 256 + is_signed: 0 + + field variables: + + hist_data->field_vars[0]: + + field_vars[0].var: + flags: + HIST_FIELD_FL_VAR + var.name: next_pid + var.idx (into tracing_map_elt.vars[]): 1 + + field_vars[0].val: + ftrace_event_field name: next_pid + type: pid_t + size: 4 + is_signed: 1 + + hist_data->field_vars[1]: + + field_vars[1].var: + flags: + HIST_FIELD_FL_VAR + var.name: next_comm + var.idx (into tracing_map_elt.vars[]): 2 + + field_vars[1].val: + ftrace_event_field name: next_comm + type: char[16] + size: 256 + is_signed: 0 + + action tracking variables (for onmax()/onchange()/onmatch()): + + hist_data->actions[0].match_data.event_system: sched + hist_data->actions[0].match_data.event: sched_waking + +The commands below can be used to clean things up for the next test:: + + # echo '!hist:keys=next_pid:wakeup_lat=common_timestamp.usecs-$ts0:onmatch(sched.sched_waking).wakeup_latency($wakeup_lat,next_pid,next_comm)' >> /sys/kernel/debug/tracing/events/sched/sched_switch/trigger + + # echo '!hist:keys=pid:ts0=common_timestamp.usecs' >> events/sched/sched_waking/trigger + + # echo '!wakeup_latency u64 lat; pid_t pid; char comm[16]' >> synthetic_events + +action_data and the trace() action +---------------------------------- + +As mentioned above, when the trace() action generates a synthetic +event, all the parameters to the synthetic event either already are +variables or are converted into variables (via field variables), and +finally all those variable values are collected via references to them +into a var_ref_vals[] array. + +The values in the var_ref_vals[] array, however, don't necessarily +follow the same ordering as the synthetic event params. To address +that, struct action_data contains another array, var_ref_idx[] that +maps the trace action params to the var_ref_vals[] values. Below is a +diagram illustrating that for the wakeup_latency() synthetic event:: + + +------------------+ wakeup_latency() + | action_data | event params var_ref_vals[] + +------------------+ +-----------------+ +-----------------+ + | .var_ref_idx[] |--->| $wakeup_lat idx |---+ | | + +----------------+ +-----------------+ | +-----------------+ + | .synth_event | | $next_pid idx |---|-+ | $wakeup_lat val | + +----------------+ +-----------------+ | | +-----------------+ + . | +->| $next_pid val | + . | +-----------------+ + . | . + +-----------------+ | . + | | | . + +-----------------+ | +-----------------+ + +--->| $wakeup_lat val | + +-----------------+ + +Basically, how this ends up getting used in the synthetic event probe +function, trace_event_raw_event_synth(), is as follows:: + + for each field i in .synth_event + val_idx = .var_ref_idx[i] + val = var_ref_vals[val_idx] + +action_data and the onXXX() handlers +------------------------------------ + +The hist trigger onXXX() actions other than onmatch(), such as onmax() +and onchange(), also make use of and internally create hidden +variables. This information is contained in the +action_data.track_data struct, and is also visible in the hist_debug +output as will be described in the example below. + +Typically, the onmax() or onchange() handlers are used in conjunction +with the save() and snapshot() actions. For example:: + + # echo 'hist:keys=next_pid:wakeup_lat=common_timestamp.usecs-$ts0: \ + onmax($wakeup_lat).save(next_comm,prev_pid,prev_prio,prev_comm)' >> + /sys/kernel/debug/tracing/events/sched/sched_switch/trigger + +or:: + + # echo 'hist:keys=next_pid:wakeup_lat=common_timestamp.usecs-$ts0: \ + onmax($wakeup_lat).snapshot()' >> + /sys/kernel/debug/tracing/events/sched/sched_switch/trigger + +save() action field variable test +--------------------------------- + +For this example, instead of generating a synthetic event, the save() +action is used to save field values whenever an onmax() handler +detects that a new max latency has been hit. As in the previous +example, the values being saved are also field values, but in this +case, are kept in a separate hist_data array named save_vars[]. + +As in previous test examples, we set up the sched_waking trigger:: + + # echo 'hist:keys=pid:ts0=common_timestamp.usecs' >> events/sched/sched_waking/trigger + +In this case, however, we set up the sched_switch trigger to save some +sched_switch field values whenever we hit a new maximum latency. For +both the onmax() handler and save() action, variables will be created, +which we can use the hist_debug files to examine:: + + # echo 'hist:keys=next_pid:wakeup_lat=common_timestamp.usecs-$ts0:onmax($wakeup_lat).save(next_comm,prev_pid,prev_prio,prev_comm)' >> events/sched/sched_switch/trigger + +The sched_waking hist_debug output shows the same data as in the +previous test examples:: + + # cat events/sched/sched_waking/hist_debug + + # + # trigger info: hist:keys=pid:vals=hitcount:ts0=common_timestamp.usecs:sort=hitcount:size=2048:clock=global [active] + # + + hist_data: 00000000e6290f48 + + n_vals: 2 + n_keys: 1 + n_fields: 3 + + val fields: + + hist_data->fields[0]: + flags: + VAL: HIST_FIELD_FL_HITCOUNT + type: u64 + size: 8 + is_signed: 0 + + hist_data->fields[1]: + flags: + HIST_FIELD_FL_VAR + var.name: ts0 + var.idx (into tracing_map_elt.vars[]): 0 + type: u64 + size: 8 + is_signed: 0 + + key fields: + + hist_data->fields[2]: + flags: + HIST_FIELD_FL_KEY + ftrace_event_field name: pid + type: pid_t + size: 8 + is_signed: 1 + +The output of the sched_switch trigger shows the same val and key +values as before, but also shows a couple new sections. + +First, the action tracking variables section now shows the +actions[].track_data information describing the special tracking +variables and references used to track, in this case, the running +maximum value. The actions[].track_data.var_ref member contains the +reference to the variable being tracked, in this case the $wakeup_lat +variable. In order to perform the onmax() handler function, there +also needs to be a variable that tracks the current maximum by getting +updated whenever a new maximum is hit. In this case, we can see that +an auto-generated variable named ' __max' has been created and is +visible in the actions[].track_data.track_var variable. + +Finally, in the new 'save action variables' section, we can see that +the 4 params to the save() function have resulted in 4 field variables +being created for the purposes of saving the values of the named +fields when the max is hit. These variables are kept in a separate +save_vars[] array off of hist_data, so are displayed in a separate +section:: + + # cat events/sched/sched_switch/hist_debug + + # event histogram + # + # trigger info: hist:keys=next_pid:vals=hitcount:wakeup_lat=common_timestamp.usecs-$ts0:sort=hitcount:size=2048:clock=global:onmax($wakeup_lat).save(next_comm,prev_pid,prev_prio,prev_comm) [active] + # + + hist_data: 0000000057bcd28d + + n_vals: 2 + n_keys: 1 + n_fields: 3 + + val fields: + + hist_data->fields[0]: + flags: + VAL: HIST_FIELD_FL_HITCOUNT + type: u64 + size: 8 + is_signed: 0 + + hist_data->fields[1]: + flags: + HIST_FIELD_FL_VAR + var.name: wakeup_lat + var.idx (into tracing_map_elt.vars[]): 0 + type: u64 + size: 0 + is_signed: 0 + + key fields: + + hist_data->fields[2]: + flags: + HIST_FIELD_FL_KEY + ftrace_event_field name: next_pid + type: pid_t + size: 8 + is_signed: 1 + + variable reference fields: + + hist_data->var_refs[0]: + flags: + HIST_FIELD_FL_VAR_REF + name: ts0 + var.idx (into tracing_map_elt.vars[]): 0 + var.hist_data: 00000000e6290f48 + var_ref_idx (into hist_data->var_refs[]): 0 + type: u64 + size: 8 + is_signed: 0 + + hist_data->var_refs[1]: + flags: + HIST_FIELD_FL_VAR_REF + name: wakeup_lat + var.idx (into tracing_map_elt.vars[]): 0 + var.hist_data: 0000000057bcd28d + var_ref_idx (into hist_data->var_refs[]): 1 + type: u64 + size: 0 + is_signed: 0 + + action tracking variables (for onmax()/onchange()/onmatch()): + + hist_data->actions[0].track_data.var_ref: + flags: + HIST_FIELD_FL_VAR_REF + name: wakeup_lat + var.idx (into tracing_map_elt.vars[]): 0 + var.hist_data: 0000000057bcd28d + var_ref_idx (into hist_data->var_refs[]): 1 + type: u64 + size: 0 + is_signed: 0 + + hist_data->actions[0].track_data.track_var: + flags: + HIST_FIELD_FL_VAR + var.name: __max + var.idx (into tracing_map_elt.vars[]): 1 + type: u64 + size: 8 + is_signed: 0 + + save action variables (save() params): + + hist_data->save_vars[0]: + + save_vars[0].var: + flags: + HIST_FIELD_FL_VAR + var.name: next_comm + var.idx (into tracing_map_elt.vars[]): 2 + + save_vars[0].val: + ftrace_event_field name: next_comm + type: char[16] + size: 256 + is_signed: 0 + + hist_data->save_vars[1]: + + save_vars[1].var: + flags: + HIST_FIELD_FL_VAR + var.name: prev_pid + var.idx (into tracing_map_elt.vars[]): 3 + + save_vars[1].val: + ftrace_event_field name: prev_pid + type: pid_t + size: 4 + is_signed: 1 + + hist_data->save_vars[2]: + + save_vars[2].var: + flags: + HIST_FIELD_FL_VAR + var.name: prev_prio + var.idx (into tracing_map_elt.vars[]): 4 + + save_vars[2].val: + ftrace_event_field name: prev_prio + type: int + size: 4 + is_signed: 1 + + hist_data->save_vars[3]: + + save_vars[3].var: + flags: + HIST_FIELD_FL_VAR + var.name: prev_comm + var.idx (into tracing_map_elt.vars[]): 5 + + save_vars[3].val: + ftrace_event_field name: prev_comm + type: char[16] + size: 256 + is_signed: 0 + +The commands below can be used to clean things up for the next test:: + + # echo '!hist:keys=next_pid:wakeup_lat=common_timestamp.usecs-$ts0:onmax($wakeup_lat).save(next_comm,prev_pid,prev_prio,prev_comm)' >> events/sched/sched_switch/trigger + + # echo '!hist:keys=pid:ts0=common_timestamp.usecs' >> events/sched/sched_waking/trigger + +A couple special cases +====================== + +While the above covers the basics of the histogram internals, there +are a couple of special cases that should be discussed, since they +tend to create even more confusion. Those are field variables on other +histograms, and aliases, both described below through example tests +using the hist_debug files. + +Test of field variables on other histograms +------------------------------------------- + +This example is similar to the previous examples, but in this case, +the sched_switch trigger references a hist trigger field on another +event, namely the sched_waking event. In order to accomplish this, a +field variable is created for the other event, but since an existing +histogram can't be used, as existing histograms are immutable, a new +histogram with a matching variable is created and used, and we'll see +that reflected in the hist_debug output shown below. + +First, we create the wakeup_latency synthetic event. Note the +addition of the prio field:: + + # echo 'wakeup_latency u64 lat; pid_t pid; int prio' >> synthetic_events + +As in previous test examples, we set up the sched_waking trigger:: + + # echo 'hist:keys=pid:ts0=common_timestamp.usecs' >> events/sched/sched_waking/trigger + +Here we set up a hist trigger on sched_switch to send a wakeup_latency +event using an onmatch handler naming the sched_waking event. Note +that the third param being passed to the wakeup_latency() is prio, +which is a field name that needs to have a field variable created for +it. There isn't however any prio field on the sched_switch event so +it would seem that it wouldn't be possible to create a field variable +for it. The matching sched_waking event does have a prio field, so it +should be possible to make use of it for this purpose. The problem +with that is that it's not currently possible to define a new variable +on an existing histogram, so it's not possible to add a new prio field +variable to the existing sched_waking histogram. It is however +possible to create an additional new 'matching' sched_waking histogram +for the same event, meaning that it uses the same key and filters, and +define the new prio field variable on that. + +Here's the sched_switch trigger:: + + # echo 'hist:keys=next_pid:wakeup_lat=common_timestamp.usecs-$ts0:onmatch(sched.sched_waking).wakeup_latency($wakeup_lat,next_pid,prio)' >> events/sched/sched_switch/trigger + +And here's the output of the hist_debug information for the +sched_waking hist trigger. Note that there are two histograms +displayed in the output: the first is the normal sched_waking +histogram we've seen in the previous examples, and the second is the +special histogram we created to provide the prio field variable. + +Looking at the second histogram below, we see a variable with the name +synthetic_prio. This is the field variable created for the prio field +on that sched_waking histogram:: + + # cat events/sched/sched_waking/hist_debug + + # event histogram + # + # trigger info: hist:keys=pid:vals=hitcount:ts0=common_timestamp.usecs:sort=hitcount:size=2048:clock=global [active] + # + + hist_data: 00000000349570e4 + + n_vals: 2 + n_keys: 1 + n_fields: 3 + + val fields: + + hist_data->fields[0]: + flags: + VAL: HIST_FIELD_FL_HITCOUNT + type: u64 + size: 8 + is_signed: 0 + + hist_data->fields[1]: + flags: + HIST_FIELD_FL_VAR + var.name: ts0 + var.idx (into tracing_map_elt.vars[]): 0 + type: u64 + size: 8 + is_signed: 0 + + key fields: + + hist_data->fields[2]: + flags: + HIST_FIELD_FL_KEY + ftrace_event_field name: pid + type: pid_t + size: 8 + is_signed: 1 + + + # event histogram + # + # trigger info: hist:keys=pid:vals=hitcount:synthetic_prio=prio:sort=hitcount:size=2048 [active] + # + + hist_data: 000000006920cf38 + + n_vals: 2 + n_keys: 1 + n_fields: 3 + + val fields: + + hist_data->fields[0]: + flags: + VAL: HIST_FIELD_FL_HITCOUNT + type: u64 + size: 8 + is_signed: 0 + + hist_data->fields[1]: + flags: + HIST_FIELD_FL_VAR + ftrace_event_field name: prio + var.name: synthetic_prio + var.idx (into tracing_map_elt.vars[]): 0 + type: int + size: 4 + is_signed: 1 + + key fields: + + hist_data->fields[2]: + flags: + HIST_FIELD_FL_KEY + ftrace_event_field name: pid + type: pid_t + size: 8 + is_signed: 1 + +Looking at the sched_switch histogram below, we can see a reference to +the synthetic_prio variable on sched_waking, and looking at the +associated hist_data address we see that it is indeed associated with +the new histogram. Note also that the other references are to a +normal variable, wakeup_lat, and to a normal field variable, next_pid, +the details of which are in the field variables section:: + + # cat events/sched/sched_switch/hist_debug + + # event histogram + # + # trigger info: hist:keys=next_pid:vals=hitcount:wakeup_lat=common_timestamp.usecs-$ts0:sort=hitcount:size=2048:clock=global:onmatch(sched.sched_waking).wakeup_latency($wakeup_lat,next_pid,prio) [active] + # + + hist_data: 00000000a73b67df + + n_vals: 2 + n_keys: 1 + n_fields: 3 + + val fields: + + hist_data->fields[0]: + flags: + VAL: HIST_FIELD_FL_HITCOUNT + type: u64 + size: 8 + is_signed: 0 + + hist_data->fields[1]: + flags: + HIST_FIELD_FL_VAR + var.name: wakeup_lat + var.idx (into tracing_map_elt.vars[]): 0 + type: u64 + size: 0 + is_signed: 0 + + key fields: + + hist_data->fields[2]: + flags: + HIST_FIELD_FL_KEY + ftrace_event_field name: next_pid + type: pid_t + size: 8 + is_signed: 1 + + variable reference fields: + + hist_data->var_refs[0]: + flags: + HIST_FIELD_FL_VAR_REF + name: ts0 + var.idx (into tracing_map_elt.vars[]): 0 + var.hist_data: 00000000349570e4 + var_ref_idx (into hist_data->var_refs[]): 0 + type: u64 + size: 8 + is_signed: 0 + + hist_data->var_refs[1]: + flags: + HIST_FIELD_FL_VAR_REF + name: wakeup_lat + var.idx (into tracing_map_elt.vars[]): 0 + var.hist_data: 00000000a73b67df + var_ref_idx (into hist_data->var_refs[]): 1 + type: u64 + size: 0 + is_signed: 0 + + hist_data->var_refs[2]: + flags: + HIST_FIELD_FL_VAR_REF + name: next_pid + var.idx (into tracing_map_elt.vars[]): 1 + var.hist_data: 00000000a73b67df + var_ref_idx (into hist_data->var_refs[]): 2 + type: pid_t + size: 4 + is_signed: 0 + + hist_data->var_refs[3]: + flags: + HIST_FIELD_FL_VAR_REF + name: synthetic_prio + var.idx (into tracing_map_elt.vars[]): 0 + var.hist_data: 000000006920cf38 + var_ref_idx (into hist_data->var_refs[]): 3 + type: int + size: 4 + is_signed: 1 + + field variables: + + hist_data->field_vars[0]: + + field_vars[0].var: + flags: + HIST_FIELD_FL_VAR + var.name: next_pid + var.idx (into tracing_map_elt.vars[]): 1 + + field_vars[0].val: + ftrace_event_field name: next_pid + type: pid_t + size: 4 + is_signed: 1 + + action tracking variables (for onmax()/onchange()/onmatch()): + + hist_data->actions[0].match_data.event_system: sched + hist_data->actions[0].match_data.event: sched_waking + +The commands below can be used to clean things up for the next test:: + + # echo '!hist:keys=next_pid:wakeup_lat=common_timestamp.usecs-$ts0:onmatch(sched.sched_waking).wakeup_latency($wakeup_lat,next_pid,prio)' >> events/sched/sched_switch/trigger + + # echo '!hist:keys=pid:ts0=common_timestamp.usecs' >> events/sched/sched_waking/trigger + + # echo '!wakeup_latency u64 lat; pid_t pid; int prio' >> synthetic_events + +Alias test +---------- + +This example is very similar to previous examples, but demonstrates +the alias flag. + +First, we create the wakeup_latency synthetic event:: + + # echo 'wakeup_latency u64 lat; pid_t pid; char comm[16]' >> synthetic_events + +Next, we create a sched_waking trigger similar to previous examples, +but in this case we save the pid in the waking_pid variable:: + + # echo 'hist:keys=pid:waking_pid=pid:ts0=common_timestamp.usecs' >> events/sched/sched_waking/trigger + +For the sched_switch trigger, instead of using $waking_pid directly in +the wakeup_latency synthetic event invocation, we create an alias of +$waking_pid named $woken_pid, and use that in the synthetic event +invocation instead:: + + # echo 'hist:keys=next_pid:woken_pid=$waking_pid:wakeup_lat=common_timestamp.usecs-$ts0:onmatch(sched.sched_waking).wakeup_latency($wakeup_lat,$woken_pid,next_comm)' >> events/sched/sched_switch/trigger + +Looking at the sched_waking hist_debug output, in addition to the +normal fields, we can see the waking_pid variable:: + + # cat events/sched/sched_waking/hist_debug + + # event histogram + # + # trigger info: hist:keys=pid:vals=hitcount:waking_pid=pid,ts0=common_timestamp.usecs:sort=hitcount:size=2048:clock=global [active] + # + + hist_data: 00000000a250528c + + n_vals: 3 + n_keys: 1 + n_fields: 4 + + val fields: + + hist_data->fields[0]: + flags: + VAL: HIST_FIELD_FL_HITCOUNT + type: u64 + size: 8 + is_signed: 0 + + hist_data->fields[1]: + flags: + HIST_FIELD_FL_VAR + ftrace_event_field name: pid + var.name: waking_pid + var.idx (into tracing_map_elt.vars[]): 0 + type: pid_t + size: 4 + is_signed: 1 + + hist_data->fields[2]: + flags: + HIST_FIELD_FL_VAR + var.name: ts0 + var.idx (into tracing_map_elt.vars[]): 1 + type: u64 + size: 8 + is_signed: 0 + + key fields: + + hist_data->fields[3]: + flags: + HIST_FIELD_FL_KEY + ftrace_event_field name: pid + type: pid_t + size: 8 + is_signed: 1 + +The sched_switch hist_debug output shows that a variable named +woken_pid has been created but that it also has the +HIST_FIELD_FL_ALIAS flag set. It also has the HIST_FIELD_FL_VAR flag +set, which is why it appears in the val field section. + +Despite that implementation detail, an alias variable is actually more +like a variable reference; in fact it can be thought of as a reference +to a reference. The implementation copies the var_ref->fn() from the +variable reference being referenced, in this case, the waking_pid +fn(), which is hist_field_var_ref() and makes that the fn() of the +alias. The hist_field_var_ref() fn() requires the var_ref_idx of the +variable reference it's using, so waking_pid's var_ref_idx is also +copied to the alias. The end result is that when the value of alias +is retrieved, in the end it just does the same thing the original +reference would have done and retrieves the same value from the +var_ref_vals[] array. You can verify this in the output by noting +that the var_ref_idx of the alias, in this case woken_pid, is the same +as the var_ref_idx of the reference, waking_pid, in the variable +reference fields section. + +Additionally, once it gets that value, since it is also a variable, it +then saves that value into its var.idx. So the var.idx of the +woken_pid alias is 0, which it fills with the value from var_ref_idx 0 +when its fn() is called to update itself. You'll also notice that +there's a woken_pid var_ref in the variable refs section. That is the +reference to the woken_pid alias variable, and you can see that it +retrieves the value from the same var.idx as the woken_pid alias, 0, +and then in turn saves that value in its own var_ref_idx slot, 3, and +the value at this position is finally what gets assigned to the +$woken_pid slot in the trace event invocation:: + + # cat events/sched/sched_switch/hist_debug + + # event histogram + # + # trigger info: hist:keys=next_pid:vals=hitcount:woken_pid=$waking_pid,wakeup_lat=common_timestamp.usecs-$ts0:sort=hitcount:size=2048:clock=global:onmatch(sched.sched_waking).wakeup_latency($wakeup_lat,$woken_pid,next_comm) [active] + # + + hist_data: 0000000055d65ed0 + + n_vals: 3 + n_keys: 1 + n_fields: 4 + + val fields: + + hist_data->fields[0]: + flags: + VAL: HIST_FIELD_FL_HITCOUNT + type: u64 + size: 8 + is_signed: 0 + + hist_data->fields[1]: + flags: + HIST_FIELD_FL_VAR + HIST_FIELD_FL_ALIAS + var.name: woken_pid + var.idx (into tracing_map_elt.vars[]): 0 + var_ref_idx (into hist_data->var_refs[]): 0 + type: pid_t + size: 4 + is_signed: 1 + + hist_data->fields[2]: + flags: + HIST_FIELD_FL_VAR + var.name: wakeup_lat + var.idx (into tracing_map_elt.vars[]): 1 + type: u64 + size: 0 + is_signed: 0 + + key fields: + + hist_data->fields[3]: + flags: + HIST_FIELD_FL_KEY + ftrace_event_field name: next_pid + type: pid_t + size: 8 + is_signed: 1 + + variable reference fields: + + hist_data->var_refs[0]: + flags: + HIST_FIELD_FL_VAR_REF + name: waking_pid + var.idx (into tracing_map_elt.vars[]): 0 + var.hist_data: 00000000a250528c + var_ref_idx (into hist_data->var_refs[]): 0 + type: pid_t + size: 4 + is_signed: 1 + + hist_data->var_refs[1]: + flags: + HIST_FIELD_FL_VAR_REF + name: ts0 + var.idx (into tracing_map_elt.vars[]): 1 + var.hist_data: 00000000a250528c + var_ref_idx (into hist_data->var_refs[]): 1 + type: u64 + size: 8 + is_signed: 0 + + hist_data->var_refs[2]: + flags: + HIST_FIELD_FL_VAR_REF + name: wakeup_lat + var.idx (into tracing_map_elt.vars[]): 1 + var.hist_data: 0000000055d65ed0 + var_ref_idx (into hist_data->var_refs[]): 2 + type: u64 + size: 0 + is_signed: 0 + + hist_data->var_refs[3]: + flags: + HIST_FIELD_FL_VAR_REF + name: woken_pid + var.idx (into tracing_map_elt.vars[]): 0 + var.hist_data: 0000000055d65ed0 + var_ref_idx (into hist_data->var_refs[]): 3 + type: pid_t + size: 4 + is_signed: 1 + + hist_data->var_refs[4]: + flags: + HIST_FIELD_FL_VAR_REF + name: next_comm + var.idx (into tracing_map_elt.vars[]): 2 + var.hist_data: 0000000055d65ed0 + var_ref_idx (into hist_data->var_refs[]): 4 + type: char[16] + size: 256 + is_signed: 0 + + field variables: + + hist_data->field_vars[0]: + + field_vars[0].var: + flags: + HIST_FIELD_FL_VAR + var.name: next_comm + var.idx (into tracing_map_elt.vars[]): 2 + + field_vars[0].val: + ftrace_event_field name: next_comm + type: char[16] + size: 256 + is_signed: 0 + + action tracking variables (for onmax()/onchange()/onmatch()): + + hist_data->actions[0].match_data.event_system: sched + hist_data->actions[0].match_data.event: sched_waking + +The commands below can be used to clean things up for the next test:: + + # echo '!hist:keys=next_pid:woken_pid=$waking_pid:wakeup_lat=common_timestamp.usecs-$ts0:onmatch(sched.sched_waking).wakeup_latency($wakeup_lat,$woken_pid,next_comm)' >> events/sched/sched_switch/trigger + + # echo '!hist:keys=pid:ts0=common_timestamp.usecs' >> events/sched/sched_waking/trigger + + # echo '!wakeup_latency u64 lat; pid_t pid; char comm[16]' >> synthetic_events diff --git a/Documentation/trace/mmiotrace.rst b/Documentation/trace/mmiotrace.rst index 5116e8ca27b4..fed13eaead89 100644 --- a/Documentation/trace/mmiotrace.rst +++ b/Documentation/trace/mmiotrace.rst @@ -5,7 +5,7 @@ In-kernel memory-mapped I/O tracing Home page and links to optional user space tools: - http://nouveau.freedesktop.org/wiki/MmioTrace + https://nouveau.freedesktop.org/wiki/MmioTrace MMIO tracing was originally developed by Intel around 2003 for their Fault Injection Test Harness. In Dec 2006 - Jan 2007, using the code from Intel, diff --git a/Documentation/translations/it_IT/kernel-hacking/hacking.rst b/Documentation/translations/it_IT/kernel-hacking/hacking.rst index 6aab27a8d323..e9a2e92134f0 100644 --- a/Documentation/translations/it_IT/kernel-hacking/hacking.rst +++ b/Documentation/translations/it_IT/kernel-hacking/hacking.rst @@ -634,7 +634,7 @@ Definita in ``include/linux/export.h`` Questa è una variate di `EXPORT_SYMBOL()` che permette di specificare uno spazio dei nomi. Lo spazio dei nomi è documentato in -:doc:`../core-api/symbol-namespaces` +:doc:`../../../core-api/symbol-namespaces` :c:func:`EXPORT_SYMBOL_NS_GPL()` -------------------------------- @@ -643,7 +643,7 @@ Definita in ``include/linux/export.h`` Questa è una variate di `EXPORT_SYMBOL_GPL()` che permette di specificare uno spazio dei nomi. Lo spazio dei nomi è documentato in -:doc:`../core-api/symbol-namespaces` +:doc:`../../../core-api/symbol-namespaces` Procedure e convenzioni ======================= diff --git a/Documentation/translations/it_IT/process/email-clients.rst b/Documentation/translations/it_IT/process/email-clients.rst index 89abf6d325f2..66d3d65776f7 100644 --- a/Documentation/translations/it_IT/process/email-clients.rst +++ b/Documentation/translations/it_IT/process/email-clients.rst @@ -3,6 +3,8 @@ :Original: :doc:`../../../process/email-clients` :Translator: Alessia Mantegazza <amantegazza@vaga.pv.it> +.. _it_email_clients: + Informazioni sui programmi di posta elettronica per Linux ========================================================= diff --git a/Documentation/translations/it_IT/process/management-style.rst b/Documentation/translations/it_IT/process/management-style.rst index c709285138a7..76ed074082ea 100644 --- a/Documentation/translations/it_IT/process/management-style.rst +++ b/Documentation/translations/it_IT/process/management-style.rst @@ -3,6 +3,8 @@ :Original: :doc:`../../../process/management-style` :Translator: Alessia Mantegazza <amantegazza@vaga.pv.it> +.. _it_managementstyle: + Il modello di gestione del kernel Linux ======================================= diff --git a/Documentation/translations/ko_KR/memory-barriers.txt b/Documentation/translations/ko_KR/memory-barriers.txt index e50fe6541335..34d041d68f78 100644 --- a/Documentation/translations/ko_KR/memory-barriers.txt +++ b/Documentation/translations/ko_KR/memory-barriers.txt @@ -1842,12 +1842,15 @@ Mandatory 배리어들은 SMP 시스템에서도 UP 시스템에서도 SMP 효 (*) smp_mb__before_atomic(); (*) smp_mb__after_atomic(); - 이것들은 값을 리턴하지 않는 (더하기, 빼기, 증가, 감소와 같은) 어토믹 - 함수들을 위한, 특히 그것들이 레퍼런스 카운팅에 사용될 때를 위한 - 함수들입니다. 이 함수들은 메모리 배리어를 내포하고 있지는 않습니다. - - 이것들은 값을 리턴하지 않으며 어토믹한 (set_bit 과 clear_bit 같은) 비트 - 연산에도 사용될 수 있습니다. + 이것들은 메모리 배리어를 내포하지 않는 어토믹 RMW 함수를 사용하지만 코드에 + 메모리 배리어가 필요한 경우를 위한 것들입니다. 메모리 배리어를 내포하지 + 않는 어토믹 RMW 함수들의 예로는 더하기, 빼기, (실패한) 조건적 + 오퍼레이션들, _relaxed 함수들이 있으며, atomic_read 나 atomic_set 은 이에 + 해당되지 않습니다. 메모리 배리어가 필요해지는 흔한 예로는 어토믹 + 오퍼레이션을 사용해 레퍼런스 카운트를 수정하는 경우를 들 수 있습니다. + + 이것들은 또한 (set_bit 과 clear_bit 같은) 메모리 배리어를 내포하지 않는 + 어토믹 RMW bitop 함수들을 위해서도 사용될 수 있습니다. 한 예로, 객체 하나를 무효한 것으로 표시하고 그 객체의 레퍼런스 카운트를 감소시키는 다음 코드를 보세요: diff --git a/Documentation/translations/zh_CN/filesystems/debugfs.rst b/Documentation/translations/zh_CN/filesystems/debugfs.rst index f8a28793c277..822c4d42fdf9 100644 --- a/Documentation/translations/zh_CN/filesystems/debugfs.rst +++ b/Documentation/translations/zh_CN/filesystems/debugfs.rst @@ -2,7 +2,7 @@ .. include:: ../disclaimer-zh_CN.rst -:Original: :ref:`Documentation/filesystems/debugfs.txt <debugfs_index>` +:Original: :doc:`../../../filesystems/debugfs` ======= Debugfs diff --git a/Documentation/userspace-api/ioctl/ioctl-number.rst b/Documentation/userspace-api/ioctl/ioctl-number.rst index 1f3da8f32fc1..59472cd6a11d 100644 --- a/Documentation/userspace-api/ioctl/ioctl-number.rst +++ b/Documentation/userspace-api/ioctl/ioctl-number.rst @@ -202,6 +202,7 @@ Code Seq# Include File Comments 'W' 00-1F linux/wanrouter.h conflict! (pre 3.9) 'W' 00-3F sound/asound.h conflict! 'W' 40-5F drivers/pci/switch/switchtec.c +'W' 60-61 linux/watch_queue.h 'X' all fs/xfs/xfs_fs.h, conflict! fs/xfs/linux-2.6/xfs_ioctl32.h, include/linux/falloc.h, diff --git a/Documentation/vm/hmm.rst b/Documentation/vm/hmm.rst index 561969754bc0..6f9e000757fa 100644 --- a/Documentation/vm/hmm.rst +++ b/Documentation/vm/hmm.rst @@ -191,15 +191,15 @@ The usage pattern is:: again: range.notifier_seq = mmu_interval_read_begin(&interval_sub); - down_read(&mm->mmap_sem); + mmap_read_lock(mm); ret = hmm_range_fault(&range); if (ret) { - up_read(&mm->mmap_sem); + mmap_read_unlock(mm); if (ret == -EBUSY) goto again; return ret; } - up_read(&mm->mmap_sem); + mmap_read_unlock(mm); take_lock(driver->update); if (mmu_interval_read_retry(&ni, range.notifier_seq) { diff --git a/Documentation/vm/ksm.rst b/Documentation/vm/ksm.rst index d32016d9be2c..d1b7270ad55c 100644 --- a/Documentation/vm/ksm.rst +++ b/Documentation/vm/ksm.rst @@ -6,7 +6,7 @@ Kernel Samepage Merging KSM is a memory-saving de-duplication feature, enabled by CONFIG_KSM=y, added to the Linux kernel in 2.6.32. See ``mm/ksm.c`` for its implementation, -and http://lwn.net/Articles/306704/ and http://lwn.net/Articles/330589/ +and http://lwn.net/Articles/306704/ and https://lwn.net/Articles/330589/ The userspace interface of KSM is described in :ref:`Documentation/admin-guide/mm/ksm.rst <admin_guide_ksm>` diff --git a/Documentation/vm/transhuge.rst b/Documentation/vm/transhuge.rst index 37c57ca32629..0ed23e59abe5 100644 --- a/Documentation/vm/transhuge.rst +++ b/Documentation/vm/transhuge.rst @@ -98,9 +98,9 @@ split_huge_page() or split_huge_pmd() has a cost. To make pagetable walks huge pmd aware, all you need to do is to call pmd_trans_huge() on the pmd returned by pmd_offset. You must hold the -mmap_sem in read (or write) mode to be sure a huge pmd cannot be +mmap_lock in read (or write) mode to be sure a huge pmd cannot be created from under you by khugepaged (khugepaged collapse_huge_page -takes the mmap_sem in write mode in addition to the anon_vma lock). If +takes the mmap_lock in write mode in addition to the anon_vma lock). If pmd_trans_huge returns false, you just fallback in the old code paths. If instead pmd_trans_huge returns true, you have to take the page table lock (pmd_lock()) and re-run pmd_trans_huge. Taking the diff --git a/Documentation/watch_queue.rst b/Documentation/watch_queue.rst new file mode 100644 index 000000000000..849fad6893ef --- /dev/null +++ b/Documentation/watch_queue.rst @@ -0,0 +1,339 @@ +============================== +General notification mechanism +============================== + +The general notification mechanism is built on top of the standard pipe driver +whereby it effectively splices notification messages from the kernel into pipes +opened by userspace. This can be used in conjunction with:: + + * Key/keyring notifications + + +The notifications buffers can be enabled by: + + "General setup"/"General notification queue" + (CONFIG_WATCH_QUEUE) + +This document has the following sections: + +.. contents:: :local: + + +Overview +======== + +This facility appears as a pipe that is opened in a special mode. The pipe's +internal ring buffer is used to hold messages that are generated by the kernel. +These messages are then read out by read(). Splice and similar are disabled on +such pipes due to them wanting to, under some circumstances, revert their +additions to the ring - which might end up interleaved with notification +messages. + +The owner of the pipe has to tell the kernel which sources it would like to +watch through that pipe. Only sources that have been connected to a pipe will +insert messages into it. Note that a source may be bound to multiple pipes and +insert messages into all of them simultaneously. + +Filters may also be emplaced on a pipe so that certain source types and +subevents can be ignored if they're not of interest. + +A message will be discarded if there isn't a slot available in the ring or if +no preallocated message buffer is available. In both of these cases, read() +will insert a WATCH_META_LOSS_NOTIFICATION message into the output buffer after +the last message currently in the buffer has been read. + +Note that when producing a notification, the kernel does not wait for the +consumers to collect it, but rather just continues on. This means that +notifications can be generated whilst spinlocks are held and also protects the +kernel from being held up indefinitely by a userspace malfunction. + + +Message Structure +================= + +Notification messages begin with a short header:: + + struct watch_notification { + __u32 type:24; + __u32 subtype:8; + __u32 info; + }; + +"type" indicates the source of the notification record and "subtype" indicates +the type of record from that source (see the Watch Sources section below). The +type may also be "WATCH_TYPE_META". This is a special record type generated +internally by the watch queue itself. There are two subtypes: + + * WATCH_META_REMOVAL_NOTIFICATION + * WATCH_META_LOSS_NOTIFICATION + +The first indicates that an object on which a watch was installed was removed +or destroyed and the second indicates that some messages have been lost. + +"info" indicates a bunch of things, including: + + * The length of the message in bytes, including the header (mask with + WATCH_INFO_LENGTH and shift by WATCH_INFO_LENGTH__SHIFT). This indicates + the size of the record, which may be between 8 and 127 bytes. + + * The watch ID (mask with WATCH_INFO_ID and shift by WATCH_INFO_ID__SHIFT). + This indicates that caller's ID of the watch, which may be between 0 + and 255. Multiple watches may share a queue, and this provides a means to + distinguish them. + + * A type-specific field (WATCH_INFO_TYPE_INFO). This is set by the + notification producer to indicate some meaning specific to the type and + subtype. + +Everything in info apart from the length can be used for filtering. + +The header can be followed by supplementary information. The format of this is +at the discretion is defined by the type and subtype. + + +Watch List (Notification Source) API +==================================== + +A "watch list" is a list of watchers that are subscribed to a source of +notifications. A list may be attached to an object (say a key or a superblock) +or may be global (say for device events). From a userspace perspective, a +non-global watch list is typically referred to by reference to the object it +belongs to (such as using KEYCTL_NOTIFY and giving it a key serial number to +watch that specific key). + +To manage a watch list, the following functions are provided: + + * ``void init_watch_list(struct watch_list *wlist, + void (*release_watch)(struct watch *wlist));`` + + Initialise a watch list. If ``release_watch`` is not NULL, then this + indicates a function that should be called when the watch_list object is + destroyed to discard any references the watch list holds on the watched + object. + + * ``void remove_watch_list(struct watch_list *wlist);`` + + This removes all of the watches subscribed to a watch_list and frees them + and then destroys the watch_list object itself. + + +Watch Queue (Notification Output) API +===================================== + +A "watch queue" is the buffer allocated by an application that notification +records will be written into. The workings of this are hidden entirely inside +of the pipe device driver, but it is necessary to gain a reference to it to set +a watch. These can be managed with: + + * ``struct watch_queue *get_watch_queue(int fd);`` + + Since watch queues are indicated to the kernel by the fd of the pipe that + implements the buffer, userspace must hand that fd through a system call. + This can be used to look up an opaque pointer to the watch queue from the + system call. + + * ``void put_watch_queue(struct watch_queue *wqueue);`` + + This discards the reference obtained from ``get_watch_queue()``. + + +Watch Subscription API +====================== + +A "watch" is a subscription on a watch list, indicating the watch queue, and +thus the buffer, into which notification records should be written. The watch +queue object may also carry filtering rules for that object, as set by +userspace. Some parts of the watch struct can be set by the driver:: + + struct watch { + union { + u32 info_id; /* ID to be OR'd in to info field */ + ... + }; + void *private; /* Private data for the watched object */ + u64 id; /* Internal identifier */ + ... + }; + +The ``info_id`` value should be an 8-bit number obtained from userspace and +shifted by WATCH_INFO_ID__SHIFT. This is OR'd into the WATCH_INFO_ID field of +struct watch_notification::info when and if the notification is written into +the associated watch queue buffer. + +The ``private`` field is the driver's data associated with the watch_list and +is cleaned up by the ``watch_list::release_watch()`` method. + +The ``id`` field is the source's ID. Notifications that are posted with a +different ID are ignored. + +The following functions are provided to manage watches: + + * ``void init_watch(struct watch *watch, struct watch_queue *wqueue);`` + + Initialise a watch object, setting its pointer to the watch queue, using + appropriate barriering to avoid lockdep complaints. + + * ``int add_watch_to_object(struct watch *watch, struct watch_list *wlist);`` + + Subscribe a watch to a watch list (notification source). The + driver-settable fields in the watch struct must have been set before this + is called. + + * ``int remove_watch_from_object(struct watch_list *wlist, + struct watch_queue *wqueue, + u64 id, false);`` + + Remove a watch from a watch list, where the watch must match the specified + watch queue (``wqueue``) and object identifier (``id``). A notification + (``WATCH_META_REMOVAL_NOTIFICATION``) is sent to the watch queue to + indicate that the watch got removed. + + * ``int remove_watch_from_object(struct watch_list *wlist, NULL, 0, true);`` + + Remove all the watches from a watch list. It is expected that this will be + called preparatory to destruction and that the watch list will be + inaccessible to new watches by this point. A notification + (``WATCH_META_REMOVAL_NOTIFICATION``) is sent to the watch queue of each + subscribed watch to indicate that the watch got removed. + + +Notification Posting API +======================== + +To post a notification to watch list so that the subscribed watches can see it, +the following function should be used:: + + void post_watch_notification(struct watch_list *wlist, + struct watch_notification *n, + const struct cred *cred, + u64 id); + +The notification should be preformatted and a pointer to the header (``n``) +should be passed in. The notification may be larger than this and the size in +units of buffer slots is noted in ``n->info & WATCH_INFO_LENGTH``. + +The ``cred`` struct indicates the credentials of the source (subject) and is +passed to the LSMs, such as SELinux, to allow or suppress the recording of the +note in each individual queue according to the credentials of that queue +(object). + +The ``id`` is the ID of the source object (such as the serial number on a key). +Only watches that have the same ID set in them will see this notification. + + +Watch Sources +============= + +Any particular buffer can be fed from multiple sources. Sources include: + + * WATCH_TYPE_KEY_NOTIFY + + Notifications of this type indicate changes to keys and keyrings, including + the changes of keyring contents or the attributes of keys. + + See Documentation/security/keys/core.rst for more information. + + +Event Filtering +=============== + +Once a watch queue has been created, a set of filters can be applied to limit +the events that are received using:: + + struct watch_notification_filter filter = { + ... + }; + ioctl(fd, IOC_WATCH_QUEUE_SET_FILTER, &filter) + +The filter description is a variable of type:: + + struct watch_notification_filter { + __u32 nr_filters; + __u32 __reserved; + struct watch_notification_type_filter filters[]; + }; + +Where "nr_filters" is the number of filters in filters[] and "__reserved" +should be 0. The "filters" array has elements of the following type:: + + struct watch_notification_type_filter { + __u32 type; + __u32 info_filter; + __u32 info_mask; + __u32 subtype_filter[8]; + }; + +Where: + + * ``type`` is the event type to filter for and should be something like + "WATCH_TYPE_KEY_NOTIFY" + + * ``info_filter`` and ``info_mask`` act as a filter on the info field of the + notification record. The notification is only written into the buffer if:: + + (watch.info & info_mask) == info_filter + + This could be used, for example, to ignore events that are not exactly on + the watched point in a mount tree. + + * ``subtype_filter`` is a bitmask indicating the subtypes that are of + interest. Bit 0 of subtype_filter[0] corresponds to subtype 0, bit 1 to + subtype 1, and so on. + +If the argument to the ioctl() is NULL, then the filters will be removed and +all events from the watched sources will come through. + + +Userspace Code Example +====================== + +A buffer is created with something like the following:: + + pipe2(fds, O_TMPFILE); + ioctl(fds[1], IOC_WATCH_QUEUE_SET_SIZE, 256); + +It can then be set to receive keyring change notifications:: + + keyctl(KEYCTL_WATCH_KEY, KEY_SPEC_SESSION_KEYRING, fds[1], 0x01); + +The notifications can then be consumed by something like the following:: + + static void consumer(int rfd, struct watch_queue_buffer *buf) + { + unsigned char buffer[128]; + ssize_t buf_len; + + while (buf_len = read(rfd, buffer, sizeof(buffer)), + buf_len > 0 + ) { + void *p = buffer; + void *end = buffer + buf_len; + while (p < end) { + union { + struct watch_notification n; + unsigned char buf1[128]; + } n; + size_t largest, len; + + largest = end - p; + if (largest > 128) + largest = 128; + memcpy(&n, p, largest); + + len = (n->info & WATCH_INFO_LENGTH) >> + WATCH_INFO_LENGTH__SHIFT; + if (len == 0 || len > largest) + return; + + switch (n.n.type) { + case WATCH_TYPE_META: + got_meta(&n.n); + case WATCH_TYPE_KEY_NOTIFY: + saw_key_change(&n.n); + break; + } + + p += len; + } + } + } diff --git a/Documentation/xz.txt b/Documentation/xz.txt index b2220d03aa50..b2f5ff12a161 100644 --- a/Documentation/xz.txt +++ b/Documentation/xz.txt @@ -14,13 +14,13 @@ improve compression ratio of executable data. The XZ decompressor in Linux is called XZ Embedded. It supports the LZMA2 filter and optionally also BCJ filters. CRC32 is supported for integrity checking. The home page of XZ Embedded is at -<http://tukaani.org/xz/embedded.html>, where you can find the +<https://tukaani.org/xz/embedded.html>, where you can find the latest version and also information about using the code outside the Linux kernel. For userspace, XZ Utils provide a zlib-like compression library and a gzip-like command line tool. XZ Utils can be downloaded from -<http://tukaani.org/xz/>. +<https://tukaani.org/xz/>. XZ related components in the kernel =================================== @@ -113,7 +113,7 @@ Reporting bugs ============== Before reporting a bug, please check that it's not fixed already -at upstream. See <http://tukaani.org/xz/embedded.html> to get the +at upstream. See <https://tukaani.org/xz/embedded.html> to get the latest code. Report bugs to <lasse.collin@tukaani.org> or visit #tukaani on |