diff options
Diffstat (limited to 'Documentation')
56 files changed, 1679 insertions, 473 deletions
diff --git a/Documentation/ABI/testing/sysfs-devices-system-cpu b/Documentation/ABI/testing/sysfs-devices-system-cpu index 1a04ca8162ad..0eee30b27ab6 100644 --- a/Documentation/ABI/testing/sysfs-devices-system-cpu +++ b/Documentation/ABI/testing/sysfs-devices-system-cpu @@ -264,7 +264,8 @@ Description: Discover CPUs in the same CPU frequency coordination domain attribute is useful for user space DVFS controllers to get better power/performance results for platforms using acpi-cpufreq. - This file is only present if the acpi-cpufreq driver is in use. + This file is only present if the acpi-cpufreq or the cppc-cpufreq + drivers are in use. What: /sys/devices/system/cpu/cpu*/cache/index3/cache_disable_{0,1} diff --git a/Documentation/admin-guide/device-mapper/verity.rst b/Documentation/admin-guide/device-mapper/verity.rst index 8c50e5c96ee1..1a6b91368e59 100644 --- a/Documentation/admin-guide/device-mapper/verity.rst +++ b/Documentation/admin-guide/device-mapper/verity.rst @@ -134,7 +134,12 @@ root_hash_sig_key_desc <key_description> the pkcs7 signature of the roothash. The pkcs7 signature is used to validate the root hash during the creation of the device mapper block device. Verification of roothash depends on the config DM_VERITY_VERIFY_ROOTHASH_SIG - being set in the kernel. + being set in the kernel. The signatures are checked against the builtin + trusted keyring by default, or the secondary trusted keyring if + DM_VERITY_VERIFY_ROOTHASH_SIG_SECONDARY_KEYRING is set. The secondary + trusted keyring includes by default the builtin trusted keyring, and it can + also gain new certificates at run time if they are signed by a certificate + already in the secondary trusted keyring. Theory of operation =================== diff --git a/Documentation/admin-guide/kernel-parameters.txt b/Documentation/admin-guide/kernel-parameters.txt index d24336109c2e..c722ec19cd00 100644 --- a/Documentation/admin-guide/kernel-parameters.txt +++ b/Documentation/admin-guide/kernel-parameters.txt @@ -2254,6 +2254,16 @@ for all guests. Default is 1 (enabled) if in 64-bit or 32-bit PAE mode. + kvm-arm.mode= + [KVM,ARM] Select one of KVM/arm64's modes of operation. + + protected: nVHE-based mode with support for guests whose + state is kept private from the host. + Not valid if the kernel is running in EL2. + + Defaults to VHE/nVHE based on hardware support and + the value of CONFIG_ARM64_VHE. + kvm-arm.vgic_v3_group0_trap= [KVM,ARM] Trap guest accesses to GICv3 group-0 system registers diff --git a/Documentation/admin-guide/perf-security.rst b/Documentation/admin-guide/perf-security.rst index 1307b5274a0f..904e4eb37f99 100644 --- a/Documentation/admin-guide/perf-security.rst +++ b/Documentation/admin-guide/perf-security.rst @@ -84,11 +84,14 @@ capabilities then providing the process with CAP_PERFMON capability singly is recommended as the preferred secure approach to resolve double access denial logging related to usage of performance monitoring and observability. -Unprivileged processes using perf_events system call are also subject -for PTRACE_MODE_READ_REALCREDS ptrace access mode check [7]_ , whose -outcome determines whether monitoring is permitted. So unprivileged -processes provided with CAP_SYS_PTRACE capability are effectively -permitted to pass the check. +Prior Linux v5.9 unprivileged processes using perf_events system call +are also subject for PTRACE_MODE_READ_REALCREDS ptrace access mode check +[7]_ , whose outcome determines whether monitoring is permitted. +So unprivileged processes provided with CAP_SYS_PTRACE capability are +effectively permitted to pass the check. Starting from Linux v5.9 +CAP_SYS_PTRACE capability is not required and CAP_PERFMON is enough to +be provided for processes to make performance monitoring and observability +operations. Other capabilities being granted to unprivileged processes can effectively enable capturing of additional data required for later @@ -99,11 +102,11 @@ CAP_SYSLOG capability permits reading kernel space memory addresses from Privileged Perf users groups --------------------------------- -Mechanisms of capabilities, privileged capability-dumb files [6]_ and -file system ACLs [10]_ can be used to create dedicated groups of -privileged Perf users who are permitted to execute performance monitoring -and observability without scope limits. The following steps can be -taken to create such groups of privileged Perf users. +Mechanisms of capabilities, privileged capability-dumb files [6]_, +file system ACLs [10]_ and sudo [15]_ utility can be used to create +dedicated groups of privileged Perf users who are permitted to execute +performance monitoring and observability without limits. The following +steps can be taken to create such groups of privileged Perf users. 1. Create perf_users group of privileged Perf users, assign perf_users group to Perf tool executable and limit access to the executable for @@ -133,7 +136,7 @@ taken to create such groups of privileged Perf users. # getcap perf perf = cap_sys_ptrace,cap_syslog,cap_perfmon+ep -If the libcap installed doesn't yet support "cap_perfmon", use "38" instead, +If the libcap [16]_ installed doesn't yet support "cap_perfmon", use "38" instead, i.e.: :: @@ -159,6 +162,60 @@ performance monitoring and observability by using functionality of the configured Perf tool executable that, when executes, passes perf_events subsystem scope checks. +In case Perf tool executable can't be assigned required capabilities (e.g. +file system is mounted with nosuid option or extended attributes are +not supported by the file system) then creation of the capabilities +privileged environment, naturally shell, is possible. The shell provides +inherent processes with CAP_PERFMON and other required capabilities so that +performance monitoring and observability operations are available in the +environment without limits. Access to the environment can be open via sudo +utility for members of perf_users group only. In order to create such +environment: + +1. Create shell script that uses capsh utility [16]_ to assign CAP_PERFMON + and other required capabilities into ambient capability set of the shell + process, lock the process security bits after enabling SECBIT_NO_SETUID_FIXUP, + SECBIT_NOROOT and SECBIT_NO_CAP_AMBIENT_RAISE bits and then change + the process identity to sudo caller of the script who should essentially + be a member of perf_users group: + +:: + + # ls -alh /usr/local/bin/perf.shell + -rwxr-xr-x. 1 root root 83 Oct 13 23:57 /usr/local/bin/perf.shell + # cat /usr/local/bin/perf.shell + exec /usr/sbin/capsh --iab=^cap_perfmon --secbits=239 --user=$SUDO_USER -- -l + +2. Extend sudo policy at /etc/sudoers file with a rule for perf_users group: + +:: + + # grep perf_users /etc/sudoers + %perf_users ALL=/usr/local/bin/perf.shell + +3. Check that members of perf_users group have access to the privileged + shell and have CAP_PERFMON and other required capabilities enabled + in permitted, effective and ambient capability sets of an inherent process: + +:: + + $ id + uid=1003(capsh_test) gid=1004(capsh_test) groups=1004(capsh_test),1000(perf_users) context=unconfined_u:unconfined_r:unconfined_t:s0-s0:c0.c1023 + $ sudo perf.shell + [sudo] password for capsh_test: + $ grep Cap /proc/self/status + CapInh: 0000004000000000 + CapPrm: 0000004000000000 + CapEff: 0000004000000000 + CapBnd: 000000ffffffffff + CapAmb: 0000004000000000 + $ capsh --decode=0000004000000000 + 0x0000004000000000=cap_perfmon + +As a result, members of perf_users group have access to the privileged +environment where they can use tools employing performance monitoring APIs +governed by CAP_PERFMON Linux capability. + This specific access control management is only available to superuser or root running processes with CAP_SETPCAP, CAP_SETFCAP [6]_ capabilities. @@ -264,3 +321,5 @@ Bibliography .. [12] `<http://man7.org/linux/man-pages/man5/limits.conf.5.html>`_ .. [13] `<https://sites.google.com/site/fullycapable>`_ .. [14] `<http://man7.org/linux/man-pages/man8/auditd.8.html>`_ +.. [15] `<https://man7.org/linux/man-pages/man8/sudo.8.html>`_ +.. [16] `<https://git.kernel.org/pub/scm/libs/libcap/libcap.git/>`_ diff --git a/Documentation/arm/memory.rst b/Documentation/arm/memory.rst index 0521b4ce5c96..0cb1e2938823 100644 --- a/Documentation/arm/memory.rst +++ b/Documentation/arm/memory.rst @@ -45,9 +45,14 @@ fffe8000 fffeffff DTCM mapping area for platforms with fffe0000 fffe7fff ITCM mapping area for platforms with ITCM mounted inside the CPU. -ffc00000 ffefffff Fixmap mapping region. Addresses provided +ffc80000 ffefffff Fixmap mapping region. Addresses provided by fix_to_virt() will be located here. +ffc00000 ffc7ffff Guard region + +ff800000 ffbfffff Permanent, fixed read-only mapping of the + firmware provided DT blob + fee00000 feffffff Mapping of PCI I/O space. This is a static mapping within the vmalloc space. @@ -72,6 +77,11 @@ MODULES_VADDR MODULES_END-1 Kernel module space Kernel modules inserted via insmod are placed here using dynamic mappings. +TASK_SIZE MODULES_VADDR-1 KASAn shadow memory when KASan is in use. + The range from MODULES_VADDR to the top + of the memory is shadowed here with 1 bit + per byte of memory. + 00001000 TASK_SIZE-1 User space mappings Per-thread mappings are placed here via the mmap() system call. diff --git a/Documentation/arm64/memory.rst b/Documentation/arm64/memory.rst index e7522e5c8322..901cd094f4ec 100644 --- a/Documentation/arm64/memory.rst +++ b/Documentation/arm64/memory.rst @@ -97,7 +97,7 @@ hypervisor maps kernel pages in EL2 at a fixed (and potentially random) offset from the linear mapping. See the kern_hyp_va macro and kvm_update_va_mask function for more details. MMIO devices such as GICv2 gets mapped next to the HYP idmap page, as do vectors when -ARM64_HARDEN_EL2_VECTORS is selected for particular CPUs. +ARM64_SPECTRE_V3A is enabled for particular CPUs. When using KVM with the Virtualization Host Extensions, no additional mappings are created, since the host kernel runs directly in EL2. diff --git a/Documentation/dev-tools/kasan.rst b/Documentation/dev-tools/kasan.rst index 6b752a45a936..0fc3fb1860c4 100644 --- a/Documentation/dev-tools/kasan.rst +++ b/Documentation/dev-tools/kasan.rst @@ -4,13 +4,16 @@ The Kernel Address Sanitizer (KASAN) Overview -------- -KernelAddressSANitizer (KASAN) is a dynamic memory error detector designed to -find out-of-bound and use-after-free bugs. KASAN has two modes: generic KASAN -(similar to userspace ASan) and software tag-based KASAN (similar to userspace -HWASan). +KernelAddressSANitizer (KASAN) is a dynamic memory safety error detector +designed to find out-of-bound and use-after-free bugs. KASAN has three modes: -KASAN uses compile-time instrumentation to insert validity checks before every -memory access, and therefore requires a compiler version that supports that. +1. generic KASAN (similar to userspace ASan), +2. software tag-based KASAN (similar to userspace HWASan), +3. hardware tag-based KASAN (based on hardware memory tagging). + +Software KASAN modes (1 and 2) use compile-time instrumentation to insert +validity checks before every memory access, and therefore require a compiler +version that supports that. Generic KASAN is supported in both GCC and Clang. With GCC it requires version 8.3.0 or later. Any supported Clang version is compatible, but detection of @@ -18,8 +21,8 @@ out-of-bounds accesses for global variables is only supported since Clang 11. Tag-based KASAN is only supported in Clang. -Currently generic KASAN is supported for the x86_64, arm64, xtensa, s390 and -riscv architectures, and tag-based KASAN is supported only for arm64. +Currently generic KASAN is supported for the x86_64, arm, arm64, xtensa, s390 +and riscv architectures, and tag-based KASAN modes are supported only for arm64. Usage ----- @@ -28,30 +31,22 @@ To enable KASAN configure kernel with:: CONFIG_KASAN = y -and choose between CONFIG_KASAN_GENERIC (to enable generic KASAN) and -CONFIG_KASAN_SW_TAGS (to enable software tag-based KASAN). +and choose between CONFIG_KASAN_GENERIC (to enable generic KASAN), +CONFIG_KASAN_SW_TAGS (to enable software tag-based KASAN), and +CONFIG_KASAN_HW_TAGS (to enable hardware tag-based KASAN). + +For software modes, you also need to choose between CONFIG_KASAN_OUTLINE and +CONFIG_KASAN_INLINE. Outline and inline are compiler instrumentation types. +The former produces smaller binary while the latter is 1.1 - 2 times faster. -You also need to choose between CONFIG_KASAN_OUTLINE and CONFIG_KASAN_INLINE. -Outline and inline are compiler instrumentation types. The former produces -smaller binary while the latter is 1.1 - 2 times faster. +Both software KASAN modes work with both SLUB and SLAB memory allocators, +while the hardware tag-based KASAN currently only support SLUB. -Both KASAN modes work with both SLUB and SLAB memory allocators. -For better bug detection and nicer reporting, enable CONFIG_STACKTRACE. +For better error reports that include stack traces, enable CONFIG_STACKTRACE. To augment reports with last allocation and freeing stack of the physical page, it is recommended to enable also CONFIG_PAGE_OWNER and boot with page_owner=on. -To disable instrumentation for specific files or directories, add a line -similar to the following to the respective kernel Makefile: - -- For a single file (e.g. main.o):: - - KASAN_SANITIZE_main.o := n - -- For all files in one directory:: - - KASAN_SANITIZE := n - Error reports ~~~~~~~~~~~~~ @@ -136,22 +131,75 @@ freed (in case of a use-after-free bug report). Next comes a description of the accessed slab object and information about the accessed memory page. In the last section the report shows memory state around the accessed address. -Reading this part requires some understanding of how KASAN works. - -The state of each 8 aligned bytes of memory is encoded in one shadow byte. -Those 8 bytes can be accessible, partially accessible, freed or be a redzone. -We use the following encoding for each shadow byte: 0 means that all 8 bytes -of the corresponding memory region are accessible; number N (1 <= N <= 7) means -that the first N bytes are accessible, and other (8 - N) bytes are not; -any negative value indicates that the entire 8-byte word is inaccessible. -We use different negative values to distinguish between different kinds of -inaccessible memory like redzones or freed memory (see mm/kasan/kasan.h). +Internally KASAN tracks memory state separately for each memory granule, which +is either 8 or 16 aligned bytes depending on KASAN mode. Each number in the +memory state section of the report shows the state of one of the memory +granules that surround the accessed address. + +For generic KASAN the size of each memory granule is 8. The state of each +granule is encoded in one shadow byte. Those 8 bytes can be accessible, +partially accessible, freed or be a part of a redzone. KASAN uses the following +encoding for each shadow byte: 0 means that all 8 bytes of the corresponding +memory region are accessible; number N (1 <= N <= 7) means that the first N +bytes are accessible, and other (8 - N) bytes are not; any negative value +indicates that the entire 8-byte word is inaccessible. KASAN uses different +negative values to distinguish between different kinds of inaccessible memory +like redzones or freed memory (see mm/kasan/kasan.h). In the report above the arrows point to the shadow byte 03, which means that the accessed address is partially accessible. For tag-based KASAN this last report section shows the memory tags around the -accessed address (see Implementation details section). +accessed address (see `Implementation details`_ section). + +Boot parameters +~~~~~~~~~~~~~~~ + +Hardware tag-based KASAN mode (see the section about different mode below) is +intended for use in production as a security mitigation. Therefore it supports +boot parameters that allow to disable KASAN competely or otherwise control +particular KASAN features. + +The things that can be controlled are: + +1. Whether KASAN is enabled at all. +2. Whether KASAN collects and saves alloc/free stacks. +3. Whether KASAN panics on a detected bug or not. + +The ``kasan.mode`` boot parameter allows to choose one of three main modes: + +- ``kasan.mode=off`` - KASAN is disabled, no tag checks are performed +- ``kasan.mode=prod`` - only essential production features are enabled +- ``kasan.mode=full`` - all KASAN features are enabled + +The chosen mode provides default control values for the features mentioned +above. However it's also possible to override the default values by providing: + +- ``kasan.stacktrace=off`` or ``=on`` - enable alloc/free stack collection + (default: ``on`` for ``mode=full``, + otherwise ``off``) +- ``kasan.fault=report`` or ``=panic`` - only print KASAN report or also panic + (default: ``report``) + +If ``kasan.mode`` parameter is not provided, it defaults to ``full`` when +``CONFIG_DEBUG_KERNEL`` is enabled, and to ``prod`` otherwise. + +For developers +~~~~~~~~~~~~~~ + +Software KASAN modes use compiler instrumentation to insert validity checks. +Such instrumentation might be incompatible with some part of the kernel, and +therefore needs to be disabled. To disable instrumentation for specific files +or directories, add a line similar to the following to the respective kernel +Makefile: + +- For a single file (e.g. main.o):: + + KASAN_SANITIZE_main.o := n + +- For all files in one directory:: + + KASAN_SANITIZE := n Implementation details @@ -160,10 +208,10 @@ Implementation details Generic KASAN ~~~~~~~~~~~~~ -From a high level, our approach to memory error detection is similar to that -of kmemcheck: use shadow memory to record whether each byte of memory is safe -to access, and use compile-time instrumentation to insert checks of shadow -memory on each memory access. +From a high level perspective, KASAN's approach to memory error detection is +similar to that of kmemcheck: use shadow memory to record whether each byte of +memory is safe to access, and use compile-time instrumentation to insert checks +of shadow memory on each memory access. Generic KASAN dedicates 1/8th of kernel memory to its shadow memory (e.g. 16TB to cover 128TB on x86_64) and uses direct mapping with a scale and offset to @@ -194,20 +242,30 @@ Generic KASAN also reports the last 2 call stacks to creation of work that potentially has access to an object. Call stacks for the following are shown: call_rcu() and workqueue queuing. +Generic KASAN is the only mode that delays the reuse of freed object via +quarantine (see mm/kasan/quarantine.c for implementation). + Software tag-based KASAN ~~~~~~~~~~~~~~~~~~~~~~~~ -Tag-based KASAN uses the Top Byte Ignore (TBI) feature of modern arm64 CPUs to -store a pointer tag in the top byte of kernel pointers. Like generic KASAN it -uses shadow memory to store memory tags associated with each 16-byte memory +Software tag-based KASAN requires software memory tagging support in the form +of HWASan-like compiler instrumentation (see HWASan documentation for details). + +Software tag-based KASAN is currently only implemented for arm64 architecture. + +Software tag-based KASAN uses the Top Byte Ignore (TBI) feature of arm64 CPUs +to store a pointer tag in the top byte of kernel pointers. Like generic KASAN +it uses shadow memory to store memory tags associated with each 16-byte memory cell (therefore it dedicates 1/16th of the kernel memory for shadow memory). -On each memory allocation tag-based KASAN generates a random tag, tags the -allocated memory with this tag, and embeds this tag into the returned pointer. +On each memory allocation software tag-based KASAN generates a random tag, tags +the allocated memory with this tag, and embeds this tag into the returned +pointer. + Software tag-based KASAN uses compile-time instrumentation to insert checks before each memory access. These checks make sure that tag of the memory that is being accessed is equal to tag of the pointer that is used to access this -memory. In case of a tag mismatch tag-based KASAN prints a bug report. +memory. In case of a tag mismatch software tag-based KASAN prints a bug report. Software tag-based KASAN also has two instrumentation modes (outline, that emits callbacks to check memory accesses; and inline, that performs the shadow @@ -216,9 +274,36 @@ simply printed from the function that performs the access check. With inline instrumentation a brk instruction is emitted by the compiler, and a dedicated brk handler is used to print bug reports. -A potential expansion of this mode is a hardware tag-based mode, which would -use hardware memory tagging support instead of compiler instrumentation and -manual shadow memory manipulation. +Software tag-based KASAN uses 0xFF as a match-all pointer tag (accesses through +pointers with 0xFF pointer tag aren't checked). The value 0xFE is currently +reserved to tag freed memory regions. + +Software tag-based KASAN currently only supports tagging of +kmem_cache_alloc/kmalloc and page_alloc memory. + +Hardware tag-based KASAN +~~~~~~~~~~~~~~~~~~~~~~~~ + +Hardware tag-based KASAN is similar to the software mode in concept, but uses +hardware memory tagging support instead of compiler instrumentation and +shadow memory. + +Hardware tag-based KASAN is currently only implemented for arm64 architecture +and based on both arm64 Memory Tagging Extension (MTE) introduced in ARMv8.5 +Instruction Set Architecture, and Top Byte Ignore (TBI). + +Special arm64 instructions are used to assign memory tags for each allocation. +Same tags are assigned to pointers to those allocations. On every memory +access, hardware makes sure that tag of the memory that is being accessed is +equal to tag of the pointer that is used to access this memory. In case of a +tag mismatch a fault is generated and a report is printed. + +Hardware tag-based KASAN uses 0xFF as a match-all pointer tag (accesses through +pointers with 0xFF pointer tag aren't checked). The value 0xFE is currently +reserved to tag freed memory regions. + +Hardware tag-based KASAN currently only supports tagging of +kmem_cache_alloc/kmalloc and page_alloc memory. What memory accesses are sanitised by KASAN? -------------------------------------------- @@ -265,17 +350,17 @@ Most mappings in vmalloc space are small, requiring less than a full page of shadow space. Allocating a full shadow page per mapping would therefore be wasteful. Furthermore, to ensure that different mappings use different shadow pages, mappings would have to be aligned to -``KASAN_SHADOW_SCALE_SIZE * PAGE_SIZE``. +``KASAN_GRANULE_SIZE * PAGE_SIZE``. -Instead, we share backing space across multiple mappings. We allocate +Instead, KASAN shares backing space across multiple mappings. It allocates a backing page when a mapping in vmalloc space uses a particular page of the shadow region. This page can be shared by other vmalloc mappings later on. -We hook in to the vmap infrastructure to lazily clean up unused shadow +KASAN hooks into the vmap infrastructure to lazily clean up unused shadow memory. -To avoid the difficulties around swapping mappings around, we expect +To avoid the difficulties around swapping mappings around, KASAN expects that the part of the shadow region that covers the vmalloc space will not be covered by the early shadow page, but will be left unmapped. This will require changes in arch-specific code. @@ -286,24 +371,31 @@ architectures that do not have a fixed module region. CONFIG_KASAN_KUNIT_TEST & CONFIG_TEST_KASAN_MODULE -------------------------------------------------- -``CONFIG_KASAN_KUNIT_TEST`` utilizes the KUnit Test Framework for testing. -This means each test focuses on a small unit of functionality and -there are a few ways these tests can be run. +KASAN tests consist on two parts: + +1. Tests that are integrated with the KUnit Test Framework. Enabled with +``CONFIG_KASAN_KUNIT_TEST``. These tests can be run and partially verified +automatically in a few different ways, see the instructions below. -Each test will print the KASAN report if an error is detected and then -print the number of the test and the status of the test: +2. Tests that are currently incompatible with KUnit. Enabled with +``CONFIG_TEST_KASAN_MODULE`` and can only be run as a module. These tests can +only be verified manually, by loading the kernel module and inspecting the +kernel log for KASAN reports. -pass:: +Each KUnit-compatible KASAN test prints a KASAN report if an error is detected. +Then the test prints its number and status. + +When a test passes:: ok 28 - kmalloc_double_kzfree -or, if kmalloc failed:: +When a test fails due to a failed ``kmalloc``:: # kmalloc_large_oob_right: ASSERTION FAILED at lib/test_kasan.c:163 Expected ptr is not null, but is not ok 4 - kmalloc_large_oob_right -or, if a KASAN report was expected, but not found:: +When a test fails due to a missing KASAN report:: # kmalloc_double_kzfree: EXPECTATION FAILED at lib/test_kasan.c:629 Expected kasan_data->report_expected == kasan_data->report_found, but @@ -311,46 +403,38 @@ or, if a KASAN report was expected, but not found:: kasan_data->report_found == 0 not ok 28 - kmalloc_double_kzfree -All test statuses are tracked as they run and an overall status will -be printed at the end:: +At the end the cumulative status of all KASAN tests is printed. On success:: ok 1 - kasan -or:: +Or, if one of the tests failed:: not ok 1 - kasan -(1) Loadable Module -~~~~~~~~~~~~~~~~~~~~ + +There are a few ways to run KUnit-compatible KASAN tests. + +1. Loadable module +~~~~~~~~~~~~~~~~~~ With ``CONFIG_KUNIT`` enabled, ``CONFIG_KASAN_KUNIT_TEST`` can be built as -a loadable module and run on any architecture that supports KASAN -using something like insmod or modprobe. The module is called ``test_kasan``. +a loadable module and run on any architecture that supports KASAN by loading +the module with insmod or modprobe. The module is called ``test_kasan``. -(2) Built-In -~~~~~~~~~~~~~ +2. Built-In +~~~~~~~~~~~ With ``CONFIG_KUNIT`` built-in, ``CONFIG_KASAN_KUNIT_TEST`` can be built-in -on any architecture that supports KASAN. These and any other KUnit -tests enabled will run and print the results at boot as a late-init -call. +on any architecure that supports KASAN. These and any other KUnit tests enabled +will run and print the results at boot as a late-init call. -(3) Using kunit_tool -~~~~~~~~~~~~~~~~~~~~~ +3. Using kunit_tool +~~~~~~~~~~~~~~~~~~~ -With ``CONFIG_KUNIT`` and ``CONFIG_KASAN_KUNIT_TEST`` built-in, we can also -use kunit_tool to see the results of these along with other KUnit -tests in a more readable way. This will not print the KASAN reports -of tests that passed. Use `KUnit documentation <https://www.kernel.org/doc/html/latest/dev-tools/kunit/index.html>`_ for more up-to-date -information on kunit_tool. +With ``CONFIG_KUNIT`` and ``CONFIG_KASAN_KUNIT_TEST`` built-in, it's also +possible use ``kunit_tool`` to see the results of these and other KUnit tests +in a more readable way. This will not print the KASAN reports of the tests that +passed. Use `KUnit documentation <https://www.kernel.org/doc/html/latest/dev-tools/kunit/index.html>`_ +for more up-to-date information on ``kunit_tool``. .. _KUnit: https://www.kernel.org/doc/html/latest/dev-tools/kunit/index.html - -``CONFIG_TEST_KASAN_MODULE`` is a set of KASAN tests that could not be -converted to KUnit. These tests can be run only as a module with -``CONFIG_TEST_KASAN_MODULE`` built as a loadable module and -``CONFIG_KASAN`` built-in. The type of error expected and the -function being run is printed before the expression expected to give -an error. Then the error is printed, if found, and that test -should be interpreted to pass only if the error was the one expected -by the test. diff --git a/Documentation/devicetree/bindings/clock/adi,axi-clkgen.yaml b/Documentation/devicetree/bindings/clock/adi,axi-clkgen.yaml new file mode 100644 index 000000000000..0d06387184d6 --- /dev/null +++ b/Documentation/devicetree/bindings/clock/adi,axi-clkgen.yaml @@ -0,0 +1,53 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/clock/adi,axi-clkgen.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Binding for Analog Devices AXI clkgen pcore clock generator + +maintainers: + - Lars-Peter Clausen <lars@metafoo.de> + - Michael Hennerich <michael.hennerich@analog.com> + +description: | + The axi_clkgen IP core is a software programmable clock generator, + that can be synthesized on various FPGA platforms. + + Link: https://wiki.analog.com/resources/fpga/docs/axi_clkgen + +properties: + compatible: + enum: + - adi,axi-clkgen-2.00.a + + clocks: + description: + Specifies the reference clock(s) from which the output frequency is + derived. This must either reference one clock if only the first clock + input is connected or two if both clock inputs are connected. + minItems: 1 + maxItems: 2 + + '#clock-cells': + const: 0 + + reg: + maxItems: 1 + +required: + - compatible + - reg + - clocks + - '#clock-cells' + +additionalProperties: false + +examples: + - | + clock-controller@ff000000 { + compatible = "adi,axi-clkgen-2.00.a"; + #clock-cells = <0>; + reg = <0xff000000 0x1000>; + clocks = <&osc 1>; + }; diff --git a/Documentation/devicetree/bindings/clock/axi-clkgen.txt b/Documentation/devicetree/bindings/clock/axi-clkgen.txt deleted file mode 100644 index aca94fe9416f..000000000000 --- a/Documentation/devicetree/bindings/clock/axi-clkgen.txt +++ /dev/null @@ -1,25 +0,0 @@ -Binding for the axi-clkgen clock generator - -This binding uses the common clock binding[1]. - -[1] Documentation/devicetree/bindings/clock/clock-bindings.txt - -Required properties: -- compatible : shall be "adi,axi-clkgen-1.00.a" or "adi,axi-clkgen-2.00.a". -- #clock-cells : from common clock binding; Should always be set to 0. -- reg : Address and length of the axi-clkgen register set. -- clocks : Phandle and clock specifier for the parent clock(s). This must - either reference one clock if only the first clock input is connected or two - if both clock inputs are connected. For the later case the clock connected - to the first input must be specified first. - -Optional properties: -- clock-output-names : From common clock binding. - -Example: - clock@ff000000 { - compatible = "adi,axi-clkgen"; - #clock-cells = <0>; - reg = <0xff000000 0x1000>; - clocks = <&osc 1>; - }; diff --git a/Documentation/devicetree/bindings/clock/canaan,k210-clk.yaml b/Documentation/devicetree/bindings/clock/canaan,k210-clk.yaml new file mode 100644 index 000000000000..565ca468cb44 --- /dev/null +++ b/Documentation/devicetree/bindings/clock/canaan,k210-clk.yaml @@ -0,0 +1,54 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/clock/canaan,k210-clk.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Canaan Kendryte K210 Clock Device Tree Bindings + +maintainers: + - Damien Le Moal <damien.lemoal@wdc.com> + +description: | + Canaan Kendryte K210 SoC clocks driver bindings. The clock + controller node must be defined as a child node of the K210 + system controller node. + + See also: + - dt-bindings/clock/k210-clk.h + +properties: + compatible: + const: canaan,k210-clk + + clocks: + description: + Phandle of the SoC 26MHz fixed-rate oscillator clock. + + '#clock-cells': + const: 1 + +required: + - compatible + - '#clock-cells' + - clocks + +additionalProperties: false + +examples: + - | + #include <dt-bindings/clock/k210-clk.h> + clocks { + in0: oscillator { + compatible = "fixed-clock"; + #clock-cells = <0>; + clock-frequency = <26000000>; + }; + }; + + /* ... */ + sysclk: clock-controller { + #clock-cells = <1>; + compatible = "canaan,k210-clk"; + clocks = <&in0>; + }; diff --git a/Documentation/devicetree/bindings/clock/fsl,flexspi-clock.yaml b/Documentation/devicetree/bindings/clock/fsl,flexspi-clock.yaml new file mode 100644 index 000000000000..1fa390ee7b9b --- /dev/null +++ b/Documentation/devicetree/bindings/clock/fsl,flexspi-clock.yaml @@ -0,0 +1,55 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/clock/fsl,flexspi-clock.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Freescale FlexSPI clock driver for Layerscape SoCs + +maintainers: + - Michael Walle <michael@walle.cc> + +description: + The Freescale Layerscape SoCs have a special FlexSPI clock which is + derived from the platform PLL. + +properties: + compatible: + enum: + - fsl,ls1028a-flexspi-clk + - fsl,lx2160a-flexspi-clk + + reg: + maxItems: 1 + + clocks: + maxItems: 1 + + '#clock-cells': + const: 0 + + clock-output-names: + maxItems: 1 + +required: + - compatible + - reg + - clocks + - '#clock-cells' + +additionalProperties: false + +examples: + - | + dcfg { + #address-cells = <1>; + #size-cells = <1>; + + fspi_clk: clock-controller@900 { + compatible = "fsl,ls1028a-flexspi-clk"; + reg = <0x900 0x4>; + #clock-cells = <0>; + clocks = <&parentclk>; + clock-output-names = "fspi_clk"; + }; + }; diff --git a/Documentation/devicetree/bindings/clock/qcom,aoncc-sm8250.yaml b/Documentation/devicetree/bindings/clock/qcom,aoncc-sm8250.yaml new file mode 100644 index 000000000000..c40a74b5d672 --- /dev/null +++ b/Documentation/devicetree/bindings/clock/qcom,aoncc-sm8250.yaml @@ -0,0 +1,58 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/clock/qcom,aoncc-sm8250.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Clock bindings for LPASS Always ON Clock Controller on SM8250 SoCs + +maintainers: + - Srinivas Kandagatla <srinivas.kandagatla@linaro.org> + +description: | + The clock consumer should specify the desired clock by having the clock + ID in its "clocks" phandle cell. + See include/dt-bindings/clock/qcom,sm8250-lpass-aoncc.h for the full list + of Audio Clock controller clock IDs. + +properties: + compatible: + const: qcom,sm8250-lpass-aon + + reg: + maxItems: 1 + + '#clock-cells': + const: 1 + + clocks: + items: + - description: LPASS Core voting clock + - description: Glitch Free Mux register clock + + clock-names: + items: + - const: core + - const: bus + +required: + - compatible + - reg + - '#clock-cells' + - clocks + - clock-names + +additionalProperties: false + +examples: + - | + #include <dt-bindings/clock/qcom,sm8250-lpass-aoncc.h> + #include <dt-bindings/sound/qcom,q6afe.h> + clock-controller@3800000 { + #clock-cells = <1>; + compatible = "qcom,sm8250-lpass-aon"; + reg = <0x03380000 0x40000>; + clocks = <&q6afecc LPASS_HW_MACRO_VOTE LPASS_CLK_ATTRIBUTE_COUPLE_NO>, + <&q6afecc LPASS_CLK_ID_TX_CORE_MCLK LPASS_CLK_ATTRIBUTE_COUPLE_NO>; + clock-names = "core", "bus"; + }; diff --git a/Documentation/devicetree/bindings/clock/qcom,audiocc-sm8250.yaml b/Documentation/devicetree/bindings/clock/qcom,audiocc-sm8250.yaml new file mode 100644 index 000000000000..915d76206ad0 --- /dev/null +++ b/Documentation/devicetree/bindings/clock/qcom,audiocc-sm8250.yaml @@ -0,0 +1,58 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/clock/qcom,audiocc-sm8250.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Clock bindings for LPASS Audio Clock Controller on SM8250 SoCs + +maintainers: + - Srinivas Kandagatla <srinivas.kandagatla@linaro.org> + +description: | + The clock consumer should specify the desired clock by having the clock + ID in its "clocks" phandle cell. + See include/dt-bindings/clock/qcom,sm8250-lpass-audiocc.h for the full list + of Audio Clock controller clock IDs. + +properties: + compatible: + const: qcom,sm8250-lpass-audiocc + + reg: + maxItems: 1 + + '#clock-cells': + const: 1 + + clocks: + items: + - description: LPASS Core voting clock + - description: Glitch Free Mux register clock + + clock-names: + items: + - const: core + - const: bus + +required: + - compatible + - reg + - '#clock-cells' + - clocks + - clock-names + +additionalProperties: false + +examples: + - | + #include <dt-bindings/clock/qcom,sm8250-lpass-audiocc.h> + #include <dt-bindings/sound/qcom,q6afe.h> + clock-controller@3300000 { + #clock-cells = <1>; + compatible = "qcom,sm8250-lpass-audiocc"; + reg = <0x03300000 0x30000>; + clocks = <&q6afecc LPASS_HW_MACRO_VOTE LPASS_CLK_ATTRIBUTE_COUPLE_NO>, + <&q6afecc LPASS_CLK_ID_TX_CORE_MCLK LPASS_CLK_ATTRIBUTE_COUPLE_NO>; + clock-names = "core", "bus"; + }; diff --git a/Documentation/devicetree/bindings/clock/qcom,gcc-sdx55.yaml b/Documentation/devicetree/bindings/clock/qcom,gcc-sdx55.yaml new file mode 100644 index 000000000000..1121b3934cb9 --- /dev/null +++ b/Documentation/devicetree/bindings/clock/qcom,gcc-sdx55.yaml @@ -0,0 +1,77 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/clock/qcom,gcc-sdx55.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Qualcomm Global Clock & Reset Controller Binding for SDX55 + +maintainers: + - Vinod Koul <vkoul@kernel.org> + - Manivannan Sadhasivam <manivannan.sadhasivam@linaro.org> + +description: | + Qualcomm global clock control module which supports the clocks, resets and + power domains on SDX55 + + See also: + - dt-bindings/clock/qcom,gcc-sdx55.h + +properties: + compatible: + const: qcom,gcc-sdx55 + + clocks: + items: + - description: Board XO source + - description: Sleep clock source + - description: PLL test clock source (Optional clock) + minItems: 2 + maxItems: 3 + + clock-names: + items: + - const: bi_tcxo + - const: sleep_clk + - const: core_bi_pll_test_se # Optional clock + minItems: 2 + maxItems: 3 + + '#clock-cells': + const: 1 + + '#reset-cells': + const: 1 + + '#power-domain-cells': + const: 1 + + reg: + maxItems: 1 + +required: + - compatible + - clocks + - clock-names + - reg + - '#clock-cells' + - '#reset-cells' + - '#power-domain-cells' + +additionalProperties: false + +examples: + - | + #include <dt-bindings/clock/qcom,rpmh.h> + clock-controller@100000 { + compatible = "qcom,gcc-sdx55"; + reg = <0x00100000 0x1f0000>; + clocks = <&rpmhcc RPMH_CXO_CLK>, + <&sleep_clk>, <&pll_test_clk>; + clock-names = "bi_tcxo", "sleep_clk", "core_bi_pll_test_se"; + #clock-cells = <1>; + #reset-cells = <1>; + #power-domain-cells = <1>; + }; + +... diff --git a/Documentation/devicetree/bindings/clock/qcom,rpmhcc.yaml b/Documentation/devicetree/bindings/clock/qcom,rpmhcc.yaml index a46a3a799a70..12c9cbc0ebf9 100644 --- a/Documentation/devicetree/bindings/clock/qcom,rpmhcc.yaml +++ b/Documentation/devicetree/bindings/clock/qcom,rpmhcc.yaml @@ -19,8 +19,10 @@ properties: enum: - qcom,sc7180-rpmh-clk - qcom,sdm845-rpmh-clk + - qcom,sdx55-rpmh-clk - qcom,sm8150-rpmh-clk - qcom,sm8250-rpmh-clk + - qcom,sm8350-rpmh-clk clocks: maxItems: 1 diff --git a/Documentation/devicetree/bindings/clock/qcom,sc7180-camcc.yaml b/Documentation/devicetree/bindings/clock/qcom,sc7180-camcc.yaml new file mode 100644 index 000000000000..f49027edfc44 --- /dev/null +++ b/Documentation/devicetree/bindings/clock/qcom,sc7180-camcc.yaml @@ -0,0 +1,73 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/clock/qcom,sc7180-camcc.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Qualcomm Camera Clock & Reset Controller Binding for SC7180 + +maintainers: + - Taniya Das <tdas@codeaurora.org> + +description: | + Qualcomm camera clock control module which supports the clocks, resets and + power domains on SC7180. + + See also: + - dt-bindings/clock/qcom,camcc-sc7180.h + +properties: + compatible: + const: qcom,sc7180-camcc + + clocks: + items: + - description: Board XO source + - description: Camera_ahb clock from GCC + - description: Camera XO clock from GCC + + clock-names: + items: + - const: bi_tcxo + - const: iface + - const: xo + + '#clock-cells': + const: 1 + + '#reset-cells': + const: 1 + + '#power-domain-cells': + const: 1 + + reg: + maxItems: 1 + +required: + - compatible + - reg + - clocks + - clock-names + - '#clock-cells' + - '#reset-cells' + - '#power-domain-cells' + +additionalProperties: false + +examples: + - | + #include <dt-bindings/clock/qcom,gcc-sc7180.h> + #include <dt-bindings/clock/qcom,rpmh.h> + clock-controller@ad00000 { + compatible = "qcom,sc7180-camcc"; + reg = <0x0ad00000 0x10000>; + clocks = <&rpmhcc RPMH_CXO_CLK>, + <&gcc GCC_CAMERA_AHB_CLK>, + <&gcc GCC_CAMERA_XO_CLK>; + clock-names = "bi_tcxo", "iface", "xo"; + #clock-cells = <1>; + #reset-cells = <1>; + #power-domain-cells = <1>; + }; +... diff --git a/Documentation/devicetree/bindings/clock/renesas,rcar-usb2-clock-sel.txt b/Documentation/devicetree/bindings/clock/renesas,rcar-usb2-clock-sel.txt deleted file mode 100644 index da92f5748dee..000000000000 --- a/Documentation/devicetree/bindings/clock/renesas,rcar-usb2-clock-sel.txt +++ /dev/null @@ -1,68 +0,0 @@ -* Renesas R-Car USB 2.0 clock selector - -This file provides information on what the device node for the R-Car USB 2.0 -clock selector. - -If you connect an external clock to the USB_EXTAL pin only, you should set -the clock rate to "usb_extal" node only. -If you connect an oscillator to both the USB_XTAL and USB_EXTAL, this module -is not needed because this is default setting. (Of course, you can set the -clock rates to both "usb_extal" and "usb_xtal" nodes. - -Case 1: An external clock connects to R-Car SoC - +----------+ +--- R-Car ---------------------+ - |External |---|USB_EXTAL ---> all usb channels| - |clock | |USB_XTAL | - +----------+ +-------------------------------+ -In this case, we need this driver with "usb_extal" clock. - -Case 2: An oscillator connects to R-Car SoC - +----------+ +--- R-Car ---------------------+ - |Oscillator|---|USB_EXTAL -+-> all usb channels| - | |---|USB_XTAL --+ | - +----------+ +-------------------------------+ -In this case, we don't need this selector. - -Required properties: -- compatible: "renesas,r8a7795-rcar-usb2-clock-sel" if the device is a part of - an R8A7795 SoC. - "renesas,r8a7796-rcar-usb2-clock-sel" if the device if a part of - an R8A77960 SoC. - "renesas,r8a77961-rcar-usb2-clock-sel" if the device if a part of - an R8A77961 SoC. - "renesas,rcar-gen3-usb2-clock-sel" for a generic R-Car Gen3 - compatible device. - - When compatible with the generic version, nodes must list the - SoC-specific version corresponding to the platform first - followed by the generic version. - -- reg: offset and length of the USB 2.0 clock selector register block. -- clocks: A list of phandles and specifier pairs. -- clock-names: Name of the clocks. - - The functional clock of USB 2.0 host side must be "ehci_ohci" - - The functional clock of HS-USB side must be "hs-usb-if" - - The USB_EXTAL clock pin must be "usb_extal" - - The USB_XTAL clock pin must be "usb_xtal" -- #clock-cells: Must be 0 -- power-domains: A phandle and symbolic PM domain specifier. - See power/renesas,rcar-sysc.yaml. -- resets: A list of phandles and specifier pairs. -- reset-names: Name of the resets. - - The reset of USB 2.0 host side must be "ehci_ohci" - - The reset of HS-USB side must be "hs-usb-if" - -Example (R-Car H3): - - usb2_clksel: clock-controller@e6590630 { - compatible = "renesas,r8a7795-rcar-usb2-clock-sel", - "renesas,rcar-gen3-usb2-clock-sel"; - reg = <0 0xe6590630 0 0x02>; - clocks = <&cpg CPG_MOD 703>, <&cpg CPG_MOD 704>, - <&usb_extal>, <&usb_xtal>; - clock-names = "ehci_ohci", "hs-usb-if", "usb_extal", "usb_xtal"; - #clock-cells = <0>; - power-domains = <&sysc R8A7795_PD_ALWAYS_ON>; - resets = <&cpg 703>, <&cpg 704>; - reset-names = "ehci_ohci", "hs-usb-if"; - }; diff --git a/Documentation/devicetree/bindings/clock/renesas,rcar-usb2-clock-sel.yaml b/Documentation/devicetree/bindings/clock/renesas,rcar-usb2-clock-sel.yaml new file mode 100644 index 000000000000..5be1229b3d6e --- /dev/null +++ b/Documentation/devicetree/bindings/clock/renesas,rcar-usb2-clock-sel.yaml @@ -0,0 +1,100 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: "http://devicetree.org/schemas/clock/renesas,rcar-usb2-clock-sel.yaml#" +$schema: "http://devicetree.org/meta-schemas/core.yaml#" + +title: Renesas R-Car USB 2.0 clock selector + +maintainers: + - Yoshihiro Shimoda <yoshihiro.shimoda.uh@renesas.com> + +description: | + If you connect an external clock to the USB_EXTAL pin only, you should set + the clock rate to "usb_extal" node only. + If you connect an oscillator to both the USB_XTAL and USB_EXTAL, this module + is not needed because this is default setting. (Of course, you can set the + clock rates to both "usb_extal" and "usb_xtal" nodes. + + Case 1: An external clock connects to R-Car SoC + +----------+ +--- R-Car ---------------------+ + |External |---|USB_EXTAL ---> all usb channels| + |clock | |USB_XTAL | + +----------+ +-------------------------------+ + + In this case, we need this driver with "usb_extal" clock. + + Case 2: An oscillator connects to R-Car SoC + +----------+ +--- R-Car ---------------------+ + |Oscillator|---|USB_EXTAL -+-> all usb channels| + | |---|USB_XTAL --+ | + +----------+ +-------------------------------+ + In this case, we don't need this selector. + +properties: + compatible: + items: + - enum: + - renesas,r8a7795-rcar-usb2-clock-sel # R-Car H3 + - renesas,r8a7796-rcar-usb2-clock-sel # R-Car M3-W + - renesas,r8a77961-rcar-usb2-clock-sel # R-Car M3-W+ + - const: renesas,rcar-gen3-usb2-clock-sel + + reg: + maxItems: 1 + + clocks: + minItems: 4 + maxItems: 4 + + clock-names: + items: + - const: ehci_ohci + - const: hs-usb-if + - const: usb_extal + - const: usb_xtal + + '#clock-cells': + const: 0 + + power-domains: + maxItems: 1 + + resets: + minItems: 2 + maxItems: 2 + + reset-names: + items: + - const: ehci_ohci + - const: hs-usb-if + +required: + - compatible + - reg + - clocks + - clock-names + - '#clock-cells' + - power-domains + - resets + - reset-names + +additionalProperties: false + +examples: + - | + #include <dt-bindings/clock/r8a7795-cpg-mssr.h> + #include <dt-bindings/power/r8a7795-sysc.h> + + usb2_clksel: clock-controller@e6590630 { + compatible = "renesas,r8a7795-rcar-usb2-clock-sel", + "renesas,rcar-gen3-usb2-clock-sel"; + reg = <0xe6590630 0x02>; + clocks = <&cpg CPG_MOD 703>, <&cpg CPG_MOD 704>, + <&usb_extal>, <&usb_xtal>; + clock-names = "ehci_ohci", "hs-usb-if", "usb_extal", "usb_xtal"; + #clock-cells = <0>; + power-domains = <&sysc R8A7795_PD_ALWAYS_ON>; + resets = <&cpg 703>, <&cpg 704>; + reset-names = "ehci_ohci", "hs-usb-if"; + }; diff --git a/Documentation/devicetree/bindings/clock/sifive/fu740-prci.yaml b/Documentation/devicetree/bindings/clock/sifive/fu740-prci.yaml new file mode 100644 index 000000000000..e17143cac316 --- /dev/null +++ b/Documentation/devicetree/bindings/clock/sifive/fu740-prci.yaml @@ -0,0 +1,60 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +# Copyright (C) 2020 SiFive, Inc. +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/clock/sifive/fu740-prci.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: SiFive FU740 Power Reset Clock Interrupt Controller (PRCI) + +maintainers: + - Zong Li <zong.li@sifive.com> + - Paul Walmsley <paul.walmsley@sifive.com> + +description: + On the FU740 family of SoCs, most system-wide clock and reset integration + is via the PRCI IP block. + The clock consumer should specify the desired clock via the clock ID + macros defined in include/dt-bindings/clock/sifive-fu740-prci.h. + These macros begin with PRCI_CLK_. + + The hfclk and rtcclk nodes are required, and represent physical + crystals or resonators located on the PCB. These nodes should be present + underneath /, rather than /soc. + +properties: + compatible: + const: sifive,fu740-c000-prci + + reg: + maxItems: 1 + + clocks: + items: + - description: high frequency clock. + - description: RTL clock. + + clock-names: + items: + - const: hfclk + - const: rtcclk + + "#clock-cells": + const: 1 + +required: + - compatible + - reg + - clocks + - "#clock-cells" + +additionalProperties: false + +examples: + - | + prci: clock-controller@10000000 { + compatible = "sifive,fu740-c000-prci"; + reg = <0x10000000 0x1000>; + clocks = <&hfclk>, <&rtcclk>; + #clock-cells = <1>; + }; diff --git a/Documentation/devicetree/bindings/display/panel/panel-simple.yaml b/Documentation/devicetree/bindings/display/panel/panel-simple.yaml index f9750b0b6708..27fffafe5b5c 100644 --- a/Documentation/devicetree/bindings/display/panel/panel-simple.yaml +++ b/Documentation/devicetree/bindings/display/panel/panel-simple.yaml @@ -159,6 +159,8 @@ properties: - innolux,g121x1-l03 # Innolux Corporation 11.6" WXGA (1366x768) TFT LCD panel - innolux,n116bge + # InnoLux 13.3" FHD (1920x1080) eDP TFT LCD panel + - innolux,n125hce-gn1 # InnoLux 15.6" WXGA TFT LCD panel - innolux,n156bge-l21 # Innolux Corporation 7.0" WSVGA (1024x600) TFT LCD panel diff --git a/Documentation/devicetree/bindings/gpio/gpio-pca95xx.yaml b/Documentation/devicetree/bindings/gpio/gpio-pca95xx.yaml index 183ec23eda39..f5ee23c2df60 100644 --- a/Documentation/devicetree/bindings/gpio/gpio-pca95xx.yaml +++ b/Documentation/devicetree/bindings/gpio/gpio-pca95xx.yaml @@ -48,6 +48,7 @@ properties: - nxp,pcal6416 - nxp,pcal6524 - nxp,pcal9535 + - nxp,pcal9554b - nxp,pcal9555a - onnn,cat9554 - onnn,pca9654 diff --git a/Documentation/devicetree/bindings/gpio/gpio-xilinx.txt b/Documentation/devicetree/bindings/gpio/gpio-xilinx.txt index 08eed2335db0..e506f30e1a95 100644 --- a/Documentation/devicetree/bindings/gpio/gpio-xilinx.txt +++ b/Documentation/devicetree/bindings/gpio/gpio-xilinx.txt @@ -13,6 +13,7 @@ Required properties: - gpio-controller : Marks the device node as a GPIO controller. Optional properties: +- clocks : Input clock specifier. Refer to common clock bindings. - interrupts : Interrupt mapping for GPIO IRQ. - xlnx,all-inputs : if n-th bit is setup, GPIO-n is input - xlnx,dout-default : if n-th bit is 1, GPIO-n default value is 1 @@ -29,6 +30,7 @@ Example: gpio: gpio@40000000 { #gpio-cells = <2>; compatible = "xlnx,xps-gpio-1.00.a"; + clocks = <&clkc25>; gpio-controller ; interrupt-parent = <µblaze_0_intc>; interrupts = < 6 2 >; diff --git a/Documentation/devicetree/bindings/gpio/mediatek,mt7621-gpio.txt b/Documentation/devicetree/bindings/gpio/mediatek,mt7621-gpio.txt deleted file mode 100644 index e1c49b660d3a..000000000000 --- a/Documentation/devicetree/bindings/gpio/mediatek,mt7621-gpio.txt +++ /dev/null @@ -1,35 +0,0 @@ -Mediatek MT7621 SoC GPIO controller bindings - -The IP core used inside these SoCs has 3 banks of 32 GPIOs each. -The registers of all the banks are interwoven inside one single IO range. -We load one GPIO controller instance per bank. Also the GPIO controller can receive -interrupts on any of the GPIOs, either edge or level. It then interrupts the CPU -using GIC INT12. - -Required properties for the top level node: -- #gpio-cells : Should be two. The first cell is the GPIO pin number and the - second cell specifies GPIO flags, as defined in <dt-bindings/gpio/gpio.h>. - Only the GPIO_ACTIVE_HIGH and GPIO_ACTIVE_LOW flags are supported. -- #interrupt-cells : Specifies the number of cells needed to encode an - interrupt. Should be 2. The first cell defines the interrupt number, - the second encodes the trigger flags encoded as described in - Documentation/devicetree/bindings/interrupt-controller/interrupts.txt -- compatible: - - "mediatek,mt7621-gpio" for Mediatek controllers -- reg : Physical base address and length of the controller's registers -- interrupt-parent : phandle of the parent interrupt controller. -- interrupts : Interrupt specifier for the controllers interrupt. -- interrupt-controller : Mark the device node as an interrupt controller. -- gpio-controller : Marks the device node as a GPIO controller. - -Example: - gpio@600 { - #gpio-cells = <2>; - #interrupt-cells = <2>; - compatible = "mediatek,mt7621-gpio"; - gpio-controller; - interrupt-controller; - reg = <0x600 0x100>; - interrupt-parent = <&gic>; - interrupts = <GIC_SHARED 12 IRQ_TYPE_LEVEL_HIGH>; - }; diff --git a/Documentation/devicetree/bindings/gpio/mediatek,mt7621-gpio.yaml b/Documentation/devicetree/bindings/gpio/mediatek,mt7621-gpio.yaml new file mode 100644 index 000000000000..5bbb2a31266e --- /dev/null +++ b/Documentation/devicetree/bindings/gpio/mediatek,mt7621-gpio.yaml @@ -0,0 +1,72 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/gpio/mediatek,mt7621-gpio.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Mediatek MT7621 SoC GPIO controller + +maintainers: + - Sergio Paracuellos <sergio.paracuellos@gmail.com> + +description: | + The IP core used inside these SoCs has 3 banks of 32 GPIOs each. + The registers of all the banks are interwoven inside one single IO range. + We load one GPIO controller instance per bank. Also the GPIO controller can receive + interrupts on any of the GPIOs, either edge or level. It then interrupts the CPU + using GIC INT12. + +properties: + $nodename: + pattern: "^gpio@[0-9a-f]+$" + + compatible: + const: mediatek,mt7621-gpio + + reg: + maxItems: 1 + + "#gpio-cells": + const: 2 + + gpio-controller: true + gpio-ranges: true + + interrupt-controller: true + + "#interrupt-cells": + const: 2 + + interrupts: + maxItems: 1 + +required: + - compatible + - reg + - "#gpio-cells" + - gpio-controller + - gpio-ranges + - interrupt-controller + - "#interrupt-cells" + - interrupts + +additionalProperties: false + +examples: + - | + #include <dt-bindings/gpio/gpio.h> + #include <dt-bindings/interrupt-controller/mips-gic.h> + + gpio@600 { + compatible = "mediatek,mt7621-gpio"; + reg = <0x600 0x100>; + #gpio-cells = <2>; + gpio-controller; + gpio-ranges = <&pinctrl 0 0 95>; + interrupt-controller; + #interrupt-cells = <2>; + interrupt-parent = <&gic>; + interrupts = <GIC_SHARED 12 IRQ_TYPE_LEVEL_HIGH>; + }; + +... diff --git a/Documentation/devicetree/bindings/gpio/mstar,msc313-gpio.yaml b/Documentation/devicetree/bindings/gpio/mstar,msc313-gpio.yaml new file mode 100644 index 000000000000..1f2ef408bb43 --- /dev/null +++ b/Documentation/devicetree/bindings/gpio/mstar,msc313-gpio.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/mstar,msc313-gpio.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: MStar/SigmaStar GPIO controller + +maintainers: + - Daniel Palmer <daniel@thingy.jp> + +properties: + $nodename: + pattern: "^gpio@[0-9a-f]+$" + + compatible: + const: mstar,msc313-gpio + + reg: + maxItems: 1 + + gpio-controller: true + + "#gpio-cells": + const: 2 + + gpio-ranges: true + + interrupt-controller: true + + "#interrupt-cells": + const: 2 + +required: + - compatible + - reg + - gpio-controller + - "#gpio-cells" + - interrupt-controller + - "#interrupt-cells" + +additionalProperties: false + +examples: + - | + #include <dt-bindings/gpio/msc313-gpio.h> + + gpio: gpio@207800 { + compatible = "mstar,msc313e-gpio"; + #gpio-cells = <2>; + reg = <0x207800 0x200>; + gpio-controller; + gpio-ranges = <&pinctrl 0 36 22>, + <&pinctrl 22 63 4>, + <&pinctrl 26 68 6>; + #interrupt-cells = <2>; + interrupt-controller; + interrupt-parent = <&intc_fiq>; + }; diff --git a/Documentation/devicetree/bindings/i3c/mipi-i3c-hci.yaml b/Documentation/devicetree/bindings/i3c/mipi-i3c-hci.yaml new file mode 100644 index 000000000000..07a7b10163a3 --- /dev/null +++ b/Documentation/devicetree/bindings/i3c/mipi-i3c-hci.yaml @@ -0,0 +1,47 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: "http://devicetree.org/schemas/i3c/mipi-i3c-hci.yaml#" +$schema: "http://devicetree.org/meta-schemas/core.yaml#" + +title: MIPI I3C HCI Device Tree Bindings + +maintainers: + - Nicolas Pitre <npitre@baylibre.com> + +description: | + MIPI I3C Host Controller Interface + + The MIPI I3C HCI (Host Controller Interface) specification defines + a common software driver interface to support compliant MIPI I3C + host controller hardware implementations from multiple vendors. + + The hardware is self-advertising for differences in implementation + capabilities, including the spec version it is based on, so there + isn't much to describe here (yet). + + For details, please see: + https://www.mipi.org/specifications/i3c-hci + +properties: + compatible: + const: mipi-i3c-hci + reg: + maxItems: 1 + interrupts: + maxItems: 1 + +required: + - compatible + - reg + - interrupts + +additionalProperties: false + +examples: + - | + i3c@a0000000 { + compatible = "mipi-i3c-hci"; + reg = <0xa0000000 0x2000>; + interrupts = <89>; + }; diff --git a/Documentation/devicetree/bindings/power/reset/ocelot-reset.txt b/Documentation/devicetree/bindings/power/reset/ocelot-reset.txt index 4d530d815484..c5de7b555feb 100644 --- a/Documentation/devicetree/bindings/power/reset/ocelot-reset.txt +++ b/Documentation/devicetree/bindings/power/reset/ocelot-reset.txt @@ -7,7 +7,9 @@ The reset registers are both present in the MSCC vcoreiii MIPS and microchip Sparx5 armv8 SoC's. Required Properties: - - compatible: "mscc,ocelot-chip-reset" or "microchip,sparx5-chip-reset" + + - compatible: "mscc,ocelot-chip-reset", "mscc,luton-chip-reset", + "mscc,jaguar2-chip-reset" or "microchip,sparx5-chip-reset" Example: reset@1070008 { diff --git a/Documentation/devicetree/bindings/power/reset/regulator-poweroff.yaml b/Documentation/devicetree/bindings/power/reset/regulator-poweroff.yaml new file mode 100644 index 000000000000..03bd1fa5a623 --- /dev/null +++ b/Documentation/devicetree/bindings/power/reset/regulator-poweroff.yaml @@ -0,0 +1,37 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/power/reset/regulator-poweroff.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Force-disable power regulator to turn the power off. + +maintainers: + - Michael Klein <michael@fossekall.de> + +description: | + When the power-off handler is called, a power regulator is disabled by + calling regulator_force_disable(). If the power is still on and the + CPU still running after a 3000ms delay, a warning is emitted. + +properties: + compatible: + const: "regulator-poweroff" + + cpu-supply: + description: + regulator to disable on power-down + +required: + - compatible + - cpu-supply + +additionalProperties: false + +examples: + - | + regulator-poweroff { + compatible = "regulator-poweroff"; + cpu-supply = <®_vcc1v2>; + }; +... diff --git a/Documentation/devicetree/bindings/pwm/atmel-tcb-pwm.txt b/Documentation/devicetree/bindings/pwm/atmel-tcb-pwm.txt deleted file mode 100644 index 985fcc65f8c4..000000000000 --- a/Documentation/devicetree/bindings/pwm/atmel-tcb-pwm.txt +++ /dev/null @@ -1,16 +0,0 @@ -Atmel TCB PWM controller - -Required properties: -- compatible: should be "atmel,tcb-pwm" -- #pwm-cells: should be 3. See pwm.yaml in this directory for a description of - the cells format. The only third cell flag supported by this binding is - PWM_POLARITY_INVERTED. -- tc-block: The Timer Counter block to use as a PWM chip. - -Example: - -pwm { - compatible = "atmel,tcb-pwm"; - #pwm-cells = <3>; - tc-block = <1>; -}; diff --git a/Documentation/devicetree/bindings/pwm/intel,keembay-pwm.yaml b/Documentation/devicetree/bindings/pwm/intel,keembay-pwm.yaml new file mode 100644 index 000000000000..ff6880a02ce6 --- /dev/null +++ b/Documentation/devicetree/bindings/pwm/intel,keembay-pwm.yaml @@ -0,0 +1,47 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +# Copyright (C) 2020 Intel Corporation +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/pwm/intel,keembay-pwm.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Intel Keem Bay PWM Device Tree Bindings + +maintainers: + - Vijayakannan Ayyathurai <vijayakannan.ayyathurai@intel.com> + +allOf: + - $ref: pwm.yaml# + +properties: + compatible: + enum: + - intel,keembay-pwm + + reg: + maxItems: 1 + + clocks: + maxItems: 1 + + "#pwm-cells": + const: 2 + +required: + - compatible + - reg + - clocks + - '#pwm-cells' + +additionalProperties: false + +examples: + - | + #define KEEM_BAY_A53_GPIO + + pwm@203200a0 { + compatible = "intel,keembay-pwm"; + reg = <0x203200a0 0xe8>; + clocks = <&scmi_clk KEEM_BAY_A53_GPIO>; + #pwm-cells = <2>; + }; diff --git a/Documentation/devicetree/bindings/pwm/intel,lgm-pwm.yaml b/Documentation/devicetree/bindings/pwm/intel,lgm-pwm.yaml new file mode 100644 index 000000000000..11a606536169 --- /dev/null +++ b/Documentation/devicetree/bindings/pwm/intel,lgm-pwm.yaml @@ -0,0 +1,44 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/pwm/intel,lgm-pwm.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: LGM SoC PWM fan controller + +maintainers: + - Rahul Tanwar <rtanwar@maxlinear.com> + +properties: + compatible: + const: intel,lgm-pwm + + reg: + maxItems: 1 + + "#pwm-cells": + const: 2 + + clocks: + maxItems: 1 + + resets: + maxItems: 1 + +required: + - compatible + - reg + - clocks + - resets + +additionalProperties: false + +examples: + - | + pwm: pwm@e0d00000 { + compatible = "intel,lgm-pwm"; + reg = <0xe0d00000 0x30>; + #pwm-cells = <2>; + clocks = <&cgu0 126>; + resets = <&rcu0 0x30 21>; + }; diff --git a/Documentation/devicetree/bindings/pwm/pwm-mediatek.txt b/Documentation/devicetree/bindings/pwm/pwm-mediatek.txt index 29adff59c479..25ed214473d7 100644 --- a/Documentation/devicetree/bindings/pwm/pwm-mediatek.txt +++ b/Documentation/devicetree/bindings/pwm/pwm-mediatek.txt @@ -7,6 +7,7 @@ Required properties: - "mediatek,mt7623-pwm": found on mt7623 SoC. - "mediatek,mt7628-pwm": found on mt7628 SoC. - "mediatek,mt7629-pwm": found on mt7629 SoC. + - "mediatek,mt8183-pwm": found on mt8183 SoC. - "mediatek,mt8516-pwm": found on mt8516 SoC. - reg: physical base address and length of the controller's registers. - #pwm-cells: must be 2. See pwm.yaml in this directory for a description of diff --git a/Documentation/devicetree/bindings/pwm/pwm-mtk-disp.txt b/Documentation/devicetree/bindings/pwm/pwm-mtk-disp.txt index 0521957c253f..902b271891ae 100644 --- a/Documentation/devicetree/bindings/pwm/pwm-mtk-disp.txt +++ b/Documentation/devicetree/bindings/pwm/pwm-mtk-disp.txt @@ -4,6 +4,7 @@ Required properties: - compatible: should be "mediatek,<name>-disp-pwm": - "mediatek,mt2701-disp-pwm": found on mt2701 SoC. - "mediatek,mt6595-disp-pwm": found on mt6595 SoC. + - "mediatek,mt8167-disp-pwm", "mediatek,mt8173-disp-pwm": found on mt8167 SoC. - "mediatek,mt8173-disp-pwm": found on mt8173 SoC. - reg: physical base address and length of the controller's registers. - #pwm-cells: must be 2. See pwm.yaml in this directory for a description of diff --git a/Documentation/devicetree/bindings/rtc/rtc.yaml b/Documentation/devicetree/bindings/rtc/rtc.yaml index 8acd2de3de3a..d30dc045aac6 100644 --- a/Documentation/devicetree/bindings/rtc/rtc.yaml +++ b/Documentation/devicetree/bindings/rtc/rtc.yaml @@ -63,6 +63,11 @@ properties: description: Enables wake up of host system on alarm. + reset-source: + $ref: /schemas/types.yaml#/definitions/flag + description: + The RTC is able to reset the machine. + additionalProperties: true ... diff --git a/Documentation/devicetree/bindings/soc/microchip/atmel,at91rm9200-tcb.yaml b/Documentation/devicetree/bindings/soc/microchip/atmel,at91rm9200-tcb.yaml index 55fffae05dcf..597d67fba92f 100644 --- a/Documentation/devicetree/bindings/soc/microchip/atmel,at91rm9200-tcb.yaml +++ b/Documentation/devicetree/bindings/soc/microchip/atmel,at91rm9200-tcb.yaml @@ -59,6 +59,7 @@ patternProperties: items: - enum: - atmel,tcb-timer + - atmel,tcb-pwm - microchip,tcb-capture reg: description: @@ -68,10 +69,35 @@ patternProperties: minItems: 1 maxItems: 3 + required: + - compatible + - reg + + "^pwm@[0-2]$": + description: The timer block channels that are used as PWMs. + $ref: ../../pwm/pwm.yaml# + type: object + properties: + compatible: + const: atmel,tcb-pwm + reg: + description: + TCB channel to use for this PWM. + enum: [ 0, 1, 2 ] + + "#pwm-cells": + description: + The only third cell flag supported by this binding is + PWM_POLARITY_INVERTED. + const: 3 required: - compatible - reg + - "#pwm-cells" + + additionalProperties: false + allOf: - if: @@ -158,7 +184,13 @@ examples: compatible = "atmel,tcb-timer"; reg = <1>; }; - }; + + pwm@2 { + compatible = "atmel,tcb-pwm"; + reg = <2>; + #pwm-cells = <3>; + }; + }; /* TCB0 Capture with QDEC: */ timer@f800c000 { compatible = "atmel,at91rm9200-tcb", "simple-mfd", "syscon"; diff --git a/Documentation/devicetree/bindings/vendor-prefixes.yaml b/Documentation/devicetree/bindings/vendor-prefixes.yaml index ffaf833b97ee..041ae90b0d8f 100644 --- a/Documentation/devicetree/bindings/vendor-prefixes.yaml +++ b/Documentation/devicetree/bindings/vendor-prefixes.yaml @@ -187,6 +187,8 @@ patternProperties: description: CALAO Systems SAS "^calxeda,.*": description: Calxeda + "^canaan,.*": + description: Canaan, Inc. "^caninos,.*": description: Caninos Loucos Program "^capella,.*": diff --git a/Documentation/devicetree/bindings/watchdog/allwinner,sun4i-a10-wdt.yaml b/Documentation/devicetree/bindings/watchdog/allwinner,sun4i-a10-wdt.yaml index e8f226376108..5ac607de8be4 100644 --- a/Documentation/devicetree/bindings/watchdog/allwinner,sun4i-a10-wdt.yaml +++ b/Documentation/devicetree/bindings/watchdog/allwinner,sun4i-a10-wdt.yaml @@ -22,6 +22,9 @@ properties: - const: allwinner,sun50i-a64-wdt - const: allwinner,sun6i-a31-wdt - items: + - const: allwinner,sun50i-a100-wdt + - const: allwinner,sun6i-a31-wdt + - items: - const: allwinner,sun50i-h6-wdt - const: allwinner,sun6i-a31-wdt - items: diff --git a/Documentation/devicetree/bindings/watchdog/snps,dw-wdt.yaml b/Documentation/devicetree/bindings/watchdog/snps,dw-wdt.yaml index d9fc7bb851b1..f7ee9229c29f 100644 --- a/Documentation/devicetree/bindings/watchdog/snps,dw-wdt.yaml +++ b/Documentation/devicetree/bindings/watchdog/snps,dw-wdt.yaml @@ -14,7 +14,15 @@ maintainers: properties: compatible: - const: snps,dw-wdt + oneOf: + - const: snps,dw-wdt + - items: + - enum: + - rockchip,rk3066-wdt + - rockchip,rk3188-wdt + - rockchip,rk3288-wdt + - rockchip,rk3368-wdt + - const: snps,dw-wdt reg: maxItems: 1 diff --git a/Documentation/driver-api/dma-buf.rst b/Documentation/driver-api/dma-buf.rst index d6b2a195dbed..a2133d69872c 100644 --- a/Documentation/driver-api/dma-buf.rst +++ b/Documentation/driver-api/dma-buf.rst @@ -190,7 +190,7 @@ DMA Fence uABI/Sync File Indefinite DMA Fences ~~~~~~~~~~~~~~~~~~~~~ -At various times &dma_fence with an indefinite time until dma_fence_wait() +At various times struct dma_fence with an indefinite time until dma_fence_wait() finishes have been proposed. Examples include: * Future fences, used in HWC1 to signal when a buffer isn't used by the display diff --git a/Documentation/driver-api/driver-model/devres.rst b/Documentation/driver-api/driver-model/devres.rst index bb676570acc3..cd8b6e657b94 100644 --- a/Documentation/driver-api/driver-model/devres.rst +++ b/Documentation/driver-api/driver-model/devres.rst @@ -411,6 +411,12 @@ RESET devm_reset_control_get() devm_reset_controller_register() +RTC + devm_rtc_device_register() + devm_rtc_allocate_device() + devm_rtc_register_device() + devm_rtc_nvmem_register() + SERDEV devm_serdev_device_open() diff --git a/Documentation/driver-api/gpio/consumer.rst b/Documentation/driver-api/gpio/consumer.rst index 423492d125b9..173e4c7b037d 100644 --- a/Documentation/driver-api/gpio/consumer.rst +++ b/Documentation/driver-api/gpio/consumer.rst @@ -440,18 +440,20 @@ For details refer to Documentation/firmware-guide/acpi/gpio-properties.rst Interacting With the Legacy GPIO Subsystem ========================================== -Many kernel subsystems still handle GPIOs using the legacy integer-based -interface. Although it is strongly encouraged to upgrade them to the safer -descriptor-based API, the following two functions allow you to convert a GPIO -descriptor into the GPIO integer namespace and vice-versa:: +Many kernel subsystems and drivers still handle GPIOs using the legacy +integer-based interface. It is strongly recommended to update these to the new +gpiod interface. For cases where both interfaces need to be used, the following +two functions allow to convert a GPIO descriptor into the GPIO integer namespace +and vice-versa:: int desc_to_gpio(const struct gpio_desc *desc) struct gpio_desc *gpio_to_desc(unsigned gpio) -The GPIO number returned by desc_to_gpio() can be safely used as long as the -GPIO descriptor has not been freed. All the same, a GPIO number passed to -gpio_to_desc() must have been properly acquired, and usage of the returned GPIO -descriptor is only possible after the GPIO number has been released. +The GPIO number returned by desc_to_gpio() can safely be used as a parameter of +the gpio\_*() functions for as long as the GPIO descriptor `desc` is not freed. +All the same, a GPIO number passed to gpio_to_desc() must first be properly +acquired using e.g. gpio_request_one(), and the returned GPIO descriptor is only +considered valid until that GPIO number is released using gpio_free(). Freeing a GPIO obtained by one API with the other API is forbidden and an unchecked error. diff --git a/Documentation/driver-api/gpio/driver.rst b/Documentation/driver-api/gpio/driver.rst index 072a7455044e..0fb57e298b41 100644 --- a/Documentation/driver-api/gpio/driver.rst +++ b/Documentation/driver-api/gpio/driver.rst @@ -416,7 +416,8 @@ The preferred way to set up the helpers is to fill in the struct gpio_irq_chip inside struct gpio_chip before adding the gpio_chip. If you do this, the additional irq_chip will be set up by gpiolib at the same time as setting up the rest of the GPIO functionality. The following -is a typical example of a cascaded interrupt handler using gpio_irq_chip: +is a typical example of a chained cascaded interrupt handler using +the gpio_irq_chip: .. code-block:: c @@ -452,7 +453,46 @@ is a typical example of a cascaded interrupt handler using gpio_irq_chip: return devm_gpiochip_add_data(dev, &g->gc, g); -The helper support using hierarchical interrupt controllers as well. +The helper supports using threaded interrupts as well. Then you just request +the interrupt separately and go with it: + +.. code-block:: c + + /* Typical state container with dynamic irqchip */ + struct my_gpio { + struct gpio_chip gc; + struct irq_chip irq; + }; + + int irq; /* from platform etc */ + struct my_gpio *g; + struct gpio_irq_chip *girq; + + /* Set up the irqchip dynamically */ + g->irq.name = "my_gpio_irq"; + g->irq.irq_ack = my_gpio_ack_irq; + g->irq.irq_mask = my_gpio_mask_irq; + g->irq.irq_unmask = my_gpio_unmask_irq; + g->irq.irq_set_type = my_gpio_set_irq_type; + + ret = devm_request_threaded_irq(dev, irq, NULL, + irq_thread_fn, IRQF_ONESHOT, "my-chip", g); + if (ret < 0) + return ret; + + /* Get a pointer to the gpio_irq_chip */ + girq = &g->gc.irq; + girq->chip = &g->irq; + /* This will let us handle the parent IRQ in the driver */ + girq->parent_handler = NULL; + girq->num_parents = 0; + girq->parents = NULL; + girq->default_type = IRQ_TYPE_NONE; + girq->handler = handle_bad_irq; + + return devm_gpiochip_add_data(dev, &g->gc, g); + +The helper supports using hierarchical interrupt controllers as well. In this case the typical set-up will look like this: .. code-block:: c @@ -493,32 +533,13 @@ the parent hardware irq from a child (i.e. this gpio chip) hardware irq. As always it is good to look at examples in the kernel tree for advice on how to find the required pieces. -The old way of adding irqchips to gpiochips after registration is also still -available but we try to move away from this: - -- DEPRECATED: gpiochip_irqchip_add(): adds a chained cascaded irqchip to a - gpiochip. It will pass the struct gpio_chip* for the chip to all IRQ - callbacks, so the callbacks need to embed the gpio_chip in its state - container and obtain a pointer to the container using container_of(). - (See Documentation/driver-api/driver-model/design-patterns.rst) - -- gpiochip_irqchip_add_nested(): adds a nested cascaded irqchip to a gpiochip, - as discussed above regarding different types of cascaded irqchips. The - cascaded irq has to be handled by a threaded interrupt handler. - Apart from that it works exactly like the chained irqchip. - -- gpiochip_set_nested_irqchip(): sets up a nested cascaded irq handler for a - gpio_chip from a parent IRQ. As the parent IRQ has usually been - explicitly requested by the driver, this does very little more than - mark all the child IRQs as having the other IRQ as parent. - If there is a need to exclude certain GPIO lines from the IRQ domain handled by these helpers, we can set .irq.need_valid_mask of the gpiochip before devm_gpiochip_add_data() or gpiochip_add_data() is called. This allocates an .irq.valid_mask with as many bits set as there are GPIO lines in the chip, each bit representing line 0..n-1. Drivers can exclude GPIO lines by clearing bits -from this mask. The mask must be filled in before gpiochip_irqchip_add() or -gpiochip_irqchip_add_nested() is called. +from this mask. The mask can be filled in the init_valid_mask() callback +that is part of the struct gpio_irq_chip. To use the helpers please keep the following in mind: diff --git a/Documentation/features/debug/KASAN/arch-support.txt b/Documentation/features/debug/KASAN/arch-support.txt index c3fe9b266e7b..b2288dc14b72 100644 --- a/Documentation/features/debug/KASAN/arch-support.txt +++ b/Documentation/features/debug/KASAN/arch-support.txt @@ -8,7 +8,7 @@ ----------------------- | alpha: | TODO | | arc: | TODO | - | arm: | TODO | + | arm: | ok | | arm64: | ok | | c6x: | TODO | | csky: | TODO | diff --git a/Documentation/features/time/irq-time-acct/arch-support.txt b/Documentation/features/time/irq-time-acct/arch-support.txt index d9082b91f10e..6fc03deb1c38 100644 --- a/Documentation/features/time/irq-time-acct/arch-support.txt +++ b/Documentation/features/time/irq-time-acct/arch-support.txt @@ -23,7 +23,7 @@ | openrisc: | TODO | | parisc: | .. | | powerpc: | ok | - | riscv: | TODO | + | riscv: | ok | | s390: | .. | | sh: | TODO | | sparc: | .. | diff --git a/Documentation/filesystems/gfs2.rst b/Documentation/filesystems/gfs2.rst index 8d1ab589ce18..1bc48a13430c 100644 --- a/Documentation/filesystems/gfs2.rst +++ b/Documentation/filesystems/gfs2.rst @@ -1,53 +1,52 @@ .. SPDX-License-Identifier: GPL-2.0 -================== -Global File System -================== +==================== +Global File System 2 +==================== -https://fedorahosted.org/cluster/wiki/HomePage - -GFS is a cluster file system. It allows a cluster of computers to +GFS2 is a cluster file system. It allows a cluster of computers to simultaneously use a block device that is shared between them (with FC, -iSCSI, NBD, etc). GFS reads and writes to the block device like a local +iSCSI, NBD, etc). GFS2 reads and writes to the block device like a local file system, but also uses a lock module to allow the computers coordinate their I/O so file system consistency is maintained. One of the nifty -features of GFS is perfect consistency -- changes made to the file system +features of GFS2 is perfect consistency -- changes made to the file system on one machine show up immediately on all other machines in the cluster. -GFS uses interchangeable inter-node locking mechanisms, the currently +GFS2 uses interchangeable inter-node locking mechanisms, the currently supported mechanisms are: lock_nolock - - allows gfs to be used as a local file system + - allows GFS2 to be used as a local file system lock_dlm - - uses a distributed lock manager (dlm) for inter-node locking. + - uses the distributed lock manager (dlm) for inter-node locking. The dlm is found at linux/fs/dlm/ -Lock_dlm depends on user space cluster management systems found +lock_dlm depends on user space cluster management systems found at the URL above. -To use gfs as a local file system, no external clustering systems are +To use GFS2 as a local file system, no external clustering systems are needed, simply:: $ mkfs -t gfs2 -p lock_nolock -j 1 /dev/block_device $ mount -t gfs2 /dev/block_device /dir -If you are using Fedora, you need to install the gfs2-utils package -and, for lock_dlm, you will also need to install the cman package -and write a cluster.conf as per the documentation. For F17 and above -cman has been replaced by the dlm package. +The gfs2-utils package is required on all cluster nodes and, for lock_dlm, you +will also need the dlm and corosync user space utilities configured as per the +documentation. + +gfs2-utils can be found at https://pagure.io/gfs2-utils GFS2 is not on-disk compatible with previous versions of GFS, but it is pretty close. -The following man pages can be found at the URL above: +The following man pages are available from gfs2-utils: ============ ============================================= fsck.gfs2 to repair a filesystem gfs2_grow to expand a filesystem online gfs2_jadd to add journals to a filesystem online tunegfs2 to manipulate, examine and tune a filesystem - gfs2_convert to convert a gfs filesystem to gfs2 in-place + gfs2_convert to convert a gfs filesystem to GFS2 in-place mkfs.gfs2 to make a filesystem ============ ============================================= diff --git a/Documentation/kbuild/kconfig-language.rst b/Documentation/kbuild/kconfig-language.rst index 1cf1aebdd6cd..226ae072da7d 100644 --- a/Documentation/kbuild/kconfig-language.rst +++ b/Documentation/kbuild/kconfig-language.rst @@ -553,6 +553,41 @@ with "depends on m". E.g.:: limits FOO to module (=m) or disabled (=n). +Compile-testing +~~~~~~~~~~~~~~~ +If a config symbol has a dependency, but the code controlled by the config +symbol can still be compiled if the dependency is not met, it is encouraged to +increase build coverage by adding an "|| COMPILE_TEST" clause to the +dependency. This is especially useful for drivers for more exotic hardware, as +it allows continuous-integration systems to compile-test the code on a more +common system, and detect bugs that way. +Note that compile-tested code should avoid crashing when run on a system where +the dependency is not met. + +Architecture and platform dependencies +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Due to the presence of stubs, most drivers can now be compiled on most +architectures. However, this does not mean it makes sense to have all drivers +available everywhere, as the actual hardware may only exist on specific +architectures and platforms. This is especially true for on-SoC IP cores, +which may be limited to a specific vendor or SoC family. + +To prevent asking the user about drivers that cannot be used on the system(s) +the user is compiling a kernel for, and if it makes sense, config symbols +controlling the compilation of a driver should contain proper dependencies, +limiting the visibility of the symbol to (a superset of) the platform(s) the +driver can be used on. The dependency can be an architecture (e.g. ARM) or +platform (e.g. ARCH_OMAP4) dependency. This makes life simpler not only for +distro config owners, but also for every single developer or user who +configures a kernel. + +Such a dependency can be relaxed by combining it with the compile-testing rule +above, leading to: + + config FOO + bool "Support for foo hardware" + depends on ARCH_FOO_VENDOR || COMPILE_TEST + Kconfig recursive dependency limitations ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/Documentation/kbuild/kconfig-macro-language.rst b/Documentation/kbuild/kconfig-macro-language.rst index 8b413ef9603d..6163467f6ae4 100644 --- a/Documentation/kbuild/kconfig-macro-language.rst +++ b/Documentation/kbuild/kconfig-macro-language.rst @@ -97,7 +97,7 @@ Like Make, Kconfig provides several built-in functions. Every function takes a particular number of arguments. In Make, every built-in function takes at least one argument. Kconfig allows -zero argument for built-in functions, such as $(fileno), $(lineno). You could +zero argument for built-in functions, such as $(filename), $(lineno). You could consider those as "built-in variable", but it is just a matter of how we call it after all. Let's say "built-in function" here to refer to natively supported functionality. diff --git a/Documentation/kbuild/makefiles.rst b/Documentation/kbuild/makefiles.rst index 0d5dd5413af0..d36768cf1250 100644 --- a/Documentation/kbuild/makefiles.rst +++ b/Documentation/kbuild/makefiles.rst @@ -15,13 +15,15 @@ This document describes the Linux kernel Makefiles. --- 3.4 Objects which export symbols --- 3.5 Library file goals - lib-y --- 3.6 Descending down in directories - --- 3.7 Compilation flags - --- 3.8 <deleted> - --- 3.9 Dependency tracking - --- 3.10 Special Rules - --- 3.11 $(CC) support functions - --- 3.12 $(LD) support functions - --- 3.13 Script Invocation + --- 3.7 Non-builtin vmlinux targets - extra-y + --- 3.8 Always built goals - always-y + --- 3.9 Compilation flags + --- 3.10 Dependency tracking + --- 3.11 Custom Rules + --- 3.12 Command change detection + --- 3.13 $(CC) support functions + --- 3.14 $(LD) support functions + --- 3.15 Script Invocation === 4 Host Program support --- 4.1 Simple Host Program @@ -46,7 +48,7 @@ This document describes the Linux kernel Makefiles. --- 7.5 Architecture-specific boot images --- 7.6 Building non-kbuild targets --- 7.7 Commands useful for building a boot image - --- 7.8 Custom kbuild commands + --- 7.8 <deleted> --- 7.9 Preprocessing linker scripts --- 7.10 Generic header files --- 7.11 Post-link pass @@ -67,11 +69,11 @@ This document describes the Linux kernel Makefiles. The Makefiles have five parts:: - Makefile the top Makefile. - .config the kernel configuration file. - arch/$(ARCH)/Makefile the arch Makefile. - scripts/Makefile.* common rules etc. for all kbuild Makefiles. - kbuild Makefiles there are about 500 of these. + Makefile the top Makefile. + .config the kernel configuration file. + arch/$(SRCARCH)/Makefile the arch Makefile. + scripts/Makefile.* common rules etc. for all kbuild Makefiles. + kbuild Makefiles exist in every subdirectory The top Makefile reads the .config file, which comes from the kernel configuration process. @@ -82,7 +84,7 @@ It builds these goals by recursively descending into the subdirectories of the kernel source tree. The list of subdirectories which are visited depends upon the kernel configuration. The top Makefile textually includes an arch Makefile -with the name arch/$(ARCH)/Makefile. The arch Makefile supplies +with the name arch/$(SRCARCH)/Makefile. The arch Makefile supplies architecture-specific information to the top Makefile. Each subdirectory has a kbuild Makefile which carries out the commands @@ -278,7 +280,7 @@ more details, with real examples. actually recognize that there is a lib.a being built, the directory shall be listed in libs-y. - See also "6.4 List directories to visit when descending". + See also "7.4 List directories to visit when descending". Use of lib-y is normally restricted to `lib/` and `arch/*/lib`. @@ -317,11 +319,79 @@ more details, with real examples. that directory specifies obj-y, those objects will be left orphan. It is very likely a bug of the Makefile or of dependencies in Kconfig. + Kbuild also supports dedicated syntax, subdir-y and subdir-m, for + descending into subdirectories. It is a good fit when you know they + do not contain kernel-space objects at all. A typical usage is to let + Kbuild descend into subdirectories to build tools. + + Examples:: + + # scripts/Makefile + subdir-$(CONFIG_GCC_PLUGINS) += gcc-plugins + subdir-$(CONFIG_MODVERSIONS) += genksyms + subdir-$(CONFIG_SECURITY_SELINUX) += selinux + + Unlike obj-y/m, subdir-y/m does not need the trailing slash since this + syntax is always used for directories. + It is good practice to use a `CONFIG_` variable when assigning directory names. This allows kbuild to totally skip the directory if the corresponding `CONFIG_` option is neither 'y' nor 'm'. -3.7 Compilation flags +3.7 Non-builtin vmlinux targets - extra-y +----------------------------------------- + + extra-y specifies targets which are needed for building vmlinux, + but not combined into built-in.a. + + Examples are: + + 1) head objects + + Some objects must be placed at the head of vmlinux. They are + directly linked to vmlinux without going through built-in.a + A typical use-case is an object that contains the entry point. + + arch/$(SRCARCH)/Makefile should specify such objects as head-y. + + Discussion: + Given that we can control the section order in the linker script, + why do we need head-y? + + 2) vmlinux linker script + + The linker script for vmlinux is located at + arch/$(SRCARCH)/kernel/vmlinux.lds + + Example:: + + # arch/x86/kernel/Makefile + extra-y := head_$(BITS).o + extra-y += head$(BITS).o + extra-y += ebda.o + extra-y += platform-quirks.o + extra-y += vmlinux.lds + + $(extra-y) should only contain targets needed for vmlinux. + + Kbuild skips extra-y when vmlinux is apparently not a final goal. + (e.g. 'make modules', or building external modules) + + If you intend to build targets unconditionally, always-y (explained + in the next section) is the correct syntax to use. + +3.8 Always built goals - always-y +--------------------------------- + + always-y specifies targets which are literally always built when + Kbuild visits the Makefile. + + Example:: + # ./Kbuild + offsets-file := include/generated/asm-offsets.h + always-y += $(offsets-file) + +3.9 Compilation flags --------------------- ccflags-y, asflags-y and ldflags-y @@ -410,8 +480,8 @@ more details, with real examples. AFLAGS_iwmmxt.o := -Wa,-mcpu=iwmmxt -3.9 Dependency tracking ------------------------ +3.10 Dependency tracking +------------------------ Kbuild tracks dependencies on the following: @@ -422,21 +492,21 @@ more details, with real examples. Thus, if you change an option to $(CC) all affected files will be re-compiled. -3.10 Special Rules ------------------- +3.11 Custom Rules +----------------- - Special rules are used when the kbuild infrastructure does + Custom rules are used when the kbuild infrastructure does not provide the required support. A typical example is header files generated during the build process. Another example are the architecture-specific Makefiles which - need special rules to prepare boot images etc. + need custom rules to prepare boot images etc. - Special rules are written as normal Make rules. + Custom rules are written as normal Make rules. Kbuild is not executing in the directory where the Makefile is - located, so all special rules shall provide a relative + located, so all custom rules shall use a relative path to prerequisite files and target files. - Two variables are used when defining special rules: + Two variables are used when defining custom rules: $(src) $(src) is a relative path which points to the directory @@ -454,7 +524,7 @@ more details, with real examples. $(obj)/53c8xx_d.h: $(src)/53c7,8xx.scr $(src)/script_asm.pl $(CPP) -DCHIP=810 - < $< | ... $(src)/script_asm.pl - This is a special rule, following the normal syntax + This is a custom rule, following the normal syntax required by make. The target file depends on two prerequisite files. References @@ -471,13 +541,81 @@ more details, with real examples. Example:: - #arch/blackfin/boot/Makefile - $(obj)/vmImage: $(obj)/vmlinux.gz - $(call if_changed,uimage) - @$(kecho) 'Kernel: $@ is ready' + # arch/arm/Makefile + $(BOOT_TARGETS): vmlinux + $(Q)$(MAKE) $(build)=$(boot) MACHINE=$(MACHINE) $(boot)/$@ + @$(kecho) ' Kernel: $(boot)/$@ is ready' + + When kbuild is executing with KBUILD_VERBOSE=0, then only a shorthand + of a command is normally displayed. + To enable this behaviour for custom commands kbuild requires + two variables to be set:: + + quiet_cmd_<command> - what shall be echoed + cmd_<command> - the command to execute + + Example:: + + # lib/Makefile + quiet_cmd_crc32 = GEN $@ + cmd_crc32 = $< > $@ + + $(obj)/crc32table.h: $(obj)/gen_crc32table + $(call cmd,crc32) + + When updating the $(obj)/crc32table.h target, the line: + + GEN lib/crc32table.h + + will be displayed with "make KBUILD_VERBOSE=0". + +3.12 Command change detection +----------------------------- + + When the rule is evaluated, timestamps are compared between the target + and its prerequisite files. GNU Make updates the target when any of the + prerequisites is newer than that. + + The target should be rebuilt also when the command line has changed + since the last invocation. This is not supported by Make itself, so + Kbuild achieves this by a kind of meta-programming. + + if_changed is the macro used for this purpose, in the following form:: + + quiet_cmd_<command> = ... + cmd_<command> = ... + + <target>: <source(s)> FORCE + $(call if_changed,<command>) + + Any target that utilizes if_changed must be listed in $(targets), + otherwise the command line check will fail, and the target will + always be built. + + If the target is already listed in the recognized syntax such as + obj-y/m, lib-y/m, extra-y/m, always-y/m, hostprogs, userprogs, Kbuild + automatically adds it to $(targets). Otherwise, the target must be + explicitly added to $(targets). + + Assignments to $(targets) are without $(obj)/ prefix. if_changed may be + used in conjunction with custom rules as defined in "3.9 Custom Rules". + + Note: It is a typical mistake to forget the FORCE prerequisite. + Another common pitfall is that whitespace is sometimes significant; for + instance, the below will fail (note the extra space after the comma):: + + target: source(s) FORCE + + **WRONG!** $(call if_changed, objcopy) + Note: + if_changed should not be used more than once per target. + It stores the executed command in a corresponding .cmd + file and multiple calls would result in overwrites and + unwanted results when the target is up to date and only the + tests on changed commands trigger execution of commands. -3.11 $(CC) support functions +3.13 $(CC) support functions ---------------------------- The kernel may be built with several different versions of @@ -592,7 +730,7 @@ more details, with real examples. endif endif -3.12 $(LD) support functions +3.14 $(LD) support functions ---------------------------- ld-option @@ -606,7 +744,7 @@ more details, with real examples. #Makefile LDFLAGS_vmlinux += $(call ld-option, -X) -3.13 Script invocation +3.15 Script invocation ---------------------- Make rules may invoke scripts to build the kernel. The rules shall @@ -744,7 +882,7 @@ Both possibilities are described in the following. as a prerequisite. This is possible in two ways: - (1) List the prerequisite explicitly in a special rule. + (1) List the prerequisite explicitly in a custom rule. Example:: @@ -755,11 +893,11 @@ Both possibilities are described in the following. The target $(obj)/devlist.h will not be built before $(obj)/gen-devlist is updated. Note that references to - the host programs in special rules must be prefixed with $(obj). + the host programs in custom rules must be prefixed with $(obj). (2) Use always-y - When there is no suitable special rule, and the host program + When there is no suitable custom rule, and the host program shall be built when a makefile is entered, the always-y variable shall be used. @@ -933,7 +1071,7 @@ When "make clean" is executed, make will descend down in arch/x86/boot, and clean as usual. The Makefile located in arch/x86/boot/ may use the subdir- trick to descend further down. -Note 1: arch/$(ARCH)/Makefile cannot use "subdir-", because that file is +Note 1: arch/$(SRCARCH)/Makefile cannot use "subdir-", because that file is included in the top level makefile, and the kbuild infrastructure is not operational at that point. @@ -946,9 +1084,9 @@ be visited during "make clean". The top level Makefile sets up the environment and does the preparation, before starting to descend down in the individual directories. The top level makefile contains the generic part, whereas -arch/$(ARCH)/Makefile contains what is required to set up kbuild +arch/$(SRCARCH)/Makefile contains what is required to set up kbuild for said architecture. -To do so, arch/$(ARCH)/Makefile sets up a number of variables and defines +To do so, arch/$(SRCARCH)/Makefile sets up a number of variables and defines a few targets. When kbuild executes, the following steps are followed (roughly): @@ -956,14 +1094,14 @@ When kbuild executes, the following steps are followed (roughly): 1) Configuration of the kernel => produce .config 2) Store kernel version in include/linux/version.h 3) Updating all other prerequisites to the target prepare: - - Additional prerequisites are specified in arch/$(ARCH)/Makefile + - Additional prerequisites are specified in arch/$(SRCARCH)/Makefile 4) Recursively descend down in all directories listed in init-* core* drivers-* net-* libs-* and build all targets. - - The values of the above variables are expanded in arch/$(ARCH)/Makefile. + - The values of the above variables are expanded in arch/$(SRCARCH)/Makefile. 5) All object files are then linked and the resulting file vmlinux is located at the root of the obj tree. The very first objects linked are listed in head-y, assigned by - arch/$(ARCH)/Makefile. + arch/$(SRCARCH)/Makefile. 6) Finally, the architecture-specific part does any required post processing and builds the final bootimage. - This includes building boot records @@ -1154,7 +1292,7 @@ When kbuild executes, the following steps are followed (roughly): machinery is all architecture-independent. - head-y, init-y, core-y, libs-y, drivers-y, net-y + head-y, core-y, libs-y, drivers-y $(head-y) lists objects to be linked first in vmlinux. $(libs-y) lists directories where a lib.a archive can be located. @@ -1162,23 +1300,24 @@ When kbuild executes, the following steps are followed (roughly): The rest list directories where a built-in.a object file can be located. - $(init-y) objects will be located after $(head-y). - Then the rest follows in this order: - $(core-y), $(libs-y), $(drivers-y) and $(net-y). + $(core-y), $(libs-y), $(drivers-y) The top level Makefile defines values for all generic directories, - and arch/$(ARCH)/Makefile only adds architecture-specific + and arch/$(SRCARCH)/Makefile only adds architecture-specific directories. Example:: - #arch/sparc64/Makefile - core-y += arch/sparc64/kernel/ - libs-y += arch/sparc64/prom/ arch/sparc64/lib/ - drivers-$(CONFIG_OPROFILE) += arch/sparc64/oprofile/ + # arch/sparc/Makefile + core-y += arch/sparc/ + + libs-y += arch/sparc/prom/ + libs-y += arch/sparc/lib/ + drivers-$(CONFIG_PM) += arch/sparc/power/ + drivers-$(CONFIG_OPROFILE) += arch/sparc/oprofile/ 7.5 Architecture-specific boot images ------------------------------------- @@ -1189,15 +1328,15 @@ When kbuild executes, the following steps are followed (roughly): The actual goals are not standardized across architectures. It is common to locate any additional processing in a boot/ - directory below arch/$(ARCH)/. + directory below arch/$(SRCARCH)/. Kbuild does not provide any smart way to support building a - target specified in boot/. Therefore arch/$(ARCH)/Makefile shall + target specified in boot/. Therefore arch/$(SRCARCH)/Makefile shall call make manually to build a target in boot/. The recommended approach is to include shortcuts in - arch/$(ARCH)/Makefile, and use the full path when calling down - into the arch/$(ARCH)/boot/Makefile. + arch/$(SRCARCH)/Makefile, and use the full path when calling down + into the arch/$(SRCARCH)/boot/Makefile. Example:: @@ -1217,7 +1356,7 @@ When kbuild executes, the following steps are followed (roughly): #arch/x86/Makefile define archhelp - echo '* bzImage - Image (arch/$(ARCH)/boot/bzImage)' + echo '* bzImage - Compressed kernel image (arch/x86/boot/bzImage)' endif When make is executed without arguments, the first goal encountered @@ -1235,71 +1374,12 @@ When kbuild executes, the following steps are followed (roughly): When "make" is executed without arguments, bzImage will be built. -7.6 Building non-kbuild targets -------------------------------- - - extra-y - extra-y specifies additional targets created in the current - directory, in addition to any targets specified by `obj-*`. - - Listing all targets in extra-y is required for two purposes: - - 1) Enable kbuild to check changes in command lines - - - When $(call if_changed,xxx) is used - - 2) kbuild knows what files to delete during "make clean" - - Example:: - - #arch/x86/kernel/Makefile - extra-y := head.o init_task.o - - In this example, extra-y is used to list object files that - shall be built, but shall not be linked as part of built-in.a. - 7.7 Commands useful for building a boot image --------------------------------------------- Kbuild provides a few macros that are useful when building a boot image. - if_changed - if_changed is the infrastructure used for the following commands. - - Usage:: - - target: source(s) FORCE - $(call if_changed,ld/objcopy/gzip/...) - - When the rule is evaluated, it is checked to see if any files - need an update, or the command line has changed since the last - invocation. The latter will force a rebuild if any options - to the executable have changed. - Any target that utilises if_changed must be listed in $(targets), - otherwise the command line check will fail, and the target will - always be built. - Assignments to $(targets) are without $(obj)/ prefix. - if_changed may be used in conjunction with custom commands as - defined in 7.8 "Custom kbuild commands". - - Note: It is a typical mistake to forget the FORCE prerequisite. - Another common pitfall is that whitespace is sometimes - significant; for instance, the below will fail (note the extra space - after the comma):: - - target: source(s) FORCE - - **WRONG!** $(call if_changed, ld/objcopy/gzip/...) - - Note: - if_changed should not be used more than once per target. - It stores the executed command in a corresponding .cmd - - file and multiple calls would result in overwrites and - unwanted results when the target is up to date and only the - tests on changed commands trigger execution of commands. - ld Link target. Often, LDFLAGS_$@ is used to set specific options to ld. @@ -1332,7 +1412,7 @@ When kbuild executes, the following steps are followed (roughly): objcopy Copy binary. Uses OBJCOPYFLAGS usually specified in - arch/$(ARCH)/Makefile. + arch/$(SRCARCH)/Makefile. OBJCOPYFLAGS_$@ may be used to set additional options. gzip @@ -1361,41 +1441,11 @@ When kbuild executes, the following steps are followed (roughly): targets += $(dtb-y) DTC_FLAGS ?= -p 1024 -7.8 Custom kbuild commands --------------------------- - - When kbuild is executing with KBUILD_VERBOSE=0, then only a shorthand - of a command is normally displayed. - To enable this behaviour for custom commands kbuild requires - two variables to be set:: - - quiet_cmd_<command> - what shall be echoed - cmd_<command> - the command to execute - - Example:: - - # - quiet_cmd_image = BUILD $@ - cmd_image = $(obj)/tools/build $(BUILDFLAGS) \ - $(obj)/vmlinux.bin > $@ - - targets += bzImage - $(obj)/bzImage: $(obj)/vmlinux.bin $(obj)/tools/build FORCE - $(call if_changed,image) - @echo 'Kernel: $@ is ready' - - When updating the $(obj)/bzImage target, the line: - - BUILD arch/x86/boot/bzImage - - will be displayed with "make KBUILD_VERBOSE=0". - - 7.9 Preprocessing linker scripts -------------------------------- When the vmlinux image is built, the linker script - arch/$(ARCH)/kernel/vmlinux.lds is used. + arch/$(SRCARCH)/kernel/vmlinux.lds is used. The script is a preprocessed variant of the file vmlinux.lds.S located in the same directory. kbuild knows .lds files and includes a rule `*lds.S` -> `*lds`. @@ -1405,9 +1455,6 @@ When kbuild executes, the following steps are followed (roughly): #arch/x86/kernel/Makefile extra-y := vmlinux.lds - #Makefile - export CPPFLAGS_vmlinux.lds += -P -C -U$(ARCH) - The assignment to extra-y is used to tell kbuild to build the target vmlinux.lds. The assignment to $(CPPFLAGS_vmlinux.lds) tells kbuild to use the @@ -1481,7 +1528,7 @@ See subsequent chapter for the syntax of the Kbuild file. If an architecture uses a verbatim copy of a header from include/asm-generic then this is listed in the file - arch/$(ARCH)/include/asm/Kbuild like this: + arch/$(SRCARCH)/include/asm/Kbuild like this: Example:: @@ -1492,7 +1539,7 @@ See subsequent chapter for the syntax of the Kbuild file. During the prepare phase of the build a wrapper include file is generated in the directory:: - arch/$(ARCH)/include/generated/asm + arch/$(SRCARCH)/include/generated/asm When a header is exported where the architecture uses the generic header a similar wrapper is generated as part @@ -1527,8 +1574,8 @@ See subsequent chapter for the syntax of the Kbuild file. to define the minimum set of ASM headers that all architectures must have. This works like optional generic-y. If a mandatory header is missing - in arch/$(ARCH)/include/(uapi/)/asm, Kbuild will automatically generate - a wrapper of the asm-generic one. + in arch/$(SRCARCH)/include/(uapi/)/asm, Kbuild will automatically + generate a wrapper of the asm-generic one. 9 Kbuild Variables ================== @@ -1564,6 +1611,16 @@ The top Makefile exports the following variables: make ARCH=m68k ... + SRCARCH + This variable specifies the directory in arch/ to build. + + ARCH and SRCARCH may not necessarily match. A couple of arch + directories are biarch, that is, a single `arch/*/` directory supports + both 32-bit and 64-bit. + + For example, you can pass in ARCH=i386, ARCH=x86_64, or ARCH=x86. + For all of them, SRCARCH=x86 because arch/x86/ supports both i386 and + x86_64. INSTALL_PATH This variable defines a place for the arch Makefiles to install diff --git a/Documentation/kbuild/modules.rst b/Documentation/kbuild/modules.rst index 85ccc878895e..a1f3eb7a43e2 100644 --- a/Documentation/kbuild/modules.rst +++ b/Documentation/kbuild/modules.rst @@ -332,7 +332,7 @@ according to the following rule: There are two notable exceptions to this rule: larger subsystems have their own directory under include/, such as include/scsi; and architecture specific headers are located - under arch/$(ARCH)/include/. + under arch/$(SRCARCH)/include/. 4.1 Kernel Includes ------------------- diff --git a/Documentation/sphinx/parse-headers.pl b/Documentation/sphinx/parse-headers.pl index 1910079f984f..b063f2f1cfb2 100755 --- a/Documentation/sphinx/parse-headers.pl +++ b/Documentation/sphinx/parse-headers.pl @@ -1,4 +1,4 @@ -#!/usr/bin/perl +#!/usr/bin/env perl use strict; use Text::Tabs; use Getopt::Long; diff --git a/Documentation/target/tcm_mod_builder.py b/Documentation/target/tcm_mod_builder.py index 1548d8420499..54492aa813b9 100755 --- a/Documentation/target/tcm_mod_builder.py +++ b/Documentation/target/tcm_mod_builder.py @@ -1,4 +1,4 @@ -#!/usr/bin/python +#!/usr/bin/env python # The TCM v4 multi-protocol fabric module generation script for drivers/target/$NEW_MOD # # Copyright (c) 2010 Rising Tide Systems diff --git a/Documentation/trace/postprocess/decode_msr.py b/Documentation/trace/postprocess/decode_msr.py index 0ab40e0db580..aa9cc7abd5c2 100644 --- a/Documentation/trace/postprocess/decode_msr.py +++ b/Documentation/trace/postprocess/decode_msr.py @@ -1,4 +1,4 @@ -#!/usr/bin/python +#!/usr/bin/env python # add symbolic names to read_msr / write_msr in trace # decode_msr msr-index.h < trace import sys diff --git a/Documentation/trace/postprocess/trace-pagealloc-postprocess.pl b/Documentation/trace/postprocess/trace-pagealloc-postprocess.pl index 0a120aae33ce..b9b7d80c2f9d 100644 --- a/Documentation/trace/postprocess/trace-pagealloc-postprocess.pl +++ b/Documentation/trace/postprocess/trace-pagealloc-postprocess.pl @@ -1,4 +1,4 @@ -#!/usr/bin/perl +#!/usr/bin/env perl # This is a POC (proof of concept or piece of crap, take your pick) for reading the # text representation of trace output related to page allocation. It makes an attempt # to extract some high-level information on what is going on. The accuracy of the parser diff --git a/Documentation/trace/postprocess/trace-vmscan-postprocess.pl b/Documentation/trace/postprocess/trace-vmscan-postprocess.pl index 995da15b16ca..2f4e39875fb3 100644 --- a/Documentation/trace/postprocess/trace-vmscan-postprocess.pl +++ b/Documentation/trace/postprocess/trace-vmscan-postprocess.pl @@ -1,4 +1,4 @@ -#!/usr/bin/perl +#!/usr/bin/env perl # This is a POC for reading the text representation of trace output related to # page reclaim. It makes an attempt to extract some high-level information on # what is going on. The accuracy of the parser may vary diff --git a/Documentation/virt/kvm/api.rst b/Documentation/virt/kvm/api.rst index e00a66d72372..70254eaa5229 100644 --- a/Documentation/virt/kvm/api.rst +++ b/Documentation/virt/kvm/api.rst @@ -262,6 +262,18 @@ The KVM_RUN ioctl (cf.) communicates with userspace via a shared memory region. This ioctl returns the size of that region. See the KVM_RUN documentation for details. +Besides the size of the KVM_RUN communication region, other areas of +the VCPU file descriptor can be mmap-ed, including: + +- if KVM_CAP_COALESCED_MMIO is available, a page at + KVM_COALESCED_MMIO_PAGE_OFFSET * PAGE_SIZE; for historical reasons, + this page is included in the result of KVM_GET_VCPU_MMAP_SIZE. + KVM_CAP_COALESCED_MMIO is not documented yet. + +- if KVM_CAP_DIRTY_LOG_RING is available, a number of pages at + KVM_DIRTY_LOG_PAGE_OFFSET * PAGE_SIZE. For more information on + KVM_CAP_DIRTY_LOG_RING, see section 8.3. + 4.6 KVM_SET_MEMORY_REGION ------------------------- @@ -4455,9 +4467,9 @@ that KVM_CAP_MANUAL_DIRTY_LOG_PROTECT2 is present. 4.118 KVM_GET_SUPPORTED_HV_CPUID -------------------------------- -:Capability: KVM_CAP_HYPERV_CPUID +:Capability: KVM_CAP_HYPERV_CPUID (vcpu), KVM_CAP_SYS_HYPERV_CPUID (system) :Architectures: x86 -:Type: vcpu ioctl +:Type: system ioctl, vcpu ioctl :Parameters: struct kvm_cpuid2 (in/out) :Returns: 0 on success, -1 on error @@ -4502,9 +4514,6 @@ Currently, the following list of CPUID leaves are returned: - HYPERV_CPUID_SYNDBG_INTERFACE - HYPERV_CPUID_SYNDBG_PLATFORM_CAPABILITIES -HYPERV_CPUID_NESTED_FEATURES leaf is only exposed when Enlightened VMCS was -enabled on the corresponding vCPU (KVM_CAP_HYPERV_ENLIGHTENED_VMCS). - Userspace invokes KVM_GET_SUPPORTED_HV_CPUID by passing a kvm_cpuid2 structure with the 'nent' field indicating the number of entries in the variable-size array 'entries'. If the number of entries is too low to describe all Hyper-V @@ -4515,6 +4524,15 @@ number of valid entries in the 'entries' array, which is then filled. 'index' and 'flags' fields in 'struct kvm_cpuid_entry2' are currently reserved, userspace should not expect to get any particular value there. +Note, vcpu version of KVM_GET_SUPPORTED_HV_CPUID is currently deprecated. Unlike +system ioctl which exposes all supported feature bits unconditionally, vcpu +version has the following quirks: +- HYPERV_CPUID_NESTED_FEATURES leaf and HV_X64_ENLIGHTENED_VMCS_RECOMMENDED + feature bit are only exposed when Enlightened VMCS was previously enabled + on the corresponding vCPU (KVM_CAP_HYPERV_ENLIGHTENED_VMCS). +- HV_STIMER_DIRECT_MODE_AVAILABLE bit is only exposed with in-kernel LAPIC. + (presumes KVM_CREATE_IRQCHIP has already been called). + 4.119 KVM_ARM_VCPU_FINALIZE --------------------------- @@ -6390,3 +6408,91 @@ When enabled, KVM will disable paravirtual features provided to the guest according to the bits in the KVM_CPUID_FEATURES CPUID leaf (0x40000001). Otherwise, a guest may use the paravirtual features regardless of what has actually been exposed through the CPUID leaf. + + +8.29 KVM_CAP_DIRTY_LOG_RING +--------------------------- + +:Architectures: x86 +:Parameters: args[0] - size of the dirty log ring + +KVM is capable of tracking dirty memory using ring buffers that are +mmaped into userspace; there is one dirty ring per vcpu. + +The dirty ring is available to userspace as an array of +``struct kvm_dirty_gfn``. Each dirty entry it's defined as:: + + struct kvm_dirty_gfn { + __u32 flags; + __u32 slot; /* as_id | slot_id */ + __u64 offset; + }; + +The following values are defined for the flags field to define the +current state of the entry:: + + #define KVM_DIRTY_GFN_F_DIRTY BIT(0) + #define KVM_DIRTY_GFN_F_RESET BIT(1) + #define KVM_DIRTY_GFN_F_MASK 0x3 + +Userspace should call KVM_ENABLE_CAP ioctl right after KVM_CREATE_VM +ioctl to enable this capability for the new guest and set the size of +the rings. Enabling the capability is only allowed before creating any +vCPU, and the size of the ring must be a power of two. The larger the +ring buffer, the less likely the ring is full and the VM is forced to +exit to userspace. The optimal size depends on the workload, but it is +recommended that it be at least 64 KiB (4096 entries). + +Just like for dirty page bitmaps, the buffer tracks writes to +all user memory regions for which the KVM_MEM_LOG_DIRTY_PAGES flag was +set in KVM_SET_USER_MEMORY_REGION. Once a memory region is registered +with the flag set, userspace can start harvesting dirty pages from the +ring buffer. + +An entry in the ring buffer can be unused (flag bits ``00``), +dirty (flag bits ``01``) or harvested (flag bits ``1X``). The +state machine for the entry is as follows:: + + dirtied harvested reset + 00 -----------> 01 -------------> 1X -------+ + ^ | + | | + +------------------------------------------+ + +To harvest the dirty pages, userspace accesses the mmaped ring buffer +to read the dirty GFNs. If the flags has the DIRTY bit set (at this stage +the RESET bit must be cleared), then it means this GFN is a dirty GFN. +The userspace should harvest this GFN and mark the flags from state +``01b`` to ``1Xb`` (bit 0 will be ignored by KVM, but bit 1 must be set +to show that this GFN is harvested and waiting for a reset), and move +on to the next GFN. The userspace should continue to do this until the +flags of a GFN have the DIRTY bit cleared, meaning that it has harvested +all the dirty GFNs that were available. + +It's not necessary for userspace to harvest the all dirty GFNs at once. +However it must collect the dirty GFNs in sequence, i.e., the userspace +program cannot skip one dirty GFN to collect the one next to it. + +After processing one or more entries in the ring buffer, userspace +calls the VM ioctl KVM_RESET_DIRTY_RINGS to notify the kernel about +it, so that the kernel will reprotect those collected GFNs. +Therefore, the ioctl must be called *before* reading the content of +the dirty pages. + +The dirty ring can get full. When it happens, the KVM_RUN of the +vcpu will return with exit reason KVM_EXIT_DIRTY_LOG_FULL. + +The dirty ring interface has a major difference comparing to the +KVM_GET_DIRTY_LOG interface in that, when reading the dirty ring from +userspace, it's still possible that the kernel has not yet flushed the +processor's dirty page buffers into the kernel buffer (with dirty bitmaps, the +flushing is done by the KVM_GET_DIRTY_LOG ioctl). To achieve that, one +needs to kick the vcpu out of KVM_RUN using a signal. The resulting +vmexit ensures that all dirty GFNs are flushed to the dirty rings. + +NOTE: the capability KVM_CAP_DIRTY_LOG_RING and the corresponding +ioctl KVM_RESET_DIRTY_RINGS are mutual exclusive to the existing ioctls +KVM_GET_DIRTY_LOG and KVM_CLEAR_DIRTY_LOG. After enabling +KVM_CAP_DIRTY_LOG_RING with an acceptable dirty ring size, the virtual +machine will switch to ring-buffer dirty page tracking and further +KVM_GET_DIRTY_LOG or KVM_CLEAR_DIRTY_LOG ioctls will fail. diff --git a/Documentation/virt/kvm/arm/pvtime.rst b/Documentation/virt/kvm/arm/pvtime.rst index 687b60d76ca9..392521af7c90 100644 --- a/Documentation/virt/kvm/arm/pvtime.rst +++ b/Documentation/virt/kvm/arm/pvtime.rst @@ -19,8 +19,8 @@ Two new SMCCC compatible hypercalls are defined: These are only available in the SMC64/HVC64 calling convention as paravirtualized time is not available to 32 bit Arm guests. The existence of -the PV_FEATURES hypercall should be probed using the SMCCC 1.1 ARCH_FEATURES -mechanism before calling it. +the PV_TIME_FEATURES hypercall should be probed using the SMCCC 1.1 +ARCH_FEATURES mechanism before calling it. PV_TIME_FEATURES ============= ======== ========== |