From: Linus Torvalds Date: Sun, 12 Sep 2021 17:43:51 +0000 (-0700) Subject: Merge branch 'misc.namei' of git://git.kernel.org/pub/scm/linux/kernel/git/viro/vfs X-Git-Tag: microblaze-v5.16~11 X-Git-Url: http://git.monstr.eu/?p=linux-2.6-microblaze.git;a=commitdiff_plain;h=fdfc346302a7b63e3d5b9168be74bb12b1975999;hp=ea47ab111669b187808b3080602788dec26cb9bc Merge branch 'misc.namei' of git://git./linux/kernel/git/viro/vfs Pull namei updates from Al Viro: "Clearing fallout from mkdirat in io_uring series. The fix in the kern_path_locked() patch plus associated cleanups" * 'misc.namei' of git://git.kernel.org/pub/scm/linux/kernel/git/viro/vfs: putname(): IS_ERR_OR_NULL() is wrong here namei: Standardize callers of filename_create() namei: Standardize callers of filename_lookup() rename __filename_parentat() to filename_parentat() namei: Fix use after free in kern_path_locked --- diff --git a/Documentation/ABI/stable/sysfs-driver-dma-idxd b/Documentation/ABI/stable/sysfs-driver-dma-idxd index d431e2d00472..df4afbccf037 100644 --- a/Documentation/ABI/stable/sysfs-driver-dma-idxd +++ b/Documentation/ABI/stable/sysfs-driver-dma-idxd @@ -128,6 +128,8 @@ Date: Aug 28, 2020 KernelVersion: 5.10.0 Contact: dmaengine@vger.kernel.org Description: The last executed device administrative command's status/error. + Also last configuration error overloaded. + Writing to it will clear the status. What: /sys/bus/dsa/devices/wq./block_on_fault Date: Oct 27, 2020 @@ -211,6 +213,13 @@ Contact: dmaengine@vger.kernel.org Description: Indicate whether ATS disable is turned on for the workqueue. 0 indicates ATS is on, and 1 indicates ATS is off for the workqueue. +What: /sys/bus/dsa/devices/wq./occupancy +Date May 25, 2021 +KernelVersion: 5.14.0 +Contact: dmaengine@vger.kernel.org +Description: Show the current number of entries in this WQ if WQ Occupancy + Support bit WQ capabilities is 1. + What: /sys/bus/dsa/devices/engine./group_id Date: Oct 25, 2019 KernelVersion: 5.6.0 diff --git a/Documentation/ABI/testing/debugfs-driver-habanalabs b/Documentation/ABI/testing/debugfs-driver-habanalabs index a5c28f606865..284e2dfa61cd 100644 --- a/Documentation/ABI/testing/debugfs-driver-habanalabs +++ b/Documentation/ABI/testing/debugfs-driver-habanalabs @@ -215,6 +215,17 @@ Description: Sets the skip reset on timeout option for the device. Value of "0" means device will be reset in case some CS has timed out, otherwise it will not be reset. +What: /sys/kernel/debug/habanalabs/hl/state_dump +Date: Oct 2021 +KernelVersion: 5.15 +Contact: ynudelman@habana.ai +Description: Gets the state dump occurring on a CS timeout or failure. + State dump is used for debug and is created each time in case of + a problem in a CS execution, before reset. + Reading from the node returns the newest state dump available. + Writing an integer X discards X state dumps, so that the + next read would return X+1-st newest state dump. + What: /sys/kernel/debug/habanalabs/hl/stop_on_err Date: Mar 2020 KernelVersion: 5.6 @@ -230,6 +241,14 @@ Description: Displays a list with information about the currently user pointers (user virtual addresses) that are pinned and mapped to DMA addresses +What: /sys/kernel/debug/habanalabs/hl/userptr_lookup +Date: Aug 2021 +KernelVersion: 5.15 +Contact: ogabbay@kernel.org +Description: Allows to search for specific user pointers (user virtual + addresses) that are pinned and mapped to DMA addresses, and see + their resolution to the specific dma address. + What: /sys/kernel/debug/habanalabs/hl/vm Date: Jan 2019 KernelVersion: 5.1 diff --git a/Documentation/ABI/testing/sysfs-bus-pci b/Documentation/ABI/testing/sysfs-bus-pci index 793cbb76cd25..d4ae03296861 100644 --- a/Documentation/ABI/testing/sysfs-bus-pci +++ b/Documentation/ABI/testing/sysfs-bus-pci @@ -121,6 +121,23 @@ Description: child buses, and re-discover devices removed earlier from this part of the device tree. +What: /sys/bus/pci/devices/.../reset_method +Date: August 2021 +Contact: Amey Narkhede +Description: + Some devices allow an individual function to be reset + without affecting other functions in the same slot. + + For devices that have this support, a file named + reset_method is present in sysfs. Reading this file + gives names of the supported and enabled reset methods and + their ordering. Writing a space-separated list of names of + reset methods sets the reset methods and ordering to be + used when resetting the device. Writing an empty string + disables the ability to reset the device. Writing + "default" enables all supported reset methods in the + default ordering. + What: /sys/bus/pci/devices/.../reset Date: July 2009 Contact: Michael S. Tsirkin diff --git a/Documentation/PCI/endpoint/pci-endpoint-cfs.rst b/Documentation/PCI/endpoint/pci-endpoint-cfs.rst index db609b97ad58..fb73345cfb8a 100644 --- a/Documentation/PCI/endpoint/pci-endpoint-cfs.rst +++ b/Documentation/PCI/endpoint/pci-endpoint-cfs.rst @@ -43,6 +43,7 @@ entries corresponding to EPF driver will be created by the EPF core. .. / ... / ... / + ... / .. / ... / ... / @@ -68,6 +69,7 @@ created) ... subsys_vendor_id ... subsys_id ... interrupt_pin + ... / ... primary/ ... / ... secondary/ @@ -79,6 +81,13 @@ interface should be added in 'primary' directory and symlink of endpoint controller connected to secondary interface should be added in 'secondary' directory. +The directory can have a list of symbolic links +() to other . These symbolic links should +be created by the user to represent the virtual functions that are bound to +the physical function. In the above directory structure is a +physical function and is a virtual function. An EPF device once +it's linked to another EPF device, cannot be linked to a EPC device. + EPC Device ========== @@ -98,7 +107,8 @@ entries corresponding to EPC device will be created by the EPC core. The directory will have a list of symbolic links to . These symbolic links should be created by the user to -represent the functions present in the endpoint device. +represent the functions present in the endpoint device. Only +that represents a physical function can be linked to a EPC device. The directory will also have a *start* field. Once "1" is written to this field, the endpoint device will be ready to diff --git a/Documentation/admin-guide/acpi/ssdt-overlays.rst b/Documentation/admin-guide/acpi/ssdt-overlays.rst index 5d7e25988085..b5fbf54dca19 100644 --- a/Documentation/admin-guide/acpi/ssdt-overlays.rst +++ b/Documentation/admin-guide/acpi/ssdt-overlays.rst @@ -30,22 +30,21 @@ following ASL code can be used:: { Device (STAC) { - Name (_ADR, Zero) Name (_HID, "BMA222E") + Name (RBUF, ResourceTemplate () + { + I2cSerialBus (0x0018, ControllerInitiated, 0x00061A80, + AddressingMode7Bit, "\\_SB.I2C6", 0x00, + ResourceConsumer, ,) + GpioInt (Edge, ActiveHigh, Exclusive, PullDown, 0x0000, + "\\_SB.GPO2", 0x00, ResourceConsumer, , ) + { // Pin list + 0 + } + }) Method (_CRS, 0, Serialized) { - Name (RBUF, ResourceTemplate () - { - I2cSerialBus (0x0018, ControllerInitiated, 0x00061A80, - AddressingMode7Bit, "\\_SB.I2C6", 0x00, - ResourceConsumer, ,) - GpioInt (Edge, ActiveHigh, Exclusive, PullDown, 0x0000, - "\\_SB.GPO2", 0x00, ResourceConsumer, , ) - { // Pin list - 0 - } - }) Return (RBUF) } } @@ -75,7 +74,7 @@ This option allows loading of user defined SSDTs from initrd and it is useful when the system does not support EFI or when there is not enough EFI storage. It works in a similar way with initrd based ACPI tables override/upgrade: SSDT -aml code must be placed in the first, uncompressed, initrd under the +AML code must be placed in the first, uncompressed, initrd under the "kernel/firmware/acpi" path. Multiple files can be used and this will translate in loading multiple tables. Only SSDT and OEM tables are allowed. See initrd_table_override.txt for more details. @@ -103,12 +102,14 @@ This is the preferred method, when EFI is supported on the platform, because it allows a persistent, OS independent way of storing the user defined SSDTs. There is also work underway to implement EFI support for loading user defined SSDTs and using this method will make it easier to convert to the EFI loading -mechanism when that will arrive. +mechanism when that will arrive. To enable it, the +CONFIG_EFI_CUSTOM_SSDT_OVERLAYS shoyld be chosen to y. -In order to load SSDTs from an EFI variable the efivar_ssdt kernel command line -parameter can be used. The argument for the option is the variable name to -use. If there are multiple variables with the same name but with different -vendor GUIDs, all of them will be loaded. +In order to load SSDTs from an EFI variable the ``"efivar_ssdt=..."`` kernel +command line parameter can be used (the name has a limitation of 16 characters). +The argument for the option is the variable name to use. If there are multiple +variables with the same name but with different vendor GUIDs, all of them will +be loaded. In order to store the AML code in an EFI variable the efivarfs filesystem can be used. It is enabled and mounted by default in /sys/firmware/efi/efivars in all @@ -127,7 +128,7 @@ variable with the content from a given file:: #!/bin/sh -e - while ! [ -z "$1" ]; do + while [ -n "$1" ]; do case "$1" in "-f") filename="$2"; shift;; "-g") guid="$2"; shift;; @@ -167,14 +168,14 @@ variable with the content from a given file:: Loading ACPI SSDTs from configfs ================================ -This option allows loading of user defined SSDTs from userspace via the configfs +This option allows loading of user defined SSDTs from user space via the configfs interface. The CONFIG_ACPI_CONFIGFS option must be select and configfs must be mounted. In the following examples, we assume that configfs has been mounted in -/config. +/sys/kernel/config. -New tables can be loading by creating new directories in /config/acpi/table/ and -writing the SSDT aml code in the aml attribute:: +New tables can be loading by creating new directories in /sys/kernel/config/acpi/table +and writing the SSDT AML code in the aml attribute:: - cd /config/acpi/table + cd /sys/kernel/config/acpi/table mkdir my_ssdt cat ~/ssdt.aml > my_ssdt/aml diff --git a/Documentation/admin-guide/bootconfig.rst b/Documentation/admin-guide/bootconfig.rst index 6a79f2e59396..a1860fc0ca88 100644 --- a/Documentation/admin-guide/bootconfig.rst +++ b/Documentation/admin-guide/bootconfig.rst @@ -178,7 +178,7 @@ update the boot loader and the kernel image itself as long as the boot loader passes the correct initrd file size. If by any chance, the boot loader passes a longer size, the kernel fails to find the bootconfig data. -To do this operation, Linux kernel provides "bootconfig" command under +To do this operation, Linux kernel provides ``bootconfig`` command under tools/bootconfig, which allows admin to apply or delete the config file to/from initrd image. You can build it by the following command:: @@ -196,6 +196,43 @@ To remove the config from the image, you can use -d option as below:: Then add "bootconfig" on the normal kernel command line to tell the kernel to look for the bootconfig at the end of the initrd file. + +Kernel parameters via Boot Config +================================= + +In addition to the kernel command line, the boot config can be used for +passing the kernel parameters. All the key-value pairs under ``kernel`` +key will be passed to kernel cmdline directly. Moreover, the key-value +pairs under ``init`` will be passed to init process via the cmdline. +The parameters are concatinated with user-given kernel cmdline string +as the following order, so that the command line parameter can override +bootconfig parameters (this depends on how the subsystem handles parameters +but in general, earlier parameter will be overwritten by later one.):: + + [bootconfig params][cmdline params] -- [bootconfig init params][cmdline init params] + +Here is an example of the bootconfig file for kernel/init parameters.:: + + kernel { + root = 01234567-89ab-cdef-0123-456789abcd + } + init { + splash + } + +This will be copied into the kernel cmdline string as the following:: + + root="01234567-89ab-cdef-0123-456789abcd" -- splash + +If user gives some other command line like,:: + + ro bootconfig -- quiet + +The final kernel cmdline will be the following:: + + root="01234567-89ab-cdef-0123-456789abcd" ro bootconfig -- splash quiet + + Config File Limitation ====================== diff --git a/Documentation/admin-guide/kernel-parameters.txt b/Documentation/admin-guide/kernel-parameters.txt index 828d11441ebf..91ba391f9b32 100644 --- a/Documentation/admin-guide/kernel-parameters.txt +++ b/Documentation/admin-guide/kernel-parameters.txt @@ -1758,6 +1758,11 @@ support for the idxd driver. By default it is set to true (1). + idxd.tc_override= [HW] + Format: + Allow override of default traffic class configuration + for the device. By default it is set to false (0). + ieee754= [MIPS] Select IEEE Std 754 conformance mode Format: { strict | legacy | 2008 | relaxed } Default: strict diff --git a/Documentation/admin-guide/mm/damon/index.rst b/Documentation/admin-guide/mm/damon/index.rst new file mode 100644 index 000000000000..8c5dde3a5754 --- /dev/null +++ b/Documentation/admin-guide/mm/damon/index.rst @@ -0,0 +1,15 @@ +.. SPDX-License-Identifier: GPL-2.0 + +======================== +Monitoring Data Accesses +======================== + +:doc:`DAMON ` allows light-weight data access monitoring. +Using DAMON, users can analyze the memory access patterns of their systems and +optimize those. + +.. toctree:: + :maxdepth: 2 + + start + usage diff --git a/Documentation/admin-guide/mm/damon/start.rst b/Documentation/admin-guide/mm/damon/start.rst new file mode 100644 index 000000000000..d5eb89a8fc38 --- /dev/null +++ b/Documentation/admin-guide/mm/damon/start.rst @@ -0,0 +1,114 @@ +.. SPDX-License-Identifier: GPL-2.0 + +=============== +Getting Started +=============== + +This document briefly describes how you can use DAMON by demonstrating its +default user space tool. Please note that this document describes only a part +of its features for brevity. Please refer to :doc:`usage` for more details. + + +TL; DR +====== + +Follow the commands below to monitor and visualize the memory access pattern of +your workload. :: + + # # build the kernel with CONFIG_DAMON_*=y, install it, and reboot + # mount -t debugfs none /sys/kernel/debug/ + # git clone https://github.com/awslabs/damo + # ./damo/damo record $(pidof ) + # ./damo/damo report heat --plot_ascii + +The final command draws the access heatmap of ````. The heatmap +shows which memory region (x-axis) is accessed when (y-axis) and how frequently +(number; the higher the more accesses have been observed). :: + + 111111111111111111111111111111111111111111111111111111110000 + 111121111111111111111111111111211111111111111111111111110000 + 000000000000000000000000000000000000000000000000001555552000 + 000000000000000000000000000000000000000000000222223555552000 + 000000000000000000000000000000000000000011111677775000000000 + 000000000000000000000000000000000000000488888000000000000000 + 000000000000000000000000000000000177888400000000000000000000 + 000000000000000000000000000046666522222100000000000000000000 + 000000000000000000000014444344444300000000000000000000000000 + 000000000000000002222245555510000000000000000000000000000000 + # access_frequency: 0 1 2 3 4 5 6 7 8 9 + # x-axis: space (140286319947776-140286426374096: 101.496 MiB) + # y-axis: time (605442256436361-605479951866441: 37.695430s) + # resolution: 60x10 (1.692 MiB and 3.770s for each character) + + +Prerequisites +============= + +Kernel +------ + +You should first ensure your system is running on a kernel built with +``CONFIG_DAMON_*=y``. + + +User Space Tool +--------------- + +For the demonstration, we will use the default user space tool for DAMON, +called DAMON Operator (DAMO). It is available at +https://github.com/awslabs/damo. The examples below assume that ``damo`` is on +your ``$PATH``. It's not mandatory, though. + +Because DAMO is using the debugfs interface (refer to :doc:`usage` for the +detail) of DAMON, you should ensure debugfs is mounted. Mount it manually as +below:: + + # mount -t debugfs none /sys/kernel/debug/ + +or append the following line to your ``/etc/fstab`` file so that your system +can automatically mount debugfs upon booting:: + + debugfs /sys/kernel/debug debugfs defaults 0 0 + + +Recording Data Access Patterns +============================== + +The commands below record the memory access patterns of a program and save the +monitoring results to a file. :: + + $ git clone https://github.com/sjp38/masim + $ cd masim; make; ./masim ./configs/zigzag.cfg & + $ sudo damo record -o damon.data $(pidof masim) + +The first two lines of the commands download an artificial memory access +generator program and run it in the background. The generator will repeatedly +access two 100 MiB sized memory regions one by one. You can substitute this +with your real workload. The last line asks ``damo`` to record the access +pattern in the ``damon.data`` file. + + +Visualizing Recorded Patterns +============================= + +The following three commands visualize the recorded access patterns and save +the results as separate image files. :: + + $ damo report heats --heatmap access_pattern_heatmap.png + $ damo report wss --range 0 101 1 --plot wss_dist.png + $ damo report wss --range 0 101 1 --sortby time --plot wss_chron_change.png + +- ``access_pattern_heatmap.png`` will visualize the data access pattern in a + heatmap, showing which memory region (y-axis) got accessed when (x-axis) + and how frequently (color). +- ``wss_dist.png`` will show the distribution of the working set size. +- ``wss_chron_change.png`` will show how the working set size has + chronologically changed. + +You can view the visualizations of this example workload at [1]_. +Visualizations of other realistic workloads are available at [2]_ [3]_ [4]_. + +.. [1] https://damonitor.github.io/doc/html/v17/admin-guide/mm/damon/start.html#visualizing-recorded-patterns +.. [2] https://damonitor.github.io/test/result/visual/latest/rec.heatmap.1.png.html +.. [3] https://damonitor.github.io/test/result/visual/latest/rec.wss_sz.png.html +.. [4] https://damonitor.github.io/test/result/visual/latest/rec.wss_time.png.html diff --git a/Documentation/admin-guide/mm/damon/usage.rst b/Documentation/admin-guide/mm/damon/usage.rst new file mode 100644 index 000000000000..a72cda374aba --- /dev/null +++ b/Documentation/admin-guide/mm/damon/usage.rst @@ -0,0 +1,112 @@ +.. SPDX-License-Identifier: GPL-2.0 + +=============== +Detailed Usages +=============== + +DAMON provides below three interfaces for different users. + +- *DAMON user space tool.* + This 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 only virtual address spaces monitoring. +- *debugfs interface.* + This is for privileged user space programmers who want more optimized use of + DAMON. Using this, users can use DAMON’s major features by reading + from and writing to special debugfs files. Therefore, you can write and use + your personalized DAMON debugfs wrapper programs that reads/writes the + debugfs files instead of you. The DAMON user space tool is also a reference + implementation of such programs. It supports only virtual address spaces + monitoring. +- *Kernel Space Programming Interface.* + This is for kernel space programmers. Using this, users can utilize every + feature of DAMON most flexibly and efficiently by writing kernel space + DAMON application programs for you. You can even extend DAMON for various + address spaces. + +Nevertheless, you could write your own user space tool using the debugfs +interface. A reference implementation is available at +https://github.com/awslabs/damo. If you are a kernel programmer, you could +refer to :doc:`/vm/damon/api` for the kernel space programming interface. For +the reason, this document describes only the debugfs interface + +debugfs Interface +================= + +DAMON exports three files, ``attrs``, ``target_ids``, and ``monitor_on`` under +its debugfs directory, ``/damon/``. + + +Attributes +---------- + +Users can get and set the ``sampling interval``, ``aggregation interval``, +``regions update interval``, and min/max number of monitoring target regions by +reading from and writing to the ``attrs`` file. To know about the monitoring +attributes in detail, please refer to the :doc:`/vm/damon/design`. For +example, below commands set those values to 5 ms, 100 ms, 1,000 ms, 10 and +1000, and then check it again:: + + # cd /damon + # echo 5000 100000 1000000 10 1000 > attrs + # cat attrs + 5000 100000 1000000 10 1000 + + +Target IDs +---------- + +Some types of address spaces supports multiple monitoring target. For example, +the virtual memory address spaces monitoring can have multiple processes as the +monitoring targets. Users can set the targets by writing relevant id values of +the targets to, and get the ids of the current targets by reading from the +``target_ids`` file. In case of the virtual address spaces monitoring, the +values should be pids of the monitoring target processes. For example, below +commands set processes having pids 42 and 4242 as the monitoring targets and +check it again:: + + # cd /damon + # echo 42 4242 > target_ids + # cat target_ids + 42 4242 + +Note that setting the target ids doesn't start the monitoring. + + +Turning On/Off +-------------- + +Setting the files as described above doesn't incur effect unless you explicitly +start the monitoring. You can start, stop, and check the current status of the +monitoring by writing to and reading from the ``monitor_on`` file. Writing +``on`` to the file starts the monitoring of the targets with the attributes. +Writing ``off`` to the file stops those. DAMON also stops if every target +process is terminated. Below example commands turn on, off, and check the +status of DAMON:: + + # cd /damon + # echo on > monitor_on + # echo off > monitor_on + # cat monitor_on + off + +Please note that you cannot write to the above-mentioned debugfs files while +the monitoring is turned on. If you write to the files while DAMON is running, +an error code such as ``-EBUSY`` will be returned. + + +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:: + + # echo on > monitor_on + # perf record -e damon:damon_aggregated & + # sleep 5 + # kill 9 $(pidof perf) + # echo off > monitor_on + # perf script diff --git a/Documentation/admin-guide/mm/index.rst b/Documentation/admin-guide/mm/index.rst index 4b14d8b50e9e..cbd19d5e625f 100644 --- a/Documentation/admin-guide/mm/index.rst +++ b/Documentation/admin-guide/mm/index.rst @@ -27,6 +27,7 @@ the Linux memory management. concepts cma_debugfs + damon/index hugetlbpage idle_page_tracking ksm diff --git a/Documentation/admin-guide/mm/memory-hotplug.rst b/Documentation/admin-guide/mm/memory-hotplug.rst index c6bae2d77160..03dfbc925252 100644 --- a/Documentation/admin-guide/mm/memory-hotplug.rst +++ b/Documentation/admin-guide/mm/memory-hotplug.rst @@ -1,466 +1,576 @@ .. _admin_guide_memory_hotplug: -============== -Memory Hotplug -============== +================== +Memory Hot(Un)Plug +================== -:Created: Jul 28 2007 -:Updated: Add some details about locking internals: Aug 20 2018 - -This document is about memory hotplug including how-to-use and current status. -Because Memory Hotplug is still under development, contents of this text will -be changed often. +This document describes generic Linux support for memory hot(un)plug with +a focus on System RAM, including ZONE_MOVABLE support. .. contents:: :local: -.. note:: +Introduction +============ - (1) x86_64's has special implementation for memory hotplug. - This text does not describe it. - (2) This text assumes that sysfs is mounted at ``/sys``. +Memory hot(un)plug allows for increasing and decreasing the size of physical +memory available to a machine at runtime. In the simplest case, it consists of +physically plugging or unplugging a DIMM at runtime, coordinated with the +operating system. +Memory hot(un)plug is used for various purposes: -Introduction -============ +- The physical memory available to a machine can be adjusted at runtime, up- or + downgrading the memory capacity. This dynamic memory resizing, sometimes + referred to as "capacity on demand", is frequently used with virtual machines + and logical partitions. + +- Replacing hardware, such as DIMMs or whole NUMA nodes, without downtime. One + example is replacing failing memory modules. -Purpose of memory hotplug -------------------------- +- Reducing energy consumption either by physically unplugging memory modules or + by logically unplugging (parts of) memory modules from Linux. -Memory Hotplug allows users to increase/decrease the amount of memory. -Generally, there are two purposes. +Further, the basic memory hot(un)plug infrastructure in Linux is nowadays also +used to expose persistent memory, other performance-differentiated memory and +reserved memory regions as ordinary system RAM to Linux. -(A) For changing the amount of memory. - This is to allow a feature like capacity on demand. -(B) For installing/removing DIMMs or NUMA-nodes physically. - This is to exchange DIMMs/NUMA-nodes, reduce power consumption, etc. +Linux only supports memory hot(un)plug on selected 64 bit architectures, such as +x86_64, arm64, ppc64, s390x and ia64. -(A) is required by highly virtualized environments and (B) is required by -hardware which supports memory power management. +Memory Hot(Un)Plug Granularity +------------------------------ -Linux memory hotplug is designed for both purpose. +Memory hot(un)plug in Linux uses the SPARSEMEM memory model, which divides the +physical memory address space into chunks of the same size: memory sections. The +size of a memory section is architecture dependent. For example, x86_64 uses +128 MiB and ppc64 uses 16 MiB. -Phases of memory hotplug +Memory sections are combined into chunks referred to as "memory blocks". The +size of a memory block is architecture dependent and corresponds to the smallest +granularity that can be hot(un)plugged. The default size of a memory block is +the same as memory section size, unless an architecture specifies otherwise. + +All memory blocks have the same size. + +Phases of Memory Hotplug ------------------------ -There are 2 phases in Memory Hotplug: +Memory hotplug consists of two phases: - 1) Physical Memory Hotplug phase - 2) Logical Memory Hotplug phase. +(1) Adding the memory to Linux +(2) Onlining memory blocks -The First phase is to communicate hardware/firmware and make/erase -environment for hotplugged memory. Basically, this phase is necessary -for the purpose (B), but this is good phase for communication between -highly virtualized environments too. +In the first phase, metadata, such as the memory map ("memmap") and page tables +for the direct mapping, is allocated and initialized, and memory blocks are +created; the latter also creates sysfs files for managing newly created memory +blocks. -When memory is hotplugged, the kernel recognizes new memory, makes new memory -management tables, and makes sysfs files for new memory's operation. +In the second phase, added memory is exposed to the page allocator. After this +phase, the memory is visible in memory statistics, such as free and total +memory, of the system. -If firmware supports notification of connection of new memory to OS, -this phase is triggered automatically. ACPI can notify this event. If not, -"probe" operation by system administration is used instead. -(see :ref:`memory_hotplug_physical_mem`). +Phases of Memory Hotunplug +-------------------------- -Logical Memory Hotplug phase is to change memory state into -available/unavailable for users. Amount of memory from user's view is -changed by this phase. The kernel makes all memory in it as free pages -when a memory range is available. +Memory hotunplug consists of two phases: -In this document, this phase is described as online/offline. +(1) Offlining memory blocks +(2) Removing the memory from Linux -Logical Memory Hotplug phase is triggered by write of sysfs file by system -administrator. For the hot-add case, it must be executed after Physical Hotplug -phase by hand. -(However, if you writes udev's hotplug scripts for memory hotplug, these -phases can be execute in seamless way.) +In the fist phase, memory is "hidden" from the page allocator again, for +example, by migrating busy memory to other memory locations and removing all +relevant free pages from the page allocator After this phase, the memory is no +longer visible in memory statistics of the system. -Unit of Memory online/offline operation ---------------------------------------- +In the second phase, the memory blocks are removed and metadata is freed. -Memory hotplug uses SPARSEMEM memory model which allows memory to be divided -into chunks of the same size. These chunks are called "sections". The size of -a memory section is architecture dependent. For example, power uses 16MiB, ia64 -uses 1GiB. +Memory Hotplug Notifications +============================ -Memory sections are combined into chunks referred to as "memory blocks". The -size of a memory block is architecture dependent and represents the logical -unit upon which memory online/offline operations are to be performed. The -default size of a memory block is the same as memory section size unless an -architecture specifies otherwise. (see :ref:`memory_hotplug_sysfs_files`.) +There are various ways how Linux is notified about memory hotplug events such +that it can start adding hotplugged memory. This description is limited to +systems that support ACPI; mechanisms specific to other firmware interfaces or +virtual machines are not described. -To determine the size (in bytes) of a memory block please read this file:: +ACPI Notifications +------------------ - /sys/devices/system/memory/block_size_bytes +Platforms that support ACPI, such as x86_64, can support memory hotplug +notifications via ACPI. -Kernel Configuration -==================== +In general, a firmware supporting memory hotplug defines a memory class object +HID "PNP0C80". When notified about hotplug of a new memory device, the ACPI +driver will hotplug the memory to Linux. -To use memory hotplug feature, kernel must be compiled with following -config options. +If the firmware supports hotplug of NUMA nodes, it defines an object _HID +"ACPI0004", "PNP0A05", or "PNP0A06". When notified about an hotplug event, all +assigned memory devices are added to Linux by the ACPI driver. -- For all memory hotplug: - - Memory model -> Sparse Memory (``CONFIG_SPARSEMEM``) - - Allow for memory hot-add (``CONFIG_MEMORY_HOTPLUG``) +Similarly, Linux can be notified about requests to hotunplug a memory device or +a NUMA node via ACPI. The ACPI driver will try offlining all relevant memory +blocks, and, if successful, hotunplug the memory from Linux. -- To enable memory removal, the following are also necessary: - - Allow for memory hot remove (``CONFIG_MEMORY_HOTREMOVE``) - - Page Migration (``CONFIG_MIGRATION``) +Manual Probing +-------------- -- For ACPI memory hotplug, the following are also necessary: - - Memory hotplug (under ACPI Support menu) (``CONFIG_ACPI_HOTPLUG_MEMORY``) - - This option can be kernel module. +On some architectures, the firmware may not be able to notify the operating +system about a memory hotplug event. Instead, the memory has to be manually +probed from user space. -- As a related configuration, if your box has a feature of NUMA-node hotplug - via ACPI, then this option is necessary too. +The probe interface is located at:: - - ACPI0004,PNP0A05 and PNP0A06 Container Driver (under ACPI Support menu) - (``CONFIG_ACPI_CONTAINER``). + /sys/devices/system/memory/probe - This option can be kernel module too. +Only complete memory blocks can be probed. Individual memory blocks are probed +by providing the physical start address of the memory block:: + % echo addr > /sys/devices/system/memory/probe -.. _memory_hotplug_sysfs_files: +Which results in a memory block for the range [addr, addr + memory_block_size) +being created. -sysfs files for memory hotplug -============================== +.. note:: -All memory blocks have their device information in sysfs. Each memory block -is described under ``/sys/devices/system/memory`` as:: + Using the probe interface is discouraged as it is easy to crash the kernel, + because Linux cannot validate user input; this interface might be removed in + the future. - /sys/devices/system/memory/memoryXXX +Onlining and Offlining Memory Blocks +==================================== -where XXX is the memory block id. +After a memory block has been created, Linux has to be instructed to actually +make use of that memory: the memory block has to be "online". -For the memory block covered by the sysfs directory. It is expected that all -memory sections in this range are present and no memory holes exist in the -range. Currently there is no way to determine if there is a memory hole, but -the existence of one should not affect the hotplug capabilities of the memory -block. +Before a memory block can be removed, Linux has to stop using any memory part of +the memory block: the memory block has to be "offlined". -For example, assume 1GiB memory block size. A device for a memory starting at -0x100000000 is ``/sys/device/system/memory/memory4``:: +The Linux kernel can be configured to automatically online added memory blocks +and drivers automatically trigger offlining of memory blocks when trying +hotunplug of memory. Memory blocks can only be removed once offlining succeeded +and drivers may trigger offlining of memory blocks when attempting hotunplug of +memory. - (0x100000000 / 1Gib = 4) +Onlining Memory Blocks Manually +------------------------------- -This device covers address range [0x100000000 ... 0x140000000) +If auto-onlining of memory blocks isn't enabled, user-space has to manually +trigger onlining of memory blocks. Often, udev rules are used to automate this +task in user space. -Under each memory block, you can see 5 files: +Onlining of a memory block can be triggered via:: -- ``/sys/devices/system/memory/memoryXXX/phys_index`` -- ``/sys/devices/system/memory/memoryXXX/phys_device`` -- ``/sys/devices/system/memory/memoryXXX/state`` -- ``/sys/devices/system/memory/memoryXXX/removable`` -- ``/sys/devices/system/memory/memoryXXX/valid_zones`` + % echo online > /sys/devices/system/memory/memoryXXX/state -=================== ============================================================ -``phys_index`` read-only and contains memory block id, same as XXX. -``state`` read-write +Or alternatively:: - - at read: contains online/offline state of memory. - - at write: user can specify "online_kernel", + % echo 1 > /sys/devices/system/memory/memoryXXX/online - "online_movable", "online", "offline" command - which will be performed on all sections in the block. -``phys_device`` read-only: legacy interface only ever used on s390x to - expose the covered storage increment. -``removable`` read-only: legacy interface that indicated whether a memory - block was likely to be offlineable or not. Newer kernel - versions return "1" if and only if the kernel supports - memory offlining. -``valid_zones`` read-only: designed to show by which zone memory provided by - a memory block is managed, and to show by which zone memory - provided by an offline memory block could be managed when - onlining. - - The first column shows it`s default zone. - - "memory6/valid_zones: Normal Movable" shows this memoryblock - can be onlined to ZONE_NORMAL by default and to ZONE_MOVABLE - by online_movable. - - "memory7/valid_zones: Movable Normal" shows this memoryblock - can be onlined to ZONE_MOVABLE by default and to ZONE_NORMAL - by online_kernel. -=================== ============================================================ +The kernel will select the target zone automatically, usually defaulting to +``ZONE_NORMAL`` unless ``movablecore=1`` has been specified on the kernel +command line or if the memory block would intersect the ZONE_MOVABLE already. -.. note:: +One can explicitly request to associate an offline memory block with +ZONE_MOVABLE by:: - These directories/files appear after physical memory hotplug phase. + % echo online_movable > /sys/devices/system/memory/memoryXXX/state -If CONFIG_NUMA is enabled the memoryXXX/ directories can also be accessed -via symbolic links located in the ``/sys/devices/system/node/node*`` directories. +Or one can explicitly request a kernel zone (usually ZONE_NORMAL) by:: -For example:: + % echo online_kernel > /sys/devices/system/memory/memoryXXX/state - /sys/devices/system/node/node0/memory9 -> ../../memory/memory9 +In any case, if onlining succeeds, the state of the memory block is changed to +be "online". If it fails, the state of the memory block will remain unchanged +and the above commands will fail. -A backlink will also be created:: +Onlining Memory Blocks Automatically +------------------------------------ - /sys/devices/system/memory/memory9/node0 -> ../../node/node0 +The kernel can be configured to try auto-onlining of newly added memory blocks. +If this feature is disabled, the memory blocks will stay offline until +explicitly onlined from user space. -.. _memory_hotplug_physical_mem: +The configured auto-online behavior can be observed via:: -Physical memory hot-add phase -============================= + % cat /sys/devices/system/memory/auto_online_blocks -Hardware(Firmware) Support --------------------------- +Auto-onlining can be enabled by writing ``online``, ``online_kernel`` or +``online_movable`` to that file, like:: -On x86_64/ia64 platform, memory hotplug by ACPI is supported. + % echo online > /sys/devices/system/memory/auto_online_blocks -In general, the firmware (ACPI) which supports memory hotplug defines -memory class object of _HID "PNP0C80". When a notify is asserted to PNP0C80, -Linux's ACPI handler does hot-add memory to the system and calls a hotplug udev -script. This will be done automatically. +Modifying the auto-online behavior will only affect all subsequently added +memory blocks only. -But scripts for memory hotplug are not contained in generic udev package(now). -You may have to write it by yourself or online/offline memory by hand. -Please see :ref:`memory_hotplug_how_to_online_memory` and -:ref:`memory_hotplug_how_to_offline_memory`. +.. note:: -If firmware supports NUMA-node hotplug, and defines an object _HID "ACPI0004", -"PNP0A05", or "PNP0A06", notification is asserted to it, and ACPI handler -calls hotplug code for all of objects which are defined in it. -If memory device is found, memory hotplug code will be called. + In corner cases, auto-onlining can fail. The kernel won't retry. Note that + auto-onlining is not expected to fail in default configurations. -Notify memory hot-add event by hand ------------------------------------ +.. note:: -On some architectures, the firmware may not notify the kernel of a memory -hotplug event. Therefore, the memory "probe" interface is supported to -explicitly notify the kernel. This interface depends on -CONFIG_ARCH_MEMORY_PROBE and can be configured on powerpc, sh, and x86 -if hotplug is supported, although for x86 this should be handled by ACPI -notification. + DLPAR on ppc64 ignores the ``offline`` setting and will still online added + memory blocks; if onlining fails, memory blocks are removed again. -Probe interface is located at:: +Offlining Memory Blocks +----------------------- - /sys/devices/system/memory/probe +In the current implementation, Linux's memory offlining will try migrating all +movable pages off the affected memory block. As most kernel allocations, such as +page tables, are unmovable, page migration can fail and, therefore, inhibit +memory offlining from succeeding. -You can tell the physical address of new memory to the kernel by:: +Having the memory provided by memory block managed by ZONE_MOVABLE significantly +increases memory offlining reliability; still, memory offlining can fail in +some corner cases. - % echo start_address_of_new_memory > /sys/devices/system/memory/probe +Further, memory offlining might retry for a long time (or even forever), until +aborted by the user. -Then, [start_address_of_new_memory, start_address_of_new_memory + -memory_block_size] memory range is hot-added. In this case, hotplug script is -not called (in current implementation). You'll have to online memory by -yourself. Please see :ref:`memory_hotplug_how_to_online_memory`. +Offlining of a memory block can be triggered via:: -Logical Memory hot-add phase -============================ + % echo offline > /sys/devices/system/memory/memoryXXX/state -State of memory ---------------- +Or alternatively:: -To see (online/offline) state of a memory block, read 'state' file:: + % echo 0 > /sys/devices/system/memory/memoryXXX/online - % cat /sys/device/system/memory/memoryXXX/state +If offlining succeeds, the state of the memory block is changed to be "offline". +If it fails, the state of the memory block will remain unchanged and the above +commands will fail, for example, via:: + bash: echo: write error: Device or resource busy -- If the memory block is online, you'll read "online". -- If the memory block is offline, you'll read "offline". +or via:: + bash: echo: write error: Invalid argument -.. _memory_hotplug_how_to_online_memory: +Observing the State of Memory Blocks +------------------------------------ -How to online memory --------------------- +The state (online/offline/going-offline) of a memory block can be observed +either via:: -When the memory is hot-added, the kernel decides whether or not to "online" -it according to the policy which can be read from "auto_online_blocks" file:: + % cat /sys/device/system/memory/memoryXXX/state - % cat /sys/devices/system/memory/auto_online_blocks +Or alternatively (1/0) via:: -The default depends on the CONFIG_MEMORY_HOTPLUG_DEFAULT_ONLINE kernel config -option. If it is disabled the default is "offline" which means the newly added -memory is not in a ready-to-use state and you have to "online" the newly added -memory blocks manually. Automatic onlining can be requested by writing "online" -to "auto_online_blocks" file:: + % cat /sys/device/system/memory/memoryXXX/online - % echo online > /sys/devices/system/memory/auto_online_blocks +For an online memory block, the managing zone can be observed via:: -This sets a global policy and impacts all memory blocks that will subsequently -be hotplugged. Currently offline blocks keep their state. It is possible, under -certain circumstances, that some memory blocks will be added but will fail to -online. User space tools can check their "state" files -(``/sys/devices/system/memory/memoryXXX/state``) and try to online them manually. + % cat /sys/device/system/memory/memoryXXX/valid_zones -If the automatic onlining wasn't requested, failed, or some memory block was -offlined it is possible to change the individual block's state by writing to the -"state" file:: +Configuring Memory Hot(Un)Plug +============================== - % echo online > /sys/devices/system/memory/memoryXXX/state +There are various ways how system administrators can configure memory +hot(un)plug and interact with memory blocks, especially, to online them. -This onlining will not change the ZONE type of the target memory block, -If the memory block doesn't belong to any zone an appropriate kernel zone -(usually ZONE_NORMAL) will be used unless movable_node kernel command line -option is specified when ZONE_MOVABLE will be used. +Memory Hot(Un)Plug Configuration via Sysfs +------------------------------------------ -You can explicitly request to associate it with ZONE_MOVABLE by:: +Some memory hot(un)plug properties can be configured or inspected via sysfs in:: - % echo online_movable > /sys/devices/system/memory/memoryXXX/state + /sys/devices/system/memory/ -.. note:: current limit: this memory block must be adjacent to ZONE_MOVABLE +The following files are currently defined: -Or you can explicitly request a kernel zone (usually ZONE_NORMAL) by:: +====================== ========================================================= +``auto_online_blocks`` read-write: set or get the default state of new memory + blocks; configure auto-onlining. - % echo online_kernel > /sys/devices/system/memory/memoryXXX/state + The default value depends on the + CONFIG_MEMORY_HOTPLUG_DEFAULT_ONLINE kernel configuration + option. -.. note:: current limit: this memory block must be adjacent to ZONE_NORMAL + See the ``state`` property of memory blocks for details. +``block_size_bytes`` read-only: the size in bytes of a memory block. +``probe`` write-only: add (probe) selected memory blocks manually + from user space by supplying the physical start address. -An explicit zone onlining can fail (e.g. when the range is already within -and existing and incompatible zone already). + Availability depends on the CONFIG_ARCH_MEMORY_PROBE + kernel configuration option. +``uevent`` read-write: generic udev file for device subsystems. +====================== ========================================================= -After this, memory block XXX's state will be 'online' and the amount of -available memory will be increased. +.. note:: -This may be changed in future. + When the CONFIG_MEMORY_FAILURE kernel configuration option is enabled, two + additional files ``hard_offline_page`` and ``soft_offline_page`` are available + to trigger hwpoisoning of pages, for example, for testing purposes. Note that + this functionality is not really related to memory hot(un)plug or actual + offlining of memory blocks. -Logical memory remove -===================== +Memory Block Configuration via Sysfs +------------------------------------ -Memory offline and ZONE_MOVABLE -------------------------------- +Each memory block is represented as a memory block device that can be +onlined or offlined. All memory blocks have their device information located in +sysfs. Each present memory block is listed under +``/sys/devices/system/memory`` as:: -Memory offlining is more complicated than memory online. Because memory offline -has to make the whole memory block be unused, memory offline can fail if -the memory block includes memory which cannot be freed. + /sys/devices/system/memory/memoryXXX -In general, memory offline can use 2 techniques. +where XXX is the memory block id; the number of digits is variable. -(1) reclaim and free all memory in the memory block. -(2) migrate all pages in the memory block. +A present memory block indicates that some memory in the range is present; +however, a memory block might span memory holes. A memory block spanning memory +holes cannot be offlined. -In the current implementation, Linux's memory offline uses method (2), freeing -all pages in the memory block by page migration. But not all pages are -migratable. Under current Linux, migratable pages are anonymous pages and -page caches. For offlining a memory block by migration, the kernel has to -guarantee that the memory block contains only migratable pages. +For example, assume 1 GiB memory block size. A device for a memory starting at +0x100000000 is ``/sys/device/system/memory/memory4``:: -Now, a boot option for making a memory block which consists of migratable pages -is supported. By specifying "kernelcore=" or "movablecore=" boot option, you can -create ZONE_MOVABLE...a zone which is just used for movable pages. -(See also Documentation/admin-guide/kernel-parameters.rst) + (0x100000000 / 1Gib = 4) -Assume the system has "TOTAL" amount of memory at boot time, this boot option -creates ZONE_MOVABLE as following. +This device covers address range [0x100000000 ... 0x140000000) -1) When kernelcore=YYYY boot option is used, - Size of memory not for movable pages (not for offline) is YYYY. - Size of memory for movable pages (for offline) is TOTAL-YYYY. +The following files are currently defined: -2) When movablecore=ZZZZ boot option is used, - Size of memory not for movable pages (not for offline) is TOTAL - ZZZZ. - Size of memory for movable pages (for offline) is ZZZZ. +=================== ============================================================ +``online`` read-write: simplified interface to trigger onlining / + offlining and to observe the state of a memory block. + When onlining, the zone is selected automatically. +``phys_device`` read-only: legacy interface only ever used on s390x to + expose the covered storage increment. +``phys_index`` read-only: the memory block id (XXX). +``removable`` read-only: legacy interface that indicated whether a memory + block was likely to be offlineable or not. Nowadays, the + kernel return ``1`` if and only if it supports memory + offlining. +``state`` read-write: advanced interface to trigger onlining / + offlining and to observe the state of a memory block. + + When writing, ``online``, ``offline``, ``online_kernel`` and + ``online_movable`` are supported. + + ``online_movable`` specifies onlining to ZONE_MOVABLE. + ``online_kernel`` specifies onlining to the default kernel + zone for the memory block, such as ZONE_NORMAL. + ``online`` let's the kernel select the zone automatically. + + When reading, ``online``, ``offline`` and ``going-offline`` + may be returned. +``uevent`` read-write: generic uevent file for devices. +``valid_zones`` read-only: when a block is online, shows the zone it + belongs to; when a block is offline, shows what zone will + manage it when the block will be onlined. + + For online memory blocks, ``DMA``, ``DMA32``, ``Normal``, + ``Movable`` and ``none`` may be returned. ``none`` indicates + that memory provided by a memory block is managed by + multiple zones or spans multiple nodes; such memory blocks + cannot be offlined. ``Movable`` indicates ZONE_MOVABLE. + Other values indicate a kernel zone. + + For offline memory blocks, the first column shows the + zone the kernel would select when onlining the memory block + right now without further specifying a zone. + + Availability depends on the CONFIG_MEMORY_HOTREMOVE + kernel configuration option. +=================== ============================================================ .. note:: - Unfortunately, there is no information to show which memory block belongs - to ZONE_MOVABLE. This is TBD. + If the CONFIG_NUMA kernel configuration option is enabled, the memoryXXX/ + directories can also be accessed via symbolic links located in the + ``/sys/devices/system/node/node*`` directories. + + For example:: + + /sys/devices/system/node/node0/memory9 -> ../../memory/memory9 + + A backlink will also be created:: + + /sys/devices/system/memory/memory9/node0 -> ../../node/node0 + +Command Line Parameters +----------------------- + +Some command line parameters affect memory hot(un)plug handling. The following +command line parameters are relevant: + +======================== ======================================================= +``memhp_default_state`` configure auto-onlining by essentially setting + ``/sys/devices/system/memory/auto_online_blocks``. +``movablecore`` configure automatic zone selection of the kernel. When + set, the kernel will default to ZONE_MOVABLE, unless + other zones can be kept contiguous. +======================== ======================================================= + +Module Parameters +------------------ - Memory offlining can fail when dissolving a free huge page on ZONE_MOVABLE - and the feature of freeing unused vmemmap pages associated with each hugetlb - page is enabled. +Instead of additional command line parameters or sysfs files, the +``memory_hotplug`` subsystem now provides a dedicated namespace for module +parameters. Module parameters can be set via the command line by predicating +them with ``memory_hotplug.`` such as:: + + memory_hotplug.memmap_on_memory=1 + +and they can be observed (and some even modified at runtime) via:: + + /sys/modules/memory_hotplug/parameters/ + +The following module parameters are currently defined: + +======================== ======================================================= +``memmap_on_memory`` read-write: Allocate memory for the memmap from the + added memory block itself. Even if enabled, actual + support depends on various other system properties and + should only be regarded as a hint whether the behavior + would be desired. + + While allocating the memmap from the memory block + itself makes memory hotplug less likely to fail and + keeps the memmap on the same NUMA node in any case, it + can fragment physical memory in a way that huge pages + in bigger granularity cannot be formed on hotplugged + memory. +======================== ======================================================= + +ZONE_MOVABLE +============ + +ZONE_MOVABLE is an important mechanism for more reliable memory offlining. +Further, having system RAM managed by ZONE_MOVABLE instead of one of the +kernel zones can increase the number of possible transparent huge pages and +dynamically allocated huge pages. + +Most kernel allocations are unmovable. Important examples include the memory +map (usually 1/64ths of memory), page tables, and kmalloc(). Such allocations +can only be served from the kernel zones. + +Most user space pages, such as anonymous memory, and page cache pages are +movable. Such allocations can be served from ZONE_MOVABLE and the kernel zones. + +Only movable allocations are served from ZONE_MOVABLE, resulting in unmovable +allocations being limited to the kernel zones. Without ZONE_MOVABLE, there is +absolutely no guarantee whether a memory block can be offlined successfully. + +Zone Imbalances +--------------- - This can happen when we have plenty of ZONE_MOVABLE memory, but not enough - kernel memory to allocate vmemmmap pages. We may even be able to migrate - huge page contents, but will not be able to dissolve the source huge page. - This will prevent an offline operation and is unfortunate as memory offlining - is expected to succeed on movable zones. Users that depend on memory hotplug - to succeed for movable zones should carefully consider whether the memory - savings gained from this feature are worth the risk of possibly not being - able to offline memory in certain situations. +Having too much system RAM managed by ZONE_MOVABLE is called a zone imbalance, +which can harm the system or degrade performance. As one example, the kernel +might crash because it runs out of free memory for unmovable allocations, +although there is still plenty of free memory left in ZONE_MOVABLE. + +Usually, MOVABLE:KERNEL ratios of up to 3:1 or even 4:1 are fine. Ratios of 63:1 +are definitely impossible due to the overhead for the memory map. + +Actual safe zone ratios depend on the workload. Extreme cases, like excessive +long-term pinning of pages, might not be able to deal with ZONE_MOVABLE at all. .. note:: - Techniques that rely on long-term pinnings of memory (especially, RDMA and - vfio) are fundamentally problematic with ZONE_MOVABLE and, therefore, memory - hot remove. Pinned pages cannot reside on ZONE_MOVABLE, to guarantee that - memory can still get hot removed - be aware that pinning can fail even if - there is plenty of free memory in ZONE_MOVABLE. In addition, using - ZONE_MOVABLE might make page pinning more expensive, because pages have to be - migrated off that zone first. -.. _memory_hotplug_how_to_offline_memory: + CMA memory part of a kernel zone essentially behaves like memory in + ZONE_MOVABLE and similar considerations apply, especially when combining + CMA with ZONE_MOVABLE. -How to offline memory ---------------------- +ZONE_MOVABLE Sizing Considerations +---------------------------------- -You can offline a memory block by using the same sysfs interface that was used -in memory onlining:: +We usually expect that a large portion of available system RAM will actually +be consumed by user space, either directly or indirectly via the page cache. In +the normal case, ZONE_MOVABLE can be used when allocating such pages just fine. - % echo offline > /sys/devices/system/memory/memoryXXX/state +With that in mind, it makes sense that we can have a big portion of system RAM +managed by ZONE_MOVABLE. However, there are some things to consider when using +ZONE_MOVABLE, especially when fine-tuning zone ratios: + +- Having a lot of offline memory blocks. Even offline memory blocks consume + memory for metadata and page tables in the direct map; having a lot of offline + memory blocks is not a typical case, though. + +- Memory ballooning without balloon compaction is incompatible with + ZONE_MOVABLE. Only some implementations, such as virtio-balloon and + pseries CMM, fully support balloon compaction. + + Further, the CONFIG_BALLOON_COMPACTION kernel configuration option might be + disabled. In that case, balloon inflation will only perform unmovable + allocations and silently create a zone imbalance, usually triggered by + inflation requests from the hypervisor. + +- Gigantic pages are unmovable, resulting in user space consuming a + lot of unmovable memory. + +- Huge pages are unmovable when an architectures does not support huge + page migration, resulting in a similar issue as with gigantic pages. + +- Page tables are unmovable. Excessive swapping, mapping extremely large + files or ZONE_DEVICE memory can be problematic, although only really relevant + in corner cases. When we manage a lot of user space memory that has been + swapped out or is served from a file/persistent memory/... we still need a lot + of page tables to manage that memory once user space accessed that memory. + +- In certain DAX configurations the memory map for the device memory will be + allocated from the kernel zones. + +- KASAN can have a significant memory overhead, for example, consuming 1/8th of + the total system memory size as (unmovable) tracking metadata. + +- Long-term pinning of pages. Techniques that rely on long-term pinnings + (especially, RDMA and vfio/mdev) are fundamentally problematic with + ZONE_MOVABLE, and therefore, memory offlining. Pinned pages cannot reside + on ZONE_MOVABLE as that would turn these pages unmovable. Therefore, they + have to be migrated off that zone while pinning. Pinning a page can fail + even if there is plenty of free memory in ZONE_MOVABLE. + + In addition, using ZONE_MOVABLE might make page pinning more expensive, + because of the page migration overhead. + +By default, all the memory configured at boot time is managed by the kernel +zones and ZONE_MOVABLE is not used. + +To enable ZONE_MOVABLE to include the memory present at boot and to control the +ratio between movable and kernel zones there are two command line options: +``kernelcore=`` and ``movablecore=``. See +Documentation/admin-guide/kernel-parameters.rst for their description. + +Memory Offlining and ZONE_MOVABLE +--------------------------------- + +Even with ZONE_MOVABLE, there are some corner cases where offlining a memory +block might fail: + +- Memory blocks with memory holes; this applies to memory blocks present during + boot and can apply to memory blocks hotplugged via the XEN balloon and the + Hyper-V balloon. + +- Mixed NUMA nodes and mixed zones within a single memory block prevent memory + offlining; this applies to memory blocks present during boot only. + +- Special memory blocks prevented by the system from getting offlined. Examples + include any memory available during boot on arm64 or memory blocks spanning + the crashkernel area on s390x; this usually applies to memory blocks present + during boot only. + +- Memory blocks overlapping with CMA areas cannot be offlined, this applies to + memory blocks present during boot only. + +- Concurrent activity that operates on the same physical memory area, such as + allocating gigantic pages, can result in temporary offlining failures. + +- Out of memory when dissolving huge pages, especially when freeing unused + vmemmap pages associated with each hugetlb page is enabled. + + Offlining code may be able to migrate huge page contents, but may not be able + to dissolve the source huge page because it fails allocating (unmovable) pages + for the vmemmap, because the system might not have free memory in the kernel + zones left. + + Users that depend on memory offlining to succeed for movable zones should + carefully consider whether the memory savings gained from this feature are + worth the risk of possibly not being able to offline memory in certain + situations. + +Further, when running into out of memory situations while migrating pages, or +when still encountering permanently unmovable pages within ZONE_MOVABLE +(-> BUG), memory offlining will keep retrying until it eventually succeeds. + +When offlining is triggered from user space, the offlining context can be +terminated by sending a fatal signal. A timeout based offlining can easily be +implemented via:: -If offline succeeds, the state of the memory block is changed to be "offline". -If it fails, some error core (like -EBUSY) will be returned by the kernel. -Even if a memory block does not belong to ZONE_MOVABLE, you can try to offline -it. If it doesn't contain 'unmovable' memory, you'll get success. - -A memory block under ZONE_MOVABLE is considered to be able to be offlined -easily. But under some busy state, it may return -EBUSY. Even if a memory -block cannot be offlined due to -EBUSY, you can retry offlining it and may be -able to offline it (or not). (For example, a page is referred to by some kernel -internal call and released soon.) - -Consideration: - Memory hotplug's design direction is to make the possibility of memory - offlining higher and to guarantee unplugging memory under any situation. But - it needs more work. Returning -EBUSY under some situation may be good because - the user can decide to retry more or not by himself. Currently, memory - offlining code does some amount of retry with 120 seconds timeout. - -Physical memory remove -====================== - -Need more implementation yet.... - - Notification completion of remove works by OS to firmware. - - Guard from remove if not yet. - - -Locking Internals -================= - -When adding/removing memory that uses memory block devices (i.e. ordinary RAM), -the device_hotplug_lock should be held to: - -- synchronize against online/offline requests (e.g. via sysfs). This way, memory - block devices can only be accessed (.online/.state attributes) by user - space once memory has been fully added. And when removing memory, we - know nobody is in critical sections. -- synchronize against CPU hotplug and similar (e.g. relevant for ACPI and PPC) - -Especially, there is a possible lock inversion that is avoided using -device_hotplug_lock when adding memory and user space tries to online that -memory faster than expected: - -- device_online() will first take the device_lock(), followed by - mem_hotplug_lock -- add_memory_resource() will first take the mem_hotplug_lock, followed by - the device_lock() (while creating the devices, during bus_add_device()). - -As the device is visible to user space before taking the device_lock(), this -can result in a lock inversion. - -onlining/offlining of memory should be done via device_online()/ -device_offline() - to make sure it is properly synchronized to actions -via sysfs. Holding device_hotplug_lock is advised (to e.g. protect online_type) - -When adding/removing/onlining/offlining memory or adding/removing -heterogeneous/device memory, we should always hold the mem_hotplug_lock in -write mode to serialise memory hotplug (e.g. access to global/zone -variables). - -In addition, mem_hotplug_lock (in contrast to device_hotplug_lock) in read -mode allows for a quite efficient get_online_mems/put_online_mems -implementation, so code accessing memory can protect from that memory -vanishing. - - -Future Work -=========== - - - allowing memory hot-add to ZONE_MOVABLE. maybe we need some switch like - sysctl or new control file. - - showing memory block and physical device relationship. - - test and make it better memory offlining. - - support HugeTLB page migration and offlining. - - memmap removing at memory offline. - - physical remove memory. + % timeout $TIMEOUT offline_block | failure_handling diff --git a/Documentation/arm/marvell.rst b/Documentation/arm/marvell.rst index 85169bc3f538..56bb592dbd0c 100644 --- a/Documentation/arm/marvell.rst +++ b/Documentation/arm/marvell.rst @@ -140,6 +140,7 @@ EBU Armada family - 88F6821 Armada 382 - 88F6W21 Armada 383 - 88F6820 Armada 385 + - 88F6825 - 88F6828 Armada 388 - Product infos: https://web.archive.org/web/20181006144616/http://www.marvell.com/embedded-processors/armada-38x/ diff --git a/Documentation/block/blk-mq.rst b/Documentation/block/blk-mq.rst index d96118c73954..31f52f326971 100644 --- a/Documentation/block/blk-mq.rst +++ b/Documentation/block/blk-mq.rst @@ -54,7 +54,7 @@ layer or if we want to try to merge requests. In both cases, requests will be sent to the software queue. Then, after the requests are processed by software queues, they will be placed -at the hardware queue, a second stage queue were the hardware has direct access +at the hardware queue, a second stage queue where the hardware has direct access to process those requests. However, if the hardware does not have enough resources to accept more requests, blk-mq will places requests on a temporary queue, to be sent in the future, when the hardware is able. diff --git a/Documentation/conf.py b/Documentation/conf.py index 75650f6443af..948a97d6387d 100644 --- a/Documentation/conf.py +++ b/Documentation/conf.py @@ -463,8 +463,8 @@ latex_elements['preamble'] += ''' \\newcommand{\\kerneldocEndTC}{} \\newcommand{\\kerneldocBeginKR}{} \\newcommand{\\kerneldocEndKR}{} - \\newcommand{\\kerneldocBeginSC}{} - \\newcommand{\\kerneldocEndKR}{} + \\newcommand{\\kerneldocBeginJP}{} + \\newcommand{\\kerneldocEndJP}{} } ''' diff --git a/Documentation/core-api/kernel-api.rst b/Documentation/core-api/kernel-api.rst index 2a7444e3a4c2..2e7186805148 100644 --- a/Documentation/core-api/kernel-api.rst +++ b/Documentation/core-api/kernel-api.rst @@ -315,6 +315,9 @@ Block Devices .. kernel-doc:: block/genhd.c :export: +.. kernel-doc:: block/bdev.c + :export: + Char devices ============ diff --git a/Documentation/cpu-freq/cpu-drivers.rst b/Documentation/cpu-freq/cpu-drivers.rst index d84ededb66f9..3b32336a7803 100644 --- a/Documentation/cpu-freq/cpu-drivers.rst +++ b/Documentation/cpu-freq/cpu-drivers.rst @@ -75,9 +75,6 @@ And optionally .resume - A pointer to a per-policy resume function which is called with interrupts disabled and _before_ the governor is started again. - .ready - A pointer to a per-policy ready function which is called after - the policy is fully initialized. - .attr - A pointer to a NULL-terminated list of "struct freq_attr" which allow to export values to sysfs. diff --git a/Documentation/dev-tools/kfence.rst b/Documentation/dev-tools/kfence.rst index fdf04e741ea5..0fbe3308bf37 100644 --- a/Documentation/dev-tools/kfence.rst +++ b/Documentation/dev-tools/kfence.rst @@ -65,25 +65,27 @@ Error reports A typical out-of-bounds access looks like this:: ================================================================== - BUG: KFENCE: out-of-bounds read in test_out_of_bounds_read+0xa3/0x22b + BUG: KFENCE: out-of-bounds read in test_out_of_bounds_read+0xa6/0x234 - Out-of-bounds read at 0xffffffffb672efff (1B left of kfence-#17): - test_out_of_bounds_read+0xa3/0x22b - kunit_try_run_case+0x51/0x85 + Out-of-bounds read at 0xffff8c3f2e291fff (1B left of kfence-#72): + test_out_of_bounds_read+0xa6/0x234 + kunit_try_run_case+0x61/0xa0 kunit_generic_run_threadfn_adapter+0x16/0x30 - kthread+0x137/0x160 + kthread+0x176/0x1b0 ret_from_fork+0x22/0x30 - kfence-#17 [0xffffffffb672f000-0xffffffffb672f01f, size=32, cache=kmalloc-32] allocated by task 507: - test_alloc+0xf3/0x25b - test_out_of_bounds_read+0x98/0x22b - kunit_try_run_case+0x51/0x85 + kfence-#72: 0xffff8c3f2e292000-0xffff8c3f2e29201f, size=32, cache=kmalloc-32 + + allocated by task 484 on cpu 0 at 32.919330s: + test_alloc+0xfe/0x738 + test_out_of_bounds_read+0x9b/0x234 + kunit_try_run_case+0x61/0xa0 kunit_generic_run_threadfn_adapter+0x16/0x30 - kthread+0x137/0x160 + kthread+0x176/0x1b0 ret_from_fork+0x22/0x30 - CPU: 4 PID: 107 Comm: kunit_try_catch Not tainted 5.8.0-rc6+ #7 - Hardware name: QEMU Standard PC (i440FX + PIIX, 1996), BIOS 1.13.0-1 04/01/2014 + CPU: 0 PID: 484 Comm: kunit_try_catch Not tainted 5.13.0-rc3+ #7 + Hardware name: QEMU Standard PC (i440FX + PIIX, 1996), BIOS 1.14.0-2 04/01/2014 ================================================================== The header of the report provides a short summary of the function involved in @@ -96,30 +98,32 @@ Use-after-free accesses are reported as:: ================================================================== BUG: KFENCE: use-after-free read in test_use_after_free_read+0xb3/0x143 - Use-after-free read at 0xffffffffb673dfe0 (in kfence-#24): + Use-after-free read at 0xffff8c3f2e2a0000 (in kfence-#79): test_use_after_free_read+0xb3/0x143 - kunit_try_run_case+0x51/0x85 + kunit_try_run_case+0x61/0xa0 kunit_generic_run_threadfn_adapter+0x16/0x30 - kthread+0x137/0x160 + kthread+0x176/0x1b0 ret_from_fork+0x22/0x30 - kfence-#24 [0xffffffffb673dfe0-0xffffffffb673dfff, size=32, cache=kmalloc-32] allocated by task 507: - test_alloc+0xf3/0x25b + kfence-#79: 0xffff8c3f2e2a0000-0xffff8c3f2e2a001f, size=32, cache=kmalloc-32 + + allocated by task 488 on cpu 2 at 33.871326s: + test_alloc+0xfe/0x738 test_use_after_free_read+0x76/0x143 - kunit_try_run_case+0x51/0x85 + kunit_try_run_case+0x61/0xa0 kunit_generic_run_threadfn_adapter+0x16/0x30 - kthread+0x137/0x160 + kthread+0x176/0x1b0 ret_from_fork+0x22/0x30 - freed by task 507: + freed by task 488 on cpu 2 at 33.871358s: test_use_after_free_read+0xa8/0x143 - kunit_try_run_case+0x51/0x85 + kunit_try_run_case+0x61/0xa0 kunit_generic_run_threadfn_adapter+0x16/0x30 - kthread+0x137/0x160 + kthread+0x176/0x1b0 ret_from_fork+0x22/0x30 - CPU: 4 PID: 109 Comm: kunit_try_catch Tainted: G W 5.8.0-rc6+ #7 - Hardware name: QEMU Standard PC (i440FX + PIIX, 1996), BIOS 1.13.0-1 04/01/2014 + CPU: 2 PID: 488 Comm: kunit_try_catch Tainted: G B 5.13.0-rc3+ #7 + Hardware name: QEMU Standard PC (i440FX + PIIX, 1996), BIOS 1.14.0-2 04/01/2014 ================================================================== KFENCE also reports on invalid frees, such as double-frees:: @@ -127,30 +131,32 @@ KFENCE also reports on invalid frees, such as double-frees:: ================================================================== BUG: KFENCE: invalid free in test_double_free+0xdc/0x171 - Invalid free of 0xffffffffb6741000: + Invalid free of 0xffff8c3f2e2a4000 (in kfence-#81): test_double_free+0xdc/0x171 - kunit_try_run_case+0x51/0x85 + kunit_try_run_case+0x61/0xa0 kunit_generic_run_threadfn_adapter+0x16/0x30 - kthread+0x137/0x160 + kthread+0x176/0x1b0 ret_from_fork+0x22/0x30 - kfence-#26 [0xffffffffb6741000-0xffffffffb674101f, size=32, cache=kmalloc-32] allocated by task 507: - test_alloc+0xf3/0x25b + kfence-#81: 0xffff8c3f2e2a4000-0xffff8c3f2e2a401f, size=32, cache=kmalloc-32 + + allocated by task 490 on cpu 1 at 34.175321s: + test_alloc+0xfe/0x738 test_double_free+0x76/0x171 - kunit_try_run_case+0x51/0x85 + kunit_try_run_case+0x61/0xa0 kunit_generic_run_threadfn_adapter+0x16/0x30 - kthread+0x137/0x160 + kthread+0x176/0x1b0 ret_from_fork+0x22/0x30 - freed by task 507: + freed by task 490 on cpu 1 at 34.175348s: test_double_free+0xa8/0x171 - kunit_try_run_case+0x51/0x85 + kunit_try_run_case+0x61/0xa0 kunit_generic_run_threadfn_adapter+0x16/0x30 - kthread+0x137/0x160 + kthread+0x176/0x1b0 ret_from_fork+0x22/0x30 - CPU: 4 PID: 111 Comm: kunit_try_catch Tainted: G W 5.8.0-rc6+ #7 - Hardware name: QEMU Standard PC (i440FX + PIIX, 1996), BIOS 1.13.0-1 04/01/2014 + CPU: 1 PID: 490 Comm: kunit_try_catch Tainted: G B 5.13.0-rc3+ #7 + Hardware name: QEMU Standard PC (i440FX + PIIX, 1996), BIOS 1.14.0-2 04/01/2014 ================================================================== KFENCE also uses pattern-based redzones on the other side of an object's guard @@ -160,23 +166,25 @@ These are reported on frees:: ================================================================== BUG: KFENCE: memory corruption in test_kmalloc_aligned_oob_write+0xef/0x184 - Corrupted memory at 0xffffffffb6797ff9 [ 0xac . . . . . . ] (in kfence-#69): + Corrupted memory at 0xffff8c3f2e33aff9 [ 0xac . . . . . . ] (in kfence-#156): test_kmalloc_aligned_oob_write+0xef/0x184 - kunit_try_run_case+0x51/0x85 + kunit_try_run_case+0x61/0xa0 kunit_generic_run_threadfn_adapter+0x16/0x30 - kthread+0x137/0x160 + kthread+0x176/0x1b0 ret_from_fork+0x22/0x30 - kfence-#69 [0xffffffffb6797fb0-0xffffffffb6797ff8, size=73, cache=kmalloc-96] allocated by task 507: - test_alloc+0xf3/0x25b + kfence-#156: 0xffff8c3f2e33afb0-0xffff8c3f2e33aff8, size=73, cache=kmalloc-96 + + allocated by task 502 on cpu 7 at 42.159302s: + test_alloc+0xfe/0x738 test_kmalloc_aligned_oob_write+0x57/0x184 - kunit_try_run_case+0x51/0x85 + kunit_try_run_case+0x61/0xa0 kunit_generic_run_threadfn_adapter+0x16/0x30 - kthread+0x137/0x160 + kthread+0x176/0x1b0 ret_from_fork+0x22/0x30 - CPU: 4 PID: 120 Comm: kunit_try_catch Tainted: G W 5.8.0-rc6+ #7 - Hardware name: QEMU Standard PC (i440FX + PIIX, 1996), BIOS 1.13.0-1 04/01/2014 + CPU: 7 PID: 502 Comm: kunit_try_catch Tainted: G B 5.13.0-rc3+ #7 + Hardware name: QEMU Standard PC (i440FX + PIIX, 1996), BIOS 1.14.0-2 04/01/2014 ================================================================== For such errors, the address where the corruption occurred as well as the diff --git a/Documentation/devicetree/bindings/cpufreq/cpufreq-dt.txt b/Documentation/devicetree/bindings/cpufreq/cpufreq-dt.txt index 56f442374383..1d7e49167666 100644 --- a/Documentation/devicetree/bindings/cpufreq/cpufreq-dt.txt +++ b/Documentation/devicetree/bindings/cpufreq/cpufreq-dt.txt @@ -11,7 +11,7 @@ Required properties: - None Optional properties: -- operating-points: Refer to Documentation/devicetree/bindings/opp/opp.txt for +- operating-points: Refer to Documentation/devicetree/bindings/opp/opp-v1.yaml for details. OPPs *must* be supplied either via DT, i.e. this property, or populated at runtime. - clock-latency: Specify the possible maximum transition latency for clock, diff --git a/Documentation/devicetree/bindings/cpufreq/cpufreq-mediatek-hw.yaml b/Documentation/devicetree/bindings/cpufreq/cpufreq-mediatek-hw.yaml new file mode 100644 index 000000000000..9cd42a64b13e --- /dev/null +++ b/Documentation/devicetree/bindings/cpufreq/cpufreq-mediatek-hw.yaml @@ -0,0 +1,70 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/cpufreq/cpufreq-mediatek-hw.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: MediaTek's CPUFREQ Bindings + +maintainers: + - Hector Yuan + +description: + CPUFREQ HW is a hardware engine used by MediaTek SoCs to + manage frequency in hardware. It is capable of controlling + frequency for multiple clusters. + +properties: + compatible: + const: mediatek,cpufreq-hw + + reg: + minItems: 1 + maxItems: 2 + description: + Addresses and sizes for the memory of the HW bases in + each frequency domain. Each entry corresponds to + a register bank for each frequency domain present. + + "#performance-domain-cells": + description: + Number of cells in a performance domain specifier. + Set const to 1 here for nodes providing multiple + performance domains. + const: 1 + +required: + - compatible + - reg + - "#performance-domain-cells" + +additionalProperties: false + +examples: + - | + cpus { + #address-cells = <1>; + #size-cells = <0>; + + cpu0: cpu@0 { + device_type = "cpu"; + compatible = "arm,cortex-a55"; + enable-method = "psci"; + performance-domains = <&performance 0>; + reg = <0x000>; + }; + }; + + /* ... */ + + soc { + #address-cells = <2>; + #size-cells = <2>; + + performance: performance-controller@11bc00 { + compatible = "mediatek,cpufreq-hw"; + reg = <0 0x0011bc10 0 0x120>, <0 0x0011bd30 0 0x120>; + + #performance-domain-cells = <1>; + }; + }; diff --git a/Documentation/devicetree/bindings/cpufreq/cpufreq-mediatek.txt b/Documentation/devicetree/bindings/cpufreq/cpufreq-mediatek.txt index ef68711716fb..b8233ec91d3d 100644 --- a/Documentation/devicetree/bindings/cpufreq/cpufreq-mediatek.txt +++ b/Documentation/devicetree/bindings/cpufreq/cpufreq-mediatek.txt @@ -10,7 +10,7 @@ Required properties: transition and not stable yet. Please refer to Documentation/devicetree/bindings/clock/clock-bindings.txt for generic clock consumer properties. -- operating-points-v2: Please refer to Documentation/devicetree/bindings/opp/opp.txt +- operating-points-v2: Please refer to Documentation/devicetree/bindings/opp/opp-v2.yaml for detail. - proc-supply: Regulator for Vproc of CPU cluster. diff --git a/Documentation/devicetree/bindings/cpufreq/cpufreq-st.txt b/Documentation/devicetree/bindings/cpufreq/cpufreq-st.txt index d91a02a3b6b0..6b0b452acef0 100644 --- a/Documentation/devicetree/bindings/cpufreq/cpufreq-st.txt +++ b/Documentation/devicetree/bindings/cpufreq/cpufreq-st.txt @@ -6,8 +6,6 @@ from the SoC, then supplies the OPP framework with 'prop' and 'supported hardware' information respectively. The framework is then able to read the DT and operate in the usual way. -For more information about the expected DT format [See: ../opp/opp.txt]. - Frequency Scaling only ---------------------- @@ -15,7 +13,7 @@ No vendor specific driver required for this. Located in CPU's node: -- operating-points : [See: ../power/opp.txt] +- operating-points : [See: ../power/opp-v1.yaml] Example [safe] -------------- @@ -37,7 +35,7 @@ This requires the ST CPUFreq driver to supply 'process' and 'version' info. Located in CPU's node: -- operating-points-v2 : [See ../power/opp.txt] +- operating-points-v2 : [See ../power/opp-v2.yaml] Example [unsafe] ---------------- diff --git a/Documentation/devicetree/bindings/cpufreq/nvidia,tegra20-cpufreq.txt b/Documentation/devicetree/bindings/cpufreq/nvidia,tegra20-cpufreq.txt index 52a24b82fd86..bdbfd7c36101 100644 --- a/Documentation/devicetree/bindings/cpufreq/nvidia,tegra20-cpufreq.txt +++ b/Documentation/devicetree/bindings/cpufreq/nvidia,tegra20-cpufreq.txt @@ -4,7 +4,7 @@ Binding for NVIDIA Tegra20 CPUFreq Required properties: - clocks: Must contain an entry for the CPU clock. See ../clocks/clock-bindings.txt for details. -- operating-points-v2: See ../bindings/opp/opp.txt for details. +- operating-points-v2: See ../bindings/opp/opp-v2.yaml for details. - #cooling-cells: Should be 2. See ../thermal/thermal-cooling-devices.yaml for details. For each opp entry in 'operating-points-v2' table: diff --git a/Documentation/devicetree/bindings/devfreq/rk3399_dmc.txt b/Documentation/devicetree/bindings/devfreq/rk3399_dmc.txt index ac189dd82b08..3fbeb3733c48 100644 --- a/Documentation/devicetree/bindings/devfreq/rk3399_dmc.txt +++ b/Documentation/devicetree/bindings/devfreq/rk3399_dmc.txt @@ -8,7 +8,7 @@ Required properties: - clocks: Phandles for clock specified in "clock-names" property - clock-names : The name of clock used by the DFI, must be "pclk_ddr_mon"; -- operating-points-v2: Refer to Documentation/devicetree/bindings/opp/opp.txt +- operating-points-v2: Refer to Documentation/devicetree/bindings/opp/opp-v2.yaml for details. - center-supply: DMC supply node. - status: Marks the node enabled/disabled. diff --git a/Documentation/devicetree/bindings/display/msm/dsi-phy-7nm.yaml b/Documentation/devicetree/bindings/display/msm/dsi-phy-7nm.yaml index 4265399bb154..c851770bbdf2 100644 --- a/Documentation/devicetree/bindings/display/msm/dsi-phy-7nm.yaml +++ b/Documentation/devicetree/bindings/display/msm/dsi-phy-7nm.yaml @@ -14,10 +14,10 @@ allOf: properties: compatible: - oneOf: - - const: qcom,dsi-phy-7nm - - const: qcom,dsi-phy-7nm-8150 - - const: qcom,sc7280-dsi-phy-7nm + enum: + - qcom,dsi-phy-7nm + - qcom,dsi-phy-7nm-8150 + - qcom,sc7280-dsi-phy-7nm reg: items: diff --git a/Documentation/devicetree/bindings/dma/altr,msgdma.yaml b/Documentation/devicetree/bindings/dma/altr,msgdma.yaml index a4f9fe23dcd9..b193ee2db4a7 100644 --- a/Documentation/devicetree/bindings/dma/altr,msgdma.yaml +++ b/Documentation/devicetree/bindings/dma/altr,msgdma.yaml @@ -24,13 +24,15 @@ properties: items: - description: Control and Status Register Slave Port - description: Descriptor Slave Port - - description: Response Slave Port + - description: Response Slave Port (Optional) + minItems: 2 reg-names: items: - const: csr - const: desc - const: resp + minItems: 2 interrupts: maxItems: 1 diff --git a/Documentation/devicetree/bindings/dma/renesas,rz-dmac.yaml b/Documentation/devicetree/bindings/dma/renesas,rz-dmac.yaml new file mode 100644 index 000000000000..7a4f415d74dc --- /dev/null +++ b/Documentation/devicetree/bindings/dma/renesas,rz-dmac.yaml @@ -0,0 +1,130 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/dma/renesas,rz-dmac.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Renesas RZ/G2L DMA Controller + +maintainers: + - Biju Das + +allOf: + - $ref: "dma-controller.yaml#" + +properties: + compatible: + items: + - enum: + - renesas,r9a07g044-dmac # RZ/G2{L,LC} + - const: renesas,rz-dmac + + reg: + items: + - description: Control and channel register block + - description: DMA extended resource selector block + + interrupts: + maxItems: 17 + + interrupt-names: + items: + - const: error + - const: ch0 + - const: ch1 + - const: ch2 + - const: ch3 + - const: ch4 + - const: ch5 + - const: ch6 + - const: ch7 + - const: ch8 + - const: ch9 + - const: ch10 + - const: ch11 + - const: ch12 + - const: ch13 + - const: ch14 + - const: ch15 + + clocks: + items: + - description: DMA main clock + - description: DMA register access clock + + '#dma-cells': + const: 1 + description: + The cell specifies the encoded MID/RID values of the DMAC port + connected to the DMA client and the slave channel configuration + parameters. + bits[0:9] - Specifies MID/RID value + bit[10] - Specifies DMA request high enable (HIEN) + bit[11] - Specifies DMA request detection type (LVL) + bits[12:14] - Specifies DMAACK output mode (AM) + bit[15] - Specifies Transfer Mode (TM) + + dma-channels: + const: 16 + + power-domains: + maxItems: 1 + + resets: + items: + - description: Reset for DMA ARESETN reset terminal + - description: Reset for DMA RST_ASYNC reset terminal + +required: + - compatible + - reg + - interrupts + - interrupt-names + - clocks + - '#dma-cells' + - dma-channels + - power-domains + - resets + +additionalProperties: false + +examples: + - | + #include + #include + + dmac: dma-controller@11820000 { + compatible = "renesas,r9a07g044-dmac", + "renesas,rz-dmac"; + reg = <0x11820000 0x10000>, + <0x11830000 0x10000>; + interrupts = , + , + , + , + , + , + , + , + , + , + , + , + , + , + , + , + ; + interrupt-names = "error", + "ch0", "ch1", "ch2", "ch3", + "ch4", "ch5", "ch6", "ch7", + "ch8", "ch9", "ch10", "ch11", + "ch12", "ch13", "ch14", "ch15"; + clocks = <&cpg CPG_MOD R9A07G044_DMAC_ACLK>, + <&cpg CPG_MOD R9A07G044_DMAC_PCLK>; + power-domains = <&cpg>; + resets = <&cpg R9A07G044_DMAC_ARESETN>, + <&cpg R9A07G044_DMAC_RST_ASYNC>; + #dma-cells = <1>; + dma-channels = <16>; + }; diff --git a/Documentation/devicetree/bindings/dma/st,stm32-dma.yaml b/Documentation/devicetree/bindings/dma/st,stm32-dma.yaml index 2a5325f480f6..4bf676fd25dc 100644 --- a/Documentation/devicetree/bindings/dma/st,stm32-dma.yaml +++ b/Documentation/devicetree/bindings/dma/st,stm32-dma.yaml @@ -40,6 +40,13 @@ description: | 0x0: FIFO mode with threshold selectable with bit 0-1 0x1: Direct mode: each DMA request immediately initiates a transfer from/to the memory, FIFO is bypassed. + -bit 4: alternative DMA request/acknowledge protocol + 0x0: Use standard DMA ACK management, where ACK signal is maintained + up to the removal of request and transfer completion + 0x1: Use alternative DMA ACK management, where ACK de-assertion does + not wait for the de-assertion of the REQuest, ACK is only managed + by transfer completion. This must only be used on channels + managing transfers for STM32 USART/UART. maintainers: diff --git a/Documentation/devicetree/bindings/gpio/gpio-virtio.yaml b/Documentation/devicetree/bindings/gpio/gpio-virtio.yaml new file mode 100644 index 000000000000..601d85754577 --- /dev/null +++ b/Documentation/devicetree/bindings/gpio/gpio-virtio.yaml @@ -0,0 +1,59 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/gpio/gpio-virtio.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Virtio GPIO controller + +maintainers: + - Viresh Kumar + +allOf: + - $ref: /schemas/virtio/virtio-device.yaml# + +description: + Virtio GPIO controller, see /schemas/virtio/virtio-device.yaml for more + details. + +properties: + $nodename: + const: gpio + + compatible: + const: virtio,device29 + + gpio-controller: true + + "#gpio-cells": + const: 2 + + interrupt-controller: true + + "#interrupt-cells": + const: 2 + +required: + - compatible + - gpio-controller + - "#gpio-cells" + +unevaluatedProperties: false + +examples: + - | + virtio@3000 { + compatible = "virtio,mmio"; + reg = <0x3000 0x100>; + interrupts = <41>; + + gpio { + compatible = "virtio,device29"; + gpio-controller; + #gpio-cells = <2>; + interrupt-controller; + #interrupt-cells = <2>; + }; + }; + +... diff --git a/Documentation/devicetree/bindings/gpu/arm,mali-bifrost.yaml b/Documentation/devicetree/bindings/gpu/arm,mali-bifrost.yaml index c5f6092a2855..6f98dd55fb4c 100644 --- a/Documentation/devicetree/bindings/gpu/arm,mali-bifrost.yaml +++ b/Documentation/devicetree/bindings/gpu/arm,mali-bifrost.yaml @@ -137,7 +137,7 @@ examples: resets = <&reset 0>, <&reset 1>; }; - gpu_opp_table: opp_table0 { + gpu_opp_table: opp-table { compatible = "operating-points-v2"; opp-533000000 { diff --git a/Documentation/devicetree/bindings/gpu/arm,mali-midgard.yaml b/Documentation/devicetree/bindings/gpu/arm,mali-midgard.yaml index 696c17aedbbe..d209f272625d 100644 --- a/Documentation/devicetree/bindings/gpu/arm,mali-midgard.yaml +++ b/Documentation/devicetree/bindings/gpu/arm,mali-midgard.yaml @@ -160,7 +160,7 @@ examples: #cooling-cells = <2>; }; - gpu_opp_table: opp_table0 { + gpu_opp_table: opp-table { compatible = "operating-points-v2"; opp-533000000 { diff --git a/Documentation/devicetree/bindings/i2c/i2c-virtio.yaml b/Documentation/devicetree/bindings/i2c/i2c-virtio.yaml new file mode 100644 index 000000000000..7d87ed855301 --- /dev/null +++ b/Documentation/devicetree/bindings/i2c/i2c-virtio.yaml @@ -0,0 +1,51 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/i2c/i2c-virtio.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Virtio I2C Adapter + +maintainers: + - Viresh Kumar + +allOf: + - $ref: /schemas/i2c/i2c-controller.yaml# + - $ref: /schemas/virtio/virtio-device.yaml# + +description: + Virtio I2C device, see /schemas/virtio/virtio-device.yaml for more details. + +properties: + $nodename: + const: i2c + + compatible: + const: virtio,device22 + +required: + - compatible + +unevaluatedProperties: false + +examples: + - | + virtio@3000 { + compatible = "virtio,mmio"; + reg = <0x3000 0x100>; + interrupts = <41>; + + i2c { + compatible = "virtio,device22"; + + #address-cells = <1>; + #size-cells = <0>; + + light-sensor@20 { + compatible = "dynaimage,al3320a"; + reg = <0x20>; + }; + }; + }; + +... diff --git a/Documentation/devicetree/bindings/input/allwinner,sun4i-a10-lradc-keys.yaml b/Documentation/devicetree/bindings/input/allwinner,sun4i-a10-lradc-keys.yaml index cffd02028d02..d74f2002409e 100644 --- a/Documentation/devicetree/bindings/input/allwinner,sun4i-a10-lradc-keys.yaml +++ b/Documentation/devicetree/bindings/input/allwinner,sun4i-a10-lradc-keys.yaml @@ -29,6 +29,8 @@ properties: description: Regulator for the LRADC reference voltage + wakeup-source: true + patternProperties: "^button-[0-9]+$": type: object diff --git a/Documentation/devicetree/bindings/input/qcom,pm8941-pwrkey.txt b/Documentation/devicetree/bindings/input/qcom,pm8941-pwrkey.txt deleted file mode 100644 index 6cd08bca2c66..000000000000 --- a/Documentation/devicetree/bindings/input/qcom,pm8941-pwrkey.txt +++ /dev/null @@ -1,55 +0,0 @@ -Qualcomm PM8941 PMIC Power Key - -PROPERTIES - -- compatible: - Usage: required - Value type: - Definition: must be one of: - "qcom,pm8941-pwrkey" - "qcom,pm8941-resin" - "qcom,pmk8350-pwrkey" - "qcom,pmk8350-resin" - -- reg: - Usage: required - Value type: - Definition: base address of registers for block - -- interrupts: - Usage: required - Value type: - Definition: key change interrupt; The format of the specifier is - defined by the binding document describing the node's - interrupt parent. - -- debounce: - Usage: optional - Value type: - Definition: time in microseconds that key must be pressed or released - for state change interrupt to trigger. - -- bias-pull-up: - Usage: optional - Value type: - Definition: presence of this property indicates that the KPDPWR_N pin - should be configured for pull up. - -- linux,code: - Usage: optional - Value type: - Definition: The input key-code associated with the power key. - Use the linux event codes defined in - include/dt-bindings/input/linux-event-codes.h - When property is omitted KEY_POWER is assumed. - -EXAMPLE - - pwrkey@800 { - compatible = "qcom,pm8941-pwrkey"; - reg = <0x800>; - interrupts = <0x0 0x8 0 IRQ_TYPE_EDGE_BOTH>; - debounce = <15625>; - bias-pull-up; - linux,code = ; - }; diff --git a/Documentation/devicetree/bindings/input/qcom,pm8941-pwrkey.yaml b/Documentation/devicetree/bindings/input/qcom,pm8941-pwrkey.yaml new file mode 100644 index 000000000000..62314a5fdce5 --- /dev/null +++ b/Documentation/devicetree/bindings/input/qcom,pm8941-pwrkey.yaml @@ -0,0 +1,51 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/input/qcom,pm8941-pwrkey.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Qualcomm PM8941 PMIC Power Key + +maintainers: + - Courtney Cavin + - Vinod Koul + +allOf: + - $ref: input.yaml# + +properties: + compatible: + enum: + - qcom,pm8941-pwrkey + - qcom,pm8941-resin + - qcom,pmk8350-pwrkey + - qcom,pmk8350-resin + + interrupts: + maxItems: 1 + + debounce: + description: | + Time in microseconds that key must be pressed or + released for state change interrupt to trigger. + $ref: /schemas/types.yaml#/definitions/uint32 + + bias-pull-up: + description: | + Presence of this property indicates that the KPDPWR_N + pin should be configured for pull up. + $ref: /schemas/types.yaml#/definitions/flag + + linux,code: + description: | + The input key-code associated with the power key. + Use the linux event codes defined in + include/dt-bindings/input/linux-event-codes.h + When property is omitted KEY_POWER is assumed. + +required: + - compatible + - interrupts + +unevaluatedProperties: false +... diff --git a/Documentation/devicetree/bindings/input/regulator-haptic.txt b/Documentation/devicetree/bindings/input/regulator-haptic.txt deleted file mode 100644 index 3ed1c7eb2f97..000000000000 --- a/Documentation/devicetree/bindings/input/regulator-haptic.txt +++ /dev/null @@ -1,21 +0,0 @@ -* Regulator Haptic Device Tree Bindings - -Required Properties: - - compatible : Should be "regulator-haptic" - - haptic-supply : Power supply to the haptic motor. - [*] refer Documentation/devicetree/bindings/regulator/regulator.txt - - - max-microvolt : The maximum voltage value supplied to the haptic motor. - [The unit of the voltage is a micro] - - - min-microvolt : The minimum voltage value supplied to the haptic motor. - [The unit of the voltage is a micro] - -Example: - - haptics { - compatible = "regulator-haptic"; - haptic-supply = <&motor_regulator>; - max-microvolt = <2700000>; - min-microvolt = <1100000>; - }; diff --git a/Documentation/devicetree/bindings/input/regulator-haptic.yaml b/Documentation/devicetree/bindings/input/regulator-haptic.yaml new file mode 100644 index 000000000000..b1ae72f9cd2d --- /dev/null +++ b/Documentation/devicetree/bindings/input/regulator-haptic.yaml @@ -0,0 +1,43 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: "http://devicetree.org/schemas/input/regulator-haptic.yaml#" +$schema: "http://devicetree.org/meta-schemas/core.yaml#" + +title: Regulator Haptic Device Tree Bindings + +maintainers: + - Jaewon Kim + +properties: + compatible: + const: regulator-haptic + + haptic-supply: + description: > + Power supply to the haptic motor + + max-microvolt: + description: > + The maximum voltage value supplied to the haptic motor + + min-microvolt: + description: > + The minimum voltage value supplied to the haptic motor + +required: + - compatible + - haptic-supply + - max-microvolt + - min-microvolt + +additionalProperties: false + +examples: + - | + haptics { + compatible = "regulator-haptic"; + haptic-supply = <&motor_regulator>; + max-microvolt = <2700000>; + min-microvolt = <1100000>; + }; diff --git a/Documentation/devicetree/bindings/input/touchscreen/chipone,icn8318.yaml b/Documentation/devicetree/bindings/input/touchscreen/chipone,icn8318.yaml new file mode 100644 index 000000000000..9df685bdc5db --- /dev/null +++ b/Documentation/devicetree/bindings/input/touchscreen/chipone,icn8318.yaml @@ -0,0 +1,62 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/input/touchscreen/chipone,icn8318.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: ChipOne ICN8318 Touchscreen Controller Device Tree Bindings + +maintainers: + - Dmitry Torokhov + +allOf: + - $ref: touchscreen.yaml# + +properties: + compatible: + const: chipone,icn8318 + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + wake-gpios: + maxItems: 1 + +unevaluatedProperties: false + +required: + - compatible + - reg + - interrupts + - wake-gpios + - touchscreen-size-x + - touchscreen-size-y + +examples: + - | + #include + #include + + i2c { + #address-cells = <1>; + #size-cells = <0>; + + touchscreen@40 { + compatible = "chipone,icn8318"; + reg = <0x40>; + interrupt-parent = <&pio>; + interrupts = <9 IRQ_TYPE_EDGE_FALLING>; /* EINT9 (PG9) */ + pinctrl-names = "default"; + pinctrl-0 = <&ts_wake_pin_p66>; + wake-gpios = <&pio 1 3 GPIO_ACTIVE_HIGH>; /* PB3 */ + touchscreen-size-x = <800>; + touchscreen-size-y = <480>; + touchscreen-inverted-x; + touchscreen-swapped-x-y; + }; + }; + +... diff --git a/Documentation/devicetree/bindings/input/touchscreen/chipone_icn8318.txt b/Documentation/devicetree/bindings/input/touchscreen/chipone_icn8318.txt deleted file mode 100644 index 38b0603f65f3..000000000000 --- a/Documentation/devicetree/bindings/input/touchscreen/chipone_icn8318.txt +++ /dev/null @@ -1,44 +0,0 @@ -* ChipOne icn8318 I2C touchscreen controller - -Required properties: - - compatible : "chipone,icn8318" - - reg : I2C slave address of the chip (0x40) - - interrupts : interrupt specification for the icn8318 interrupt - - wake-gpios : GPIO specification for the WAKE input - - touchscreen-size-x : horizontal resolution of touchscreen (in pixels) - - touchscreen-size-y : vertical resolution of touchscreen (in pixels) - -Optional properties: - - pinctrl-names : should be "default" - - pinctrl-0: : a phandle pointing to the pin settings for the - control gpios - - touchscreen-fuzz-x : horizontal noise value of the absolute input - device (in pixels) - - touchscreen-fuzz-y : vertical noise value of the absolute input - device (in pixels) - - touchscreen-inverted-x : X axis is inverted (boolean) - - touchscreen-inverted-y : Y axis is inverted (boolean) - - touchscreen-swapped-x-y : X and Y axis are swapped (boolean) - Swapping is done after inverting the axis - -Example: - -i2c@00000000 { - /* ... */ - - chipone_icn8318@40 { - compatible = "chipone,icn8318"; - reg = <0x40>; - interrupt-parent = <&pio>; - interrupts = <9 IRQ_TYPE_EDGE_FALLING>; /* EINT9 (PG9) */ - pinctrl-names = "default"; - pinctrl-0 = <&ts_wake_pin_p66>; - wake-gpios = <&pio 1 3 GPIO_ACTIVE_HIGH>; /* PB3 */ - touchscreen-size-x = <800>; - touchscreen-size-y = <480>; - touchscreen-inverted-x; - touchscreen-swapped-x-y; - }; - - /* ... */ -}; diff --git a/Documentation/devicetree/bindings/input/touchscreen/pixcir,pixcir_ts.yaml b/Documentation/devicetree/bindings/input/touchscreen/pixcir,pixcir_ts.yaml new file mode 100644 index 000000000000..f9998edbff70 --- /dev/null +++ b/Documentation/devicetree/bindings/input/touchscreen/pixcir,pixcir_ts.yaml @@ -0,0 +1,68 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/input/touchscreen/pixcir,pixcir_ts.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Pixcir Touchscreen Controller Device Tree Bindings + +maintainers: + - Dmitry Torokhov + +allOf: + - $ref: touchscreen.yaml# + +properties: + compatible: + enum: + - pixcir,pixcir_ts + - pixcir,pixcir_tangoc + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + attb-gpio: + maxItems: 1 + + reset-gpios: + maxItems: 1 + + enable-gpios: + maxItems: 1 + + wake-gpios: + maxItems: 1 + +unevaluatedProperties: false + +required: + - compatible + - reg + - interrupts + - attb-gpio + - touchscreen-size-x + - touchscreen-size-y + +examples: + - | + #include + #include + + i2c { + #address-cells = <1>; + #size-cells = <0>; + + touchscreen@5c { + compatible = "pixcir,pixcir_ts"; + reg = <0x5c>; + interrupts = <2 0>; + attb-gpio = <&gpf 2 0 2>; + touchscreen-size-x = <800>; + touchscreen-size-y = <600>; + }; + }; + +... diff --git a/Documentation/devicetree/bindings/input/touchscreen/pixcir_i2c_ts.txt b/Documentation/devicetree/bindings/input/touchscreen/pixcir_i2c_ts.txt deleted file mode 100644 index 697a3e7831e7..000000000000 --- a/Documentation/devicetree/bindings/input/touchscreen/pixcir_i2c_ts.txt +++ /dev/null @@ -1,31 +0,0 @@ -* Pixcir I2C touchscreen controllers - -Required properties: -- compatible: must be "pixcir,pixcir_ts" or "pixcir,pixcir_tangoc" -- reg: I2C address of the chip -- interrupts: interrupt to which the chip is connected -- attb-gpio: GPIO connected to the ATTB line of the chip -- touchscreen-size-x: horizontal resolution of touchscreen (in pixels) -- touchscreen-size-y: vertical resolution of touchscreen (in pixels) - -Optional properties: -- reset-gpios: GPIO connected to the RESET line of the chip -- enable-gpios: GPIO connected to the ENABLE line of the chip -- wake-gpios: GPIO connected to the WAKE line of the chip - -Example: - - i2c@00000000 { - /* ... */ - - pixcir_ts@5c { - compatible = "pixcir,pixcir_ts"; - reg = <0x5c>; - interrupts = <2 0>; - attb-gpio = <&gpf 2 0 2>; - touchscreen-size-x = <800>; - touchscreen-size-y = <600>; - }; - - /* ... */ - }; diff --git a/Documentation/devicetree/bindings/input/touchscreen/ti,tsc2005.yaml b/Documentation/devicetree/bindings/input/touchscreen/ti,tsc2005.yaml new file mode 100644 index 000000000000..938aab016cc2 --- /dev/null +++ b/Documentation/devicetree/bindings/input/touchscreen/ti,tsc2005.yaml @@ -0,0 +1,128 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/input/touchscreen/ti,tsc2005.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Texas Instruments TSC2004 and TSC2005 touchscreen controller bindings + +maintainers: + - Marek Vasut + - Michael Welling + +properties: + $nodename: + pattern: "^touchscreen(@.*)?$" + + compatible: + enum: + - ti,tsc2004 + - ti,tsc2005 + + reg: + maxItems: 1 + description: | + I2C address when used on the I2C bus, or the SPI chip select index + when used on the SPI bus + + interrupts: + maxItems: 1 + + reset-gpios: + maxItems: 1 + description: GPIO specifier for the controller reset line + + spi-max-frequency: + description: TSC2005 SPI bus clock frequency. + maximum: 25000000 + + ti,x-plate-ohms: + description: resistance of the touchscreen's X plates in ohm (defaults to 280) + + ti,esd-recovery-timeout-ms: + description: | + if the touchscreen does not respond after the configured time + (in milli seconds), the driver will reset it. This is disabled + by default. + + vio-supply: + description: Regulator specifier + + touchscreen-fuzz-pressure: true + touchscreen-fuzz-x: true + touchscreen-fuzz-y: true + touchscreen-max-pressure: true + touchscreen-size-x: true + touchscreen-size-y: true + +allOf: + - $ref: touchscreen.yaml# + - if: + properties: + compatible: + contains: + const: ti,tsc2004 + then: + properties: + spi-max-frequency: false + +additionalProperties: false + +required: + - compatible + - reg + - interrupts + +examples: + - | + #include + #include + i2c { + #address-cells = <1>; + #size-cells = <0>; + touchscreen@48 { + compatible = "ti,tsc2004"; + reg = <0x48>; + vio-supply = <&vio>; + + reset-gpios = <&gpio4 8 GPIO_ACTIVE_HIGH>; + interrupts-extended = <&gpio1 27 IRQ_TYPE_EDGE_RISING>; + + touchscreen-fuzz-x = <4>; + touchscreen-fuzz-y = <7>; + touchscreen-fuzz-pressure = <2>; + touchscreen-size-x = <4096>; + touchscreen-size-y = <4096>; + touchscreen-max-pressure = <2048>; + + ti,x-plate-ohms = <280>; + ti,esd-recovery-timeout-ms = <8000>; + }; + }; + - | + #include + #include + spi { + #address-cells = <1>; + #size-cells = <0>; + touchscreen@0 { + compatible = "ti,tsc2005"; + spi-max-frequency = <6000000>; + reg = <0>; + + vio-supply = <&vio>; + + reset-gpios = <&gpio4 8 GPIO_ACTIVE_HIGH>; /* 104 */ + interrupts-extended = <&gpio4 4 IRQ_TYPE_EDGE_RISING>; /* 100 */ + + touchscreen-fuzz-x = <4>; + touchscreen-fuzz-y = <7>; + touchscreen-fuzz-pressure = <2>; + touchscreen-size-x = <4096>; + touchscreen-size-y = <4096>; + touchscreen-max-pressure = <2048>; + + ti,x-plate-ohms = <280>; + ti,esd-recovery-timeout-ms = <8000>; + }; + }; diff --git a/Documentation/devicetree/bindings/input/touchscreen/tsc2005.txt b/Documentation/devicetree/bindings/input/touchscreen/tsc2005.txt deleted file mode 100644 index b80c04b0e5c0..000000000000 --- a/Documentation/devicetree/bindings/input/touchscreen/tsc2005.txt +++ /dev/null @@ -1,64 +0,0 @@ -* Texas Instruments tsc2004 and tsc2005 touchscreen controllers - -Required properties: - - compatible : "ti,tsc2004" or "ti,tsc2005" - - reg : Device address - - interrupts : IRQ specifier - - spi-max-frequency : Maximum SPI clocking speed of the device - (for tsc2005) - -Optional properties: - - vio-supply : Regulator specifier - - reset-gpios : GPIO specifier for the controller reset line - - ti,x-plate-ohms : integer, resistance of the touchscreen's X plates - in ohm (defaults to 280) - - ti,esd-recovery-timeout-ms : integer, if the touchscreen does not respond after - the configured time (in milli seconds), the driver - will reset it. This is disabled by default. - - properties defined in touchscreen.txt - -Example: - -&i2c3 { - tsc2004@48 { - compatible = "ti,tsc2004"; - reg = <0x48>; - vio-supply = <&vio>; - - reset-gpios = <&gpio4 8 GPIO_ACTIVE_HIGH>; - interrupts-extended = <&gpio1 27 IRQ_TYPE_EDGE_RISING>; - - touchscreen-fuzz-x = <4>; - touchscreen-fuzz-y = <7>; - touchscreen-fuzz-pressure = <2>; - touchscreen-size-x = <4096>; - touchscreen-size-y = <4096>; - touchscreen-max-pressure = <2048>; - - ti,x-plate-ohms = <280>; - ti,esd-recovery-timeout-ms = <8000>; - }; -} - -&mcspi1 { - tsc2005@0 { - compatible = "ti,tsc2005"; - spi-max-frequency = <6000000>; - reg = <0>; - - vio-supply = <&vio>; - - reset-gpios = <&gpio4 8 GPIO_ACTIVE_HIGH>; /* 104 */ - interrupts-extended = <&gpio4 4 IRQ_TYPE_EDGE_RISING>; /* 100 */ - - touchscreen-fuzz-x = <4>; - touchscreen-fuzz-y = <7>; - touchscreen-fuzz-pressure = <2>; - touchscreen-size-x = <4096>; - touchscreen-size-y = <4096>; - touchscreen-max-pressure = <2048>; - - ti,x-plate-ohms = <280>; - ti,esd-recovery-timeout-ms = <8000>; - }; -} diff --git a/Documentation/devicetree/bindings/interconnect/fsl,imx8m-noc.yaml b/Documentation/devicetree/bindings/interconnect/fsl,imx8m-noc.yaml index a8873739d61a..b8204ed22dd5 100644 --- a/Documentation/devicetree/bindings/interconnect/fsl,imx8m-noc.yaml +++ b/Documentation/devicetree/bindings/interconnect/fsl,imx8m-noc.yaml @@ -81,10 +81,10 @@ examples: noc_opp_table: opp-table { compatible = "operating-points-v2"; - opp-133M { + opp-133333333 { opp-hz = /bits/ 64 <133333333>; }; - opp-800M { + opp-800000000 { opp-hz = /bits/ 64 <800000000>; }; }; diff --git a/Documentation/devicetree/bindings/mfd/axp20x.txt b/Documentation/devicetree/bindings/mfd/axp20x.txt index 4991a6415796..2b53dcc0ea61 100644 --- a/Documentation/devicetree/bindings/mfd/axp20x.txt +++ b/Documentation/devicetree/bindings/mfd/axp20x.txt @@ -26,10 +26,10 @@ Required properties: * "x-powers,axp803" * "x-powers,axp806" * "x-powers,axp805", "x-powers,axp806" + * "x-powers,axp305", "x-powers,axp805", "x-powers,axp806" * "x-powers,axp809" * "x-powers,axp813" - reg: The I2C slave address or RSB hardware address for the AXP chip -- interrupts: SoC NMI / GPIO interrupt connected to the PMIC's IRQ pin - interrupt-controller: The PMIC has its own internal IRQs - #interrupt-cells: Should be set to 1 @@ -43,6 +43,7 @@ more information: AXP20x/LDO3: software-based implementation Optional properties: +- interrupts: SoC NMI / GPIO interrupt connected to the PMIC's IRQ pin - x-powers,dcdc-freq: defines the work frequency of DC-DC in KHz AXP152/20X: range: 750-1875, Default: 1.5 MHz AXP22X/8XX: range: 1800-4050, Default: 3 MHz diff --git a/Documentation/devicetree/bindings/mfd/brcm,cru.yaml b/Documentation/devicetree/bindings/mfd/brcm,cru.yaml new file mode 100644 index 000000000000..fc1317ab3226 --- /dev/null +++ b/Documentation/devicetree/bindings/mfd/brcm,cru.yaml @@ -0,0 +1,86 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/mfd/brcm,cru.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Broadcom CRU + +maintainers: + - Rafał Miłecki + +description: | + Broadcom CRU ("Clock and Reset Unit" or "Central Resource Unit") is a hardware + block grouping smaller blocks. On Broadcom Northstar platform it contains e.g. + clocks, pinctrl, USB PHY and thermal. + +properties: + compatible: + items: + - enum: + - brcm,ns-cru + - const: simple-mfd + + reg: + description: CRU registers + + ranges: true + + "#address-cells": + const: 1 + + "#size-cells": + const: 1 + + pinctrl: + $ref: ../pinctrl/brcm,ns-pinmux.yaml + +patternProperties: + '^clock-controller@[a-f0-9]+$': + $ref: ../clock/brcm,iproc-clocks.yaml + + '^thermal@[a-f0-9]+$': + $ref: ../thermal/brcm,ns-thermal.yaml + +additionalProperties: false + +required: + - reg + +examples: + - | + cru-bus@1800c100 { + compatible = "brcm,ns-cru", "simple-mfd"; + reg = <0x1800c100 0x1d0>; + ranges; + #address-cells = <1>; + #size-cells = <1>; + + clock-controller@100 { + #clock-cells = <1>; + compatible = "brcm,nsp-lcpll0"; + reg = <0x100 0x14>; + clocks = <&osc>; + clock-output-names = "lcpll0", "pcie_phy", "sdio", "ddr_phy"; + }; + + clock-controller@140 { + #clock-cells = <1>; + compatible = "brcm,nsp-genpll"; + reg = <0x140 0x24>; + clocks = <&osc>; + clock-output-names = "genpll", "phy", "ethernetclk", "usbclk", + "iprocfast", "sata1", "sata2"; + }; + + pinctrl { + compatible = "brcm,bcm4708-pinmux"; + offset = <0x1c0>; + }; + + thermal@2c0 { + compatible = "brcm,ns-thermal"; + reg = <0x2c0 0x10>; + #thermal-sensor-cells = <0>; + }; + }; diff --git a/Documentation/devicetree/bindings/mfd/qcom,pm8008.yaml b/Documentation/devicetree/bindings/mfd/qcom,pm8008.yaml index 779936850ee0..ec3138c1bbfc 100644 --- a/Documentation/devicetree/bindings/mfd/qcom,pm8008.yaml +++ b/Documentation/devicetree/bindings/mfd/qcom,pm8008.yaml @@ -53,7 +53,9 @@ patternProperties: properties: compatible: - const: qcom,pm8008-gpio + items: + - const: qcom,pm8008-gpio + - const: qcom,spmi-gpio reg: description: Peripheral address of one of the two GPIO peripherals. @@ -61,6 +63,9 @@ patternProperties: gpio-controller: true + gpio-ranges: + maxItems: 1 + interrupt-controller: true "#interrupt-cells": @@ -75,6 +80,7 @@ patternProperties: - gpio-controller - interrupt-controller - "#gpio-cells" + - gpio-ranges - "#interrupt-cells" additionalProperties: false @@ -107,10 +113,11 @@ examples: interrupt-parent = <&tlmm>; interrupts = <32 IRQ_TYPE_EDGE_RISING>; - gpio@c000 { - compatible = "qcom,pm8008-gpio"; + pm8008_gpios: gpio@c000 { + compatible = "qcom,pm8008-gpio", "qcom,spmi-gpio"; reg = <0xc000>; gpio-controller; + gpio-ranges = <&pm8008_gpios 0 0 2>; #gpio-cells = <2>; interrupt-controller; #interrupt-cells = <2>; diff --git a/Documentation/devicetree/bindings/mfd/syscon.yaml b/Documentation/devicetree/bindings/mfd/syscon.yaml index f14ae6da0068..abe3fd817e0b 100644 --- a/Documentation/devicetree/bindings/mfd/syscon.yaml +++ b/Documentation/devicetree/bindings/mfd/syscon.yaml @@ -45,9 +45,12 @@ properties: - microchip,sparx5-cpu-syscon - mstar,msc313-pmsleep - rockchip,px30-qos + - rockchip,rk3036-qos - rockchip,rk3066-qos + - rockchip,rk3228-qos - rockchip,rk3288-qos - rockchip,rk3399-qos + - rockchip,rk3568-qos - samsung,exynos3-sysreg - samsung,exynos4-sysreg - samsung,exynos5-sysreg diff --git a/Documentation/devicetree/bindings/mfd/ti,tps65086.yaml b/Documentation/devicetree/bindings/mfd/ti,tps65086.yaml new file mode 100644 index 000000000000..6aeedda3be15 --- /dev/null +++ b/Documentation/devicetree/bindings/mfd/ti,tps65086.yaml @@ -0,0 +1,124 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/mfd/ti,tps65086.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: TPS65086 Power Management Integrated Circuit (PMIC) + +maintainers: + - Emil Renner Berthing + +properties: + compatible: + const: ti,tps65086 + + reg: + const: 0x5e + description: I2C slave address + + interrupts: + maxItems: 1 + + interrupt-controller: true + + '#interrupt-cells': + const: 2 + description: | + The first cell is the IRQ number. The second cell is the flags, + encoded as trigger masks from ../interrupt-controller/interrupts.txt. + + gpio-controller: true + + '#gpio-cells': + const: 2 + description: | + The first cell is the pin number and the second cell is used to specify + flags. See ../gpio/gpio.txt for more information. + + regulators: + type: object + description: | + List of child nodes that specify the regulator initialization data. + Child nodes must be named after their hardware counterparts: + buck[1-6], ldoa[1-3], swa1, swb[1-2], and vtt. + Each child node is defined using the standard binding for regulators and + the optional regulator properties defined below. + + patternProperties: + "^buck[1-6]$": + type: object + $ref: ../regulator/regulator.yaml + + properties: + regulator-name: true + regulator-boot-on: true + regulator-always-on: true + regulator-min-microvolt: true + regulator-max-microvolt: true + ti,regulator-step-size-25mv: + type: boolean + description: | + Set this if the regulator is factory set with a 25mv step voltage + mapping. + ti,regulator-decay: + type: boolean + description: | + Set this if the output needs to decay, default is for the output + to slew down. + + additionalProperties: false + + "^(ldoa[1-3]|swa1|swb[1-2]|vtt)$": + type: object + $ref: ../regulator/regulator.yaml + + properties: + regulator-name: true + regulator-boot-on: true + regulator-always-on: true + regulator-min-microvolt: true + regulator-max-microvolt: true + + additionalProperties: false + +additionalProperties: false + +required: + - compatible + - reg + - gpio-controller + - '#gpio-cells' + - regulators + +examples: + - | + #include + i2c0 { + #address-cells = <1>; + #size-cells = <0>; + + pmic: pmic@5e { + compatible = "ti,tps65086"; + reg = <0x5e>; + interrupt-parent = <&gpio1>; + interrupts = <28 IRQ_TYPE_LEVEL_LOW>; + interrupt-controller; + #interrupt-cells = <2>; + gpio-controller; + #gpio-cells = <2>; + + regulators { + buck1 { + regulator-name = "vcc1"; + regulator-min-microvolt = <1600000>; + regulator-max-microvolt = <1600000>; + regulator-boot-on; + ti,regulator-decay; + ti,regulator-step-size-25mv; + }; + }; + }; + }; + +... diff --git a/Documentation/devicetree/bindings/mfd/tps65086.txt b/Documentation/devicetree/bindings/mfd/tps65086.txt deleted file mode 100644 index 67eac0ed32df..000000000000 --- a/Documentation/devicetree/bindings/mfd/tps65086.txt +++ /dev/null @@ -1,54 +0,0 @@ -* TPS65086 Power Management Integrated Circuit (PMIC) bindings - -Required properties: - - compatible : Should be "ti,tps65086". - - reg : I2C slave address. - - interrupts : The interrupt line the device is connected to. - - interrupt-controller : Marks the device node as an interrupt controller. - - #interrupt-cells : The number of cells to describe an IRQ, should be 2. - The first cell is the IRQ number. - The second cell is the flags, encoded as trigger - masks from ../interrupt-controller/interrupts.txt. - - gpio-controller : Marks the device node as a GPIO Controller. - - #gpio-cells : Should be two. The first cell is the pin number and - the second cell is used to specify flags. - See ../gpio/gpio.txt for more information. - - regulators: : List of child nodes that specify the regulator - initialization data. Child nodes must be named - after their hardware counterparts: buck[1-6], - ldoa[1-3], swa1, swb[1-2], and vtt. Each child - node is defined using the standard binding for - regulators and the optional regulator properties - defined below. - -Optional regulator properties: - - ti,regulator-step-size-25mv : This is applicable for buck[1-6], set this - if the regulator is factory set with a 25mv - step voltage mapping. - - ti,regulator-decay : This is applicable for buck[1-6], set this if - the output needs to decay, default is for - the output to slew down. - -Example: - - pmic: tps65086@5e { - compatible = "ti,tps65086"; - reg = <0x5e>; - interrupt-parent = <&gpio1>; - interrupts = <28 IRQ_TYPE_LEVEL_LOW>; - interrupt-controller; - #interrupt-cells = <2>; - gpio-controller; - #gpio-cells = <2>; - - regulators { - buck1 { - regulator-name = "vcc1"; - regulator-min-microvolt = <1600000>; - regulator-max-microvolt = <1600000>; - regulator-boot-on; - ti,regulator-decay; - ti,regulator-step-size-25mv; - }; - }; - }; diff --git a/Documentation/devicetree/bindings/opp/allwinner,sun50i-h6-operating-points.yaml b/Documentation/devicetree/bindings/opp/allwinner,sun50i-h6-operating-points.yaml index aeff2bd774dd..729ae97b63d9 100644 --- a/Documentation/devicetree/bindings/opp/allwinner,sun50i-h6-operating-points.yaml +++ b/Documentation/devicetree/bindings/opp/allwinner,sun50i-h6-operating-points.yaml @@ -18,6 +18,9 @@ description: | sun50i-cpufreq-nvmem driver reads the efuse value from the SoC to provide the OPP framework with required information. +allOf: + - $ref: opp-v2-base.yaml# + properties: compatible: const: allwinner,sun50i-h6-operating-points @@ -43,6 +46,7 @@ patternProperties: properties: opp-hz: true + clock-latency-ns: true patternProperties: "opp-microvolt-.*": true diff --git a/Documentation/devicetree/bindings/opp/opp-v1.yaml b/Documentation/devicetree/bindings/opp/opp-v1.yaml new file mode 100644 index 000000000000..d585d536a3fb --- /dev/null +++ b/Documentation/devicetree/bindings/opp/opp-v1.yaml @@ -0,0 +1,51 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/opp/opp-v1.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Generic OPP (Operating Performance Points) v1 Bindings + +maintainers: + - Viresh Kumar + +description: |+ + Devices work at voltage-current-frequency combinations and some implementations + have the liberty of choosing these. These combinations are called Operating + Performance Points aka OPPs. This document defines bindings for these OPPs + applicable across wide range of devices. For illustration purpose, this document + uses CPU as a device. + + This binding only supports voltage-frequency pairs. + +select: true + +properties: + operating-points: + $ref: /schemas/types.yaml#/definitions/uint32-matrix + items: + items: + - description: Frequency in kHz + - description: Voltage for OPP in uV + + +additionalProperties: true +examples: + - | + cpus { + #address-cells = <1>; + #size-cells = <0>; + + cpu@0 { + compatible = "arm,cortex-a9"; + device_type = "cpu"; + reg = <0>; + next-level-cache = <&L2>; + operating-points = + /* kHz uV */ + <792000 1100000>, + <396000 950000>, + <198000 850000>; + }; + }; +... diff --git a/Documentation/devicetree/bindings/opp/opp-v2-base.yaml b/Documentation/devicetree/bindings/opp/opp-v2-base.yaml new file mode 100644 index 000000000000..ae3ae4d39843 --- /dev/null +++ b/Documentation/devicetree/bindings/opp/opp-v2-base.yaml @@ -0,0 +1,214 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/opp/opp-v2-base.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Generic OPP (Operating Performance Points) Common Binding + +maintainers: + - Viresh Kumar + +description: | + Devices work at voltage-current-frequency combinations and some implementations + have the liberty of choosing these. These combinations are called Operating + Performance Points aka OPPs. This document defines bindings for these OPPs + applicable across wide range of devices. For illustration purpose, this document + uses CPU as a device. + + This describes the OPPs belonging to a device. + +select: false + +properties: + $nodename: + pattern: '^opp-table(-[a-z0-9]+)?$' + + opp-shared: + description: + Indicates that device nodes using this OPP Table Node's phandle switch + their DVFS state together, i.e. they share clock/voltage/current lines. + Missing property means devices have independent clock/voltage/current + lines, but they share OPP tables. + type: boolean + +patternProperties: + '^opp-?[0-9]+$': + type: object + description: + One or more OPP nodes describing voltage-current-frequency combinations. + Their name isn't significant but their phandle can be used to reference an + OPP. These are mandatory except for the case where the OPP table is + present only to indicate dependency between devices using the opp-shared + property. + + properties: + opp-hz: + description: + Frequency in Hz, expressed as a 64-bit big-endian integer. This is a + required property for all device nodes, unless another "required" + property to uniquely identify the OPP nodes exists. Devices like power + domains must have another (implementation dependent) property. + + opp-microvolt: + description: | + Voltage for the OPP + + A single regulator's voltage is specified with an array of size one or three. + Single entry is for target voltage and three entries are for + voltages. + + Entries for multiple regulators shall be provided in the same field separated + by angular brackets <>. The OPP binding doesn't provide any provisions to + relate the values to their power supplies or the order in which the supplies + need to be configured and that is left for the implementation specific + binding. + + Entries for all regulators shall be of the same size, i.e. either all use a + single value or triplets. + minItems: 1 + maxItems: 8 # Should be enough regulators + items: + minItems: 1 + maxItems: 3 + + opp-microamp: + description: | + The maximum current drawn by the device in microamperes considering + system specific parameters (such as transients, process, aging, + maximum operating temperature range etc.) as necessary. This may be + used to set the most efficient regulator operating mode. + + Should only be set if opp-microvolt or opp-microvolt- is set for + the OPP. + + Entries for multiple regulators shall be provided in the same field + separated by angular brackets <>. If current values aren't required + for a regulator, then it shall be filled with 0. If current values + aren't required for any of the regulators, then this field is not + required. The OPP binding doesn't provide any provisions to relate the + values to their power supplies or the order in which the supplies need + to be configured and that is left for the implementation specific + binding. + minItems: 1 + maxItems: 8 # Should be enough regulators + + opp-level: + description: + A value representing the performance level of the device. + $ref: /schemas/types.yaml#/definitions/uint32 + + opp-peak-kBps: + description: + Peak bandwidth in kilobytes per second, expressed as an array of + 32-bit big-endian integers. Each element of the array represents the + peak bandwidth value of each interconnect path. The number of elements + should match the number of interconnect paths. + minItems: 1 + maxItems: 32 # Should be enough + + opp-avg-kBps: + description: + Average bandwidth in kilobytes per second, expressed as an array + of 32-bit big-endian integers. Each element of the array represents the + average bandwidth value of each interconnect path. The number of elements + should match the number of interconnect paths. This property is only + meaningful in OPP tables where opp-peak-kBps is present. + minItems: 1 + maxItems: 32 # Should be enough + + clock-latency-ns: + description: + Specifies the maximum possible transition latency (in nanoseconds) for + switching to this OPP from any other OPP. + + turbo-mode: + description: + Marks the OPP to be used only for turbo modes. Turbo mode is available + on some platforms, where the device can run over its operating + frequency for a short duration of time limited by the device's power, + current and thermal limits. + type: boolean + + opp-suspend: + description: + Marks the OPP to be used during device suspend. If multiple OPPs in + the table have this, the OPP with highest opp-hz will be used. + type: boolean + + opp-supported-hw: + description: | + This property allows a platform to enable only a subset of the OPPs + from the larger set present in the OPP table, based on the current + version of the hardware (already known to the operating system). + + Each block present in the array of blocks in this property, represents + a sub-group of hardware versions supported by the OPP. i.e. , , etc. The OPP will be enabled if _any_ of these + sub-groups match the hardware's version. + + Each sub-group is a platform defined array representing the hierarchy + of hardware versions supported by the platform. For a platform with + three hierarchical levels of version (X.Y.Z), this field shall look + like + + opp-supported-hw = , , . + + Each level (eg. X1) in version hierarchy is represented by a 32 bit + value, one bit per version and so there can be maximum 32 versions per + level. Logical AND (&) operation is performed for each level with the + hardware's level version and a non-zero output for _all_ the levels in + a sub-group means the OPP is supported by hardware. A value of + 0xFFFFFFFF for each level in the sub-group will enable the OPP for all + versions for the hardware. + $ref: /schemas/types.yaml#/definitions/uint32-matrix + maxItems: 32 + items: + minItems: 1 + maxItems: 4 + + required-opps: + description: + This contains phandle to an OPP node in another device's OPP table. It + may contain an array of phandles, where each phandle points to an OPP + of a different device. It should not contain multiple phandles to the + OPP nodes in the same OPP table. This specifies the minimum required + OPP of the device(s), whose OPP's phandle is present in this property, + for the functioning of the current device at the current OPP (where + this property is present). + $ref: /schemas/types.yaml#/definitions/phandle-array + + patternProperties: + '^opp-microvolt-': + description: + Named opp-microvolt property. This is exactly similar to the above + opp-microvolt property, but allows multiple voltage ranges to be + provided for the same OPP. At runtime, the platform can pick a + and matching opp-microvolt- property will be enabled for all + OPPs. If the platform doesn't pick a specific or the + doesn't match with any opp-microvolt- properties, then + opp-microvolt property shall be used, if present. + $ref: /schemas/types.yaml#/definitions/uint32-matrix + minItems: 1 + maxItems: 8 # Should be enough regulators + items: + minItems: 1 + maxItems: 3 + + '^opp-microamp-': + description: + Named opp-microamp property. Similar to opp-microvolt- property, + but for microamp instead. + $ref: /schemas/types.yaml#/definitions/uint32-array + minItems: 1 + maxItems: 8 # Should be enough regulators + + dependencies: + opp-avg-kBps: [ opp-peak-kBps ] + +required: + - compatible + +additionalProperties: true + +... diff --git a/Documentation/devicetree/bindings/opp/opp-v2.yaml b/Documentation/devicetree/bindings/opp/opp-v2.yaml new file mode 100644 index 000000000000..eaf8fba2c691 --- /dev/null +++ b/Documentation/devicetree/bindings/opp/opp-v2.yaml @@ -0,0 +1,475 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/opp/opp-v2.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Generic OPP (Operating Performance Points) Bindings + +maintainers: + - Viresh Kumar + +allOf: + - $ref: opp-v2-base.yaml# + +properties: + compatible: + const: operating-points-v2 + +unevaluatedProperties: false + +examples: + - | + /* + * Example 1: Single cluster Dual-core ARM cortex A9, switch DVFS states + * together. + */ + cpus { + #address-cells = <1>; + #size-cells = <0>; + + cpu@0 { + compatible = "arm,cortex-a9"; + device_type = "cpu"; + reg = <0>; + next-level-cache = <&L2>; + clocks = <&clk_controller 0>; + clock-names = "cpu"; + cpu-supply = <&cpu_supply0>; + operating-points-v2 = <&cpu0_opp_table0>; + }; + + cpu@1 { + compatible = "arm,cortex-a9"; + device_type = "cpu"; + reg = <1>; + next-level-cache = <&L2>; + clocks = <&clk_controller 0>; + clock-names = "cpu"; + cpu-supply = <&cpu_supply0>; + operating-points-v2 = <&cpu0_opp_table0>; + }; + }; + + cpu0_opp_table0: opp-table { + compatible = "operating-points-v2"; + opp-shared; + + opp-1000000000 { + opp-hz = /bits/ 64 <1000000000>; + opp-microvolt = <975000 970000 985000>; + opp-microamp = <70000>; + clock-latency-ns = <300000>; + opp-suspend; + }; + opp-1100000000 { + opp-hz = /bits/ 64 <1100000000>; + opp-microvolt = <1000000 980000 1010000>; + opp-microamp = <80000>; + clock-latency-ns = <310000>; + }; + opp-1200000000 { + opp-hz = /bits/ 64 <1200000000>; + opp-microvolt = <1025000>; + clock-latency-ns = <290000>; + turbo-mode; + }; + }; + + - | + /* + * Example 2: Single cluster, Quad-core Qualcom-krait, switches DVFS states + * independently. + */ + cpus { + #address-cells = <1>; + #size-cells = <0>; + + cpu@0 { + compatible = "qcom,krait"; + device_type = "cpu"; + reg = <0>; + next-level-cache = <&L2>; + clocks = <&clk_controller 0>; + clock-names = "cpu"; + cpu-supply = <&cpu_supply0>; + operating-points-v2 = <&cpu_opp_table>; + }; + + cpu@1 { + compatible = "qcom,krait"; + device_type = "cpu"; + reg = <1>; + next-level-cache = <&L2>; + clocks = <&clk_controller 1>; + clock-names = "cpu"; + cpu-supply = <&cpu_supply1>; + operating-points-v2 = <&cpu_opp_table>; + }; + + cpu@2 { + compatible = "qcom,krait"; + device_type = "cpu"; + reg = <2>; + next-level-cache = <&L2>; + clocks = <&clk_controller 2>; + clock-names = "cpu"; + cpu-supply = <&cpu_supply2>; + operating-points-v2 = <&cpu_opp_table>; + }; + + cpu@3 { + compatible = "qcom,krait"; + device_type = "cpu"; + reg = <3>; + next-level-cache = <&L2>; + clocks = <&clk_controller 3>; + clock-names = "cpu"; + cpu-supply = <&cpu_supply3>; + operating-points-v2 = <&cpu_opp_table>; + }; + }; + + cpu_opp_table: opp-table { + compatible = "operating-points-v2"; + + /* + * Missing opp-shared property means CPUs switch DVFS states + * independently. + */ + + opp-1000000000 { + opp-hz = /bits/ 64 <1000000000>; + opp-microvolt = <975000 970000 985000>; + opp-microamp = <70000>; + clock-latency-ns = <300000>; + opp-suspend; + }; + opp-1100000000 { + opp-hz = /bits/ 64 <1100000000>; + opp-microvolt = <1000000 980000 1010000>; + opp-microamp = <80000>; + clock-latency-ns = <310000>; + }; + opp-1200000000 { + opp-hz = /bits/ 64 <1200000000>; + opp-microvolt = <1025000>; + opp-microamp = <90000>; + lock-latency-ns = <290000>; + turbo-mode; + }; + }; + + - | + /* + * Example 3: Dual-cluster, Dual-core per cluster. CPUs within a cluster switch + * DVFS state together. + */ + cpus { + #address-cells = <1>; + #size-cells = <0>; + + cpu@0 { + compatible = "arm,cortex-a7"; + device_type = "cpu"; + reg = <0>; + next-level-cache = <&L2>; + clocks = <&clk_controller 0>; + clock-names = "cpu"; + cpu-supply = <&cpu_supply0>; + operating-points-v2 = <&cluster0_opp>; + }; + + cpu@1 { + compatible = "arm,cortex-a7"; + device_type = "cpu"; + reg = <1>; + next-level-cache = <&L2>; + clocks = <&clk_controller 0>; + clock-names = "cpu"; + cpu-supply = <&cpu_supply0>; + operating-points-v2 = <&cluster0_opp>; + }; + + cpu@100 { + compatible = "arm,cortex-a15"; + device_type = "cpu"; + reg = <100>; + next-level-cache = <&L2>; + clocks = <&clk_controller 1>; + clock-names = "cpu"; + cpu-supply = <&cpu_supply1>; + operating-points-v2 = <&cluster1_opp>; + }; + + cpu@101 { + compatible = "arm,cortex-a15"; + device_type = "cpu"; + reg = <101>; + next-level-cache = <&L2>; + clocks = <&clk_controller 1>; + clock-names = "cpu"; + cpu-supply = <&cpu_supply1>; + operating-points-v2 = <&cluster1_opp>; + }; + }; + + cluster0_opp: opp-table-0 { + compatible = "operating-points-v2"; + opp-shared; + + opp-1000000000 { + opp-hz = /bits/ 64 <1000000000>; + opp-microvolt = <975000 970000 985000>; + opp-microamp = <70000>; + clock-latency-ns = <300000>; + opp-suspend; + }; + opp-1100000000 { + opp-hz = /bits/ 64 <1100000000>; + opp-microvolt = <1000000 980000 1010000>; + opp-microamp = <80000>; + clock-latency-ns = <310000>; + }; + opp-1200000000 { + opp-hz = /bits/ 64 <1200000000>; + opp-microvolt = <1025000>; + opp-microamp = <90000>; + clock-latency-ns = <290000>; + turbo-mode; + }; + }; + + cluster1_opp: opp-table-1 { + compatible = "operating-points-v2"; + opp-shared; + + opp-1300000000 { + opp-hz = /bits/ 64 <1300000000>; + opp-microvolt = <1050000 1045000 1055000>; + opp-microamp = <95000>; + clock-latency-ns = <400000>; + opp-suspend; + }; + opp-1400000000 { + opp-hz = /bits/ 64 <1400000000>; + opp-microvolt = <1075000>; + opp-microamp = <100000>; + clock-latency-ns = <400000>; + }; + opp-1500000000 { + opp-hz = /bits/ 64 <1500000000>; + opp-microvolt = <1100000 1010000 1110000>; + opp-microamp = <95000>; + clock-latency-ns = <400000>; + turbo-mode; + }; + }; + + - | + /* Example 4: Handling multiple regulators */ + cpus { + #address-cells = <1>; + #size-cells = <0>; + + cpu@0 { + compatible = "foo,cpu-type"; + device_type = "cpu"; + reg = <0>; + + vcc0-supply = <&cpu_supply0>; + vcc1-supply = <&cpu_supply1>; + vcc2-supply = <&cpu_supply2>; + operating-points-v2 = <&cpu0_opp_table4>; + }; + }; + + cpu0_opp_table4: opp-table-0 { + compatible = "operating-points-v2"; + opp-shared; + + opp-1000000000 { + opp-hz = /bits/ 64 <1000000000>; + opp-microvolt = <970000>, /* Supply 0 */ + <960000>, /* Supply 1 */ + <960000>; /* Supply 2 */ + opp-microamp = <70000>, /* Supply 0 */ + <70000>, /* Supply 1 */ + <70000>; /* Supply 2 */ + clock-latency-ns = <300000>; + }; + + /* OR */ + + opp-1000000001 { + opp-hz = /bits/ 64 <1000000001>; + opp-microvolt = <975000 970000 985000>, /* Supply 0 */ + <965000 960000 975000>, /* Supply 1 */ + <965000 960000 975000>; /* Supply 2 */ + opp-microamp = <70000>, /* Supply 0 */ + <70000>, /* Supply 1 */ + <70000>; /* Supply 2 */ + clock-latency-ns = <300000>; + }; + + /* OR */ + + opp-1000000002 { + opp-hz = /bits/ 64 <1000000002>; + opp-microvolt = <975000 970000 985000>, /* Supply 0 */ + <965000 960000 975000>, /* Supply 1 */ + <965000 960000 975000>; /* Supply 2 */ + opp-microamp = <70000>, /* Supply 0 */ + <0>, /* Supply 1 doesn't need this */ + <70000>; /* Supply 2 */ + clock-latency-ns = <300000>; + }; + }; + + - | + /* + * Example 5: opp-supported-hw + * (example: three level hierarchy of versions: cuts, substrate and process) + */ + cpus { + #address-cells = <1>; + #size-cells = <0>; + + cpu@0 { + compatible = "arm,cortex-a7"; + device_type = "cpu"; + reg = <0>; + cpu-supply = <&cpu_supply>; + operating-points-v2 = <&cpu0_opp_table_slow>; + }; + }; + + cpu0_opp_table_slow: opp-table { + compatible = "operating-points-v2"; + opp-shared; + + opp-600000000 { + /* + * Supports all substrate and process versions for 0xF + * cuts, i.e. only first four cuts. + */ + opp-supported-hw = <0xF 0xFFFFFFFF 0xFFFFFFFF>; + opp-hz = /bits/ 64 <600000000>; + }; + + opp-800000000 { + /* + * Supports: + * - cuts: only one, 6th cut (represented by 6th bit). + * - substrate: supports 16 different substrate versions + * - process: supports 9 different process versions + */ + opp-supported-hw = <0x20 0xff0000ff 0x0000f4f0>; + opp-hz = /bits/ 64 <800000000>; + }; + + opp-900000000 { + /* + * Supports: + * - All cuts and substrate where process version is 0x2. + * - All cuts and process where substrate version is 0x2. + */ + opp-supported-hw = <0xFFFFFFFF 0xFFFFFFFF 0x02>, + <0xFFFFFFFF 0x01 0xFFFFFFFF>; + opp-hz = /bits/ 64 <900000000>; + }; + }; + + - | + /* + * Example 6: opp-microvolt-, opp-microamp-: + * (example: device with two possible microvolt ranges: slow and fast) + */ + cpus { + #address-cells = <1>; + #size-cells = <0>; + + cpu@0 { + compatible = "arm,cortex-a7"; + device_type = "cpu"; + reg = <0>; + operating-points-v2 = <&cpu0_opp_table6>; + }; + }; + + cpu0_opp_table6: opp-table-0 { + compatible = "operating-points-v2"; + opp-shared; + + opp-1000000000 { + opp-hz = /bits/ 64 <1000000000>; + opp-microvolt-slow = <915000 900000 925000>; + opp-microvolt-fast = <975000 970000 985000>; + opp-microamp-slow = <70000>; + opp-microamp-fast = <71000>; + }; + + opp-1200000000 { + opp-hz = /bits/ 64 <1200000000>; + opp-microvolt-slow = <915000 900000 925000>, /* Supply vcc0 */ + <925000 910000 935000>; /* Supply vcc1 */ + opp-microvolt-fast = <975000 970000 985000>, /* Supply vcc0 */ + <965000 960000 975000>; /* Supply vcc1 */ + opp-microamp = <70000>; /* Will be used for both slow/fast */ + }; + }; + + - | + /* + * Example 7: Single cluster Quad-core ARM cortex A53, OPP points from firmware, + * distinct clock controls but two sets of clock/voltage/current lines. + */ + cpus { + #address-cells = <2>; + #size-cells = <0>; + + cpu@0 { + compatible = "arm,cortex-a53"; + device_type = "cpu"; + reg = <0x0 0x100>; + next-level-cache = <&A53_L2>; + clocks = <&dvfs_controller 0>; + operating-points-v2 = <&cpu_opp0_table>; + }; + cpu@1 { + compatible = "arm,cortex-a53"; + device_type = "cpu"; + reg = <0x0 0x101>; + next-level-cache = <&A53_L2>; + clocks = <&dvfs_controller 1>; + operating-points-v2 = <&cpu_opp0_table>; + }; + cpu@2 { + compatible = "arm,cortex-a53"; + device_type = "cpu"; + reg = <0x0 0x102>; + next-level-cache = <&A53_L2>; + clocks = <&dvfs_controller 2>; + operating-points-v2 = <&cpu_opp1_table>; + }; + cpu@3 { + compatible = "arm,cortex-a53"; + device_type = "cpu"; + reg = <0x0 0x103>; + next-level-cache = <&A53_L2>; + clocks = <&dvfs_controller 3>; + operating-points-v2 = <&cpu_opp1_table>; + }; + + }; + + cpu_opp0_table: opp-table-0 { + compatible = "operating-points-v2"; + opp-shared; + }; + + cpu_opp1_table: opp-table-1 { + compatible = "operating-points-v2"; + opp-shared; + }; +... diff --git a/Documentation/devicetree/bindings/opp/opp.txt b/Documentation/devicetree/bindings/opp/opp.txt deleted file mode 100644 index 08b3da4736cf..000000000000 --- a/Documentation/devicetree/bindings/opp/opp.txt +++ /dev/null @@ -1,622 +0,0 @@ -Generic OPP (Operating Performance Points) Bindings ----------------------------------------------------- - -Devices work at voltage-current-frequency combinations and some implementations -have the liberty of choosing these. These combinations are called Operating -Performance Points aka OPPs. This document defines bindings for these OPPs -applicable across wide range of devices. For illustration purpose, this document -uses CPU as a device. - -This document contain multiple versions of OPP binding and only one of them -should be used per device. - -Binding 1: operating-points -============================ - -This binding only supports voltage-frequency pairs. - -Properties: -- operating-points: An array of 2-tuples items, and each item consists - of frequency and voltage like . - freq: clock frequency in kHz - vol: voltage in microvolt - -Examples: - -cpu@0 { - compatible = "arm,cortex-a9"; - reg = <0>; - next-level-cache = <&L2>; - operating-points = < - /* kHz uV */ - 792000 1100000 - 396000 950000 - 198000 850000 - >; -}; - - -Binding 2: operating-points-v2 -============================ - -* Property: operating-points-v2 - -Devices supporting OPPs must set their "operating-points-v2" property with -phandle to a OPP table in their DT node. The OPP core will use this phandle to -find the operating points for the device. - -This can contain more than one phandle for power domain providers that provide -multiple power domains. That is, one phandle for each power domain. If only one -phandle is available, then the same OPP table will be used for all power domains -provided by the power domain provider. - -If required, this can be extended for SoC vendor specific bindings. Such bindings -should be documented as Documentation/devicetree/bindings/power/-opp.txt -and should have a compatible description like: "operating-points-v2-". - -* OPP Table Node - -This describes the OPPs belonging to a device. This node can have following -properties: - -Required properties: -- compatible: Allow OPPs to express their compatibility. It should be: - "operating-points-v2". - -- OPP nodes: One or more OPP nodes describing voltage-current-frequency - combinations. Their name isn't significant but their phandle can be used to - reference an OPP. These are mandatory except for the case where the OPP table - is present only to indicate dependency between devices using the opp-shared - property. - -Optional properties: -- opp-shared: Indicates that device nodes using this OPP Table Node's phandle - switch their DVFS state together, i.e. they share clock/voltage/current lines. - Missing property means devices have independent clock/voltage/current lines, - but they share OPP tables. - -- status: Marks the OPP table enabled/disabled. - - -* OPP Node - -This defines voltage-current-frequency combinations along with other related -properties. - -Required properties: -- opp-hz: Frequency in Hz, expressed as a 64-bit big-endian integer. This is a - required property for all device nodes, unless another "required" property to - uniquely identify the OPP nodes exists. Devices like power domains must have - another (implementation dependent) property. - -- opp-peak-kBps: Peak bandwidth in kilobytes per second, expressed as an array - of 32-bit big-endian integers. Each element of the array represents the - peak bandwidth value of each interconnect path. The number of elements should - match the number of interconnect paths. - -Optional properties: -- opp-microvolt: voltage in micro Volts. - - A single regulator's voltage is specified with an array of size one or three. - Single entry is for target voltage and three entries are for - voltages. - - Entries for multiple regulators shall be provided in the same field separated - by angular brackets <>. The OPP binding doesn't provide any provisions to - relate the values to their power supplies or the order in which the supplies - need to be configured and that is left for the implementation specific - binding. - - Entries for all regulators shall be of the same size, i.e. either all use a - single value or triplets. - -- opp-microvolt-: Named opp-microvolt property. This is exactly similar to - the above opp-microvolt property, but allows multiple voltage ranges to be - provided for the same OPP. At runtime, the platform can pick a and - matching opp-microvolt- property will be enabled for all OPPs. If the - platform doesn't pick a specific or the doesn't match with any - opp-microvolt- properties, then opp-microvolt property shall be used, if - present. - -- opp-microamp: The maximum current drawn by the device in microamperes - considering system specific parameters (such as transients, process, aging, - maximum operating temperature range etc.) as necessary. This may be used to - set the most efficient regulator operating mode. - - Should only be set if opp-microvolt is set for the OPP. - - Entries for multiple regulators shall be provided in the same field separated - by angular brackets <>. If current values aren't required for a regulator, - then it shall be filled with 0. If current values aren't required for any of - the regulators, then this field is not required. The OPP binding doesn't - provide any provisions to relate the values to their power supplies or the - order in which the supplies need to be configured and that is left for the - implementation specific binding. - -- opp-microamp-: Named opp-microamp property. Similar to - opp-microvolt- property, but for microamp instead. - -- opp-level: A value representing the performance level of the device, - expressed as a 32-bit integer. - -- opp-avg-kBps: Average bandwidth in kilobytes per second, expressed as an array - of 32-bit big-endian integers. Each element of the array represents the - average bandwidth value of each interconnect path. The number of elements - should match the number of interconnect paths. This property is only - meaningful in OPP tables where opp-peak-kBps is present. - -- clock-latency-ns: Specifies the maximum possible transition latency (in - nanoseconds) for switching to this OPP from any other OPP. - -- turbo-mode: Marks the OPP to be used only for turbo modes. Turbo mode is - available on some platforms, where the device can run over its operating - frequency for a short duration of time limited by the device's power, current - and thermal limits. - -- opp-suspend: Marks the OPP to be used during device suspend. If multiple OPPs - in the table have this, the OPP with highest opp-hz will be used. - -- opp-supported-hw: This property allows a platform to enable only a subset of - the OPPs from the larger set present in the OPP table, based on the current - version of the hardware (already known to the operating system). - - Each block present in the array of blocks in this property, represents a - sub-group of hardware versions supported by the OPP. i.e. , - , etc. The OPP will be enabled if _any_ of these sub-groups match - the hardware's version. - - Each sub-group is a platform defined array representing the hierarchy of - hardware versions supported by the platform. For a platform with three - hierarchical levels of version (X.Y.Z), this field shall look like - - opp-supported-hw = , , . - - Each level (eg. X1) in version hierarchy is represented by a 32 bit value, one - bit per version and so there can be maximum 32 versions per level. Logical AND - (&) operation is performed for each level with the hardware's level version - and a non-zero output for _all_ the levels in a sub-group means the OPP is - supported by hardware. A value of 0xFFFFFFFF for each level in the sub-group - will enable the OPP for all versions for the hardware. - -- status: Marks the node enabled/disabled. - -- required-opps: This contains phandle to an OPP node in another device's OPP - table. It may contain an array of phandles, where each phandle points to an - OPP of a different device. It should not contain multiple phandles to the OPP - nodes in the same OPP table. This specifies the minimum required OPP of the - device(s), whose OPP's phandle is present in this property, for the - functioning of the current device at the current OPP (where this property is - present). - -Example 1: Single cluster Dual-core ARM cortex A9, switch DVFS states together. - -/ { - cpus { - #address-cells = <1>; - #size-cells = <0>; - - cpu@0 { - compatible = "arm,cortex-a9"; - reg = <0>; - next-level-cache = <&L2>; - clocks = <&clk_controller 0>; - clock-names = "cpu"; - cpu-supply = <&cpu_supply0>; - operating-points-v2 = <&cpu0_opp_table>; - }; - - cpu@1 { - compatible = "arm,cortex-a9"; - reg = <1>; - next-level-cache = <&L2>; - clocks = <&clk_controller 0>; - clock-names = "cpu"; - cpu-supply = <&cpu_supply0>; - operating-points-v2 = <&cpu0_opp_table>; - }; - }; - - cpu0_opp_table: opp_table0 { - compatible = "operating-points-v2"; - opp-shared; - - opp-1000000000 { - opp-hz = /bits/ 64 <1000000000>; - opp-microvolt = <975000 970000 985000>; - opp-microamp = <70000>; - clock-latency-ns = <300000>; - opp-suspend; - }; - opp-1100000000 { - opp-hz = /bits/ 64 <1100000000>; - opp-microvolt = <1000000 980000 1010000>; - opp-microamp = <80000>; - clock-latency-ns = <310000>; - }; - opp-1200000000 { - opp-hz = /bits/ 64 <1200000000>; - opp-microvolt = <1025000>; - clock-latency-ns = <290000>; - turbo-mode; - }; - }; -}; - -Example 2: Single cluster, Quad-core Qualcom-krait, switches DVFS states -independently. - -/ { - cpus { - #address-cells = <1>; - #size-cells = <0>; - - cpu@0 { - compatible = "qcom,krait"; - reg = <0>; - next-level-cache = <&L2>; - clocks = <&clk_controller 0>; - clock-names = "cpu"; - cpu-supply = <&cpu_supply0>; - operating-points-v2 = <&cpu_opp_table>; - }; - - cpu@1 { - compatible = "qcom,krait"; - reg = <1>; - next-level-cache = <&L2>; - clocks = <&clk_controller 1>; - clock-names = "cpu"; - cpu-supply = <&cpu_supply1>; - operating-points-v2 = <&cpu_opp_table>; - }; - - cpu@2 { - compatible = "qcom,krait"; - reg = <2>; - next-level-cache = <&L2>; - clocks = <&clk_controller 2>; - clock-names = "cpu"; - cpu-supply = <&cpu_supply2>; - operating-points-v2 = <&cpu_opp_table>; - }; - - cpu@3 { - compatible = "qcom,krait"; - reg = <3>; - next-level-cache = <&L2>; - clocks = <&clk_controller 3>; - clock-names = "cpu"; - cpu-supply = <&cpu_supply3>; - operating-points-v2 = <&cpu_opp_table>; - }; - }; - - cpu_opp_table: opp_table { - compatible = "operating-points-v2"; - - /* - * Missing opp-shared property means CPUs switch DVFS states - * independently. - */ - - opp-1000000000 { - opp-hz = /bits/ 64 <1000000000>; - opp-microvolt = <975000 970000 985000>; - opp-microamp = <70000>; - clock-latency-ns = <300000>; - opp-suspend; - }; - opp-1100000000 { - opp-hz = /bits/ 64 <1100000000>; - opp-microvolt = <1000000 980000 1010000>; - opp-microamp = <80000>; - clock-latency-ns = <310000>; - }; - opp-1200000000 { - opp-hz = /bits/ 64 <1200000000>; - opp-microvolt = <1025000>; - opp-microamp = <90000; - lock-latency-ns = <290000>; - turbo-mode; - }; - }; -}; - -Example 3: Dual-cluster, Dual-core per cluster. CPUs within a cluster switch -DVFS state together. - -/ { - cpus { - #address-cells = <1>; - #size-cells = <0>; - - cpu@0 { - compatible = "arm,cortex-a7"; - reg = <0>; - next-level-cache = <&L2>; - clocks = <&clk_controller 0>; - clock-names = "cpu"; - cpu-supply = <&cpu_supply0>; - operating-points-v2 = <&cluster0_opp>; - }; - - cpu@1 { - compatible = "arm,cortex-a7"; - reg = <1>; - next-level-cache = <&L2>; - clocks = <&clk_controller 0>; - clock-names = "cpu"; - cpu-supply = <&cpu_supply0>; - operating-points-v2 = <&cluster0_opp>; - }; - - cpu@100 { - compatible = "arm,cortex-a15"; - reg = <100>; - next-level-cache = <&L2>; - clocks = <&clk_controller 1>; - clock-names = "cpu"; - cpu-supply = <&cpu_supply1>; - operating-points-v2 = <&cluster1_opp>; - }; - - cpu@101 { - compatible = "arm,cortex-a15"; - reg = <101>; - next-level-cache = <&L2>; - clocks = <&clk_controller 1>; - clock-names = "cpu"; - cpu-supply = <&cpu_supply1>; - operating-points-v2 = <&cluster1_opp>; - }; - }; - - cluster0_opp: opp_table0 { - compatible = "operating-points-v2"; - opp-shared; - - opp-1000000000 { - opp-hz = /bits/ 64 <1000000000>; - opp-microvolt = <975000 970000 985000>; - opp-microamp = <70000>; - clock-latency-ns = <300000>; - opp-suspend; - }; - opp-1100000000 { - opp-hz = /bits/ 64 <1100000000>; - opp-microvolt = <1000000 980000 1010000>; - opp-microamp = <80000>; - clock-latency-ns = <310000>; - }; - opp-1200000000 { - opp-hz = /bits/ 64 <1200000000>; - opp-microvolt = <1025000>; - opp-microamp = <90000>; - clock-latency-ns = <290000>; - turbo-mode; - }; - }; - - cluster1_opp: opp_table1 { - compatible = "operating-points-v2"; - opp-shared; - - opp-1300000000 { - opp-hz = /bits/ 64 <1300000000>; - opp-microvolt = <1050000 1045000 1055000>; - opp-microamp = <95000>; - clock-latency-ns = <400000>; - opp-suspend; - }; - opp-1400000000 { - opp-hz = /bits/ 64 <1400000000>; - opp-microvolt = <1075000>; - opp-microamp = <100000>; - clock-latency-ns = <400000>; - }; - opp-1500000000 { - opp-hz = /bits/ 64 <1500000000>; - opp-microvolt = <1100000 1010000 1110000>; - opp-microamp = <95000>; - clock-latency-ns = <400000>; - turbo-mode; - }; - }; -}; - -Example 4: Handling multiple regulators - -/ { - cpus { - cpu@0 { - compatible = "vendor,cpu-type"; - ... - - vcc0-supply = <&cpu_supply0>; - vcc1-supply = <&cpu_supply1>; - vcc2-supply = <&cpu_supply2>; - operating-points-v2 = <&cpu0_opp_table>; - }; - }; - - cpu0_opp_table: opp_table0 { - compatible = "operating-points-v2"; - opp-shared; - - opp-1000000000 { - opp-hz = /bits/ 64 <1000000000>; - opp-microvolt = <970000>, /* Supply 0 */ - <960000>, /* Supply 1 */ - <960000>; /* Supply 2 */ - opp-microamp = <70000>, /* Supply 0 */ - <70000>, /* Supply 1 */ - <70000>; /* Supply 2 */ - clock-latency-ns = <300000>; - }; - - /* OR */ - - opp-1000000000 { - opp-hz = /bits/ 64 <1000000000>; - opp-microvolt = <975000 970000 985000>, /* Supply 0 */ - <965000 960000 975000>, /* Supply 1 */ - <965000 960000 975000>; /* Supply 2 */ - opp-microamp = <70000>, /* Supply 0 */ - <70000>, /* Supply 1 */ - <70000>; /* Supply 2 */ - clock-latency-ns = <300000>; - }; - - /* OR */ - - opp-1000000000 { - opp-hz = /bits/ 64 <1000000000>; - opp-microvolt = <975000 970000 985000>, /* Supply 0 */ - <965000 960000 975000>, /* Supply 1 */ - <965000 960000 975000>; /* Supply 2 */ - opp-microamp = <70000>, /* Supply 0 */ - <0>, /* Supply 1 doesn't need this */ - <70000>; /* Supply 2 */ - clock-latency-ns = <300000>; - }; - }; -}; - -Example 5: opp-supported-hw -(example: three level hierarchy of versions: cuts, substrate and process) - -/ { - cpus { - cpu@0 { - compatible = "arm,cortex-a7"; - ... - - cpu-supply = <&cpu_supply> - operating-points-v2 = <&cpu0_opp_table_slow>; - }; - }; - - opp_table { - compatible = "operating-points-v2"; - opp-shared; - - opp-600000000 { - /* - * Supports all substrate and process versions for 0xF - * cuts, i.e. only first four cuts. - */ - opp-supported-hw = <0xF 0xFFFFFFFF 0xFFFFFFFF> - opp-hz = /bits/ 64 <600000000>; - ... - }; - - opp-800000000 { - /* - * Supports: - * - cuts: only one, 6th cut (represented by 6th bit). - * - substrate: supports 16 different substrate versions - * - process: supports 9 different process versions - */ - opp-supported-hw = <0x20 0xff0000ff 0x0000f4f0> - opp-hz = /bits/ 64 <800000000>; - ... - }; - - opp-900000000 { - /* - * Supports: - * - All cuts and substrate where process version is 0x2. - * - All cuts and process where substrate version is 0x2. - */ - opp-supported-hw = <0xFFFFFFFF 0xFFFFFFFF 0x02>, <0xFFFFFFFF 0x01 0xFFFFFFFF> - opp-hz = /bits/ 64 <900000000>; - ... - }; - }; -}; - -Example 6: opp-microvolt-, opp-microamp-: -(example: device with two possible microvolt ranges: slow and fast) - -/ { - cpus { - cpu@0 { - compatible = "arm,cortex-a7"; - ... - - operating-points-v2 = <&cpu0_opp_table>; - }; - }; - - cpu0_opp_table: opp_table0 { - compatible = "operating-points-v2"; - opp-shared; - - opp-1000000000 { - opp-hz = /bits/ 64 <1000000000>; - opp-microvolt-slow = <915000 900000 925000>; - opp-microvolt-fast = <975000 970000 985000>; - opp-microamp-slow = <70000>; - opp-microamp-fast = <71000>; - }; - - opp-1200000000 { - opp-hz = /bits/ 64 <1200000000>; - opp-microvolt-slow = <915000 900000 925000>, /* Supply vcc0 */ - <925000 910000 935000>; /* Supply vcc1 */ - opp-microvolt-fast = <975000 970000 985000>, /* Supply vcc0 */ - <965000 960000 975000>; /* Supply vcc1 */ - opp-microamp = <70000>; /* Will be used for both slow/fast */ - }; - }; -}; - -Example 7: Single cluster Quad-core ARM cortex A53, OPP points from firmware, -distinct clock controls but two sets of clock/voltage/current lines. - -/ { - cpus { - #address-cells = <2>; - #size-cells = <0>; - - cpu@0 { - compatible = "arm,cortex-a53"; - reg = <0x0 0x100>; - next-level-cache = <&A53_L2>; - clocks = <&dvfs_controller 0>; - operating-points-v2 = <&cpu_opp0_table>; - }; - cpu@1 { - compatible = "arm,cortex-a53"; - reg = <0x0 0x101>; - next-level-cache = <&A53_L2>; - clocks = <&dvfs_controller 1>; - operating-points-v2 = <&cpu_opp0_table>; - }; - cpu@2 { - compatible = "arm,cortex-a53"; - reg = <0x0 0x102>; - next-level-cache = <&A53_L2>; - clocks = <&dvfs_controller 2>; - operating-points-v2 = <&cpu_opp1_table>; - }; - cpu@3 { - compatible = "arm,cortex-a53"; - reg = <0x0 0x103>; - next-level-cache = <&A53_L2>; - clocks = <&dvfs_controller 3>; - operating-points-v2 = <&cpu_opp1_table>; - }; - - }; - - cpu_opp0_table: opp0_table { - compatible = "operating-points-v2"; - opp-shared; - }; - - cpu_opp1_table: opp1_table { - compatible = "operating-points-v2"; - opp-shared; - }; -}; diff --git a/Documentation/devicetree/bindings/opp/qcom-opp.txt b/Documentation/devicetree/bindings/opp/qcom-opp.txt index 32eb0793c7e6..41d3e4ff2dc3 100644 --- a/Documentation/devicetree/bindings/opp/qcom-opp.txt +++ b/Documentation/devicetree/bindings/opp/qcom-opp.txt @@ -1,7 +1,7 @@ Qualcomm OPP bindings to describe OPP nodes The bindings are based on top of the operating-points-v2 bindings -described in Documentation/devicetree/bindings/opp/opp.txt +described in Documentation/devicetree/bindings/opp/opp-v2-base.yaml Additional properties are described below. * OPP Table Node diff --git a/Documentation/devicetree/bindings/opp/ti-omap5-opp-supply.txt b/Documentation/devicetree/bindings/opp/ti-omap5-opp-supply.txt index 832346e489a3..b70d326117cd 100644 --- a/Documentation/devicetree/bindings/opp/ti-omap5-opp-supply.txt +++ b/Documentation/devicetree/bindings/opp/ti-omap5-opp-supply.txt @@ -13,7 +13,7 @@ regulators to the device that will undergo OPP transitions we can make use of the multi regulator binding that is part of the OPP core described here [1] to describe both regulators needed by the platform. -[1] Documentation/devicetree/bindings/opp/opp.txt +[1] Documentation/devicetree/bindings/opp/opp-v2.yaml Required Properties for Device Node: - vdd-supply: phandle to regulator controlling VDD supply diff --git a/Documentation/devicetree/bindings/pci/intel,keembay-pcie-ep.yaml b/Documentation/devicetree/bindings/pci/intel,keembay-pcie-ep.yaml new file mode 100644 index 000000000000..e87ff27526ff --- /dev/null +++ b/Documentation/devicetree/bindings/pci/intel,keembay-pcie-ep.yaml @@ -0,0 +1,69 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: "http://devicetree.org/schemas/pci/intel,keembay-pcie-ep.yaml#" +$schema: "http://devicetree.org/meta-schemas/core.yaml#" + +title: Intel Keem Bay PCIe controller Endpoint mode + +maintainers: + - Wan Ahmad Zainie + - Srikanth Thokala + +properties: + compatible: + const: intel,keembay-pcie-ep + + reg: + maxItems: 5 + + reg-names: + items: + - const: dbi + - const: dbi2 + - const: atu + - const: addr_space + - const: apb + + interrupts: + maxItems: 4 + + interrupt-names: + items: + - const: pcie + - const: pcie_ev + - const: pcie_err + - const: pcie_mem_access + + num-lanes: + description: Number of lanes to use. + enum: [ 1, 2 ] + +required: + - compatible + - reg + - reg-names + - interrupts + - interrupt-names + +additionalProperties: false + +examples: + - | + #include + #include + pcie-ep@37000000 { + compatible = "intel,keembay-pcie-ep"; + reg = <0x37000000 0x00001000>, + <0x37100000 0x00001000>, + <0x37300000 0x00001000>, + <0x36000000 0x01000000>, + <0x37800000 0x00000200>; + reg-names = "dbi", "dbi2", "atu", "addr_space", "apb"; + interrupts = , + , + , + ; + interrupt-names = "pcie", "pcie_ev", "pcie_err", "pcie_mem_access"; + num-lanes = <2>; + }; diff --git a/Documentation/devicetree/bindings/pci/intel,keembay-pcie.yaml b/Documentation/devicetree/bindings/pci/intel,keembay-pcie.yaml new file mode 100644 index 000000000000..ed4400c9ac09 --- /dev/null +++ b/Documentation/devicetree/bindings/pci/intel,keembay-pcie.yaml @@ -0,0 +1,97 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: "http://devicetree.org/schemas/pci/intel,keembay-pcie.yaml#" +$schema: "http://devicetree.org/meta-schemas/core.yaml#" + +title: Intel Keem Bay PCIe controller Root Complex mode + +maintainers: + - Wan Ahmad Zainie + - Srikanth Thokala + +allOf: + - $ref: /schemas/pci/pci-bus.yaml# + +properties: + compatible: + const: intel,keembay-pcie + + ranges: + maxItems: 1 + + reset-gpios: + maxItems: 1 + + reg: + maxItems: 4 + + reg-names: + items: + - const: dbi + - const: atu + - const: config + - const: apb + + clocks: + maxItems: 2 + + clock-names: + items: + - const: master + - const: aux + + interrupts: + maxItems: 3 + + interrupt-names: + items: + - const: pcie + - const: pcie_ev + - const: pcie_err + + num-lanes: + description: Number of lanes to use. + enum: [ 1, 2 ] + +required: + - compatible + - reg + - reg-names + - ranges + - clocks + - clock-names + - interrupts + - interrupt-names + - reset-gpios + +unevaluatedProperties: false + +examples: + - | + #include + #include + #include + #define KEEM_BAY_A53_PCIE + #define KEEM_BAY_A53_AUX_PCIE + pcie@37000000 { + compatible = "intel,keembay-pcie"; + reg = <0x37000000 0x00001000>, + <0x37300000 0x00001000>, + <0x36e00000 0x00200000>, + <0x37800000 0x00000200>; + reg-names = "dbi", "atu", "config", "apb"; + #address-cells = <3>; + #size-cells = <2>; + device_type = "pci"; + ranges = <0x02000000 0 0x36000000 0x36000000 0 0x00e00000>; + interrupts = , + , + ; + interrupt-names = "pcie", "pcie_ev", "pcie_err"; + clocks = <&scmi_clk KEEM_BAY_A53_PCIE>, + <&scmi_clk KEEM_BAY_A53_AUX_PCIE>; + clock-names = "master", "aux"; + reset-gpios = <&pca2 9 GPIO_ACTIVE_LOW>; + num-lanes = <2>; + }; diff --git a/Documentation/devicetree/bindings/pci/mediatek-pcie-cfg.yaml b/Documentation/devicetree/bindings/pci/mediatek-pcie-cfg.yaml new file mode 100644 index 000000000000..841a3d284bbf --- /dev/null +++ b/Documentation/devicetree/bindings/pci/mediatek-pcie-cfg.yaml @@ -0,0 +1,39 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/pci/mediatek-pcie-cfg.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: MediaTek PCIECFG controller + +maintainers: + - Chuanjia Liu + - Jianjun Wang + +description: | + The MediaTek PCIECFG controller controls some feature about + LTSSM, ASPM and so on. + +properties: + compatible: + items: + - enum: + - mediatek,generic-pciecfg + - const: syscon + + reg: + maxItems: 1 + +required: + - compatible + - reg + +additionalProperties: false + +examples: + - | + pciecfg: pciecfg@1a140000 { + compatible = "mediatek,generic-pciecfg", "syscon"; + reg = <0x1a140000 0x1000>; + }; +... diff --git a/Documentation/devicetree/bindings/pci/mediatek-pcie.txt b/Documentation/devicetree/bindings/pci/mediatek-pcie.txt index 7468d666763a..57ae73462272 100644 --- a/Documentation/devicetree/bindings/pci/mediatek-pcie.txt +++ b/Documentation/devicetree/bindings/pci/mediatek-pcie.txt @@ -8,7 +8,7 @@ Required properties: "mediatek,mt7623-pcie" "mediatek,mt7629-pcie" - device_type: Must be "pci" -- reg: Base addresses and lengths of the PCIe subsys and root ports. +- reg: Base addresses and lengths of the root ports. - reg-names: Names of the above areas to use during resource lookup. - #address-cells: Address representation for root ports (must be 3) - #size-cells: Size representation for root ports (must be 2) @@ -47,9 +47,12 @@ Required properties for MT7623/MT2701: - reset-names: Must be "pcie-rst0", "pcie-rst1", "pcie-rstN".. based on the number of root ports. -Required properties for MT2712/MT7622: +Required properties for MT2712/MT7622/MT7629: -interrupts: A list of interrupt outputs of the controller, must have one entry for each PCIe port +- interrupt-names: Must include the following entries: + - "pcie_irq": The interrupt that is asserted when an MSI/INTX is received +- linux,pci-domain: PCI domain ID. Should be unique for each host controller In addition, the device tree node must have sub-nodes describing each PCIe port interface, having the following mandatory properties: @@ -143,130 +146,143 @@ Examples for MT7623: Examples for MT2712: - pcie: pcie@11700000 { + pcie1: pcie@112ff000 { compatible = "mediatek,mt2712-pcie"; device_type = "pci"; - reg = <0 0x11700000 0 0x1000>, - <0 0x112ff000 0 0x1000>; - reg-names = "port0", "port1"; + reg = <0 0x112ff000 0 0x1000>; + reg-names = "port1"; + linux,pci-domain = <1>; #address-cells = <3>; #size-cells = <2>; - interrupts = , - ; - clocks = <&topckgen CLK_TOP_PE2_MAC_P0_SEL>, - <&topckgen CLK_TOP_PE2_MAC_P1_SEL>, - <&pericfg CLK_PERI_PCIE0>, + interrupts = ; + interrupt-names = "pcie_irq"; + clocks = <&topckgen CLK_TOP_PE2_MAC_P1_SEL>, <&pericfg CLK_PERI_PCIE1>; - clock-names = "sys_ck0", "sys_ck1", "ahb_ck0", "ahb_ck1"; - phys = <&pcie0_phy PHY_TYPE_PCIE>, <&pcie1_phy PHY_TYPE_PCIE>; - phy-names = "pcie-phy0", "pcie-phy1"; + clock-names = "sys_ck1", "ahb_ck1"; + phys = <&u3port1 PHY_TYPE_PCIE>; + phy-names = "pcie-phy1"; bus-range = <0x00 0xff>; - ranges = <0x82000000 0 0x20000000 0x0 0x20000000 0 0x10000000>; + ranges = <0x82000000 0 0x11400000 0x0 0x11400000 0 0x300000>; + status = "disabled"; - pcie0: pcie@0,0 { - reg = <0x0000 0 0 0 0>; - #address-cells = <3>; - #size-cells = <2>; + #interrupt-cells = <1>; + interrupt-map-mask = <0 0 0 7>; + interrupt-map = <0 0 0 1 &pcie_intc1 0>, + <0 0 0 2 &pcie_intc1 1>, + <0 0 0 3 &pcie_intc1 2>, + <0 0 0 4 &pcie_intc1 3>; + pcie_intc1: interrupt-controller { + interrupt-controller; + #address-cells = <0>; #interrupt-cells = <1>; - ranges; - interrupt-map-mask = <0 0 0 7>; - interrupt-map = <0 0 0 1 &pcie_intc0 0>, - <0 0 0 2 &pcie_intc0 1>, - <0 0 0 3 &pcie_intc0 2>, - <0 0 0 4 &pcie_intc0 3>; - pcie_intc0: interrupt-controller { - interrupt-controller; - #address-cells = <0>; - #interrupt-cells = <1>; - }; }; + }; - pcie1: pcie@1,0 { - reg = <0x0800 0 0 0 0>; - #address-cells = <3>; - #size-cells = <2>; + pcie0: pcie@11700000 { + compatible = "mediatek,mt2712-pcie"; + device_type = "pci"; + reg = <0 0x11700000 0 0x1000>; + reg-names = "port0"; + linux,pci-domain = <0>; + #address-cells = <3>; + #size-cells = <2>; + interrupts = ; + interrupt-names = "pcie_irq"; + clocks = <&topckgen CLK_TOP_PE2_MAC_P0_SEL>, + <&pericfg CLK_PERI_PCIE0>; + clock-names = "sys_ck0", "ahb_ck0"; + phys = <&u3port0 PHY_TYPE_PCIE>; + phy-names = "pcie-phy0"; + bus-range = <0x00 0xff>; + ranges = <0x82000000 0 0x20000000 0x0 0x20000000 0 0x10000000>; + status = "disabled"; + + #interrupt-cells = <1>; + interrupt-map-mask = <0 0 0 7>; + interrupt-map = <0 0 0 1 &pcie_intc0 0>, + <0 0 0 2 &pcie_intc0 1>, + <0 0 0 3 &pcie_intc0 2>, + <0 0 0 4 &pcie_intc0 3>; + pcie_intc0: interrupt-controller { + interrupt-controller; + #address-cells = <0>; #interrupt-cells = <1>; - ranges; - interrupt-map-mask = <0 0 0 7>; - interrupt-map = <0 0 0 1 &pcie_intc1 0>, - <0 0 0 2 &pcie_intc1 1>, - <0 0 0 3 &pcie_intc1 2>, - <0 0 0 4 &pcie_intc1 3>; - pcie_intc1: interrupt-controller { - interrupt-controller; - #address-cells = <0>; - #interrupt-cells = <1>; - }; }; }; Examples for MT7622: - pcie: pcie@1a140000 { + pcie0: pcie@1a143000 { compatible = "mediatek,mt7622-pcie"; device_type = "pci"; - reg = <0 0x1a140000 0 0x1000>, - <0 0x1a143000 0 0x1000>, - <0 0x1a145000 0 0x1000>; - reg-names = "subsys", "port0", "port1"; + reg = <0 0x1a143000 0 0x1000>; + reg-names = "port0"; + linux,pci-domain = <0>; #address-cells = <3>; #size-cells = <2>; - interrupts = , - ; + interrupts = ; + interrupt-names = "pcie_irq"; clocks = <&pciesys CLK_PCIE_P0_MAC_EN>, - <&pciesys CLK_PCIE_P1_MAC_EN>, <&pciesys CLK_PCIE_P0_AHB_EN>, - <&pciesys CLK_PCIE_P1_AHB_EN>, <&pciesys CLK_PCIE_P0_AUX_EN>, - <&pciesys CLK_PCIE_P1_AUX_EN>, <&pciesys CLK_PCIE_P0_AXI_EN>, - <&pciesys CLK_PCIE_P1_AXI_EN>, <&pciesys CLK_PCIE_P0_OBFF_EN>, - <&pciesys CLK_PCIE_P1_OBFF_EN>, - <&pciesys CLK_PCIE_P0_PIPE_EN>, - <&pciesys CLK_PCIE_P1_PIPE_EN>; - clock-names = "sys_ck0", "sys_ck1", "ahb_ck0", "ahb_ck1", - "aux_ck0", "aux_ck1", "axi_ck0", "axi_ck1", - "obff_ck0", "obff_ck1", "pipe_ck0", "pipe_ck1"; - phys = <&pcie0_phy PHY_TYPE_PCIE>, <&pcie1_phy PHY_TYPE_PCIE>; - phy-names = "pcie-phy0", "pcie-phy1"; + <&pciesys CLK_PCIE_P0_PIPE_EN>; + clock-names = "sys_ck0", "ahb_ck0", "aux_ck0", + "axi_ck0", "obff_ck0", "pipe_ck0"; + power-domains = <&scpsys MT7622_POWER_DOMAIN_HIF0>; bus-range = <0x00 0xff>; - ranges = <0x82000000 0 0x20000000 0x0 0x20000000 0 0x10000000>; + ranges = <0x82000000 0 0x20000000 0x0 0x20000000 0 0x8000000>; + status = "disabled"; - pcie0: pcie@0,0 { - reg = <0x0000 0 0 0 0>; - #address-cells = <3>; - #size-cells = <2>; + #interrupt-cells = <1>; + interrupt-map-mask = <0 0 0 7>; + interrupt-map = <0 0 0 1 &pcie_intc0 0>, + <0 0 0 2 &pcie_intc0 1>, + <0 0 0 3 &pcie_intc0 2>, + <0 0 0 4 &pcie_intc0 3>; + pcie_intc0: interrupt-controller { + interrupt-controller; + #address-cells = <0>; #interrupt-cells = <1>; - ranges; - interrupt-map-mask = <0 0 0 7>; - interrupt-map = <0 0 0 1 &pcie_intc0 0>, - <0 0 0 2 &pcie_intc0 1>, - <0 0 0 3 &pcie_intc0 2>, - <0 0 0 4 &pcie_intc0 3>; - pcie_intc0: interrupt-controller { - interrupt-controller; - #address-cells = <0>; - #interrupt-cells = <1>; - }; }; + }; - pcie1: pcie@1,0 { - reg = <0x0800 0 0 0 0>; - #address-cells = <3>; - #size-cells = <2>; + pcie1: pcie@1a145000 { + compatible = "mediatek,mt7622-pcie"; + device_type = "pci"; + reg = <0 0x1a145000 0 0x1000>; + reg-names = "port1"; + linux,pci-domain = <1>; + #address-cells = <3>; + #size-cells = <2>; + interrupts = ; + interrupt-names = "pcie_irq"; + clocks = <&pciesys CLK_PCIE_P1_MAC_EN>, + /* designer has connect RC1 with p0_ahb clock */ + <&pciesys CLK_PCIE_P0_AHB_EN>, + <&pciesys CLK_PCIE_P1_AUX_EN>, + <&pciesys CLK_PCIE_P1_AXI_EN>, + <&pciesys CLK_PCIE_P1_OBFF_EN>, + <&pciesys CLK_PCIE_P1_PIPE_EN>; + clock-names = "sys_ck1", "ahb_ck1", "aux_ck1", + "axi_ck1", "obff_ck1", "pipe_ck1"; + + power-domains = <&scpsys MT7622_POWER_DOMAIN_HIF0>; + bus-range = <0x00 0xff>; + ranges = <0x82000000 0 0x28000000 0x0 0x28000000 0 0x8000000>; + status = "disabled"; + + #interrupt-cells = <1>; + interrupt-map-mask = <0 0 0 7>; + interrupt-map = <0 0 0 1 &pcie_intc1 0>, + <0 0 0 2 &pcie_intc1 1>, + <0 0 0 3 &pcie_intc1 2>, + <0 0 0 4 &pcie_intc1 3>; + pcie_intc1: interrupt-controller { + interrupt-controller; + #address-cells = <0>; #interrupt-cells = <1>; - ranges; - interrupt-map-mask = <0 0 0 7>; - interrupt-map = <0 0 0 1 &pcie_intc1 0>, - <0 0 0 2 &pcie_intc1 1>, - <0 0 0 3 &pcie_intc1 2>, - <0 0 0 4 &pcie_intc1 3>; - pcie_intc1: interrupt-controller { - interrupt-controller; - #address-cells = <0>; - #interrupt-cells = <1>; - }; }; }; diff --git a/Documentation/devicetree/bindings/pci/pci-ep.yaml b/Documentation/devicetree/bindings/pci/pci-ep.yaml index 7847bbcd4a03..ccec51ab5247 100644 --- a/Documentation/devicetree/bindings/pci/pci-ep.yaml +++ b/Documentation/devicetree/bindings/pci/pci-ep.yaml @@ -23,6 +23,13 @@ properties: default: 1 maximum: 255 + max-virtual-functions: + description: Array representing the number of virtual functions corresponding to each physical + function + $ref: /schemas/types.yaml#/definitions/uint8-array + minItems: 1 + maxItems: 255 + max-link-speed: $ref: /schemas/types.yaml#/definitions/uint32 enum: [ 1, 2, 3, 4 ] diff --git a/Documentation/devicetree/bindings/pci/xilinx-nwl-pcie.txt b/Documentation/devicetree/bindings/pci/xilinx-nwl-pcie.txt index 2d677e90a7e2..f56f8c58c5d9 100644 --- a/Documentation/devicetree/bindings/pci/xilinx-nwl-pcie.txt +++ b/Documentation/devicetree/bindings/pci/xilinx-nwl-pcie.txt @@ -35,6 +35,7 @@ Required properties: Optional properties: - dma-coherent: present if DMA operations are coherent +- clocks: Input clock specifier. Refer to common clock bindings Example: ++++++++ diff --git a/Documentation/devicetree/bindings/power/power-domain.yaml b/Documentation/devicetree/bindings/power/power-domain.yaml index aed51e9dcb11..3143ed9a3313 100644 --- a/Documentation/devicetree/bindings/power/power-domain.yaml +++ b/Documentation/devicetree/bindings/power/power-domain.yaml @@ -46,7 +46,7 @@ properties: Phandles to the OPP tables of power domains provided by a power domain provider. If the provider provides a single power domain only or all the power domains provided by the provider have identical OPP tables, - then this shall contain a single phandle. Refer to ../opp/opp.txt + then this shall contain a single phandle. Refer to ../opp/opp-v2-base.yaml for more information. "#power-domain-cells": diff --git a/Documentation/devicetree/bindings/power/reset/qcom,pon.txt b/Documentation/devicetree/bindings/power/reset/qcom,pon.txt deleted file mode 100644 index 0c0dc3a1e693..000000000000 --- a/Documentation/devicetree/bindings/power/reset/qcom,pon.txt +++ /dev/null @@ -1,49 +0,0 @@ -Qualcomm PON Device - -The Power On device for Qualcomm PM8xxx is MFD supporting pwrkey -and resin along with the Android reboot-mode. - -This DT node has pwrkey and resin as sub nodes. - -Required Properties: --compatible: Must be one of: - "qcom,pm8916-pon" - "qcom,pms405-pon" - "qcom,pm8998-pon" - --reg: Specifies the physical address of the pon register - -Optional subnode: --pwrkey: Specifies the subnode pwrkey and should follow the - qcom,pm8941-pwrkey.txt description. --resin: Specifies the subnode resin and should follow the - qcom,pm8xxx-pwrkey.txt description. - -The rest of the properties should follow the generic reboot-mode description -found in reboot-mode.txt - -Example: - - pon@800 { - compatible = "qcom,pm8916-pon"; - - reg = <0x800>; - mode-bootloader = <0x2>; - mode-recovery = <0x1>; - - pwrkey { - compatible = "qcom,pm8941-pwrkey"; - interrupts = <0x0 0x8 0 IRQ_TYPE_EDGE_BOTH>; - debounce = <15625>; - bias-pull-up; - linux,code = ; - }; - - resin { - compatible = "qcom,pm8941-resin"; - interrupts = <0x0 0x8 1 IRQ_TYPE_EDGE_BOTH>; - debounce = <15625>; - bias-pull-up; - linux,code = ; - }; - }; diff --git a/Documentation/devicetree/bindings/power/reset/qcom,pon.yaml b/Documentation/devicetree/bindings/power/reset/qcom,pon.yaml new file mode 100644 index 000000000000..353f155df0f4 --- /dev/null +++ b/Documentation/devicetree/bindings/power/reset/qcom,pon.yaml @@ -0,0 +1,80 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/power/reset/qcom,pon.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Qualcomm PON Device + +maintainers: + - Vinod Koul + +description: | + The Power On device for Qualcomm PM8xxx is MFD supporting pwrkey + and resin along with the Android reboot-mode. + + This DT node has pwrkey and resin as sub nodes. + +allOf: + - $ref: reboot-mode.yaml# + +properties: + compatible: + enum: + - qcom,pm8916-pon + - qcom,pms405-pon + - qcom,pm8998-pon + + reg: + maxItems: 1 + + pwrkey: + type: object + $ref: "../../input/qcom,pm8941-pwrkey.yaml#" + + resin: + type: object + $ref: "../../input/qcom,pm8941-pwrkey.yaml#" + +required: + - compatible + - reg + +unevaluatedProperties: false + +examples: + - | + #include + #include + #include + spmi_bus: spmi@c440000 { + reg = <0x0c440000 0x1100>; + #address-cells = <2>; + #size-cells = <0>; + pmk8350: pmic@0 { + reg = <0x0 SPMI_USID>; + #address-cells = <1>; + #size-cells = <0>; + pmk8350_pon: pon_hlos@1300 { + reg = <0x1300>; + compatible = "qcom,pm8998-pon"; + + pwrkey { + compatible = "qcom,pm8941-pwrkey"; + interrupts = < 0x0 0x8 0 IRQ_TYPE_EDGE_BOTH >; + debounce = <15625>; + bias-pull-up; + linux,code = ; + }; + + resin { + compatible = "qcom,pm8941-resin"; + interrupts = <0x0 0x8 1 IRQ_TYPE_EDGE_BOTH>; + debounce = <15625>; + bias-pull-up; + linux,code = ; + }; + }; + }; + }; +... diff --git a/Documentation/devicetree/bindings/power/reset/reboot-mode.yaml b/Documentation/devicetree/bindings/power/reset/reboot-mode.yaml index 9c6fda6b1dd9..ad0a0b95cec1 100644 --- a/Documentation/devicetree/bindings/power/reset/reboot-mode.yaml +++ b/Documentation/devicetree/bindings/power/reset/reboot-mode.yaml @@ -36,7 +36,7 @@ patternProperties: "^mode-.*$": $ref: /schemas/types.yaml#/definitions/uint32 -additionalProperties: false +additionalProperties: true examples: - | diff --git a/Documentation/devicetree/bindings/pwm/pwm-rockchip.yaml b/Documentation/devicetree/bindings/pwm/pwm-rockchip.yaml index 5596bee70509..81a54a4e8e3e 100644 --- a/Documentation/devicetree/bindings/pwm/pwm-rockchip.yaml +++ b/Documentation/devicetree/bindings/pwm/pwm-rockchip.yaml @@ -29,6 +29,7 @@ properties: - enum: - rockchip,px30-pwm - rockchip,rk3308-pwm + - rockchip,rk3568-pwm - const: rockchip,rk3328-pwm reg: diff --git a/Documentation/devicetree/bindings/remoteproc/qcom,adsp.yaml b/Documentation/devicetree/bindings/remoteproc/qcom,adsp.yaml index c597ccced623..0c112f3264a9 100644 --- a/Documentation/devicetree/bindings/remoteproc/qcom,adsp.yaml +++ b/Documentation/devicetree/bindings/remoteproc/qcom,adsp.yaml @@ -28,6 +28,7 @@ properties: - qcom,sc8180x-adsp-pas - qcom,sc8180x-cdsp-pas - qcom,sc8180x-mpss-pas + - qcom,sdm660-adsp-pas - qcom,sdm845-adsp-pas - qcom,sdm845-cdsp-pas - qcom,sdx55-mpss-pas diff --git a/Documentation/devicetree/bindings/rtc/trivial-rtc.yaml b/Documentation/devicetree/bindings/rtc/trivial-rtc.yaml index 7548d8714871..13925bb78ec7 100644 --- a/Documentation/devicetree/bindings/rtc/trivial-rtc.yaml +++ b/Documentation/devicetree/bindings/rtc/trivial-rtc.yaml @@ -32,6 +32,9 @@ properties: - dallas,ds3232 # I2C-BUS INTERFACE REAL TIME CLOCK MODULE - epson,rx8010 + # I2C-BUS INTERFACE REAL TIME CLOCK MODULE + - epson,rx8025 + - epson,rx8035 # I2C-BUS INTERFACE REAL TIME CLOCK MODULE with Battery Backed RAM - epson,rx8571 # I2C-BUS INTERFACE REAL TIME CLOCK MODULE diff --git a/Documentation/devicetree/bindings/sound/fsl,rpmsg.yaml b/Documentation/devicetree/bindings/sound/fsl,rpmsg.yaml index 61802a11baf4..d370c98a62c7 100644 --- a/Documentation/devicetree/bindings/sound/fsl,rpmsg.yaml +++ b/Documentation/devicetree/bindings/sound/fsl,rpmsg.yaml @@ -21,6 +21,7 @@ properties: - fsl,imx8mn-rpmsg-audio - fsl,imx8mm-rpmsg-audio - fsl,imx8mp-rpmsg-audio + - fsl,imx8ulp-rpmsg-audio model: $ref: /schemas/types.yaml#/definitions/string diff --git a/Documentation/devicetree/bindings/sound/mt8195-afe-pcm.yaml b/Documentation/devicetree/bindings/sound/mt8195-afe-pcm.yaml index 53e9434a6d9d..dcf790b053d2 100644 --- a/Documentation/devicetree/bindings/sound/mt8195-afe-pcm.yaml +++ b/Documentation/devicetree/bindings/sound/mt8195-afe-pcm.yaml @@ -130,36 +130,34 @@ additionalProperties: false examples: - | - #include #include #include - #include afe: mt8195-afe-pcm@10890000 { compatible = "mediatek,mt8195-audio"; reg = <0x10890000 0x10000>; interrupts = ; mediatek,topckgen = <&topckgen>; - power-domains = <&spm MT8195_POWER_DOMAIN_AUDIO>; + power-domains = <&spm 7>; //MT8195_POWER_DOMAIN_AUDIO clocks = <&clk26m>, - <&topckgen CLK_TOP_APLL1>, - <&topckgen CLK_TOP_APLL2>, - <&topckgen CLK_TOP_APLL12_DIV0>, - <&topckgen CLK_TOP_APLL12_DIV1>, - <&topckgen CLK_TOP_APLL12_DIV2>, - <&topckgen CLK_TOP_APLL12_DIV3>, - <&topckgen CLK_TOP_APLL12_DIV9>, - <&topckgen CLK_TOP_A1SYS_HP_SEL>, - <&topckgen CLK_TOP_AUD_INTBUS_SEL>, - <&topckgen CLK_TOP_AUDIO_H_SEL>, - <&topckgen CLK_TOP_AUDIO_LOCAL_BUS_SEL>, - <&topckgen CLK_TOP_DPTX_M_SEL>, - <&topckgen CLK_TOP_I2SO1_M_SEL>, - <&topckgen CLK_TOP_I2SO2_M_SEL>, - <&topckgen CLK_TOP_I2SI1_M_SEL>, - <&topckgen CLK_TOP_I2SI2_M_SEL>, - <&infracfg_ao CLK_INFRA_AO_AUDIO_26M_B>, - <&scp_adsp CLK_SCP_ADSP_AUDIODSP>; + <&topckgen 163>, //CLK_TOP_APLL1 + <&topckgen 166>, //CLK_TOP_APLL2 + <&topckgen 233>, //CLK_TOP_APLL12_DIV0 + <&topckgen 234>, //CLK_TOP_APLL12_DIV1 + <&topckgen 235>, //CLK_TOP_APLL12_DIV2 + <&topckgen 236>, //CLK_TOP_APLL12_DIV3 + <&topckgen 238>, //CLK_TOP_APLL12_DIV9 + <&topckgen 100>, //CLK_TOP_A1SYS_HP_SEL + <&topckgen 33>, //CLK_TOP_AUD_INTBUS_SEL + <&topckgen 34>, //CLK_TOP_AUDIO_H_SEL + <&topckgen 107>, //CLK_TOP_AUDIO_LOCAL_BUS_SEL + <&topckgen 98>, //CLK_TOP_DPTX_M_SEL + <&topckgen 94>, //CLK_TOP_I2SO1_M_SEL + <&topckgen 95>, //CLK_TOP_I2SO2_M_SEL + <&topckgen 96>, //CLK_TOP_I2SI1_M_SEL + <&topckgen 97>, //CLK_TOP_I2SI2_M_SEL + <&infracfg_ao 50>, //CLK_INFRA_AO_AUDIO_26M_B + <&scp_adsp 0>; //CLK_SCP_ADSP_AUDIODSP clock-names = "clk26m", "apll1_ck", "apll2_ck", diff --git a/Documentation/devicetree/bindings/spi/omap-spi.yaml b/Documentation/devicetree/bindings/spi/omap-spi.yaml index e55538186cf6..9952199cae11 100644 --- a/Documentation/devicetree/bindings/spi/omap-spi.yaml +++ b/Documentation/devicetree/bindings/spi/omap-spi.yaml @@ -84,9 +84,9 @@ unevaluatedProperties: false if: properties: compatible: - oneOf: - - const: ti,omap2-mcspi - - const: ti,omap4-mcspi + enum: + - ti,omap2-mcspi + - ti,omap4-mcspi then: properties: diff --git a/Documentation/devicetree/bindings/spi/spi-xilinx.yaml b/Documentation/devicetree/bindings/spi/spi-xilinx.yaml index 593f7693bace..03e5dca7e933 100644 --- a/Documentation/devicetree/bindings/spi/spi-xilinx.yaml +++ b/Documentation/devicetree/bindings/spi/spi-xilinx.yaml @@ -27,13 +27,11 @@ properties: xlnx,num-ss-bits: description: Number of chip selects used. - $ref: /schemas/types.yaml#/definitions/uint32 minimum: 1 maximum: 32 xlnx,num-transfer-bits: description: Number of bits per transfer. This will be 8 if not specified. - $ref: /schemas/types.yaml#/definitions/uint32 enum: [8, 16, 32] default: 8 diff --git a/Documentation/devicetree/bindings/thermal/qcom-lmh.yaml b/Documentation/devicetree/bindings/thermal/qcom-lmh.yaml new file mode 100644 index 000000000000..289e9a845600 --- /dev/null +++ b/Documentation/devicetree/bindings/thermal/qcom-lmh.yaml @@ -0,0 +1,82 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +# Copyright 2021 Linaro Ltd. +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/thermal/qcom-lmh.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Qualcomm Limits Management Hardware(LMh) + +maintainers: + - Thara Gopinath + +description: + Limits Management Hardware(LMh) is a hardware infrastructure on some + Qualcomm SoCs that can enforce temperature and current limits as + programmed by software for certain IPs like CPU. + +properties: + compatible: + enum: + - qcom,sdm845-lmh + + reg: + items: + - description: core registers + + interrupts: + maxItems: 1 + + '#interrupt-cells': + const: 1 + + interrupt-controller: true + + cpus: + description: + phandle of the first cpu in the LMh cluster + $ref: /schemas/types.yaml#/definitions/phandle + + qcom,lmh-temp-arm-millicelsius: + description: + An integer expressing temperature threshold at which the LMh thermal + FSM is engaged. + + qcom,lmh-temp-low-millicelsius: + description: + An integer expressing temperature threshold at which the state machine + will attempt to remove frequency throttling. + + qcom,lmh-temp-high-millicelsius: + description: + An integer expressing temperature threshold at which the state machine + will attempt to throttle the frequency. + +required: + - compatible + - reg + - interrupts + - '#interrupt-cells' + - interrupt-controller + - cpus + - qcom,lmh-temp-arm-millicelsius + - qcom,lmh-temp-low-millicelsius + - qcom,lmh-temp-high-millicelsius + +additionalProperties: false + +examples: + - | + #include + + lmh@17d70800 { + compatible = "qcom,sdm845-lmh"; + reg = <0x17d70800 0x400>; + interrupts = ; + cpus = <&CPU4>; + qcom,lmh-temp-arm-millicelsius = <65000>; + qcom,lmh-temp-low-millicelsius = <94500>; + qcom,lmh-temp-high-millicelsius = <95000>; + interrupt-controller; + #interrupt-cells = <1>; + }; diff --git a/Documentation/devicetree/bindings/thermal/thermal-zones.yaml b/Documentation/devicetree/bindings/thermal/thermal-zones.yaml index 164f71598c59..a07de5ed0ca6 100644 --- a/Documentation/devicetree/bindings/thermal/thermal-zones.yaml +++ b/Documentation/devicetree/bindings/thermal/thermal-zones.yaml @@ -215,7 +215,7 @@ patternProperties: - polling-delay - polling-delay-passive - thermal-sensors - - trips + additionalProperties: false additionalProperties: false diff --git a/Documentation/devicetree/bindings/virtio/mmio.yaml b/Documentation/devicetree/bindings/virtio/mmio.yaml index d46597028cf1..4b7a0273181c 100644 --- a/Documentation/devicetree/bindings/virtio/mmio.yaml +++ b/Documentation/devicetree/bindings/virtio/mmio.yaml @@ -36,7 +36,8 @@ required: - reg - interrupts -additionalProperties: false +additionalProperties: + type: object examples: - | diff --git a/Documentation/devicetree/bindings/virtio/virtio-device.yaml b/Documentation/devicetree/bindings/virtio/virtio-device.yaml new file mode 100644 index 000000000000..1778ea9b5aa5 --- /dev/null +++ b/Documentation/devicetree/bindings/virtio/virtio-device.yaml @@ -0,0 +1,41 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/virtio/virtio-device.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Virtio device bindings + +maintainers: + - Viresh Kumar + +description: + These bindings are applicable to virtio devices irrespective of the bus they + are bound to, like mmio or pci. + +# We need a select here so we don't match all nodes with 'virtio,mmio' +properties: + compatible: + pattern: "^virtio,device[0-9a-f]{1,8}$" + description: Virtio device nodes. + "virtio,deviceID", where ID is the virtio device id. The textual + representation of ID shall be in lower case hexadecimal with leading + zeroes suppressed. + +required: + - compatible + +additionalProperties: true + +examples: + - | + virtio@3000 { + compatible = "virtio,mmio"; + reg = <0x3000 0x100>; + interrupts = <43>; + + i2c { + compatible = "virtio,device22"; + }; + }; +... diff --git a/Documentation/devicetree/bindings/watchdog/maxim,max63xx.yaml b/Documentation/devicetree/bindings/watchdog/maxim,max63xx.yaml new file mode 100644 index 000000000000..ab9641e845db --- /dev/null +++ b/Documentation/devicetree/bindings/watchdog/maxim,max63xx.yaml @@ -0,0 +1,44 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/watchdog/maxim,max63xx.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Maxim 63xx Watchdog Timers + +allOf: + - $ref: "watchdog.yaml#" + +maintainers: + - Marc Zyngier + - Linus Walleij + +properties: + compatible: + enum: + - maxim,max6369 + - maxim,max6370 + - maxim,max6371 + - maxim,max6372 + - maxim,max6373 + - maxim,max6374 + + reg: + description: This is a 1-byte memory-mapped address + maxItems: 1 + +required: + - compatible + - reg + +unevaluatedProperties: false + +examples: + - | + wdt: watchdog@50000000 { + compatible = "maxim,max6369"; + reg = <0x50000000 0x1>; + timeout-sec = <10>; + }; + +... diff --git a/Documentation/devicetree/bindings/watchdog/mtk-wdt.txt b/Documentation/devicetree/bindings/watchdog/mtk-wdt.txt index 416d716403f6..a4e31ce96e0e 100644 --- a/Documentation/devicetree/bindings/watchdog/mtk-wdt.txt +++ b/Documentation/devicetree/bindings/watchdog/mtk-wdt.txt @@ -13,6 +13,7 @@ Required properties: "mediatek,mt7622-wdt", "mediatek,mt6589-wdt": for MT7622 "mediatek,mt7623-wdt", "mediatek,mt6589-wdt": for MT7623 "mediatek,mt7629-wdt", "mediatek,mt6589-wdt": for MT7629 + "mediatek,mt7986-wdt", "mediatek,mt6589-wdt": for MT7986 "mediatek,mt8183-wdt": for MT8183 "mediatek,mt8516-wdt", "mediatek,mt6589-wdt": for MT8516 "mediatek,mt8192-wdt": for MT8192 diff --git a/Documentation/driver-api/cxl/memory-devices.rst b/Documentation/driver-api/cxl/memory-devices.rst index 487ce4f41d77..50ebcda17ad0 100644 --- a/Documentation/driver-api/cxl/memory-devices.rst +++ b/Documentation/driver-api/cxl/memory-devices.rst @@ -36,9 +36,15 @@ CXL Core .. kernel-doc:: drivers/cxl/cxl.h :internal: -.. kernel-doc:: drivers/cxl/core.c +.. kernel-doc:: drivers/cxl/core/bus.c :doc: cxl core +.. kernel-doc:: drivers/cxl/core/pmem.c + :doc: cxl pmem + +.. kernel-doc:: drivers/cxl/core/regs.c + :doc: cxl registers + External Interfaces =================== diff --git a/Documentation/driver-api/gpio/consumer.rst b/Documentation/driver-api/gpio/consumer.rst index 3366a991b4aa..47869ca8ccf0 100644 --- a/Documentation/driver-api/gpio/consumer.rst +++ b/Documentation/driver-api/gpio/consumer.rst @@ -72,6 +72,10 @@ for the GPIO. Values can be: * GPIOD_OUT_HIGH_OPEN_DRAIN same as GPIOD_OUT_HIGH but also enforce the line to be electrically used with open drain. +Note that the initial value is *logical* and the physical line level depends on +whether the line is configured active high or active low (see +:ref:`active_low_semantics`). + The two last flags are used for use cases where open drain is mandatory, such as I2C: if the line is not already configured as open drain in the mappings (see board.txt), then open drain will be enforced anyway and a warning will be @@ -252,6 +256,8 @@ that can't be accessed from hardIRQ handlers, these calls act the same as the spinlock-safe calls. +.. _active_low_semantics: + The active low and open drain semantics --------------------------------------- As a consumer should not have to care about the physical line level, all of the @@ -309,9 +315,11 @@ work on the raw line value:: void gpiod_set_raw_value_cansleep(struct gpio_desc *desc, int value) int gpiod_direction_output_raw(struct gpio_desc *desc, int value) -The active low state of a GPIO can also be queried using the following call:: +The active low state of a GPIO can also be queried and toggled using the +following calls:: int gpiod_is_active_low(const struct gpio_desc *desc) + void gpiod_toggle_active_low(struct gpio_desc *desc) Note that these functions should only be used with great moderation; a driver should not have to care about the physical line level or open drain semantics. diff --git a/Documentation/driver-api/gpio/driver.rst b/Documentation/driver-api/gpio/driver.rst index d6b0d779859b..bbc53920d4dd 100644 --- a/Documentation/driver-api/gpio/driver.rst +++ b/Documentation/driver-api/gpio/driver.rst @@ -547,13 +547,10 @@ To use the helpers please keep the following in mind: the irqchip can initialize. E.g. .dev and .can_sleep shall be set up properly. -- Nominally set all handlers to handle_bad_irq() in the setup call and pass - handle_bad_irq() as flow handler parameter in gpiochip_irqchip_add() if it is - expected for GPIO driver that irqchip .set_type() callback will be called - before using/enabling each GPIO IRQ. Then set the handler to - handle_level_irq() and/or handle_edge_irq() in the irqchip .set_type() - callback depending on what your controller supports and what is requested - by the consumer. +- Nominally set gpio_irq_chip.handler to handle_bad_irq. Then, if your irqchip + is cascaded, set the handler to handle_level_irq() and/or handle_edge_irq() + in the irqchip .set_type() callback depending on what your controller + supports and what is requested by the consumer. Locking IRQ usage diff --git a/Documentation/features/vm/ELF-ASLR/arch-support.txt b/Documentation/features/vm/ELF-ASLR/arch-support.txt index 99cb6d7f5005..2949c99fbb2f 100644 --- a/Documentation/features/vm/ELF-ASLR/arch-support.txt +++ b/Documentation/features/vm/ELF-ASLR/arch-support.txt @@ -22,7 +22,7 @@ | openrisc: | TODO | | parisc: | ok | | powerpc: | ok | - | riscv: | TODO | + | riscv: | ok | | s390: | ok | | sh: | TODO | | sparc: | TODO | diff --git a/Documentation/features/vm/huge-vmap/arch-support.txt b/Documentation/features/vm/huge-vmap/arch-support.txt index 439fd9069b8b..bc53905a0306 100644 --- a/Documentation/features/vm/huge-vmap/arch-support.txt +++ b/Documentation/features/vm/huge-vmap/arch-support.txt @@ -1,7 +1,7 @@ # # Feature name: huge-vmap # Kconfig: HAVE_ARCH_HUGE_VMAP -# description: arch supports the ioremap_pud_enabled() and ioremap_pmd_enabled() VM APIs +# description: arch supports the arch_vmap_pud_supported() and arch_vmap_pmd_supported() VM APIs # ----------------------- | arch |status| diff --git a/Documentation/filesystems/api-summary.rst b/Documentation/filesystems/api-summary.rst index 7e5c04c98619..98db2ea5fa12 100644 --- a/Documentation/filesystems/api-summary.rst +++ b/Documentation/filesystems/api-summary.rst @@ -71,9 +71,6 @@ Other Functions .. kernel-doc:: fs/fs-writeback.c :export: -.. kernel-doc:: fs/block_dev.c - :export: - .. kernel-doc:: fs/anon_inodes.c :export: diff --git a/Documentation/gpu/drm-mm.rst b/Documentation/gpu/drm-mm.rst index d5a73fa2c9ef..8126beadc7df 100644 --- a/Documentation/gpu/drm-mm.rst +++ b/Documentation/gpu/drm-mm.rst @@ -37,7 +37,7 @@ TTM initialization This section is outdated. Drivers wishing to support TTM must pass a filled :c:type:`ttm_bo_driver -` structure to ttm_bo_device_init, together with an +` structure to ttm_device_init, together with an initialized global reference to the memory manager. The ttm_bo_driver structure contains several fields with function pointers for initializing the TTM, allocating and freeing memory, waiting for command diff --git a/Documentation/kbuild/llvm.rst b/Documentation/kbuild/llvm.rst index e87ed5479963..d32616891dcf 100644 --- a/Documentation/kbuild/llvm.rst +++ b/Documentation/kbuild/llvm.rst @@ -130,9 +130,10 @@ Getting Help ------------ - `Website `_ -- `Mailing List `_: +- `Mailing List `_: +- `Old Mailing List Archives `_ - `Issue Tracker `_ -- IRC: #clangbuiltlinux on chat.freenode.net +- IRC: #clangbuiltlinux on irc.libera.chat - `Telegram `_: @ClangBuiltLinux - `Wiki `_ - `Beginner Bugs `_ diff --git a/Documentation/kernel-hacking/hacking.rst b/Documentation/kernel-hacking/hacking.rst index df65c19aa7df..55bd37a2efb0 100644 --- a/Documentation/kernel-hacking/hacking.rst +++ b/Documentation/kernel-hacking/hacking.rst @@ -76,8 +76,8 @@ handler is never re-entered: if the same interrupt arrives, it is queued fast: frequently it simply acknowledges the interrupt, marks a 'software interrupt' for execution and exits. -You can tell you are in a hardware interrupt, because -:c:func:`in_irq()` returns true. +You can tell you are in a hardware interrupt, because in_hardirq() returns +true. .. warning:: diff --git a/Documentation/kernel-hacking/locking.rst b/Documentation/kernel-hacking/locking.rst index ed1284c6f078..90bc3f51eda9 100644 --- a/Documentation/kernel-hacking/locking.rst +++ b/Documentation/kernel-hacking/locking.rst @@ -94,16 +94,10 @@ primitives, but I'll pretend they don't exist. Locking in the Linux Kernel =========================== -If I could give you one piece of advice: never sleep with anyone crazier -than yourself. But if I had to give you advice on locking: **keep it -simple**. +If I could give you one piece of advice on locking: **keep it simple**. Be reluctant to introduce new locks. -Strangely enough, this last one is the exact reverse of my advice when -you **have** slept with someone crazier than yourself. And you should -think about getting a big dog. - Two Main Types of Kernel Locks: Spinlocks and Mutexes ----------------------------------------------------- @@ -1406,7 +1400,7 @@ bh half will be running at any time. Hardware Interrupt / Hardware IRQ - Hardware interrupt request. in_irq() returns true in a + Hardware interrupt request. in_hardirq() returns true in a hardware interrupt handler. Interrupt Context @@ -1418,7 +1412,7 @@ SMP (``CONFIG_SMP=y``). Software Interrupt / softirq - Software interrupt handler. in_irq() returns false; + Software interrupt handler. in_hardirq() returns false; in_softirq() returns true. Tasklets and softirqs both fall into the category of 'software interrupts'. diff --git a/Documentation/locking/futex-requeue-pi.rst b/Documentation/locking/futex-requeue-pi.rst index 14ab5787b9a7..dd4ecf4528a4 100644 --- a/Documentation/locking/futex-requeue-pi.rst +++ b/Documentation/locking/futex-requeue-pi.rst @@ -5,7 +5,7 @@ Futex Requeue PI Requeueing of tasks from a non-PI futex to a PI futex requires special handling in order to ensure the underlying rt_mutex is never left without an owner if it has waiters; doing so would break the PI -boosting logic [see rt-mutex-desgin.txt] For the purposes of +boosting logic [see rt-mutex-design.rst] For the purposes of brevity, this action will be referred to as "requeue_pi" throughout this document. Priority inheritance is abbreviated throughout as "PI". diff --git a/Documentation/locking/ww-mutex-design.rst b/Documentation/locking/ww-mutex-design.rst index 54d9c17bb66b..6a4d7319f8f0 100644 --- a/Documentation/locking/ww-mutex-design.rst +++ b/Documentation/locking/ww-mutex-design.rst @@ -2,7 +2,7 @@ Wound/Wait Deadlock-Proof Mutex Design ====================================== -Please read mutex-design.txt first, as it applies to wait/wound mutexes too. +Please read mutex-design.rst first, as it applies to wait/wound mutexes too. Motivation for WW-Mutexes ------------------------- diff --git a/Documentation/networking/nf_conntrack-sysctl.rst b/Documentation/networking/nf_conntrack-sysctl.rst index 34ca762ea56f..311128abb768 100644 --- a/Documentation/networking/nf_conntrack-sysctl.rst +++ b/Documentation/networking/nf_conntrack-sysctl.rst @@ -17,9 +17,8 @@ nf_conntrack_acct - BOOLEAN nf_conntrack_buckets - INTEGER Size of hash table. If not specified as parameter during module loading, the default size is calculated by dividing total memory - by 16384 to determine the number of buckets but the hash table will - never have fewer than 32 and limited to 16384 buckets. For systems - with more than 4GB of memory it will be 65536 buckets. + by 16384 to determine the number of buckets. The hash table will + never have fewer than 1024 and never more than 262144 buckets. This sysctl is only writeable in the initial net namespace. nf_conntrack_checksum - BOOLEAN @@ -100,8 +99,12 @@ nf_conntrack_log_invalid - INTEGER Log invalid packets of a type specified by value. nf_conntrack_max - INTEGER - Size of connection tracking table. Default value is - nf_conntrack_buckets value * 4. + Maximum number of allowed connection tracking entries. This value is set + to nf_conntrack_buckets by default. + Note that connection tracking entries are added to the table twice -- once + for the original direction and once for the reply direction (i.e., with + the reversed address). This means that with default settings a maxed-out + table will have a average hash chain length of 2, not 1. nf_conntrack_tcp_be_liberal - BOOLEAN - 0 - disabled (default) diff --git a/Documentation/power/energy-model.rst b/Documentation/power/energy-model.rst index 60ac091d3b0d..8a2788afe89b 100644 --- a/Documentation/power/energy-model.rst +++ b/Documentation/power/energy-model.rst @@ -101,8 +101,7 @@ subsystems which use EM might rely on this flag to check if all EM devices use the same scale. If there are different scales, these subsystems might decide to: return warning/error, stop working or panic. See Section 3. for an example of driver implementing this -callback, and kernel/power/energy_model.c for further documentation on this -API. +callback, or Section 2.4 for further documentation on this API 2.3 Accessing performance domains @@ -123,7 +122,17 @@ em_cpu_energy() API. The estimation is performed assuming that the schedutil CPUfreq governor is in use in case of CPU device. Currently this calculation is not provided for other type of devices. -More details about the above APIs can be found in include/linux/energy_model.h. +More details about the above APIs can be found in ```` +or in Section 2.4 + + +2.4 Description details of this API +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. kernel-doc:: include/linux/energy_model.h + :internal: + +.. kernel-doc:: kernel/power/energy_model.c + :export: 3. Example driver diff --git a/Documentation/process/applying-patches.rst b/Documentation/process/applying-patches.rst index 2e7017bef4b8..c2121c1e55d7 100644 --- a/Documentation/process/applying-patches.rst +++ b/Documentation/process/applying-patches.rst @@ -389,7 +389,7 @@ The -mm patches are experimental patches released by Andrew Morton. In the past, -mm tree were used to also test subsystem patches, but this function is now done via the -`linux-next ` +`linux-next` (https://www.kernel.org/doc/man-pages/linux-next.html) tree. The Subsystem maintainers push their patches first to linux-next, and, during the merge window, sends them directly to Linus. diff --git a/Documentation/process/kernel-docs.rst b/Documentation/process/kernel-docs.rst index 22d9ace5df2a..da9527502ef0 100644 --- a/Documentation/process/kernel-docs.rst +++ b/Documentation/process/kernel-docs.rst @@ -126,15 +126,17 @@ On-line docs describes how to write user-mode utilities for communicating with Card Services. - * Title: **Linux Kernel Module Programming Guide** + * Title: **The Linux Kernel Module Programming Guide** - :Author: Ori Pomerantz. - :URL: https://tldp.org/LDP/lkmpg/2.6/html/index.html - :Date: 2001 + :Author: Peter Jay Salzman, Michael Burian, Ori Pomerantz, Bob Mottram, + Jim Huang. + :URL: https://sysprog21.github.io/lkmpg/ + :Date: 2021 :Keywords: modules, GPL book, /proc, ioctls, system calls, interrupt handlers . - :Description: Very nice 92 pages GPL book on the topic of modules - programming. Lots of examples. + :Description: A very nice GPL book on the topic of modules + programming. Lots of examples. Currently the new version is being + actively maintained at https://github.com/sysprog21/lkmpg. * Title: **Global spinlock list and usage** diff --git a/Documentation/process/maintainer-pgp-guide.rst b/Documentation/process/maintainer-pgp-guide.rst index 8f8f1fee92b8..29e7d7b1cd44 100644 --- a/Documentation/process/maintainer-pgp-guide.rst +++ b/Documentation/process/maintainer-pgp-guide.rst @@ -944,12 +944,11 @@ have on your keyring:: uid [ unknown] Linus Torvalds sub rsa2048 2011-09-20 [E] -Next, open the `PGP pathfinder`_. In the "From" field, paste the key -fingerprint of Linus Torvalds from the output above. In the "To" field, -paste the key-id you found via ``gpg --search`` of the unknown key, and -check the results: - -- `Finding paths to Linus`_ +Next, find a trust path from Linus Torvalds to the key-id you found via ``gpg +--search`` of the unknown key. For this, you can use several tools including +https://github.com/mricon/wotmate, +https://git.kernel.org/pub/scm/docs/kernel/pgpkeys.git/tree/graphs, and +https://the.earth.li/~noodles/pathfind.html. If you get a few decent trust paths, then it's a pretty good indication that it is a valid key. You can add it to your keyring from the @@ -962,6 +961,3 @@ administrators of the PGP Pathfinder service to not be malicious (in fact, this goes against :ref:`devs_not_infra`). However, if you do not carefully maintain your own web of trust, then it is a marked improvement over blindly trusting keyservers. - -.. _`PGP pathfinder`: https://pgp.cs.uu.nl/ -.. _`Finding paths to Linus`: https://pgp.cs.uu.nl/paths/79BE3E4300411886/to/C94035C21B4F2AEB.html diff --git a/Documentation/translations/it_IT/kernel-hacking/hacking.rst b/Documentation/translations/it_IT/kernel-hacking/hacking.rst index b4ea00f1b583..d5c521327f6a 100644 --- a/Documentation/translations/it_IT/kernel-hacking/hacking.rst +++ b/Documentation/translations/it_IT/kernel-hacking/hacking.rst @@ -90,7 +90,7 @@ i gestori d'interruzioni devono essere veloci: spesso si limitano esclusivamente a notificare la presa in carico dell'interruzione, programmare una 'interruzione software' per l'esecuzione e quindi terminare. -Potete dire d'essere in una interruzione hardware perché :c:func:`in_irq()` +Potete dire d'essere in una interruzione hardware perché in_hardirq() ritorna vero. .. warning:: diff --git a/Documentation/translations/it_IT/kernel-hacking/locking.rst b/Documentation/translations/it_IT/kernel-hacking/locking.rst index 1e7c84def369..1efb8293bf1f 100644 --- a/Documentation/translations/it_IT/kernel-hacking/locking.rst +++ b/Documentation/translations/it_IT/kernel-hacking/locking.rst @@ -1459,11 +1459,11 @@ contesto utente che hardware. interruzione hardware - Richiesta di interruzione hardware. in_irq() ritorna vero in un + Richiesta di interruzione hardware. in_hardirq() ritorna vero in un gestore d'interruzioni hardware. interruzione software / softirq - Gestore di interruzioni software: in_irq() ritorna falso; + Gestore di interruzioni software: in_hardirq() ritorna falso; in_softirq() ritorna vero. I tasklet e le softirq sono entrambi considerati 'interruzioni software'. diff --git a/Documentation/translations/zh_CN/core-api/cachetlb.rst b/Documentation/translations/zh_CN/core-api/cachetlb.rst index 55827b8a7c53..6fee45fe5e80 100644 --- a/Documentation/translations/zh_CN/core-api/cachetlb.rst +++ b/Documentation/translations/zh_CN/core-api/cachetlb.rst @@ -80,7 +80,7 @@ cpu上对这个地址空间进行刷新。 5) ``void update_mmu_cache(struct vm_area_struct *vma, unsigned long address, pte_t *ptep)`` - 在每个页面故障结束时，这个程序被调用，以告诉体系结构特定的代码，在 + 在每个缺页异常结束时，这个程序被调用，以告诉体系结构特定的代码，在 软件页表中，在地址空间“vma->vm_mm”的虚拟地址“地址”处，现在存在 一个翻译。 diff --git a/Documentation/translations/zh_CN/core-api/index.rst b/Documentation/translations/zh_CN/core-api/index.rst index d5e947d8b6f1..72f0a36daa1c 100644 --- a/Documentation/translations/zh_CN/core-api/index.rst +++ b/Documentation/translations/zh_CN/core-api/index.rst @@ -1,10 +1,12 @@ .. include:: ../disclaimer-zh_CN.rst -:Original: :doc:`../../../core-api/irq/index` -:Translator: Yanteng Si +:Original: Documentation/core-api/index.rst -.. _cn_core-api_index.rst: +:翻译: + + 司延腾 Yanteng Si +.. _cn_core-api_index.rst: =========== 核心API文档 diff --git a/Documentation/translations/zh_CN/core-api/irq/concepts.rst b/Documentation/translations/zh_CN/core-api/irq/concepts.rst index 41455bf0f783..9957f0453353 100644 --- a/Documentation/translations/zh_CN/core-api/irq/concepts.rst +++ b/Documentation/translations/zh_CN/core-api/irq/concepts.rst @@ -1,10 +1,12 @@ .. include:: ../../disclaimer-zh_CN.rst -:Original: :doc:`../../../../core-api/irq/concepts` -:Translator: Yanteng Si +:Original: Documentation/core-api/irq/concepts.rst -.. _cn_concepts.rst: +:翻译: + + 司延腾 Yanteng Si +.. _cn_concepts.rst: =========== 什么是IRQ？ diff --git a/Documentation/translations/zh_CN/core-api/irq/index.rst b/Documentation/translations/zh_CN/core-api/irq/index.rst index 910ccabf041f..ba6acc4b48e5 100644 --- a/Documentation/translations/zh_CN/core-api/irq/index.rst +++ b/Documentation/translations/zh_CN/core-api/irq/index.rst @@ -1,7 +1,10 @@ .. include:: ../../disclaimer-zh_CN.rst -:Original: :doc:`../../../../core-api/irq/index` -:Translator: Yanteng Si +:Original: Documentation/core-api/irq/index.rst + +:翻译: + + 司延腾 Yanteng Si .. _cn_irq_index.rst: diff --git a/Documentation/translations/zh_CN/core-api/irq/irq-affinity.rst b/Documentation/translations/zh_CN/core-api/irq/irq-affinity.rst index 82a4428f22fd..7addd5f27a88 100644 --- a/Documentation/translations/zh_CN/core-api/irq/irq-affinity.rst +++ b/Documentation/translations/zh_CN/core-api/irq/irq-affinity.rst @@ -1,10 +1,12 @@ .. include:: ../../disclaimer-zh_CN.rst -:Original: :doc:`../../../../core-api/irq/irq-affinity` -:Translator: Yanteng Si +:Original: Documentation/core-api/irq/irq-affinity -.. _cn_irq-affinity.rst: +:翻译: + + 司延腾 Yanteng Si +.. _cn_irq-affinity.rst: ============== SMP IRQ 亲和性 diff --git a/Documentation/translations/zh_CN/core-api/irq/irq-domain.rst b/Documentation/translations/zh_CN/core-api/irq/irq-domain.rst index 3c82dd307a46..7d077742f758 100644 --- a/Documentation/translations/zh_CN/core-api/irq/irq-domain.rst +++ b/Documentation/translations/zh_CN/core-api/irq/irq-domain.rst @@ -1,10 +1,12 @@ .. include:: ../../disclaimer-zh_CN.rst -:Original: :doc:`../../../../core-api/irq/irq-domain` -:Translator: Yanteng Si +:Original: Documentation/core-api/irq/irq-domain.rst -.. _cn_irq-domain.rst: +:翻译: + + 司延腾 Yanteng Si +.. _cn_irq-domain.rst: ======================= irq_domain 中断号映射库 diff --git a/Documentation/translations/zh_CN/core-api/irq/irqflags-tracing.rst b/Documentation/translations/zh_CN/core-api/irq/irqflags-tracing.rst index c889bd0f65d9..9af50b4b8c2d 100644 --- a/Documentation/translations/zh_CN/core-api/irq/irqflags-tracing.rst +++ b/Documentation/translations/zh_CN/core-api/irq/irqflags-tracing.rst @@ -1,10 +1,12 @@ .. include:: ../../disclaimer-zh_CN.rst -:Original: :doc:`../../../../core-api/irq/irqflags-tracing` -:Translator: Yanteng Si +:Original: Documentation/core-api/irq/irqflags-tracing.rst -.. _cn_irqflags-tracing.rst: +:翻译: + + 司延腾 Yanteng Si +.. _cn_irqflags-tracing.rst: ================= IRQ-flags状态追踪 diff --git a/Documentation/translations/zh_CN/core-api/kernel-api.rst b/Documentation/translations/zh_CN/core-api/kernel-api.rst index d6f815ec265b..ab7d81889340 100644 --- a/Documentation/translations/zh_CN/core-api/kernel-api.rst +++ b/Documentation/translations/zh_CN/core-api/kernel-api.rst @@ -1,10 +1,12 @@ .. include:: ../disclaimer-zh_CN.rst :Original: Documentation/core-api/kernel-api.rst -:Translator: Yanteng Si -.. _cn_kernel-api.rst: +:翻译: + + 司延腾 Yanteng Si +.. _cn_kernel-api.rst: ============ Linux内核API diff --git a/Documentation/translations/zh_CN/core-api/kobject.rst b/Documentation/translations/zh_CN/core-api/kobject.rst index f0e6a4aeb372..b7c37794cc7f 100644 --- a/Documentation/translations/zh_CN/core-api/kobject.rst +++ b/Documentation/translations/zh_CN/core-api/kobject.rst @@ -1,7 +1,10 @@ .. include:: ../disclaimer-zh_CN.rst :Original: Documentation/core-api/kobject.rst -:Translator: Yanteng Si + +:翻译: + + 司延腾 Yanteng Si .. _cn_core_api_kobject.rst: diff --git a/Documentation/translations/zh_CN/core-api/local_ops.rst b/Documentation/translations/zh_CN/core-api/local_ops.rst index ee67379b6869..41e4525038e8 100644 --- a/Documentation/translations/zh_CN/core-api/local_ops.rst +++ b/Documentation/translations/zh_CN/core-api/local_ops.rst @@ -1,10 +1,12 @@ .. include:: ../disclaimer-zh_CN.rst :Original: Documentation/core-api/local_ops.rst -:Translator: Yanteng Si -.. _cn_local_ops: +:翻译: + + 司延腾 Yanteng Si +.. _cn_local_ops: ======================== 本地原子操作的语义和行为 diff --git a/Documentation/translations/zh_CN/core-api/padata.rst b/Documentation/translations/zh_CN/core-api/padata.rst index c627f8f131f9..781d30675afd 100644 --- a/Documentation/translations/zh_CN/core-api/padata.rst +++ b/Documentation/translations/zh_CN/core-api/padata.rst @@ -3,7 +3,10 @@ .. include:: ../disclaimer-zh_CN.rst :Original: Documentation/core-api/padata.rst -:Translator: Yanteng Si + +:翻译: + + 司延腾 Yanteng Si .. _cn_core_api_padata.rst: diff --git a/Documentation/translations/zh_CN/core-api/printk-basics.rst b/Documentation/translations/zh_CN/core-api/printk-basics.rst index 2b20f6303a82..d574de3167c8 100644 --- a/Documentation/translations/zh_CN/core-api/printk-basics.rst +++ b/Documentation/translations/zh_CN/core-api/printk-basics.rst @@ -2,10 +2,12 @@ .. include:: ../disclaimer-zh_CN.rst :Original: Documentation/core-api/printk-basics.rst -:Translator: Yanteng Si -.. _cn_printk-basics.rst: +:翻译: + + 司延腾 Yanteng Si +.. _cn_printk-basics.rst: ================== 使用printk记录消息 diff --git a/Documentation/translations/zh_CN/core-api/printk-formats.rst b/Documentation/translations/zh_CN/core-api/printk-formats.rst index a680c8f164c3..ce39c788cf5a 100644 --- a/Documentation/translations/zh_CN/core-api/printk-formats.rst +++ b/Documentation/translations/zh_CN/core-api/printk-formats.rst @@ -1,10 +1,12 @@ .. include:: ../disclaimer-zh_CN.rst :Original: Documentation/core-api/printk-formats.rst -:Translator: Yanteng Si -.. _cn_printk-formats.rst: +:翻译: + + 司延腾 Yanteng Si +.. _cn_printk-formats.rst: ============================== 如何获得正确的printk格式占位符 diff --git a/Documentation/translations/zh_CN/core-api/refcount-vs-atomic.rst b/Documentation/translations/zh_CN/core-api/refcount-vs-atomic.rst index ea834e38d2f6..e2467fd26fc0 100644 --- a/Documentation/translations/zh_CN/core-api/refcount-vs-atomic.rst +++ b/Documentation/translations/zh_CN/core-api/refcount-vs-atomic.rst @@ -1,10 +1,12 @@ .. include:: ../disclaimer-zh_CN.rst :Original: Documentation/core-api/refcount-vs-atomic.rst -:Translator: Yanteng Si -.. _cn_refcount-vs-atomic: +:翻译: + + 司延腾 Yanteng Si +.. _cn_refcount-vs-atomic: ======================================= 与atomic_t相比，refcount_t的API是这样的 diff --git a/Documentation/translations/zh_CN/core-api/symbol-namespaces.rst b/Documentation/translations/zh_CN/core-api/symbol-namespaces.rst index ce05c29c7697..6abf7ed534ca 100644 --- a/Documentation/translations/zh_CN/core-api/symbol-namespaces.rst +++ b/Documentation/translations/zh_CN/core-api/symbol-namespaces.rst @@ -1,10 +1,12 @@ .. include:: ../disclaimer-zh_CN.rst :Original: Documentation/core-api/symbol-namespaces.rst -:Translator: Yanteng Si -.. _cn_symbol-namespaces.rst: +:翻译: + + 司延腾 Yanteng Si +.. _cn_symbol-namespaces.rst: ================================= 符号命名空间（Symbol Namespaces） diff --git a/Documentation/translations/zh_CN/core-api/workqueue.rst b/Documentation/translations/zh_CN/core-api/workqueue.rst index 0b8f730db6c0..e372fa5cf101 100644 --- a/Documentation/translations/zh_CN/core-api/workqueue.rst +++ b/Documentation/translations/zh_CN/core-api/workqueue.rst @@ -2,10 +2,12 @@ .. include:: ../disclaimer-zh_CN.rst :Original: Documentation/core-api/workqueue.rst -:Translator: Yanteng Si -.. _cn_workqueue.rst: +:翻译: + + 司延腾 Yanteng Si +.. _cn_workqueue.rst: ========================= 并发管理的工作队列 (cmwq) diff --git a/Documentation/translations/zh_CN/cpu-freq/core.rst b/Documentation/translations/zh_CN/cpu-freq/core.rst index 19fb9c029cfe..0c6fd447ced6 100644 --- a/Documentation/translations/zh_CN/cpu-freq/core.rst +++ b/Documentation/translations/zh_CN/cpu-freq/core.rst @@ -1,11 +1,13 @@ .. SPDX-License-Identifier: GPL-2.0 .. include:: ../disclaimer-zh_CN.rst -:Original: :doc:`../../../cpu-freq/core` -:Translator: Yanteng Si +:Original: Documentation/cpu-freq/core.rst -.. _cn_core.rst: +:翻译: + + 司延腾 Yanteng Si +.. _cn_core.rst: ==================================== CPUFreq核心和CPUFreq通知器的通用说明 diff --git a/Documentation/translations/zh_CN/cpu-freq/cpu-drivers.rst b/Documentation/translations/zh_CN/cpu-freq/cpu-drivers.rst index 5ae9cfa2ec55..0fc5d1495789 100644 --- a/Documentation/translations/zh_CN/cpu-freq/cpu-drivers.rst +++ b/Documentation/translations/zh_CN/cpu-freq/cpu-drivers.rst @@ -2,11 +2,13 @@ .. include:: ../disclaimer-zh_CN.rst -:Original: :doc:`../../../cpu-freq/cpu-drivers` -:Translator: Yanteng Si +:Original: Documentation/cpu-freq/cpu-drivers.rst -.. _cn_cpu-drivers.rst: +:翻译: + + 司延腾 Yanteng Si +.. _cn_cpu-drivers.rst: ======================================= 如何实现一个新的CPUFreq处理器驱动程序？ @@ -80,8 +82,6 @@ CPUfreq核心层注册一个cpufreq_driver结构体。 .resume - 一个指向per-policy恢复函数的指针，该函数在关中断且在调节器再一次开始前被 调用。 - .ready - 一个指向per-policy准备函数的指针，该函数在策略完全初始化之后被调用。 - .attr - 一个指向NULL结尾的"struct freq_attr"列表的指针，该函数允许导出值到 sysfs。 diff --git a/Documentation/translations/zh_CN/cpu-freq/cpufreq-stats.rst b/Documentation/translations/zh_CN/cpu-freq/cpufreq-stats.rst index c90d1d8353ed..f14423099d4b 100644 --- a/Documentation/translations/zh_CN/cpu-freq/cpufreq-stats.rst +++ b/Documentation/translations/zh_CN/cpu-freq/cpufreq-stats.rst @@ -2,11 +2,13 @@ .. include:: ../disclaimer-zh_CN.rst -:Original: :doc:`../../../cpu-freq/cpufreq-stats` -:Translator: Yanteng Si +:Original: Documentation/cpu-freq/cpufreq-stats.rst -.. _cn_cpufreq-stats.rst: +:翻译: + + 司延腾 Yanteng Si +.. _cn_cpufreq-stats.rst: ========================================== sysfs CPUFreq Stats的一般说明 diff --git a/Documentation/translations/zh_CN/cpu-freq/index.rst b/Documentation/translations/zh_CN/cpu-freq/index.rst index 65074e211940..c6e50963cd33 100644 --- a/Documentation/translations/zh_CN/cpu-freq/index.rst +++ b/Documentation/translations/zh_CN/cpu-freq/index.rst @@ -2,11 +2,13 @@ .. include:: ../disclaimer-zh_CN.rst -:Original: :doc:`../../../cpu-freq/index` -:Translator: Yanteng Si +:Original: Documentation/cpu-freq/index.rst -.. _cn_index.rst: +:翻译: + + 司延腾 Yanteng Si +.. _cn_index.rst: ======================================================= Linux CPUFreq - Linux(TM)内核中的CPU频率和电压升降代码 diff --git a/Documentation/translations/zh_CN/filesystems/debugfs.rst b/Documentation/translations/zh_CN/filesystems/debugfs.rst index 822c4d42fdf9..4981a82dd651 100644 --- a/Documentation/translations/zh_CN/filesystems/debugfs.rst +++ b/Documentation/translations/zh_CN/filesystems/debugfs.rst @@ -2,7 +2,7 @@ .. include:: ../disclaimer-zh_CN.rst -:Original: :doc:`../../../filesystems/debugfs` +:Original: Documentation/filesystems/debugfs.rst ======= Debugfs diff --git a/Documentation/translations/zh_CN/iio/ep93xx_adc.rst b/Documentation/translations/zh_CN/iio/ep93xx_adc.rst index 7e91d2197867..64f3f3508353 100644 --- a/Documentation/translations/zh_CN/iio/ep93xx_adc.rst +++ b/Documentation/translations/zh_CN/iio/ep93xx_adc.rst @@ -1,10 +1,12 @@ .. include:: ../disclaimer-zh_CN.rst -:Original: :doc:`../../../iio/ep93xx_adc` -:Translator: Yanteng Si +:Original: Documentation/iio/ep93xx_adc.rst -.. _cn_iio_ep93xx_adc: +:翻译: + + 司延腾 Yanteng Si +.. _cn_iio_ep93xx_adc: ================================== 思睿逻辑 EP93xx 模拟数字转换器驱动 diff --git a/Documentation/translations/zh_CN/iio/iio_configfs.rst b/Documentation/translations/zh_CN/iio/iio_configfs.rst index 274488e8dce4..d5460e951804 100644 --- a/Documentation/translations/zh_CN/iio/iio_configfs.rst +++ b/Documentation/translations/zh_CN/iio/iio_configfs.rst @@ -1,10 +1,12 @@ .. include:: ../disclaimer-zh_CN.rst -:Original: :doc:`../../../iio/iio_configfs` -:Translator: Yanteng Si +:Original: Documentation/iio/iio_configfs.rst -.. _cn_iio_configfs: +:翻译: + + 司延腾 Yanteng Si +.. _cn_iio_configfs: ===================== 工业 IIO configfs支持 diff --git a/Documentation/translations/zh_CN/iio/index.rst b/Documentation/translations/zh_CN/iio/index.rst index 7087076a10f6..32d69047b16a 100644 --- a/Documentation/translations/zh_CN/iio/index.rst +++ b/Documentation/translations/zh_CN/iio/index.rst @@ -2,11 +2,13 @@ .. include:: ../disclaimer-zh_CN.rst -:Original: :doc:`../../../iio/index` -:Translator: Yanteng Si +:Original: Documentation/iio/index.rst -.. _cn_iio_index: +:翻译: + + 司延腾 Yanteng Si +.. _cn_iio_index: ======== 工业 I/O diff --git a/Documentation/translations/zh_CN/kernel-hacking/hacking.rst b/Documentation/translations/zh_CN/kernel-hacking/hacking.rst index ab974faddecf..f2bc154c5bcc 100644 --- a/Documentation/translations/zh_CN/kernel-hacking/hacking.rst +++ b/Documentation/translations/zh_CN/kernel-hacking/hacking.rst @@ -68,7 +68,7 @@ 它将被排队（或丢弃）。因为它会关闭中断，所以处理程序必须很快：通常它只是 确认中断，标记一个“软件中断”以执行并退出。 -您可以通过 :c:func:`in_irq()` 返回真来判断您处于硬件中断状态。 +您可以通过 in_hardirq() 返回真来判断您处于硬件中断状态。 .. warning:: diff --git a/Documentation/translations/zh_CN/mips/booting.rst b/Documentation/translations/zh_CN/mips/booting.rst index 96453e1b962e..e0bbd3f20862 100644 --- a/Documentation/translations/zh_CN/mips/booting.rst +++ b/Documentation/translations/zh_CN/mips/booting.rst @@ -2,8 +2,11 @@ .. include:: ../disclaimer-zh_CN.rst -:Original: :doc:`../../../mips/booting` -:Translator: Yanteng Si +:Original: Documentation/mips/booting.rst + +:翻译: + + 司延腾 Yanteng Si .. _cn_booting: diff --git a/Documentation/translations/zh_CN/mips/features.rst b/Documentation/translations/zh_CN/mips/features.rst index 93d93d06b1b3..b61dab06ceaf 100644 --- a/Documentation/translations/zh_CN/mips/features.rst +++ b/Documentation/translations/zh_CN/mips/features.rst @@ -2,8 +2,11 @@ .. include:: ../disclaimer-zh_CN.rst -:Original: :doc:`../../../mips/features` -:Translator: Yanteng Si +:Original: Documentation/mips/features.rst + +:翻译: + + 司延腾 Yanteng Si .. _cn_features: diff --git a/Documentation/translations/zh_CN/mips/index.rst b/Documentation/translations/zh_CN/mips/index.rst index b85033f9d67c..192c6adbb72e 100644 --- a/Documentation/translations/zh_CN/mips/index.rst +++ b/Documentation/translations/zh_CN/mips/index.rst @@ -2,8 +2,11 @@ .. include:: ../disclaimer-zh_CN.rst -:Original: :doc:`../../../mips/index` -:Translator: Yanteng Si +:Original: Documentation/mips/index.rst + +:翻译: + + 司延腾 Yanteng Si =========================== MIPS特性文档 diff --git a/Documentation/translations/zh_CN/mips/ingenic-tcu.rst b/Documentation/translations/zh_CN/mips/ingenic-tcu.rst index f04ba407384a..ddbe149c517b 100644 --- a/Documentation/translations/zh_CN/mips/ingenic-tcu.rst +++ b/Documentation/translations/zh_CN/mips/ingenic-tcu.rst @@ -2,8 +2,11 @@ .. include:: ../disclaimer-zh_CN.rst -:Original: :doc:`../../../mips/ingenic-tcu` -:Translator: Yanteng Si +:Original: Documentation/mips/ingenic-tcu.rst + +:翻译: + + 司延腾 Yanteng Si .. _cn_ingenic-tcu: diff --git a/Documentation/translations/zh_CN/openrisc/index.rst b/Documentation/translations/zh_CN/openrisc/index.rst index d722642796c8..9ad6cc600884 100644 --- a/Documentation/translations/zh_CN/openrisc/index.rst +++ b/Documentation/translations/zh_CN/openrisc/index.rst @@ -2,11 +2,13 @@ .. include:: ../disclaimer-zh_CN.rst -:Original: :doc:`../../../openrisc/index` -:Translator: Yanteng Si +:Original: Documentation/openrisc/index.rst -.. _cn_openrisc_index: +:翻译: + + 司延腾 Yanteng Si +.. _cn_openrisc_index: ================= OpenRISC 体系架构 diff --git a/Documentation/translations/zh_CN/openrisc/openrisc_port.rst b/Documentation/translations/zh_CN/openrisc/openrisc_port.rst index e87d0eec281d..b8a67670492d 100644 --- a/Documentation/translations/zh_CN/openrisc/openrisc_port.rst +++ b/Documentation/translations/zh_CN/openrisc/openrisc_port.rst @@ -1,7 +1,10 @@ .. include:: ../disclaimer-zh_CN.rst -:Original: :doc:`../../../openrisc/openrisc_port` -:Translator: Yanteng Si +:Original: Documentation/openrisc/openrisc_port.rst + +:翻译: + + 司延腾 Yanteng Si .. _cn_openrisc_port: diff --git a/Documentation/translations/zh_CN/openrisc/todo.rst b/Documentation/translations/zh_CN/openrisc/todo.rst index 9944ad05473b..63c38717edb1 100644 --- a/Documentation/translations/zh_CN/openrisc/todo.rst +++ b/Documentation/translations/zh_CN/openrisc/todo.rst @@ -1,7 +1,10 @@ .. include:: ../disclaimer-zh_CN.rst -:Original: :doc:`../../../openrisc/todo` -:Translator: Yanteng Si +:Original: Documentation/openrisc/todo.rst + +:翻译: + + 司延腾 Yanteng Si .. _cn_openrisc_todo.rst: diff --git a/Documentation/translations/zh_CN/parisc/debugging.rst b/Documentation/translations/zh_CN/parisc/debugging.rst index c21beb986e15..68b73eb57105 100644 --- a/Documentation/translations/zh_CN/parisc/debugging.rst +++ b/Documentation/translations/zh_CN/parisc/debugging.rst @@ -1,7 +1,10 @@ .. include:: ../disclaimer-zh_CN.rst :Original: Documentation/parisc/debugging.rst -:Translator: Yanteng Si + +:翻译: + + 司延腾 Yanteng Si .. _cn_parisc_debugging: diff --git a/Documentation/translations/zh_CN/parisc/index.rst b/Documentation/translations/zh_CN/parisc/index.rst index a47454ebe32e..0cc553fc8272 100644 --- a/Documentation/translations/zh_CN/parisc/index.rst +++ b/Documentation/translations/zh_CN/parisc/index.rst @@ -2,7 +2,10 @@ .. include:: ../disclaimer-zh_CN.rst :Original: Documentation/parisc/index.rst -:Translator: Yanteng Si + +:翻译: + + 司延腾 Yanteng Si .. _cn_parisc_index: diff --git a/Documentation/translations/zh_CN/parisc/registers.rst b/Documentation/translations/zh_CN/parisc/registers.rst index 71e2404cd103..d2ab1874a602 100644 --- a/Documentation/translations/zh_CN/parisc/registers.rst +++ b/Documentation/translations/zh_CN/parisc/registers.rst @@ -1,7 +1,10 @@ .. include:: ../disclaimer-zh_CN.rst :Original: Documentation/parisc/registers.rst -:Translator: Yanteng Si + +:翻译: + + 司延腾 Yanteng Si .. _cn_parisc_registers: diff --git a/Documentation/translations/zh_CN/riscv/boot-image-header.rst b/Documentation/translations/zh_CN/riscv/boot-image-header.rst index 241bf9c1bcbe..0234c28a7114 100644 --- a/Documentation/translations/zh_CN/riscv/boot-image-header.rst +++ b/Documentation/translations/zh_CN/riscv/boot-image-header.rst @@ -1,10 +1,12 @@ .. include:: ../disclaimer-zh_CN.rst -:Original: :doc:`../../../riscv/boot-image-header` -:Translator: Yanteng Si +:Original: Documentation/riscv/boot-image-header.rst -.. _cn_boot-image-header.rst: +:翻译: + + 司延腾 Yanteng Si +.. _cn_boot-image-header.rst: ========================== RISC-V Linux启动镜像文件头 diff --git a/Documentation/translations/zh_CN/riscv/index.rst b/Documentation/translations/zh_CN/riscv/index.rst index db13b1101490..bbf5d7b3777a 100644 --- a/Documentation/translations/zh_CN/riscv/index.rst +++ b/Documentation/translations/zh_CN/riscv/index.rst @@ -2,11 +2,13 @@ .. include:: ../disclaimer-zh_CN.rst -:Original: :doc:`../../../riscv/index` -:Translator: Yanteng Si +:Original: Documentation/riscv/index.rst -.. _cn_riscv_index: +:翻译: + + 司延腾 Yanteng Si +.. _cn_riscv_index: =============== RISC-V 体系结构 diff --git a/Documentation/translations/zh_CN/riscv/patch-acceptance.rst b/Documentation/translations/zh_CN/riscv/patch-acceptance.rst index 9fd1c8216763..d180d24717bf 100644 --- a/Documentation/translations/zh_CN/riscv/patch-acceptance.rst +++ b/Documentation/translations/zh_CN/riscv/patch-acceptance.rst @@ -2,11 +2,13 @@ .. include:: ../disclaimer-zh_CN.rst -:Original: :doc:`../../../riscv/patch-acceptance` -:Translator: Yanteng Si +:Original: Documentation/riscv/patch-acceptance.rst -.. _cn_riscv_patch-acceptance: +:翻译: + + 司延腾 Yanteng Si +.. _cn_riscv_patch-acceptance: arch/riscv 开发者维护指南 ========================= diff --git a/Documentation/translations/zh_CN/riscv/pmu.rst b/Documentation/translations/zh_CN/riscv/pmu.rst index 22dcf3a9ca6e..7ec801026c4d 100644 --- a/Documentation/translations/zh_CN/riscv/pmu.rst +++ b/Documentation/translations/zh_CN/riscv/pmu.rst @@ -1,10 +1,12 @@ .. include:: ../disclaimer-zh_CN.rst -:Original: :doc:`../../../riscv/pmu` -:Translator: Yanteng Si +:Original: Documentation/riscv/pmu.rst -.. _cn_riscv_pmu: +:翻译: + + 司延腾 Yanteng Si +.. _cn_riscv_pmu: ======================== RISC-V平台上对PMUs的支持 diff --git a/Documentation/translations/zh_TW/arm64/amu.rst b/Documentation/translations/zh_TW/arm64/amu.rst new file mode 100644 index 000000000000..ffdc466e0f62 --- /dev/null +++ b/Documentation/translations/zh_TW/arm64/amu.rst @@ -0,0 +1,104 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. include:: ../disclaimer-zh_TW.rst + +:Original: :ref:`Documentation/arm64/amu.rst ` + +Translator: Bailu Lin + Hu Haowen + +================================== +AArch64 Linux 中擴展的活動監控單元 +================================== + +作者: Ionela Voinescu + +日期: 2019-09-10 + +本文檔簡要描述了 AArch64 Linux 支持的活動監控單元的規範。 + + +架構總述 +-------- + +活動監控是 ARMv8.4 CPU 架構引入的一個可選擴展特性。 + +活動監控單元(在每個 CPU 中實現)爲系統管理提供了性能計數器。既可以通 +過系統寄存器的方式訪問計數器，同時也支持外部內存映射的方式訪問計數器。 + +AMUv1 架構實現了一個由4個固定的64位事件計數器組成的計數器組。 + + - CPU 周期計數器：同 CPU 的頻率增長 + - 常量計數器：同固定的系統時鐘頻率增長 + - 淘汰指令計數器: 同每次架構指令執行增長 + - 內存停頓周期計數器：計算由在時鐘域內的最後一級緩存中未命中而引起 + 的指令調度停頓周期數 + +當處於 WFI 或者 WFE 狀態時，計數器不會增長。 + +AMU 架構提供了一個高達16位的事件計數器空間，未來新的 AMU 版本中可能 +用它來實現新增的事件計數器。 + +另外，AMUv1 實現了一個多達16個64位輔助事件計數器的計數器組。 + +冷復位時所有的計數器會清零。 + + +基本支持 +-------- + +內核可以安全地運行在支持 AMU 和不支持 AMU 的 CPU 組合中。 +因此，當配置 CONFIG_ARM64_AMU_EXTN 後我們無條件使能後續 +(secondary or hotplugged) CPU 檢測和使用這個特性。 + +當在 CPU 上檢測到該特性時，我們會標記爲特性可用但是不能保證計數器的功能， +僅表明有擴展屬性。 + +固件(代碼運行在高異常級別，例如 arm-tf )需支持以下功能： + + - 提供低異常級別(EL2 和 EL1)訪問 AMU 寄存器的能力。 + - 使能計數器。如果未使能，它的值應爲 0。 + - 在從電源關閉狀態啓動 CPU 前或後保存或者恢復計數器。 + +當使用使能了該特性的內核啓動但固件損壞時，訪問計數器寄存器可能會遭遇 +panic 或者死鎖。即使未發現這些症狀，計數器寄存器返回的數據結果並不一 +定能反映真實情況。通常，計數器會返回 0，表明他們未被使能。 + +如果固件沒有提供適當的支持最好關閉 CONFIG_ARM64_AMU_EXTN。 +值得注意的是，出於安全原因，不要繞過 AMUSERRENR_EL0 設置而捕獲從 +EL0(用戶空間) 訪問 EL1(內核空間)。 因此，固件應該確保訪問 AMU寄存器 +不會困在 EL2或EL3。 + +AMUv1 的固定計數器可以通過如下系統寄存器訪問： + + - SYS_AMEVCNTR0_CORE_EL0 + - SYS_AMEVCNTR0_CONST_EL0 + - SYS_AMEVCNTR0_INST_RET_EL0 + - SYS_AMEVCNTR0_MEM_STALL_EL0 + +特定輔助計數器可以通過 SYS_AMEVCNTR1_EL0(n) 訪問，其中n介於0到15。 + +詳細信息定義在目錄：arch/arm64/include/asm/sysreg.h。 + + +用戶空間訪問 +------------ + +由於以下原因，當前禁止從用戶空間訪問 AMU 的寄存器： + + - 安全因數：可能會暴露處於安全模式執行的代碼信息。 + - 意願：AMU 是用於系統管理的。 + +同樣，該功能對用戶空間不可見。 + + +虛擬化 +------ + +由於以下原因，當前禁止從 KVM 客戶端的用戶空間(EL0)和內核空間(EL1) +訪問 AMU 的寄存器： + + - 安全因數：可能會暴露給其他客戶端或主機端執行的代碼信息。 + +任何試圖訪問 AMU 寄存器的行爲都會觸發一個註冊在客戶端的未定義異常。 + diff --git a/Documentation/translations/zh_TW/arm64/booting.txt b/Documentation/translations/zh_TW/arm64/booting.txt new file mode 100644 index 000000000000..b9439dd54012 --- /dev/null +++ b/Documentation/translations/zh_TW/arm64/booting.txt @@ -0,0 +1,251 @@ +SPDX-License-Identifier: GPL-2.0 + +Chinese translated version of Documentation/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 +communicating in English you can also ask the Chinese maintainer for +help. Contact the Chinese maintainer if this translation is outdated +or if there is a problem with the translation. + +M: Will Deacon +zh_CN: Fu Wei +zh_TW: Hu Haowen +C: 55f058e7574c3615dea4615573a19bdb258696c6 +--------------------------------------------------------------------- +Documentation/arm64/booting.rst 的中文翻譯 + +如果想評論或更新本文的內容，請直接聯繫原文檔的維護者。如果你使用英文 +交流有困難的話，也可以向中文版維護者求助。如果本翻譯更新不及時或者翻 +譯存在問題，請聯繫中文版維護者。 + +英文版維護者： Will Deacon +中文版維護者： 傅煒 Fu Wei +中文版翻譯者： 傅煒 Fu Wei +中文版校譯者： 傅煒 Fu Wei +繁體中文版校譯者： 胡皓文 Hu Haowen +本文翻譯提交時的 Git 檢出點爲： 55f058e7574c3615dea4615573a19bdb258696c6 + +以下爲正文 +--------------------------------------------------------------------- + 啓動 AArch64 Linux + ================== + +作者: Will Deacon +日期: 2012 年 09 月 07 日 + +本文檔基於 Russell King 的 ARM 啓動文檔，且適用於所有公開發布的 +AArch64 Linux 內核代碼。 + +AArch64 異常模型由多個異常級（EL0 - EL3）組成，對於 EL0 和 EL1 異常級 +有對應的安全和非安全模式。EL2 是系統管理級，且僅存在於非安全模式下。 +EL3 是最高特權級，且僅存在於安全模式下。 + +基於本文檔的目的，我們將簡單地使用『引導裝載程序』（『boot loader』） +這個術語來定義在將控制權交給 Linux 內核前 CPU 上執行的所有軟體。 +這可能包含安全監控和系統管理代碼，或者它可能只是一些用於準備最小啓動 +環境的指令。 + +基本上，引導裝載程序（至少）應實現以下操作： + +1、設置和初始化 RAM +2、設置設備樹數據 +3、解壓內核映像 +4、調用內核映像 + + +1、設置和初始化 RAM +----------------- + +必要性: 強制 + +引導裝載程序應該找到並初始化系統中所有內核用於保持系統變量數據的 RAM。 +這個操作的執行方式因設備而異。（它可能使用內部算法來自動定位和計算所有 +RAM，或可能使用對這個設備已知的 RAM 信息，還可能是引導裝載程序設計者 +想到的任何合適的方法。） + + +2、設置設備樹數據 +--------------- + +必要性: 強制 + +設備樹數據塊（dtb）必須 8 字節對齊，且大小不能超過 2MB。由於設備樹 +數據塊將在使能緩存的情況下以 2MB 粒度被映射，故其不能被置於必須以特定 +屬性映射的2M區域內。 + +註： v4.2 之前的版本同時要求設備樹數據塊被置於從內核映像以下 +text_offset 字節處算起第一個 512MB 內。 + +3、解壓內核映像 +------------- + +必要性: 可選 + +AArch64 內核當前沒有提供自解壓代碼，因此如果使用了壓縮內核映像文件 +（比如 Image.gz），則需要通過引導裝載程序（使用 gzip 等）來進行解壓。 +若引導裝載程序沒有實現這個功能，就要使用非壓縮內核映像文件。 + + +4、調用內核映像 +------------- + +必要性: 強制 + +已解壓的內核映像包含一個 64 字節的頭，內容如下： + + u32 code0; /* 可執行代碼 */ + u32 code1; /* 可執行代碼 */ + u64 text_offset; /* 映像裝載偏移，小端模式 */ + u64 image_size; /* 映像實際大小, 小端模式 */ + u64 flags; /* 內核旗標, 小端模式 * + u64 res2 = 0; /* 保留 */ + u64 res3 = 0; /* 保留 */ + u64 res4 = 0; /* 保留 */ + u32 magic = 0x644d5241; /* 魔數, 小端, "ARM\x64" */ + u32 res5; /* 保留 （用於 PE COFF 偏移） */ + + +映像頭注釋： + +- 自 v3.17 起，除非另有說明，所有域都是小端模式。 + +- code0/code1 負責跳轉到 stext. + +- 當通過 EFI 啓動時， 最初 code0/code1 被跳過。 + res5 是到 PE 文件頭的偏移，而 PE 文件頭含有 EFI 的啓動入口點 + （efi_stub_entry）。當 stub 代碼完成了它的使命，它會跳轉到 code0 + 繼續正常的啓動流程。 + +- v3.17 之前，未明確指定 text_offset 的字節序。此時，image_size 爲零， + 且 text_offset 依照內核字節序爲 0x80000。 + 當 image_size 非零，text_offset 爲小端模式且是有效值，應被引導加載 + 程序使用。當 image_size 爲零，text_offset 可假定爲 0x80000。 + +- flags 域 (v3.17 引入) 爲 64 位小端模式，其編碼如下： + 位 0: 內核字節序。 1 表示大端模式，0 表示小端模式。 + 位 1-2: 內核頁大小。 + 0 - 未指定。 + 1 - 4K + 2 - 16K + 3 - 64K + 位 3: 內核物理位置 + 0 - 2MB 對齊基址應儘量靠近內存起始處，因爲 + 其基址以下的內存無法通過線性映射訪問 + 1 - 2MB 對齊基址可以在物理內存的任意位置 + 位 4-63: 保留。 + +- 當 image_size 爲零時，引導裝載程序應試圖在內核映像末尾之後儘可能 + 多地保留空閒內存供內核直接使用。對內存空間的需求量因所選定的內核 + 特性而異, 並無實際限制。 + +內核映像必須被放置在任意一個可用系統內存 2MB 對齊基址的 text_offset +字節處，並從該處被調用。2MB 對齊基址和內核映像起始地址之間的區域對於 +內核來說沒有特殊意義，且可能被用於其他目的。 +從映像起始地址算起，最少必須準備 image_size 字節的空閒內存供內核使用。 +註： v4.6 之前的版本無法使用內核映像物理偏移以下的內存，所以當時建議 +將映像儘量放置在靠近系統內存起始的地方。 + +任何提供給內核的內存（甚至在映像起始地址之前），若未從內核中標記爲保留 +(如在設備樹（dtb）的 memreserve 區域），都將被認爲對內核是可用。 + +在跳轉入內核前，必須符合以下狀態： + +- 停止所有 DMA 設備，這樣內存數據就不會因爲虛假網絡包或磁碟數據而 + 被破壞。這可能可以節省你許多的調試時間。 + +- 主 CPU 通用寄存器設置 + x0 = 系統 RAM 中設備樹數據塊（dtb）的物理地址。 + x1 = 0 (保留，將來可能使用) + x2 = 0 (保留，將來可能使用) + x3 = 0 (保留，將來可能使用) + +- CPU 模式 + 所有形式的中斷必須在 PSTATE.DAIF 中被屏蔽（Debug、SError、IRQ + 和 FIQ）。 + CPU 必須處於 EL2（推薦，可訪問虛擬化擴展）或非安全 EL1 模式下。 + +- 高速緩存、MMU + MMU 必須關閉。 + 指令緩存開啓或關閉皆可。 + 已載入的內核映像的相應內存區必須被清理，以達到緩存一致性點（PoC）。 + 當存在系統緩存或其他使能緩存的一致性主控器時，通常需使用虛擬地址 + 維護其緩存，而非 set/way 操作。 + 遵從通過虛擬地址操作維護構架緩存的系統緩存必須被配置，並可以被使能。 + 而不通過虛擬地址操作維護構架緩存的系統緩存（不推薦），必須被配置且 + 禁用。 + + *譯者註：對於 PoC 以及緩存相關內容，請參考 ARMv8 構架參考手冊 + ARM DDI 0487A + +- 架構計時器 + CNTFRQ 必須設定爲計時器的頻率，且 CNTVOFF 必須設定爲對所有 CPU + 都一致的值。如果在 EL1 模式下進入內核，則 CNTHCTL_EL2 中的 + EL1PCTEN (bit 0) 必須置位。 + +- 一致性 + 通過內核啓動的所有 CPU 在內核入口地址上必須處於相同的一致性域中。 + 這可能要根據具體實現來定義初始化過程，以使能每個CPU上對維護操作的 + 接收。 + +- 系統寄存器 + 在進入內核映像的異常級中，所有構架中可寫的系統寄存器必須通過軟體 + 在一個更高的異常級別下初始化，以防止在 未知 狀態下運行。 + + 對於擁有 GICv3 中斷控制器並以 v3 模式運行的系統： + - 如果 EL3 存在： + ICC_SRE_EL3.Enable (位 3) 必須初始化爲 0b1。 + ICC_SRE_EL3.SRE (位 0) 必須初始化爲 0b1。 + - 若內核運行在 EL1： + ICC_SRE_EL2.Enable (位 3) 必須初始化爲 0b1。 + ICC_SRE_EL2.SRE (位 0) 必須初始化爲 0b1。 + - 設備樹（DT）或 ACPI 表必須描述一個 GICv3 中斷控制器。 + + 對於擁有 GICv3 中斷控制器並以兼容（v2）模式運行的系統： + - 如果 EL3 存在： + ICC_SRE_EL3.SRE (位 0) 必須初始化爲 0b0。 + - 若內核運行在 EL1： + ICC_SRE_EL2.SRE (位 0) 必須初始化爲 0b0。 + - 設備樹（DT）或 ACPI 表必須描述一個 GICv2 中斷控制器。 + +以上對於 CPU 模式、高速緩存、MMU、架構計時器、一致性、系統寄存器的 +必要條件描述適用於所有 CPU。所有 CPU 必須在同一異常級別跳入內核。 + +引導裝載程序必須在每個 CPU 處於以下狀態時跳入內核入口： + +- 主 CPU 必須直接跳入內核映像的第一條指令。通過此 CPU 傳遞的設備樹 + 數據塊必須在每個 CPU 節點中包含一個 『enable-method』 屬性，所 + 支持的 enable-method 請見下文。 + + 引導裝載程序必須生成這些設備樹屬性，並在跳入內核入口之前將其插入 + 數據塊。 + +- enable-method 爲 「spin-table」 的 CPU 必須在它們的 CPU + 節點中包含一個 『cpu-release-addr』 屬性。這個屬性標識了一個 + 64 位自然對齊且初始化爲零的內存位置。 + + 這些 CPU 必須在內存保留區（通過設備樹中的 /memreserve/ 域傳遞 + 給內核）中自旋於內核之外，輪詢它們的 cpu-release-addr 位置（必須 + 包含在保留區中）。可通過插入 wfe 指令來降低忙循環開銷，而主 CPU 將 + 發出 sev 指令。當對 cpu-release-addr 所指位置的讀取操作返回非零值 + 時，CPU 必須跳入此值所指向的地址。此值爲一個單獨的 64 位小端值， + 因此 CPU 須在跳轉前將所讀取的值轉換爲其本身的端模式。 + +- enable-method 爲 「psci」 的 CPU 保持在內核外（比如，在 + memory 節點中描述爲內核空間的內存區外，或在通過設備樹 /memreserve/ + 域中描述爲內核保留區的空間中）。內核將會發起在 ARM 文檔（編號 + ARM DEN 0022A：用於 ARM 上的電源狀態協調接口系統軟體）中描述的 + CPU_ON 調用來將 CPU 帶入內核。 + + *譯者注: ARM DEN 0022A 已更新到 ARM DEN 0022C。 + + 設備樹必須包含一個 『psci』 節點，請參考以下文檔： + Documentation/devicetree/bindings/arm/psci.yaml + + +- 輔助 CPU 通用寄存器設置 + x0 = 0 (保留，將來可能使用) + x1 = 0 (保留，將來可能使用) + x2 = 0 (保留，將來可能使用) + x3 = 0 (保留，將來可能使用) + diff --git a/Documentation/translations/zh_TW/arm64/elf_hwcaps.rst b/Documentation/translations/zh_TW/arm64/elf_hwcaps.rst new file mode 100644 index 000000000000..3eb1c623ce31 --- /dev/null +++ b/Documentation/translations/zh_TW/arm64/elf_hwcaps.rst @@ -0,0 +1,244 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. include:: ../disclaimer-zh_TW.rst + +:Original: :ref:`Documentation/arm64/elf_hwcaps.rst ` + +Translator: Bailu Lin + Hu Haowen + +================ +ARM64 ELF hwcaps +================ + +這篇文檔描述了 arm64 ELF hwcaps 的用法和語義。 + + +1. 簡介 +------- + +有些硬體或軟體功能僅在某些 CPU 實現上和/或在具體某個內核配置上可用，但 +對於處於 EL0 的用戶空間代碼沒有可用的架構發現機制。內核通過在輔助向量表 +公開一組稱爲 hwcaps 的標誌而把這些功能暴露給用戶空間。 + +用戶空間軟體可以通過獲取輔助向量的 AT_HWCAP 或 AT_HWCAP2 條目來測試功能， +並測試是否設置了相關標誌，例如:: + + bool floating_point_is_present(void) + { + unsigned long hwcaps = getauxval(AT_HWCAP); + if (hwcaps & HWCAP_FP) + return true; + + return false; + } + +如果軟體依賴於 hwcap 描述的功能，在嘗試使用該功能前則應檢查相關的 hwcap +標誌以驗證該功能是否存在。 + +不能通過其他方式探查這些功能。當一個功能不可用時，嘗試使用它可能導致不可 +預測的行爲，並且無法保證能確切的知道該功能不可用，例如 SIGILL。 + + +2. Hwcaps 的說明 +---------------- + +大多數 hwcaps 旨在說明通過架構 ID 寄存器(處於 EL0 的用戶空間代碼無法訪問) +描述的功能的存在。這些 hwcap 通過 ID 寄存器欄位定義，並且應根據 ARM 體系 +結構參考手冊（ARM ARM）中定義的欄位來解釋說明。 + +這些 hwcaps 以下面的形式描述:: + + idreg.field == val 表示有某個功能。 + +當 idreg.field 中有 val 時，hwcaps 表示 ARM ARM 定義的功能是有效的，但是 +並不是說要完全和 val 相等，也不是說 idreg.field 描述的其他功能就是缺失的。 + +其他 hwcaps 可能表明無法僅由 ID 寄存器描述的功能的存在。這些 hwcaps 可能 +沒有被 ID 寄存器描述，需要參考其他文檔。 + + +3. AT_HWCAP 中揭示的 hwcaps +--------------------------- + +HWCAP_FP + ID_AA64PFR0_EL1.FP == 0b0000 表示有此功能。 + +HWCAP_ASIMD + ID_AA64PFR0_EL1.AdvSIMD == 0b0000 表示有此功能。 + +HWCAP_EVTSTRM + 通用計時器頻率配置爲大約100KHz以生成事件。 + +HWCAP_AES + ID_AA64ISAR0_EL1.AES == 0b0001 表示有此功能。 + +HWCAP_PMULL + ID_AA64ISAR0_EL1.AES == 0b0010 表示有此功能。 + +HWCAP_SHA1 + ID_AA64ISAR0_EL1.SHA1 == 0b0001 表示有此功能。 + +HWCAP_SHA2 + ID_AA64ISAR0_EL1.SHA2 == 0b0001 表示有此功能。 + +HWCAP_CRC32 + ID_AA64ISAR0_EL1.CRC32 == 0b0001 表示有此功能。 + +HWCAP_ATOMICS + ID_AA64ISAR0_EL1.Atomic == 0b0010 表示有此功能。 + +HWCAP_FPHP + ID_AA64PFR0_EL1.FP == 0b0001 表示有此功能。 + +HWCAP_ASIMDHP + ID_AA64PFR0_EL1.AdvSIMD == 0b0001 表示有此功能。 + +HWCAP_CPUID + 根據 Documentation/arm64/cpu-feature-registers.rst 描述，EL0 可以訪問 + 某些 ID 寄存器。 + + 這些 ID 寄存器可能表示功能的可用性。 + +HWCAP_ASIMDRDM + ID_AA64ISAR0_EL1.RDM == 0b0001 表示有此功能。 + +HWCAP_JSCVT + ID_AA64ISAR1_EL1.JSCVT == 0b0001 表示有此功能。 + +HWCAP_FCMA + ID_AA64ISAR1_EL1.FCMA == 0b0001 表示有此功能。 + +HWCAP_LRCPC + ID_AA64ISAR1_EL1.LRCPC == 0b0001 表示有此功能。 + +HWCAP_DCPOP + ID_AA64ISAR1_EL1.DPB == 0b0001 表示有此功能。 + +HWCAP_SHA3 + ID_AA64ISAR0_EL1.SHA3 == 0b0001 表示有此功能。 + +HWCAP_SM3 + ID_AA64ISAR0_EL1.SM3 == 0b0001 表示有此功能。 + +HWCAP_SM4 + ID_AA64ISAR0_EL1.SM4 == 0b0001 表示有此功能。 + +HWCAP_ASIMDDP + ID_AA64ISAR0_EL1.DP == 0b0001 表示有此功能。 + +HWCAP_SHA512 + ID_AA64ISAR0_EL1.SHA2 == 0b0010 表示有此功能。 + +HWCAP_SVE + ID_AA64PFR0_EL1.SVE == 0b0001 表示有此功能。 + +HWCAP_ASIMDFHM + ID_AA64ISAR0_EL1.FHM == 0b0001 表示有此功能。 + +HWCAP_DIT + ID_AA64PFR0_EL1.DIT == 0b0001 表示有此功能。 + +HWCAP_USCAT + ID_AA64MMFR2_EL1.AT == 0b0001 表示有此功能。 + +HWCAP_ILRCPC + ID_AA64ISAR1_EL1.LRCPC == 0b0010 表示有此功能。 + +HWCAP_FLAGM + ID_AA64ISAR0_EL1.TS == 0b0001 表示有此功能。 + +HWCAP_SSBS + ID_AA64PFR1_EL1.SSBS == 0b0010 表示有此功能。 + +HWCAP_SB + ID_AA64ISAR1_EL1.SB == 0b0001 表示有此功能。 + +HWCAP_PACA + 如 Documentation/arm64/pointer-authentication.rst 所描述， + ID_AA64ISAR1_EL1.APA == 0b0001 或 ID_AA64ISAR1_EL1.API == 0b0001 + 表示有此功能。 + +HWCAP_PACG + 如 Documentation/arm64/pointer-authentication.rst 所描述， + ID_AA64ISAR1_EL1.GPA == 0b0001 或 ID_AA64ISAR1_EL1.GPI == 0b0001 + 表示有此功能。 + +HWCAP2_DCPODP + + ID_AA64ISAR1_EL1.DPB == 0b0010 表示有此功能。 + +HWCAP2_SVE2 + + ID_AA64ZFR0_EL1.SVEVer == 0b0001 表示有此功能。 + +HWCAP2_SVEAES + + ID_AA64ZFR0_EL1.AES == 0b0001 表示有此功能。 + +HWCAP2_SVEPMULL + + ID_AA64ZFR0_EL1.AES == 0b0010 表示有此功能。 + +HWCAP2_SVEBITPERM + + ID_AA64ZFR0_EL1.BitPerm == 0b0001 表示有此功能。 + +HWCAP2_SVESHA3 + + ID_AA64ZFR0_EL1.SHA3 == 0b0001 表示有此功能。 + +HWCAP2_SVESM4 + + ID_AA64ZFR0_EL1.SM4 == 0b0001 表示有此功能。 + +HWCAP2_FLAGM2 + + ID_AA64ISAR0_EL1.TS == 0b0010 表示有此功能。 + +HWCAP2_FRINT + + ID_AA64ISAR1_EL1.FRINTTS == 0b0001 表示有此功能。 + +HWCAP2_SVEI8MM + + ID_AA64ZFR0_EL1.I8MM == 0b0001 表示有此功能。 + +HWCAP2_SVEF32MM + + ID_AA64ZFR0_EL1.F32MM == 0b0001 表示有此功能。 + +HWCAP2_SVEF64MM + + ID_AA64ZFR0_EL1.F64MM == 0b0001 表示有此功能。 + +HWCAP2_SVEBF16 + + ID_AA64ZFR0_EL1.BF16 == 0b0001 表示有此功能。 + +HWCAP2_I8MM + + ID_AA64ISAR1_EL1.I8MM == 0b0001 表示有此功能。 + +HWCAP2_BF16 + + ID_AA64ISAR1_EL1.BF16 == 0b0001 表示有此功能。 + +HWCAP2_DGH + + ID_AA64ISAR1_EL1.DGH == 0b0001 表示有此功能。 + +HWCAP2_RNG + + ID_AA64ISAR0_EL1.RNDR == 0b0001 表示有此功能。 + +HWCAP2_BTI + + ID_AA64PFR0_EL1.BT == 0b0001 表示有此功能。 + + +4. 未使用的 AT_HWCAP 位 +----------------------- + +爲了與用戶空間交互，內核保證 AT_HWCAP 的第62、63位將始終返回0。 + diff --git a/Documentation/translations/zh_TW/arm64/hugetlbpage.rst b/Documentation/translations/zh_TW/arm64/hugetlbpage.rst new file mode 100644 index 000000000000..846b500dae97 --- /dev/null +++ b/Documentation/translations/zh_TW/arm64/hugetlbpage.rst @@ -0,0 +1,49 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. include:: ../disclaimer-zh_TW.rst + +:Original: :ref:`Documentation/arm64/hugetlbpage.rst ` + +Translator: Bailu Lin + Hu Haowen + +===================== +ARM64中的 HugeTLBpage +===================== + +大頁依靠有效利用 TLBs 來提高地址翻譯的性能。這取決於以下 +兩點 - + + - 大頁的大小 + - TLBs 支持的條目大小 + +ARM64 接口支持2種大頁方式。 + +1) pud/pmd 級別的塊映射 +----------------------- + +這是常規大頁，他們的 pmd 或 pud 頁面表條目指向一個內存塊。 +不管 TLB 中支持的條目大小如何，塊映射可以減少翻譯大頁地址 +所需遍歷的頁表深度。 + +2) 使用連續位 +------------- + +架構中轉換頁表條目(D4.5.3, ARM DDI 0487C.a)中提供一個連續 +位告訴 MMU 這個條目是一個連續條目集的一員，它可以被緩存在單 +個 TLB 條目中。 + +在 Linux 中連續位用來增加 pmd 和 pte(最後一級)級別映射的大 +小。受支持的連續頁表條目數量因頁面大小和頁表級別而異。 + + +支持以下大頁尺寸配置 - + + ====== ======== ==== ======== === + - CONT PTE PMD CONT PMD PUD + ====== ======== ==== ======== === + 4K: 64K 2M 32M 1G + 16K: 2M 32M 1G + 64K: 2M 512M 16G + ====== ======== ==== ======== === + diff --git a/Documentation/translations/zh_TW/arm64/index.rst b/Documentation/translations/zh_TW/arm64/index.rst new file mode 100644 index 000000000000..2322783f3881 --- /dev/null +++ b/Documentation/translations/zh_TW/arm64/index.rst @@ -0,0 +1,23 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. include:: ../disclaimer-zh_TW.rst + +:Original: :ref:`Documentation/arm64/index.rst ` +:Translator: Bailu Lin + Hu Haowen + +.. _tw_arm64_index: + + +========== +ARM64 架構 +========== + +.. toctree:: + :maxdepth: 2 + + amu + hugetlbpage + perf + elf_hwcaps + diff --git a/Documentation/translations/zh_TW/arm64/legacy_instructions.txt b/Documentation/translations/zh_TW/arm64/legacy_instructions.txt new file mode 100644 index 000000000000..6d4454f77b9e --- /dev/null +++ b/Documentation/translations/zh_TW/arm64/legacy_instructions.txt @@ -0,0 +1,77 @@ +SPDX-License-Identifier: GPL-2.0 + +Chinese translated version of Documentation/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 +communicating in English you can also ask the Chinese maintainer for +help. Contact the Chinese maintainer if this translation is outdated +or if there is a problem with the translation. + +Maintainer: Punit Agrawal + Suzuki K. Poulose +Chinese maintainer: Fu Wei +Traditional Chinese maintainer: Hu Haowen +--------------------------------------------------------------------- +Documentation/arm64/legacy_instructions.rst 的中文翻譯 + +如果想評論或更新本文的內容，請直接聯繫原文檔的維護者。如果你使用英文 +交流有困難的話，也可以向中文版維護者求助。如果本翻譯更新不及時或者翻 +譯存在問題，請聯繫中文版維護者。 + +本文翻譯提交時的 Git 檢出點爲： bc465aa9d045feb0e13b4a8f32cc33c1943f62d6 + +英文版維護者： Punit Agrawal + Suzuki K. Poulose +中文版維護者： 傅煒 Fu Wei +中文版翻譯者： 傅煒 Fu Wei +中文版校譯者： 傅煒 Fu Wei +繁體中文版校譯者：胡皓文 Hu Haowen + +以下爲正文 +--------------------------------------------------------------------- +Linux 內核在 arm64 上的移植提供了一個基礎框架，以支持構架中正在被淘汰或已廢棄指令的模擬執行。 +這個基礎框架的代碼使用未定義指令鉤子（hooks）來支持模擬。如果指令存在，它也允許在硬體中啓用該指令。 + +模擬模式可通過寫 sysctl 節點（/proc/sys/abi）來控制。 +不同的執行方式及 sysctl 節點的相應值，解釋如下： + +* Undef（未定義） + 值： 0 + 產生未定義指令終止異常。它是那些構架中已廢棄的指令，如 SWP，的默認處理方式。 + +* Emulate（模擬） + 值： 1 + 使用軟體模擬方式。爲解決軟體遷移問題，這種模擬指令模式的使用是被跟蹤的，並會發出速率限制警告。 + 它是那些構架中正在被淘汰的指令，如 CP15 barriers（隔離指令），的默認處理方式。 + +* Hardware Execution（硬體執行） + 值： 2 + 雖然標記爲正在被淘汰，但一些實現可能提供硬體執行這些指令的使能/禁用操作。 + 使用硬體執行一般會有更好的性能，但將無法收集運行時對正被淘汰指令的使用統計數據。 + +默認執行模式依賴於指令在構架中狀態。正在被淘汰的指令應該以模擬（Emulate）作爲默認模式， +而已廢棄的指令必須默認使用未定義（Undef）模式 + +注意：指令模擬可能無法應對所有情況。更多詳情請參考單獨的指令注釋。 + +受支持的遺留指令 +------------- +* SWP{B} +節點: /proc/sys/abi/swp +狀態: 已廢棄 +默認執行方式: Undef (0) + +* CP15 Barriers +節點: /proc/sys/abi/cp15_barrier +狀態: 正被淘汰，不推薦使用 +默認執行方式: Emulate (1) + +* SETEND +節點: /proc/sys/abi/setend +狀態: 正被淘汰，不推薦使用 +默認執行方式: Emulate (1)* +註：爲了使能這個特性，系統中的所有 CPU 必須在 EL0 支持混合字節序。 +如果一個新的 CPU （不支持混合字節序） 在使能這個特性後被熱插入系統， +在應用中可能會出現不可預期的結果。 + diff --git a/Documentation/translations/zh_TW/arm64/memory.txt b/Documentation/translations/zh_TW/arm64/memory.txt new file mode 100644 index 000000000000..99c2b78b5674 --- /dev/null +++ b/Documentation/translations/zh_TW/arm64/memory.txt @@ -0,0 +1,119 @@ +SPDX-License-Identifier: GPL-2.0 + +Chinese translated version of Documentation/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 +communicating in English you can also ask the Chinese maintainer for +help. Contact the Chinese maintainer if this translation is outdated +or if there is a problem with the translation. + +Maintainer: Catalin Marinas +Chinese maintainer: Fu Wei +Traditional Chinese maintainer: Hu Haowen +--------------------------------------------------------------------- +Documentation/arm64/memory.rst 的中文翻譯 + +如果想評論或更新本文的內容，請直接聯繫原文檔的維護者。如果你使用英文 +交流有困難的話，也可以向中文版維護者求助。如果本翻譯更新不及時或者翻 +譯存在問題，請聯繫中文版維護者。 + +本文翻譯提交時的 Git 檢出點爲： bc465aa9d045feb0e13b4a8f32cc33c1943f62d6 + +英文版維護者： Catalin Marinas +中文版維護者： 傅煒 Fu Wei +中文版翻譯者： 傅煒 Fu Wei +中文版校譯者： 傅煒 Fu Wei +繁體中文版校譯者： 胡皓文 Hu Haowen + +以下爲正文 +--------------------------------------------------------------------- + Linux 在 AArch64 中的內存布局 + =========================== + +作者: Catalin Marinas + +本文檔描述 AArch64 Linux 內核所使用的虛擬內存布局。此構架可以實現 +頁大小爲 4KB 的 4 級轉換表和頁大小爲 64KB 的 3 級轉換表。 + +AArch64 Linux 使用 3 級或 4 級轉換表，其頁大小配置爲 4KB，對於用戶和內核 +分別都有 39-bit (512GB) 或 48-bit (256TB) 的虛擬地址空間。 +對於頁大小爲 64KB的配置，僅使用 2 級轉換表，有 42-bit (4TB) 的虛擬地址空間，但內存布局相同。 + +用戶地址空間的 63:48 位爲 0，而內核地址空間的相應位爲 1。TTBRx 的 +選擇由虛擬地址的 63 位給出。swapper_pg_dir 僅包含內核（全局）映射， +而用戶 pgd 僅包含用戶（非全局）映射。swapper_pg_dir 地址被寫入 +TTBR1 中，且從不寫入 TTBR0。 + + +AArch64 Linux 在頁大小爲 4KB，並使用 3 級轉換表時的內存布局： + +起始地址 結束地址 大小 用途 +----------------------------------------------------------------------- +0000000000000000 0000007fffffffff 512GB 用戶空間 +ffffff8000000000 ffffffffffffffff 512GB 內核空間 + + +AArch64 Linux 在頁大小爲 4KB，並使用 4 級轉換表時的內存布局： + +起始地址 結束地址 大小 用途 +----------------------------------------------------------------------- +0000000000000000 0000ffffffffffff 256TB 用戶空間 +ffff000000000000 ffffffffffffffff 256TB 內核空間 + + +AArch64 Linux 在頁大小爲 64KB，並使用 2 級轉換表時的內存布局： + +起始地址 結束地址 大小 用途 +----------------------------------------------------------------------- +0000000000000000 000003ffffffffff 4TB 用戶空間 +fffffc0000000000 ffffffffffffffff 4TB 內核空間 + + +AArch64 Linux 在頁大小爲 64KB，並使用 3 級轉換表時的內存布局： + +起始地址 結束地址 大小 用途 +----------------------------------------------------------------------- +0000000000000000 0000ffffffffffff 256TB 用戶空間 +ffff000000000000 ffffffffffffffff 256TB 內核空間 + + +更詳細的內核虛擬內存布局，請參閱內核啓動信息。 + + +4KB 頁大小的轉換表查找： + ++--------+--------+--------+--------+--------+--------+--------+--------+ +|63 56|55 48|47 40|39 32|31 24|23 16|15 8|7 0| ++--------+--------+--------+--------+--------+--------+--------+--------+ + | | | | | | + | | | | | v + | | | | | [11:0] 頁內偏移 + | | | | +-> [20:12] L3 索引 + | | | +-----------> [29:21] L2 索引 + | | +---------------------> [38:30] L1 索引 + | +-------------------------------> [47:39] L0 索引 + +-------------------------------------------------> [63] TTBR0/1 + + +64KB 頁大小的轉換表查找： + ++--------+--------+--------+--------+--------+--------+--------+--------+ +|63 56|55 48|47 40|39 32|31 24|23 16|15 8|7 0| ++--------+--------+--------+--------+--------+--------+--------+--------+ + | | | | | + | | | | v + | | | | [15:0] 頁內偏移 + | | | +----------> [28:16] L3 索引 + | | +--------------------------> [41:29] L2 索引 + | +-------------------------------> [47:42] L1 索引 + +-------------------------------------------------> [63] TTBR0/1 + + +當使用 KVM 時, 管理程序（hypervisor）在 EL2 中通過相對內核虛擬地址的 +一個固定偏移來映射內核頁（內核虛擬地址的高 24 位設爲零）: + +起始地址 結束地址 大小 用途 +----------------------------------------------------------------------- +0000004000000000 0000007fffffffff 256GB 在 HYP 中映射的內核對象 + diff --git a/Documentation/translations/zh_TW/arm64/perf.rst b/Documentation/translations/zh_TW/arm64/perf.rst new file mode 100644 index 000000000000..f1ffd55dfe50 --- /dev/null +++ b/Documentation/translations/zh_TW/arm64/perf.rst @@ -0,0 +1,88 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. include:: ../disclaimer-zh_TW.rst + +:Original: :ref:`Documentation/arm64/perf.rst ` + +Translator: Bailu Lin + Hu Haowen + +============= +Perf 事件屬性 +============= + +:作者: Andrew Murray +:日期: 2019-03-06 + +exclude_user +------------ + +該屬性排除用戶空間。 + +用戶空間始終運行在 EL0，因此該屬性將排除 EL0。 + + +exclude_kernel +-------------- + +該屬性排除內核空間。 + +打開 VHE 時內核運行在 EL2，不打開 VHE 時內核運行在 EL1。客戶機 +內核總是運行在 EL1。 + +對於宿主機，該屬性排除 EL1 和 VHE 上的 EL2。 + +對於客戶機，該屬性排除 EL1。請注意客戶機從來不會運行在 EL2。 + + +exclude_hv +---------- + +該屬性排除虛擬機監控器。 + +對於 VHE 宿主機該屬性將被忽略，此時我們認爲宿主機內核是虛擬機監 +控器。 + +對於 non-VHE 宿主機該屬性將排除 EL2，因爲虛擬機監控器運行在 EL2 +的任何代碼主要用於客戶機和宿主機的切換。 + +對於客戶機該屬性無效。請注意客戶機從來不會運行在 EL2。 + + +exclude_host / exclude_guest +---------------------------- + +這些屬性分別排除了 KVM 宿主機和客戶機。 + +KVM 宿主機可能運行在 EL0（用戶空間），EL1（non-VHE 內核）和 +EL2（VHE 內核 或 non-VHE 虛擬機監控器）。 + +KVM 客戶機可能運行在 EL0（用戶空間）和 EL1（內核）。 + +由於宿主機和客戶機之間重疊的異常級別，我們不能僅僅依靠 PMU 的硬體異 +常過濾機制-因此我們必須啓用/禁用對於客戶機進入和退出的計數。而這在 +VHE 和 non-VHE 系統上表現不同。 + +對於 non-VHE 系統的 exclude_host 屬性排除 EL2 - 在進入和退出客戶 +機時，我們會根據 exclude_host 和 exclude_guest 屬性在適當的情況下 +禁用/啓用該事件。 + +對於 VHE 系統的 exclude_guest 屬性排除 EL1，而對其中的 exclude_host +屬性同時排除 EL0，EL2。在進入和退出客戶機時，我們會適當地根據 +exclude_host 和 exclude_guest 屬性包括/排除 EL0。 + +以上聲明也適用於在 not-VHE 客戶機使用這些屬性時，但是請注意客戶機從 +來不會運行在 EL2。 + + +準確性 +------ + +在 non-VHE 宿主機上，我們在 EL2 進入/退出宿主機/客戶機的切換時啓用/ +關閉計數器 -但是在啓用/禁用計數器和進入/退出客戶機之間存在一段延時。 +對於 exclude_host， 我們可以通過過濾 EL2 消除在客戶機進入/退出邊界 +上用於計數客戶機事件的宿主機事件計數器。但是當使用 !exclude_hv 時， +在客戶機進入/退出有一個小的停電窗口無法捕獲到宿主機的事件。 + +在 VHE 系統沒有停電窗口。 + diff --git a/Documentation/translations/zh_TW/arm64/silicon-errata.txt b/Documentation/translations/zh_TW/arm64/silicon-errata.txt new file mode 100644 index 000000000000..bf2077197504 --- /dev/null +++ b/Documentation/translations/zh_TW/arm64/silicon-errata.txt @@ -0,0 +1,79 @@ +SPDX-License-Identifier: GPL-2.0 + +Chinese translated version of Documentation/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 +communicating in English you can also ask the Chinese maintainer for +help. Contact the Chinese maintainer if this translation is outdated +or if there is a problem with the translation. + +M: Will Deacon +zh_CN: Fu Wei +zh_TW: Hu Haowen +C: 1926e54f115725a9248d0c4c65c22acaf94de4c4 +--------------------------------------------------------------------- +Documentation/arm64/silicon-errata.rst 的中文翻譯 + +如果想評論或更新本文的內容，請直接聯繫原文檔的維護者。如果你使用英文 +交流有困難的話，也可以向中文版維護者求助。如果本翻譯更新不及時或者翻 +譯存在問題，請聯繫中文版維護者。 + +英文版維護者： Will Deacon +中文版維護者： 傅煒 Fu Wei +中文版翻譯者： 傅煒 Fu Wei +中文版校譯者： 傅煒 Fu Wei +繁體中文版校譯者： 胡皓文 Hu Haowen +本文翻譯提交時的 Git 檢出點爲： 1926e54f115725a9248d0c4c65c22acaf94de4c4 + +以下爲正文 +--------------------------------------------------------------------- + 晶片勘誤和軟體補救措施 + ================== + +作者: Will Deacon +日期: 2015年11月27日 + +一個不幸的現實：硬體經常帶有一些所謂的「瑕疵（errata）」，導致其在 +某些特定情況下會違背構架定義的行爲。就基於 ARM 的硬體而言，這些瑕疵 +大體可分爲以下幾類： + + A 類：無可行補救措施的嚴重缺陷。 + B 類：有可接受的補救措施的重大或嚴重缺陷。 + C 類：在正常操作中不會顯現的小瑕疵。 + +更多資訊，請在 infocenter.arm.com （需註冊）中查閱「軟體開發者勘誤 +筆記」（「Software Developers Errata Notice」）文檔。 + +對於 Linux 而言，B 類缺陷可能需要作業系統的某些特別處理。例如，避免 +一個特殊的代碼序列，或是以一種特定的方式配置處理器。在某種不太常見的 +情況下，爲將 A 類缺陷當作 C 類處理，可能需要用類似的手段。這些手段被 +統稱爲「軟體補救措施」，且僅在少數情況需要（例如，那些需要一個運行在 +非安全異常級的補救措施 *並且* 能被 Linux 觸發的情況）。 + +對於尚在討論中的可能對未受瑕疵影響的系統產生干擾的軟體補救措施，有一個 +相應的內核配置（Kconfig）選項被加在 「內核特性（Kernel Features）」-> +「基於可選方法框架的 ARM 瑕疵補救措施（ARM errata workarounds via +the alternatives framework）"。這些選項被默認開啓，若探測到受影響的CPU， +補丁將在運行時被使用。至於對系統運行影響較小的補救措施，內核配置選項 +並不存在，且代碼以某種規避瑕疵的方式被構造（帶注釋爲宜）。 + +這種做法對於在任意內核原始碼樹中準確地判斷出哪個瑕疵已被軟體方法所補救 +稍微有點麻煩，所以在 Linux 內核中此文件作爲軟體補救措施的註冊表， +並將在新的軟體補救措施被提交和向後移植（backported）到穩定內核時被更新。 + +| 實現者 | 受影響的組件 | 勘誤編號 | 內核配置 | ++----------------+-----------------+-----------------+-------------------------+ +| ARM | Cortex-A53 | #826319 | ARM64_ERRATUM_826319 | +| ARM | Cortex-A53 | #827319 | ARM64_ERRATUM_827319 | +| ARM | Cortex-A53 | #824069 | ARM64_ERRATUM_824069 | +| ARM | Cortex-A53 | #819472 | ARM64_ERRATUM_819472 | +| ARM | Cortex-A53 | #845719 | ARM64_ERRATUM_845719 | +| ARM | Cortex-A53 | #843419 | ARM64_ERRATUM_843419 | +| ARM | Cortex-A57 | #832075 | ARM64_ERRATUM_832075 | +| ARM | Cortex-A57 | #852523 | N/A | +| ARM | Cortex-A57 | #834220 | ARM64_ERRATUM_834220 | +| | | | | +| Cavium | ThunderX ITS | #22375, #24313 | CAVIUM_ERRATUM_22375 | +| Cavium | ThunderX GICv3 | #23154 | CAVIUM_ERRATUM_23154 | + diff --git a/Documentation/translations/zh_TW/arm64/tagged-pointers.txt b/Documentation/translations/zh_TW/arm64/tagged-pointers.txt new file mode 100644 index 000000000000..87f88628401a --- /dev/null +++ b/Documentation/translations/zh_TW/arm64/tagged-pointers.txt @@ -0,0 +1,57 @@ +SPDX-License-Identifier: GPL-2.0 + +Chinese translated version of Documentation/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 +communicating in English you can also ask the Chinese maintainer for +help. Contact the Chinese maintainer if this translation is outdated +or if there is a problem with the translation. + +Maintainer: Will Deacon +Chinese maintainer: Fu Wei +Traditional Chinese maintainer: Hu Haowen +--------------------------------------------------------------------- +Documentation/arm64/tagged-pointers.rst 的中文翻譯 + +如果想評論或更新本文的內容，請直接聯繫原文檔的維護者。如果你使用英文 +交流有困難的話，也可以向中文版維護者求助。如果本翻譯更新不及時或者翻 +譯存在問題，請聯繫中文版維護者。 + +英文版維護者： Will Deacon +中文版維護者： 傅煒 Fu Wei +中文版翻譯者： 傅煒 Fu Wei +中文版校譯者： 傅煒 Fu Wei +繁體中文版校譯者： 胡皓文 Hu Haowen + +以下爲正文 +--------------------------------------------------------------------- + Linux 在 AArch64 中帶標記的虛擬地址 + ================================= + +作者: Will Deacon +日期: 2013 年 06 月 12 日 + +本文檔簡述了在 AArch64 地址轉換系統中提供的帶標記的虛擬地址及其在 +AArch64 Linux 中的潛在用途。 + +內核提供的地址轉換表配置使通過 TTBR0 完成的虛擬地址轉換（即用戶空間 +映射），其虛擬地址的最高 8 位（63:56）會被轉換硬體所忽略。這種機制 +讓這些位可供應用程式自由使用，其注意事項如下： + + (1) 內核要求所有傳遞到 EL1 的用戶空間地址帶有 0x00 標記。 + 這意味著任何攜帶用戶空間虛擬地址的系統調用（syscall） + 參數 *必須* 在陷入內核前使它們的最高字節被清零。 + + (2) 非零標記在傳遞信號時不被保存。這意味著在應用程式中利用了 + 標記的信號處理函數無法依賴 siginfo_t 的用戶空間虛擬 + 地址所攜帶的包含其內部域信息的標記。此規則的一個例外是 + 當信號是在調試觀察點的異常處理程序中產生的，此時標記的 + 信息將被保存。 + + (3) 當使用帶標記的指針時需特別留心，因爲僅對兩個虛擬地址 + 的高字節，C 編譯器很可能無法判斷它們是不同的。 + +此構架會阻止對帶標記的 PC 指針的利用，因此在異常返回時，其高字節 +將被設置成一個爲 「55」 的擴展符。 + diff --git a/Documentation/translations/zh_TW/cpu-freq/core.rst b/Documentation/translations/zh_TW/cpu-freq/core.rst new file mode 100644 index 000000000000..3d890c2f2a61 --- /dev/null +++ b/Documentation/translations/zh_TW/cpu-freq/core.rst @@ -0,0 +1,108 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. include:: ../disclaimer-zh_TW.rst + +:Original: :doc:`../../../cpu-freq/core` +:Translator: Yanteng Si + Hu Haowen + +.. _tw_core.rst: + + +==================================== +CPUFreq核心和CPUFreq通知器的通用說明 +==================================== + +作者: + - Dominik Brodowski + - David Kimdon + - Rafael J. Wysocki + - Viresh Kumar + +.. 目錄: + + 1. CPUFreq核心和接口 + 2. CPUFreq通知器 + 3. 含有Operating Performance Point (OPP)的CPUFreq表的生成 + +1. CPUFreq核心和接口 +====================== + +cpufreq核心代碼位於drivers/cpufreq/cpufreq.c中。這些cpufreq代碼爲CPUFreq架構的驅 +動程序（那些操作硬體切換頻率的代碼）以及 "通知器 "提供了一個標準化的接口。 +這些是設備驅動程序或需要了解策略變化的其它內核部分（如 ACPI 熱量管理）或所有頻率更改（除 +計時代碼外），甚至需要強制確定速度限制的通知器（如 ARM 架構上的 LCD 驅動程序）。 +此外， 內核 "常數" loops_per_jiffy會根據頻率變化而更新。 + +cpufreq策略的引用計數由 cpufreq_cpu_get 和 cpufreq_cpu_put 來完成，以確保 cpufreq 驅 +動程序被正確地註冊到核心中，並且驅動程序在 cpufreq_put_cpu 被調用之前不會被卸載。這也保證 +了每個CPU核的cpufreq 策略在使用期間不會被釋放。 + +2. CPUFreq 通知器 +==================== + +CPUFreq通知器符合標準的內核通知器接口。 +關於通知器的細節請參閱 linux/include/linux/notifier.h。 + +這裡有兩個不同的CPUfreq通知器 - 策略通知器和轉換通知器。 + + +2.1 CPUFreq策略通知器 +---------------------------- + +當創建或移除策略時，這些都會被通知。 + +階段是在通知器的第二個參數中指定的。當第一次創建策略時，階段是CPUFREQ_CREATE_POLICY，當 +策略被移除時，階段是CPUFREQ_REMOVE_POLICY。 + +第三個參數 ``void *pointer`` 指向一個結構體cpufreq_policy，其包括min，max(新策略的下限和 +上限（單位爲kHz）)這幾個值。 + + +2.2 CPUFreq轉換通知器 +-------------------------------- + +當CPUfreq驅動切換CPU核心頻率時，策略中的每個在線CPU都會收到兩次通知，這些變化沒有任何外部干 +預。 + +第二個參數指定階段 - CPUFREQ_PRECHANGE or CPUFREQ_POSTCHANGE. + +第三個參數是一個包含如下值的結構體cpufreq_freqs： + +===== ==================== +cpu 受影響cpu的編號 +old 舊頻率 +new 新頻率 +flags cpufreq驅動的標誌 +===== ==================== + +3. 含有Operating Performance Point (OPP)的CPUFreq表的生成 +================================================================== +關於OPP的細節請參閱 Documentation/power/opp.rst + +dev_pm_opp_init_cpufreq_table - + 這個功能提供了一個隨時可用的轉換程序，用來將OPP層關於可用頻率的內部信息翻譯成一種容易提供給 + cpufreq的格式。 + + .. Warning:: + + 不要在中斷上下文中使用此函數。 + + 例如:: + + soc_pm_init() + { + /* Do things */ + r = dev_pm_opp_init_cpufreq_table(dev, &freq_table); + if (!r) + policy->freq_table = freq_table; + /* Do other things */ + } + + .. note:: + + 該函數只有在CONFIG_PM_OPP之外還啓用了CONFIG_CPU_FREQ時才可用。 + +dev_pm_opp_free_cpufreq_table + 釋放dev_pm_opp_init_cpufreq_table分配的表。 + diff --git a/Documentation/translations/zh_TW/cpu-freq/cpu-drivers.rst b/Documentation/translations/zh_TW/cpu-freq/cpu-drivers.rst new file mode 100644 index 000000000000..2bb8197cd320 --- /dev/null +++ b/Documentation/translations/zh_TW/cpu-freq/cpu-drivers.rst @@ -0,0 +1,256 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. include:: ../disclaimer-zh_TW.rst + +:Original: :doc:`../../../cpu-freq/cpu-drivers` +:Translator: Yanteng Si + Hu Haowen + +.. _tw_cpu-drivers.rst: + + +======================================= +如何實現一個新的CPUFreq處理器驅動程序？ +======================================= + +作者: + + + - Dominik Brodowski + - Rafael J. Wysocki + - Viresh Kumar + +.. Contents + + 1. 怎麼做？ + 1.1 初始化 + 1.2 Per-CPU 初始化 + 1.3 驗證 + 1.4 target/target_index 或 setpolicy? + 1.5 target/target_index + 1.6 setpolicy + 1.7 get_intermediate 與 target_intermediate + 2. 頻率表助手 + + + +1. 怎麼做？ +=========== + +如此，你剛剛得到了一個全新的CPU/晶片組及其數據手冊，並希望爲這個CPU/晶片組添加cpufreq +支持？很好，這裡有一些至關重要的提示： + + +1.1 初始化 +---------- + +首先，在__initcall_level_7 (module_init())或更靠後的函數中檢查這個內核是否 +運行在正確的CPU和正確的晶片組上。如果是，則使用cpufreq_register_driver()向 +CPUfreq核心層註冊一個cpufreq_driver結構體。 + +結構體cpufreq_driver應該包含什麼成員? + + .name - 驅動的名字。 + + .init - 一個指向per-policy初始化函數的指針。 + + .verify - 一個指向"verification"函數的指針。 + + .setpolicy 或 .fast_switch 或 .target 或 .target_index - 差異見 + 下文。 + +並且可選擇 + + .flags - cpufreq核的提示。 + + .driver_data - cpufreq驅動程序的特定數據。 + + .get_intermediate 和 target_intermediate - 用於在改變CPU頻率時切換到穩定 + 的頻率。 + + .get - 返回CPU的當前頻率。 + + .bios_limit - 返回HW/BIOS對CPU的最大頻率限制值。 + + .exit - 一個指向per-policy清理函數的指針，該函數在cpu熱插拔過程的CPU_POST_DEAD + 階段被調用。 + + .suspend - 一個指向per-policy暫停函數的指針，該函數在關中斷且在該策略的調節器停止 + 後被調用。 + + .resume - 一個指向per-policy恢復函數的指針，該函數在關中斷且在調節器再一次開始前被 + 調用。 + + .ready - 一個指向per-policy準備函數的指針，該函數在策略完全初始化之後被調用。 + + .attr - 一個指向NULL結尾的"struct freq_attr"列表的指針，該函數允許導出值到 + sysfs。 + + .boost_enabled - 如果設置，則啓用提升(boost)頻率。 + + .set_boost - 一個指向per-policy函數的指針，該函數用來開啓/關閉提升(boost)頻率功能。 + + +1.2 Per-CPU 初始化 +------------------ + +每當一個新的CPU被註冊到設備模型中，或者在cpufreq驅動註冊自己之後，如果此CPU的cpufreq策 +略不存在，則會調用per-policy的初始化函數cpufreq_driver.init。請注意，.init()和.exit()程序 +只對策略調用一次，而不是對策略管理的每個CPU調用一次。它需要一個 ``struct cpufreq_policy +*policy`` 作爲參數。現在該怎麼做呢？ + +如果有必要，請在你的CPU上激活CPUfreq功能支持。 + +然後，驅動程序必須填寫以下數值: + ++-----------------------------------+--------------------------------------+ +|policy->cpuinfo.min_freq 和 | | +|policy->cpuinfo.max_freq | 該CPU支持的最低和最高頻率（kHz） | +| | | +| | | ++-----------------------------------+--------------------------------------+ +|policy->cpuinfo.transition_latency | | +| | CPU在兩個頻率之間切換所需的時間，以 | +| | 納秒爲單位（如適用，否則指定 | +| | CPUFREQ_ETERNAL） | ++-----------------------------------+--------------------------------------+ +|policy->cur | 該CPU當前的工作頻率(如適用) | +| | | ++-----------------------------------+--------------------------------------+ +|policy->min, | | +|policy->max, | | +|policy->policy and, if necessary, | | +|policy->governor | 必須包含該cpu的 「默認策略」。稍後 | +| | 會用這些值調用 | +| | cpufreq_driver.verify and either | +| | cpufreq_driver.setpolicy or | +| | cpufreq_driver.target/target_index | +| | | ++-----------------------------------+--------------------------------------+ +|policy->cpus | 用與這個CPU一起做DVFS的(在線+離線) | +| | CPU(即與它共享時鐘/電壓軌)的掩碼更新 | +| | 這個 | +| | | ++-----------------------------------+--------------------------------------+ + +對於設置其中的一些值(cpuinfo.min[max]_freq, policy->min[max])，頻率表助手可能會有幫 +助。關於它們的更多信息，請參見第2節。 + + +1.3 驗證 +-------- + +當用戶決定設置一個新的策略(由 「policy,governor,min,max組成」)時，必須對這個策略進行驗證， +以便糾正不兼容的值。爲了驗證這些值，cpufreq_verify_within_limits(``struct cpufreq_policy +*policy``, ``unsigned int min_freq``, ``unsigned int max_freq``)函數可能會有幫助。 +關於頻率表助手的詳細內容請參見第2節。 + +您需要確保至少有一個有效頻率（或工作範圍）在 policy->min 和 policy->max 範圍內。如果有必 +要，先增加policy->max，只有在沒有辦法的情況下，才減少policy->min。 + + +1.4 target 或 target_index 或 setpolicy 或 fast_switch? +------------------------------------------------------- + +大多數cpufreq驅動甚至大多數cpu頻率升降算法只允許將CPU頻率設置爲預定義的固定值。對於這些，你 +可以使用->target()，->target_index()或->fast_switch()回調。 + +有些cpufreq功能的處理器可以自己在某些限制之間切換頻率。這些應使用->setpolicy()回調。 + + +1.5. target/target_index +------------------------ + +target_index調用有兩個參數：``struct cpufreq_policy * policy``和``unsigned int`` +索引(於列出的頻率表)。 + +當調用這裡時，CPUfreq驅動必須設置新的頻率。實際頻率必須由freq_table[index].frequency決定。 + +它應該總是在錯誤的情況下恢復到之前的頻率(即policy->restore_freq)，即使我們之前切換到中間頻率。 + +已棄用 +---------- +目標調用有三個參數。``struct cpufreq_policy * policy``, unsigned int target_frequency, +unsigned int relation. + +CPUfreq驅動在調用這裡時必須設置新的頻率。實際的頻率必須使用以下規則來確定。 + +- 緊跟 "目標頻率"。 +- policy->min <= new_freq <= policy->max (這必須是有效的!!!) +- 如果 relation==CPUFREQ_REL_L，嘗試選擇一個高於或等於 target_freq 的 new_freq。("L代表 + 最低，但不能低於") +- 如果 relation==CPUFREQ_REL_H，嘗試選擇一個低於或等於 target_freq 的 new_freq。("H代表 + 最高，但不能高於") + +這裡，頻率表助手可能會幫助你--詳見第2節。 + +1.6. fast_switch +---------------- + +這個函數用於從調度器的上下文進行頻率切換。並非所有的驅動都要實現它，因爲不允許在這個回調中睡眠。這 +個回調必須經過高度優化，以儘可能快地進行切換。 + +這個函數有兩個參數： ``struct cpufreq_policy *policy`` 和 ``unsigned int target_frequency``。 + + +1.7 setpolicy +------------- + +setpolicy調用只需要一個``struct cpufreq_policy * policy``作爲參數。需要將處理器內或晶片組內動態頻 +率切換的下限設置爲policy->min，上限設置爲policy->max，如果支持的話，當policy->policy爲 +CPUFREQ_POLICY_PERFORMANCE時選擇面向性能的設置，當CPUFREQ_POLICY_POWERSAVE時選擇面向省電的設置。 +也可以查看drivers/cpufreq/longrun.c中的參考實現。 + +1.8 get_intermediate 和 target_intermediate +-------------------------------------------- + +僅適用於 target_index() 和 CPUFREQ_ASYNC_NOTIFICATION 未設置的驅動。 + +get_intermediate應該返回一個平台想要切換到的穩定的中間頻率，target_intermediate()應該將CPU設置爲 +該頻率，然後再跳轉到'index'對應的頻率。核心會負責發送通知，驅動不必在target_intermediate()或 +target_index()中處理。 + +在驅動程序不想因爲某個目標頻率切換到中間頻率的情況下，它們可以從get_intermediate()中返回'0'。在這種情況 +下，核心將直接調用->target_index()。 + +注意：->target_index()應該在失敗的情況下恢復到policy->restore_freq，因爲core會爲此發送通知。 + + +2. 頻率表助手 +============= + +由於大多數cpufreq處理器只允許被設置爲幾個特定的頻率，因此，一個帶有一些函數的 「頻率表」可能會輔助處理器驅動 +程序的一些工作。這樣的 "頻率表" 由一個cpufreq_frequency_table條目構成的數組組成，"driver_data" 中包 +含了驅動程序的具體數值，"frequency" 中包含了相應的頻率，並設置了標誌。在表的最後，需要添加一個 +cpufreq_frequency_table條目，頻率設置爲CPUFREQ_TABLE_END。而如果想跳過表中的一個條目，則將頻率設置爲 +CPUFREQ_ENTRY_INVALID。這些條目不需要按照任何特定的順序排序，但如果它們是cpufreq 核心會對它們進行快速的DVFS， +因爲搜索最佳匹配會更快。 + +如果策略在其policy->freq_table欄位中包含一個有效的指針，cpufreq表就會被核心自動驗證。 + +cpufreq_frequency_table_verify()保證至少有一個有效的頻率在policy->min和policy->max範圍內，並且所有其他 +標準都被滿足。這對->verify調用很有幫助。 + +cpufreq_frequency_table_target()是對應於->target階段的頻率表助手。只要把數值傳遞給這個函數，這個函數就會返 +回包含CPU要設置的頻率的頻率表條目。 + +以下宏可以作爲cpufreq_frequency_table的疊代器。 + +cpufreq_for_each_entry(pos, table) - 遍歷頻率表的所有條目。 + +cpufreq_for_each_valid_entry(pos, table) - 該函數遍歷所有條目，不包括CPUFREQ_ENTRY_INVALID頻率。 +使用參數 "pos"-一個``cpufreq_frequency_table * `` 作爲循環變量，使用參數 "table"-作爲你想疊代 +的``cpufreq_frequency_table * `` 。 + +例如:: + + struct cpufreq_frequency_table *pos, *driver_freq_table; + + cpufreq_for_each_entry(pos, driver_freq_table) { + /* Do something with pos */ + pos->frequency = ... + } + +如果你需要在driver_freq_table中處理pos的位置，不要減去指針，因爲它的代價相當高。相反，使用宏 +cpufreq_for_each_entry_idx() 和 cpufreq_for_each_valid_entry_idx() 。 + diff --git a/Documentation/translations/zh_TW/cpu-freq/cpufreq-stats.rst b/Documentation/translations/zh_TW/cpu-freq/cpufreq-stats.rst new file mode 100644 index 000000000000..d80bfed50e8c --- /dev/null +++ b/Documentation/translations/zh_TW/cpu-freq/cpufreq-stats.rst @@ -0,0 +1,132 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. include:: ../disclaimer-zh_TW.rst + +:Original: :doc:`../../../cpu-freq/cpufreq-stats` +:Translator: Yanteng Si + Hu Haowen + +.. _tw_cpufreq-stats.rst: + + +========================================== +sysfs CPUFreq Stats的一般說明 +========================================== + +用戶信息 + + +作者: Venkatesh Pallipadi + +.. Contents + + 1. 簡介 + 2. 提供的統計數據(舉例說明) + 3. 配置cpufreq-stats + + +1. 簡介 +=============== + +cpufreq-stats是一個爲每個CPU提供CPU頻率統計的驅動。 +這些統計數據在/sysfs中以一堆只讀接口的形式提供。這個接口（在配置好後）將出現在 +/sysfs（/devices/system/cpu/cpuX/cpufreq/stats/）中cpufreq下的一個單 +獨的目錄中，提供給每個CPU。 +各種統計數據將在此目錄下形成只讀文件。 + +此驅動是獨立於任何可能運行在你所用CPU上的特定cpufreq_driver而設計的。因此，它將與所有 +cpufreq_driver一起工作。 + + +2. 提供的統計數據(舉例說明) +===================================== + +cpufreq stats提供了以下統計數據（在下面詳細解釋）。 + +- time_in_state +- total_trans +- trans_table + +所有的統計數據將從統計驅動被載入的時間（或統計被重置的時間）開始，到某一統計數據被讀取的時間爲止。 +顯然，統計驅動不會有任何關於統計驅動載入之前的頻率轉換信息。 + +:: + + :/sys/devices/system/cpu/cpu0/cpufreq/stats # ls -l + total 0 + drwxr-xr-x 2 root root 0 May 14 16:06 . + drwxr-xr-x 3 root root 0 May 14 15:58 .. + --w------- 1 root root 4096 May 14 16:06 reset + -r--r--r-- 1 root root 4096 May 14 16:06 time_in_state + -r--r--r-- 1 root root 4096 May 14 16:06 total_trans + -r--r--r-- 1 root root 4096 May 14 16:06 trans_table + +- **reset** + +只寫屬性，可用於重置統計計數器。這對於評估不同調節器下的系統行爲非常有用，且無需重啓。 + + +- **time_in_state** + +此項給出了這個CPU所支持的每個頻率所花費的時間。cat輸出的每一行都會有" +