diff options
Diffstat (limited to 'Documentation')
220 files changed, 3422 insertions, 1122 deletions
diff --git a/Documentation/ABI/testing/sysfs-devices-system-cpu b/Documentation/ABI/testing/sysfs-devices-system-cpu index f54867cadb0f..ecd585ca2d50 100644 --- a/Documentation/ABI/testing/sysfs-devices-system-cpu +++ b/Documentation/ABI/testing/sysfs-devices-system-cpu @@ -670,7 +670,7 @@ Description: Preferred MTE tag checking mode "async" Prefer asynchronous mode ================ ============================================== - See also: Documentation/arm64/memory-tagging-extension.rst + See also: Documentation/arch/arm64/memory-tagging-extension.rst What: /sys/devices/system/cpu/nohz_full Date: Apr 2015 diff --git a/Documentation/RCU/Design/Requirements/Requirements.rst b/Documentation/RCU/Design/Requirements/Requirements.rst index 49387d823619..f3b605285a87 100644 --- a/Documentation/RCU/Design/Requirements/Requirements.rst +++ b/Documentation/RCU/Design/Requirements/Requirements.rst @@ -2071,41 +2071,7 @@ call. Because RCU avoids interrupting idle CPUs, it is illegal to execute an RCU read-side critical section on an idle CPU. (Kernels built with -``CONFIG_PROVE_RCU=y`` will splat if you try it.) The RCU_NONIDLE() -macro and ``_rcuidle`` event tracing is provided to work around this -restriction. In addition, rcu_is_watching() may be used to test -whether or not it is currently legal to run RCU read-side critical -sections on this CPU. I learned of the need for diagnostics on the one -hand and RCU_NONIDLE() on the other while inspecting idle-loop code. -Steven Rostedt supplied ``_rcuidle`` event tracing, which is used quite -heavily in the idle loop. However, there are some restrictions on the -code placed within RCU_NONIDLE(): - -#. Blocking is prohibited. In practice, this is not a serious - restriction given that idle tasks are prohibited from blocking to - begin with. -#. Although nesting RCU_NONIDLE() is permitted, they cannot nest - indefinitely deeply. However, given that they can be nested on the - order of a million deep, even on 32-bit systems, this should not be a - serious restriction. This nesting limit would probably be reached - long after the compiler OOMed or the stack overflowed. -#. Any code path that enters RCU_NONIDLE() must sequence out of that - same RCU_NONIDLE(). For example, the following is grossly - illegal: - - :: - - 1 RCU_NONIDLE({ - 2 do_something(); - 3 goto bad_idea; /* BUG!!! */ - 4 do_something_else();}); - 5 bad_idea: - - - It is just as illegal to transfer control into the middle of - RCU_NONIDLE()'s argument. Yes, in theory, you could transfer in - as long as you also transferred out, but in practice you could also - expect to get sharply worded review comments. +``CONFIG_PROVE_RCU=y`` will splat if you try it.) It is similarly socially unacceptable to interrupt an ``nohz_full`` CPU running in userspace. RCU must therefore track ``nohz_full`` userspace diff --git a/Documentation/RCU/whatisRCU.rst b/Documentation/RCU/whatisRCU.rst index 8eddef28d3a1..e488c8e557a9 100644 --- a/Documentation/RCU/whatisRCU.rst +++ b/Documentation/RCU/whatisRCU.rst @@ -1117,7 +1117,6 @@ All: lockdep-checked RCU utility APIs:: RCU_LOCKDEP_WARN rcu_sleep_check - RCU_NONIDLE All: Unchecked RCU-protected pointer access:: diff --git a/Documentation/admin-guide/bcache.rst b/Documentation/admin-guide/bcache.rst index bb5032a99234..6fdb495ac466 100644 --- a/Documentation/admin-guide/bcache.rst +++ b/Documentation/admin-guide/bcache.rst @@ -508,9 +508,6 @@ cache_miss_collisions cache miss, but raced with a write and data was already present (usually 0 since the synchronization for cache misses was rewritten) -cache_readaheads - Count of times readahead occurred. - Sysfs - cache set ~~~~~~~~~~~~~~~~~ diff --git a/Documentation/admin-guide/cgroup-v1/memory.rst b/Documentation/admin-guide/cgroup-v1/memory.rst index 47d1d7d932a8..fabaad3fd9c2 100644 --- a/Documentation/admin-guide/cgroup-v1/memory.rst +++ b/Documentation/admin-guide/cgroup-v1/memory.rst @@ -297,7 +297,7 @@ Lock order is as follows:: Page lock (PG_locked bit of page->flags) mm->page_table_lock or split pte_lock - lock_page_memcg (memcg->move_lock) + folio_memcg_lock (memcg->move_lock) mapping->i_pages lock lruvec->lru_lock. diff --git a/Documentation/admin-guide/cgroup-v2.rst b/Documentation/admin-guide/cgroup-v2.rst index e592a9364473..4ef890191196 100644 --- a/Documentation/admin-guide/cgroup-v2.rst +++ b/Documentation/admin-guide/cgroup-v2.rst @@ -1580,6 +1580,13 @@ PAGE_SIZE multiple when read back. Healthy workloads are not expected to reach this limit. + memory.swap.peak + A read-only single value file which exists on non-root + cgroups. + + The max swap usage recorded for the cgroup and its + descendants since the creation of the cgroup. + memory.swap.max A read-write single value file which exists on non-root cgroups. The default is "max". @@ -2022,31 +2029,33 @@ that attribute: no-change Do not modify the I/O priority class. - none-to-rt - For requests that do not have an I/O priority class (NONE), - change the I/O priority class into RT. Do not modify - the I/O priority class of other requests. + promote-to-rt + For requests that have a non-RT I/O priority class, change it into RT. + Also change the priority level of these requests to 4. Do not modify + the I/O priority of requests that have priority class RT. restrict-to-be For requests that do not have an I/O priority class or that have I/O - priority class RT, change it into BE. Do not modify the I/O priority - class of requests that have priority class IDLE. + priority class RT, change it into BE. Also change the priority level + of these requests to 0. Do not modify the I/O priority class of + requests that have priority class IDLE. idle Change the I/O priority class of all requests into IDLE, the lowest I/O priority class. + none-to-rt + Deprecated. Just an alias for promote-to-rt. + The following numerical values are associated with the I/O priority policies: -+-------------+---+ -| no-change | 0 | -+-------------+---+ -| none-to-rt | 1 | -+-------------+---+ -| rt-to-be | 2 | -+-------------+---+ -| all-to-idle | 3 | -+-------------+---+ ++----------------+---+ +| no-change | 0 | ++----------------+---+ +| rt-to-be | 2 | ++----------------+---+ +| all-to-idle | 3 | ++----------------+---+ The numerical value that corresponds to each I/O priority class is as follows: @@ -2062,9 +2071,13 @@ The numerical value that corresponds to each I/O priority class is as follows: The algorithm to set the I/O priority class for a request is as follows: -- Translate the I/O priority class policy into a number. -- Change the request I/O priority class into the maximum of the I/O priority - class policy number and the numerical I/O priority class. +- If I/O priority class policy is promote-to-rt, change the request I/O + priority class to IOPRIO_CLASS_RT and change the request I/O priority + level to 4. +- If I/O priorityt class is not promote-to-rt, translate the I/O priority + class policy into a number, then change the request I/O priority class + into the maximum of the I/O priority class policy number and the numerical + I/O priority class. PID --- @@ -2437,7 +2450,7 @@ Miscellaneous controller provides 3 interface files. If two misc resources (res_ res_b 10 misc.current - A read-only flat-keyed file shown in the non-root cgroups. It shows + A read-only flat-keyed file shown in the all cgroups. It shows the current usage of the resources in the cgroup and its children.:: $ cat misc.current diff --git a/Documentation/admin-guide/kernel-parameters.txt b/Documentation/admin-guide/kernel-parameters.txt index 9e5bab29685f..d172651ed914 100644 --- a/Documentation/admin-guide/kernel-parameters.txt +++ b/Documentation/admin-guide/kernel-parameters.txt @@ -304,7 +304,7 @@ EL0 is indicated by /sys/devices/system/cpu/aarch32_el0 and hot-unplug operations may be restricted. - See Documentation/arm64/asymmetric-32bit.rst for more + See Documentation/arch/arm64/asymmetric-32bit.rst for more information. amd_iommu= [HW,X86-64] @@ -429,6 +429,9 @@ arm64.nosme [ARM64] Unconditionally disable Scalable Matrix Extension support + arm64.nomops [ARM64] Unconditionally disable Memory Copy and Memory + Set instructions support + ataflop= [HW,M68k] atarimouse= [HW,MOUSE] Atari Mouse @@ -818,20 +821,6 @@ Format: <first_slot>,<last_slot>,<port>,<enum_bit>[,<debug>] - cpu0_hotplug [X86] Turn on CPU0 hotplug feature when - CONFIG_BOOTPARAM_HOTPLUG_CPU0 is off. - Some features depend on CPU0. Known dependencies are: - 1. Resume from suspend/hibernate depends on CPU0. - Suspend/hibernate will fail if CPU0 is offline and you - need to online CPU0 before suspend/hibernate. - 2. PIC interrupts also depend on CPU0. CPU0 can't be - removed if a PIC interrupt is detected. - It's said poweroff/reboot may depend on CPU0 on some - machines although I haven't seen such issues so far - after CPU0 is offline on a few tested machines. - If the dependencies are under your control, you can - turn on cpu0_hotplug. - cpuidle.off=1 [CPU_IDLE] disable the cpuidle sub-system @@ -852,6 +841,12 @@ on every CPU online, such as boot, and resume from suspend. Default: 10000 + cpuhp.parallel= + [SMP] Enable/disable parallel bringup of secondary CPUs + Format: <bool> + Default is enabled if CONFIG_HOTPLUG_PARALLEL=y. Otherwise + the parameter has no effect. + crash_kexec_post_notifiers Run kdump after running panic-notifiers and dumping kmsg. This only for the users who doubt kdump always @@ -2117,6 +2112,16 @@ disable Do not enable intel_pstate as the default scaling driver for the supported processors + active + Use intel_pstate driver to bypass the scaling + governors layer of cpufreq and provides it own + algorithms for p-state selection. There are two + P-state selection algorithms provided by + intel_pstate in the active mode: powersave and + performance. The way they both operate depends + on whether or not the hardware managed P-states + (HWP) feature has been enabled in the processor + and possibly on the processor model. passive Use intel_pstate as a scaling driver, but configure it to work with generic cpufreq governors (instead of @@ -2551,12 +2556,13 @@ If the value is 0 (the default), KVM will pick a period based on the ratio, such that a page is zapped after 1 hour on average. - kvm-amd.nested= [KVM,AMD] Allow nested virtualization in KVM/SVM. - Default is 1 (enabled) + kvm-amd.nested= [KVM,AMD] Control nested virtualization feature in + KVM/SVM. Default is 1 (enabled). - kvm-amd.npt= [KVM,AMD] Disable nested paging (virtualized MMU) - for all guests. - Default is 1 (enabled) if in 64-bit or 32-bit PAE mode. + kvm-amd.npt= [KVM,AMD] Control KVM's use of Nested Page Tables, + a.k.a. Two-Dimensional Page Tables. Default is 1 + (enabled). Disable by KVM if hardware lacks support + for NPT. kvm-arm.mode= [KVM,ARM] Select one of KVM/arm64's modes of operation. @@ -2602,30 +2608,33 @@ Format: <integer> Default: 5 - kvm-intel.ept= [KVM,Intel] Disable extended page tables - (virtualized MMU) support on capable Intel chips. - Default is 1 (enabled) + kvm-intel.ept= [KVM,Intel] Control KVM's use of Extended Page Tables, + a.k.a. Two-Dimensional Page Tables. Default is 1 + (enabled). Disable by KVM if hardware lacks support + for EPT. kvm-intel.emulate_invalid_guest_state= - [KVM,Intel] Disable emulation of invalid guest state. - Ignored if kvm-intel.enable_unrestricted_guest=1, as - guest state is never invalid for unrestricted guests. - This param doesn't apply to nested guests (L2), as KVM - never emulates invalid L2 guest state. - Default is 1 (enabled) + [KVM,Intel] Control whether to emulate invalid guest + state. Ignored if kvm-intel.enable_unrestricted_guest=1, + as guest state is never invalid for unrestricted + guests. This param doesn't apply to nested guests (L2), + as KVM never emulates invalid L2 guest state. + Default is 1 (enabled). kvm-intel.flexpriority= - [KVM,Intel] Disable FlexPriority feature (TPR shadow). - Default is 1 (enabled) + [KVM,Intel] Control KVM's use of FlexPriority feature + (TPR shadow). Default is 1 (enabled). Disalbe by KVM if + hardware lacks support for it. kvm-intel.nested= - [KVM,Intel] Enable VMX nesting (nVMX). - Default is 0 (disabled) + [KVM,Intel] Control nested virtualization feature in + KVM/VMX. Default is 1 (enabled). kvm-intel.unrestricted_guest= - [KVM,Intel] Disable unrestricted guest feature - (virtualized real and unpaged mode) on capable - Intel chips. Default is 1 (enabled) + [KVM,Intel] Control KVM's use of unrestricted guest + feature (virtualized real and unpaged mode). Default + is 1 (enabled). Disable by KVM if EPT is disabled or + hardware lacks support for it. kvm-intel.vmentry_l1d_flush=[KVM,Intel] Mitigation for L1 Terminal Fault CVE-2018-3620. @@ -2639,9 +2648,10 @@ Default is cond (do L1 cache flush in specific instances) - kvm-intel.vpid= [KVM,Intel] Disable Virtual Processor Identification - feature (tagged TLBs) on capable Intel chips. - Default is 1 (enabled) + kvm-intel.vpid= [KVM,Intel] Control KVM's use of Virtual Processor + Identification feature (tagged TLBs). Default is 1 + (enabled). Disable by KVM if hardware lacks support + for it. l1d_flush= [X86,INTEL] Control mitigation for L1D based snooping vulnerability. @@ -3423,6 +3433,10 @@ [HW] Make the MicroTouch USB driver use raw coordinates ('y', default) or cooked coordinates ('n') + mtrr=debug [X86] + Enable printing debug information related to MTRR + registers at boot time. + mtrr_chunk_size=nn[KMG] [X86] used for mtrr cleanup. It is largest continuous chunk that could hold holes aka. UC entries. @@ -4736,43 +4750,6 @@ the propagation of recent CPU-hotplug changes up the rcu_node combining tree. - rcutree.use_softirq= [KNL] - If set to zero, move all RCU_SOFTIRQ processing to - per-CPU rcuc kthreads. Defaults to a non-zero - value, meaning that RCU_SOFTIRQ is used by default. - Specify rcutree.use_softirq=0 to use rcuc kthreads. - - But note that CONFIG_PREEMPT_RT=y kernels disable - this kernel boot parameter, forcibly setting it - to zero. - - rcutree.rcu_fanout_exact= [KNL] - Disable autobalancing of the rcu_node combining - tree. This is used by rcutorture, and might - possibly be useful for architectures having high - cache-to-cache transfer latencies. - - rcutree.rcu_fanout_leaf= [KNL] - Change the number of CPUs assigned to each - leaf rcu_node structure. Useful for very - large systems, which will choose the value 64, - and for NUMA systems with large remote-access - latencies, which will choose a value aligned - with the appropriate hardware boundaries. - - rcutree.rcu_min_cached_objs= [KNL] - Minimum number of objects which are cached and - maintained per one CPU. Object size is equal - to PAGE_SIZE. The cache allows to reduce the - pressure to page allocator, also it makes the - whole algorithm to behave better in low memory - condition. - - rcutree.rcu_delay_page_cache_fill_msec= [KNL] - Set the page-cache refill delay (in milliseconds) - in response to low-memory conditions. The range - of permitted values is in the range 0:100000. - rcutree.jiffies_till_first_fqs= [KNL] Set delay from grace-period initialization to first attempt to force quiescent states. @@ -4811,21 +4788,6 @@ When RCU_NOCB_CPU is set, also adjust the priority of NOCB callback kthreads. - rcutree.rcu_divisor= [KNL] - Set the shift-right count to use to compute - the callback-invocation batch limit bl from - the number of callbacks queued on this CPU. - The result will be bounded below by the value of - the rcutree.blimit kernel parameter. Every bl - callbacks, the softirq handler will exit in - order to allow the CPU to do other work. - - Please note that this callback-invocation batch - limit applies only to non-offloaded callback - invocation. Offloaded callbacks are instead - invoked in the context of an rcuoc kthread, which - scheduler will preempt as it does any other task. - rcutree.nocb_nobypass_lim_per_jiffy= [KNL] On callback-offloaded (rcu_nocbs) CPUs, RCU reduces the lock contention that would @@ -4839,14 +4801,6 @@ the ->nocb_bypass queue. The definition of "too many" is supplied by this kernel boot parameter. - rcutree.rcu_nocb_gp_stride= [KNL] - Set the number of NOCB callback kthreads in - each group, which defaults to the square root - of the number of CPUs. Larger numbers reduce - the wakeup overhead on the global grace-period - kthread, but increases that same overhead on - each group's NOCB grace-period kthread. - rcutree.qhimark= [KNL] Set threshold of queued RCU callbacks beyond which batch limiting is disabled. @@ -4864,6 +4818,56 @@ on rcutree.qhimark at boot time and to zero to disable more aggressive help enlistment. + rcutree.rcu_delay_page_cache_fill_msec= [KNL] + Set the page-cache refill delay (in milliseconds) + in response to low-memory conditions. The range + of permitted values is in the range 0:100000. + + rcutree.rcu_divisor= [KNL] + Set the shift-right count to use to compute + the callback-invocation batch limit bl from + the number of callbacks queued on this CPU. + The result will be bounded below by the value of + the rcutree.blimit kernel parameter. Every bl + callbacks, the softirq handler will exit in + order to allow the CPU to do other work. + + Please note that this callback-invocation batch + limit applies only to non-offloaded callback + invocation. Offloaded callbacks are instead + invoked in the context of an rcuoc kthread, which + scheduler will preempt as it does any other task. + + rcutree.rcu_fanout_exact= [KNL] + Disable autobalancing of the rcu_node combining + tree. This is used by rcutorture, and might + possibly be useful for architectures having high + cache-to-cache transfer latencies. + + rcutree.rcu_fanout_leaf= [KNL] + Change the number of CPUs assigned to each + leaf rcu_node structure. Useful for very + large systems, which will choose the value 64, + and for NUMA systems with large remote-access + latencies, which will choose a value aligned + with the appropriate hardware boundaries. + + rcutree.rcu_min_cached_objs= [KNL] + Minimum number of objects which are cached and + maintained per one CPU. Object size is equal + to PAGE_SIZE. The cache allows to reduce the + pressure to page allocator, also it makes the + whole algorithm to behave better in low memory + condition. + + rcutree.rcu_nocb_gp_stride= [KNL] + Set the number of NOCB callback kthreads in + each group, which defaults to the square root + of the number of CPUs. Larger numbers reduce + the wakeup overhead on the global grace-period + kthread, but increases that same overhead on + each group's NOCB grace-period kthread. + rcutree.rcu_kick_kthreads= [KNL] Cause the grace-period kthread to get an extra wake_up() if it sleeps three times longer than @@ -4871,6 +4875,13 @@ This wake_up() will be accompanied by a WARN_ONCE() splat and an ftrace_dump(). + rcutree.rcu_resched_ns= [KNL] + Limit the time spend invoking a batch of RCU + callbacks to the specified number of nanoseconds. + By default, this limit is checked only once + every 32 callbacks in order to limit the pain + inflicted by local_clock() overhead. + rcutree.rcu_unlock_delay= [KNL] In CONFIG_RCU_STRICT_GRACE_PERIOD=y kernels, this specifies an rcu_read_unlock()-time delay @@ -4885,6 +4896,16 @@ rcu_node tree with an eye towards determining why a new grace period has not yet started. + rcutree.use_softirq= [KNL] + If set to zero, move all RCU_SOFTIRQ processing to + per-CPU rcuc kthreads. Defaults to a non-zero + value, meaning that RCU_SOFTIRQ is used by default. + Specify rcutree.use_softirq=0 to use rcuc kthreads. + + But note that CONFIG_PREEMPT_RT=y kernels disable + this kernel boot parameter, forcibly setting it + to zero. + rcuscale.gp_async= [KNL] Measure performance of asynchronous grace-period primitives such as call_rcu(). @@ -5087,8 +5108,17 @@ rcutorture.stall_cpu_block= [KNL] Sleep while stalling if set. This will result - in warnings from preemptible RCU in addition - to any other stall-related activity. + in warnings from preemptible RCU in addition to + any other stall-related activity. Note that + in kernels built with CONFIG_PREEMPTION=n and + CONFIG_PREEMPT_COUNT=y, this parameter will + cause the CPU to pass through a quiescent state. + Given CONFIG_PREEMPTION=n, this will suppress + RCU CPU stall warnings, but will instead result + in scheduling-while-atomic splats. + + Use of this module parameter results in splats. + rcutorture.stall_cpu_holdoff= [KNL] Time to wait (s) after boot before inducing stall. @@ -5452,7 +5482,12 @@ port and the regular usb controller gets disabled. root= [KNL] Root filesystem - See name_to_dev_t comment in init/do_mounts.c. + Usually this a a block device specifier of some kind, + see the early_lookup_bdev comment in + block/early-lookup.c for details. + Alternatively this can be "ram" for the legacy initial + ramdisk, "nfs" and "cifs" for root on a network file + system, or "mtd" and "ubi" for mounting from raw flash. rootdelay= [KNL] Delay (in seconds) to pause before attempting to mount the root filesystem @@ -6563,6 +6598,12 @@ unknown_nmi_panic [X86] Cause panic on unknown NMI. + unwind_debug [X86-64] + Enable unwinder debug output. This can be + useful for debugging certain unwinder error + conditions, including corrupt stacks and + bad/missing unwinder metadata. + usbcore.authorized_default= [USB] Default USB device authorization: (default -1 = authorized except for wireless USB, @@ -6931,6 +6972,18 @@ it can be updated at runtime by writing to the corresponding sysfs file. + workqueue.cpu_intensive_thresh_us= + Per-cpu work items which run for longer than this + threshold are automatically considered CPU intensive + and excluded from concurrency management to prevent + them from noticeably delaying other per-cpu work + items. Default is 10000 (10ms). + + If CONFIG_WQ_CPU_INTENSIVE_REPORT is set, the kernel + will report the work functions which violate this + threshold repeatedly. They are likely good + candidates for using WQ_UNBOUND workqueues instead. + workqueue.disable_numa By default, all work items queued to unbound workqueues are affine to the NUMA nodes they're diff --git a/Documentation/admin-guide/mm/damon/start.rst b/Documentation/admin-guide/mm/damon/start.rst index 9f88afc734da..7aa0071ff1c3 100644 --- a/Documentation/admin-guide/mm/damon/start.rst +++ b/Documentation/admin-guide/mm/damon/start.rst @@ -119,9 +119,9 @@ set size has chronologically changed.:: Data Access Pattern Aware Memory Management =========================================== -Below three commands make every memory region of size >=4K that doesn't -accessed for >=60 seconds in your workload to be swapped out. :: +Below command makes every memory region of size >=4K that has not accessed for +>=60 seconds in your workload to be swapped out. :: - $ echo "#min-size max-size min-acc max-acc min-age max-age action" > test_scheme - $ echo "4K max 0 0 60s max pageout" >> test_scheme - $ damo schemes -c test_scheme <pid of your workload> + $ sudo damo schemes --damos_access_rate 0 0 --damos_sz_region 4K max \ + --damos_age 60s max --damos_action pageout \ + <pid of your workload> diff --git a/Documentation/admin-guide/mm/damon/usage.rst b/Documentation/admin-guide/mm/damon/usage.rst index 9b823fec974d..2d495fa85a0e 100644 --- a/Documentation/admin-guide/mm/damon/usage.rst +++ b/Documentation/admin-guide/mm/damon/usage.rst @@ -10,9 +10,8 @@ DAMON provides below interfaces for different users. `This <https://github.com/awslabs/damo>`_ is for privileged people such as system administrators who want a just-working human-friendly interface. Using this, users can use the DAMON’s major features in a human-friendly way. - It may not be highly tuned for special cases, though. It supports both - virtual and physical address spaces monitoring. For more detail, please - refer to its `usage document + It may not be highly tuned for special cases, though. For more detail, + please refer to its `usage document <https://github.com/awslabs/damo/blob/next/USAGE.md>`_. - *sysfs interface.* :ref:`This <sysfs_interface>` is for privileged user space programmers who @@ -20,11 +19,7 @@ DAMON provides below interfaces for different users. features by reading from and writing to special sysfs files. Therefore, you can write and use your personalized DAMON sysfs wrapper programs that reads/writes the sysfs files instead of you. The `DAMON user space tool - <https://github.com/awslabs/damo>`_ is one example of such programs. It - supports both virtual and physical address spaces monitoring. Note that this - interface provides only simple :ref:`statistics <damos_stats>` for the - monitoring results. For detailed monitoring results, DAMON provides a - :ref:`tracepoint <tracepoint>`. + <https://github.com/awslabs/damo>`_ is one example of such programs. - *debugfs interface. (DEPRECATED!)* :ref:`This <debugfs_interface>` is almost identical to :ref:`sysfs interface <sysfs_interface>`. This is deprecated, so users should move to the @@ -139,7 +134,7 @@ scheme of the kdamond. Writing ``clear_schemes_tried_regions`` to ``state`` file clears the DAMON-based operating scheme action tried regions directory for each DAMON-based operation scheme of the kdamond. For details of the DAMON-based operation scheme action tried regions directory, please refer to -:ref:tried_regions section <sysfs_schemes_tried_regions>`. +:ref:`tried_regions section <sysfs_schemes_tried_regions>`. If the state is ``on``, reading ``pid`` shows the pid of the kdamond thread. @@ -259,12 +254,9 @@ be equal or smaller than ``start`` of directory ``N+1``. contexts/<N>/schemes/ --------------------- -For usual DAMON-based data access aware memory management optimizations, users -would normally want the system to apply a memory management action to a memory -region of a specific access pattern. DAMON receives such formalized operation -schemes from the user and applies those to the target memory regions. Users -can get and set the schemes by reading from and writing to files under this -directory. +The directory for DAMON-based Operation Schemes (:ref:`DAMOS +<damon_design_damos>`). Users can get and set the schemes by reading from and +writing to files under this directory. In the beginning, this directory has only one file, ``nr_schemes``. Writing a number (``N``) to the file creates the number of child directories named ``0`` @@ -277,12 +269,12 @@ In each scheme directory, five directories (``access_pattern``, ``quotas``, ``watermarks``, ``filters``, ``stats``, and ``tried_regions``) and one file (``action``) exist. -The ``action`` file is for setting and getting what action you want to apply to -memory regions having specific access pattern of the interest. The keywords -that can be written to and read from the file and their meaning are as below. +The ``action`` file is for setting and getting the scheme's :ref:`action +<damon_design_damos_action>`. The keywords that can be written to and read +from the file and their meaning are as below. Note that support of each action depends on the running DAMON operations set -`implementation <sysfs_contexts>`. +:ref:`implementation <sysfs_contexts>`. - ``willneed``: Call ``madvise()`` for the region with ``MADV_WILLNEED``. Supported by ``vaddr`` and ``fvaddr`` operations set. @@ -304,32 +296,21 @@ Note that support of each action depends on the running DAMON operations set schemes/<N>/access_pattern/ --------------------------- -The target access pattern of each DAMON-based operation scheme is constructed -with three ranges including the size of the region in bytes, number of -monitored accesses per aggregate interval, and number of aggregated intervals -for the age of the region. +The directory for the target access :ref:`pattern +<damon_design_damos_access_pattern>` of the given DAMON-based operation scheme. Under the ``access_pattern`` directory, three directories (``sz``, ``nr_accesses``, and ``age``) each having two files (``min`` and ``max``) exist. You can set and get the access pattern for the given scheme by writing to and reading from the ``min`` and ``max`` files under ``sz``, -``nr_accesses``, and ``age`` directories, respectively. +``nr_accesses``, and ``age`` directories, respectively. Note that the ``min`` +and the ``max`` form a closed interval. schemes/<N>/quotas/ ------------------- -Optimal ``target access pattern`` for each ``action`` is workload dependent, so -not easy to find. Worse yet, setting a scheme of some action too aggressive -can cause severe overhead. To avoid such overhead, users can limit time and -size quota for each scheme. In detail, users can ask DAMON to try to use only -up to specific time (``time quota``) for applying the action, and to apply the -action to only up to specific amount (``size quota``) of memory regions having -the target access pattern within a given time interval (``reset interval``). - -When the quota limit is expected to be exceeded, DAMON prioritizes found memory -regions of the ``target access pattern`` based on their size, access frequency, -and age. For personalized prioritization, users can set the weights for the -three properties. +The directory for the :ref:`quotas <damon_design_damos_quotas>` of the given +DAMON-based operation scheme. Under ``quotas`` directory, three files (``ms``, ``bytes``, ``reset_interval_ms``) and one directory (``weights``) having three files @@ -337,23 +318,26 @@ Under ``quotas`` directory, three files (``ms``, ``bytes``, You can set the ``time quota`` in milliseconds, ``size quota`` in bytes, and ``reset interval`` in milliseconds by writing the values to the three files, -respectively. You can also set the prioritization weights for size, access -frequency, and age in per-thousand unit by writing the values to the three -files under the ``weights`` directory. +respectively. Then, DAMON tries to use only up to ``time quota`` milliseconds +for applying the ``action`` to memory regions of the ``access_pattern``, and to +apply the action to only up to ``bytes`` bytes of memory regions within the +``reset_interval_ms``. Setting both ``ms`` and ``bytes`` zero disables the +quota limits. + +You can also set the :ref:`prioritization weights +<damon_design_damos_quotas_prioritization>` for size, access frequency, and age +in per-thousand unit by writing the values to the three files under the +``weights`` directory. schemes/<N>/watermarks/ ----------------------- -To allow easy activation and deactivation of each scheme based on system -status, DAMON provides a feature called watermarks. The feature receives five -values called ``metric``, ``interval``, ``high``, ``mid``, and ``low``. The -``metric`` is the system metric such as free memory ratio that can be measured. -If the metric value of the system is higher than the value in ``high`` or lower -than ``low`` at the memoent, the scheme is deactivated. If the value is lower -than ``mid``, the scheme is activated. +The directory for the :ref:`watermarks <damon_design_damos_watermarks>` of the +given DAMON-based operation scheme. Under the watermarks directory, five files (``metric``, ``interval_us``, -``high``, ``mid``, and ``low``) for setting each value exist. You can set and +``high``, ``mid``, and ``low``) for setting the metric, the time interval +between check of the metric, and the three watermarks exist. You can set and get the five values by writing to the files, respectively. Keywords and meanings of those that can be written to the ``metric`` file are @@ -367,12 +351,8 @@ The ``interval`` should written in microseconds unit. schemes/<N>/filters/ -------------------- -Users could know something more than the kernel for specific types of memory. -In the case, users could do their own management for the memory and hence -doesn't want DAMOS bothers that. Users could limit DAMOS by setting the access -pattern of the scheme and/or the monitoring regions for the purpose, but that -can be inefficient in some cases. In such cases, users could set non-access -pattern driven filters using files in this directory. +The directory for the :ref:`filters <damon_design_damos_filters>` of the given +DAMON-based operation scheme. In the beginning, this directory has only one file, ``nr_filters``. Writing a number (``N``) to the file creates the number of child directories named ``0`` @@ -432,13 +412,17 @@ starting from ``0`` under this directory. Each directory contains files exposing detailed information about each of the memory region that the corresponding scheme's ``action`` has tried to be applied under this directory, during next :ref:`aggregation interval <sysfs_monitoring_attrs>`. The -information includes address range, ``nr_accesses``, , and ``age`` of the -region. +information includes address range, ``nr_accesses``, and ``age`` of the region. The directories will be removed when another special keyword, ``clear_schemes_tried_regions``, is written to the relevant ``kdamonds/<N>/state`` file. +The expected usage of this directory is investigations of schemes' behaviors, +and query-like efficient data access monitoring results retrievals. For the +latter use case, in particular, users can set the ``action`` as ``stat`` and +set the ``access pattern`` as their interested pattern that they want to query. + tried_regions/<N>/ ------------------ @@ -600,15 +584,10 @@ update. Schemes ------- -For usual DAMON-based data access aware memory management optimizations, users -would simply want the system to apply a memory management action to a memory -region of a specific access pattern. DAMON receives such formalized operation -schemes from the user and applies those to the target processes. - -Users can get and set the schemes by reading from and writing to ``schemes`` -debugfs file. Reading the file also shows the statistics of each scheme. To -the file, each of the schemes should be represented in each line in below -form:: +Users can get and set the DAMON-based operation :ref:`schemes +<damon_design_damos>` by reading from and writing to ``schemes`` debugfs file. +Reading the file also shows the statistics of each scheme. To the file, each +of the schemes should be represented in each line in below form:: <target access pattern> <action> <quota> <watermarks> @@ -617,8 +596,9 @@ You can disable schemes by simply writing an empty string to the file. Target Access Pattern ~~~~~~~~~~~~~~~~~~~~~ -The ``<target access pattern>`` is constructed with three ranges in below -form:: +The target access :ref:`pattern <damon_design_damos_access_pattern>` of the +scheme. The ``<target access pattern>`` is constructed with three ranges in +below form:: min-size max-size min-acc max-acc min-age max-age @@ -631,9 +611,9 @@ closed interval. Action ~~~~~~ -The ``<action>`` is a predefined integer for memory management actions, which -DAMON will apply to the regions having the target access pattern. The -supported numbers and their meanings are as below. +The ``<action>`` is a predefined integer for memory management :ref:`actions +<damon_design_damos_action>`. The supported numbers and their meanings are as +below. - 0: Call ``madvise()`` for the region with ``MADV_WILLNEED``. Ignored if ``target`` is ``paddr``. @@ -649,10 +629,8 @@ supported numbers and their meanings are as below. Quota ~~~~~ -Optimal ``target access pattern`` for each ``action`` is workload dependent, so -not easy to find. Worse yet, setting a scheme of some action too aggressive -can cause severe overhead. To avoid such overhead, users can limit time and -size quota for the scheme via the ``<quota>`` in below form:: +Users can set the :ref:`quotas <damon_design_damos_quotas>` of the given scheme +via the ``<quota>`` in below form:: <ms> <sz> <reset interval> <priority weights> @@ -662,19 +640,17 @@ the action to memory regions of the ``target access pattern`` within the ``<sz>`` bytes of memory regions within the ``<reset interval>``. Setting both ``<ms>`` and ``<sz>`` zero disables the quota limits. -When the quota limit is expected to be exceeded, DAMON prioritizes found memory -regions of the ``target access pattern`` based on their size, access frequency, -and age. For personalized prioritization, users can set the weights for the -three properties in ``<priority weights>`` in below form:: +For the :ref:`prioritization <damon_design_damos_quotas_prioritization>`, users +can set the weights for the three properties in ``<priority weights>`` in below +form:: <size weight> <access frequency weight> <age weight> Watermarks ~~~~~~~~~~ -Some schemes would need to run based on current value of the system's specific -metrics like free memory ratio. For such cases, users can specify watermarks -for the condition.:: +Users can specify :ref:`watermarks <damon_design_damos_watermarks>` of the +given scheme via ``<watermarks>`` in below form:: <metric> <check interval> <high mark> <middle mark> <low mark> @@ -797,10 +773,12 @@ root directory only. Tracepoint for Monitoring Results ================================= -DAMON provides the monitoring results via a tracepoint, -``damon:damon_aggregated``. While the monitoring is turned on, you could -record the tracepoint events and show results using tracepoint supporting tools -like ``perf``. For example:: +Users can get the monitoring results via the :ref:`tried_regions +<sysfs_schemes_tried_regions>` or a tracepoint, ``damon:damon_aggregated``. +While the tried regions directory is useful for getting a snapshot, the +tracepoint is useful for getting a full record of the results. While the +monitoring is turned on, you could record the tracepoint events and show +results using tracepoint supporting tools like ``perf``. For example:: # echo on > monitor_on # perf record -e damon:damon_aggregated & diff --git a/Documentation/admin-guide/perf/hisi-pmu.rst b/Documentation/admin-guide/perf/hisi-pmu.rst index 546979360513..e0174d20809a 100644 --- a/Documentation/admin-guide/perf/hisi-pmu.rst +++ b/Documentation/admin-guide/perf/hisi-pmu.rst @@ -56,14 +56,14 @@ Example usage of perf:: For HiSilicon uncore PMU v2 whose identifier is 0x30, the topology is the same as PMU v1, but some new functions are added to the hardware. -(a) L3C PMU supports filtering by core/thread within the cluster which can be +1. L3C PMU supports filtering by core/thread within the cluster which can be specified as a bitmap:: $# perf stat -a -e hisi_sccl3_l3c0/config=0x02,tt_core=0x3/ sleep 5 This will only count the operations from core/thread 0 and 1 in this cluster. -(b) Tracetag allow the user to chose to count only read, write or atomic +2. Tracetag allow the user to chose to count only read, write or atomic operations via the tt_req parameeter in perf. The default value counts all operations. tt_req is 3bits, 3'b100 represents read operations, 3'b101 represents write operations, 3'b110 represents atomic store operations and @@ -73,14 +73,16 @@ represents write operations, 3'b110 represents atomic store operations and This will only count the read operations in this cluster. -(c) Datasrc allows the user to check where the data comes from. It is 5 bits. +3. Datasrc allows the user to check where the data comes from. It is 5 bits. Some important codes are as follows: -5'b00001: comes from L3C in this die; -5'b01000: comes from L3C in the cross-die; -5'b01001: comes from L3C which is in another socket; -5'b01110: comes from the local DDR; -5'b01111: comes from the cross-die DDR; -5'b10000: comes from cross-socket DDR; + +- 5'b00001: comes from L3C in this die; +- 5'b01000: comes from L3C in the cross-die; +- 5'b01001: comes from L3C which is in another socket; +- 5'b01110: comes from the local DDR; +- 5'b01111: comes from the cross-die DDR; +- 5'b10000: comes from cross-socket DDR; + etc, it is mainly helpful to find that the data source is nearest from the CPU cores. If datasrc_cfg is used in the multi-chips, the datasrc_skt shall be configured in perf command:: @@ -88,15 +90,25 @@ configured in perf command:: $# perf stat -a -e hisi_sccl3_l3c0/config=0xb9,datasrc_cfg=0xE/, hisi_sccl3_l3c0/config=0xb9,datasrc_cfg=0xF/ sleep 5 -(d)Some HiSilicon SoCs encapsulate multiple CPU and IO dies. Each CPU die +4. Some HiSilicon SoCs encapsulate multiple CPU and IO dies. Each CPU die contains several Compute Clusters (CCLs). The I/O dies are called Super I/O clusters (SICL) containing multiple I/O clusters (ICLs). Each CCL/ICL in the SoC has a unique ID. Each ID is 11bits, include a 6-bit SCCL-ID and 5-bit CCL/ICL-ID. For I/O die, the ICL-ID is followed by: -5'b00000: I/O_MGMT_ICL; -5'b00001: Network_ICL; -5'b00011: HAC_ICL; -5'b10000: PCIe_ICL; + +- 5'b00000: I/O_MGMT_ICL; +- 5'b00001: Network_ICL; +- 5'b00011: HAC_ICL; +- 5'b10000: PCIe_ICL; + +5. uring_channel: UC PMU events 0x47~0x59 supports filtering by tx request +uring channel. It is 2 bits. Some important codes are as follows: + +- 2'b11: count the events which sent to the uring_ext (MATA) channel; +- 2'b01: is the same as 2'b11; +- 2'b10: count the events which sent to the uring (non-MATA) channel; +- 2'b00: default value, count the events which sent to the both uring and + uring_ext channel; Users could configure IDs to count data come from specific CCL/ICL, by setting srcid_cmd & srcid_msk, and data desitined for specific CCL/ICL by setting diff --git a/Documentation/admin-guide/sysctl/kernel.rst b/Documentation/admin-guide/sysctl/kernel.rst index d85d90f5d000..3800fab1619b 100644 --- a/Documentation/admin-guide/sysctl/kernel.rst +++ b/Documentation/admin-guide/sysctl/kernel.rst @@ -949,7 +949,7 @@ user space can read performance monitor counter registers directly. The default value is 0 (access disabled). -See Documentation/arm64/perf.rst for more information. +See Documentation/arch/arm64/perf.rst for more information. pid_max diff --git a/Documentation/arm/arm.rst b/Documentation/arch/arm/arm.rst index 99d660fdf73f..99d660fdf73f 100644 --- a/Documentation/arm/arm.rst +++ b/Documentation/arch/arm/arm.rst diff --git a/Documentation/arm/booting.rst b/Documentation/arch/arm/booting.rst index 5974e37b3d20..5974e37b3d20 100644 --- a/Documentation/arm/booting.rst +++ b/Documentation/arch/arm/booting.rst diff --git a/Documentation/arm/cluster-pm-race-avoidance.rst b/Documentation/arch/arm/cluster-pm-race-avoidance.rst index aa58603d3f28..aa58603d3f28 100644 --- a/Documentation/arm/cluster-pm-race-avoidance.rst +++ b/Documentation/arch/arm/cluster-pm-race-avoidance.rst diff --git a/Documentation/arm/features.rst b/Documentation/arch/arm/features.rst index 7414ec03dd15..7414ec03dd15 100644 --- a/Documentation/arm/features.rst +++ b/Documentation/arch/arm/features.rst diff --git a/Documentation/arm/firmware.rst b/Documentation/arch/arm/firmware.rst index efd844baec1d..efd844baec1d 100644 --- a/Documentation/arm/firmware.rst +++ b/Documentation/arch/arm/firmware.rst diff --git a/Documentation/arm/google/chromebook-boot-flow.rst b/Documentation/arch/arm/google/chromebook-boot-flow.rst index 36da77684bba..36da77684bba 100644 --- a/Documentation/arm/google/chromebook-boot-flow.rst +++ b/Documentation/arch/arm/google/chromebook-boot-flow.rst diff --git a/Documentation/arm/index.rst b/Documentation/arch/arm/index.rst index fd43502ae924..fd43502ae924 100644 --- a/Documentation/arm/index.rst +++ b/Documentation/arch/arm/index.rst diff --git a/Documentation/arm/interrupts.rst b/Documentation/arch/arm/interrupts.rst index 2ae70e0e9732..2ae70e0e9732 100644 --- a/Documentation/arm/interrupts.rst +++ b/Documentation/arch/arm/interrupts.rst diff --git a/Documentation/arm/ixp4xx.rst b/Documentation/arch/arm/ixp4xx.rst index a57235616294..a57235616294 100644 --- a/Documentation/arm/ixp4xx.rst +++ b/Documentation/arch/arm/ixp4xx.rst diff --git a/Documentation/arm/kernel_mode_neon.rst b/Documentation/arch/arm/kernel_mode_neon.rst index 9bfb71a2a9b9..9bfb71a2a9b9 100644 --- a/Documentation/arm/kernel_mode_neon.rst +++ b/Documentation/arch/arm/kernel_mode_neon.rst diff --git a/Documentation/arm/kernel_user_helpers.rst b/Documentation/arch/arm/kernel_user_helpers.rst index eb6f3d916622..eb6f3d916622 100644 --- a/Documentation/arm/kernel_user_helpers.rst +++ b/Documentation/arch/arm/kernel_user_helpers.rst diff --git a/Documentation/arm/keystone/knav-qmss.rst b/Documentation/arch/arm/keystone/knav-qmss.rst index 7f7638d80b42..7f7638d80b42 100644 --- a/Documentation/arm/keystone/knav-qmss.rst +++ b/Documentation/arch/arm/keystone/knav-qmss.rst diff --git a/Documentation/arm/keystone/overview.rst b/Documentation/arch/arm/keystone/overview.rst index cd90298c493c..cd90298c493c 100644 --- a/Documentation/arm/keystone/overview.rst +++ b/Documentation/arch/arm/keystone/overview.rst diff --git a/Documentation/arm/marvell.rst b/Documentation/arch/arm/marvell.rst index 3d369a566038..3d369a566038 100644 --- a/Documentation/arm/marvell.rst +++ b/Documentation/arch/arm/marvell.rst diff --git a/Documentation/arm/mem_alignment.rst b/Documentation/arch/arm/mem_alignment.rst index aa22893b62bc..aa22893b62bc 100644 --- a/Documentation/arm/mem_alignment.rst +++ b/Documentation/arch/arm/mem_alignment.rst diff --git a/Documentation/arm/memory.rst b/Documentation/arch/arm/memory.rst index 0cb1e2938823..0cb1e2938823 100644 --- a/Documentation/arm/memory.rst +++ b/Documentation/arch/arm/memory.rst diff --git a/Documentation/arm/microchip.rst b/Documentation/arch/arm/microchip.rst index e721d855f2c9..e721d855f2c9 100644 --- a/Documentation/arm/microchip.rst +++ b/Documentation/arch/arm/microchip.rst diff --git a/Documentation/arm/netwinder.rst b/Documentation/arch/arm/netwinder.rst index 8eab66caa2ac..8eab66caa2ac 100644 --- a/Documentation/arm/netwinder.rst +++ b/Documentation/arch/arm/netwinder.rst diff --git a/Documentation/arm/nwfpe/index.rst b/Documentation/arch/arm/nwfpe/index.rst index 3c4d2f9aa10e..3c4d2f9aa10e 100644 --- a/Documentation/arm/nwfpe/index.rst +++ b/Documentation/arch/arm/nwfpe/index.rst diff --git a/Documentation/arm/nwfpe/netwinder-fpe.rst b/Documentation/arch/arm/nwfpe/netwinder-fpe.rst index cbb320960fc4..cbb320960fc4 100644 --- a/Documentation/arm/nwfpe/netwinder-fpe.rst +++ b/Documentation/arch/arm/nwfpe/netwinder-fpe.rst diff --git a/Documentation/arm/nwfpe/notes.rst b/Documentation/arch/arm/nwfpe/notes.rst index 102e55af8439..102e55af8439 100644 --- a/Documentation/arm/nwfpe/notes.rst +++ b/Documentation/arch/arm/nwfpe/notes.rst diff --git a/Documentation/arm/nwfpe/nwfpe.rst b/Documentation/arch/arm/nwfpe/nwfpe.rst index 35cd90dacbff..35cd90dacbff 100644 --- a/Documentation/arm/nwfpe/nwfpe.rst +++ b/Documentation/arch/arm/nwfpe/nwfpe.rst diff --git a/Documentation/arm/nwfpe/todo.rst b/Documentation/arch/arm/nwfpe/todo.rst index 393f11b14540..393f11b14540 100644 --- a/Documentation/arm/nwfpe/todo.rst +++ b/Documentation/arch/arm/nwfpe/todo.rst diff --git a/Documentation/arm/omap/dss.rst b/Documentation/arch/arm/omap/dss.rst index a40c4d9c717a..a40c4d9c717a 100644 --- a/Documentation/arm/omap/dss.rst +++ b/Documentation/arch/arm/omap/dss.rst diff --git a/Documentation/arm/omap/index.rst b/Documentation/arch/arm/omap/index.rst index 8b365b212e49..8b365b212e49 100644 --- a/Documentation/arm/omap/index.rst +++ b/Documentation/arch/arm/omap/index.rst diff --git a/Documentation/arm/omap/omap.rst b/Documentation/arch/arm/omap/omap.rst index f440c0f4613f..f440c0f4613f 100644 --- a/Documentation/arm/omap/omap.rst +++ b/Documentation/arch/arm/omap/omap.rst diff --git a/Documentation/arm/omap/omap_pm.rst b/Documentation/arch/arm/omap/omap_pm.rst index a335e4c8ce2c..a335e4c8ce2c 100644 --- a/Documentation/arm/omap/omap_pm.rst +++ b/Documentation/arch/arm/omap/omap_pm.rst diff --git a/Documentation/arm/porting.rst b/Documentation/arch/arm/porting.rst index bd21958bdb2d..bd21958bdb2d 100644 --- a/Documentation/arm/porting.rst +++ b/Documentation/arch/arm/porting.rst diff --git a/Documentation/arm/pxa/mfp.rst b/Documentation/arch/arm/pxa/mfp.rst index ac34e5d7ee44..ac34e5d7ee44 100644 --- a/Documentation/arm/pxa/mfp.rst +++ b/Documentation/arch/arm/pxa/mfp.rst diff --git a/Documentation/arm/sa1100/assabet.rst b/Documentation/arch/arm/sa1100/assabet.rst index a761e128fb08..a761e128fb08 100644 --- a/Documentation/arm/sa1100/assabet.rst +++ b/Documentation/arch/arm/sa1100/assabet.rst diff --git a/Documentation/arm/sa1100/cerf.rst b/Documentation/arch/arm/sa1100/cerf.rst index 7fa71b609bf9..7fa71b609bf9 100644 --- a/Documentation/arm/sa1100/cerf.rst +++ b/Documentation/arch/arm/sa1100/cerf.rst diff --git a/Documentation/arm/sa1100/index.rst b/Documentation/arch/arm/sa1100/index.rst index c9aed43280ff..c9aed43280ff 100644 --- a/Documentation/arm/sa1100/index.rst +++ b/Documentation/arch/arm/sa1100/index.rst diff --git a/Documentation/arm/sa1100/lart.rst b/Documentation/arch/arm/sa1100/lart.rst index 94c0568d1095..94c0568d1095 100644 --- a/Documentation/arm/sa1100/lart.rst +++ b/Documentation/arch/arm/sa1100/lart.rst diff --git a/Documentation/arm/sa1100/serial_uart.rst b/Documentation/arch/arm/sa1100/serial_uart.rst index ea983642b9be..ea983642b9be 100644 --- a/Documentation/arm/sa1100/serial_uart.rst +++ b/Documentation/arch/arm/sa1100/serial_uart.rst diff --git a/Documentation/arm/samsung/bootloader-interface.rst b/Documentation/arch/arm/samsung/bootloader-interface.rst index a56f325dae78..a56f325dae78 100644 --- a/Documentation/arm/samsung/bootloader-interface.rst +++ b/Documentation/arch/arm/samsung/bootloader-interface.rst diff --git a/Documentation/arm/samsung/clksrc-change-registers.awk b/Documentation/arch/arm/samsung/clksrc-change-registers.awk index 7be1b8aa7cd9..7be1b8aa7cd9 100755 --- a/Documentation/arm/samsung/clksrc-change-registers.awk +++ b/Documentation/arch/arm/samsung/clksrc-change-registers.awk diff --git a/Documentation/arm/samsung/gpio.rst b/Documentation/arch/arm/samsung/gpio.rst index 27fae0d50361..27fae0d50361 100644 --- a/Documentation/arm/samsung/gpio.rst +++ b/Documentation/arch/arm/samsung/gpio.rst diff --git a/Documentation/arm/samsung/index.rst b/Documentation/arch/arm/samsung/index.rst index 8142cce3d23e..8142cce3d23e 100644 --- a/Documentation/arm/samsung/index.rst +++ b/Documentation/arch/arm/samsung/index.rst diff --git a/Documentation/arm/samsung/overview.rst b/Documentation/arch/arm/samsung/overview.rst index 8b15a190169b..8b15a190169b 100644 --- a/Documentation/arm/samsung/overview.rst +++ b/Documentation/arch/arm/samsung/overview.rst diff --git a/Documentation/arm/setup.rst b/Documentation/arch/arm/setup.rst index 8e12ef3fb9a7..8e12ef3fb9a7 100644 --- a/Documentation/arm/setup.rst +++ b/Documentation/arch/arm/setup.rst diff --git a/Documentation/arm/spear/overview.rst b/Documentation/arch/arm/spear/overview.rst index 1a77f6b213b6..1a77f6b213b6 100644 --- a/Documentation/arm/spear/overview.rst +++ b/Documentation/arch/arm/spear/overview.rst diff --git a/Documentation/arm/sti/overview.rst b/Documentation/arch/arm/sti/overview.rst index ae16aced800f..ae16aced800f 100644 --- a/Documentation/arm/sti/overview.rst +++ b/Documentation/arch/arm/sti/overview.rst diff --git a/Documentation/arm/sti/stih407-overview.rst b/Documentation/arch/arm/sti/stih407-overview.rst index 027e75bc7b7c..027e75bc7b7c 100644 --- a/Documentation/arm/sti/stih407-overview.rst +++ b/Documentation/arch/arm/sti/stih407-overview.rst diff --git a/Documentation/arm/sti/stih418-overview.rst b/Documentation/arch/arm/sti/stih418-overview.rst index b563c1f4fe5a..b563c1f4fe5a 100644 --- a/Documentation/arm/sti/stih418-overview.rst +++ b/Documentation/arch/arm/sti/stih418-overview.rst diff --git a/Documentation/arm/stm32/overview.rst b/Documentation/arch/arm/stm32/overview.rst index 85cfc8410798..85cfc8410798 100644 --- a/Documentation/arm/stm32/overview.rst +++ b/Documentation/arch/arm/stm32/overview.rst diff --git a/Documentation/arm/stm32/stm32-dma-mdma-chaining.rst b/Documentation/arch/arm/stm32/stm32-dma-mdma-chaining.rst index 2945e0e33104..2945e0e33104 100644 --- a/Documentation/arm/stm32/stm32-dma-mdma-chaining.rst +++ b/Documentation/arch/arm/stm32/stm32-dma-mdma-chaining.rst diff --git a/Documentation/arm/stm32/stm32f429-overview.rst b/Documentation/arch/arm/stm32/stm32f429-overview.rst index a7ebe8ea6697..a7ebe8ea6697 100644 --- a/Documentation/arm/stm32/stm32f429-overview.rst +++ b/Documentation/arch/arm/stm32/stm32f429-overview.rst diff --git a/Documentation/arm/stm32/stm32f746-overview.rst b/Documentation/arch/arm/stm32/stm32f746-overview.rst index 78befddc7740..78befddc7740 100644 --- a/Documentation/arm/stm32/stm32f746-overview.rst +++ b/Documentation/arch/arm/stm32/stm32f746-overview.rst diff --git a/Documentation/arm/stm32/stm32f769-overview.rst b/Documentation/arch/arm/stm32/stm32f769-overview.rst index e482980ddf21..e482980ddf21 100644 --- a/Documentation/arm/stm32/stm32f769-overview.rst +++ b/Documentation/arch/arm/stm32/stm32f769-overview.rst diff --git a/Documentation/arm/stm32/stm32h743-overview.rst b/Documentation/arch/arm/stm32/stm32h743-overview.rst index 4e15f1a42730..4e15f1a42730 100644 --- a/Documentation/arm/stm32/stm32h743-overview.rst +++ b/Documentation/arch/arm/stm32/stm32h743-overview.rst diff --git a/Documentation/arm/stm32/stm32h750-overview.rst b/Documentation/arch/arm/stm32/stm32h750-overview.rst index 0e51235c9547..0e51235c9547 100644 --- a/Documentation/arm/stm32/stm32h750-overview.rst +++ b/Documentation/arch/arm/stm32/stm32h750-overview.rst diff --git a/Documentation/arm/stm32/stm32mp13-overview.rst b/Documentation/arch/arm/stm32/stm32mp13-overview.rst index 3bb9492dad49..3bb9492dad49 100644 --- a/Documentation/arm/stm32/stm32mp13-overview.rst +++ b/Documentation/arch/arm/stm32/stm32mp13-overview.rst diff --git a/Documentation/arm/stm32/stm32mp151-overview.rst b/Documentation/arch/arm/stm32/stm32mp151-overview.rst index f42a2ac309c0..f42a2ac309c0 100644 --- a/Documentation/arm/stm32/stm32mp151-overview.rst +++ b/Documentation/arch/arm/stm32/stm32mp151-overview.rst diff --git a/Documentation/arm/stm32/stm32mp157-overview.rst b/Documentation/arch/arm/stm32/stm32mp157-overview.rst index f62fdc8e7d8d..f62fdc8e7d8d 100644 --- a/Documentation/arm/stm32/stm32mp157-overview.rst +++ b/Documentation/arch/arm/stm32/stm32mp157-overview.rst diff --git a/Documentation/arm/sunxi.rst b/Documentation/arch/arm/sunxi.rst index b85d1e2f2d47..b85d1e2f2d47 100644 --- a/Documentation/arm/sunxi.rst +++ b/Documentation/arch/arm/sunxi.rst diff --git a/Documentation/arm/sunxi/clocks.rst b/Documentation/arch/arm/sunxi/clocks.rst index 23bd03f3e21f..23bd03f3e21f 100644 --- a/Documentation/arm/sunxi/clocks.rst +++ b/Documentation/arch/arm/sunxi/clocks.rst diff --git a/Documentation/arm/swp_emulation.rst b/Documentation/arch/arm/swp_emulation.rst index 6a608a9c3715..6a608a9c3715 100644 --- a/Documentation/arm/swp_emulation.rst +++ b/Documentation/arch/arm/swp_emulation.rst diff --git a/Documentation/arm/tcm.rst b/Documentation/arch/arm/tcm.rst index 1dc6c39220f9..1dc6c39220f9 100644 --- a/Documentation/arm/tcm.rst +++ b/Documentation/arch/arm/tcm.rst diff --git a/Documentation/arm/uefi.rst b/Documentation/arch/arm/uefi.rst index baebe688a006..baebe688a006 100644 --- a/Documentation/arm/uefi.rst +++ b/Documentation/arch/arm/uefi.rst diff --git a/Documentation/arm/vfp/release-notes.rst b/Documentation/arch/arm/vfp/release-notes.rst index c6b04937cee3..c6b04937cee3 100644 --- a/Documentation/arm/vfp/release-notes.rst +++ b/Documentation/arch/arm/vfp/release-notes.rst diff --git a/Documentation/arm/vlocks.rst b/Documentation/arch/arm/vlocks.rst index a40a1742110b..a40a1742110b 100644 --- a/Documentation/arm/vlocks.rst +++ b/Documentation/arch/arm/vlocks.rst diff --git a/Documentation/arm64/acpi_object_usage.rst b/Documentation/arch/arm64/acpi_object_usage.rst index 484ef9676653..1da22200fdf8 100644 --- a/Documentation/arm64/acpi_object_usage.rst +++ b/Documentation/arch/arm64/acpi_object_usage.rst @@ -17,16 +17,37 @@ For ACPI on arm64, tables also fall into the following categories: - Recommended: BERT, EINJ, ERST, HEST, PCCT, SSDT - - Optional: BGRT, CPEP, CSRT, DBG2, DRTM, ECDT, FACS, FPDT, IBFT, - IORT, MCHI, MPST, MSCT, NFIT, PMTT, RASF, SBST, SLIT, SPMI, SRAT, - STAO, TCPA, TPM2, UEFI, XENV + - Optional: AGDI, BGRT, CEDT, CPEP, CSRT, DBG2, DRTM, ECDT, FACS, FPDT, + HMAT, IBFT, IORT, MCHI, MPAM, MPST, MSCT, NFIT, PMTT, PPTT, RASF, SBST, + SDEI, SLIT, SPMI, SRAT, STAO, TCPA, TPM2, UEFI, XENV - - Not supported: BOOT, DBGP, DMAR, ETDT, HPET, IVRS, LPIT, MSDM, OEMx, - PSDT, RSDT, SLIC, WAET, WDAT, WDRT, WPBT + - Not supported: AEST, APMT, BOOT, DBGP, DMAR, ETDT, HPET, IVRS, LPIT, + MSDM, OEMx, PDTT, PSDT, RAS2, RSDT, SLIC, WAET, WDAT, WDRT, WPBT ====== ======================================================================== Table Usage for ARMv8 Linux ====== ======================================================================== +AEST Signature Reserved (signature == "AEST") + + **Arm Error Source Table** + + This table informs the OS of any error nodes in the system that are + compliant with the Arm RAS architecture. + +AGDI Signature Reserved (signature == "AGDI") + + **Arm Generic diagnostic Dump and Reset Device Interface Table** + + This table describes a non-maskable event, that is used by the platform + firmware, to request the OS to generate a diagnostic dump and reset the device. + +APMT Signature Reserved (signature == "APMT") + + **Arm Performance Monitoring Table** + + This table describes the properties of PMU support implmented by + components in the system. + BERT Section 18.3 (signature == "BERT") **Boot Error Record Table** @@ -47,6 +68,13 @@ BGRT Section 5.2.22 (signature == "BGRT") Optional, not currently supported, with no real use-case for an ARM server. +CEDT Signature Reserved (signature == "CEDT") + + **CXL Early Discovery Table** + + This table allows the OS to discover any CXL Host Bridges and the Host + Bridge registers. + CPEP Section 5.2.18 (signature == "CPEP") **Corrected Platform Error Polling table** @@ -184,6 +212,15 @@ HEST Section 18.3.2 (signature == "HEST") Must be supplied if RAS support is provided by the platform. It is recommended this table be supplied. +HMAT Section 5.2.28 (signature == "HMAT") + + **Heterogeneous Memory Attribute Table** + + This table describes the memory attributes, such as memory side cache + attributes and bandwidth and latency details, related to Memory Proximity + Domains. The OS uses this information to optimize the system memory + configuration. + HPET Signature Reserved (signature == "HPET") **High Precision Event timer Table** @@ -241,6 +278,13 @@ MCHI Signature Reserved (signature == "MCHI") Optional, not currently supported. +MPAM Signature Reserved (signature == "MPAM") + + **Memory Partitioning And Monitoring table** + + This table allows the OS to discover the MPAM controls implemented by + the subsystems. + MPST Section 5.2.21 (signature == "MPST") **Memory Power State Table** @@ -281,18 +325,39 @@ PCCT Section 14.1 (signature == "PCCT) Recommend for use on arm64; use of PCC is recommended when using CPPC to control performance and power for platform processors. +PDTT Section 5.2.29 (signature == "PDTT") + + **Platform Debug Trigger Table** + + This table describes PCC channels used to gather debug logs of + non-architectural features. + + PMTT Section 5.2.21.12 (signature == "PMTT") **Platform Memory Topology Table** Optional, not currently supported. +PPTT Section 5.2.30 (signature == "PPTT") + + **Processor Properties Topology Table** + + This table provides the processor and cache topology. + PSDT Section 5.2.11.3 (signature == "PSDT") **Persistent System Description Table** Obsolete table, will not be supported. +RAS2 Section 5.2.21 (signature == "RAS2") + + **RAS Features 2 table** + + This table provides interfaces for the RAS capabilities implemented in + the platform. + RASF Section 5.2.20 (signature == "RASF") **RAS Feature table** @@ -318,6 +383,12 @@ SBST Section 5.2.14 (signature == "SBST") Optional, not currently supported. +SDEI Signature Reserved (signature == "SDEI") + + **Software Delegated Exception Interface table** + + This table advertises the presence of the SDEI interface. + SLIC Signature Reserved (signature == "SLIC") **Software LIcensing table** diff --git a/Documentation/arm64/amu.rst b/Documentation/arch/arm64/amu.rst index 01f2de2b0450..01f2de2b0450 100644 --- a/Documentation/arm64/amu.rst +++ b/Documentation/arch/arm64/amu.rst diff --git a/Documentation/arm64/arm-acpi.rst b/Documentation/arch/arm64/arm-acpi.rst index 47ecb9930dde..94274a8d84cf 100644 --- a/Documentation/arm64/arm-acpi.rst +++ b/Documentation/arch/arm64/arm-acpi.rst @@ -1,40 +1,41 @@ -===================== -ACPI on ARMv8 Servers -===================== - -ACPI can be used for ARMv8 general purpose servers designed to follow -the ARM SBSA (Server Base System Architecture) [0] and SBBR (Server -Base Boot Requirements) [1] specifications. Please note that the SBBR -can be retrieved simply by visiting [1], but the SBSA is currently only -available to those with an ARM login due to ARM IP licensing concerns. - -The ARMv8 kernel implements the reduced hardware model of ACPI version +=================== +ACPI on Arm systems +=================== + +ACPI can be used for Armv8 and Armv9 systems designed to follow +the BSA (Arm Base System Architecture) [0] and BBR (Arm +Base Boot Requirements) [1] specifications. Both BSA and BBR are publicly +accessible documents. +Arm Servers, in addition to being BSA compliant, comply with a set +of rules defined in SBSA (Server Base System Architecture) [2]. + +The Arm kernel implements the reduced hardware model of ACPI version 5.1 or later. Links to the specification and all external documents it refers to are managed by the UEFI Forum. The specification is available at http://www.uefi.org/specifications and documents referenced by the specification can be found via http://www.uefi.org/acpi. -If an ARMv8 system does not meet the requirements of the SBSA and SBBR, +If an Arm system does not meet the requirements of the BSA and BBR, or cannot be described using the mechanisms defined in the required ACPI specifications, then ACPI may not be a good fit for the hardware. While the documents mentioned above set out the requirements for building -industry-standard ARMv8 servers, they also apply to more than one operating +industry-standard Arm systems, they also apply to more than one operating system. The purpose of this document is to describe the interaction between -ACPI and Linux only, on an ARMv8 system -- that is, what Linux expects of +ACPI and Linux only, on an Arm system -- that is, what Linux expects of ACPI and what ACPI can expect of Linux. -Why ACPI on ARM? +Why ACPI on Arm? ---------------- Before examining the details of the interface between ACPI and Linux, it is useful to understand why ACPI is being used. Several technologies already exist in Linux for describing non-enumerable hardware, after all. In this -section we summarize a blog post [2] from Grant Likely that outlines the -reasoning behind ACPI on ARMv8 servers. Actually, we snitch a good portion +section we summarize a blog post [3] from Grant Likely that outlines the +reasoning behind ACPI on Arm systems. Actually, we snitch a good portion of the summary text almost directly, to be honest. -The short form of the rationale for ACPI on ARM is: +The short form of the rationale for ACPI on Arm is: - ACPI’s byte code (AML) allows the platform to encode hardware behavior, while DT explicitly does not support this. For hardware vendors, being @@ -47,7 +48,7 @@ The short form of the rationale for ACPI on ARM is: - In the enterprise server environment, ACPI has established bindings (such as for RAS) which are currently used in production systems. DT does not. - Such bindings could be defined in DT at some point, but doing so means ARM + Such bindings could be defined in DT at some point, but doing so means Arm and x86 would end up using completely different code paths in both firmware and the kernel. @@ -108,7 +109,7 @@ recent version of the kernel. Relationship with Device Tree ----------------------------- -ACPI support in drivers and subsystems for ARMv8 should never be mutually +ACPI support in drivers and subsystems for Arm should never be mutually exclusive with DT support at compile time. At boot time the kernel will only use one description method depending on @@ -121,11 +122,11 @@ time). Booting using ACPI tables ------------------------- -The only defined method for passing ACPI tables to the kernel on ARMv8 +The only defined method for passing ACPI tables to the kernel on Arm is via the UEFI system configuration table. Just so it is explicit, this means that ACPI is only supported on platforms that boot via UEFI. -When an ARMv8 system boots, it can either have DT information, ACPI tables, +When an Arm system boots, it can either have DT information, ACPI tables, or in some very unusual cases, both. If no command line parameters are used, the kernel will try to use DT for device enumeration; if there is no DT present, the kernel will try to use ACPI tables, but only if they are present. @@ -169,7 +170,7 @@ hardware reduced mode must be set to zero. For the ACPI core to operate properly, and in turn provide the information the kernel needs to configure devices, it expects to find the following -tables (all section numbers refer to the ACPI 6.1 specification): +tables (all section numbers refer to the ACPI 6.5 specification): - RSDP (Root System Description Pointer), section 5.2.5 @@ -184,20 +185,76 @@ tables (all section numbers refer to the ACPI 6.1 specification): - GTDT (Generic Timer Description Table), section 5.2.24 + - PPTT (Processor Properties Topology Table), section 5.2.30 + + - DBG2 (DeBuG port table 2), section 5.2.6, specifically Table 5-6. + + - APMT (Arm Performance Monitoring unit Table), section 5.2.6, specifically Table 5-6. + + - AGDI (Arm Generic diagnostic Dump and Reset Device Interface Table), section 5.2.6, specifically Table 5-6. + - If PCI is supported, the MCFG (Memory mapped ConFiGuration - Table), section 5.2.6, specifically Table 5-31. + Table), section 5.2.6, specifically Table 5-6. - If booting without a console=<device> kernel parameter is supported, the SPCR (Serial Port Console Redirection table), - section 5.2.6, specifically Table 5-31. + section 5.2.6, specifically Table 5-6. - If necessary to describe the I/O topology, SMMUs and GIC ITSs, the IORT (Input Output Remapping Table, section 5.2.6, specifically - Table 5-31). + Table 5-6). + + - If NUMA is supported, the following tables are required: + + - SRAT (System Resource Affinity Table), section 5.2.16 + + - SLIT (System Locality distance Information Table), section 5.2.17 + + - If NUMA is supported, and the system contains heterogeneous memory, + the HMAT (Heterogeneous Memory Attribute Table), section 5.2.28. + + - If the ACPI Platform Error Interfaces are required, the following + tables are conditionally required: + + - BERT (Boot Error Record Table, section 18.3.1) + + - EINJ (Error INJection table, section 18.6.1) + + - ERST (Error Record Serialization Table, section 18.5) + + - HEST (Hardware Error Source Table, section 18.3.2) + + - SDEI (Software Delegated Exception Interface table, section 5.2.6, + specifically Table 5-6) + + - AEST (Arm Error Source Table, section 5.2.6, + specifically Table 5-6) + + - RAS2 (ACPI RAS2 feature table, section 5.2.21) + + - If the system contains controllers using PCC channel, the + PCCT (Platform Communications Channel Table), section 14.1 + + - If the system contains a controller to capture board-level system state, + and communicates with the host via PCC, the PDTT (Platform Debug Trigger + Table), section 5.2.29. + + - If NVDIMM is supported, the NFIT (NVDIMM Firmware Interface Table), section 5.2.26 + + - If video framebuffer is present, the BGRT (Boot Graphics Resource Table), section 5.2.23 + + - If IPMI is implemented, the SPMI (Server Platform Management Interface), + section 5.2.6, specifically Table 5-6. + + - If the system contains a CXL Host Bridge, the CEDT (CXL Early Discovery + Table), section 5.2.6, specifically Table 5-6. + + - If the system supports MPAM, the MPAM (Memory Partitioning And Monitoring table), section 5.2.6, + specifically Table 5-6. + + - If the system lacks persistent storage, the IBFT (ISCSI Boot Firmware + Table), section 5.2.6, specifically Table 5-6. - - If NUMA is supported, the SRAT (System Resource Affinity Table) - and SLIT (System Locality distance Information Table), sections - 5.2.16 and 5.2.17, respectively. If the above tables are not all present, the kernel may or may not be able to boot properly since it may not be able to configure all of the @@ -269,16 +326,14 @@ Drivers should look for device properties in the _DSD object ONLY; the _DSD object is described in the ACPI specification section 6.2.5, but this only describes how to define the structure of an object returned via _DSD, and how specific data structures are defined by specific UUIDs. Linux should -only use the _DSD Device Properties UUID [5]: +only use the _DSD Device Properties UUID [4]: - UUID: daffd814-6eba-4d8c-8a91-bc9bbf4aa301 - - https://www.uefi.org/sites/default/files/resources/_DSD-device-properties-UUID.pdf - -The UEFI Forum provides a mechanism for registering device properties [4] -so that they may be used across all operating systems supporting ACPI. -Device properties that have not been registered with the UEFI Forum should -not be used. +Common device properties can be registered by creating a pull request to [4] so +that they may be used across all operating systems supporting ACPI. +Device properties that have not been registered with the UEFI Forum can be used +but not as "uefi-" common properties. Before creating new device properties, check to be sure that they have not been defined before and either registered in the Linux kernel documentation @@ -306,7 +361,7 @@ process. Once registration and review have been completed, the kernel provides an interface for looking up device properties in a manner independent of -whether DT or ACPI is being used. This API should be used [6]; it can +whether DT or ACPI is being used. This API should be used [5]; it can eliminate some duplication of code paths in driver probing functions and discourage divergence between DT bindings and ACPI device properties. @@ -448,15 +503,15 @@ ASWG ---- The ACPI specification changes regularly. During the year 2014, for instance, version 5.1 was released and version 6.0 substantially completed, with most of -the changes being driven by ARM-specific requirements. Proposed changes are +the changes being driven by Arm-specific requirements. Proposed changes are presented and discussed in the ASWG (ACPI Specification Working Group) which is a part of the UEFI Forum. The current version of the ACPI specification -is 6.1 release in January 2016. +is 6.5 release in August 2022. Participation in this group is open to all UEFI members. Please see http://www.uefi.org/workinggroup for details on group membership. -It is the intent of the ARMv8 ACPI kernel code to follow the ACPI specification +It is the intent of the Arm ACPI kernel code to follow the ACPI specification as closely as possible, and to only implement functionality that complies with the released standards from UEFI ASWG. As a practical matter, there will be vendors that provide bad ACPI tables or violate the standards in some way. @@ -470,12 +525,12 @@ likely be willing to assist in submitting ECRs. Linux Code ---------- -Individual items specific to Linux on ARM, contained in the Linux +Individual items specific to Linux on Arm, contained in the Linux source code, are in the list that follows: ACPI_OS_NAME This macro defines the string to be returned when - an ACPI method invokes the _OS method. On ARM64 + an ACPI method invokes the _OS method. On Arm systems, this macro will be "Linux" by default. The command line parameter acpi_os=<string> can be used to set it to some other value. The @@ -485,36 +540,28 @@ ACPI_OS_NAME ACPI Objects ------------ Detailed expectations for ACPI tables and object are listed in the file -Documentation/arm64/acpi_object_usage.rst. +Documentation/arch/arm64/acpi_object_usage.rst. References ---------- -[0] http://silver.arm.com - document ARM-DEN-0029, or newer: - "Server Base System Architecture", version 2.3, dated 27 Mar 2014 +[0] https://developer.arm.com/documentation/den0094/latest + document Arm-DEN-0094: "Arm Base System Architecture", version 1.0C, dated 6 Oct 2022 + +[1] https://developer.arm.com/documentation/den0044/latest + Document Arm-DEN-0044: "Arm Base Boot Requirements", version 2.0G, dated 15 Apr 2022 -[1] http://infocenter.arm.com/help/topic/com.arm.doc.den0044a/Server_Base_Boot_Requirements.pdf - Document ARM-DEN-0044A, or newer: "Server Base Boot Requirements, System - Software on ARM Platforms", dated 16 Aug 2014 +[2] https://developer.arm.com/documentation/den0029/latest + Document Arm-DEN-0029: "Arm Server Base System Architecture", version 7.1, dated 06 Oct 2022 -[2] http://www.secretlab.ca/archives/151, +[3] http://www.secretlab.ca/archives/151, 10 Jan 2015, Copyright (c) 2015, Linaro Ltd., written by Grant Likely. -[3] AMD ACPI for Seattle platform documentation - http://amd-dev.wpengine.netdna-cdn.com/wordpress/media/2012/10/Seattle_ACPI_Guide.pdf - - -[4] http://www.uefi.org/acpi - please see the link for the "ACPI _DSD Device - Property Registry Instructions" - -[5] http://www.uefi.org/acpi - please see the link for the "_DSD (Device - Specific Data) Implementation Guide" +[4] _DSD (Device Specific Data) Implementation Guide + https://github.com/UEFI/DSD-Guide/blob/main/dsd-guide.pdf -[6] Kernel code for the unified device +[5] Kernel code for the unified device property interface can be found in include/linux/property.h and drivers/base/property.c. diff --git a/Documentation/arm64/asymmetric-32bit.rst b/Documentation/arch/arm64/asymmetric-32bit.rst index 64a0b505da7d..64a0b505da7d 100644 --- a/Documentation/arm64/asymmetric-32bit.rst +++ b/Documentation/arch/arm64/asymmetric-32bit.rst diff --git a/Documentation/arm64/booting.rst b/Documentation/arch/arm64/booting.rst index ffeccdd6bdac..b57776a68f15 100644 --- a/Documentation/arm64/booting.rst +++ b/Documentation/arch/arm64/booting.rst @@ -379,6 +379,38 @@ Before jumping into the kernel, the following conditions must be met: - SMCR_EL2.EZT0 (bit 30) must be initialised to 0b1. + For CPUs with Memory Copy and Memory Set instructions (FEAT_MOPS): + + - If the kernel is entered at EL1 and EL2 is present: + + - HCRX_EL2.MSCEn (bit 11) must be initialised to 0b1. + + For CPUs with the Extended Translation Control Register feature (FEAT_TCR2): + + - If EL3 is present: + + - SCR_EL3.TCR2En (bit 43) must be initialised to 0b1. + + - If the kernel is entered at EL1 and EL2 is present: + + - HCRX_EL2.TCR2En (bit 14) must be initialised to 0b1. + + For CPUs with the Stage 1 Permission Indirection Extension feature (FEAT_S1PIE): + + - If EL3 is present: + + - SCR_EL3.PIEn (bit 45) must be initialised to 0b1. + + - If the kernel is entered at EL1 and EL2 is present: + + - HFGRTR_EL2.nPIR_EL1 (bit 58) must be initialised to 0b1. + + - HFGWTR_EL2.nPIR_EL1 (bit 58) must be initialised to 0b1. + + - HFGRTR_EL2.nPIRE0_EL1 (bit 57) must be initialised to 0b1. + + - HFGRWR_EL2.nPIRE0_EL1 (bit 57) must be initialised to 0b1. + The requirements described above for CPU mode, caches, MMUs, architected timers, coherency and system registers apply to all CPUs. All CPUs must enter the kernel in the same exception level. Where the values documented diff --git a/Documentation/arm64/cpu-feature-registers.rst b/Documentation/arch/arm64/cpu-feature-registers.rst index c7adc7897df6..4e4625f2455f 100644 --- a/Documentation/arm64/cpu-feature-registers.rst +++ b/Documentation/arch/arm64/cpu-feature-registers.rst @@ -288,6 +288,8 @@ infrastructure: +------------------------------+---------+---------+ | Name | bits | visible | +------------------------------+---------+---------+ + | MOPS | [19-16] | y | + +------------------------------+---------+---------+ | RPRES | [7-4] | y | +------------------------------+---------+---------+ | WFXT | [3-0] | y | diff --git a/Documentation/arm64/elf_hwcaps.rst b/Documentation/arch/arm64/elf_hwcaps.rst index 83e57e4d38e2..8c8addb4194c 100644 --- a/Documentation/arm64/elf_hwcaps.rst +++ b/Documentation/arch/arm64/elf_hwcaps.rst @@ -102,7 +102,7 @@ HWCAP_ASIMDHP HWCAP_CPUID EL0 access to certain ID registers is available, to the extent - described by Documentation/arm64/cpu-feature-registers.rst. + described by Documentation/arch/arm64/cpu-feature-registers.rst. These ID registers may imply the availability of features. @@ -163,12 +163,12 @@ HWCAP_SB HWCAP_PACA Functionality implied by ID_AA64ISAR1_EL1.APA == 0b0001 or ID_AA64ISAR1_EL1.API == 0b0001, as described by - Documentation/arm64/pointer-authentication.rst. + Documentation/arch/arm64/pointer-authentication.rst. HWCAP_PACG Functionality implied by ID_AA64ISAR1_EL1.GPA == 0b0001 or ID_AA64ISAR1_EL1.GPI == 0b0001, as described by - Documentation/arm64/pointer-authentication.rst. + Documentation/arch/arm64/pointer-authentication.rst. HWCAP2_DCPODP Functionality implied by ID_AA64ISAR1_EL1.DPB == 0b0010. @@ -226,7 +226,7 @@ HWCAP2_BTI HWCAP2_MTE Functionality implied by ID_AA64PFR1_EL1.MTE == 0b0010, as described - by Documentation/arm64/memory-tagging-extension.rst. + by Documentation/arch/arm64/memory-tagging-extension.rst. HWCAP2_ECV Functionality implied by ID_AA64MMFR0_EL1.ECV == 0b0001. @@ -239,11 +239,11 @@ HWCAP2_RPRES HWCAP2_MTE3 Functionality implied by ID_AA64PFR1_EL1.MTE == 0b0011, as described - by Documentation/arm64/memory-tagging-extension.rst. + by Documentation/arch/arm64/memory-tagging-extension.rst. HWCAP2_SME Functionality implied by ID_AA64PFR1_EL1.SME == 0b0001, as described - by Documentation/arm64/sme.rst. + by Documentation/arch/arm64/sme.rst. HWCAP2_SME_I16I64 Functionality implied by ID_AA64SMFR0_EL1.I16I64 == 0b1111. @@ -302,6 +302,9 @@ HWCAP2_SMEB16B16 HWCAP2_SMEF16F16 Functionality implied by ID_AA64SMFR0_EL1.F16F16 == 0b1 +HWCAP2_MOPS + Functionality implied by ID_AA64ISAR2_EL1.MOPS == 0b0001. + 4. Unused AT_HWCAP bits ----------------------- diff --git a/Documentation/arm64/features.rst b/Documentation/arch/arm64/features.rst index dfa4cb3cd3ef..dfa4cb3cd3ef 100644 --- a/Documentation/arm64/features.rst +++ b/Documentation/arch/arm64/features.rst diff --git a/Documentation/arm64/hugetlbpage.rst b/Documentation/arch/arm64/hugetlbpage.rst index a110124c11e3..a110124c11e3 100644 --- a/Documentation/arm64/hugetlbpage.rst +++ b/Documentation/arch/arm64/hugetlbpage.rst diff --git a/Documentation/arm64/index.rst b/Documentation/arch/arm64/index.rst index ae21f8118830..d08e924204bf 100644 --- a/Documentation/arm64/index.rst +++ b/Documentation/arch/arm64/index.rst @@ -15,11 +15,13 @@ ARM64 Architecture cpu-feature-registers elf_hwcaps hugetlbpage + kdump legacy_instructions memory memory-tagging-extension perf pointer-authentication + ptdump silicon-errata sme sve diff --git a/Documentation/arm64/kasan-offsets.sh b/Documentation/arch/arm64/kasan-offsets.sh index 2dc5f9e18039..2dc5f9e18039 100644 --- a/Documentation/arm64/kasan-offsets.sh +++ b/Documentation/arch/arm64/kasan-offsets.sh diff --git a/Documentation/arch/arm64/kdump.rst b/Documentation/arch/arm64/kdump.rst new file mode 100644 index 000000000000..56a89f45df28 --- /dev/null +++ b/Documentation/arch/arm64/kdump.rst @@ -0,0 +1,92 @@ +======================================= +crashkernel memory reservation on arm64 +======================================= + +Author: Baoquan He <bhe@redhat.com> + +Kdump mechanism is used to capture a corrupted kernel vmcore so that +it can be subsequently analyzed. In order to do this, a preliminarily +reserved memory is needed to pre-load the kdump kernel and boot such +kernel if corruption happens. + +That reserved memory for kdump is adapted to be able to minimally +accommodate the kdump kernel and the user space programs needed for the +vmcore collection. + +Kernel parameter +================ + +Through the kernel parameters below, memory can be reserved accordingly +during the early stage of the first kernel booting so that a continuous +large chunk of memomy can be found. The low memory reservation needs to +be considered if the crashkernel is reserved from the high memory area. + +- crashkernel=size@offset +- crashkernel=size +- crashkernel=size,high crashkernel=size,low + +Low memory and high memory +========================== + +For kdump reservations, low memory is the memory area under a specific +limit, usually decided by the accessible address bits of the DMA-capable +devices needed by the kdump kernel to run. Those devices not related to +vmcore dumping can be ignored. On arm64, the low memory upper bound is +not fixed: it is 1G on the RPi4 platform but 4G on most other systems. +On special kernels built with CONFIG_ZONE_(DMA|DMA32) disabled, the +whole system RAM is low memory. Outside of the low memory described +above, the rest of system RAM is considered high memory. + +Implementation +============== + +1) crashkernel=size@offset +-------------------------- + +The crashkernel memory must be reserved at the user-specified region or +fail if already occupied. + + +2) crashkernel=size +------------------- + +The crashkernel memory region will be reserved in any available position +according to the search order: + +Firstly, the kernel searches the low memory area for an available region +with the specified size. + +If searching for low memory fails, the kernel falls back to searching +the high memory area for an available region of the specified size. If +the reservation in high memory succeeds, a default size reservation in +the low memory will be done. Currently the default size is 128M, +sufficient for the low memory needs of the kdump kernel. + +Note: crashkernel=size is the recommended option for crashkernel kernel +reservations. The user would not need to know the system memory layout +for a specific platform. + +3) crashkernel=size,high crashkernel=size,low +--------------------------------------------- + +crashkernel=size,(high|low) are an important supplement to +crashkernel=size. They allows the user to specify how much memory needs +to be allocated from the high memory and low memory respectively. On +many systems the low memory is precious and crashkernel reservations +from this area should be kept to a minimum. + +To reserve memory for crashkernel=size,high, searching is first +attempted from the high memory region. If the reservation succeeds, the +low memory reservation will be done subsequently. + +If reservation from the high memory failed, the kernel falls back to +searching the low memory with the specified size in crashkernel=,high. +If it succeeds, no further reservation for low memory is needed. + +Notes: + +- If crashkernel=,low is not specified, the default low memory + reservation will be done automatically. + +- if crashkernel=0,low is specified, it means that the low memory + reservation is omitted intentionally. diff --git a/Documentation/arm64/legacy_instructions.rst b/Documentation/arch/arm64/legacy_instructions.rst index 54401b22cb8f..54401b22cb8f 100644 --- a/Documentation/arm64/legacy_instructions.rst +++ b/Documentation/arch/arm64/legacy_instructions.rst diff --git a/Documentation/arm64/memory-tagging-extension.rst b/Documentation/arch/arm64/memory-tagging-extension.rst index dbae47bba25e..679725030731 100644 --- a/Documentation/arm64/memory-tagging-extension.rst +++ b/Documentation/arch/arm64/memory-tagging-extension.rst @@ -221,7 +221,7 @@ programs should not retry in case of a non-zero system call return. ``NT_ARM_TAGGED_ADDR_CTRL`` allow ``ptrace()`` access to the tagged address ABI control and MTE configuration of a process as per the ``prctl()`` options described in -Documentation/arm64/tagged-address-abi.rst and above. The corresponding +Documentation/arch/arm64/tagged-address-abi.rst and above. The corresponding ``regset`` is 1 element of 8 bytes (``sizeof(long))``). Core dump support diff --git a/Documentation/arm64/memory.rst b/Documentation/arch/arm64/memory.rst index 2a641ba7be3b..55a55f30eed8 100644 --- a/Documentation/arm64/memory.rst +++ b/Documentation/arch/arm64/memory.rst @@ -33,8 +33,8 @@ AArch64 Linux memory layout with 4KB pages + 4 levels (48-bit):: 0000000000000000 0000ffffffffffff 256TB user ffff000000000000 ffff7fffffffffff 128TB kernel logical memory map [ffff600000000000 ffff7fffffffffff] 32TB [kasan shadow region] - ffff800000000000 ffff800007ffffff 128MB modules - ffff800008000000 fffffbffefffffff 124TB vmalloc + ffff800000000000 ffff80007fffffff 2GB modules + ffff800080000000 fffffbffefffffff 124TB vmalloc fffffbfff0000000 fffffbfffdffffff 224MB fixed mappings (top down) fffffbfffe000000 fffffbfffe7fffff 8MB [guard region] fffffbfffe800000 fffffbffff7fffff 16MB PCI I/O space @@ -50,8 +50,8 @@ AArch64 Linux memory layout with 64KB pages + 3 levels (52-bit with HW support): 0000000000000000 000fffffffffffff 4PB user fff0000000000000 ffff7fffffffffff ~4PB kernel logical memory map [fffd800000000000 ffff7fffffffffff] 512TB [kasan shadow region] - ffff800000000000 ffff800007ffffff 128MB modules - ffff800008000000 fffffbffefffffff 124TB vmalloc + ffff800000000000 ffff80007fffffff 2GB modules + ffff800080000000 fffffbffefffffff 124TB vmalloc fffffbfff0000000 fffffbfffdffffff 224MB fixed mappings (top down) fffffbfffe000000 fffffbfffe7fffff 8MB [guard region] fffffbfffe800000 fffffbffff7fffff 16MB PCI I/O space diff --git a/Documentation/arm64/perf.rst b/Documentation/arch/arm64/perf.rst index 1f87b57c2332..1f87b57c2332 100644 --- a/Documentation/arm64/perf.rst +++ b/Documentation/arch/arm64/perf.rst diff --git a/Documentation/arm64/pointer-authentication.rst b/Documentation/arch/arm64/pointer-authentication.rst index e5dad2e40aa8..e5dad2e40aa8 100644 --- a/Documentation/arm64/pointer-authentication.rst +++ b/Documentation/arch/arm64/pointer-authentication.rst diff --git a/Documentation/arch/arm64/ptdump.rst b/Documentation/arch/arm64/ptdump.rst new file mode 100644 index 000000000000..5dcfc5d7cddf --- /dev/null +++ b/Documentation/arch/arm64/ptdump.rst @@ -0,0 +1,96 @@ +====================== +Kernel page table dump +====================== + +ptdump is a debugfs interface that provides a detailed dump of the +kernel page tables. It offers a comprehensive overview of the kernel +virtual memory layout as well as the attributes associated with the +various regions in a human-readable format. It is useful to dump the +kernel page tables to verify permissions and memory types. Examining the +page table entries and permissions helps identify potential security +vulnerabilities such as mappings with overly permissive access rights or +improper memory protections. + +Memory hotplug allows dynamic expansion or contraction of available +memory without requiring a system reboot. To maintain the consistency +and integrity of the memory management data structures, arm64 makes use +of the ``mem_hotplug_lock`` semaphore in write mode. Additionally, in +read mode, ``mem_hotplug_lock`` supports an efficient implementation of +``get_online_mems()`` and ``put_online_mems()``. These protect the +offlining of memory being accessed by the ptdump code. + +In order to dump the kernel page tables, enable the following +configurations and mount debugfs:: + + CONFIG_GENERIC_PTDUMP=y + CONFIG_PTDUMP_CORE=y + CONFIG_PTDUMP_DEBUGFS=y + + mount -t debugfs nodev /sys/kernel/debug + cat /sys/kernel/debug/kernel_page_tables + +On analysing the output of ``cat /sys/kernel/debug/kernel_page_tables`` +one can derive information about the virtual address range of the entry, +followed by size of the memory region covered by this entry, the +hierarchical structure of the page tables and finally the attributes +associated with each page. The page attributes provide information about +access permissions, execution capability, type of mapping such as leaf +level PTE or block level PGD, PMD and PUD, and access status of a page +within the kernel memory. Assessing these attributes can assist in +understanding the memory layout, access patterns and security +characteristics of the kernel pages. + +Kernel virtual memory layout example:: + + start address end address size attributes + +---------------------------------------------------------------------------------------+ + | ---[ Linear Mapping start ]---------------------------------------------------------- | + | .................. | + | 0xfff0000000000000-0xfff0000000210000 2112K PTE RW NX SHD AF UXN MEM/NORMAL-TAGGED | + | 0xfff0000000210000-0xfff0000001c00000 26560K PTE ro NX SHD AF UXN MEM/NORMAL | + | .................. | + | ---[ Linear Mapping end ]------------------------------------------------------------ | + +---------------------------------------------------------------------------------------+ + | ---[ Modules start ]----------------------------------------------------------------- | + | .................. | + | 0xffff800000000000-0xffff800008000000 128M PTE | + | .................. | + | ---[ Modules end ]------------------------------------------------------------------- | + +---------------------------------------------------------------------------------------+ + | ---[ vmalloc() area ]---------------------------------------------------------------- | + | .................. | + | 0xffff800008010000-0xffff800008200000 1984K PTE ro x SHD AF UXN MEM/NORMAL | + | 0xffff800008200000-0xffff800008e00000 12M PTE ro x SHD AF CON UXN MEM/NORMAL | + | .................. | + | ---[ vmalloc() end ]----------------------------------------------------------------- | + +---------------------------------------------------------------------------------------+ + | ---[ Fixmap start ]------------------------------------------------------------------ | + | .................. | + | 0xfffffbfffdb80000-0xfffffbfffdb90000 64K PTE ro x SHD AF UXN MEM/NORMAL | + | 0xfffffbfffdb90000-0xfffffbfffdba0000 64K PTE ro NX SHD AF UXN MEM/NORMAL | + | .................. | + | ---[ Fixmap end ]-------------------------------------------------------------------- | + +---------------------------------------------------------------------------------------+ + | ---[ PCI I/O start ]----------------------------------------------------------------- | + | .................. | + | 0xfffffbfffe800000-0xfffffbffff800000 16M PTE | + | .................. | + | ---[ PCI I/O end ]------------------------------------------------------------------- | + +---------------------------------------------------------------------------------------+ + | ---[ vmemmap start ]----------------------------------------------------------------- | + | .................. | + | 0xfffffc0002000000-0xfffffc0002200000 2M PTE RW NX SHD AF UXN MEM/NORMAL | + | 0xfffffc0002200000-0xfffffc0020000000 478M PTE | + | .................. | + | ---[ vmemmap end ]------------------------------------------------------------------- | + +---------------------------------------------------------------------------------------+ + +``cat /sys/kernel/debug/kernel_page_tables`` output:: + + 0xfff0000001c00000-0xfff0000080000000 2020M PTE RW NX SHD AF UXN MEM/NORMAL-TAGGED + 0xfff0000080000000-0xfff0000800000000 30G PMD + 0xfff0000800000000-0xfff0000800700000 7M PTE RW NX SHD AF UXN MEM/NORMAL-TAGGED + 0xfff0000800700000-0xfff0000800710000 64K PTE ro NX SHD AF UXN MEM/NORMAL-TAGGED + 0xfff0000800710000-0xfff0000880000000 2089920K PTE RW NX SHD AF UXN MEM/NORMAL-TAGGED + 0xfff0000880000000-0xfff0040000000000 4062G PMD + 0xfff0040000000000-0xffff800000000000 3964T PGD diff --git a/Documentation/arm64/silicon-errata.rst b/Documentation/arch/arm64/silicon-errata.rst index 9e311bc43e05..d6430ade349d 100644 --- a/Documentation/arm64/silicon-errata.rst +++ b/Documentation/arch/arm64/silicon-errata.rst @@ -214,3 +214,7 @@ stable kernels. +----------------+-----------------+-----------------+-----------------------------+ | Fujitsu | A64FX | E#010001 | FUJITSU_ERRATUM_010001 | +----------------+-----------------+-----------------+-----------------------------+ + ++----------------+-----------------+-----------------+-----------------------------+ +| ASR | ASR8601 | #8601001 | N/A | ++----------------+-----------------+-----------------+-----------------------------+ diff --git a/Documentation/arm64/sme.rst b/Documentation/arch/arm64/sme.rst index 1c43ea12eb4f..ba529a1dc606 100644 --- a/Documentation/arm64/sme.rst +++ b/Documentation/arch/arm64/sme.rst @@ -465,4 +465,4 @@ References [2] arch/arm64/include/uapi/asm/ptrace.h AArch64 Linux ptrace ABI definitions -[3] Documentation/arm64/cpu-feature-registers.rst +[3] Documentation/arch/arm64/cpu-feature-registers.rst diff --git a/Documentation/arm64/sve.rst b/Documentation/arch/arm64/sve.rst index 1b90a30382ac..0d9a426e9f85 100644 --- a/Documentation/arm64/sve.rst +++ b/Documentation/arch/arm64/sve.rst @@ -606,7 +606,7 @@ References [2] arch/arm64/include/uapi/asm/ptrace.h AArch64 Linux ptrace ABI definitions -[3] Documentation/arm64/cpu-feature-registers.rst +[3] Documentation/arch/arm64/cpu-feature-registers.rst [4] ARM IHI0055C http://infocenter.arm.com/help/topic/com.arm.doc.ihi0055c/IHI0055C_beta_aapcs64.pdf diff --git a/Documentation/arm64/tagged-address-abi.rst b/Documentation/arch/arm64/tagged-address-abi.rst index 540a1d4fc6c9..fe24a3f158c5 100644 --- a/Documentation/arm64/tagged-address-abi.rst +++ b/Documentation/arch/arm64/tagged-address-abi.rst @@ -107,7 +107,7 @@ following behaviours are guaranteed: A definition of the meaning of tagged pointers on AArch64 can be found -in Documentation/arm64/tagged-pointers.rst. +in Documentation/arch/arm64/tagged-pointers.rst. 3. AArch64 Tagged Address ABI Exceptions ----------------------------------------- diff --git a/Documentation/arm64/tagged-pointers.rst b/Documentation/arch/arm64/tagged-pointers.rst index 19d284b70384..81b6c2a770dd 100644 --- a/Documentation/arm64/tagged-pointers.rst +++ b/Documentation/arch/arm64/tagged-pointers.rst @@ -22,7 +22,7 @@ Passing tagged addresses to the kernel All interpretation of userspace memory addresses by the kernel assumes an address tag of 0x00, unless the application enables the AArch64 Tagged Address ABI explicitly -(Documentation/arm64/tagged-address-abi.rst). +(Documentation/arch/arm64/tagged-address-abi.rst). This includes, but is not limited to, addresses found in: diff --git a/Documentation/arch/index.rst b/Documentation/arch/index.rst index 80ee31016584..8458b88e9b79 100644 --- a/Documentation/arch/index.rst +++ b/Documentation/arch/index.rst @@ -10,8 +10,8 @@ implementation. :maxdepth: 2 arc/index - ../arm/index - ../arm64/index + arm/index + arm64/index ia64/index ../loongarch/index m68k/index diff --git a/Documentation/arch/x86/resctrl.rst b/Documentation/arch/x86/resctrl.rst index 387ccbcb558f..cb05d90111b4 100644 --- a/Documentation/arch/x86/resctrl.rst +++ b/Documentation/arch/x86/resctrl.rst @@ -287,6 +287,13 @@ Removing a directory will move all tasks and cpus owned by the group it represents to the parent. Removing one of the created CTRL_MON groups will automatically remove all MON groups below it. +Moving MON group directories to a new parent CTRL_MON group is supported +for the purpose of changing the resource allocations of a MON group +without impacting its monitoring data or assigned tasks. This operation +is not allowed for MON groups which monitor CPUs. No other move +operation is currently allowed other than simply renaming a CTRL_MON or +MON group. + All groups contain the following files: "tasks": diff --git a/Documentation/conf.py b/Documentation/conf.py index 37314afd1ac8..d4fdf6a3875a 100644 --- a/Documentation/conf.py +++ b/Documentation/conf.py @@ -74,6 +74,7 @@ if major >= 3: "__percpu", "__rcu", "__user", + "__force", # include/linux/compiler_attributes.h: "__alias", diff --git a/Documentation/core-api/cpu_hotplug.rst b/Documentation/core-api/cpu_hotplug.rst index f75778d37488..e6f5bc39cf5c 100644 --- a/Documentation/core-api/cpu_hotplug.rst +++ b/Documentation/core-api/cpu_hotplug.rst @@ -127,17 +127,8 @@ bring CPU4 back online:: $ echo 1 > /sys/devices/system/cpu/cpu4/online smpboot: Booting Node 0 Processor 4 APIC 0x1 -The CPU is usable again. This should work on all CPUs. CPU0 is often special -and excluded from CPU hotplug. On X86 the kernel option -*CONFIG_BOOTPARAM_HOTPLUG_CPU0* has to be enabled in order to be able to -shutdown CPU0. Alternatively the kernel command option *cpu0_hotplug* can be -used. Some known dependencies of CPU0: - -* Resume from hibernate/suspend. Hibernate/suspend will fail if CPU0 is offline. -* PIC interrupts. CPU0 can't be removed if a PIC interrupt is detected. - -Please let Fenghua Yu <fenghua.yu@intel.com> know if you find any dependencies -on CPU0. +The CPU is usable again. This should work on all CPUs, but CPU0 is often special +and excluded from CPU hotplug. The CPU hotplug coordination ============================ diff --git a/Documentation/core-api/kernel-api.rst b/Documentation/core-api/kernel-api.rst index 9b3f3e5f5a95..f2bcc5a7ea43 100644 --- a/Documentation/core-api/kernel-api.rst +++ b/Documentation/core-api/kernel-api.rst @@ -96,6 +96,12 @@ Command-line Parsing .. kernel-doc:: lib/cmdline.c :export: +Error Pointers +-------------- + +.. kernel-doc:: include/linux/err.h + :internal: + Sorting ------- @@ -412,3 +418,15 @@ Read-Copy Update (RCU) .. kernel-doc:: include/linux/rcu_sync.h .. kernel-doc:: kernel/rcu/sync.c + +.. kernel-doc:: kernel/rcu/tasks.h + +.. kernel-doc:: kernel/rcu/tree_stall.h + +.. kernel-doc:: include/linux/rcupdate_trace.h + +.. kernel-doc:: include/linux/rcupdate_wait.h + +.. kernel-doc:: include/linux/rcuref.h + +.. kernel-doc:: include/linux/rcutree.h diff --git a/Documentation/core-api/pin_user_pages.rst b/Documentation/core-api/pin_user_pages.rst index 9fb0b1080d3b..d3c1f6d8c0e0 100644 --- a/Documentation/core-api/pin_user_pages.rst +++ b/Documentation/core-api/pin_user_pages.rst @@ -112,6 +112,12 @@ pages: This also leads to limitations: there are only 31-10==21 bits available for a counter that increments 10 bits at a time. +* Because of that limitation, special handling is applied to the zero pages + when using FOLL_PIN. We only pretend to pin a zero page - we don't alter its + refcount or pincount at all (it is permanent, so there's no need). The + unpinning functions also don't do anything to a zero page. This is + transparent to the caller. + * Callers must specifically request "dma-pinned tracking of pages". In other words, just calling get_user_pages() will not suffice; a new set of functions, pin_user_page() and related, must be used. diff --git a/Documentation/core-api/this_cpu_ops.rst b/Documentation/core-api/this_cpu_ops.rst index 5cb8b883ae83..91acbcf30e9b 100644 --- a/Documentation/core-api/this_cpu_ops.rst +++ b/Documentation/core-api/this_cpu_ops.rst @@ -53,7 +53,6 @@ preemption and interrupts:: this_cpu_add_return(pcp, val) this_cpu_xchg(pcp, nval) this_cpu_cmpxchg(pcp, oval, nval) - this_cpu_cmpxchg_double(pcp1, pcp2, oval1, oval2, nval1, nval2) this_cpu_sub(pcp, val) this_cpu_inc(pcp) this_cpu_dec(pcp) @@ -242,7 +241,6 @@ safe:: __this_cpu_add_return(pcp, val) __this_cpu_xchg(pcp, nval) __this_cpu_cmpxchg(pcp, oval, nval) - __this_cpu_cmpxchg_double(pcp1, pcp2, oval1, oval2, nval1, nval2) __this_cpu_sub(pcp, val) __this_cpu_inc(pcp) __this_cpu_dec(pcp) diff --git a/Documentation/core-api/workqueue.rst b/Documentation/core-api/workqueue.rst index 8ec4d6270b24..a4c9b9d1905f 100644 --- a/Documentation/core-api/workqueue.rst +++ b/Documentation/core-api/workqueue.rst @@ -348,6 +348,37 @@ Guidelines level of locality in wq operations and work item execution. +Monitoring +========== + +Use tools/workqueue/wq_monitor.py to monitor workqueue operations: :: + + $ tools/workqueue/wq_monitor.py events + total infl CPUtime CPUhog CMwake mayday rescued + events 18545 0 6.1 0 5 - - + events_highpri 8 0 0.0 0 0 - - + events_long 3 0 0.0 0 0 - - + events_unbound 38306 0 0.1 - - - - + events_freezable 0 0 0.0 0 0 - - + events_power_efficient 29598 0 0.2 0 0 - - + events_freezable_power_ 10 0 0.0 0 0 - - + sock_diag_events 0 0 0.0 0 0 - - + + total infl CPUtime CPUhog CMwake mayday rescued + events 18548 0 6.1 0 5 - - + events_highpri 8 0 0.0 0 0 - - + events_long 3 0 0.0 0 0 - - + events_unbound 38322 0 0.1 - - - - + events_freezable 0 0 0.0 0 0 - - + events_power_efficient 29603 0 0.2 0 0 - - + events_freezable_power_ 10 0 0.0 0 0 - - + sock_diag_events 0 0 0.0 0 0 - - + + ... + +See the command's help message for more info. + + Debugging ========= @@ -387,6 +418,7 @@ the stack trace of the offending worker thread. :: The work item's function should be trivially visible in the stack trace. + Non-reentrance Conditions ========================= diff --git a/Documentation/crypto/async-tx-api.rst b/Documentation/crypto/async-tx-api.rst index bfc773991bdc..27c146b54d71 100644 --- a/Documentation/crypto/async-tx-api.rst +++ b/Documentation/crypto/async-tx-api.rst @@ -66,7 +66,7 @@ features surfaced as a result: :: struct dma_async_tx_descriptor * - async_<operation>(<op specific parameters>, struct async_submit ctl *submit) + async_<operation>(<op specific parameters>, struct async_submit_ctl *submit) 3.2 Supported operations ------------------------ diff --git a/Documentation/dev-tools/kasan.rst b/Documentation/dev-tools/kasan.rst index e66916a483cd..f4acf9c2e90f 100644 --- a/Documentation/dev-tools/kasan.rst +++ b/Documentation/dev-tools/kasan.rst @@ -107,9 +107,12 @@ effectively disables ``panic_on_warn`` for KASAN reports. Alternatively, independent of ``panic_on_warn``, the ``kasan.fault=`` boot parameter can be used to control panic and reporting behaviour: -- ``kasan.fault=report`` or ``=panic`` controls whether to only print a KASAN - report or also panic the kernel (default: ``report``). The panic happens even - if ``kasan_multi_shot`` is enabled. +- ``kasan.fault=report``, ``=panic``, or ``=panic_on_write`` controls whether + to only print a KASAN report, panic the kernel, or panic the kernel on + invalid writes only (default: ``report``). The panic happens even if + ``kasan_multi_shot`` is enabled. Note that when using asynchronous mode of + Hardware Tag-Based KASAN, ``kasan.fault=panic_on_write`` always panics on + asynchronously checked accesses (including reads). Software and Hardware Tag-Based KASAN modes (see the section about various modes below) support altering stack trace collection behavior: diff --git a/Documentation/dev-tools/kselftest.rst b/Documentation/dev-tools/kselftest.rst index 12b575b76b20..deede972f254 100644 --- a/Documentation/dev-tools/kselftest.rst +++ b/Documentation/dev-tools/kselftest.rst @@ -36,6 +36,7 @@ Running the selftests (hotplug tests are run in limited mode) To build the tests:: + $ make headers $ make -C tools/testing/selftests To run the tests:: @@ -168,6 +169,28 @@ the `-t` option for specific single tests. Either can be used multiple times:: For other features see the script usage output, seen with the `-h` option. +Timeout for selftests +===================== + +Selftests are designed to be quick and so a default timeout is used of 45 +seconds for each test. Tests can override the default timeout by adding +a settings file in their directory and set a timeout variable there to the +configured a desired upper timeout for the test. Only a few tests override +the timeout with a value higher than 45 seconds, selftests strives to keep +it that way. Timeouts in selftests are not considered fatal because the +system under which a test runs may change and this can also modify the +expected time it takes to run a test. If you have control over the systems +which will run the tests you can configure a test runner on those systems to +use a greater or lower timeout on the command line as with the `-o` or +the `--override-timeout` argument. For example to use 165 seconds instead +one would use: + + $ ./run_kselftest.sh --override-timeout 165 + +You can look at the TAP output to see if you ran into the timeout. Test +runners which know a test must run under a specific time can then optionally +treat these timeouts then as fatal. + Packaging selftests =================== diff --git a/Documentation/dev-tools/kunit/architecture.rst b/Documentation/dev-tools/kunit/architecture.rst index e95ab05342bb..f335f883f8f6 100644 --- a/Documentation/dev-tools/kunit/architecture.rst +++ b/Documentation/dev-tools/kunit/architecture.rst @@ -119,9 +119,9 @@ All expectations/assertions are formatted as: terminated immediately. - Assertions call the function: - ``void __noreturn kunit_abort(struct kunit *)``. + ``void __noreturn __kunit_abort(struct kunit *)``. - - ``kunit_abort`` calls the function: + - ``__kunit_abort`` calls the function: ``void __noreturn kunit_try_catch_throw(struct kunit_try_catch *try_catch)``. - ``kunit_try_catch_throw`` calls the function: diff --git a/Documentation/dev-tools/kunit/start.rst b/Documentation/dev-tools/kunit/start.rst index c736613c9b19..a98235326bab 100644 --- a/Documentation/dev-tools/kunit/start.rst +++ b/Documentation/dev-tools/kunit/start.rst @@ -250,15 +250,20 @@ Now we are ready to write the test cases. }; kunit_test_suite(misc_example_test_suite); + MODULE_LICENSE("GPL"); + 2. Add the following lines to ``drivers/misc/Kconfig``: .. code-block:: kconfig config MISC_EXAMPLE_TEST tristate "Test for my example" if !KUNIT_ALL_TESTS - depends on MISC_EXAMPLE && KUNIT=y + depends on MISC_EXAMPLE && KUNIT default KUNIT_ALL_TESTS +Note: If your test does not support being built as a loadable module (which is +discouraged), replace tristate by bool, and depend on KUNIT=y instead of KUNIT. + 3. Add the following lines to ``drivers/misc/Makefile``: .. code-block:: make diff --git a/Documentation/dev-tools/kunit/usage.rst b/Documentation/dev-tools/kunit/usage.rst index 9faf2b4153fc..c27e1646ecd9 100644 --- a/Documentation/dev-tools/kunit/usage.rst +++ b/Documentation/dev-tools/kunit/usage.rst @@ -121,6 +121,12 @@ there's an allocation error. ``return`` so they only work from the test function. In KUnit, we stop the current kthread on failure, so you can call them from anywhere. +.. note:: + Warning: There is an exception to the above rule. You shouldn't use assertions + in the suite's exit() function, or in the free function for a resource. These + run when a test is shutting down, and an assertion here prevents further + cleanup code from running, potentially leading to a memory leak. + Customizing error messages -------------------------- @@ -160,7 +166,12 @@ many similar tests. In order to reduce duplication in these closely related tests, most unit testing frameworks (including KUnit) provide the concept of a *test suite*. A test suite is a collection of test cases for a unit of code with optional setup and teardown functions that run before/after the whole -suite and/or every test case. For example: +suite and/or every test case. + +.. note:: + A test case will only run if it is associated with a test suite. + +For example: .. code-block:: c @@ -190,7 +201,10 @@ after everything else. ``kunit_test_suite(example_test_suite)`` registers the test suite with the KUnit test framework. .. note:: - A test case will only run if it is associated with a test suite. + The ``exit`` and ``suite_exit`` functions will run even if ``init`` or + ``suite_init`` fail. Make sure that they can handle any inconsistent + state which may result from ``init`` or ``suite_init`` encountering errors + or exiting early. ``kunit_test_suite(...)`` is a macro which tells the linker to put the specified test suite in a special linker section so that it can be run by KUnit @@ -601,6 +615,57 @@ For example: KUNIT_ASSERT_STREQ(test, buffer, ""); } +Registering Cleanup Actions +--------------------------- + +If you need to perform some cleanup beyond simple use of ``kunit_kzalloc``, +you can register a custom "deferred action", which is a cleanup function +run when the test exits (whether cleanly, or via a failed assertion). + +Actions are simple functions with no return value, and a single ``void*`` +context argument, and fulfill the same role as "cleanup" functions in Python +and Go tests, "defer" statements in languages which support them, and +(in some cases) destructors in RAII languages. + +These are very useful for unregistering things from global lists, closing +files or other resources, or freeing resources. + +For example: + +.. code-block:: C + + static void cleanup_device(void *ctx) + { + struct device *dev = (struct device *)ctx; + + device_unregister(dev); + } + + void example_device_test(struct kunit *test) + { + struct my_device dev; + + device_register(&dev); + + kunit_add_action(test, &cleanup_device, &dev); + } + +Note that, for functions like device_unregister which only accept a single +pointer-sized argument, it's possible to directly cast that function to +a ``kunit_action_t`` rather than writing a wrapper function, for example: + +.. code-block:: C + + kunit_add_action(test, (kunit_action_t *)&device_unregister, &dev); + +``kunit_add_action`` can fail if, for example, the system is out of memory. +You can use ``kunit_add_action_or_reset`` instead which runs the action +immediately if it cannot be deferred. + +If you need more control over when the cleanup function is called, you +can trigger it early using ``kunit_release_action``, or cancel it entirely +with ``kunit_remove_action``. + Testing Static Functions ------------------------ diff --git a/Documentation/devicetree/bindings/arm/xen.txt b/Documentation/devicetree/bindings/arm/xen.txt index 61d77acbeb5e..f925290d4641 100644 --- a/Documentation/devicetree/bindings/arm/xen.txt +++ b/Documentation/devicetree/bindings/arm/xen.txt @@ -56,7 +56,7 @@ hypervisor { }; The format and meaning of the "xen,uefi-*" parameters are similar to those in -Documentation/arm/uefi.rst, which are provided by the regular UEFI stub. However +Documentation/arch/arm/uefi.rst, which are provided by the regular UEFI stub. However they differ because they are provided by the Xen hypervisor, together with a set of UEFI runtime services implemented via hypercalls, see http://xenbits.xen.org/docs/unstable/hypercall/x86_64/include,public,platform.h.html. diff --git a/Documentation/devicetree/bindings/cpu/idle-states.yaml b/Documentation/devicetree/bindings/cpu/idle-states.yaml index b8cc826c9501..b3a5356f9916 100644 --- a/Documentation/devicetree/bindings/cpu/idle-states.yaml +++ b/Documentation/devicetree/bindings/cpu/idle-states.yaml @@ -259,7 +259,7 @@ description: |+ http://infocenter.arm.com/help/index.jsp [5] ARM Linux Kernel documentation - Booting AArch64 Linux - Documentation/arm64/booting.rst + Documentation/arch/arm64/booting.rst [6] RISC-V Linux Kernel documentation - CPUs bindings Documentation/devicetree/bindings/riscv/cpus.yaml diff --git a/Documentation/devicetree/bindings/firmware/qcom,scm.yaml b/Documentation/devicetree/bindings/firmware/qcom,scm.yaml index 367d04ad1923..83381f3a1341 100644 --- a/Documentation/devicetree/bindings/firmware/qcom,scm.yaml +++ b/Documentation/devicetree/bindings/firmware/qcom,scm.yaml @@ -71,6 +71,8 @@ properties: minItems: 1 maxItems: 3 + dma-coherent: true + interconnects: maxItems: 1 diff --git a/Documentation/devicetree/bindings/i2c/opencores,i2c-ocores.yaml b/Documentation/devicetree/bindings/i2c/opencores,i2c-ocores.yaml index 85d9efb743ee..d9ef86729011 100644 --- a/Documentation/devicetree/bindings/i2c/opencores,i2c-ocores.yaml +++ b/Documentation/devicetree/bindings/i2c/opencores,i2c-ocores.yaml @@ -60,6 +60,7 @@ properties: default: 0 regstep: + $ref: /schemas/types.yaml#/definitions/uint32 description: | deprecated, use reg-shift above deprecated: true diff --git a/Documentation/devicetree/bindings/interrupt-controller/loongson,eiointc.yaml b/Documentation/devicetree/bindings/interrupt-controller/loongson,eiointc.yaml new file mode 100644 index 000000000000..393c128a41d8 --- /dev/null +++ b/Documentation/devicetree/bindings/interrupt-controller/loongson,eiointc.yaml @@ -0,0 +1,59 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/interrupt-controller/loongson,eiointc.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Loongson Extended I/O Interrupt Controller + +maintainers: + - Binbin Zhou <zhoubinbin@loongson.cn> + +description: | + This interrupt controller is found on the Loongson-3 family chips and + Loongson-2K series chips and is used to distribute interrupts directly to + individual cores without forwarding them through the HT's interrupt line. + +allOf: + - $ref: /schemas/interrupt-controller.yaml# + +properties: + compatible: + enum: + - loongson,ls2k0500-eiointc + - loongson,ls2k2000-eiointc + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + interrupt-controller: true + + '#interrupt-cells': + const: 1 + +required: + - compatible + - reg + - interrupts + - interrupt-controller + - '#interrupt-cells' + +unevaluatedProperties: false + +examples: + - | + eiointc: interrupt-controller@1fe11600 { + compatible = "loongson,ls2k0500-eiointc"; + reg = <0x1fe10000 0x10000>; + + interrupt-controller; + #interrupt-cells = <1>; + + interrupt-parent = <&cpuintc>; + interrupts = <3>; + }; + +... diff --git a/Documentation/devicetree/bindings/memory-controllers/nuvoton,npcm-memory-controller.yaml b/Documentation/devicetree/bindings/memory-controllers/nuvoton,npcm-memory-controller.yaml new file mode 100644 index 000000000000..ac1a5a17749d --- /dev/null +++ b/Documentation/devicetree/bindings/memory-controllers/nuvoton,npcm-memory-controller.yaml @@ -0,0 +1,50 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/memory-controllers/nuvoton,npcm-memory-controller.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Nuvoton NPCM Memory Controller + +maintainers: + - Marvin Lin <kflin@nuvoton.com> + - Stanley Chu <yschu@nuvoton.com> + +description: | + The Nuvoton BMC SoC supports DDR4 memory with or without ECC (error correction + check). + + The memory controller supports single bit error correction, double bit error + detection (in-line ECC in which a section (1/8th) of the memory device used to + store data is used for ECC storage). + + Note, the bootloader must configure ECC mode for the memory controller. + +properties: + compatible: + enum: + - nuvoton,npcm750-memory-controller + - nuvoton,npcm845-memory-controller + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + +required: + - compatible + - reg + - interrupts + +additionalProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/arm-gic.h> + + mc: memory-controller@f0824000 { + compatible = "nuvoton,npcm750-memory-controller"; + reg = <0xf0824000 0x1000>; + interrupts = <GIC_SPI 25 IRQ_TYPE_LEVEL_HIGH>; + }; diff --git a/Documentation/devicetree/bindings/mfd/rockchip,rk806.yaml b/Documentation/devicetree/bindings/mfd/rockchip,rk806.yaml new file mode 100644 index 000000000000..cf2500f2e9a0 --- /dev/null +++ b/Documentation/devicetree/bindings/mfd/rockchip,rk806.yaml @@ -0,0 +1,406 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/mfd/rockchip,rk806.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: RK806 Power Management Integrated Circuit + +maintainers: + - Sebastian Reichel <sebastian.reichel@collabora.com> + +description: + Rockchip RK806 series PMIC. This device consists of an spi or + i2c controlled MFD that includes multiple switchable regulators. + +properties: + compatible: + enum: + - rockchip,rk806 + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + gpio-controller: true + + '#gpio-cells': + const: 2 + + vcc1-supply: + description: + The input supply for dcdc-reg1. + + vcc2-supply: + description: + The input supply for dcdc-reg2. + + vcc3-supply: + description: + The input supply for dcdc-reg3. + + vcc4-supply: + description: + The input supply for dcdc-reg4. + + vcc5-supply: + description: + The input supply for dcdc-reg5. + + vcc6-supply: + description: + The input supply for dcdc-reg6. + + vcc7-supply: + description: + The input supply for dcdc-reg7. + + vcc8-supply: + description: + The input supply for dcdc-reg8. + + vcc9-supply: + description: + The input supply for dcdc-reg9. + + vcc10-supply: + description: + The input supply for dcdc-reg10. + + vcc11-supply: + description: + The input supply for pldo-reg1, pldo-reg2 and pldo-reg3. + + vcc12-supply: + description: + The input supply for pldo-reg4 and pldo-reg5. + + vcc13-supply: + description: + The input supply for nldo-reg1, nldo-reg2 and nldo-reg3. + + vcc14-supply: + description: + The input supply for nldo-reg4 and nldo-reg5. + + vcca-supply: + description: + The input supply for pldo-reg6. + + regulators: + type: object + additionalProperties: false + patternProperties: + "^(dcdc-reg([1-9]|10)|pldo-reg[1-6]|nldo-reg[1-5])$": + type: object + $ref: /schemas/regulator/regulator.yaml# + unevaluatedProperties: false + +patternProperties: + '-pins$': + type: object + additionalProperties: false + $ref: /schemas/pinctrl/pinmux-node.yaml + + properties: + function: + enum: [pin_fun0, pin_fun1, pin_fun2, pin_fun3, pin_fun4, pin_fun5] + + pins: + $ref: /schemas/types.yaml#/definitions/string + enum: [gpio_pwrctrl1, gpio_pwrctrl2, gpio_pwrctrl3] + +allOf: + - $ref: /schemas/spi/spi-peripheral-props.yaml + +required: + - compatible + - reg + - interrupts + +unevaluatedProperties: false + +examples: + - | + #include <dt-bindings/pinctrl/rockchip.h> + #include <dt-bindings/interrupt-controller/irq.h> + #include <dt-bindings/gpio/gpio.h> + spi { + #address-cells = <1>; + #size-cells = <0>; + + pmic@0 { + compatible = "rockchip,rk806"; + reg = <0x0>; + + interrupts = <7 IRQ_TYPE_LEVEL_LOW>; + + vcc1-supply = <&vcc5v0_sys>; + vcc2-supply = <&vcc5v0_sys>; + vcc3-supply = <&vcc5v0_sys>; + vcc4-supply = <&vcc5v0_sys>; + vcc5-supply = <&vcc5v0_sys>; + vcc6-supply = <&vcc5v0_sys>; + vcc7-supply = <&vcc5v0_sys>; + vcc8-supply = <&vcc5v0_sys>; + vcc9-supply = <&vcc5v0_sys>; + vcc10-supply = <&vcc5v0_sys>; + vcc11-supply = <&vcc_2v0_pldo_s3>; + vcc12-supply = <&vcc5v0_sys>; + vcc13-supply = <&vcc5v0_sys>; + vcc14-supply = <&vcc_1v1_nldo_s3>; + vcca-supply = <&vcc5v0_sys>; + + regulators { + vdd_gpu_s0: dcdc-reg1 { + regulator-always-on; + regulator-boot-on; + regulator-min-microvolt = <550000>; + regulator-max-microvolt = <950000>; + regulator-ramp-delay = <12500>; + regulator-name = "vdd_gpu_s0"; + regulator-state-mem { + regulator-off-in-suspend; + }; + }; + + vdd_npu_s0: dcdc-reg2 { + regulator-always-on; + regulator-boot-on; + regulator-min-microvolt = <550000>; + regulator-max-microvolt = <950000>; + regulator-ramp-delay = <12500>; + regulator-name = "vdd_npu_s0"; + regulator-state-mem { + regulator-off-in-suspend; + }; + }; + + vdd_log_s0: dcdc-reg3 { + regulator-always-on; + regulator-boot-on; + regulator-min-microvolt = <750000>; + regulator-max-microvolt = <750000>; + regulator-ramp-delay = <12500>; + regulator-name = "vdd_log_s0"; + regulator-state-mem { + regulator-on-in-suspend; + regulator-suspend-microvolt = <750000>; + }; + }; + + vdd_vdenc_s0: dcdc-reg4 { + regulator-always-on; + regulator-boot-on; + regulator-min-microvolt = <550000>; + regulator-max-microvolt = <950000>; + regulator-ramp-delay = <12500>; + regulator-name = "vdd_vdenc_s0"; + regulator-state-mem { + regulator-off-in-suspend; + }; + }; + + vdd_gpu_mem_s0: dcdc-reg5 { + regulator-always-on; + regulator-boot-on; + regulator-min-microvolt = <675000>; + regulator-max-microvolt = <950000>; + regulator-ramp-delay = <12500>; + regulator-name = "vdd_gpu_mem_s0"; + regulator-state-mem { + regulator-off-in-suspend; + }; + }; + + vdd_npu_mem_s0: dcdc-reg6 { + regulator-always-on; + regulator-boot-on; + regulator-min-microvolt = <675000>; + regulator-max-microvolt = <950000>; + regulator-ramp-delay = <12500>; + regulator-name = "vdd_npu_mem_s0"; + regulator-state-mem { + regulator-off-in-suspend; + }; + }; + + vcc_2v0_pldo_s3: dcdc-reg7 { + regulator-always-on; + regulator-boot-on; + regulator-min-microvolt = <2000000>; + regulator-max-microvolt = <2000000>; + regulator-ramp-delay = <12500>; + regulator-name = "vdd_2v0_pldo_s3"; + regulator-state-mem { + regulator-on-in-suspend; + regulator-suspend-microvolt = <2000000>; + }; + }; + + vdd_vdenc_mem_s0: dcdc-reg8 { + regulator-always-on; + regulator-boot-on; + regulator-min-microvolt = <675000>; + regulator-max-microvolt = <950000>; + regulator-ramp-delay = <12500>; + regulator-name = "vdd_vdenc_mem_s0"; + regulator-state-mem { + regulator-off-in-suspend; + }; + }; + + vdd2_ddr_s3: dcdc-reg9 { + regulator-always-on; + regulator-boot-on; + regulator-name = "vdd2_ddr_s3"; + regulator-state-mem { + regulator-on-in-suspend; + }; + }; + + vcc_1v1_nldo_s3: dcdc-reg10 { + regulator-always-on; + regulator-boot-on; + regulator-min-microvolt = <1100000>; + regulator-max-microvolt = <1100000>; + regulator-ramp-delay = <12500>; + regulator-name = "vcc_1v1_nldo_s3"; + regulator-state-mem { + regulator-on-in-suspend; + regulator-suspend-microvolt = <1100000>; + }; + }; + + avcc_1v8_s0: pldo-reg1 { + regulator-always-on; + regulator-boot-on; + regulator-min-microvolt = <1800000>; + regulator-max-microvolt = <1800000>; + regulator-ramp-delay = <12500>; + regulator-name = "avcc_1v8_s0"; + regulator-state-mem { + regulator-off-in-suspend; + }; + }; + + vdd1_1v8_ddr_s3: pldo-reg2 { + regulator-always-on; + regulator-boot-on; + regulator-min-microvolt = <1800000>; + regulator-max-microvolt = <1800000>; + regulator-ramp-delay = <12500>; + regulator-name = "vdd1_1v8_ddr_s3"; + regulator-state-mem { + regulator-on-in-suspend; + regulator-suspend-microvolt = <1800000>; + }; + }; + + vcc_1v8_s3: pldo-reg3 { + regulator-always-on; + regulator-boot-on; + regulator-min-microvolt = <1800000>; + regulator-max-microvolt = <1800000>; + regulator-ramp-delay = <12500>; + regulator-name = "vcc_1v8_s3"; + regulator-state-mem { + regulator-on-in-suspend; + regulator-suspend-microvolt = <1800000>; + }; + }; + + vcc_3v3_s0: pldo-reg4 { + regulator-always-on; + regulator-boot-on; + regulator-min-microvolt = <3300000>; + regulator-max-microvolt = <3300000>; + regulator-ramp-delay = <12500>; + regulator-name = "vcc_3v3_s0"; + regulator-state-mem { + regulator-off-in-suspend; + }; + }; + + vccio_sd_s0: pldo-reg5 { + regulator-always-on; + regulator-boot-on; + regulator-min-microvolt = <1800000>; + regulator-max-microvolt = <3300000>; + regulator-ramp-delay = <12500>; + regulator-name = "vccio_sd_s0"; + regulator-state-mem { + regulator-off-in-suspend; + }; + }; + + master_pldo6_s3: pldo-reg6 { + regulator-always-on; + regulator-boot-on; + regulator-min-microvolt = <1800000>; + regulator-max-microvolt = <1800000>; + regulator-name = "master_pldo6_s3"; + regulator-state-mem { + regulator-on-in-suspend; + regulator-suspend-microvolt = <1800000>; + }; + }; + + vdd_0v75_s3: nldo-reg1 { + regulator-always-on; + regulator-boot-on; + regulator-min-microvolt = <750000>; + regulator-max-microvolt = <750000>; + regulator-ramp-delay = <12500>; + regulator-name = "vdd_0v75_s3"; + regulator-state-mem { + regulator-on-in-suspend; + regulator-suspend-microvolt = <750000>; + }; + }; + + vdd2l_0v9_ddr_s3: nldo-reg2 { + regulator-always-on; + regulator-boot-on; + regulator-min-microvolt = <900000>; + regulator-max-microvolt = <900000>; + regulator-name = "vdd2l_0v9_ddr_s3"; + regulator-state-mem { + regulator-on-in-suspend; + regulator-suspend-microvolt = <900000>; + }; + }; + + master_nldo3: nldo-reg3 { + regulator-name = "master_nldo3"; + regulator-state-mem { + regulator-off-in-suspend; + }; + }; + + avdd_0v75_s0: nldo-reg4 { + regulator-always-on; + regulator-boot-on; + regulator-min-microvolt = <750000>; + regulator-max-microvolt = <750000>; + regulator-name = "avdd_0v75_s0"; + regulator-state-mem { + regulator-off-in-suspend; + }; + }; + + vdd_0v85_s0: nldo-reg5 { + regulator-always-on; + regulator-boot-on; + regulator-min-microvolt = <850000>; + regulator-max-microvolt = <850000>; + regulator-name = "vdd_0v85_s0"; + regulator-state-mem { + regulator-off-in-suspend; + }; + }; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/mmc/arm,pl18x.yaml b/Documentation/devicetree/bindings/mmc/arm,pl18x.yaml index 1c96da04f0e5..2459a55ed540 100644 --- a/Documentation/devicetree/bindings/mmc/arm,pl18x.yaml +++ b/Documentation/devicetree/bindings/mmc/arm,pl18x.yaml @@ -53,10 +53,11 @@ properties: items: - const: arm,pl18x - const: arm,primecell - - description: Entry for STMicroelectronics variant of PL18x. - This dedicated compatible is used by bootloaders. + - description: Entries for STMicroelectronics variant of PL18x. items: - - const: st,stm32-sdmmc2 + - enum: + - st,stm32-sdmmc2 + - st,stm32mp25-sdmmc2 - const: arm,pl18x - const: arm,primecell diff --git a/Documentation/devicetree/bindings/mmc/brcm,bcm2835-sdhost.txt b/Documentation/devicetree/bindings/mmc/brcm,bcm2835-sdhost.txt deleted file mode 100644 index d876580ae3b8..000000000000 --- a/Documentation/devicetree/bindings/mmc/brcm,bcm2835-sdhost.txt +++ /dev/null @@ -1,23 +0,0 @@ -Broadcom BCM2835 SDHOST controller - -This file documents differences between the core properties described -by mmc.txt and the properties that represent the BCM2835 controller. - -Required properties: -- compatible: Should be "brcm,bcm2835-sdhost". -- clocks: The clock feeding the SDHOST controller. - -Optional properties: -- dmas: DMA channel for read and write. - See Documentation/devicetree/bindings/dma/dma.txt for details - -Example: - -sdhost: mmc@7e202000 { - compatible = "brcm,bcm2835-sdhost"; - reg = <0x7e202000 0x100>; - interrupts = <2 24>; - clocks = <&clocks BCM2835_CLOCK_VPU>; - dmas = <&dma 13>; - dma-names = "rx-tx"; -}; diff --git a/Documentation/devicetree/bindings/mmc/brcm,bcm2835-sdhost.yaml b/Documentation/devicetree/bindings/mmc/brcm,bcm2835-sdhost.yaml new file mode 100644 index 000000000000..3a5a44800675 --- /dev/null +++ b/Documentation/devicetree/bindings/mmc/brcm,bcm2835-sdhost.yaml @@ -0,0 +1,54 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/mmc/brcm,bcm2835-sdhost.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Broadcom BCM2835 SDHOST controller + +maintainers: + - Stefan Wahren <stefan.wahren@i2se.com> + +allOf: + - $ref: mmc-controller.yaml + +properties: + compatible: + const: brcm,bcm2835-sdhost + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + clocks: + maxItems: 1 + + dmas: + maxItems: 1 + + dma-names: + const: rx-tx + +required: + - compatible + - reg + - interrupts + - clocks + +unevaluatedProperties: false + +examples: + - | + #include <dt-bindings/clock/bcm2835.h> + + sdhost: mmc@7e202000 { + compatible = "brcm,bcm2835-sdhost"; + reg = <0x7e202000 0x100>; + interrupts = <2 24>; + clocks = <&clocks BCM2835_CLOCK_VPU>; + dmas = <&dma 13>; + dma-names = "rx-tx"; + bus-width = <4>; + }; diff --git a/Documentation/devicetree/bindings/mmc/brcm,kona-sdhci.txt b/Documentation/devicetree/bindings/mmc/brcm,kona-sdhci.txt deleted file mode 100644 index 7f5dd83f5bd9..000000000000 --- a/Documentation/devicetree/bindings/mmc/brcm,kona-sdhci.txt +++ /dev/null @@ -1,21 +0,0 @@ -Broadcom BCM281xx SDHCI - -This file documents differences between the core properties in mmc.txt -and the properties present in the bcm281xx SDHCI - -Required properties: -- compatible : Should be "brcm,kona-sdhci" -- DEPRECATED: compatible : Should be "bcm,kona-sdhci" -- clocks: phandle + clock specifier pair of the external clock - -Refer to clocks/clock-bindings.txt for generic clock consumer properties. - -Example: - -sdio2: sdio@3f1a0000 { - compatible = "brcm,kona-sdhci"; - reg = <0x3f1a0000 0x10000>; - clocks = <&sdio3_clk>; - interrupts = <0x0 74 0x4>; -}; - diff --git a/Documentation/devicetree/bindings/mmc/brcm,kona-sdhci.yaml b/Documentation/devicetree/bindings/mmc/brcm,kona-sdhci.yaml new file mode 100644 index 000000000000..12eb3988f824 --- /dev/null +++ b/Documentation/devicetree/bindings/mmc/brcm,kona-sdhci.yaml @@ -0,0 +1,48 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/mmc/brcm,kona-sdhci.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Broadcom Kona family SDHCI controller + +maintainers: + - Florian Fainelli <f.fainelli@gmail.com> + +allOf: + - $ref: sdhci-common.yaml# + +properties: + compatible: + const: brcm,kona-sdhci + + reg: + maxItems: 1 + + clocks: + maxItems: 1 + + interrupts: + maxItems: 1 + +required: + - compatible + - reg + - clocks + - interrupts + +unevaluatedProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/arm-gic.h> + #include <dt-bindings/interrupt-controller/irq.h> + #include <dt-bindings/clock/bcm281xx.h> + + mmc@3f1a0000 { + compatible = "brcm,kona-sdhci"; + reg = <0x3f1a0000 0x10000>; + clocks = <&master_ccu BCM281XX_MASTER_CCU_SDIO3>; + interrupts = <GIC_SPI 74 IRQ_TYPE_LEVEL_HIGH>; + }; +... diff --git a/Documentation/devicetree/bindings/mmc/fsl-imx-esdhc.yaml b/Documentation/devicetree/bindings/mmc/fsl-imx-esdhc.yaml index fbfd822b9270..82eb7a24c857 100644 --- a/Documentation/devicetree/bindings/mmc/fsl-imx-esdhc.yaml +++ b/Documentation/devicetree/bindings/mmc/fsl-imx-esdhc.yaml @@ -42,6 +42,7 @@ properties: - enum: - fsl,imx6sll-usdhc - fsl,imx6ull-usdhc + - fsl,imx6ul-usdhc - const: fsl,imx6sx-usdhc - items: - const: fsl,imx7d-usdhc diff --git a/Documentation/devicetree/bindings/mmc/sdhci-msm.yaml b/Documentation/devicetree/bindings/mmc/sdhci-msm.yaml index 4f2d9e8127dd..6da28e630577 100644 --- a/Documentation/devicetree/bindings/mmc/sdhci-msm.yaml +++ b/Documentation/devicetree/bindings/mmc/sdhci-msm.yaml @@ -36,11 +36,14 @@ properties: - enum: - qcom,ipq5018-sdhci - qcom,ipq5332-sdhci + - qcom,ipq6018-sdhci - qcom,ipq9574-sdhci - qcom,qcm2290-sdhci - qcom,qcs404-sdhci + - qcom,qdu1000-sdhci - qcom,sc7180-sdhci - qcom,sc7280-sdhci + - qcom,sc8280xp-sdhci - qcom,sdm630-sdhci - qcom,sdm670-sdhci - qcom,sdm845-sdhci diff --git a/Documentation/devicetree/bindings/mtd/allwinner,sun4i-a10-nand.yaml b/Documentation/devicetree/bindings/mtd/allwinner,sun4i-a10-nand.yaml index 9a88870cd865..054b6b8bf9b9 100644 --- a/Documentation/devicetree/bindings/mtd/allwinner,sun4i-a10-nand.yaml +++ b/Documentation/devicetree/bindings/mtd/allwinner,sun4i-a10-nand.yaml @@ -49,13 +49,12 @@ properties: patternProperties: "^nand@[a-f0-9]$": type: object + $ref: raw-nand-chip.yaml properties: reg: minimum: 0 maximum: 7 - nand-ecc-mode: true - nand-ecc-algo: const: bch @@ -75,7 +74,7 @@ patternProperties: minimum: 0 maximum: 1 - additionalProperties: false + unevaluatedProperties: false required: - compatible diff --git a/Documentation/devicetree/bindings/mtd/amlogic,meson-nand.yaml b/Documentation/devicetree/bindings/mtd/amlogic,meson-nand.yaml index 28fb9a7dd70f..787ef488dd5b 100644 --- a/Documentation/devicetree/bindings/mtd/amlogic,meson-nand.yaml +++ b/Documentation/devicetree/bindings/mtd/amlogic,meson-nand.yaml @@ -40,6 +40,7 @@ properties: patternProperties: "^nand@[0-7]$": type: object + $ref: raw-nand-chip.yaml properties: reg: minimum: 0 @@ -58,6 +59,14 @@ patternProperties: meson-gxl-nfc 8, 16, 24, 30, 40, 50, 60 meson-axg-nfc 8 + nand-rb: + maxItems: 1 + items: + maximum: 0 + + unevaluatedProperties: false + + required: - compatible - reg @@ -87,6 +96,7 @@ examples: nand@0 { reg = <0>; + nand-rb = <0>; }; }; diff --git a/Documentation/devicetree/bindings/mtd/brcm,brcmnand.yaml b/Documentation/devicetree/bindings/mtd/brcm,brcmnand.yaml index 1571024aa119..f57e96374e67 100644 --- a/Documentation/devicetree/bindings/mtd/brcm,brcmnand.yaml +++ b/Documentation/devicetree/bindings/mtd/brcm,brcmnand.yaml @@ -114,6 +114,7 @@ properties: patternProperties: "^nand@[a-f0-9]$": type: object + $ref: raw-nand-chip.yaml properties: compatible: const: brcm,nandcs @@ -136,6 +137,8 @@ patternProperties: layout. $ref: /schemas/types.yaml#/definitions/uint32 + unevaluatedProperties: false + allOf: - $ref: nand-controller.yaml# - if: diff --git a/Documentation/devicetree/bindings/mtd/denali,nand.yaml b/Documentation/devicetree/bindings/mtd/denali,nand.yaml index 0be83ad42970..81f95538d415 100644 --- a/Documentation/devicetree/bindings/mtd/denali,nand.yaml +++ b/Documentation/devicetree/bindings/mtd/denali,nand.yaml @@ -63,6 +63,12 @@ properties: minItems: 1 maxItems: 2 +patternProperties: + "^nand@[a-f0-9]$": + type: object + $ref: raw-nand-chip.yaml + unevaluatedProperties: false + allOf: - $ref: nand-controller.yaml @@ -74,7 +80,6 @@ allOf: then: patternProperties: "^nand@[a-f0-9]$": - type: object properties: nand-ecc-strength: enum: @@ -92,7 +97,6 @@ allOf: then: patternProperties: "^nand@[a-f0-9]$": - type: object properties: nand-ecc-strength: enum: @@ -111,7 +115,6 @@ allOf: then: patternProperties: "^nand@[a-f0-9]$": - type: object properties: nand-ecc-strength: enum: diff --git a/Documentation/devicetree/bindings/mtd/ingenic,nand.yaml b/Documentation/devicetree/bindings/mtd/ingenic,nand.yaml index a7bdb5d3675c..b9312ebefeb9 100644 --- a/Documentation/devicetree/bindings/mtd/ingenic,nand.yaml +++ b/Documentation/devicetree/bindings/mtd/ingenic,nand.yaml @@ -39,7 +39,9 @@ properties: patternProperties: "^nand@[a-f0-9]$": type: object + $ref: raw-nand-chip.yaml properties: + rb-gpios: description: GPIO specifier for the busy pin. maxItems: 1 @@ -48,6 +50,8 @@ patternProperties: description: GPIO specifier for the write-protect pin. maxItems: 1 + unevaluatedProperties: false + required: - compatible - reg diff --git a/Documentation/devicetree/bindings/mtd/intel,lgm-ebunand.yaml b/Documentation/devicetree/bindings/mtd/intel,lgm-ebunand.yaml index cc3def758e00..07bc7e3efd3a 100644 --- a/Documentation/devicetree/bindings/mtd/intel,lgm-ebunand.yaml +++ b/Documentation/devicetree/bindings/mtd/intel,lgm-ebunand.yaml @@ -42,17 +42,16 @@ properties: patternProperties: "^nand@[a-f0-9]$": type: object + $ref: raw-nand-chip.yaml properties: reg: minimum: 0 maximum: 1 - nand-ecc-mode: true - nand-ecc-algo: const: hw - additionalProperties: false + unevaluatedProperties: false required: - compatible diff --git a/Documentation/devicetree/bindings/mtd/marvell,nand-controller.yaml b/Documentation/devicetree/bindings/mtd/marvell,nand-controller.yaml new file mode 100644 index 000000000000..a10729bb1840 --- /dev/null +++ b/Documentation/devicetree/bindings/mtd/marvell,nand-controller.yaml @@ -0,0 +1,226 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/mtd/marvell,nand-controller.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Marvell NAND Flash Controller (NFC) + +maintainers: + - Miquel Raynal <miquel.raynal@bootlin.com> + +properties: + compatible: + oneOf: + - items: + - const: marvell,armada-8k-nand-controller + - const: marvell,armada370-nand-controller + - enum: + - marvell,armada370-nand-controller + - marvell,pxa3xx-nand-controller + - description: legacy bindings + deprecated: true + enum: + - marvell,armada-8k-nand + - marvell,armada370-nand + - marvell,pxa3xx-nand + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + clocks: + description: + Shall reference the NAND controller clocks, the second one is + is only needed for the Armada 7K/8K SoCs + minItems: 1 + maxItems: 2 + + clock-names: + minItems: 1 + items: + - const: core + - const: reg + + dmas: + maxItems: 1 + + dma-names: + items: + - const: data + + marvell,system-controller: + $ref: /schemas/types.yaml#/definitions/phandle + description: Syscon node that handles NAND controller related registers + +patternProperties: + "^nand@[a-f0-9]$": + type: object + $ref: raw-nand-chip.yaml + + properties: + reg: + minimum: 0 + maximum: 3 + + nand-rb: + items: + - minimum: 0 + maximum: 1 + + nand-ecc-step-size: + const: 512 + + nand-ecc-strength: + enum: [1, 4, 8, 12, 16] + + nand-ecc-mode: + const: hw + + marvell,nand-keep-config: + $ref: /schemas/types.yaml#/definitions/flag + description: + Orders the driver not to take the timings from the core and + leaving them completely untouched. Bootloader timings will then + be used. + + marvell,nand-enable-arbiter: + $ref: /schemas/types.yaml#/definitions/flag + description: + To enable the arbiter, all boards blindly used it, + this bit was set by the bootloader for many boards and even if + it is marked reserved in several datasheets, it might be needed to set + it (otherwise it is harmless). + deprecated: true + + required: + - reg + - nand-rb + + unevaluatedProperties: false + +required: + - compatible + - reg + - interrupts + - clocks + +allOf: + - $ref: nand-controller.yaml# + + - if: + properties: + compatible: + contains: + const: marvell,pxa3xx-nand-controller + then: + required: + - dmas + - dma-names + + - if: + properties: + compatible: + contains: + const: marvell,armada-8k-nand-controller + then: + properties: + clocks: + minItems: 2 + + clock-names: + minItems: 2 + + required: + - marvell,system-controller + + else: + properties: + clocks: + minItems: 1 + + clock-names: + minItems: 1 + + +unevaluatedProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/arm-gic.h> + nand_controller: nand-controller@d0000 { + compatible = "marvell,armada370-nand-controller"; + reg = <0xd0000 0x54>; + #address-cells = <1>; + #size-cells = <0>; + interrupts = <GIC_SPI 84 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&coredivclk 0>; + + nand@0 { + reg = <0>; + label = "main-storage"; + nand-rb = <0>; + nand-ecc-mode = "hw"; + marvell,nand-keep-config; + nand-on-flash-bbt; + nand-ecc-strength = <4>; + nand-ecc-step-size = <512>; + + partitions { + compatible = "fixed-partitions"; + #address-cells = <1>; + #size-cells = <1>; + + partition@0 { + label = "Rootfs"; + reg = <0x00000000 0x40000000>; + }; + }; + }; + }; + + - | + cp0_nand_controller: nand-controller@720000 { + compatible = "marvell,armada-8k-nand-controller", + "marvell,armada370-nand-controller"; + reg = <0x720000 0x54>; + #address-cells = <1>; + #size-cells = <0>; + interrupts = <115 IRQ_TYPE_LEVEL_HIGH>; + clock-names = "core", "reg"; + clocks = <&cp0_clk 1 2>, + <&cp0_clk 1 17>; + marvell,system-controller = <&cp0_syscon0>; + + nand@0 { + reg = <0>; + label = "main-storage"; + nand-rb = <0>; + nand-ecc-mode = "hw"; + nand-ecc-strength = <8>; + nand-ecc-step-size = <512>; + }; + }; + + - | + nand-controller@43100000 { + compatible = "marvell,pxa3xx-nand-controller"; + reg = <0x43100000 90>; + interrupts = <45>; + clocks = <&clks 1>; + clock-names = "core"; + dmas = <&pdma 97 3>; + dma-names = "data"; + #address-cells = <1>; + #size-cells = <0>; + nand@0 { + reg = <0>; + nand-rb = <0>; + nand-ecc-mode = "hw"; + marvell,nand-keep-config; + }; + }; + +... diff --git a/Documentation/devicetree/bindings/mtd/marvell-nand.txt b/Documentation/devicetree/bindings/mtd/marvell-nand.txt deleted file mode 100644 index a2d9a0f2b683..000000000000 --- a/Documentation/devicetree/bindings/mtd/marvell-nand.txt +++ /dev/null @@ -1,126 +0,0 @@ -Marvell NAND Flash Controller (NFC) - -Required properties: -- compatible: can be one of the following: - * "marvell,armada-8k-nand-controller" - * "marvell,armada370-nand-controller" - * "marvell,pxa3xx-nand-controller" - * "marvell,armada-8k-nand" (deprecated) - * "marvell,armada370-nand" (deprecated) - * "marvell,pxa3xx-nand" (deprecated) - Compatibles marked deprecated support only the old bindings described - at the bottom. -- reg: NAND flash controller memory area. -- #address-cells: shall be set to 1. Encode the NAND CS. -- #size-cells: shall be set to 0. -- interrupts: shall define the NAND controller interrupt. -- clocks: shall reference the NAND controller clocks, the second one is - is only needed for the Armada 7K/8K SoCs -- clock-names: mandatory if there is a second clock, in this case there - should be one clock named "core" and another one named "reg" -- marvell,system-controller: Set to retrieve the syscon node that handles - NAND controller related registers (only required with the - "marvell,armada-8k-nand[-controller]" compatibles). - -Optional properties: -- label: see partition.txt. New platforms shall omit this property. -- dmas: shall reference DMA channel associated to the NAND controller. - This property is only used with "marvell,pxa3xx-nand[-controller]" - compatible strings. -- dma-names: shall be "rxtx". - This property is only used with "marvell,pxa3xx-nand[-controller]" - compatible strings. - -Optional children nodes: -Children nodes represent the available NAND chips. - -Required properties: -- reg: shall contain the native Chip Select ids (0-3). -- nand-rb: see nand-controller.yaml (0-1). - -Optional properties: -- marvell,nand-keep-config: orders the driver not to take the timings - from the core and leaving them completely untouched. Bootloader - timings will then be used. -- label: MTD name. -- nand-on-flash-bbt: see nand-controller.yaml. -- nand-ecc-mode: see nand-controller.yaml. Will use hardware ECC if not specified. -- nand-ecc-algo: see nand-controller.yaml. This property is essentially useful when - not using hardware ECC. Howerver, it may be added when using hardware - ECC for clarification but will be ignored by the driver because ECC - mode is chosen depending on the page size and the strength required by - the NAND chip. This value may be overwritten with nand-ecc-strength - property. -- nand-ecc-strength: see nand-controller.yaml. -- nand-ecc-step-size: see nand-controller.yaml. Marvell's NAND flash controller does - use fixed strength (1-bit for Hamming, 16-bit for BCH), so the actual - step size will shrink or grow in order to fit the required strength. - Step sizes are not completely random for all and follow certain - patterns described in AN-379, "Marvell SoC NFC ECC". - -See Documentation/devicetree/bindings/mtd/nand-controller.yaml for more details on -generic bindings. - - -Example: -nand_controller: nand-controller@d0000 { - compatible = "marvell,armada370-nand-controller"; - reg = <0xd0000 0x54>; - #address-cells = <1>; - #size-cells = <0>; - interrupts = <GIC_SPI 84 IRQ_TYPE_LEVEL_HIGH>; - clocks = <&coredivclk 0>; - - nand@0 { - reg = <0>; - label = "main-storage"; - nand-rb = <0>; - nand-ecc-mode = "hw"; - marvell,nand-keep-config; - nand-on-flash-bbt; - nand-ecc-strength = <4>; - nand-ecc-step-size = <512>; - - partitions { - compatible = "fixed-partitions"; - #address-cells = <1>; - #size-cells = <1>; - - partition@0 { - label = "Rootfs"; - reg = <0x00000000 0x40000000>; - }; - }; - }; -}; - - -Note on legacy bindings: One can find, in not-updated device trees, -bindings slightly different than described above with other properties -described below as well as the partitions node at the root of a so -called "nand" node (without clear controller/chip separation). - -Legacy properties: -- marvell,nand-enable-arbiter: To enable the arbiter, all boards blindly - used it, this bit was set by the bootloader for many boards and even if - it is marked reserved in several datasheets, it might be needed to set - it (otherwise it is harmless) so whether or not this property is set, - the bit is selected by the driver. -- num-cs: Number of chip-select lines to use, all boards blindly set 1 - to this and for a reason, other values would have failed. The value of - this property is ignored. - -Example: - - nand0: nand@43100000 { - compatible = "marvell,pxa3xx-nand"; - reg = <0x43100000 90>; - interrupts = <45>; - dmas = <&pdma 97 0>; - dma-names = "rxtx"; - #address-cells = <1>; - marvell,nand-keep-config; - marvell,nand-enable-arbiter; - num-cs = <1>; - /* Partitions (optional) */ - }; diff --git a/Documentation/devicetree/bindings/mtd/mediatek,mtk-nfc.yaml b/Documentation/devicetree/bindings/mtd/mediatek,mtk-nfc.yaml index a6e7f123eda7..ab503a33a269 100644 --- a/Documentation/devicetree/bindings/mtd/mediatek,mtk-nfc.yaml +++ b/Documentation/devicetree/bindings/mtd/mediatek,mtk-nfc.yaml @@ -40,12 +40,11 @@ properties: patternProperties: "^nand@[a-f0-9]$": - $ref: nand-chip.yaml# + $ref: raw-nand-chip.yaml# unevaluatedProperties: false properties: reg: maximum: 1 - nand-on-flash-bbt: true nand-ecc-mode: const: hw diff --git a/Documentation/devicetree/bindings/mtd/mtd.yaml b/Documentation/devicetree/bindings/mtd/mtd.yaml index da3d488c335f..b82ca03e969c 100644 --- a/Documentation/devicetree/bindings/mtd/mtd.yaml +++ b/Documentation/devicetree/bindings/mtd/mtd.yaml @@ -12,7 +12,7 @@ maintainers: properties: $nodename: - pattern: "^(flash|.*sram)(@.*)?$" + pattern: "^(flash|.*sram|nand)(@.*)?$" label: description: diff --git a/Documentation/devicetree/bindings/mtd/nand-controller.yaml b/Documentation/devicetree/bindings/mtd/nand-controller.yaml index f70a32d2d9d4..83a4fe4cc29d 100644 --- a/Documentation/devicetree/bindings/mtd/nand-controller.yaml +++ b/Documentation/devicetree/bindings/mtd/nand-controller.yaml @@ -16,16 +16,6 @@ description: | children nodes of the NAND controller. This representation should be enforced even for simple controllers supporting only one chip. - The ECC strength and ECC step size properties define the user - desires in terms of correction capability of a controller. Together, - they request the ECC engine to correct {strength} bit errors per - {size} bytes. - - The interpretation of these parameters is implementation-defined, so - not all implementations must support all possible - combinations. However, implementations are encouraged to further - specify the value(s) they support. - properties: $nodename: pattern: "^nand-controller(@.*)?" @@ -51,79 +41,8 @@ properties: patternProperties: "^nand@[a-f0-9]$": - $ref: nand-chip.yaml# - - properties: - reg: - description: - Contains the chip-select IDs. - - nand-ecc-placement: - description: - Location of the ECC bytes. This location is unknown by default - but can be explicitly set to "oob", if all ECC bytes are - known to be stored in the OOB area, or "interleaved" if ECC - bytes will be interleaved with regular data in the main area. - $ref: /schemas/types.yaml#/definitions/string - enum: [ oob, interleaved ] - - nand-bus-width: - description: - Bus width to the NAND chip - $ref: /schemas/types.yaml#/definitions/uint32 - enum: [8, 16] - default: 8 - - nand-on-flash-bbt: - description: - With this property, the OS will search the device for a Bad - Block Table (BBT). If not found, it will create one, reserve - a few blocks at the end of the device to store it and update - it as the device ages. Otherwise, the out-of-band area of a - few pages of all the blocks will be scanned at boot time to - find Bad Block Markers (BBM). These markers will help to - build a volatile BBT in RAM. - $ref: /schemas/types.yaml#/definitions/flag - - nand-ecc-maximize: - description: - Whether or not the ECC strength should be maximized. The - maximum ECC strength is both controller and chip - dependent. The ECC engine has to select the ECC config - providing the best strength and taking the OOB area size - constraint into account. This is particularly useful when - only the in-band area is used by the upper layers, and you - want to make your NAND as reliable as possible. - $ref: /schemas/types.yaml#/definitions/flag - - nand-is-boot-medium: - description: - Whether or not the NAND chip is a boot medium. Drivers might - use this information to select ECC algorithms supported by - the boot ROM or similar restrictions. - $ref: /schemas/types.yaml#/definitions/flag - - nand-rb: - description: - Contains the native Ready/Busy IDs. - $ref: /schemas/types.yaml#/definitions/uint32-array - - rb-gpios: - description: - Contains one or more GPIO descriptor (the numper of descriptor - depends on the number of R/B pins exposed by the flash) for the - Ready/Busy pins. Active state refers to the NAND ready state and - should be set to GPIOD_ACTIVE_HIGH unless the signal is inverted. - - wp-gpios: - description: - Contains one GPIO descriptor for the Write Protect pin. - Active state refers to the NAND Write Protect state and should be - set to GPIOD_ACTIVE_LOW unless the signal is inverted. - maxItems: 1 - - required: - - reg + type: object + $ref: raw-nand-chip.yaml# required: - "#address-cells" diff --git a/Documentation/devicetree/bindings/mtd/partitions/partition.yaml b/Documentation/devicetree/bindings/mtd/partitions/partition.yaml index cdffbb9cedc2..1ebe9e2347ea 100644 --- a/Documentation/devicetree/bindings/mtd/partitions/partition.yaml +++ b/Documentation/devicetree/bindings/mtd/partitions/partition.yaml @@ -55,6 +55,7 @@ properties: linux,rootfs: description: Marks partition that contains root filesystem to mount and boot user space from + type: boolean if: not: diff --git a/Documentation/devicetree/bindings/mtd/partitions/partitions.yaml b/Documentation/devicetree/bindings/mtd/partitions/partitions.yaml index 2edc65e0e361..1dda2c80747b 100644 --- a/Documentation/devicetree/bindings/mtd/partitions/partitions.yaml +++ b/Documentation/devicetree/bindings/mtd/partitions/partitions.yaml @@ -21,6 +21,7 @@ oneOf: - $ref: linksys,ns-partitions.yaml - $ref: qcom,smem-part.yaml - $ref: redboot-fis.yaml + - $ref: tplink,safeloader-partitions.yaml properties: compatible: true diff --git a/Documentation/devicetree/bindings/mtd/qcom,nandc.yaml b/Documentation/devicetree/bindings/mtd/qcom,nandc.yaml index 00c991ffa6c4..4ada60fbf81d 100644 --- a/Documentation/devicetree/bindings/mtd/qcom,nandc.yaml +++ b/Documentation/devicetree/bindings/mtd/qcom,nandc.yaml @@ -34,7 +34,9 @@ properties: patternProperties: "^nand@[a-f0-9]$": type: object + $ref: raw-nand-chip.yaml properties: + nand-bus-width: const: 8 @@ -45,6 +47,24 @@ patternProperties: enum: - 512 + qcom,boot-partitions: + $ref: /schemas/types.yaml#/definitions/uint32-matrix + items: + items: + - description: offset + - description: size + description: + Boot partition use a different layout where the 4 bytes of spare + data are not protected by ECC. Use this to declare these special + partitions by defining first the offset and then the size. + + It's in the form of <offset1 size1 offset2 size2 offset3 ...> + and should be declared in ascending order. + + Refer to the ipq8064 example on how to use this special binding. + + unevaluatedProperties: false + allOf: - $ref: nand-controller.yaml# @@ -107,22 +127,15 @@ allOf: - qcom,ipq806x-nand then: - properties: - qcom,boot-partitions: - $ref: /schemas/types.yaml#/definitions/uint32-matrix - items: - items: - - description: offset - - description: size - description: - Boot partition use a different layout where the 4 bytes of spare - data are not protected by ECC. Use this to declare these special - partitions by defining first the offset and then the size. - - It's in the form of <offset1 size1 offset2 size2 offset3 ...> - and should be declared in ascending order. - - Refer to the ipq8064 example on how to use this special binding. + patternProperties: + "^nand@[a-f0-9]$": + properties: + qcom,boot-partitions: true + else: + patternProperties: + "^nand@[a-f0-9]$": + properties: + qcom,boot-partitions: false required: - compatible diff --git a/Documentation/devicetree/bindings/mtd/raw-nand-chip.yaml b/Documentation/devicetree/bindings/mtd/raw-nand-chip.yaml new file mode 100644 index 000000000000..092448d7bfc5 --- /dev/null +++ b/Documentation/devicetree/bindings/mtd/raw-nand-chip.yaml @@ -0,0 +1,111 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/mtd/raw-nand-chip.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Raw NAND Chip Common Properties + +maintainers: + - Miquel Raynal <miquel.raynal@bootlin.com> + +allOf: + - $ref: nand-chip.yaml# + +description: | + The ECC strength and ECC step size properties define the user + desires in terms of correction capability of a controller. Together, + they request the ECC engine to correct {strength} bit errors per + {size} bytes for a particular raw NAND chip. + + The interpretation of these parameters is implementation-defined, so + not all implementations must support all possible + combinations. However, implementations are encouraged to further + specify the value(s) they support. + +properties: + $nodename: + pattern: "^nand@[a-f0-9]$" + + reg: + description: + Contains the chip-select IDs. + + nand-ecc-placement: + description: + Location of the ECC bytes. This location is unknown by default + but can be explicitly set to "oob", if all ECC bytes are + known to be stored in the OOB area, or "interleaved" if ECC + bytes will be interleaved with regular data in the main area. + $ref: /schemas/types.yaml#/definitions/string + enum: [ oob, interleaved ] + deprecated: true + + nand-ecc-mode: + description: + Legacy ECC configuration mixing the ECC engine choice and + configuration. + $ref: /schemas/types.yaml#/definitions/string + enum: [none, soft, soft_bch, hw, hw_syndrome, on-die] + deprecated: true + + nand-bus-width: + description: + Bus width to the NAND chip + $ref: /schemas/types.yaml#/definitions/uint32 + enum: [8, 16] + default: 8 + + nand-on-flash-bbt: + description: + With this property, the OS will search the device for a Bad + Block Table (BBT). If not found, it will create one, reserve + a few blocks at the end of the device to store it and update + it as the device ages. Otherwise, the out-of-band area of a + few pages of all the blocks will be scanned at boot time to + find Bad Block Markers (BBM). These markers will help to + build a volatile BBT in RAM. + $ref: /schemas/types.yaml#/definitions/flag + + nand-ecc-maximize: + description: + Whether or not the ECC strength should be maximized. The + maximum ECC strength is both controller and chip + dependent. The ECC engine has to select the ECC config + providing the best strength and taking the OOB area size + constraint into account. This is particularly useful when + only the in-band area is used by the upper layers, and you + want to make your NAND as reliable as possible. + $ref: /schemas/types.yaml#/definitions/flag + + nand-is-boot-medium: + description: + Whether or not the NAND chip is a boot medium. Drivers might + use this information to select ECC algorithms supported by + the boot ROM or similar restrictions. + $ref: /schemas/types.yaml#/definitions/flag + + nand-rb: + description: + Contains the native Ready/Busy IDs. + $ref: /schemas/types.yaml#/definitions/uint32-array + + rb-gpios: + description: + Contains one or more GPIO descriptor (the numper of descriptor + depends on the number of R/B pins exposed by the flash) for the + Ready/Busy pins. Active state refers to the NAND ready state and + should be set to GPIOD_ACTIVE_HIGH unless the signal is inverted. + + wp-gpios: + description: + Contains one GPIO descriptor for the Write Protect pin. + Active state refers to the NAND Write Protect state and should be + set to GPIOD_ACTIVE_LOW unless the signal is inverted. + maxItems: 1 + +required: + - reg + +# This is a generic file other binding inherit from and extend +additionalProperties: true diff --git a/Documentation/devicetree/bindings/mtd/rockchip,nand-controller.yaml b/Documentation/devicetree/bindings/mtd/rockchip,nand-controller.yaml index 7eb1d0a38565..ee53715ffdca 100644 --- a/Documentation/devicetree/bindings/mtd/rockchip,nand-controller.yaml +++ b/Documentation/devicetree/bindings/mtd/rockchip,nand-controller.yaml @@ -57,6 +57,7 @@ properties: patternProperties: "^nand@[0-7]$": type: object + $ref: raw-nand-chip.yaml properties: reg: minimum: 0 @@ -116,6 +117,8 @@ patternProperties: Only used in combination with 'nand-is-boot-medium'. + unevaluatedProperties: false + required: - compatible - reg diff --git a/Documentation/devicetree/bindings/mtd/st,stm32-fmc2-nand.yaml b/Documentation/devicetree/bindings/mtd/st,stm32-fmc2-nand.yaml index 986e85ccebc7..e72cb5bacaf0 100644 --- a/Documentation/devicetree/bindings/mtd/st,stm32-fmc2-nand.yaml +++ b/Documentation/devicetree/bindings/mtd/st,stm32-fmc2-nand.yaml @@ -37,6 +37,7 @@ properties: patternProperties: "^nand@[a-f0-9]$": type: object + $ref: raw-nand-chip.yaml properties: nand-ecc-step-size: const: 512 @@ -44,6 +45,8 @@ patternProperties: nand-ecc-strength: enum: [1, 4, 8] + unevaluatedProperties: false + allOf: - $ref: nand-controller.yaml# diff --git a/Documentation/devicetree/bindings/mtd/ti,am654-hbmc.yaml b/Documentation/devicetree/bindings/mtd/ti,am654-hbmc.yaml index 4774c92e7fc4..df4fdc02456d 100644 --- a/Documentation/devicetree/bindings/mtd/ti,am654-hbmc.yaml +++ b/Documentation/devicetree/bindings/mtd/ti,am654-hbmc.yaml @@ -30,6 +30,8 @@ properties: patternProperties: "^flash@[0-1],[0-9a-f]+$": type: object + $ref: mtd-physmap.yaml + unevaluatedProperties: false required: - compatible diff --git a/Documentation/devicetree/bindings/perf/fsl-imx-ddr.yaml b/Documentation/devicetree/bindings/perf/fsl-imx-ddr.yaml index 80a92385367e..e9fad4b3de68 100644 --- a/Documentation/devicetree/bindings/perf/fsl-imx-ddr.yaml +++ b/Documentation/devicetree/bindings/perf/fsl-imx-ddr.yaml @@ -4,7 +4,7 @@ $id: http://devicetree.org/schemas/perf/fsl-imx-ddr.yaml# $schema: http://devicetree.org/meta-schemas/core.yaml# -title: Freescale(NXP) IMX8 DDR performance monitor +title: Freescale(NXP) IMX8/9 DDR performance monitor maintainers: - Frank Li <frank.li@nxp.com> @@ -19,6 +19,7 @@ properties: - fsl,imx8mm-ddr-pmu - fsl,imx8mn-ddr-pmu - fsl,imx8mp-ddr-pmu + - fsl,imx93-ddr-pmu - items: - enum: - fsl,imx8mm-ddr-pmu diff --git a/Documentation/devicetree/bindings/regulator/mt6358-regulator.txt b/Documentation/devicetree/bindings/regulator/mt6358-regulator.txt index 7034cdca54e0..b6384306db5c 100644 --- a/Documentation/devicetree/bindings/regulator/mt6358-regulator.txt +++ b/Documentation/devicetree/bindings/regulator/mt6358-regulator.txt @@ -8,15 +8,14 @@ Documentation/devicetree/bindings/regulator/regulator.txt. The valid names for regulators are:: BUCK: - buck_vdram1, buck_vcore, buck_vcore_sshub, buck_vpa, buck_vproc11, - buck_vproc12, buck_vgpu, buck_vs2, buck_vmodem, buck_vs1 + buck_vdram1, buck_vcore, buck_vpa, buck_vproc11, buck_vproc12, buck_vgpu, + buck_vs2, buck_vmodem, buck_vs1 LDO: ldo_vdram2, ldo_vsim1, ldo_vibr, ldo_vrf12, ldo_vio18, ldo_vusb, ldo_vcamio, ldo_vcamd, ldo_vcn18, ldo_vfe28, ldo_vsram_proc11, ldo_vcn28, ldo_vsram_others, - ldo_vsram_others_sshub, ldo_vsram_gpu, ldo_vxo22, ldo_vefuse, ldo_vaux18, - ldo_vmch, ldo_vbif28, ldo_vsram_proc12, ldo_vcama1, ldo_vemc, ldo_vio28, ldo_va12, - ldo_vrf18, ldo_vcn33_bt, ldo_vcn33_wifi, ldo_vcama2, ldo_vmc, ldo_vldo28, ldo_vaud28, - ldo_vsim2 + ldo_vsram_gpu, ldo_vxo22, ldo_vefuse, ldo_vaux18, ldo_vmch, ldo_vbif28, + ldo_vsram_proc12, ldo_vcama1, ldo_vemc, ldo_vio28, ldo_va12, ldo_vrf18, + ldo_vcn33, ldo_vcama2, ldo_vmc, ldo_vldo28, ldo_vaud28, ldo_vsim2 Example: @@ -305,15 +304,8 @@ Example: regulator-enable-ramp-delay = <120>; }; - mt6358_vcn33_bt_reg: ldo_vcn33_bt { - regulator-name = "vcn33_bt"; - regulator-min-microvolt = <3300000>; - regulator-max-microvolt = <3500000>; - regulator-enable-ramp-delay = <270>; - }; - - mt6358_vcn33_wifi_reg: ldo_vcn33_wifi { - regulator-name = "vcn33_wifi"; + mt6358_vcn33_reg: ldo_vcn33 { + regulator-name = "vcn33"; regulator-min-microvolt = <3300000>; regulator-max-microvolt = <3500000>; regulator-enable-ramp-delay = <270>; @@ -354,17 +346,5 @@ Example: regulator-max-microvolt = <3100000>; regulator-enable-ramp-delay = <540>; }; - - mt6358_vcore_sshub_reg: buck_vcore_sshub { - regulator-name = "vcore_sshub"; - regulator-min-microvolt = <500000>; - regulator-max-microvolt = <1293750>; - }; - - mt6358_vsram_others_sshub_reg: ldo_vsram_others_sshub { - regulator-name = "vsram_others_sshub"; - regulator-min-microvolt = <500000>; - regulator-max-microvolt = <1293750>; - }; }; }; diff --git a/Documentation/devicetree/bindings/regulator/pfuze100.yaml b/Documentation/devicetree/bindings/regulator/pfuze100.yaml index 67a30b23b92c..e384e4953f0a 100644 --- a/Documentation/devicetree/bindings/regulator/pfuze100.yaml +++ b/Documentation/devicetree/bindings/regulator/pfuze100.yaml @@ -36,6 +36,9 @@ properties: reg: maxItems: 1 + interrupts: + maxItems: 1 + fsl,pfuze-support-disable-sw: $ref: /schemas/types.yaml#/definitions/flag description: | diff --git a/Documentation/devicetree/bindings/regulator/pwm-regulator.yaml b/Documentation/devicetree/bindings/regulator/pwm-regulator.yaml index 7e58471097f8..80ecf938b749 100644 --- a/Documentation/devicetree/bindings/regulator/pwm-regulator.yaml +++ b/Documentation/devicetree/bindings/regulator/pwm-regulator.yaml @@ -64,6 +64,7 @@ properties: defined, <100> is assumed, meaning that pwm-dutycycle-range contains values expressed in percent. + $ref: /schemas/types.yaml#/definitions/uint32 default: 100 pwm-dutycycle-range: diff --git a/Documentation/devicetree/bindings/regulator/renesas,raa215300.yaml b/Documentation/devicetree/bindings/regulator/renesas,raa215300.yaml new file mode 100644 index 000000000000..97cff71d2967 --- /dev/null +++ b/Documentation/devicetree/bindings/regulator/renesas,raa215300.yaml @@ -0,0 +1,85 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/regulator/renesas,raa215300.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Renesas RAA215300 Power Management Integrated Circuit (PMIC) + +maintainers: + - Biju Das <biju.das.jz@bp.renesas.com> + +description: | + The RAA215300 is a high-performance, low-cost 9-channel PMIC designed for + 32-bit and 64-bit MCU and MPU applications. It supports DDR3, DDR3L, DDR4, + and LPDDR4 memory power requirements. The internally compensated regulators, + built-in Real-Time Clock (RTC), 32kHz crystal oscillator, and coin cell + battery charger provide a highly integrated, small footprint power solution + ideal for System-On-Module (SOM) applications. A spread spectrum feature + provides an ease-of-use solution for noise-sensitive audio or RF applications. + + This device exposes two devices via I2C. One for the integrated RTC IP, and + one for everything else. + + Link to datasheet: + https://www.renesas.com/in/en/products/power-power-management/multi-channel-power-management-ics-pmics/ssdsoc-power-management-ics-pmic-and-pmus/raa215300-high-performance-9-channel-pmic-supporting-ddr-memory-built-charger-and-rtc + +properties: + compatible: + enum: + - renesas,raa215300 + + reg: + maxItems: 2 + + reg-names: + items: + - const: main + - const: rtc + + interrupts: + maxItems: 1 + + clocks: + description: | + The clocks are optional. The RTC is disabled, if no clocks are + provided(either xin or clkin). + maxItems: 1 + + clock-names: + description: | + Use xin, if connected to an external crystal. + Use clkin, if connected to an external clock signal. + enum: + - xin + - clkin + +required: + - compatible + - reg + - reg-names + +additionalProperties: false + +examples: + - | + /* 32.768kHz crystal */ + x2: x2-clock { + compatible = "fixed-clock"; + #clock-cells = <0>; + clock-frequency = <32768>; + }; + + i2c { + #address-cells = <1>; + #size-cells = <0>; + + raa215300: pmic@12 { + compatible = "renesas,raa215300"; + reg = <0x12>, <0x6f>; + reg-names = "main", "rtc"; + + clocks = <&x2>; + clock-names = "xin"; + }; + }; diff --git a/Documentation/devicetree/bindings/regulator/ti,tps62870.yaml b/Documentation/devicetree/bindings/regulator/ti,tps62870.yaml new file mode 100644 index 000000000000..386989544dac --- /dev/null +++ b/Documentation/devicetree/bindings/regulator/ti,tps62870.yaml @@ -0,0 +1,52 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/regulator/ti,tps62870.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: TI TPS62870/TPS62871/TPS62872/TPS62873 voltage regulator + +maintainers: + - Mårten Lindahl <marten.lindahl@axis.com> + +allOf: + - $ref: regulator.yaml# + +properties: + compatible: + enum: + - ti,tps62870 + - ti,tps62871 + - ti,tps62872 + - ti,tps62873 + + reg: + maxItems: 1 + + regulator-initial-mode: + enum: [ 1, 2 ] + description: 1 - Forced PWM mode, 2 - Low power mode + +required: + - compatible + - reg + +unevaluatedProperties: false + +examples: + - | + i2c { + #address-cells = <1>; + #size-cells = <0>; + + regulator@41 { + compatible = "ti,tps62873"; + reg = <0x41>; + regulator-name = "+0.75V"; + regulator-min-microvolt = <400000>; + regulator-max-microvolt = <1675000>; + regulator-initial-mode = <1>; + }; + }; + +... diff --git a/Documentation/devicetree/bindings/spi/allwinner,sun4i-a10-spi.yaml b/Documentation/devicetree/bindings/spi/allwinner,sun4i-a10-spi.yaml index 2155478bfc4d..a6f34bdd1d3c 100644 --- a/Documentation/devicetree/bindings/spi/allwinner,sun4i-a10-spi.yaml +++ b/Documentation/devicetree/bindings/spi/allwinner,sun4i-a10-spi.yaml @@ -14,9 +14,6 @@ maintainers: - Maxime Ripard <mripard@kernel.org> properties: - "#address-cells": true - "#size-cells": true - compatible: const: allwinner,sun4i-a10-spi @@ -46,12 +43,9 @@ properties: - const: rx - const: tx - num-cs: true - patternProperties: "^.*@[0-9a-f]+": type: object - additionalProperties: true properties: reg: items: @@ -71,7 +65,7 @@ required: - clocks - clock-names -additionalProperties: false +unevaluatedProperties: false examples: - | diff --git a/Documentation/devicetree/bindings/spi/allwinner,sun6i-a31-spi.yaml b/Documentation/devicetree/bindings/spi/allwinner,sun6i-a31-spi.yaml index de36c6a34a0f..28b8ace63044 100644 --- a/Documentation/devicetree/bindings/spi/allwinner,sun6i-a31-spi.yaml +++ b/Documentation/devicetree/bindings/spi/allwinner,sun6i-a31-spi.yaml @@ -14,11 +14,9 @@ maintainers: - Maxime Ripard <mripard@kernel.org> properties: - "#address-cells": true - "#size-cells": true - compatible: oneOf: + - const: allwinner,sun50i-r329-spi - const: allwinner,sun6i-a31-spi - const: allwinner,sun8i-h3-spi - items: @@ -28,6 +26,15 @@ properties: - allwinner,sun50i-h616-spi - allwinner,suniv-f1c100s-spi - const: allwinner,sun8i-h3-spi + - items: + - enum: + - allwinner,sun20i-d1-spi + - allwinner,sun50i-r329-spi-dbi + - const: allwinner,sun50i-r329-spi + - items: + - const: allwinner,sun20i-d1-spi-dbi + - const: allwinner,sun50i-r329-spi-dbi + - const: allwinner,sun50i-r329-spi reg: maxItems: 1 @@ -58,12 +65,9 @@ properties: - const: rx - const: tx - num-cs: true - patternProperties: "^.*@[0-9a-f]+": type: object - additionalProperties: true properties: reg: items: @@ -83,7 +87,7 @@ required: - clocks - clock-names -additionalProperties: false +unevaluatedProperties: false examples: - | diff --git a/Documentation/devicetree/bindings/spi/atmel,at91rm9200-spi.yaml b/Documentation/devicetree/bindings/spi/atmel,at91rm9200-spi.yaml index 6c57dd6c3a36..58367587bfbc 100644 --- a/Documentation/devicetree/bindings/spi/atmel,at91rm9200-spi.yaml +++ b/Documentation/devicetree/bindings/spi/atmel,at91rm9200-spi.yaml @@ -20,6 +20,10 @@ properties: - items: - const: microchip,sam9x60-spi - const: atmel,at91rm9200-spi + - items: + - const: microchip,sam9x7-spi + - const: microchip,sam9x60-spi + - const: atmel,at91rm9200-spi reg: maxItems: 1 diff --git a/Documentation/devicetree/bindings/spi/cdns,qspi-nor.yaml b/Documentation/devicetree/bindings/spi/cdns,qspi-nor.yaml index b310069762dd..4f15f9a0cc34 100644 --- a/Documentation/devicetree/bindings/spi/cdns,qspi-nor.yaml +++ b/Documentation/devicetree/bindings/spi/cdns,qspi-nor.yaml @@ -46,12 +46,28 @@ allOf: maxItems: 2 items: enum: [ qspi, qspi-ocp ] + - if: + properties: + compatible: + contains: + const: amd,pensando-elba-qspi + then: + properties: + cdns,fifo-depth: + enum: [ 128, 256, 1024 ] + default: 1024 + else: + properties: + cdns,fifo-depth: + enum: [ 128, 256 ] + default: 128 properties: compatible: oneOf: - items: - enum: + - amd,pensando-elba-qspi - ti,k2g-qspi - ti,am654-ospi - intel,lgm-qspi @@ -76,8 +92,6 @@ properties: description: Size of the data FIFO in words. $ref: /schemas/types.yaml#/definitions/uint32 - enum: [ 128, 256 ] - default: 128 cdns,fifo-width: $ref: /schemas/types.yaml#/definitions/uint32 diff --git a/Documentation/devicetree/bindings/spi/qcom,spi-qcom-qspi.yaml b/Documentation/devicetree/bindings/spi/qcom,spi-qcom-qspi.yaml index ee8f7ea907b0..1696ac46a660 100644 --- a/Documentation/devicetree/bindings/spi/qcom,spi-qcom-qspi.yaml +++ b/Documentation/devicetree/bindings/spi/qcom,spi-qcom-qspi.yaml @@ -29,6 +29,9 @@ properties: reg: maxItems: 1 + iommus: + maxItems: 1 + interrupts: maxItems: 1 diff --git a/Documentation/devicetree/bindings/spi/renesas,rzv2m-csi.yaml b/Documentation/devicetree/bindings/spi/renesas,rzv2m-csi.yaml new file mode 100644 index 000000000000..e59183e53690 --- /dev/null +++ b/Documentation/devicetree/bindings/spi/renesas,rzv2m-csi.yaml @@ -0,0 +1,70 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/spi/renesas,rzv2m-csi.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Renesas RZ/V2M Clocked Serial Interface (CSI) + +maintainers: + - Fabrizio Castro <fabrizio.castro.jz@renesas.com> + - Geert Uytterhoeven <geert+renesas@glider.be> + +allOf: + - $ref: spi-controller.yaml# + +properties: + compatible: + const: renesas,rzv2m-csi + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + clocks: + items: + - description: The clock used to generate the output clock (CSICLK) + - description: Internal clock to access the registers (PCLK) + + clock-names: + items: + - const: csiclk + - const: pclk + + resets: + maxItems: 1 + + power-domains: + maxItems: 1 + +required: + - compatible + - reg + - interrupts + - clocks + - clock-names + - resets + - power-domains + - '#address-cells' + - '#size-cells' + +unevaluatedProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/arm-gic.h> + #include <dt-bindings/clock/r9a09g011-cpg.h> + csi4: spi@a4020200 { + compatible = "renesas,rzv2m-csi"; + reg = <0xa4020200 0x80>; + interrupts = <GIC_SPI 230 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&cpg CPG_MOD R9A09G011_CSI4_CLK>, + <&cpg CPG_MOD R9A09G011_CPERI_GRPH_PCLK>; + clock-names = "csiclk", "pclk"; + resets = <&cpg R9A09G011_CSI_GPH_PRESETN>; + power-domains = <&cpg>; + #address-cells = <1>; + #size-cells = <0>; + }; diff --git a/Documentation/devicetree/bindings/spi/samsung,spi.yaml b/Documentation/devicetree/bindings/spi/samsung,spi.yaml index e0a465d70b0a..79da99ca0e53 100644 --- a/Documentation/devicetree/bindings/spi/samsung,spi.yaml +++ b/Documentation/devicetree/bindings/spi/samsung,spi.yaml @@ -35,8 +35,6 @@ properties: minItems: 2 maxItems: 3 - cs-gpios: true - dmas: minItems: 2 maxItems: 2 diff --git a/Documentation/devicetree/bindings/spi/snps,dw-apb-ssi.yaml b/Documentation/devicetree/bindings/spi/snps,dw-apb-ssi.yaml index 12ca108864c6..a47cb144b09f 100644 --- a/Documentation/devicetree/bindings/spi/snps,dw-apb-ssi.yaml +++ b/Documentation/devicetree/bindings/spi/snps,dw-apb-ssi.yaml @@ -74,6 +74,8 @@ properties: const: intel,keembay-ssi - description: Intel Thunder Bay SPI Controller const: intel,thunderbay-ssi + - description: Intel Mount Evans Integrated Management Complex SPI Controller + const: intel,mountevans-imc-ssi - description: AMD Pensando Elba SoC SPI Controller const: amd,pensando-elba-spi - description: Baikal-T1 SPI Controller diff --git a/Documentation/devicetree/bindings/spi/socionext,uniphier-spi.yaml b/Documentation/devicetree/bindings/spi/socionext,uniphier-spi.yaml index 597fc4e6b01c..c96131ebbea1 100644 --- a/Documentation/devicetree/bindings/spi/socionext,uniphier-spi.yaml +++ b/Documentation/devicetree/bindings/spi/socionext,uniphier-spi.yaml @@ -17,9 +17,6 @@ allOf: - $ref: spi-controller.yaml# properties: - "#address-cells": true - "#size-cells": true - compatible: const: socionext,uniphier-scssi diff --git a/Documentation/devicetree/bindings/spi/spi-controller.yaml b/Documentation/devicetree/bindings/spi/spi-controller.yaml index 90945f59b7e8..524f6fe8c27b 100644 --- a/Documentation/devicetree/bindings/spi/spi-controller.yaml +++ b/Documentation/devicetree/bindings/spi/spi-controller.yaml @@ -17,7 +17,7 @@ description: | properties: $nodename: - pattern: "^spi(@.*|-[0-9a-f])*$" + pattern: "^spi(@.*|-([0-9]|[1-9][0-9]+))?$" "#address-cells": enum: [0, 1] diff --git a/Documentation/devicetree/bindings/spi/spi-zynqmp-qspi.yaml b/Documentation/devicetree/bindings/spi/spi-zynqmp-qspi.yaml index 20f77246d365..226d8b493b57 100644 --- a/Documentation/devicetree/bindings/spi/spi-zynqmp-qspi.yaml +++ b/Documentation/devicetree/bindings/spi/spi-zynqmp-qspi.yaml @@ -32,6 +32,12 @@ properties: clocks: maxItems: 2 + iommus: + maxItems: 1 + + power-domains: + maxItems: 1 + required: - compatible - reg diff --git a/Documentation/devicetree/bindings/thermal/armada-thermal.txt b/Documentation/devicetree/bindings/thermal/armada-thermal.txt index b0bee7e42038..ab8b8fccc7af 100644 --- a/Documentation/devicetree/bindings/thermal/armada-thermal.txt +++ b/Documentation/devicetree/bindings/thermal/armada-thermal.txt @@ -8,6 +8,7 @@ Required properties: * marvell,armada380-thermal * marvell,armadaxp-thermal * marvell,armada-ap806-thermal + * marvell,armada-ap807-thermal * marvell,armada-cp110-thermal Note: these bindings are deprecated for AP806/CP110 and should instead diff --git a/Documentation/devicetree/bindings/thermal/brcm,bcm2835-thermal.txt b/Documentation/devicetree/bindings/thermal/brcm,bcm2835-thermal.txt deleted file mode 100644 index a3e9ec5dc7ac..000000000000 --- a/Documentation/devicetree/bindings/thermal/brcm,bcm2835-thermal.txt +++ /dev/null @@ -1,41 +0,0 @@ -Binding for Thermal Sensor driver for BCM2835 SoCs. - -Required parameters: -------------------- - -compatible: should be one of: "brcm,bcm2835-thermal", - "brcm,bcm2836-thermal" or "brcm,bcm2837-thermal" -reg: Address range of the thermal registers. -clocks: Phandle of the clock used by the thermal sensor. -#thermal-sensor-cells: should be 0 (see Documentation/devicetree/bindings/thermal/thermal-sensor.yaml) - -Example: - -thermal-zones { - cpu_thermal: cpu-thermal { - polling-delay-passive = <0>; - polling-delay = <1000>; - - thermal-sensors = <&thermal>; - - trips { - cpu-crit { - temperature = <80000>; - hysteresis = <0>; - type = "critical"; - }; - }; - - coefficients = <(-538) 407000>; - - cooling-maps { - }; - }; -}; - -thermal: thermal@7e212000 { - compatible = "brcm,bcm2835-thermal"; - reg = <0x7e212000 0x8>; - clocks = <&clocks BCM2835_CLOCK_TSENS>; - #thermal-sensor-cells = <0>; -}; diff --git a/Documentation/devicetree/bindings/thermal/brcm,bcm2835-thermal.yaml b/Documentation/devicetree/bindings/thermal/brcm,bcm2835-thermal.yaml new file mode 100644 index 000000000000..2b6026d9fbcf --- /dev/null +++ b/Documentation/devicetree/bindings/thermal/brcm,bcm2835-thermal.yaml @@ -0,0 +1,48 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/thermal/brcm,bcm2835-thermal.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Broadcom BCM2835 thermal sensor + +maintainers: + - Stefan Wahren <stefan.wahren@i2se.com> + +allOf: + - $ref: thermal-sensor.yaml# + +properties: + compatible: + enum: + - brcm,bcm2835-thermal + - brcm,bcm2836-thermal + - brcm,bcm2837-thermal + + reg: + maxItems: 1 + + clocks: + maxItems: 1 + + "#thermal-sensor-cells": + const: 0 + +unevaluatedProperties: false + +required: + - compatible + - reg + - clocks + - '#thermal-sensor-cells' + +examples: + - | + #include <dt-bindings/clock/bcm2835.h> + + thermal@7e212000 { + compatible = "brcm,bcm2835-thermal"; + reg = <0x7e212000 0x8>; + clocks = <&clocks BCM2835_CLOCK_TSENS>; + #thermal-sensor-cells = <0>; + }; diff --git a/Documentation/devicetree/bindings/thermal/qcom-tsens.yaml b/Documentation/devicetree/bindings/thermal/qcom-tsens.yaml index d1ec963a6834..27e9e16e6455 100644 --- a/Documentation/devicetree/bindings/thermal/qcom-tsens.yaml +++ b/Documentation/devicetree/bindings/thermal/qcom-tsens.yaml @@ -29,6 +29,8 @@ properties: items: - enum: - qcom,mdm9607-tsens + - qcom,msm8226-tsens + - qcom,msm8909-tsens - qcom,msm8916-tsens - qcom,msm8939-tsens - qcom,msm8974-tsens @@ -48,6 +50,7 @@ properties: - qcom,msm8953-tsens - qcom,msm8996-tsens - qcom,msm8998-tsens + - qcom,qcm2290-tsens - qcom,sc7180-tsens - qcom,sc7280-tsens - qcom,sc8180x-tsens @@ -56,6 +59,7 @@ properties: - qcom,sdm845-tsens - qcom,sm6115-tsens - qcom,sm6350-tsens + - qcom,sm6375-tsens - qcom,sm8150-tsens - qcom,sm8250-tsens - qcom,sm8350-tsens @@ -67,6 +71,12 @@ properties: enum: - qcom,ipq8074-tsens + - description: v2 of TSENS with combined interrupt + items: + - enum: + - qcom,ipq9574-tsens + - const: qcom,ipq8074-tsens + reg: items: - description: TM registers @@ -223,12 +233,7 @@ allOf: contains: enum: - qcom,ipq8064-tsens - - qcom,mdm9607-tsens - - qcom,msm8916-tsens - qcom,msm8960-tsens - - qcom,msm8974-tsens - - qcom,msm8976-tsens - - qcom,qcs404-tsens - qcom,tsens-v0_1 - qcom,tsens-v1 then: @@ -244,22 +249,7 @@ allOf: properties: compatible: contains: - enum: - - qcom,msm8953-tsens - - qcom,msm8996-tsens - - qcom,msm8998-tsens - - qcom,sc7180-tsens - - qcom,sc7280-tsens - - qcom,sc8180x-tsens - - qcom,sc8280xp-tsens - - qcom,sdm630-tsens - - qcom,sdm845-tsens - - qcom,sm6350-tsens - - qcom,sm8150-tsens - - qcom,sm8250-tsens - - qcom,sm8350-tsens - - qcom,sm8450-tsens - - qcom,tsens-v2 + const: qcom,tsens-v2 then: properties: interrupts: diff --git a/Documentation/devicetree/bindings/timer/brcm,kona-timer.txt b/Documentation/devicetree/bindings/timer/brcm,kona-timer.txt deleted file mode 100644 index 39adf54b4388..000000000000 --- a/Documentation/devicetree/bindings/timer/brcm,kona-timer.txt +++ /dev/null @@ -1,25 +0,0 @@ -Broadcom Kona Family timer ------------------------------------------------------ -This timer is used in the following Broadcom SoCs: - BCM11130, BCM11140, BCM11351, BCM28145, BCM28155 - -Required properties: -- compatible : "brcm,kona-timer" -- DEPRECATED: compatible : "bcm,kona-timer" -- reg : Register range for the timer -- interrupts : interrupt for the timer -- clocks: phandle + clock specifier pair of the external clock -- clock-frequency: frequency that the clock operates - -Only one of clocks or clock-frequency should be specified. - -Refer to clocks/clock-bindings.txt for generic clock consumer properties. - -Example: - timer@35006000 { - compatible = "brcm,kona-timer"; - reg = <0x35006000 0x1000>; - interrupts = <0x0 7 0x4>; - clocks = <&hub_timer_clk>; - }; - diff --git a/Documentation/devicetree/bindings/timer/brcm,kona-timer.yaml b/Documentation/devicetree/bindings/timer/brcm,kona-timer.yaml new file mode 100644 index 000000000000..d6af8383d6fc --- /dev/null +++ b/Documentation/devicetree/bindings/timer/brcm,kona-timer.yaml @@ -0,0 +1,52 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/timer/brcm,kona-timer.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Broadcom Kona family timer + +maintainers: + - Florian Fainelli <f.fainelli@gmail.com> + +properties: + compatible: + const: brcm,kona-timer + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + clocks: + maxItems: 1 + + clock-frequency: true + +oneOf: + - required: + - clocks + - required: + - clock-frequency + +required: + - compatible + - reg + - interrupts + +additionalProperties: false + +examples: + - | + #include <dt-bindings/clock/bcm281xx.h> + #include <dt-bindings/interrupt-controller/arm-gic.h> + #include <dt-bindings/interrupt-controller/irq.h> + + timer@35006000 { + compatible = "brcm,kona-timer"; + reg = <0x35006000 0x1000>; + interrupts = <GIC_SPI 7 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&aon_ccu BCM281XX_AON_CCU_HUB_TIMER>; + }; +... diff --git a/Documentation/devicetree/bindings/timer/loongson,ls1x-pwmtimer.yaml b/Documentation/devicetree/bindings/timer/loongson,ls1x-pwmtimer.yaml new file mode 100644 index 000000000000..ad61ae55850b --- /dev/null +++ b/Documentation/devicetree/bindings/timer/loongson,ls1x-pwmtimer.yaml @@ -0,0 +1,48 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/timer/loongson,ls1x-pwmtimer.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Loongson-1 PWM timer + +maintainers: + - Keguang Zhang <keguang.zhang@gmail.com> + +description: + Loongson-1 PWM timer can be used for system clock source + and clock event timers. + +properties: + compatible: + const: loongson,ls1b-pwmtimer + + reg: + maxItems: 1 + + clocks: + maxItems: 1 + + interrupts: + maxItems: 1 + +required: + - compatible + - reg + - clocks + - interrupts + +additionalProperties: false + +examples: + - | + #include <dt-bindings/clock/loongson,ls1x-clk.h> + #include <dt-bindings/interrupt-controller/irq.h> + clocksource: timer@1fe5c030 { + compatible = "loongson,ls1b-pwmtimer"; + reg = <0x1fe5c030 0x10>; + + clocks = <&clkc LS1X_CLKID_APB>; + interrupt-parent = <&intc0>; + interrupts = <20 IRQ_TYPE_LEVEL_HIGH>; + }; diff --git a/Documentation/devicetree/bindings/timer/ralink,rt2880-timer.yaml b/Documentation/devicetree/bindings/timer/ralink,rt2880-timer.yaml new file mode 100644 index 000000000000..daa7832babe3 --- /dev/null +++ b/Documentation/devicetree/bindings/timer/ralink,rt2880-timer.yaml @@ -0,0 +1,44 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/timer/ralink,rt2880-timer.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Timer present in Ralink family SoCs + +maintainers: + - Sergio Paracuellos <sergio.paracuellos@gmail.com> + +properties: + compatible: + const: ralink,rt2880-timer + + reg: + maxItems: 1 + + clocks: + maxItems: 1 + + interrupts: + maxItems: 1 + +required: + - compatible + - reg + - clocks + - interrupts + +additionalProperties: false + +examples: + - | + timer@100 { + compatible = "ralink,rt2880-timer"; + reg = <0x100 0x20>; + + clocks = <&sysc 3>; + + interrupt-parent = <&intc>; + interrupts = <1>; + }; +... diff --git a/Documentation/doc-guide/sphinx.rst b/Documentation/doc-guide/sphinx.rst index 23edb427e76f..cd8ad7904491 100644 --- a/Documentation/doc-guide/sphinx.rst +++ b/Documentation/doc-guide/sphinx.rst @@ -313,9 +313,18 @@ the documentation build system will automatically turn a reference to function name exists. If you see ``c:func:`` use in a kernel document, please feel free to remove it. +Tables +------ + +ReStructuredText provides several options for table syntax. Kernel style for +tables is to prefer *simple table* syntax or *grid table* syntax. See the +`reStructuredText user reference for table syntax`_ for more details. + +.. _reStructuredText user reference for table syntax: + https://docutils.sourceforge.io/docs/user/rst/quickref.html#tables list tables ------------ +~~~~~~~~~~~ The list-table formats can be useful for tables that are not easily laid out in the usual Sphinx ASCII-art formats. These formats are nearly diff --git a/Documentation/driver-api/basics.rst b/Documentation/driver-api/basics.rst index 4b4d8e28d3be..7671b531ba1a 100644 --- a/Documentation/driver-api/basics.rst +++ b/Documentation/driver-api/basics.rst @@ -84,7 +84,13 @@ Reference counting Atomics ------- -.. kernel-doc:: arch/x86/include/asm/atomic.h +.. kernel-doc:: include/linux/atomic/atomic-instrumented.h + :internal: + +.. kernel-doc:: include/linux/atomic/atomic-arch-fallback.h + :internal: + +.. kernel-doc:: include/linux/atomic/atomic-long.h :internal: Kernel objects manipulation diff --git a/Documentation/driver-api/edac.rst b/Documentation/driver-api/edac.rst index b8c742aa0a71..f4f044b95c4f 100644 --- a/Documentation/driver-api/edac.rst +++ b/Documentation/driver-api/edac.rst @@ -106,6 +106,16 @@ will occupy those chip-select rows. This term is avoided because it is unclear when needing to distinguish between chip-select rows and socket sets. +* High Bandwidth Memory (HBM) + +HBM is a new memory type with low power consumption and ultra-wide +communication lanes. It uses vertically stacked memory chips (DRAM dies) +interconnected by microscopic wires called "through-silicon vias," or +TSVs. + +Several stacks of HBM chips connect to the CPU or GPU through an ultra-fast +interconnect called the "interposer". Therefore, HBM's characteristics +are nearly indistinguishable from on-chip integrated RAM. Memory Controllers ------------------ @@ -176,3 +186,113 @@ nodes:: the L1 and L2 directories would be "edac_device_block's" .. kernel-doc:: drivers/edac/edac_device.h + + +Heterogeneous system support +---------------------------- + +An AMD heterogeneous system is built by connecting the data fabrics of +both CPUs and GPUs via custom xGMI links. Thus, the data fabric on the +GPU nodes can be accessed the same way as the data fabric on CPU nodes. + +The MI200 accelerators are data center GPUs. They have 2 data fabrics, +and each GPU data fabric contains four Unified Memory Controllers (UMC). +Each UMC contains eight channels. Each UMC channel controls one 128-bit +HBM2e (2GB) channel (equivalent to 8 X 2GB ranks). This creates a total +of 4096-bits of DRAM data bus. + +While the UMC is interfacing a 16GB (8high X 2GB DRAM) HBM stack, each UMC +channel is interfacing 2GB of DRAM (represented as rank). + +Memory controllers on AMD GPU nodes can be represented in EDAC thusly: + + GPU DF / GPU Node -> EDAC MC + GPU UMC -> EDAC CSROW + GPU UMC channel -> EDAC CHANNEL + +For example: a heterogeneous system with 1 AMD CPU is connected to +4 MI200 (Aldebaran) GPUs using xGMI. + +Some more heterogeneous hardware details: + +- The CPU UMC (Unified Memory Controller) is mostly the same as the GPU UMC. + They have chip selects (csrows) and channels. However, the layouts are different + for performance, physical layout, or other reasons. +- CPU UMCs use 1 channel, In this case UMC = EDAC channel. This follows the + marketing speak. CPU has X memory channels, etc. +- CPU UMCs use up to 4 chip selects, So UMC chip select = EDAC CSROW. +- GPU UMCs use 1 chip select, So UMC = EDAC CSROW. +- GPU UMCs use 8 channels, So UMC channel = EDAC channel. + +The EDAC subsystem provides a mechanism to handle AMD heterogeneous +systems by calling system specific ops for both CPUs and GPUs. + +AMD GPU nodes are enumerated in sequential order based on the PCI +hierarchy, and the first GPU node is assumed to have a Node ID value +following those of the CPU nodes after latter are fully populated:: + + $ ls /sys/devices/system/edac/mc/ + mc0 - CPU MC node 0 + mc1 | + mc2 |- GPU card[0] => node 0(mc1), node 1(mc2) + mc3 | + mc4 |- GPU card[1] => node 0(mc3), node 1(mc4) + mc5 | + mc6 |- GPU card[2] => node 0(mc5), node 1(mc6) + mc7 | + mc8 |- GPU card[3] => node 0(mc7), node 1(mc8) + +For example, a heterogeneous system with one AMD CPU is connected to +four MI200 (Aldebaran) GPUs using xGMI. This topology can be represented +via the following sysfs entries:: + + /sys/devices/system/edac/mc/.. + + CPU # CPU node + ├── mc 0 + + GPU Nodes are enumerated sequentially after CPU nodes have been populated + GPU card 1 # Each MI200 GPU has 2 nodes/mcs + ├── mc 1 # GPU node 0 == mc1, Each MC node has 4 UMCs/CSROWs + │ ├── csrow 0 # UMC 0 + │ │ ├── channel 0 # Each UMC has 8 channels + │ │ ├── channel 1 # size of each channel is 2 GB, so each UMC has 16 GB + │ │ ├── channel 2 + │ │ ├── channel 3 + │ │ ├── channel 4 + │ │ ├── channel 5 + │ │ ├── channel 6 + │ │ ├── channel 7 + │ ├── csrow 1 # UMC 1 + │ │ ├── channel 0 + │ │ ├── .. + │ │ ├── channel 7 + │ ├── .. .. + │ ├── csrow 3 # UMC 3 + │ │ ├── channel 0 + │ │ ├── .. + │ │ ├── channel 7 + │ ├── rank 0 + │ ├── .. .. + │ ├── rank 31 # total 32 ranks/dimms from 4 UMCs + ├ + ├── mc 2 # GPU node 1 == mc2 + │ ├── .. # each GPU has total 64 GB + + GPU card 2 + ├── mc 3 + │ ├── .. + ├── mc 4 + │ ├── .. + + GPU card 3 + ├── mc 5 + │ ├── .. + ├── mc 6 + │ ├── .. + + GPU card 4 + ├── mc 7 + │ ├── .. + ├── mc 8 + │ ├── .. diff --git a/Documentation/filesystems/autofs-mount-control.rst b/Documentation/filesystems/autofs-mount-control.rst index bf4b511cdbe8..b5a379d25c40 100644 --- a/Documentation/filesystems/autofs-mount-control.rst +++ b/Documentation/filesystems/autofs-mount-control.rst @@ -196,7 +196,7 @@ information and return operation results:: struct args_ismountpoint ismountpoint; }; - char path[0]; + char path[]; }; The ioctlfd field is a mount point file descriptor of an autofs mount diff --git a/Documentation/filesystems/autofs.rst b/Documentation/filesystems/autofs.rst index 4f490278d22f..3b6e38e646cd 100644 --- a/Documentation/filesystems/autofs.rst +++ b/Documentation/filesystems/autofs.rst @@ -467,7 +467,7 @@ Each ioctl is passed a pointer to an `autofs_dev_ioctl` structure:: struct args_ismountpoint ismountpoint; }; - char path[0]; + char path[]; }; For the **OPEN_MOUNT** and **IS_MOUNTPOINT** commands, the target diff --git a/Documentation/filesystems/directory-locking.rst b/Documentation/filesystems/directory-locking.rst index 504ba940c36c..dccd61c7c5c3 100644 --- a/Documentation/filesystems/directory-locking.rst +++ b/Documentation/filesystems/directory-locking.rst @@ -22,12 +22,11 @@ exclusive. 3) object removal. Locking rules: caller locks parent, finds victim, locks victim and calls the method. Locks are exclusive. -4) rename() that is _not_ cross-directory. Locking rules: caller locks -the parent and finds source and target. In case of exchange (with -RENAME_EXCHANGE in flags argument) lock both. In any case, -if the target already exists, lock it. If the source is a non-directory, -lock it. If we need to lock both, lock them in inode pointer order. -Then call the method. All locks are exclusive. +4) rename() that is _not_ cross-directory. Locking rules: caller locks the +parent and finds source and target. We lock both (provided they exist). If we +need to lock two inodes of different type (dir vs non-dir), we lock directory +first. If we need to lock two inodes of the same type, lock them in inode +pointer order. Then call the method. All locks are exclusive. NB: we might get away with locking the source (and target in exchange case) shared. @@ -44,15 +43,17 @@ All locks are exclusive. rules: * lock the filesystem - * lock parents in "ancestors first" order. + * lock parents in "ancestors first" order. If one is not ancestor of + the other, lock them in inode pointer order. * find source and target. * if old parent is equal to or is a descendent of target fail with -ENOTEMPTY * if new parent is equal to or is a descendent of source fail with -ELOOP - * If it's an exchange, lock both the source and the target. - * If the target exists, lock it. If the source is a non-directory, - lock it. If we need to lock both, do so in inode pointer order. + * Lock both the source and the target provided they exist. If we + need to lock two inodes of different type (dir vs non-dir), we lock + the directory first. If we need to lock two inodes of the same type, + lock them in inode pointer order. * call the method. All ->i_rwsem are taken exclusive. Again, we might get away with locking @@ -66,8 +67,9 @@ If no directory is its own ancestor, the scheme above is deadlock-free. Proof: - First of all, at any moment we have a partial ordering of the - objects - A < B iff A is an ancestor of B. + First of all, at any moment we have a linear ordering of the + objects - A < B iff (A is an ancestor of B) or (B is not an ancestor + of A and ptr(A) < ptr(B)). That ordering can change. However, the following is true: diff --git a/Documentation/filesystems/fsverity.rst b/Documentation/filesystems/fsverity.rst index ede672dedf11..cb845e8e5435 100644 --- a/Documentation/filesystems/fsverity.rst +++ b/Documentation/filesystems/fsverity.rst @@ -38,20 +38,14 @@ fail at runtime. Use cases ========= -By itself, the base fs-verity feature only provides integrity -protection, i.e. detection of accidental (non-malicious) corruption. +By itself, fs-verity only provides integrity protection, i.e. +detection of accidental (non-malicious) corruption. However, because fs-verity makes retrieving the file hash extremely efficient, it's primarily meant to be used as a tool to support authentication (detection of malicious modifications) or auditing (logging file hashes before use). -Trusted userspace code (e.g. operating system code running on a -read-only partition that is itself authenticated by dm-verity) can -authenticate the contents of an fs-verity file by using the -`FS_IOC_MEASURE_VERITY`_ ioctl to retrieve its hash, then verifying a -digital signature of it. - A standard file hash could be used instead of fs-verity. However, this is inefficient if the file is large and only a small portion may be accessed. This is often the case for Android application package @@ -69,24 +63,31 @@ still be used on read-only filesystems. fs-verity is for files that must live on a read-write filesystem because they are independently updated and potentially user-installed, so dm-verity cannot be used. -The base fs-verity feature is a hashing mechanism only; actually -authenticating the files may be done by: - -* Userspace-only - -* Builtin signature verification + userspace policy - - fs-verity optionally supports a simple signature verification - mechanism where users can configure the kernel to require that - all fs-verity files be signed by a key loaded into a keyring; - see `Built-in signature verification`_. - -* Integrity Measurement Architecture (IMA) - - IMA supports including fs-verity file digests and signatures in the - IMA measurement list and verifying fs-verity based file signatures - stored as security.ima xattrs, based on policy. - +fs-verity does not mandate a particular scheme for authenticating its +file hashes. (Similarly, dm-verity does not mandate a particular +scheme for authenticating its block device root hashes.) Options for +authenticating fs-verity file hashes include: + +- Trusted userspace code. Often, the userspace code that accesses + files can be trusted to authenticate them. Consider e.g. an + application that wants to authenticate data files before using them, + or an application loader that is part of the operating system (which + is already authenticated in a different way, such as by being loaded + from a read-only partition that uses dm-verity) and that wants to + authenticate applications before loading them. In these cases, this + trusted userspace code can authenticate a file's contents by + retrieving its fs-verity digest using `FS_IOC_MEASURE_VERITY`_, then + verifying a signature of it using any userspace cryptographic + library that supports digital signatures. + +- Integrity Measurement Architecture (IMA). IMA supports fs-verity + file digests as an alternative to its traditional full file digests. + "IMA appraisal" enforces that files contain a valid, matching + signature in their "security.ima" extended attribute, as controlled + by the IMA policy. For more information, see the IMA documentation. + +- Trusted userspace code in combination with `Built-in signature + verification`_. This approach should be used only with great care. User API ======== @@ -111,8 +112,7 @@ follows:: }; This structure contains the parameters of the Merkle tree to build for -the file, and optionally contains a signature. It must be initialized -as follows: +the file. It must be initialized as follows: - ``version`` must be 1. - ``hash_algorithm`` must be the identifier for the hash algorithm to @@ -129,12 +129,14 @@ as follows: file or device. Currently the maximum salt size is 32 bytes. - ``salt_ptr`` is the pointer to the salt, or NULL if no salt is provided. -- ``sig_size`` is the size of the signature in bytes, or 0 if no - signature is provided. Currently the signature is (somewhat - arbitrarily) limited to 16128 bytes. See `Built-in signature - verification`_ for more information. -- ``sig_ptr`` is the pointer to the signature, or NULL if no - signature is provided. +- ``sig_size`` is the size of the builtin signature in bytes, or 0 if no + builtin signature is provided. Currently the builtin signature is + (somewhat arbitrarily) limited to 16128 bytes. +- ``sig_ptr`` is the pointer to the builtin signature, or NULL if no + builtin signature is provided. A builtin signature is only needed + if the `Built-in signature verification`_ feature is being used. It + is not needed for IMA appraisal, and it is not needed if the file + signature is being handled entirely in userspace. - All reserved fields must be zeroed. FS_IOC_ENABLE_VERITY causes the filesystem to build a Merkle tree for @@ -158,7 +160,7 @@ fatal signal), no changes are made to the file. FS_IOC_ENABLE_VERITY can fail with the following errors: - ``EACCES``: the process does not have write access to the file -- ``EBADMSG``: the signature is malformed +- ``EBADMSG``: the builtin signature is malformed - ``EBUSY``: this ioctl is already running on the file - ``EEXIST``: the file already has verity enabled - ``EFAULT``: the caller provided inaccessible memory @@ -168,10 +170,10 @@ FS_IOC_ENABLE_VERITY can fail with the following errors: reserved bits are set; or the file descriptor refers to neither a regular file nor a directory. - ``EISDIR``: the file descriptor refers to a directory -- ``EKEYREJECTED``: the signature doesn't match the file -- ``EMSGSIZE``: the salt or signature is too long -- ``ENOKEY``: the fs-verity keyring doesn't contain the certificate - needed to verify the signature +- ``EKEYREJECTED``: the builtin signature doesn't match the file +- ``EMSGSIZE``: the salt or builtin signature is too long +- ``ENOKEY``: the ".fs-verity" keyring doesn't contain the certificate + needed to verify the builtin signature - ``ENOPKG``: fs-verity recognizes the hash algorithm, but it's not available in the kernel's crypto API as currently configured (e.g. for SHA-512, missing CONFIG_CRYPTO_SHA512). @@ -180,8 +182,8 @@ FS_IOC_ENABLE_VERITY can fail with the following errors: support; or the filesystem superblock has not had the 'verity' feature enabled on it; or the filesystem does not support fs-verity on this file. (See `Filesystem support`_.) -- ``EPERM``: the file is append-only; or, a signature is required and - one was not provided. +- ``EPERM``: the file is append-only; or, a builtin signature is + required and one was not provided. - ``EROFS``: the filesystem is read-only - ``ETXTBSY``: someone has the file open for writing. This can be the caller's file descriptor, another open file descriptor, or the file @@ -270,9 +272,9 @@ This ioctl takes in a pointer to the following structure:: - ``FS_VERITY_METADATA_TYPE_DESCRIPTOR`` reads the fs-verity descriptor. See `fs-verity descriptor`_. -- ``FS_VERITY_METADATA_TYPE_SIGNATURE`` reads the signature which was - passed to FS_IOC_ENABLE_VERITY, if any. See `Built-in signature - verification`_. +- ``FS_VERITY_METADATA_TYPE_SIGNATURE`` reads the builtin signature + which was passed to FS_IOC_ENABLE_VERITY, if any. See `Built-in + signature verification`_. The semantics are similar to those of ``pread()``. ``offset`` specifies the offset in bytes into the metadata item to read from, and @@ -299,7 +301,7 @@ FS_IOC_READ_VERITY_METADATA can fail with the following errors: overflowed - ``ENODATA``: the file is not a verity file, or FS_VERITY_METADATA_TYPE_SIGNATURE was requested but the file doesn't - have a built-in signature + have a builtin signature - ``ENOTTY``: this type of filesystem does not implement fs-verity, or this ioctl is not yet implemented on it - ``EOPNOTSUPP``: the kernel was not configured with fs-verity @@ -347,8 +349,8 @@ non-verity one, with the following exceptions: with EIO (for read()) or SIGBUS (for mmap() reads). - If the sysctl "fs.verity.require_signatures" is set to 1 and the - file is not signed by a key in the fs-verity keyring, then opening - the file will fail. See `Built-in signature verification`_. + file is not signed by a key in the ".fs-verity" keyring, then + opening the file will fail. See `Built-in signature verification`_. Direct access to the Merkle tree is not supported. Therefore, if a verity file is copied, or is backed up and restored, then it will lose @@ -433,20 +435,25 @@ root hash as well as other fields such as the file size:: Built-in signature verification =============================== -With CONFIG_FS_VERITY_BUILTIN_SIGNATURES=y, fs-verity supports putting -a portion of an authentication policy (see `Use cases`_) in the -kernel. Specifically, it adds support for: +CONFIG_FS_VERITY_BUILTIN_SIGNATURES=y adds supports for in-kernel +verification of fs-verity builtin signatures. + +**IMPORTANT**! Please take great care before using this feature. +It is not the only way to do signatures with fs-verity, and the +alternatives (such as userspace signature verification, and IMA +appraisal) can be much better. It's also easy to fall into a trap +of thinking this feature solves more problems than it actually does. + +Enabling this option adds the following: -1. At fs-verity module initialization time, a keyring ".fs-verity" is - created. The root user can add trusted X.509 certificates to this - keyring using the add_key() system call, then (when done) - optionally use keyctl_restrict_keyring() to prevent additional - certificates from being added. +1. At boot time, the kernel creates a keyring named ".fs-verity". The + root user can add trusted X.509 certificates to this keyring using + the add_key() system call. 2. `FS_IOC_ENABLE_VERITY`_ accepts a pointer to a PKCS#7 formatted detached signature in DER format of the file's fs-verity digest. - On success, this signature is persisted alongside the Merkle tree. - Then, any time the file is opened, the kernel will verify the + On success, the ioctl persists the signature alongside the Merkle + tree. Then, any time the file is opened, the kernel verifies the file's actual digest against this signature, using the certificates in the ".fs-verity" keyring. @@ -454,8 +461,8 @@ kernel. Specifically, it adds support for: When set to 1, the kernel requires that all verity files have a correctly signed digest as described in (2). -fs-verity file digests must be signed in the following format, which -is similar to the structure used by `FS_IOC_MEASURE_VERITY`_:: +The data that the signature as described in (2) must be a signature of +is the fs-verity file digest in the following format:: struct fsverity_formatted_digest { char magic[8]; /* must be "FSVerity" */ @@ -464,13 +471,66 @@ is similar to the structure used by `FS_IOC_MEASURE_VERITY`_:: __u8 digest[]; }; -fs-verity's built-in signature verification support is meant as a -relatively simple mechanism that can be used to provide some level of -authenticity protection for verity files, as an alternative to doing -the signature verification in userspace or using IMA-appraisal. -However, with this mechanism, userspace programs still need to check -that the verity bit is set, and there is no protection against verity -files being swapped around. +That's it. It should be emphasized again that fs-verity builtin +signatures are not the only way to do signatures with fs-verity. See +`Use cases`_ for an overview of ways in which fs-verity can be used. +fs-verity builtin signatures have some major limitations that should +be carefully considered before using them: + +- Builtin signature verification does *not* make the kernel enforce + that any files actually have fs-verity enabled. Thus, it is not a + complete authentication policy. Currently, if it is used, the only + way to complete the authentication policy is for trusted userspace + code to explicitly check whether files have fs-verity enabled with a + signature before they are accessed. (With + fs.verity.require_signatures=1, just checking whether fs-verity is + enabled suffices.) But, in this case the trusted userspace code + could just store the signature alongside the file and verify it + itself using a cryptographic library, instead of using this feature. + +- A file's builtin signature can only be set at the same time that + fs-verity is being enabled on the file. Changing or deleting the + builtin signature later requires re-creating the file. + +- Builtin signature verification uses the same set of public keys for + all fs-verity enabled files on the system. Different keys cannot be + trusted for different files; each key is all or nothing. + +- The sysctl fs.verity.require_signatures applies system-wide. + Setting it to 1 only works when all users of fs-verity on the system + agree that it should be set to 1. This limitation can prevent + fs-verity from being used in cases where it would be helpful. + +- Builtin signature verification can only use signature algorithms + that are supported by the kernel. For example, the kernel does not + yet support Ed25519, even though this is often the signature + algorithm that is recommended for new cryptographic designs. + +- fs-verity builtin signatures are in PKCS#7 format, and the public + keys are in X.509 format. These formats are commonly used, + including by some other kernel features (which is why the fs-verity + builtin signatures use them), and are very feature rich. + Unfortunately, history has shown that code that parses and handles + these formats (which are from the 1990s and are based on ASN.1) + often has vulnerabilities as a result of their complexity. This + complexity is not inherent to the cryptography itself. + + fs-verity users who do not need advanced features of X.509 and + PKCS#7 should strongly consider using simpler formats, such as plain + Ed25519 keys and signatures, and verifying signatures in userspace. + + fs-verity users who choose to use X.509 and PKCS#7 anyway should + still consider that verifying those signatures in userspace is more + flexible (for other reasons mentioned earlier in this document) and + eliminates the need to enable CONFIG_FS_VERITY_BUILTIN_SIGNATURES + and its associated increase in kernel attack surface. In some cases + it can even be necessary, since advanced X.509 and PKCS#7 features + do not always work as intended with the kernel. For example, the + kernel does not check X.509 certificate validity times. + + Note: IMA appraisal, which supports fs-verity, does not use PKCS#7 + for its signatures, so it partially avoids the issues discussed + here. IMA appraisal does use X.509. Filesystem support ================== diff --git a/Documentation/maintainer/configure-git.rst b/Documentation/maintainer/configure-git.rst index 80ae5030a590..ec0ddfb9cdd3 100644 --- a/Documentation/maintainer/configure-git.rst +++ b/Documentation/maintainer/configure-git.rst @@ -56,7 +56,7 @@ by adding the following hook into your git: $ cat >.git/hooks/applypatch-msg <<'EOF' #!/bin/sh . git-sh-setup - perl -pi -e 's|^Message-Id:\s*<?([^>]+)>?$|Link: https://lore.kernel.org/r/$1|g;' "$1" + perl -pi -e 's|^Message-I[dD]:\s*<?([^>]+)>?$|Link: https://lore.kernel.org/r/$1|g;' "$1" test -x "$GIT_DIR/hooks/commit-msg" && exec "$GIT_DIR/hooks/commit-msg" ${1+"$@"} : diff --git a/Documentation/mm/damon/design.rst b/Documentation/mm/damon/design.rst index 0cff6fac6b7e..4bfdf1d30c4a 100644 --- a/Documentation/mm/damon/design.rst +++ b/Documentation/mm/damon/design.rst @@ -4,31 +4,55 @@ Design ====== -Configurable Layers -=================== - -DAMON provides data access monitoring functionality while making the accuracy -and the overhead controllable. The fundamental access monitorings require -primitives that dependent on and optimized for the target address space. On -the other hand, the accuracy and overhead tradeoff mechanism, which is the core -of DAMON, is in the pure logic space. DAMON separates the two parts in -different layers and defines its interface to allow various low level -primitives implementations configurable with the core logic. We call the low -level primitives implementations monitoring operations. - -Due to this separated design and the configurable interface, users can extend -DAMON for any address space by configuring the core logics with appropriate -monitoring operations. If appropriate one is not provided, users can implement -the operations on their own. + +Overall Architecture +==================== + +DAMON subsystem is configured with three layers including + +- Operations Set: Implements fundamental operations for DAMON that depends on + the given monitoring target address-space and available set of + software/hardware primitives, +- Core: Implements core logics including monitoring overhead/accurach control + and access-aware system operations on top of the operations set layer, and +- Modules: Implements kernel modules for various purposes that provides + interfaces for the user space, on top of the core layer. + + +Configurable Operations Set +--------------------------- + +For data access monitoring and additional low level work, DAMON needs a set of +implementations for specific operations that are dependent on and optimized for +the given target address space. On the other hand, the accuracy and overhead +tradeoff mechanism, which is the core logic of DAMON, is in the pure logic +space. DAMON separates the two parts in different layers, namely DAMON +Operations Set and DAMON Core Logics Layers, respectively. It further defines +the interface between the layers to allow various operations sets to be +configured with the core logic. + +Due to this design, users can extend DAMON for any address space by configuring +the core logic to use the appropriate operations set. If any appropriate set +is unavailable, users can implement one on their own. For example, physical memory, virtual memory, swap space, those for specific processes, NUMA nodes, files, and backing memory devices would be supportable. -Also, if some architectures or devices support special optimized access check -primitives, those will be easily configurable. +Also, if some architectures or devices supporting special optimized access +check primitives, those will be easily configurable. -Reference Implementations of Address Space Specific Monitoring Operations -========================================================================= +Programmable Modules +-------------------- + +Core layer of DAMON is implemented as a framework, and exposes its application +programming interface to all kernel space components such as subsystems and +modules. For common use cases of DAMON, DAMON subsystem provides kernel +modules that built on top of the core layer using the API, which can be easily +used by the user space end users. + + +Operations Set Layer +==================== The monitoring operations are defined in two parts: @@ -90,8 +114,12 @@ conflict with the reclaim logic using ``PG_idle`` and ``PG_young`` page flags, as Idle page tracking does. -Address Space Independent Core Mechanisms -========================================= +Core Logics +=========== + + +Monitoring +---------- Below four sections describe each of the DAMON core mechanisms and the five monitoring attributes, ``sampling interval``, ``aggregation interval``, @@ -100,7 +128,7 @@ regions``. Access Frequency Monitoring ---------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~~~~ The output of DAMON says what pages are how frequently accessed for a given duration. The resolution of the access frequency is controlled by setting @@ -127,7 +155,7 @@ size of the target workload grows. Region Based Sampling ---------------------- +~~~~~~~~~~~~~~~~~~~~~ To avoid the unbounded increase of the overhead, DAMON groups adjacent pages that assumed to have the same access frequencies into a region. As long as the @@ -144,7 +172,7 @@ assumption is not guaranteed. Adaptive Regions Adjustment ---------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~~~~ Even somehow the initial monitoring target regions are well constructed to fulfill the assumption (pages in same region have similar access frequencies), @@ -162,8 +190,22 @@ In this way, DAMON provides its best-effort quality and minimal overhead while keeping the bounds users set for their trade-off. +Age Tracking +~~~~~~~~~~~~ + +By analyzing the monitoring results, users can also find how long the current +access pattern of a region has maintained. That could be used for good +understanding of the access pattern. For example, page placement algorithm +utilizing both the frequency and the recency could be implemented using that. +To make such access pattern maintained period analysis easier, DAMON maintains +yet another counter called ``age`` in each region. For each ``aggregation +interval``, DAMON checks if the region's size and access frequency +(``nr_accesses``) has significantly changed. If so, the counter is reset to +zero. Otherwise, the counter is increased. + + Dynamic Target Space Updates Handling -------------------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The monitoring target address range could dynamically changed. For example, virtual memory could be dynamically mapped and unmapped. Physical memory could @@ -174,3 +216,246 @@ monitoring operations to check dynamic changes including memory mapping changes and applies it to monitoring operations-related data structures such as the abstracted monitoring target memory area only for each of a user-specified time interval (``update interval``). + + +.. _damon_design_damos: + +Operation Schemes +----------------- + +One common purpose of data access monitoring is access-aware system efficiency +optimizations. For example, + + paging out memory regions that are not accessed for more than two minutes + +or + + using THP for memory regions that are larger than 2 MiB and showing a high + access frequency for more than one minute. + +One straightforward approach for such schemes would be profile-guided +optimizations. That is, getting data access monitoring results of the +workloads or the system using DAMON, finding memory regions of special +characteristics by profiling the monitoring results, and making system +operation changes for the regions. The changes could be made by modifying or +providing advice to the software (the application and/or the kernel), or +reconfiguring the hardware. Both offline and online approaches could be +available. + +Among those, providing advice to the kernel at runtime would be flexible and +effective, and therefore widely be used. However, implementing such schemes +could impose unnecessary redundancy and inefficiency. The profiling could be +redundant if the type of interest is common. Exchanging the information +including monitoring results and operation advice between kernel and user +spaces could be inefficient. + +To allow users to reduce such redundancy and inefficiencies by offloading the +works, DAMON provides a feature called Data Access Monitoring-based Operation +Schemes (DAMOS). It lets users specify their desired schemes at a high +level. For such specifications, DAMON starts monitoring, finds regions having +the access pattern of interest, and applies the user-desired operation actions +to the regions as soon as found. + + +.. _damon_design_damos_action: + +Operation Action +~~~~~~~~~~~~~~~~ + +The management action that the users desire to apply to the regions of their +interest. For example, paging out, prioritizing for next reclamation victim +selection, advising ``khugepaged`` to collapse or split, or doing nothing but +collecting statistics of the regions. + +The list of supported actions is defined in DAMOS, but the implementation of +each action is in the DAMON operations set layer because the implementation +normally depends on the monitoring target address space. For example, the code +for paging specific virtual address ranges out would be different from that for +physical address ranges. And the monitoring operations implementation sets are +not mandated to support all actions of the list. Hence, the availability of +specific DAMOS action depends on what operations set is selected to be used +together. + +Applying an action to a region is considered as changing the region's +characteristics. Hence, DAMOS resets the age of regions when an action is +applied to those. + + +.. _damon_design_damos_access_pattern: + +Target Access Pattern +~~~~~~~~~~~~~~~~~~~~~ + +The access pattern of the schemes' interest. The patterns are constructed with +the properties that DAMON's monitoring results provide, specifically the size, +the access frequency, and the age. Users can describe their access pattern of +interest by setting minimum and maximum values of the three properties. If a +region's three properties are in the ranges, DAMOS classifies it as one of the +regions that the scheme is having an interest in. + + +.. _damon_design_damos_quotas: + +Quotas +~~~~~~ + +DAMOS upper-bound overhead control feature. DAMOS could incur high overhead if +the target access pattern is not properly tuned. For example, if a huge memory +region having the access pattern of interest is found, applying the scheme's +action to all pages of the huge region could consume unacceptably large system +resources. Preventing such issues by tuning the access pattern could be +challenging, especially if the access patterns of the workloads are highly +dynamic. + +To mitigate that situation, DAMOS provides an upper-bound overhead control +feature called quotas. It lets users specify an upper limit of time that DAMOS +can use for applying the action, and/or a maximum bytes of memory regions that +the action can be applied within a user-specified time duration. + + +.. _damon_design_damos_quotas_prioritization: + +Prioritization +^^^^^^^^^^^^^^ + +A mechanism for making a good decision under the quotas. When the action +cannot be applied to all regions of interest due to the quotas, DAMOS +prioritizes regions and applies the action to only regions having high enough +priorities so that it will not exceed the quotas. + +The prioritization mechanism should be different for each action. For example, +rarely accessed (colder) memory regions would be prioritized for page-out +scheme action. In contrast, the colder regions would be deprioritized for huge +page collapse scheme action. Hence, the prioritization mechanisms for each +action are implemented in each DAMON operations set, together with the actions. + +Though the implementation is up to the DAMON operations set, it would be common +to calculate the priority using the access pattern properties of the regions. +Some users would want the mechanisms to be personalized for their specific +case. For example, some users would want the mechanism to weigh the recency +(``age``) more than the access frequency (``nr_accesses``). DAMOS allows users +to specify the weight of each access pattern property and passes the +information to the underlying mechanism. Nevertheless, how and even whether +the weight will be respected are up to the underlying prioritization mechanism +implementation. + + +.. _damon_design_damos_watermarks: + +Watermarks +~~~~~~~~~~ + +Conditional DAMOS (de)activation automation. Users might want DAMOS to run +only under certain situations. For example, when a sufficient amount of free +memory is guaranteed, running a scheme for proactive reclamation would only +consume unnecessary system resources. To avoid such consumption, the user would +need to manually monitor some metrics such as free memory ratio, and turn +DAMON/DAMOS on or off. + +DAMOS allows users to offload such works using three watermarks. It allows the +users to configure the metric of their interest, and three watermark values, +namely high, middle, and low. If the value of the metric becomes above the +high watermark or below the low watermark, the scheme is deactivated. If the +metric becomes below the mid watermark but above the low watermark, the scheme +is activated. If all schemes are deactivated by the watermarks, the monitoring +is also deactivated. In this case, the DAMON worker thread only periodically +checks the watermarks and therefore incurs nearly zero overhead. + + +.. _damon_design_damos_filters: + +Filters +~~~~~~~ + +Non-access pattern-based target memory regions filtering. If users run +self-written programs or have good profiling tools, they could know something +more than the kernel, such as future access patterns or some special +requirements for specific types of memory. For example, some users may know +only anonymous pages can impact their program's performance. They can also +have a list of latency-critical processes. + +To let users optimize DAMOS schemes with such special knowledge, DAMOS provides +a feature called DAMOS filters. The feature allows users to set an arbitrary +number of filters for each scheme. Each filter specifies the type of target +memory, and whether it should exclude the memory of the type (filter-out), or +all except the memory of the type (filter-in). + +As of this writing, anonymous page type and memory cgroup type are supported by +the feature. Some filter target types can require additional arguments. For +example, the memory cgroup filter type asks users to specify the file path of +the memory cgroup for the filter. Hence, users can apply specific schemes to +only anonymous pages, non-anonymous pages, pages of specific cgroups, all pages +excluding those of specific cgroups, and any combination of those. + + +Application Programming Interface +--------------------------------- + +The programming interface for kernel space data access-aware applications. +DAMON is a framework, so it does nothing by itself. Instead, it only helps +other kernel components such as subsystems and modules building their data +access-aware applications using DAMON's core features. For this, DAMON exposes +its all features to other kernel components via its application programming +interface, namely ``include/linux/damon.h``. Please refer to the API +:doc:`document </mm/damon/api>` for details of the interface. + + +Modules +======= + +Because the core of DAMON is a framework for kernel components, it doesn't +provide any direct interface for the user space. Such interfaces should be +implemented by each DAMON API user kernel components, instead. DAMON subsystem +itself implements such DAMON API user modules, which are supposed to be used +for general purpose DAMON control and special purpose data access-aware system +operations, and provides stable application binary interfaces (ABI) for the +user space. The user space can build their efficient data access-aware +applications using the interfaces. + + +General Purpose User Interface Modules +-------------------------------------- + +DAMON modules that provide user space ABIs for general purpose DAMON usage in +runtime. + +DAMON user interface modules, namely 'DAMON sysfs interface' and 'DAMON debugfs +interface' are DAMON API user kernel modules that provide ABIs to the +user-space. Please note that DAMON debugfs interface is currently deprecated. + +Like many other ABIs, the modules create files on sysfs and debugfs, allow +users to specify their requests to and get the answers from DAMON by writing to +and reading from the files. As a response to such I/O, DAMON user interface +modules control DAMON and retrieve the results as user requested via the DAMON +API, and return the results to the user-space. + +The ABIs are designed to be used for user space applications development, +rather than human beings' fingers. Human users are recommended to use such +user space tools. One such Python-written user space tool is available at +Github (https://github.com/awslabs/damo), Pypi +(https://pypistats.org/packages/damo), and Fedora +(https://packages.fedoraproject.org/pkgs/python-damo/damo/). + +Please refer to the ABI :doc:`document </admin-guide/mm/damon/usage>` for +details of the interfaces. + + +Special-Purpose Access-aware Kernel Modules +------------------------------------------- + +DAMON modules that provide user space ABI for specific purpose DAMON usage. + +DAMON sysfs/debugfs user interfaces are for full control of all DAMON features +in runtime. For each special-purpose system-wide data access-aware system +operations such as proactive reclamation or LRU lists balancing, the interfaces +could be simplified by removing unnecessary knobs for the specific purpose, and +extended for boot-time and even compile time control. Default values of DAMON +control parameters for the usage would also need to be optimized for the +purpose. + +To support such cases, yet more DAMON API user kernel modules that provide more +simple and optimized user space interfaces are available. Currently, two +modules for proactive reclamation and LRU lists manipulation are provided. For +more detail, please read the usage documents for those +(:doc:`/admin-guide/mm/damon/reclaim` and +:doc:`/admin-guide/mm/damon/lru_sort`). diff --git a/Documentation/mm/damon/faq.rst b/Documentation/mm/damon/faq.rst index dde7e2414ee6..3279dc7a8211 100644 --- a/Documentation/mm/damon/faq.rst +++ b/Documentation/mm/damon/faq.rst @@ -4,29 +4,6 @@ Frequently Asked Questions ========================== -Why a new subsystem, instead of extending perf or other user space tools? -========================================================================= - -First, because it needs to be lightweight as much as possible so that it can be -used online, any unnecessary overhead such as kernel - user space context -switching cost should be avoided. Second, DAMON aims to be used by other -programs including the kernel. Therefore, having a dependency on specific -tools like perf is not desirable. These are the two biggest reasons why DAMON -is implemented in the kernel space. - - -Can 'idle pages tracking' or 'perf mem' substitute DAMON? -========================================================= - -Idle page tracking is a low level primitive for access check of the physical -address space. 'perf mem' is similar, though it can use sampling to minimize -the overhead. On the other hand, DAMON is a higher-level framework for the -monitoring of various address spaces. It is focused on memory management -optimization and provides sophisticated accuracy/overhead handling mechanisms. -Therefore, 'idle pages tracking' and 'perf mem' could provide a subset of -DAMON's output, but cannot substitute DAMON. - - Does DAMON support virtual memory only? ======================================= diff --git a/Documentation/mm/damon/maintainer-profile.rst b/Documentation/mm/damon/maintainer-profile.rst index 24a202f03de8..a84c14e59053 100644 --- a/Documentation/mm/damon/maintainer-profile.rst +++ b/Documentation/mm/damon/maintainer-profile.rst @@ -3,7 +3,7 @@ DAMON Maintainer Entry Profile ============================== -The DAMON subsystem covers the files that listed in 'DATA ACCESS MONITOR' +The DAMON subsystem covers the files that are listed in 'DATA ACCESS MONITOR' section of 'MAINTAINERS' file. The mailing lists for the subsystem are damon@lists.linux.dev and @@ -15,7 +15,7 @@ SCM Trees There are multiple Linux trees for DAMON development. Patches under development or testing are queued in damon/next [2]_ by the DAMON maintainer. -Suffieicntly reviewed patches will be queued in mm-unstable [1]_ by the memory +Sufficiently reviewed patches will be queued in mm-unstable [1]_ by the memory management subsystem maintainer. After more sufficient tests, the patches will be queued in mm-stable [3]_ , and finally pull-requested to the mainline by the memory management subsystem maintainer. diff --git a/Documentation/mm/page_migration.rst b/Documentation/mm/page_migration.rst index 313dce18893e..e35af7805be5 100644 --- a/Documentation/mm/page_migration.rst +++ b/Documentation/mm/page_migration.rst @@ -73,14 +73,13 @@ In kernel use of migrate_pages() It also prevents the swapper or other scans from encountering the page. -2. We need to have a function of type new_page_t that can be +2. We need to have a function of type new_folio_t that can be passed to migrate_pages(). This function should figure out - how to allocate the correct new page given the old page. + how to allocate the correct new folio given the old folio. 3. The migrate_pages() function is called which attempts to do the migration. It will call the function to allocate - the new page for each page that is considered for - moving. + the new folio for each folio that is considered for moving. How migrate_pages() works ========================= diff --git a/Documentation/mm/page_tables.rst b/Documentation/mm/page_tables.rst index 96939571d7bc..7840c1891751 100644 --- a/Documentation/mm/page_tables.rst +++ b/Documentation/mm/page_tables.rst @@ -3,3 +3,152 @@ =========== Page Tables =========== + +Paged virtual memory was invented along with virtual memory as a concept in +1962 on the Ferranti Atlas Computer which was the first computer with paged +virtual memory. The feature migrated to newer computers and became a de facto +feature of all Unix-like systems as time went by. In 1985 the feature was +included in the Intel 80386, which was the CPU Linux 1.0 was developed on. + +Page tables map virtual addresses as seen by the CPU into physical addresses +as seen on the external memory bus. + +Linux defines page tables as a hierarchy which is currently five levels in +height. The architecture code for each supported architecture will then +map this to the restrictions of the hardware. + +The physical address corresponding to the virtual address is often referenced +by the underlying physical page frame. The **page frame number** or **pfn** +is the physical address of the page (as seen on the external memory bus) +divided by `PAGE_SIZE`. + +Physical memory address 0 will be *pfn 0* and the highest pfn will be +the last page of physical memory the external address bus of the CPU can +address. + +With a page granularity of 4KB and a address range of 32 bits, pfn 0 is at +address 0x00000000, pfn 1 is at address 0x00001000, pfn 2 is at 0x00002000 +and so on until we reach pfn 0xfffff at 0xfffff000. With 16KB pages pfs are +at 0x00004000, 0x00008000 ... 0xffffc000 and pfn goes from 0 to 0x3fffff. + +As you can see, with 4KB pages the page base address uses bits 12-31 of the +address, and this is why `PAGE_SHIFT` in this case is defined as 12 and +`PAGE_SIZE` is usually defined in terms of the page shift as `(1 << PAGE_SHIFT)` + +Over time a deeper hierarchy has been developed in response to increasing memory +sizes. When Linux was created, 4KB pages and a single page table called +`swapper_pg_dir` with 1024 entries was used, covering 4MB which coincided with +the fact that Torvald's first computer had 4MB of physical memory. Entries in +this single table were referred to as *PTE*:s - page table entries. + +The software page table hierarchy reflects the fact that page table hardware has +become hierarchical and that in turn is done to save page table memory and +speed up mapping. + +One could of course imagine a single, linear page table with enormous amounts +of entries, breaking down the whole memory into single pages. Such a page table +would be very sparse, because large portions of the virtual memory usually +remains unused. By using hierarchical page tables large holes in the virtual +address space does not waste valuable page table memory, because it will suffice +to mark large areas as unmapped at a higher level in the page table hierarchy. + +Additionally, on modern CPUs, a higher level page table entry can point directly +to a physical memory range, which allows mapping a contiguous range of several +megabytes or even gigabytes in a single high-level page table entry, taking +shortcuts in mapping virtual memory to physical memory: there is no need to +traverse deeper in the hierarchy when you find a large mapped range like this. + +The page table hierarchy has now developed into this:: + + +-----+ + | PGD | + +-----+ + | + | +-----+ + +-->| P4D | + +-----+ + | + | +-----+ + +-->| PUD | + +-----+ + | + | +-----+ + +-->| PMD | + +-----+ + | + | +-----+ + +-->| PTE | + +-----+ + + +Symbols on the different levels of the page table hierarchy have the following +meaning beginning from the bottom: + +- **pte**, `pte_t`, `pteval_t` = **Page Table Entry** - mentioned earlier. + The *pte* is an array of `PTRS_PER_PTE` elements of the `pteval_t` type, each + mapping a single page of virtual memory to a single page of physical memory. + The architecture defines the size and contents of `pteval_t`. + + A typical example is that the `pteval_t` is a 32- or 64-bit value with the + upper bits being a **pfn** (page frame number), and the lower bits being some + architecture-specific bits such as memory protection. + + The **entry** part of the name is a bit confusing because while in Linux 1.0 + this did refer to a single page table entry in the single top level page + table, it was retrofitted to be an array of mapping elements when two-level + page tables were first introduced, so the *pte* is the lowermost page + *table*, not a page table *entry*. + +- **pmd**, `pmd_t`, `pmdval_t` = **Page Middle Directory**, the hierarchy right + above the *pte*, with `PTRS_PER_PMD` references to the *pte*:s. + +- **pud**, `pud_t`, `pudval_t` = **Page Upper Directory** was introduced after + the other levels to handle 4-level page tables. It is potentially unused, + or *folded* as we will discuss later. + +- **p4d**, `p4d_t`, `p4dval_t` = **Page Level 4 Directory** was introduced to + handle 5-level page tables after the *pud* was introduced. Now it was clear + that we needed to replace *pgd*, *pmd*, *pud* etc with a figure indicating the + directory level and that we cannot go on with ad hoc names any more. This + is only used on systems which actually have 5 levels of page tables, otherwise + it is folded. + +- **pgd**, `pgd_t`, `pgdval_t` = **Page Global Directory** - the Linux kernel + main page table handling the PGD for the kernel memory is still found in + `swapper_pg_dir`, but each userspace process in the system also has its own + memory context and thus its own *pgd*, found in `struct mm_struct` which + in turn is referenced to in each `struct task_struct`. So tasks have memory + context in the form of a `struct mm_struct` and this in turn has a + `struct pgt_t *pgd` pointer to the corresponding page global directory. + +To repeat: each level in the page table hierarchy is a *array of pointers*, so +the **pgd** contains `PTRS_PER_PGD` pointers to the next level below, **p4d** +contains `PTRS_PER_P4D` pointers to **pud** items and so on. The number of +pointers on each level is architecture-defined.:: + + PMD + --> +-----+ PTE + | ptr |-------> +-----+ + | ptr |- | ptr |-------> PAGE + | ptr | \ | ptr | + | ptr | \ ... + | ... | \ + | ptr | \ PTE + +-----+ +----> +-----+ + | ptr |-------> PAGE + | ptr | + ... + + +Page Table Folding +================== + +If the architecture does not use all the page table levels, they can be *folded* +which means skipped, and all operations performed on page tables will be +compile-time augmented to just skip a level when accessing the next lower +level. + +Page table handling code that wishes to be architecture-neutral, such as the +virtual memory manager, will need to be written so that it traverses all of the +currently five levels. This style should also be preferred for +architecture-specific code, so as to be robust to future changes. diff --git a/Documentation/mm/split_page_table_lock.rst b/Documentation/mm/split_page_table_lock.rst index 50ee0dfc95be..a834fad9de12 100644 --- a/Documentation/mm/split_page_table_lock.rst +++ b/Documentation/mm/split_page_table_lock.rst @@ -14,15 +14,20 @@ tables. Access to higher level tables protected by mm->page_table_lock. There are helpers to lock/unlock a table and other accessor functions: - pte_offset_map_lock() - maps pte and takes PTE table lock, returns pointer to the taken - lock; + maps PTE and takes PTE table lock, returns pointer to PTE with + pointer to its PTE table lock, or returns NULL if no PTE table; + - pte_offset_map_nolock() + maps PTE, returns pointer to PTE with pointer to its PTE table + lock (not taken), or returns NULL if no PTE table; + - pte_offset_map() + maps PTE, returns pointer to PTE, or returns NULL if no PTE table; + - pte_unmap() + unmaps PTE table; - pte_unmap_unlock() unlocks and unmaps PTE table; - pte_alloc_map_lock() - allocates PTE table if needed and take the lock, returns pointer - to taken lock or NULL if allocation failed; - - pte_lockptr() - returns pointer to PTE table lock; + allocates PTE table if needed and takes its lock, returns pointer to + PTE with pointer to its lock, or returns NULL if allocation failed; - pmd_lock() takes PMD table lock, returns pointer to taken lock; - pmd_lockptr() diff --git a/Documentation/process/2.Process.rst b/Documentation/process/2.Process.rst index 6a919cffcbfd..613a01da4717 100644 --- a/Documentation/process/2.Process.rst +++ b/Documentation/process/2.Process.rst @@ -434,9 +434,10 @@ There are a few hints which can help with linux-kernel survival: questions. Some developers can get impatient with people who clearly have not done their homework. -- Avoid top-posting (the practice of putting your answer above the quoted - text you are responding to). It makes your response harder to read and - makes a poor impression. +- Use interleaved ("inline") replies, which makes your response easier to + read. (i.e. avoid top-posting -- the practice of putting your answer above + the quoted text you are responding to.) For more details, see + :ref:`Documentation/process/submitting-patches.rst <interleaved_replies>`. - Ask on the correct mailing list. Linux-kernel may be the general meeting point, but it is not the best place to find developers from all diff --git a/Documentation/process/changes.rst b/Documentation/process/changes.rst index ef540865ad22..5cf6a5f8ca57 100644 --- a/Documentation/process/changes.rst +++ b/Documentation/process/changes.rst @@ -31,7 +31,7 @@ you probably needn't concern yourself with pcmciautils. ====================== =============== ======================================== GNU C 5.1 gcc --version Clang/LLVM (optional) 11.0.0 clang --version -Rust (optional) 1.62.0 rustc --version +Rust (optional) 1.68.2 rustc --version bindgen (optional) 0.56.0 bindgen --version GNU make 3.82 make --version bash 4.2 bash --version diff --git a/Documentation/process/handling-regressions.rst b/Documentation/process/handling-regressions.rst index abb741b1aeee..5d3c3de3f4ec 100644 --- a/Documentation/process/handling-regressions.rst +++ b/Documentation/process/handling-regressions.rst @@ -129,88 +129,132 @@ tools and scripts used by other kernel developers or Linux distributions; one of these tools is regzbot, which heavily relies on the "Link:" tags to associate reports for regression with changes resolving them. -Prioritize work on fixing regressions -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -You should fix any reported regression as quickly as possible, to provide -affected users with a solution in a timely manner and prevent more users from -running into the issue; nevertheless developers need to take enough time and -care to ensure regression fixes do not cause additional damage. - -In the end though, developers should give their best to prevent users from -running into situations where a regression leaves them only three options: "run -a kernel with a regression that seriously impacts usage", "continue running an -outdated and thus potentially insecure kernel version for more than two weeks -after a regression's culprit was identified", and "downgrade to a still -supported kernel series that lack required features". - -How to realize this depends a lot on the situation. Here are a few rules of -thumb for you, in order or importance: - - * Prioritize work on handling regression reports and fixing regression over all - other Linux kernel work, unless the latter concerns acute security issues or - bugs causing data loss or damage. - - * Always consider reverting the culprit commits and reapplying them later - together with necessary fixes, as this might be the least dangerous and - quickest way to fix a regression. - - * Developers should handle regressions in all supported kernel series, but are - free to delegate the work to the stable team, if the issue probably at no - point in time occurred with mainline. - - * Try to resolve any regressions introduced in the current development before - its end. If you fear a fix might be too risky to apply only days before a new - mainline release, let Linus decide: submit the fix separately to him as soon - as possible with the explanation of the situation. He then can make a call - and postpone the release if necessary, for example if multiple such changes - show up in his inbox. - - * Address regressions in stable, longterm, or proper mainline releases with - more urgency than regressions in mainline pre-releases. That changes after - the release of the fifth pre-release, aka "-rc5": mainline then becomes as - important, to ensure all the improvements and fixes are ideally tested - together for at least one week before Linus releases a new mainline version. - - * Fix regressions within two or three days, if they are critical for some - reason -- for example, if the issue is likely to affect many users of the - kernel series in question on all or certain architectures. Note, this - includes mainline, as issues like compile errors otherwise might prevent many - testers or continuous integration systems from testing the series. - - * Aim to fix regressions within one week after the culprit was identified, if - the issue was introduced in either: - - * a recent stable/longterm release - - * the development cycle of the latest proper mainline release - - In the latter case (say Linux v5.14), try to address regressions even - quicker, if the stable series for the predecessor (v5.13) will be abandoned - soon or already was stamped "End-of-Life" (EOL) -- this usually happens about - three to four weeks after a new mainline release. - - * Try to fix all other regressions within two weeks after the culprit was - found. Two or three additional weeks are acceptable for performance - regressions and other issues which are annoying, but don't prevent anyone - from running Linux (unless it's an issue in the current development cycle, - as those should ideally be addressed before the release). A few weeks in - total are acceptable if a regression can only be fixed with a risky change - and at the same time is affecting only a few users; as much time is - also okay if the regression is already present in the second newest longterm - kernel series. - -Note: The aforementioned time frames for resolving regressions are meant to -include getting the fix tested, reviewed, and merged into mainline, ideally with -the fix being in linux-next at least briefly. This leads to delays you need to -account for. - -Subsystem maintainers are expected to assist in reaching those periods by doing -timely reviews and quick handling of accepted patches. They thus might have to -send git-pull requests earlier or more often than usual; depending on the fix, -it might even be acceptable to skip testing in linux-next. Especially fixes for -regressions in stable and longterm kernels need to be handled quickly, as fixes -need to be merged in mainline before they can be backported to older series. +Expectations and best practices for fixing regressions +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +As a Linux kernel developer, you are expected to give your best to prevent +situations where a regression caused by a recent change of yours leaves users +only these options: + + * Run a kernel with a regression that impacts usage. + + * Switch to an older or newer kernel series. + + * Continue running an outdated and thus potentially insecure kernel for more + than three weeks after the regression's culprit was identified. Ideally it + should be less than two. And it ought to be just a few days, if the issue is + severe or affects many users -- either in general or in prevalent + environments. + +How to realize that in practice depends on various factors. Use the following +rules of thumb as a guide. + +In general: + + * Prioritize work on regressions over all other Linux kernel work, unless the + latter concerns a severe issue (e.g. acute security vulnerability, data loss, + bricked hardware, ...). + + * Expedite fixing mainline regressions that recently made it into a proper + mainline, stable, or longterm release (either directly or via backport). + + * Do not consider regressions from the current cycle as something that can wait + till the end of the cycle, as the issue might discourage or prevent users and + CI systems from testing mainline now or generally. + + * Work with the required care to avoid additional or bigger damage, even if + resolving an issue then might take longer than outlined below. + +On timing once the culprit of a regression is known: + + * Aim to mainline a fix within two or three days, if the issue is severe or + bothering many users -- either in general or in prevalent conditions like a + particular hardware environment, distribution, or stable/longterm series. + + * Aim to mainline a fix by Sunday after the next, if the culprit made it + into a recent mainline, stable, or longterm release (either directly or via + backport); if the culprit became known early during a week and is simple to + resolve, try to mainline the fix within the same week. + + * For other regressions, aim to mainline fixes before the hindmost Sunday + within the next three weeks. One or two Sundays later are acceptable, if the + regression is something people can live with easily for a while -- like a + mild performance regression. + + * It's strongly discouraged to delay mainlining regression fixes till the next + merge window, except when the fix is extraordinarily risky or when the + culprit was mainlined more than a year ago. + +On procedure: + + * Always consider reverting the culprit, as it's often the quickest and least + dangerous way to fix a regression. Don't worry about mainlining a fixed + variant later: that should be straight-forward, as most of the code went + through review once already. + + * Try to resolve any regressions introduced in mainline during the past + twelve months before the current development cycle ends: Linus wants such + regressions to be handled like those from the current cycle, unless fixing + bears unusual risks. + + * Consider CCing Linus on discussions or patch review, if a regression seems + tangly. Do the same in precarious or urgent cases -- especially if the + subsystem maintainer might be unavailable. Also CC the stable team, when you + know such a regression made it into a mainline, stable, or longterm release. + + * For urgent regressions, consider asking Linus to pick up the fix straight + from the mailing list: he is totally fine with that for uncontroversial + fixes. Ideally though such requests should happen in accordance with the + subsystem maintainers or come directly from them. + + * In case you are unsure if a fix is worth the risk applying just days before + a new mainline release, send Linus a mail with the usual lists and people in + CC; in it, summarize the situation while asking him to consider picking up + the fix straight from the list. He then himself can make the call and when + needed even postpone the release. Such requests again should ideally happen + in accordance with the subsystem maintainers or come directly from them. + +Regarding stable and longterm kernels: + + * You are free to leave regressions to the stable team, if they at no point in + time occurred with mainline or were fixed there already. + + * If a regression made it into a proper mainline release during the past + twelve months, ensure to tag the fix with "Cc: stable@vger.kernel.org", as a + "Fixes:" tag alone does not guarantee a backport. Please add the same tag, + in case you know the culprit was backported to stable or longterm kernels. + + * When receiving reports about regressions in recent stable or longterm kernel + series, please evaluate at least briefly if the issue might happen in current + mainline as well -- and if that seems likely, take hold of the report. If in + doubt, ask the reporter to check mainline. + + * Whenever you want to swiftly resolve a regression that recently also made it + into a proper mainline, stable, or longterm release, fix it quickly in + mainline; when appropriate thus involve Linus to fast-track the fix (see + above). That's because the stable team normally does neither revert nor fix + any changes that cause the same problems in mainline. + + * In case of urgent regression fixes you might want to ensure prompt + backporting by dropping the stable team a note once the fix was mainlined; + this is especially advisable during merge windows and shortly thereafter, as + the fix otherwise might land at the end of a huge patch queue. + +On patch flow: + + * Developers, when trying to reach the time periods mentioned above, remember + to account for the time it takes to get fixes tested, reviewed, and merged by + Linus, ideally with them being in linux-next at least briefly. Hence, if a + fix is urgent, make it obvious to ensure others handle it appropriately. + + * Reviewers, you are kindly asked to assist developers in reaching the time + periods mentioned above by reviewing regression fixes in a timely manner. + + * Subsystem maintainers, you likewise are encouraged to expedite the handling + of regression fixes. Thus evaluate if skipping linux-next is an option for + the particular fix. Also consider sending git pull requests more often than + usual when needed. And try to avoid holding onto regression fixes over + weekends -- especially when the fix is marked for backporting. More aspects regarding regressions developers should be aware of diff --git a/Documentation/process/maintainer-tip.rst b/Documentation/process/maintainer-tip.rst index 178c95fd17dc..93d8a794bdfc 100644 --- a/Documentation/process/maintainer-tip.rst +++ b/Documentation/process/maintainer-tip.rst @@ -421,6 +421,9 @@ allowing themselves a breath. Please respect that. The release candidate -rc1 is the starting point for new patches to be applied which are targeted for the next merge window. +So called _urgent_ branches will be merged into mainline during the +stabilization phase of each release. + Git ^^^ diff --git a/Documentation/process/submitting-patches.rst b/Documentation/process/submitting-patches.rst index 486875fd73c0..efac910e2659 100644 --- a/Documentation/process/submitting-patches.rst +++ b/Documentation/process/submitting-patches.rst @@ -331,6 +331,31 @@ explaining difference against previous submission (see See Documentation/process/email-clients.rst for recommendations on email clients and mailing list etiquette. +.. _interleaved_replies: + +Use trimmed interleaved replies in email discussions +---------------------------------------------------- +Top-posting is strongly discouraged in Linux kernel development +discussions. Interleaved (or "inline") replies make conversations much +easier to follow. For more details see: +https://en.wikipedia.org/wiki/Posting_style#Interleaved_style + +As is frequently quoted on the mailing list:: + + A: http://en.wikipedia.org/wiki/Top_post + Q: Were do I find info about this thing called top-posting? + A: Because it messes up the order in which people normally read text. + Q: Why is top-posting such a bad thing? + A: Top-posting. + Q: What is the most annoying thing in e-mail? + +Similarly, please trim all unneeded quotations that aren't relevant +to your reply. This makes responses easier to find, and saves time and +space. For more details see: http://daringfireball.net/2007/07/on_top :: + + A: No. + Q: Should I include quotations after my reply? + .. _resend_reminders: Don't get discouraged - or impatient diff --git a/Documentation/rust/quick-start.rst b/Documentation/rust/quick-start.rst index 13b7744b1e27..a8931512ed98 100644 --- a/Documentation/rust/quick-start.rst +++ b/Documentation/rust/quick-start.rst @@ -38,9 +38,9 @@ and run:: rustup override set $(scripts/min-tool-version.sh rustc) -Otherwise, fetch a standalone installer or install ``rustup`` from: +Otherwise, fetch a standalone installer from: - https://www.rust-lang.org + https://forge.rust-lang.org/infra/other-installation-methods.html#standalone Rust standard library source diff --git a/Documentation/scheduler/sched-deadline.rst b/Documentation/scheduler/sched-deadline.rst index 9d9be52f221a..9fe4846079bb 100644 --- a/Documentation/scheduler/sched-deadline.rst +++ b/Documentation/scheduler/sched-deadline.rst @@ -203,12 +203,15 @@ Deadline Task Scheduling - Total bandwidth (this_bw): this is the sum of all tasks "belonging" to the runqueue, including the tasks in Inactive state. + - Maximum usable bandwidth (max_bw): This is the maximum bandwidth usable by + deadline tasks and is currently set to the RT capacity. + The algorithm reclaims the bandwidth of the tasks in Inactive state. It does so by decrementing the runtime of the executing task Ti at a pace equal to - dq = -max{ Ui / Umax, (1 - Uinact - Uextra) } dt + dq = -(max{ Ui, (Umax - Uinact - Uextra) } / Umax) dt where: diff --git a/Documentation/subsystem-apis.rst b/Documentation/subsystem-apis.rst index b51f38527e14..02d6dc3a49c8 100644 --- a/Documentation/subsystem-apis.rst +++ b/Documentation/subsystem-apis.rst @@ -10,6 +10,30 @@ is taken directly from the kernel source, with supplemental material added as needed (or at least as we managed to add it — probably *not* all that is needed). +Human interfaces +---------------- + +.. toctree:: + :maxdepth: 1 + + input/index + hid/index + sound/index + gpu/index + fb/index + +Storage interfaces +------------------ + +.. toctree:: + :maxdepth: 1 + + filesystems/index + block/index + cdrom/index + scsi/index + target/index + **Fixme**: much more organizational work is needed here. .. toctree:: @@ -19,12 +43,8 @@ needed). core-api/index locking/index accounting/index - block/index - cdrom/index cpu-freq/index - fb/index fpga/index - hid/index i2c/index iio/index isdn/index @@ -34,25 +54,19 @@ needed). networking/index pcmcia/index power/index - target/index timers/index spi/index w1/index watchdog/index virt/index - input/index hwmon/index - gpu/index accel/index security/index - sound/index crypto/index - filesystems/index mm/index bpf/index usb/index PCI/index - scsi/index misc-devices/index scheduler/index mhi/index diff --git a/Documentation/translations/zh_CN/arm/Booting b/Documentation/translations/zh_CN/arch/arm/Booting index 5ecea0767893..f18585156b67 100644 --- a/Documentation/translations/zh_CN/arm/Booting +++ b/Documentation/translations/zh_CN/arch/arm/Booting @@ -1,4 +1,4 @@ -Chinese translated version of Documentation/arm/booting.rst +Chinese translated version of Documentation/arch/arm/booting.rst If you have any comment or update to the content, please contact the original document maintainer directly. However, if you have a problem @@ -9,7 +9,7 @@ or if there is a problem with the translation. Maintainer: Russell King <linux@arm.linux.org.uk> Chinese maintainer: Fu Wei <tekkamanninja@gmail.com> --------------------------------------------------------------------- -Documentation/arm/booting.rst 的中文翻译 +Documentation/arch/arm/booting.rst 的中文翻译 如果想评论或更新本文的内容，请直接联系原文档的维护者。如果你使用英文 交流有困难的话，也可以向中文版维护者求助。如果本翻译更新不及时或者翻 diff --git a/Documentation/translations/zh_CN/arm/kernel_user_helpers.txt b/Documentation/translations/zh_CN/arch/arm/kernel_user_helpers.txt index 99af4363984d..018eb7d54233 100644 --- a/Documentation/translations/zh_CN/arm/kernel_user_helpers.txt +++ b/Documentation/translations/zh_CN/arch/arm/kernel_user_helpers.txt @@ -1,4 +1,4 @@ -Chinese translated version of Documentation/arm/kernel_user_helpers.rst +Chinese translated version of Documentation/arch/arm/kernel_user_helpers.rst If you have any comment or update to the content, please contact the original document maintainer directly. However, if you have a problem @@ -10,7 +10,7 @@ Maintainer: Nicolas Pitre <nicolas.pitre@linaro.org> Dave Martin <dave.martin@linaro.org> Chinese maintainer: Fu Wei <tekkamanninja@gmail.com> --------------------------------------------------------------------- -Documentation/arm/kernel_user_helpers.rst 的中文翻译 +Documentation/arch/arm/kernel_user_helpers.rst 的中文翻译 如果想评论或更新本文的内容，请直接联系原文档的维护者。如果你使用英文 交流有困难的话，也可以向中文版维护者求助。如果本翻译更新不及时或者翻 diff --git a/Documentation/translations/zh_CN/arm64/amu.rst b/Documentation/translations/zh_CN/arch/arm64/amu.rst index ab7180f91394..f8e09fd21ef5 100644 --- a/Documentation/translations/zh_CN/arm64/amu.rst +++ b/Documentation/translations/zh_CN/arch/arm64/amu.rst @@ -1,6 +1,6 @@ -.. include:: ../disclaimer-zh_CN.rst +.. include:: ../../disclaimer-zh_CN.rst -:Original: :ref:`Documentation/arm64/amu.rst <amu_index>` +:Original: :ref:`Documentation/arch/arm64/amu.rst <amu_index>` Translator: Bailu Lin <bailu.lin@vivo.com> diff --git a/Documentation/translations/zh_CN/arm64/booting.txt b/Documentation/translations/zh_CN/arch/arm64/booting.txt index 5b0164132c71..630eb32a8854 100644 --- a/Documentation/translations/zh_CN/arm64/booting.txt +++ b/Documentation/translations/zh_CN/arch/arm64/booting.txt @@ -1,4 +1,4 @@ -Chinese translated version of Documentation/arm64/booting.rst +Chinese translated version of Documentation/arch/arm64/booting.rst If you have any comment or update to the content, please contact the original document maintainer directly. However, if you have a problem @@ -10,7 +10,7 @@ M: Will Deacon <will.deacon@arm.com> zh_CN: Fu Wei <wefu@redhat.com> C: 55f058e7574c3615dea4615573a19bdb258696c6 --------------------------------------------------------------------- -Documentation/arm64/booting.rst 的中文翻译 +Documentation/arch/arm64/booting.rst 的中文翻译 如果想评论或更新本文的内容，请直接联系原文档的维护者。如果你使用英文 交流有困难的话，也可以向中文版维护者求助。如果本翻译更新不及时或者翻 diff --git a/Documentation/translations/zh_CN/arm64/elf_hwcaps.rst b/Documentation/translations/zh_CN/arch/arm64/elf_hwcaps.rst index 9aa4637eac97..f60ac1580d3e 100644 --- a/Documentation/translations/zh_CN/arm64/elf_hwcaps.rst +++ b/Documentation/translations/zh_CN/arch/arm64/elf_hwcaps.rst @@ -1,6 +1,6 @@ -.. include:: ../disclaimer-zh_CN.rst +.. include:: ../../disclaimer-zh_CN.rst -:Original: :ref:`Documentation/arm64/elf_hwcaps.rst <elf_hwcaps_index>` +:Original: :ref:`Documentation/arch/arm64/elf_hwcaps.rst <elf_hwcaps_index>` Translator: Bailu Lin <bailu.lin@vivo.com> @@ -92,7 +92,7 @@ HWCAP_ASIMDHP ID_AA64PFR0_EL1.AdvSIMD == 0b0001 表示有此功能。 HWCAP_CPUID - 根据 Documentation/arm64/cpu-feature-registers.rst 描述，EL0 可以访问 + 根据 Documentation/arch/arm64/cpu-feature-registers.rst 描述，EL0 可以访问 某些 ID 寄存器。 这些 ID 寄存器可能表示功能的可用性。 @@ -152,12 +152,12 @@ HWCAP_SB ID_AA64ISAR1_EL1.SB == 0b0001 表示有此功能。 HWCAP_PACA - 如 Documentation/arm64/pointer-authentication.rst 所描述， + 如 Documentation/arch/arm64/pointer-authentication.rst 所描述， ID_AA64ISAR1_EL1.APA == 0b0001 或 ID_AA64ISAR1_EL1.API == 0b0001 表示有此功能。 HWCAP_PACG - 如 Documentation/arm64/pointer-authentication.rst 所描述， + 如 Documentation/arch/arm64/pointer-authentication.rst 所描述， ID_AA64ISAR1_EL1.GPA == 0b0001 或 ID_AA64ISAR1_EL1.GPI == 0b0001 表示有此功能。 diff --git a/Documentation/translations/zh_CN/arm64/hugetlbpage.rst b/Documentation/translations/zh_CN/arch/arm64/hugetlbpage.rst index 13304d269d0b..8079eadde29a 100644 --- a/Documentation/translations/zh_CN/arm64/hugetlbpage.rst +++ b/Documentation/translations/zh_CN/arch/arm64/hugetlbpage.rst @@ -1,6 +1,6 @@ -.. include:: ../disclaimer-zh_CN.rst +.. include:: ../../disclaimer-zh_CN.rst -:Original: :ref:`Documentation/arm64/hugetlbpage.rst <hugetlbpage_index>` +:Original: :ref:`Documentation/arch/arm64/hugetlbpage.rst <hugetlbpage_index>` Translator: Bailu Lin <bailu.lin@vivo.com> diff --git a/Documentation/translations/zh_CN/arm64/index.rst b/Documentation/translations/zh_CN/arch/arm64/index.rst index 57dc5de5ccc5..e12b9f6e5d6c 100644 --- a/Documentation/translations/zh_CN/arm64/index.rst +++ b/Documentation/translations/zh_CN/arch/arm64/index.rst @@ -1,6 +1,6 @@ -.. include:: ../disclaimer-zh_CN.rst +.. include:: ../../disclaimer-zh_CN.rst -:Original: :ref:`Documentation/arm64/index.rst <arm64_index>` +:Original: :ref:`Documentation/arch/arm64/index.rst <arm64_index>` :Translator: Bailu Lin <bailu.lin@vivo.com> .. _cn_arm64_index: diff --git a/Documentation/translations/zh_CN/arm64/legacy_instructions.txt b/Documentation/translations/zh_CN/arch/arm64/legacy_instructions.txt index e295cf75f606..e469fccbe356 100644 --- a/Documentation/translations/zh_CN/arm64/legacy_instructions.txt +++ b/Documentation/translations/zh_CN/arch/arm64/legacy_instructions.txt @@ -1,4 +1,4 @@ -Chinese translated version of Documentation/arm64/legacy_instructions.rst +Chinese translated version of Documentation/arch/arm64/legacy_instructions.rst If you have any comment or update to the content, please contact the original document maintainer directly. However, if you have a problem @@ -10,7 +10,7 @@ Maintainer: Punit Agrawal <punit.agrawal@arm.com> Suzuki K. Poulose <suzuki.poulose@arm.com> Chinese maintainer: Fu Wei <wefu@redhat.com> --------------------------------------------------------------------- -Documentation/arm64/legacy_instructions.rst 的中文翻译 +Documentation/arch/arm64/legacy_instructions.rst 的中文翻译 如果想评论或更新本文的内容，请直接联系原文档的维护者。如果你使用英文 交流有困难的话，也可以向中文版维护者求助。如果本翻译更新不及时或者翻 diff --git a/Documentation/translations/zh_CN/arm64/memory.txt b/Documentation/translations/zh_CN/arch/arm64/memory.txt index be20f8228b91..c6962e9cb9f8 100644 --- a/Documentation/translations/zh_CN/arm64/memory.txt +++ b/Documentation/translations/zh_CN/arch/arm64/memory.txt @@ -1,4 +1,4 @@ -Chinese translated version of Documentation/arm64/memory.rst +Chinese translated version of Documentation/arch/arm64/memory.rst If you have any comment or update to the content, please contact the original document maintainer directly. However, if you have a problem @@ -9,7 +9,7 @@ or if there is a problem with the translation. Maintainer: Catalin Marinas <catalin.marinas@arm.com> Chinese maintainer: Fu Wei <wefu@redhat.com> --------------------------------------------------------------------- -Documentation/arm64/memory.rst 的中文翻译 +Documentation/arch/arm64/memory.rst 的中文翻译 如果想评论或更新本文的内容，请直接联系原文档的维护者。如果你使用英文 交流有困难的话，也可以向中文版维护者求助。如果本翻译更新不及时或者翻 diff --git a/Documentation/translations/zh_CN/arm64/perf.rst b/Documentation/translations/zh_CN/arch/arm64/perf.rst index 9bf21d73f4d1..6be72704e659 100644 --- a/Documentation/translations/zh_CN/arm64/perf.rst +++ b/Documentation/translations/zh_CN/arch/arm64/perf.rst @@ -1,8 +1,8 @@ .. SPDX-License-Identifier: GPL-2.0 -.. include:: ../disclaimer-zh_CN.rst +.. include:: ../../disclaimer-zh_CN.rst -:Original: :ref:`Documentation/arm64/perf.rst <perf_index>` +:Original: :ref:`Documentation/arch/arm64/perf.rst <perf_index>` Translator: Bailu Lin <bailu.lin@vivo.com> diff --git a/Documentation/translations/zh_CN/arm64/silicon-errata.txt b/Documentation/translations/zh_CN/arch/arm64/silicon-errata.txt index 440c59ac7dce..f4767ffdd61d 100644 --- a/Documentation/translations/zh_CN/arm64/silicon-errata.txt +++ b/Documentation/translations/zh_CN/arch/arm64/silicon-errata.txt @@ -1,4 +1,4 @@ -Chinese translated version of Documentation/arm64/silicon-errata.rst +Chinese translated version of Documentation/arch/arm64/silicon-errata.rst If you have any comment or update to the content, please contact the original document maintainer directly. However, if you have a problem @@ -10,7 +10,7 @@ M: Will Deacon <will.deacon@arm.com> zh_CN: Fu Wei <wefu@redhat.com> C: 1926e54f115725a9248d0c4c65c22acaf94de4c4 --------------------------------------------------------------------- -Documentation/arm64/silicon-errata.rst 的中文翻译 +Documentation/arch/arm64/silicon-errata.rst 的中文翻译 如果想评论或更新本文的内容，请直接联系原文档的维护者。如果你使用英文 交流有困难的话，也可以向中文版维护者求助。如果本翻译更新不及时或者翻 diff --git a/Documentation/translations/zh_CN/arm64/tagged-pointers.txt b/Documentation/translations/zh_CN/arch/arm64/tagged-pointers.txt index 77ac3548a16d..27577c3c5e3f 100644 --- a/Documentation/translations/zh_CN/arm64/tagged-pointers.txt +++ b/Documentation/translations/zh_CN/arch/arm64/tagged-pointers.txt @@ -1,4 +1,4 @@ -Chinese translated version of Documentation/arm64/tagged-pointers.rst +Chinese translated version of Documentation/arch/arm64/tagged-pointers.rst If you have any comment or update to the content, please contact the original document maintainer directly. However, if you have a problem @@ -9,7 +9,7 @@ or if there is a problem with the translation. Maintainer: Will Deacon <will.deacon@arm.com> Chinese maintainer: Fu Wei <wefu@redhat.com> --------------------------------------------------------------------- -Documentation/arm64/tagged-pointers.rst 的中文翻译 +Documentation/arch/arm64/tagged-pointers.rst 的中文翻译 如果想评论或更新本文的内容，请直接联系原文档的维护者。如果你使用英文 交流有困难的话，也可以向中文版维护者求助。如果本翻译更新不及时或者翻 diff --git a/Documentation/translations/zh_CN/arch/index.rst b/Documentation/translations/zh_CN/arch/index.rst index 908ea131bb1c..6fa0cb671009 100644 --- a/Documentation/translations/zh_CN/arch/index.rst +++ b/Documentation/translations/zh_CN/arch/index.rst @@ -9,7 +9,7 @@ :maxdepth: 2 ../mips/index - ../arm64/index + arm64/index ../riscv/index openrisc/index parisc/index diff --git a/Documentation/translations/zh_CN/mm/page_migration.rst b/Documentation/translations/zh_CN/mm/page_migration.rst index 076081dc1635..f95063826a15 100644 --- a/Documentation/translations/zh_CN/mm/page_migration.rst +++ b/Documentation/translations/zh_CN/mm/page_migration.rst @@ -55,7 +55,7 @@ mbind()设置一个新的内存策略。一个进程的页面也可以通过sys_ 消失。它还可以防止交换器或其他扫描器遇到该页。 -2. 我们需要有一个new_page_t类型的函数，可以传递给migrate_pages()。这个函数应该计算 +2. 我们需要有一个new_folio_t类型的函数，可以传递给migrate_pages()。这个函数应该计算 出如何在给定的旧页面中分配正确的新页面。 3. migrate_pages()函数被调用，它试图进行迁移。它将调用该函数为每个被考虑迁移的页面分 diff --git a/Documentation/translations/zh_TW/arm64/amu.rst b/Documentation/translations/zh_TW/arch/arm64/amu.rst index ffdc466e0f62..f947a6c7369f 100644 --- a/Documentation/translations/zh_TW/arm64/amu.rst +++ b/Documentation/translations/zh_TW/arch/arm64/amu.rst @@ -1,8 +1,8 @@ .. SPDX-License-Identifier: GPL-2.0 -.. include:: ../disclaimer-zh_TW.rst +.. include:: ../../disclaimer-zh_TW.rst -:Original: :ref:`Documentation/arm64/amu.rst <amu_index>` +:Original: :ref:`Documentation/arch/arm64/amu.rst <amu_index>` Translator: Bailu Lin <bailu.lin@vivo.com> Hu Haowen <src.res@email.cn> diff --git a/Documentation/translations/zh_TW/arm64/booting.txt b/Documentation/translations/zh_TW/arch/arm64/booting.txt index b9439dd54012..24817b8b70cd 100644 --- a/Documentation/translations/zh_TW/arm64/booting.txt +++ b/Documentation/translations/zh_TW/arch/arm64/booting.txt @@ -1,6 +1,6 @@ SPDX-License-Identifier: GPL-2.0 -Chinese translated version of Documentation/arm64/booting.rst +Chinese translated version of Documentation/arch/arm64/booting.rst If you have any comment or update to the content, please contact the original document maintainer directly. However, if you have a problem @@ -13,7 +13,7 @@ zh_CN: Fu Wei <wefu@redhat.com> zh_TW: Hu Haowen <src.res@email.cn> C: 55f058e7574c3615dea4615573a19bdb258696c6 --------------------------------------------------------------------- -Documentation/arm64/booting.rst 的中文翻譯 +Documentation/arch/arm64/booting.rst 的中文翻譯 如果想評論或更新本文的內容，請直接聯繫原文檔的維護者。如果你使用英文 交流有困難的話，也可以向中文版維護者求助。如果本翻譯更新不及時或者翻 diff --git a/Documentation/translations/zh_TW/arm64/elf_hwcaps.rst b/Documentation/translations/zh_TW/arch/arm64/elf_hwcaps.rst index 3eb1c623ce31..fca3c6ff7b93 100644 --- a/Documentation/translations/zh_TW/arm64/elf_hwcaps.rst +++ b/Documentation/translations/zh_TW/arch/arm64/elf_hwcaps.rst @@ -1,8 +1,8 @@ .. SPDX-License-Identifier: GPL-2.0 -.. include:: ../disclaimer-zh_TW.rst +.. include:: ../../disclaimer-zh_TW.rst -:Original: :ref:`Documentation/arm64/elf_hwcaps.rst <elf_hwcaps_index>` +:Original: :ref:`Documentation/arch/arm64/elf_hwcaps.rst <elf_hwcaps_index>` Translator: Bailu Lin <bailu.lin@vivo.com> Hu Haowen <src.res@email.cn> @@ -95,7 +95,7 @@ HWCAP_ASIMDHP ID_AA64PFR0_EL1.AdvSIMD == 0b0001 表示有此功能。 HWCAP_CPUID - 根據 Documentation/arm64/cpu-feature-registers.rst 描述，EL0 可以訪問 + 根據 Documentation/arch/arm64/cpu-feature-registers.rst 描述，EL0 可以訪問 某些 ID 寄存器。 這些 ID 寄存器可能表示功能的可用性。 @@ -155,12 +155,12 @@ HWCAP_SB ID_AA64ISAR1_EL1.SB == 0b0001 表示有此功能。 HWCAP_PACA - 如 Documentation/arm64/pointer-authentication.rst 所描述， + 如 Documentation/arch/arm64/pointer-authentication.rst 所描述， ID_AA64ISAR1_EL1.APA == 0b0001 或 ID_AA64ISAR1_EL1.API == 0b0001 表示有此功能。 HWCAP_PACG - 如 Documentation/arm64/pointer-authentication.rst 所描述， + 如 Documentation/arch/arm64/pointer-authentication.rst 所描述， ID_AA64ISAR1_EL1.GPA == 0b0001 或 ID_AA64ISAR1_EL1.GPI == 0b0001 表示有此功能。 diff --git a/Documentation/translations/zh_TW/arm64/hugetlbpage.rst b/Documentation/translations/zh_TW/arch/arm64/hugetlbpage.rst index 846b500dae97..10feb329dfb8 100644 --- a/Documentation/translations/zh_TW/arm64/hugetlbpage.rst +++ b/Documentation/translations/zh_TW/arch/arm64/hugetlbpage.rst @@ -1,8 +1,8 @@ .. SPDX-License-Identifier: GPL-2.0 -.. include:: ../disclaimer-zh_TW.rst +.. include:: ../../disclaimer-zh_TW.rst -:Original: :ref:`Documentation/arm64/hugetlbpage.rst <hugetlbpage_index>` +:Original: :ref:`Documentation/arch/arm64/hugetlbpage.rst <hugetlbpage_index>` Translator: Bailu Lin <bailu.lin@vivo.com> Hu Haowen <src.res@email.cn> diff --git a/Documentation/translations/zh_TW/arm64/index.rst b/Documentation/translations/zh_TW/arch/arm64/index.rst index 2322783f3881..68befee14b99 100644 --- a/Documentation/translations/zh_TW/arm64/index.rst +++ b/Documentation/translations/zh_TW/arch/arm64/index.rst @@ -1,8 +1,8 @@ .. SPDX-License-Identifier: GPL-2.0 -.. include:: ../disclaimer-zh_TW.rst +.. include:: ../../disclaimer-zh_TW.rst -:Original: :ref:`Documentation/arm64/index.rst <arm64_index>` +:Original: :ref:`Documentation/arch/arm64/index.rst <arm64_index>` :Translator: Bailu Lin <bailu.lin@vivo.com> Hu Haowen <src.res@email.cn> diff --git a/Documentation/translations/zh_TW/arm64/legacy_instructions.txt b/Documentation/translations/zh_TW/arch/arm64/legacy_instructions.txt index 6d4454f77b9e..3c915df9836c 100644 --- a/Documentation/translations/zh_TW/arm64/legacy_instructions.txt +++ b/Documentation/translations/zh_TW/arch/arm64/legacy_instructions.txt @@ -1,6 +1,6 @@ SPDX-License-Identifier: GPL-2.0 -Chinese translated version of Documentation/arm64/legacy_instructions.rst +Chinese translated version of Documentation/arch/arm64/legacy_instructions.rst If you have any comment or update to the content, please contact the original document maintainer directly. However, if you have a problem @@ -13,7 +13,7 @@ Maintainer: Punit Agrawal <punit.agrawal@arm.com> Chinese maintainer: Fu Wei <wefu@redhat.com> Traditional Chinese maintainer: Hu Haowen <src.res@email.cn> --------------------------------------------------------------------- -Documentation/arm64/legacy_instructions.rst 的中文翻譯 +Documentation/arch/arm64/legacy_instructions.rst 的中文翻譯 如果想評論或更新本文的內容，請直接聯繫原文檔的維護者。如果你使用英文 交流有困難的話，也可以向中文版維護者求助。如果本翻譯更新不及時或者翻 diff --git a/Documentation/translations/zh_TW/arm64/memory.txt b/Documentation/translations/zh_TW/arch/arm64/memory.txt index 99c2b78b5674..2437380a26d8 100644 --- a/Documentation/translations/zh_TW/arm64/memory.txt +++ b/Documentation/translations/zh_TW/arch/arm64/memory.txt @@ -1,6 +1,6 @@ SPDX-License-Identifier: GPL-2.0 -Chinese translated version of Documentation/arm64/memory.rst +Chinese translated version of Documentation/arch/arm64/memory.rst If you have any comment or update to the content, please contact the original document maintainer directly. However, if you have a problem @@ -12,7 +12,7 @@ Maintainer: Catalin Marinas <catalin.marinas@arm.com> Chinese maintainer: Fu Wei <wefu@redhat.com> Traditional Chinese maintainer: Hu Haowen <src.res@email.cn> --------------------------------------------------------------------- -Documentation/arm64/memory.rst 的中文翻譯 +Documentation/arch/arm64/memory.rst 的中文翻譯 如果想評論或更新本文的內容，請直接聯繫原文檔的維護者。如果你使用英文 交流有困難的話，也可以向中文版維護者求助。如果本翻譯更新不及時或者翻 diff --git a/Documentation/translations/zh_TW/arm64/perf.rst b/Documentation/translations/zh_TW/arch/arm64/perf.rst index f1ffd55dfe50..3b39997a52eb 100644 --- a/Documentation/translations/zh_TW/arm64/perf.rst +++ b/Documentation/translations/zh_TW/arch/arm64/perf.rst @@ -1,8 +1,8 @@ .. SPDX-License-Identifier: GPL-2.0 -.. include:: ../disclaimer-zh_TW.rst +.. include:: ../../disclaimer-zh_TW.rst -:Original: :ref:`Documentation/arm64/perf.rst <perf_index>` +:Original: :ref:`Documentation/arch/arm64/perf.rst <perf_index>` Translator: Bailu Lin <bailu.lin@vivo.com> Hu Haowen <src.res@email.cn> diff --git a/Documentation/translations/zh_TW/arm64/silicon-errata.txt b/Documentation/translations/zh_TW/arch/arm64/silicon-errata.txt index bf2077197504..66c3a3506458 100644 --- a/Documentation/translations/zh_TW/arm64/silicon-errata.txt +++ b/Documentation/translations/zh_TW/arch/arm64/silicon-errata.txt @@ -1,6 +1,6 @@ SPDX-License-Identifier: GPL-2.0 -Chinese translated version of Documentation/arm64/silicon-errata.rst +Chinese translated version of Documentation/arch/arm64/silicon-errata.rst If you have any comment or update to the content, please contact the original document maintainer directly. However, if you have a problem @@ -13,7 +13,7 @@ zh_CN: Fu Wei <wefu@redhat.com> zh_TW: Hu Haowen <src.res@email.cn> C: 1926e54f115725a9248d0c4c65c22acaf94de4c4 --------------------------------------------------------------------- -Documentation/arm64/silicon-errata.rst 的中文翻譯 +Documentation/arch/arm64/silicon-errata.rst 的中文翻譯 如果想評論或更新本文的內容，請直接聯繫原文檔的維護者。如果你使用英文 交流有困難的話，也可以向中文版維護者求助。如果本翻譯更新不及時或者翻 diff --git a/Documentation/translations/zh_TW/arm64/tagged-pointers.txt b/Documentation/translations/zh_TW/arch/arm64/tagged-pointers.txt index 87f88628401a..b7f683f20ed1 100644 --- a/Documentation/translations/zh_TW/arm64/tagged-pointers.txt +++ b/Documentation/translations/zh_TW/arch/arm64/tagged-pointers.txt @@ -1,6 +1,6 @@ SPDX-License-Identifier: GPL-2.0 -Chinese translated version of Documentation/arm64/tagged-pointers.rst +Chinese translated version of Documentation/arch/arm64/tagged-pointers.rst If you have any comment or update to the content, please contact the original document maintainer directly. However, if you have a problem @@ -12,7 +12,7 @@ Maintainer: Will Deacon <will.deacon@arm.com> Chinese maintainer: Fu Wei <wefu@redhat.com> Traditional Chinese maintainer: Hu Haowen <src.res@email.cn> --------------------------------------------------------------------- -Documentation/arm64/tagged-pointers.rst 的中文翻譯 +Documentation/arch/arm64/tagged-pointers.rst 的中文翻譯 如果想評論或更新本文的內容，請直接聯繫原文檔的維護者。如果你使用英文 交流有困難的話，也可以向中文版維護者求助。如果本翻譯更新不及時或者翻 diff --git a/Documentation/translations/zh_TW/index.rst b/Documentation/translations/zh_TW/index.rst index e97d7d578751..e7c83868e780 100644 --- a/Documentation/translations/zh_TW/index.rst +++ b/Documentation/translations/zh_TW/index.rst @@ -150,7 +150,7 @@ TODOList: .. toctree:: :maxdepth: 2 - arm64/index + arch/arm64/index TODOList: diff --git a/Documentation/virt/guest-halt-polling.rst b/Documentation/virt/guest-halt-polling.rst index b4e747942417..922291ddc40c 100644 --- a/Documentation/virt/guest-halt-polling.rst +++ b/Documentation/virt/guest-halt-polling.rst @@ -72,7 +72,7 @@ high once achieves global guest_halt_poll_ns value). Default: Y -The module parameters can be set from the debugfs files in:: +The module parameters can be set from the sysfs files in:: /sys/module/haltpoll/parameters/ diff --git a/Documentation/virt/kvm/api.rst b/Documentation/virt/kvm/api.rst index add067793b90..96c4475539c2 100644 --- a/Documentation/virt/kvm/api.rst +++ b/Documentation/virt/kvm/api.rst @@ -2613,7 +2613,7 @@ follows:: this vcpu, and determines which register slices are visible through this ioctl interface. -(See Documentation/arm64/sve.rst for an explanation of the "vq" +(See Documentation/arch/arm64/sve.rst for an explanation of the "vq" nomenclature.) KVM_REG_ARM64_SVE_VLS is only accessible after KVM_ARM_VCPU_INIT. diff --git a/Documentation/virt/kvm/halt-polling.rst b/Documentation/virt/kvm/halt-polling.rst index 3fae39b1a5ba..4f1a1b23d99c 100644 --- a/Documentation/virt/kvm/halt-polling.rst +++ b/Documentation/virt/kvm/halt-polling.rst @@ -112,11 +112,11 @@ powerpc kvm-hv case. | | function. | | +-----------------------+---------------------------+-------------------------+ -These module parameters can be set from the debugfs files in: +These module parameters can be set from the sysfs files in: /sys/module/kvm/parameters/ -Note: that these module parameters are system wide values and are not able to +Note: these module parameters are system-wide values and are not able to be tuned on a per vm basis. Any changes to these parameters will be picked up by new and existing vCPUs the @@ -142,12 +142,12 @@ Further Notes global max polling interval (halt_poll_ns) then the host will always poll for the entire block time and thus cpu utilisation will go to 100%. -- Halt polling essentially presents a trade off between power usage and latency and +- Halt polling essentially presents a trade-off between power usage and latency and the module parameters should be used to tune the affinity for this. Idle cpu time is essentially converted to host kernel time with the aim of decreasing latency when entering the guest. - Halt polling will only be conducted by the host when no other tasks are runnable on that cpu, otherwise the polling will cease immediately and schedule will be invoked to - allow that other task to run. Thus this doesn't allow a guest to denial of service the - cpu. + allow that other task to run. Thus this doesn't allow a guest to cause denial of service + of the cpu. diff --git a/Documentation/virt/kvm/locking.rst b/Documentation/virt/kvm/locking.rst index 8c77554e4896..3a034db5e55f 100644 --- a/Documentation/virt/kvm/locking.rst +++ b/Documentation/virt/kvm/locking.rst @@ -67,7 +67,7 @@ following two cases: 2. Write-Protection: The SPTE is present and the fault is caused by write-protect. That means we just need to change the W bit of the spte. -What we use to avoid all the race is the Host-writable bit and MMU-writable bit +What we use to avoid all the races is the Host-writable bit and MMU-writable bit on the spte: - Host-writable means the gfn is writable in the host kernel page tables and in @@ -130,7 +130,7 @@ to gfn. For indirect sp, we disabled fast page fault for simplicity. A solution for indirect sp could be to pin the gfn, for example via kvm_vcpu_gfn_to_pfn_atomic, before the cmpxchg. After the pinning: -- We have held the refcount of pfn that means the pfn can not be freed and +- We have held the refcount of pfn; that means the pfn can not be freed and be reused for another gfn. - The pfn is writable and therefore it cannot be shared between different gfns by KSM. @@ -186,22 +186,22 @@ writable between reading spte and updating spte. Like below case: The Dirty bit is lost in this case. In order to avoid this kind of issue, we always treat the spte as "volatile" -if it can be updated out of mmu-lock, see spte_has_volatile_bits(), it means, +if it can be updated out of mmu-lock [see spte_has_volatile_bits()]; it means the spte is always atomically updated in this case. 3) flush tlbs due to spte updated -If the spte is updated from writable to readonly, we should flush all TLBs, +If the spte is updated from writable to read-only, we should flush all TLBs, otherwise rmap_write_protect will find a read-only spte, even though the writable spte might be cached on a CPU's TLB. As mentioned before, the spte can be updated to writable out of mmu-lock on -fast page fault path, in order to easily audit the path, we see if TLBs need -be flushed caused by this reason in mmu_spte_update() since this is a common +fast page fault path. In order to easily audit the path, we see if TLBs needing +to be flushed caused this reason in mmu_spte_update() since this is a common function to update spte (present -> present). Since the spte is "volatile" if it can be updated out of mmu-lock, we always -atomically update the spte, the race caused by fast page fault can be avoided, +atomically update the spte and the race caused by fast page fault can be avoided. See the comments in spte_has_volatile_bits() and mmu_spte_update(). Lockless Access Tracking: @@ -283,9 +283,9 @@ time it will be set using the Dirty tracking mechanism described above. :Arch: x86 :Protects: wakeup_vcpus_on_cpu :Comment: This is a per-CPU lock and it is used for VT-d posted-interrupts. - When VT-d posted-interrupts is supported and the VM has assigned + When VT-d posted-interrupts are supported and the VM has assigned devices, we put the blocked vCPU on the list blocked_vcpu_on_cpu - protected by blocked_vcpu_on_cpu_lock, when VT-d hardware issues + protected by blocked_vcpu_on_cpu_lock. When VT-d hardware issues wakeup notification event since external interrupts from the assigned devices happens, we will find the vCPU on the list to wakeup. diff --git a/Documentation/virt/kvm/ppc-pv.rst b/Documentation/virt/kvm/ppc-pv.rst index 5fdb907670be..740d03d25300 100644 --- a/Documentation/virt/kvm/ppc-pv.rst +++ b/Documentation/virt/kvm/ppc-pv.rst @@ -89,7 +89,7 @@ also define a new hypercall feature to indicate that the host can give you more registers. Only if the host supports the additional features, make use of them. The magic page layout is described by struct kvm_vcpu_arch_shared -in arch/powerpc/include/asm/kvm_para.h. +in arch/powerpc/include/uapi/asm/kvm_para.h. Magic page features =================== @@ -112,7 +112,7 @@ Magic page flags ================ In addition to features that indicate whether a host is capable of a particular -feature we also have a channel for a guest to tell the guest whether it's capable +feature we also have a channel for a guest to tell the host whether it's capable of something. This is what we call "flags". Flags are passed to the host in the low 12 bits of the Effective Address. @@ -139,7 +139,7 @@ Patched instructions ==================== The "ld" and "std" instructions are transformed to "lwz" and "stw" instructions -respectively on 32 bit systems with an added offset of 4 to accommodate for big +respectively on 32-bit systems with an added offset of 4 to accommodate for big endianness. The following is a list of mapping the Linux kernel performs when running as @@ -210,7 +210,7 @@ available on all targets. 2) PAPR hypercalls PAPR hypercalls are needed to run server PowerPC PAPR guests (-M pseries in QEMU). -These are the same hypercalls that pHyp, the POWER hypervisor implements. Some of +These are the same hypercalls that pHyp, the POWER hypervisor, implements. Some of them are handled in the kernel, some are handled in user space. This is only available on book3s_64. diff --git a/Documentation/virt/kvm/vcpu-requests.rst b/Documentation/virt/kvm/vcpu-requests.rst index 87f04c1fa53d..06718b9bc959 100644 --- a/Documentation/virt/kvm/vcpu-requests.rst +++ b/Documentation/virt/kvm/vcpu-requests.rst @@ -101,7 +101,7 @@ also be used, e.g. :: However, VCPU request users should refrain from doing so, as it would break the abstraction. The first 8 bits are reserved for architecture -independent requests, all additional bits are available for architecture +independent requests; all additional bits are available for architecture dependent requests. Architecture Independent Requests @@ -151,8 +151,8 @@ KVM_REQUEST_NO_WAKEUP This flag is applied to requests that only need immediate attention from VCPUs running in guest mode. That is, sleeping VCPUs do not need - to be awaken for these requests. Sleeping VCPUs will handle the - requests when they are awaken later for some other reason. + to be awakened for these requests. Sleeping VCPUs will handle the + requests when they are awakened later for some other reason. KVM_REQUEST_WAIT diff --git a/Documentation/virt/paravirt_ops.rst b/Documentation/virt/paravirt_ops.rst index 6b789d27cead..62d867e0d4d6 100644 --- a/Documentation/virt/paravirt_ops.rst +++ b/Documentation/virt/paravirt_ops.rst @@ -5,31 +5,31 @@ Paravirt_ops ============ Linux provides support for different hypervisor virtualization technologies. -Historically different binary kernels would be required in order to support -different hypervisors, this restriction was removed with pv_ops. +Historically, different binary kernels would be required in order to support +different hypervisors; this restriction was removed with pv_ops. Linux pv_ops is a virtualization API which enables support for different hypervisors. It allows each hypervisor to override critical operations and allows a single kernel binary to run on all supported execution environments including native machine -- without any hypervisors. pv_ops provides a set of function pointers which represent operations -corresponding to low level critical instructions and high level -functionalities in various areas. pv-ops allows for optimizations at run -time by enabling binary patching of the low-ops critical operations +corresponding to low-level critical instructions and high-level +functionalities in various areas. pv_ops allows for optimizations at run +time by enabling binary patching of the low-level critical operations at boot time. pv_ops operations are classified into three categories: - simple indirect call - These operations correspond to high level functionality where it is + These operations correspond to high-level functionality where it is known that the overhead of indirect call isn't very important. - indirect call which allows optimization with binary patch - Usually these operations correspond to low level critical instructions. They + Usually these operations correspond to low-level critical instructions. They are called frequently and are performance critical. The overhead is very important. - a set of macros for hand written assembly code Hand written assembly codes (.S files) also need paravirtualization - because they include sensitive instructions or some of code paths in + because they include sensitive instructions or some code paths in them are very performance critical. |