diff options
Diffstat (limited to 'Documentation')
110 files changed, 2947 insertions, 1345 deletions
diff --git a/Documentation/ABI/testing/sysfs-bus-nvdimm b/Documentation/ABI/testing/sysfs-bus-nvdimm index bff84a16812a..1c1f5acbf53d 100644 --- a/Documentation/ABI/testing/sysfs-bus-nvdimm +++ b/Documentation/ABI/testing/sysfs-bus-nvdimm @@ -6,3 +6,38 @@ Description: The libnvdimm sub-system implements a common sysfs interface for platform nvdimm resources. See Documentation/driver-api/nvdimm/. + +What: /sys/bus/event_source/devices/nmemX/format +Date: February 2022 +KernelVersion: 5.18 +Contact: Kajol Jain <kjain@linux.ibm.com> +Description: (RO) Attribute group to describe the magic bits + that go into perf_event_attr.config for a particular pmu. + (See ABI/testing/sysfs-bus-event_source-devices-format). + + Each attribute under this group defines a bit range of the + perf_event_attr.config. Supported attribute is listed + below:: + event = "config:0-4" - event ID + + For example:: + ctl_res_cnt = "event=0x1" + +What: /sys/bus/event_source/devices/nmemX/events +Date: February 2022 +KernelVersion: 5.18 +Contact: Kajol Jain <kjain@linux.ibm.com> +Description: (RO) Attribute group to describe performance monitoring events + for the nvdimm memory device. Each attribute in this group + describes a single performance monitoring event supported by + this nvdimm pmu. The name of the file is the name of the event. + (See ABI/testing/sysfs-bus-event_source-devices-events). A + listing of the events supported by a given nvdimm provider type + can be found in Documentation/driver-api/nvdimm/$provider. + +What: /sys/bus/event_source/devices/nmemX/cpumask +Date: February 2022 +KernelVersion: 5.18 +Contact: Kajol Jain <kjain@linux.ibm.com> +Description: (RO) This sysfs file exposes the cpumask which is designated to + to retrieve nvdimm pmu event counter data. diff --git a/Documentation/admin-guide/kernel-parameters.txt b/Documentation/admin-guide/kernel-parameters.txt index b7ccaa2ea867..3f1cc5e317ed 100644 --- a/Documentation/admin-guide/kernel-parameters.txt +++ b/Documentation/admin-guide/kernel-parameters.txt @@ -4427,6 +4427,12 @@ fully seed the kernel's CRNG. Default is controlled by CONFIG_RANDOM_TRUST_CPU. + random.trust_bootloader={on,off} + [KNL] Enable or disable trusting the use of a + seed passed by the bootloader (if available) to + fully seed the kernel's CRNG. Default is controlled + by CONFIG_RANDOM_TRUST_BOOTLOADER. + randomize_kstack_offset= [KNL] Enable or disable kernel stack offset randomization, which provides roughly 5 bits of diff --git a/Documentation/bpf/bpf_devel_QA.rst b/Documentation/bpf/bpf_devel_QA.rst index 253496af8fef..761474bd7fe6 100644 --- a/Documentation/bpf/bpf_devel_QA.rst +++ b/Documentation/bpf/bpf_devel_QA.rst @@ -658,7 +658,7 @@ when: .. Links .. _Documentation/process/: https://www.kernel.org/doc/html/latest/process/ -.. _netdev-FAQ: ../networking/netdev-FAQ.rst +.. _netdev-FAQ: Documentation/process/maintainer-netdev.rst .. _selftests: https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/tools/testing/selftests/bpf/ .. _Documentation/dev-tools/kselftest.rst: diff --git a/Documentation/core-api/xarray.rst b/Documentation/core-api/xarray.rst index a137a0e6d068..77e0ece2b1d6 100644 --- a/Documentation/core-api/xarray.rst +++ b/Documentation/core-api/xarray.rst @@ -315,11 +315,15 @@ indeed the normal API is implemented in terms of the advanced API. The advanced API is only available to modules with a GPL-compatible license. The advanced API is based around the xa_state. This is an opaque data -structure which you declare on the stack using the XA_STATE() -macro. This macro initialises the xa_state ready to start walking -around the XArray. It is used as a cursor to maintain the position -in the XArray and let you compose various operations together without -having to restart from the top every time. +structure which you declare on the stack using the XA_STATE() macro. +This macro initialises the xa_state ready to start walking around the +XArray. It is used as a cursor to maintain the position in the XArray +and let you compose various operations together without having to restart +from the top every time. The contents of the xa_state are protected by +the rcu_read_lock() or the xas_lock(). If you need to drop whichever of +those locks is protecting your state and tree, you must call xas_pause() +so that future calls do not rely on the parts of the state which were +left unprotected. The xa_state is also used to store errors. You can call xas_error() to retrieve the error. All operations check whether diff --git a/Documentation/dev-tools/kunit/architecture.rst b/Documentation/dev-tools/kunit/architecture.rst index aa2cea821e25..ff9c85a0bff2 100644 --- a/Documentation/dev-tools/kunit/architecture.rst +++ b/Documentation/dev-tools/kunit/architecture.rst @@ -26,10 +26,7 @@ The fundamental unit in KUnit is the test case. The KUnit test cases are grouped into KUnit suites. A KUnit test case is a function with type signature ``void (*)(struct kunit *test)``. These test case functions are wrapped in a struct called -``struct kunit_case``. For code, see: - -.. kernel-doc:: include/kunit/test.h - :identifiers: kunit_case +struct kunit_case. .. note: ``generate_params`` is optional for non-parameterized tests. @@ -152,18 +149,12 @@ Parameterized Tests Each KUnit parameterized test is associated with a collection of parameters. The test is invoked multiple times, once for each parameter value and the parameter is stored in the ``param_value`` field. -The test case includes a ``KUNIT_CASE_PARAM()`` macro that accepts a +The test case includes a KUNIT_CASE_PARAM() macro that accepts a generator function. The generator function is passed the previous parameter and returns the next parameter. It also provides a macro to generate common-case generators based on arrays. -For code, see: - -.. kernel-doc:: include/kunit/test.h - :identifiers: KUNIT_ARRAY_PARAM - - kunit_tool (Command Line Test Harness) ====================================== diff --git a/Documentation/devicetree/bindings/arm/freescale/fsl,scu.txt b/Documentation/devicetree/bindings/arm/freescale/fsl,scu.txt index fd0061712443..a87ec15e28d2 100644 --- a/Documentation/devicetree/bindings/arm/freescale/fsl,scu.txt +++ b/Documentation/devicetree/bindings/arm/freescale/fsl,scu.txt @@ -86,6 +86,7 @@ This binding uses the common clock binding[1]. Required properties: - compatible: Should be one of: + "fsl,imx8dxl-clk" "fsl,imx8qm-clk" "fsl,imx8qxp-clk" followed by "fsl,scu-clk" diff --git a/Documentation/devicetree/bindings/arm/msm/qcom,idle-state.txt b/Documentation/devicetree/bindings/arm/msm/qcom,idle-state.txt index 6ce0b212ec6d..606b4b1b709d 100644 --- a/Documentation/devicetree/bindings/arm/msm/qcom,idle-state.txt +++ b/Documentation/devicetree/bindings/arm/msm/qcom,idle-state.txt @@ -81,4 +81,4 @@ Example: }; }; -[1]. Documentation/devicetree/bindings/arm/idle-states.yaml +[1]. Documentation/devicetree/bindings/cpu/idle-states.yaml diff --git a/Documentation/devicetree/bindings/arm/psci.yaml b/Documentation/devicetree/bindings/arm/psci.yaml index 8b77cf83a095..dd83ef278af0 100644 --- a/Documentation/devicetree/bindings/arm/psci.yaml +++ b/Documentation/devicetree/bindings/arm/psci.yaml @@ -101,7 +101,7 @@ properties: bindings in [1]) must specify this property. [1] Kernel documentation - ARM idle states bindings - Documentation/devicetree/bindings/arm/idle-states.yaml + Documentation/devicetree/bindings/cpu/idle-states.yaml patternProperties: "^power-domain-": diff --git a/Documentation/devicetree/bindings/clock/apple,nco.yaml b/Documentation/devicetree/bindings/clock/apple,nco.yaml new file mode 100644 index 000000000000..74eab5c0d24a --- /dev/null +++ b/Documentation/devicetree/bindings/clock/apple,nco.yaml @@ -0,0 +1,62 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/clock/apple,nco.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Apple SoCs' NCO block + +maintainers: + - Martin Povišer <povik+lin@cutebit.org> + +description: | + The NCO (Numerically Controlled Oscillator) block found on Apple SoCs + such as the t8103 (M1) is a programmable clock generator performing + fractional division of a high frequency input clock. + + It carries a number of independent channels and is typically used for + generation of audio bitclocks. + +properties: + compatible: + items: + - enum: + - apple,t6000-nco + - apple,t8103-nco + - const: apple,nco + + clocks: + description: + Specifies the reference clock from which the output clocks + are derived through fractional division. + maxItems: 1 + + '#clock-cells': + const: 1 + + reg: + maxItems: 1 + +required: + - compatible + - clocks + - '#clock-cells' + - reg + +additionalProperties: false + +examples: + - | + nco_clkref: clock-ref { + compatible = "fixed-clock"; + #clock-cells = <0>; + clock-frequency = <900000000>; + clock-output-names = "nco-ref"; + }; + + nco: clock-controller@23b044000 { + compatible = "apple,t8103-nco", "apple,nco"; + reg = <0x3b044000 0x14000>; + #clock-cells = <1>; + clocks = <&nco_clkref>; + }; diff --git a/Documentation/devicetree/bindings/clock/bitmain,bm1880-clk.yaml b/Documentation/devicetree/bindings/clock/bitmain,bm1880-clk.yaml index 228c9313df53..f0f9392470a6 100644 --- a/Documentation/devicetree/bindings/clock/bitmain,bm1880-clk.yaml +++ b/Documentation/devicetree/bindings/clock/bitmain,bm1880-clk.yaml @@ -61,16 +61,4 @@ examples: #clock-cells = <1>; }; - # Example UART controller node that consumes clock generated by the clock controller: - - | - uart0: serial@58018000 { - compatible = "snps,dw-apb-uart"; - reg = <0x58018000 0x2000>; - clocks = <&clk 45>, <&clk 46>; - clock-names = "baudclk", "apb_pclk"; - interrupts = <0 9 4>; - reg-shift = <2>; - reg-io-width = <4>; - }; - ... diff --git a/Documentation/devicetree/bindings/clock/cirrus,cs2000-cp.yaml b/Documentation/devicetree/bindings/clock/cirrus,cs2000-cp.yaml new file mode 100644 index 000000000000..0abd6ba82dfd --- /dev/null +++ b/Documentation/devicetree/bindings/clock/cirrus,cs2000-cp.yaml @@ -0,0 +1,91 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/clock/cirrus,cs2000-cp.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Binding CIRRUS LOGIC Fractional-N Clock Synthesizer & Clock Multiplier + +maintainers: + - Kuninori Morimoto <kuninori.morimoto.gx@renesas.com> + +description: | + The CS2000-CP is an extremely versatile system clocking device that + utilizes a programmable phase lock loop. + + Link: https://www.cirrus.com/products/cs2000/ + +properties: + compatible: + enum: + - cirrus,cs2000-cp + + clocks: + description: + Common clock binding for CLK_IN, XTI/REF_CLK + minItems: 2 + maxItems: 2 + + clock-names: + items: + - const: clk_in + - const: ref_clk + + '#clock-cells': + const: 0 + + reg: + maxItems: 1 + + cirrus,aux-output-source: + description: + Specifies the function of the auxiliary clock output pin + $ref: /schemas/types.yaml#/definitions/uint32 + enum: + - 0 # CS2000CP_AUX_OUTPUT_REF_CLK: ref_clk input + - 1 # CS2000CP_AUX_OUTPUT_CLK_IN: clk_in input + - 2 # CS2000CP_AUX_OUTPUT_CLK_OUT: clk_out output + - 3 # CS2000CP_AUX_OUTPUT_PLL_LOCK: pll lock status + default: 0 + + cirrus,clock-skip: + description: + This mode allows the PLL to maintain lock even when CLK_IN + has missing pulses for up to 20 ms. + $ref: /schemas/types.yaml#/definitions/flag + + cirrus,dynamic-mode: + description: + In dynamic mode, the CLK_IN input is used to drive the + digital PLL of the silicon. + If not given, the static mode shall be used to derive the + output signal directly from the REF_CLK input. + $ref: /schemas/types.yaml#/definitions/flag + +required: + - compatible + - reg + - clocks + - clock-names + - '#clock-cells' + +additionalProperties: false + +examples: + - | + #include <dt-bindings/clock/cirrus,cs2000-cp.h> + + i2c@0 { + reg = <0x0 0x100>; + #address-cells = <1>; + #size-cells = <0>; + + clock-controller@4f { + #clock-cells = <0>; + compatible = "cirrus,cs2000-cp"; + reg = <0x4f>; + clocks = <&rcar_sound 0>, <&x12_clk>; + clock-names = "clk_in", "ref_clk"; + cirrus,aux-output-source = <CS2000CP_AUX_OUTPUT_CLK_OUT>; + }; + }; diff --git a/Documentation/devicetree/bindings/clock/cs2000-cp.txt b/Documentation/devicetree/bindings/clock/cs2000-cp.txt deleted file mode 100644 index 54e6df0bee8a..000000000000 --- a/Documentation/devicetree/bindings/clock/cs2000-cp.txt +++ /dev/null @@ -1,22 +0,0 @@ -CIRRUS LOGIC Fractional-N Clock Synthesizer & Clock Multiplier - -Required properties: - -- compatible: "cirrus,cs2000-cp" -- reg: The chip select number on the I2C bus -- clocks: common clock binding for CLK_IN, XTI/REF_CLK -- clock-names: CLK_IN : clk_in, XTI/REF_CLK : ref_clk -- #clock-cells: must be <0> - -Example: - -&i2c2 { - ... - cs2000: clk_multiplier@4f { - #clock-cells = <0>; - compatible = "cirrus,cs2000-cp"; - reg = <0x4f>; - clocks = <&rcar_sound 0>, <&x12_clk>; - clock-names = "clk_in", "ref_clk"; - }; -}; diff --git a/Documentation/devicetree/bindings/clock/idt,versaclock5.yaml b/Documentation/devicetree/bindings/clock/idt,versaclock5.yaml index ffd6ae0eed64..be66f1e8b547 100644 --- a/Documentation/devicetree/bindings/clock/idt,versaclock5.yaml +++ b/Documentation/devicetree/bindings/clock/idt,versaclock5.yaml @@ -191,11 +191,4 @@ examples: }; }; - /* Consumer referencing the 5P49V5923 pin OUT1 */ - consumer { - /* ... */ - clocks = <&vc5 1>; - /* ... */ - }; - ... diff --git a/Documentation/devicetree/bindings/clock/imx1-clock.yaml b/Documentation/devicetree/bindings/clock/imx1-clock.yaml index f4833a29b79e..56f524780b1a 100644 --- a/Documentation/devicetree/bindings/clock/imx1-clock.yaml +++ b/Documentation/devicetree/bindings/clock/imx1-clock.yaml @@ -40,12 +40,3 @@ examples: compatible = "fsl,imx1-ccm"; reg = <0x0021b000 0x1000>; }; - - pwm@208000 { - #pwm-cells = <2>; - compatible = "fsl,imx1-pwm"; - reg = <0x00208000 0x1000>; - interrupts = <34>; - clocks = <&clks IMX1_CLK_DUMMY>, <&clks IMX1_CLK_PER1>; - clock-names = "ipg", "per"; - }; diff --git a/Documentation/devicetree/bindings/clock/imx21-clock.yaml b/Documentation/devicetree/bindings/clock/imx21-clock.yaml index 518ad9a4733c..e2d50544700a 100644 --- a/Documentation/devicetree/bindings/clock/imx21-clock.yaml +++ b/Documentation/devicetree/bindings/clock/imx21-clock.yaml @@ -40,12 +40,3 @@ examples: reg = <0x10027000 0x800>; #clock-cells = <1>; }; - - serial@1000a000 { - compatible = "fsl,imx21-uart"; - reg = <0x1000a000 0x1000>; - interrupts = <20>; - clocks = <&clks IMX21_CLK_UART1_IPG_GATE>, - <&clks IMX21_CLK_PER1>; - clock-names = "ipg", "per"; - }; diff --git a/Documentation/devicetree/bindings/clock/imx23-clock.yaml b/Documentation/devicetree/bindings/clock/imx23-clock.yaml index 5e296a00e14f..7e890ab9c77d 100644 --- a/Documentation/devicetree/bindings/clock/imx23-clock.yaml +++ b/Documentation/devicetree/bindings/clock/imx23-clock.yaml @@ -83,12 +83,3 @@ examples: reg = <0x80040000 0x2000>; #clock-cells = <1>; }; - - serial@8006c000 { - compatible = "fsl,imx23-auart"; - reg = <0x8006c000 0x2000>; - interrupts = <24>; - clocks = <&clks 32>; - dmas = <&dma_apbx 6>, <&dma_apbx 7>; - dma-names = "rx", "tx"; - }; diff --git a/Documentation/devicetree/bindings/clock/imx25-clock.yaml b/Documentation/devicetree/bindings/clock/imx25-clock.yaml index 2a2b10778e72..1792e138984b 100644 --- a/Documentation/devicetree/bindings/clock/imx25-clock.yaml +++ b/Documentation/devicetree/bindings/clock/imx25-clock.yaml @@ -176,11 +176,3 @@ examples: interrupts = <31>; #clock-cells = <1>; }; - - serial@43f90000 { - compatible = "fsl,imx25-uart", "fsl,imx21-uart"; - reg = <0x43f90000 0x4000>; - interrupts = <45>; - clocks = <&clks 79>, <&clks 50>; - clock-names = "ipg", "per"; - }; diff --git a/Documentation/devicetree/bindings/clock/imx27-clock.yaml b/Documentation/devicetree/bindings/clock/imx27-clock.yaml index 160268f24487..99925aa22a4c 100644 --- a/Documentation/devicetree/bindings/clock/imx27-clock.yaml +++ b/Documentation/devicetree/bindings/clock/imx27-clock.yaml @@ -44,12 +44,3 @@ examples: interrupts = <31>; #clock-cells = <1>; }; - - serial@1000a000 { - compatible = "fsl,imx27-uart", "fsl,imx21-uart"; - reg = <0x1000a000 0x1000>; - interrupts = <20>; - clocks = <&clks IMX27_CLK_UART1_IPG_GATE>, - <&clks IMX27_CLK_PER1_GATE>; - clock-names = "ipg", "per"; - }; diff --git a/Documentation/devicetree/bindings/clock/imx28-clock.yaml b/Documentation/devicetree/bindings/clock/imx28-clock.yaml index f831b780f951..a542d680b1ca 100644 --- a/Documentation/devicetree/bindings/clock/imx28-clock.yaml +++ b/Documentation/devicetree/bindings/clock/imx28-clock.yaml @@ -106,12 +106,3 @@ examples: reg = <0x80040000 0x2000>; #clock-cells = <1>; }; - - serial@8006a000 { - compatible = "fsl,imx28-auart"; - reg = <0x8006a000 0x2000>; - interrupts = <112>; - dmas = <&dma_apbx 8>, <&dma_apbx 9>; - dma-names = "rx", "tx"; - clocks = <&clks 45>; - }; diff --git a/Documentation/devicetree/bindings/clock/imx31-clock.yaml b/Documentation/devicetree/bindings/clock/imx31-clock.yaml index d2336261c922..168c8ada5e81 100644 --- a/Documentation/devicetree/bindings/clock/imx31-clock.yaml +++ b/Documentation/devicetree/bindings/clock/imx31-clock.yaml @@ -110,11 +110,3 @@ examples: interrupts = <31>, <53>; #clock-cells = <1>; }; - - serial@43f90000 { - compatible = "fsl,imx31-uart", "fsl,imx21-uart"; - reg = <0x43f90000 0x4000>; - interrupts = <45>; - clocks = <&clks 10>, <&clks 30>; - clock-names = "ipg", "per"; - }; diff --git a/Documentation/devicetree/bindings/clock/imx35-clock.yaml b/Documentation/devicetree/bindings/clock/imx35-clock.yaml index 3e20ccaf8131..6415bb6a8d04 100644 --- a/Documentation/devicetree/bindings/clock/imx35-clock.yaml +++ b/Documentation/devicetree/bindings/clock/imx35-clock.yaml @@ -129,11 +129,3 @@ examples: interrupts = <31>; #clock-cells = <1>; }; - - mmc@53fb4000 { - compatible = "fsl,imx35-esdhc"; - reg = <0x53fb4000 0x4000>; - interrupts = <7>; - clocks = <&clks 9>, <&clks 8>, <&clks 43>; - clock-names = "ipg", "ahb", "per"; - }; diff --git a/Documentation/devicetree/bindings/clock/imx7ulp-pcc-clock.yaml b/Documentation/devicetree/bindings/clock/imx7ulp-pcc-clock.yaml index 7caf5cee9199..739c3378f8c8 100644 --- a/Documentation/devicetree/bindings/clock/imx7ulp-pcc-clock.yaml +++ b/Documentation/devicetree/bindings/clock/imx7ulp-pcc-clock.yaml @@ -108,14 +108,3 @@ examples: "upll", "sosc_bus_clk", "firc_bus_clk", "rosc", "spll_bus_clk"; }; - - mmc@40380000 { - compatible = "fsl,imx7ulp-usdhc"; - reg = <0x40380000 0x10000>; - interrupts = <GIC_SPI 43 IRQ_TYPE_LEVEL_HIGH>; - clocks = <&scg1 IMX7ULP_CLK_NIC1_BUS_DIV>, - <&scg1 IMX7ULP_CLK_NIC1_DIV>, - <&pcc2 IMX7ULP_CLK_USDHC1>; - clock-names ="ipg", "ahb", "per"; - bus-width = <4>; - }; diff --git a/Documentation/devicetree/bindings/clock/imx7ulp-scg-clock.yaml b/Documentation/devicetree/bindings/clock/imx7ulp-scg-clock.yaml index ee8efb4ed599..d06344d7e34f 100644 --- a/Documentation/devicetree/bindings/clock/imx7ulp-scg-clock.yaml +++ b/Documentation/devicetree/bindings/clock/imx7ulp-scg-clock.yaml @@ -86,14 +86,3 @@ examples: "firc", "upll"; #clock-cells = <1>; }; - - mmc@40380000 { - compatible = "fsl,imx7ulp-usdhc"; - reg = <0x40380000 0x10000>; - interrupts = <GIC_SPI 43 IRQ_TYPE_LEVEL_HIGH>; - clocks = <&scg1 IMX7ULP_CLK_NIC1_BUS_DIV>, - <&scg1 IMX7ULP_CLK_NIC1_DIV>, - <&pcc2 IMX7ULP_CLK_USDHC1>; - clock-names ="ipg", "ahb", "per"; - bus-width = <4>; - }; diff --git a/Documentation/devicetree/bindings/clock/imx8qxp-lpcg.yaml b/Documentation/devicetree/bindings/clock/imx8qxp-lpcg.yaml index 0f6fe365ebf3..cb80105b3c70 100644 --- a/Documentation/devicetree/bindings/clock/imx8qxp-lpcg.yaml +++ b/Documentation/devicetree/bindings/clock/imx8qxp-lpcg.yaml @@ -101,14 +101,3 @@ examples: "sdhc0_lpcg_ahb_clk"; power-domains = <&pd IMX_SC_R_SDHC_0>; }; - - mmc@5b010000 { - compatible = "fsl,imx8qxp-usdhc", "fsl,imx7d-usdhc"; - interrupts = <GIC_SPI 232 IRQ_TYPE_LEVEL_HIGH>; - reg = <0x5b010000 0x10000>; - clocks = <&sdhc0_lpcg IMX_LPCG_CLK_4>, - <&sdhc0_lpcg IMX_LPCG_CLK_5>, - <&sdhc0_lpcg IMX_LPCG_CLK_0>; - clock-names = "ipg", "ahb", "per"; - power-domains = <&pd IMX_SC_R_SDHC_0>; - }; diff --git a/Documentation/devicetree/bindings/clock/imx93-clock.yaml b/Documentation/devicetree/bindings/clock/imx93-clock.yaml new file mode 100644 index 000000000000..21a06194e4a3 --- /dev/null +++ b/Documentation/devicetree/bindings/clock/imx93-clock.yaml @@ -0,0 +1,62 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/clock/imx93-clock.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: NXP i.MX93 Clock Control Module Binding + +maintainers: + - Peng Fan <peng.fan@nxp.com> + +description: | + i.MX93 clock control module is an integrated clock controller, which + includes clock generator, clock gate and supplies to all modules. + +properties: + compatible: + enum: + - fsl,imx93-ccm + + reg: + maxItems: 1 + + clocks: + description: + specify the external clocks used by the CCM module. + items: + - description: 32k osc + - description: 24m osc + - description: ext1 clock input + + clock-names: + description: + specify the external clocks names used by the CCM module. + items: + - const: osc_32k + - const: osc_24m + - const: clk_ext1 + + '#clock-cells': + const: 1 + description: + See include/dt-bindings/clock/imx93-clock.h for the full list of + i.MX93 clock IDs. + +required: + - compatible + - reg + - '#clock-cells' + +additionalProperties: false + +examples: + # Clock Control Module node: + - | + clock-controller@44450000 { + compatible = "fsl,imx93-ccm"; + reg = <0x44450000 0x10000>; + #clock-cells = <1>; + }; + +... diff --git a/Documentation/devicetree/bindings/clock/imxrt1050-clock.yaml b/Documentation/devicetree/bindings/clock/imxrt1050-clock.yaml new file mode 100644 index 000000000000..03fc5c1a2939 --- /dev/null +++ b/Documentation/devicetree/bindings/clock/imxrt1050-clock.yaml @@ -0,0 +1,59 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/clock/imxrt1050-clock.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Clock bindings for Freescale i.MXRT + +maintainers: + - Giulio Benetti <giulio.benetti@benettiengineering.com> + - Jesse Taube <Mr.Bossman075@gmail.com> + +description: | + The clock consumer should specify the desired clock by having the clock + ID in its "clocks" phandle cell. See include/dt-bindings/clock/imxrt*-clock.h + for the full list of i.MXRT clock IDs. + +properties: + compatible: + const: fsl,imxrt1050-ccm + + reg: + maxItems: 1 + + interrupts: + maxItems: 2 + + clocks: + description: 24m osc + maxItems: 1 + + clock-names: + const: osc + + '#clock-cells': + const: 1 + +required: + - compatible + - reg + - interrupts + - clocks + - clock-names + - '#clock-cells' + +additionalProperties: false + +examples: + - | + #include <dt-bindings/clock/imxrt1050-clock.h> + + clks: clock-controller@400fc000 { + compatible = "fsl,imxrt1050-ccm"; + reg = <0x400fc000 0x4000>; + interrupts = <95>, <96>; + clocks = <&osc>; + clock-names = "osc"; + #clock-cells = <1>; + }; diff --git a/Documentation/devicetree/bindings/clock/nvidia,tegra124-car.yaml b/Documentation/devicetree/bindings/clock/nvidia,tegra124-car.yaml index ec7ab1483652..1b2181f6d440 100644 --- a/Documentation/devicetree/bindings/clock/nvidia,tegra124-car.yaml +++ b/Documentation/devicetree/bindings/clock/nvidia,tegra124-car.yaml @@ -106,10 +106,3 @@ examples: #clock-cells = <1>; #reset-cells = <1>; }; - - usb-controller@c5004000 { - compatible = "nvidia,tegra20-ehci"; - reg = <0xc5004000 0x4000>; - clocks = <&car TEGRA124_CLK_USB2>; - resets = <&car TEGRA124_CLK_USB2>; - }; diff --git a/Documentation/devicetree/bindings/clock/nvidia,tegra20-car.yaml b/Documentation/devicetree/bindings/clock/nvidia,tegra20-car.yaml index f832abb7f11a..bee2dd4b29bf 100644 --- a/Documentation/devicetree/bindings/clock/nvidia,tegra20-car.yaml +++ b/Documentation/devicetree/bindings/clock/nvidia,tegra20-car.yaml @@ -97,10 +97,3 @@ examples: power-domains = <&domain>; }; }; - - usb-controller@c5004000 { - compatible = "nvidia,tegra20-ehci"; - reg = <0xc5004000 0x4000>; - clocks = <&car TEGRA20_CLK_USB2>; - resets = <&car TEGRA20_CLK_USB2>; - }; diff --git a/Documentation/devicetree/bindings/clock/qcom,a7pll.yaml b/Documentation/devicetree/bindings/clock/qcom,a7pll.yaml index 8666e995725f..0e96f693b050 100644 --- a/Documentation/devicetree/bindings/clock/qcom,a7pll.yaml +++ b/Documentation/devicetree/bindings/clock/qcom,a7pll.yaml @@ -10,7 +10,7 @@ maintainers: - Manivannan Sadhasivam <manivannan.sadhasivam@linaro.org> description: - The A7 PLL on the Qualcomm platforms like SDX55 is used to provide high + The A7 PLL on the Qualcomm platforms like SDX55, SDX65 is used to provide high frequency clock to the CPU. properties: diff --git a/Documentation/devicetree/bindings/clock/qcom,camcc.txt b/Documentation/devicetree/bindings/clock/qcom,camcc.txt deleted file mode 100644 index c5eb6694fda9..000000000000 --- a/Documentation/devicetree/bindings/clock/qcom,camcc.txt +++ /dev/null @@ -1,18 +0,0 @@ -Qualcomm Camera Clock & Reset Controller Binding ------------------------------------------------- - -Required properties : -- compatible : shall contain "qcom,sdm845-camcc". -- reg : shall contain base register location and length. -- #clock-cells : from common clock binding, shall contain 1. -- #reset-cells : from common reset binding, shall contain 1. -- #power-domain-cells : from generic power domain binding, shall contain 1. - -Example: - camcc: clock-controller@ad00000 { - compatible = "qcom,sdm845-camcc"; - reg = <0xad00000 0x10000>; - #clock-cells = <1>; - #reset-cells = <1>; - #power-domain-cells = <1>; - }; diff --git a/Documentation/devicetree/bindings/clock/qcom,dispcc-sm6125.yaml b/Documentation/devicetree/bindings/clock/qcom,dispcc-sm6125.yaml new file mode 100644 index 000000000000..7a03ef19c947 --- /dev/null +++ b/Documentation/devicetree/bindings/clock/qcom,dispcc-sm6125.yaml @@ -0,0 +1,87 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/clock/qcom,dispcc-sm6125.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Qualcomm Display Clock Controller Binding for SM6125 + +maintainers: + - Martin Botka <martin.botka@somainline.org> + +description: | + Qualcomm display clock control module which supports the clocks and + power domains on SM6125. + + See also: + dt-bindings/clock/qcom,dispcc-sm6125.h + +properties: + compatible: + enum: + - qcom,sm6125-dispcc + + clocks: + items: + - description: Board XO source + - description: Byte clock from DSI PHY0 + - description: Pixel clock from DSI PHY0 + - description: Pixel clock from DSI PHY1 + - description: Link clock from DP PHY + - description: VCO DIV clock from DP PHY + - description: AHB config clock from GCC + + clock-names: + items: + - const: bi_tcxo + - const: dsi0_phy_pll_out_byteclk + - const: dsi0_phy_pll_out_dsiclk + - const: dsi1_phy_pll_out_dsiclk + - const: dp_phy_pll_link_clk + - const: dp_phy_pll_vco_div_clk + - const: cfg_ahb_clk + + '#clock-cells': + const: 1 + + '#power-domain-cells': + const: 1 + + reg: + maxItems: 1 + +required: + - compatible + - reg + - clocks + - clock-names + - '#clock-cells' + - '#power-domain-cells' + +additionalProperties: false + +examples: + - | + #include <dt-bindings/clock/qcom,rpmcc.h> + #include <dt-bindings/clock/qcom,gcc-sm6125.h> + clock-controller@5f00000 { + compatible = "qcom,sm6125-dispcc"; + reg = <0x5f00000 0x20000>; + clocks = <&rpmcc RPM_SMD_XO_CLK_SRC>, + <&dsi0_phy 0>, + <&dsi0_phy 1>, + <&dsi1_phy 1>, + <&dp_phy 0>, + <&dp_phy 1>, + <&gcc GCC_DISP_AHB_CLK>; + clock-names = "bi_tcxo", + "dsi0_phy_pll_out_byteclk", + "dsi0_phy_pll_out_dsiclk", + "dsi1_phy_pll_out_dsiclk", + "dp_phy_pll_link_clk", + "dp_phy_pll_vco_div_clk", + "cfg_ahb_clk"; + #clock-cells = <1>; + #power-domain-cells = <1>; + }; +... diff --git a/Documentation/devicetree/bindings/clock/qcom,dispcc-sm6350.yaml b/Documentation/devicetree/bindings/clock/qcom,dispcc-sm6350.yaml new file mode 100644 index 000000000000..e706678b353a --- /dev/null +++ b/Documentation/devicetree/bindings/clock/qcom,dispcc-sm6350.yaml @@ -0,0 +1,86 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/clock/qcom,dispcc-sm6350.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Qualcomm Display Clock & Reset Controller Binding for SM6350 + +maintainers: + - Konrad Dybcio <konrad.dybcio@somainline.org> + +description: | + Qualcomm display clock control module which supports the clocks, resets and + power domains on SM6350. + + See also dt-bindings/clock/qcom,dispcc-sm6350.h. + +properties: + compatible: + const: qcom,sm6350-dispcc + + clocks: + items: + - description: Board XO source + - description: GPLL0 source from GCC + - description: Byte clock from DSI PHY + - description: Pixel clock from DSI PHY + - description: Link clock from DP PHY + - description: VCO DIV clock from DP PHY + + clock-names: + items: + - const: bi_tcxo + - const: gcc_disp_gpll0_clk + - const: dsi0_phy_pll_out_byteclk + - const: dsi0_phy_pll_out_dsiclk + - const: dp_phy_pll_link_clk + - const: dp_phy_pll_vco_div_clk + + '#clock-cells': + const: 1 + + '#reset-cells': + const: 1 + + '#power-domain-cells': + const: 1 + + reg: + maxItems: 1 + +required: + - compatible + - reg + - clocks + - clock-names + - '#clock-cells' + - '#reset-cells' + - '#power-domain-cells' + +additionalProperties: false + +examples: + - | + #include <dt-bindings/clock/qcom,gcc-sm6350.h> + #include <dt-bindings/clock/qcom,rpmh.h> + clock-controller@af00000 { + compatible = "qcom,sm6350-dispcc"; + reg = <0x0af00000 0x20000>; + clocks = <&rpmhcc RPMH_CXO_CLK>, + <&gcc GCC_DISP_GPLL0_CLK>, + <&dsi_phy 0>, + <&dsi_phy 1>, + <&dp_phy 0>, + <&dp_phy 1>; + clock-names = "bi_tcxo", + "gcc_disp_gpll0_clk", + "dsi0_phy_pll_out_byteclk", + "dsi0_phy_pll_out_dsiclk", + "dp_phy_pll_link_clk", + "dp_phy_pll_vco_div_clk"; + #clock-cells = <1>; + #reset-cells = <1>; + #power-domain-cells = <1>; + }; +... diff --git a/Documentation/devicetree/bindings/clock/qcom,gcc-apq8064.yaml b/Documentation/devicetree/bindings/clock/qcom,gcc-apq8064.yaml index 8e2eac6cbfb9..97936411b6b4 100644 --- a/Documentation/devicetree/bindings/clock/qcom,gcc-apq8064.yaml +++ b/Documentation/devicetree/bindings/clock/qcom,gcc-apq8064.yaml @@ -6,6 +6,9 @@ $schema: http://devicetree.org/meta-schemas/core.yaml# title: Qualcomm Global Clock & Reset Controller Binding for APQ8064 +allOf: + - $ref: qcom,gcc.yaml# + maintainers: - Stephen Boyd <sboyd@kernel.org> - Taniya Das <tdas@codeaurora.org> @@ -17,22 +20,12 @@ description: | See also: - dt-bindings/clock/qcom,gcc-msm8960.h - dt-bindings/reset/qcom,gcc-msm8960.h + - dt-bindings/clock/qcom,gcc-apq8084.h + - dt-bindings/reset/qcom,gcc-apq8084.h properties: compatible: - const: qcom,gcc-apq8064 - - '#clock-cells': - const: 1 - - '#reset-cells': - const: 1 - - '#power-domain-cells': - const: 1 - - reg: - maxItems: 1 + const: qcom,gcc-apq8084 nvmem-cells: minItems: 1 @@ -53,21 +46,13 @@ properties: '#thermal-sensor-cells': const: 1 - protected-clocks: - description: - Protected clock specifier list as per common clock binding. - required: - compatible - - reg - - '#clock-cells' - - '#reset-cells' - - '#power-domain-cells' - nvmem-cells - nvmem-cell-names - '#thermal-sensor-cells' -additionalProperties: false +unevaluatedProperties: false examples: - | diff --git a/Documentation/devicetree/bindings/clock/qcom,gcc-ipq8064.yaml b/Documentation/devicetree/bindings/clock/qcom,gcc-ipq8064.yaml new file mode 100644 index 000000000000..9eb91dd22557 --- /dev/null +++ b/Documentation/devicetree/bindings/clock/qcom,gcc-ipq8064.yaml @@ -0,0 +1,76 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/clock/qcom,gcc-ipq8064.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Qualcomm Global Clock & Reset Controller Binding for IPQ8064 + +allOf: + - $ref: qcom,gcc.yaml# + +maintainers: + - Ansuel Smith <ansuelsmth@gmail.com> + +description: | + Qualcomm global clock control module which supports the clocks, resets and + power domains on IPQ8064. + + See also: + - dt-bindings/clock/qcom,gcc-ipq806x.h (qcom,gcc-ipq8064) + - dt-bindings/reset/qcom,gcc-ipq806x.h (qcom,gcc-ipq8064) + +properties: + compatible: + items: + - const: qcom,gcc-ipq8064 + - const: syscon + + clocks: + items: + - description: PXO source + - description: CXO source + + clock-names: + items: + - const: pxo + - const: cxo + + thermal-sensor: + type: object + + allOf: + - $ref: /schemas/thermal/qcom-tsens.yaml# + +required: + - compatible + - clocks + - clock-names + +unevaluatedProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/arm-gic.h> + + gcc: clock-controller@900000 { + compatible = "qcom,gcc-ipq8064", "syscon"; + reg = <0x00900000 0x4000>; + clocks = <&pxo_board>, <&cxo_board>; + clock-names = "pxo", "cxo"; + #clock-cells = <1>; + #reset-cells = <1>; + #power-domain-cells = <1>; + + tsens: thermal-sensor { + compatible = "qcom,ipq8064-tsens"; + + nvmem-cells = <&tsens_calib>, <&tsens_calib_backup>; + nvmem-cell-names = "calib", "calib_backup"; + interrupts = <GIC_SPI 178 IRQ_TYPE_LEVEL_HIGH>; + interrupt-names = "uplow"; + + #qcom,sensors = <11>; + #thermal-sensor-cells = <1>; + }; + }; diff --git a/Documentation/devicetree/bindings/clock/qcom,gcc-other.yaml b/Documentation/devicetree/bindings/clock/qcom,gcc-other.yaml new file mode 100644 index 000000000000..6c45e0f85494 --- /dev/null +++ b/Documentation/devicetree/bindings/clock/qcom,gcc-other.yaml @@ -0,0 +1,70 @@ +# SPDX-License-Identifier: GPL-2.0-only +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/clock/qcom,gcc-other.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Qualcomm Global Clock & Reset Controller Binding + +maintainers: + - Stephen Boyd <sboyd@kernel.org> + - Taniya Das <tdas@codeaurora.org> + +description: | + Qualcomm global clock control module which supports the clocks, resets and + power domains. + + See also: + - dt-bindings/clock/qcom,gcc-ipq4019.h + - dt-bindings/clock/qcom,gcc-ipq6018.h + - dt-bindings/reset/qcom,gcc-ipq6018.h + - dt-bindings/clock/qcom,gcc-msm8939.h + - dt-bindings/clock/qcom,gcc-msm8953.h + - dt-bindings/reset/qcom,gcc-msm8939.h + - dt-bindings/clock/qcom,gcc-msm8660.h + - dt-bindings/reset/qcom,gcc-msm8660.h + - dt-bindings/clock/qcom,gcc-msm8974.h (qcom,gcc-msm8226 and qcom,gcc-msm8974) + - dt-bindings/reset/qcom,gcc-msm8974.h (qcom,gcc-msm8226 and qcom,gcc-msm8974) + - dt-bindings/clock/qcom,gcc-mdm9607.h + - dt-bindings/clock/qcom,gcc-mdm9615.h + - dt-bindings/reset/qcom,gcc-mdm9615.h + - dt-bindings/clock/qcom,gcc-sdm660.h (qcom,gcc-sdm630 and qcom,gcc-sdm660) + +allOf: + - $ref: "qcom,gcc.yaml#" + +properties: + compatible: + enum: + - qcom,gcc-ipq4019 + - qcom,gcc-ipq6018 + - qcom,gcc-mdm9607 + - qcom,gcc-msm8226 + - qcom,gcc-msm8660 + - qcom,gcc-msm8916 + - qcom,gcc-msm8939 + - qcom,gcc-msm8953 + - qcom,gcc-msm8960 + - qcom,gcc-msm8974 + - qcom,gcc-msm8974pro + - qcom,gcc-msm8974pro-ac + - qcom,gcc-mdm9615 + - qcom,gcc-sdm630 + - qcom,gcc-sdm660 + +required: + - compatible + +unevaluatedProperties: false + +examples: + # Example for GCC for MSM8960: + - | + clock-controller@900000 { + compatible = "qcom,gcc-msm8960"; + reg = <0x900000 0x4000>; + #clock-cells = <1>; + #reset-cells = <1>; + #power-domain-cells = <1>; + }; +... diff --git a/Documentation/devicetree/bindings/clock/qcom,gcc.yaml b/Documentation/devicetree/bindings/clock/qcom,gcc.yaml index f66d703bd913..2ed27a2ef445 100644 --- a/Documentation/devicetree/bindings/clock/qcom,gcc.yaml +++ b/Documentation/devicetree/bindings/clock/qcom,gcc.yaml @@ -4,57 +4,17 @@ $id: http://devicetree.org/schemas/clock/qcom,gcc.yaml# $schema: http://devicetree.org/meta-schemas/core.yaml# -title: Qualcomm Global Clock & Reset Controller Binding +title: Qualcomm Global Clock & Reset Controller Binding Common Bindings maintainers: - Stephen Boyd <sboyd@kernel.org> - Taniya Das <tdas@codeaurora.org> description: | - Qualcomm global clock control module which supports the clocks, resets and - power domains. - - See also: - - dt-bindings/clock/qcom,gcc-apq8084.h - - dt-bindings/reset/qcom,gcc-apq8084.h - - dt-bindings/clock/qcom,gcc-ipq4019.h - - dt-bindings/clock/qcom,gcc-ipq6018.h - - dt-bindings/reset/qcom,gcc-ipq6018.h - - dt-bindings/clock/qcom,gcc-ipq806x.h (qcom,gcc-ipq8064) - - dt-bindings/reset/qcom,gcc-ipq806x.h (qcom,gcc-ipq8064) - - dt-bindings/clock/qcom,gcc-msm8939.h - - dt-bindings/clock/qcom,gcc-msm8953.h - - dt-bindings/reset/qcom,gcc-msm8939.h - - dt-bindings/clock/qcom,gcc-msm8660.h - - dt-bindings/reset/qcom,gcc-msm8660.h - - dt-bindings/clock/qcom,gcc-msm8974.h (qcom,gcc-msm8226 and qcom,gcc-msm8974) - - dt-bindings/reset/qcom,gcc-msm8974.h (qcom,gcc-msm8226 and qcom,gcc-msm8974) - - dt-bindings/clock/qcom,gcc-mdm9607.h - - dt-bindings/clock/qcom,gcc-mdm9615.h - - dt-bindings/reset/qcom,gcc-mdm9615.h - - dt-bindings/clock/qcom,gcc-sdm660.h (qcom,gcc-sdm630 and qcom,gcc-sdm660) + Common bindings for Qualcomm global clock control module which supports + the clocks, resets and power domains. properties: - compatible: - enum: - - qcom,gcc-apq8084 - - qcom,gcc-ipq4019 - - qcom,gcc-ipq6018 - - qcom,gcc-ipq8064 - - qcom,gcc-mdm9607 - - qcom,gcc-msm8226 - - qcom,gcc-msm8660 - - qcom,gcc-msm8916 - - qcom,gcc-msm8939 - - qcom,gcc-msm8953 - - qcom,gcc-msm8960 - - qcom,gcc-msm8974 - - qcom,gcc-msm8974pro - - qcom,gcc-msm8974pro-ac - - qcom,gcc-mdm9615 - - qcom,gcc-sdm630 - - qcom,gcc-sdm660 - '#clock-cells': const: 1 @@ -72,22 +32,11 @@ properties: Protected clock specifier list as per common clock binding. required: - - compatible - reg - '#clock-cells' - '#reset-cells' - '#power-domain-cells' -additionalProperties: false +additionalProperties: true -examples: - # Example for GCC for MSM8960: - - | - clock-controller@900000 { - compatible = "qcom,gcc-msm8960"; - reg = <0x900000 0x4000>; - #clock-cells = <1>; - #reset-cells = <1>; - #power-domain-cells = <1>; - }; ... diff --git a/Documentation/devicetree/bindings/clock/qcom,gpucc.yaml b/Documentation/devicetree/bindings/clock/qcom,gpucc.yaml index 46dff46d5760..9ebcb1943b0a 100644 --- a/Documentation/devicetree/bindings/clock/qcom,gpucc.yaml +++ b/Documentation/devicetree/bindings/clock/qcom,gpucc.yaml @@ -17,6 +17,7 @@ description: | dt-bindings/clock/qcom,gpucc-sdm845.h dt-bindings/clock/qcom,gpucc-sc7180.h dt-bindings/clock/qcom,gpucc-sc7280.h + dt-bindings/clock/qcom,gpucc-sm6350.h dt-bindings/clock/qcom,gpucc-sm8150.h dt-bindings/clock/qcom,gpucc-sm8250.h @@ -27,6 +28,7 @@ properties: - qcom,sc7180-gpucc - qcom,sc7280-gpucc - qcom,sc8180x-gpucc + - qcom,sm6350-gpucc - qcom,sm8150-gpucc - qcom,sm8250-gpucc diff --git a/Documentation/devicetree/bindings/clock/qcom,mmcc.yaml b/Documentation/devicetree/bindings/clock/qcom,mmcc.yaml index 68fdc3d4982a..4b79e89fd174 100644 --- a/Documentation/devicetree/bindings/clock/qcom,mmcc.yaml +++ b/Documentation/devicetree/bindings/clock/qcom,mmcc.yaml @@ -19,6 +19,7 @@ properties: enum: - qcom,mmcc-apq8064 - qcom,mmcc-apq8084 + - qcom,mmcc-msm8226 - qcom,mmcc-msm8660 - qcom,mmcc-msm8960 - qcom,mmcc-msm8974 diff --git a/Documentation/devicetree/bindings/clock/qcom,qcm2290-dispcc.yaml b/Documentation/devicetree/bindings/clock/qcom,qcm2290-dispcc.yaml new file mode 100644 index 000000000000..973e408c6268 --- /dev/null +++ b/Documentation/devicetree/bindings/clock/qcom,qcm2290-dispcc.yaml @@ -0,0 +1,87 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/clock/qcom,qcm2290-dispcc.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Qualcomm Display Clock & Reset Controller Binding for qcm2290 + +maintainers: + - Loic Poulain <loic.poulain@linaro.org> + +description: | + Qualcomm display clock control module which supports the clocks, resets and + power domains on qcm2290. + + See also dt-bindings/clock/qcom,dispcc-qcm2290.h. + +properties: + compatible: + const: qcom,qcm2290-dispcc + + clocks: + items: + - description: Board XO source + - description: Board active-only XO source + - description: GPLL0 source from GCC + - description: GPLL0 div source from GCC + - description: Byte clock from DSI PHY + - description: Pixel clock from DSI PHY + + clock-names: + items: + - const: bi_tcxo + - const: bi_tcxo_ao + - const: gcc_disp_gpll0_clk_src + - const: gcc_disp_gpll0_div_clk_src + - const: dsi0_phy_pll_out_byteclk + - const: dsi0_phy_pll_out_dsiclk + + '#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,dispcc-qcm2290.h> + #include <dt-bindings/clock/qcom,gcc-qcm2290.h> + #include <dt-bindings/clock/qcom,rpmcc.h> + clock-controller@5f00000 { + compatible = "qcom,qcm2290-dispcc"; + reg = <0x5f00000 0x20000>; + clocks = <&rpmcc RPM_SMD_XO_CLK_SRC>, + <&rpmcc RPM_SMD_XO_A_CLK_SRC>, + <&gcc GCC_DISP_GPLL0_CLK_SRC>, + <&gcc GCC_DISP_GPLL0_DIV_CLK_SRC>, + <&dsi0_phy 0>, + <&dsi0_phy 1>; + clock-names = "bi_tcxo", + "bi_tcxo_ao", + "gcc_disp_gpll0_clk_src", + "gcc_disp_gpll0_div_clk_src", + "dsi0_phy_pll_out_byteclk", + "dsi0_phy_pll_out_dsiclk"; + #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 8406dde17937..8fcaf418f84a 100644 --- a/Documentation/devicetree/bindings/clock/qcom,rpmhcc.yaml +++ b/Documentation/devicetree/bindings/clock/qcom,rpmhcc.yaml @@ -20,6 +20,7 @@ properties: - qcom,sc7180-rpmh-clk - qcom,sc7280-rpmh-clk - qcom,sc8180x-rpmh-clk + - qcom,sc8280xp-rpmh-clk - qcom,sdm845-rpmh-clk - qcom,sdx55-rpmh-clk - qcom,sdx65-rpmh-clk diff --git a/Documentation/devicetree/bindings/clock/qcom,sdm845-camcc.yaml b/Documentation/devicetree/bindings/clock/qcom,sdm845-camcc.yaml new file mode 100644 index 000000000000..d4239ccae917 --- /dev/null +++ b/Documentation/devicetree/bindings/clock/qcom,sdm845-camcc.yaml @@ -0,0 +1,65 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/clock/qcom,sdm845-camcc.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Qualcomm Camera Clock & Reset Controller Binding for SDM845 + +maintainers: + - Bjorn Andersson <bjorn.andersson@linaro.org> + +description: | + Qualcomm camera clock control module which supports the clocks, resets and + power domains on SDM845. + + See also dt-bindings/clock/qcom,camcc-sm845.h + +properties: + compatible: + const: qcom,sdm845-camcc + + clocks: + items: + - description: Board XO source + + clock-names: + items: + - const: bi_tcxo + + '#clock-cells': + const: 1 + + '#reset-cells': + const: 1 + + '#power-domain-cells': + const: 1 + + reg: + maxItems: 1 + +required: + - compatible + - reg + - clocks + - clock-names + - '#clock-cells' + - '#reset-cells' + - '#power-domain-cells' + +additionalProperties: false + +examples: + - | + #include <dt-bindings/clock/qcom,rpmh.h> + clock-controller@ad00000 { + compatible = "qcom,sdm845-camcc"; + reg = <0x0ad00000 0x10000>; + clocks = <&rpmhcc RPMH_CXO_CLK>; + clock-names = "bi_tcxo"; + #clock-cells = <1>; + #reset-cells = <1>; + #power-domain-cells = <1>; + }; +... diff --git a/Documentation/devicetree/bindings/clock/renesas,9series.yaml b/Documentation/devicetree/bindings/clock/renesas,9series.yaml new file mode 100644 index 000000000000..102eb95cb3fc --- /dev/null +++ b/Documentation/devicetree/bindings/clock/renesas,9series.yaml @@ -0,0 +1,97 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/clock/renesas,9series.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Binding for Renesas 9-series I2C PCIe clock generators + +description: | + The Renesas 9-series are I2C PCIe clock generators providing + from 1 to 20 output clocks. + + When referencing the provided clock in the DT using phandle + and clock specifier, the following mapping applies: + + - 9FGV0241: + 0 -- DIF0 + 1 -- DIF1 + +maintainers: + - Marek Vasut <marex@denx.de> + +properties: + compatible: + enum: + - renesas,9fgv0241 + + reg: + description: I2C device address + enum: [ 0x68, 0x6a ] + + '#clock-cells': + const: 1 + + clocks: + items: + - description: XTal input clock + + renesas,out-amplitude-microvolt: + enum: [ 600000, 700000, 800000, 900000 ] + description: Output clock signal amplitude + + renesas,out-spread-spectrum: + $ref: /schemas/types.yaml#/definitions/uint32 + enum: [ 100000, 99750, 99500 ] + description: Output clock down spread in pcm (1/1000 of percent) + +patternProperties: + "^DIF[0-19]$": + type: object + description: + Description of one of the outputs (DIF0..DIF19). + + properties: + renesas,slew-rate: + $ref: /schemas/types.yaml#/definitions/uint32 + enum: [ 2000000, 3000000 ] + description: Output clock slew rate select in V/ns + + additionalProperties: false + +required: + - compatible + - reg + - clocks + - '#clock-cells' + +additionalProperties: false + +examples: + - | + /* 25MHz reference crystal */ + ref25: ref25m { + compatible = "fixed-clock"; + #clock-cells = <0>; + clock-frequency = <25000000>; + }; + + i2c@0 { + reg = <0x0 0x100>; + #address-cells = <1>; + #size-cells = <0>; + + rs9: clock-generator@6a { + compatible = "renesas,9fgv0241"; + reg = <0x6a>; + #clock-cells = <1>; + + clocks = <&ref25m>; + + DIF0 { + renesas,slew-rate = <3000000>; + }; + }; + }; + +... diff --git a/Documentation/devicetree/bindings/clock/renesas,cpg-div6-clock.yaml b/Documentation/devicetree/bindings/clock/renesas,cpg-div6-clock.yaml index c55a7c494e01..2197c952e21d 100644 --- a/Documentation/devicetree/bindings/clock/renesas,cpg-div6-clock.yaml +++ b/Documentation/devicetree/bindings/clock/renesas,cpg-div6-clock.yaml @@ -51,6 +51,18 @@ additionalProperties: false examples: - | #include <dt-bindings/clock/r8a73a4-clock.h> + + cpg_clocks: cpg_clocks@e6150000 { + compatible = "renesas,r8a73a4-cpg-clocks"; + reg = <0xe6150000 0x10000>; + clocks = <&extal1_clk>, <&extal2_clk>; + #clock-cells = <1>; + clock-output-names = "main", "pll0", "pll1", "pll2", + "pll2s", "pll2h", "z", "z2", + "i", "m3", "b", "m1", "m2", + "zx", "zs", "hp"; + }; + sdhi2_clk: sdhi2_clk@e615007c { compatible = "renesas,r8a73a4-div6-clock", "renesas,cpg-div6-clock"; reg = <0xe615007c 4>; diff --git a/Documentation/devicetree/bindings/clock/renesas,rzg2l-cpg.yaml b/Documentation/devicetree/bindings/clock/renesas,rzg2l-cpg.yaml index 30b2e3d0d25d..bd3af8fc616b 100644 --- a/Documentation/devicetree/bindings/clock/renesas,rzg2l-cpg.yaml +++ b/Documentation/devicetree/bindings/clock/renesas,rzg2l-cpg.yaml @@ -4,13 +4,13 @@ $id: "http://devicetree.org/schemas/clock/renesas,rzg2l-cpg.yaml#" $schema: "http://devicetree.org/meta-schemas/core.yaml#" -title: Renesas RZ/G2L Clock Pulse Generator / Module Standby Mode +title: Renesas RZ/{G2L,V2L} Clock Pulse Generator / Module Standby Mode maintainers: - Geert Uytterhoeven <geert+renesas@glider.be> description: | - On Renesas RZ/G2L SoC, the CPG (Clock Pulse Generator) and Module + On Renesas RZ/{G2L,V2L} SoC, the CPG (Clock Pulse Generator) and Module Standby Mode share the same register block. They provide the following functionalities: @@ -22,7 +22,9 @@ description: | properties: compatible: - const: renesas,r9a07g044-cpg # RZ/G2{L,LC} + enum: + - renesas,r9a07g044-cpg # RZ/G2{L,LC} + - renesas,r9a07g054-cpg # RZ/V2L reg: maxItems: 1 @@ -40,9 +42,9 @@ properties: description: | - For CPG core clocks, the two clock specifier cells must be "CPG_CORE" and a core clock reference, as defined in - <dt-bindings/clock/r9a07g044-cpg.h> + <dt-bindings/clock/r9a07g*-cpg.h> - For module clocks, the two clock specifier cells must be "CPG_MOD" and - a module number, as defined in the <dt-bindings/clock/r9a07g044-cpg.h>. + a module number, as defined in the <dt-bindings/clock/r9a07g0*-cpg.h>. const: 2 '#power-domain-cells': @@ -56,7 +58,7 @@ properties: '#reset-cells': description: The single reset specifier cell must be the module number, as defined in - the <dt-bindings/clock/r9a07g044-cpg.h>. + the <dt-bindings/clock/r9a07g0*-cpg.h>. const: 1 required: diff --git a/Documentation/devicetree/bindings/clock/starfive,jh7100-audclk.yaml b/Documentation/devicetree/bindings/clock/starfive,jh7100-audclk.yaml new file mode 100644 index 000000000000..8f49a1ae03f1 --- /dev/null +++ b/Documentation/devicetree/bindings/clock/starfive,jh7100-audclk.yaml @@ -0,0 +1,57 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/clock/starfive,jh7100-audclk.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: StarFive JH7100 Audio Clock Generator + +maintainers: + - Emil Renner Berthing <kernel@esmil.dk> + +properties: + compatible: + const: starfive,jh7100-audclk + + reg: + maxItems: 1 + + clocks: + items: + - description: Audio source clock + - description: External 12.288MHz clock + - description: Domain 7 AHB bus clock + + clock-names: + items: + - const: audio_src + - const: audio_12288 + - const: dom7ahb_bus + + '#clock-cells': + const: 1 + description: + See <dt-bindings/clock/starfive-jh7100-audio.h> for valid indices. + +required: + - compatible + - reg + - clocks + - clock-names + - '#clock-cells' + +additionalProperties: false + +examples: + - | + #include <dt-bindings/clock/starfive-jh7100.h> + + clock-controller@10480000 { + compatible = "starfive,jh7100-audclk"; + reg = <0x10480000 0x10000>; + clocks = <&clkgen JH7100_CLK_AUDIO_SRC>, + <&clkgen JH7100_CLK_AUDIO_12288>, + <&clkgen JH7100_CLK_DOM7AHB_BUS>; + clock-names = "audio_src", "audio_12288", "dom7ahb_bus"; + #clock-cells = <1>; + }; diff --git a/Documentation/devicetree/bindings/arm/idle-states.yaml b/Documentation/devicetree/bindings/cpu/idle-states.yaml index 4d381fa1ee57..5daa219ceb7b 100644 --- a/Documentation/devicetree/bindings/arm/idle-states.yaml +++ b/Documentation/devicetree/bindings/cpu/idle-states.yaml @@ -1,25 +1,30 @@ # SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) %YAML 1.2 --- -$id: http://devicetree.org/schemas/arm/idle-states.yaml# +$id: http://devicetree.org/schemas/cpu/idle-states.yaml# $schema: http://devicetree.org/meta-schemas/core.yaml# -title: ARM idle states binding description +title: Idle states binding description maintainers: - Lorenzo Pieralisi <lorenzo.pieralisi@arm.com> + - Anup Patel <anup@brainfault.org> description: |+ ========================================== 1 - Introduction ========================================== - ARM systems contain HW capable of managing power consumption dynamically, - where cores can be put in different low-power states (ranging from simple wfi - to power gating) according to OS PM policies. The CPU states representing the - range of dynamic idle states that a processor can enter at run-time, can be - specified through device tree bindings representing the parameters required to - enter/exit specific idle states on a given processor. + ARM and RISC-V systems contain HW capable of managing power consumption + dynamically, where cores can be put in different low-power states (ranging + from simple wfi to power gating) according to OS PM policies. The CPU states + representing the range of dynamic idle states that a processor can enter at + run-time, can be specified through device tree bindings representing the + parameters required to enter/exit specific idle states on a given processor. + + ========================================== + 2 - ARM idle states + ========================================== According to the Server Base System Architecture document (SBSA, [3]), the power states an ARM CPU can be put into are identified by the following list: @@ -43,8 +48,23 @@ description: |+ The device tree binding definition for ARM idle states is the subject of this document. + ========================================== + 3 - RISC-V idle states + ========================================== + + On RISC-V systems, the HARTs (or CPUs) [6] can be put in platform specific + suspend (or idle) states (ranging from simple WFI, power gating, etc). The + RISC-V SBI v0.3 (or higher) [7] hart state management extension provides a + standard mechanism for OS to request HART state transitions. + + The platform specific suspend (or idle) states of a hart can be either + retentive or non-rententive in nature. A retentive suspend state will + preserve HART registers and CSR values for all privilege modes whereas + a non-retentive suspend state will not preserve HART registers and CSR + values. + =========================================== - 2 - idle-states definitions + 4 - idle-states definitions =========================================== Idle states are characterized for a specific system through a set of @@ -211,10 +231,10 @@ description: |+ properties specification that is the subject of the following sections. =========================================== - 3 - idle-states node + 5 - idle-states node =========================================== - ARM processor idle states are defined within the idle-states node, which is + The processor idle states are defined within the idle-states node, which is a direct child of the cpus node [1] and provides a container where the processor idle states, defined as device tree nodes, are listed. @@ -223,7 +243,7 @@ description: |+ just supports idle_standby, an idle-states node is not required. =========================================== - 4 - References + 6 - References =========================================== [1] ARM Linux Kernel documentation - CPUs bindings @@ -238,9 +258,15 @@ description: |+ [4] ARM Architecture Reference Manuals http://infocenter.arm.com/help/index.jsp - [6] ARM Linux Kernel documentation - Booting AArch64 Linux + [5] ARM Linux Kernel documentation - Booting AArch64 Linux Documentation/arm64/booting.rst + [6] RISC-V Linux Kernel documentation - CPUs bindings + Documentation/devicetree/bindings/riscv/cpus.yaml + + [7] RISC-V Supervisor Binary Interface (SBI) + http://github.com/riscv/riscv-sbi-doc/riscv-sbi.adoc + properties: $nodename: const: idle-states @@ -253,7 +279,7 @@ properties: On ARM 32-bit systems this property is optional This assumes that the "enable-method" property is set to "psci" in the cpu - node[6] that is responsible for setting up CPU idle management in the OS + node[5] that is responsible for setting up CPU idle management in the OS implementation. const: psci @@ -265,8 +291,8 @@ patternProperties: as follows. The idle state entered by executing the wfi instruction (idle_standby - SBSA,[3][4]) is considered standard on all ARM platforms and therefore - must not be listed. + SBSA,[3][4]) is considered standard on all ARM and RISC-V platforms and + therefore must not be listed. In addition to the properties listed above, a state node may require additional properties specific to the entry-method defined in the @@ -275,7 +301,27 @@ patternProperties: properties: compatible: - const: arm,idle-state + enum: + - arm,idle-state + - riscv,idle-state + + arm,psci-suspend-param: + $ref: /schemas/types.yaml#/definitions/uint32 + description: | + power_state parameter to pass to the ARM PSCI suspend call. + + Device tree nodes that require usage of PSCI CPU_SUSPEND function + (i.e. idle states node with entry-method property is set to "psci") + must specify this property. + + riscv,sbi-suspend-param: + $ref: /schemas/types.yaml#/definitions/uint32 + description: | + suspend_type parameter to pass to the RISC-V SBI HSM suspend call. + + This property is required in idle state nodes of device tree meant + for RISC-V systems. For more details on the suspend_type parameter + refer the SBI specifiation v0.3 (or higher) [7]. local-timer-stop: description: @@ -317,6 +363,8 @@ patternProperties: description: A string used as a descriptive name for the idle state. + additionalProperties: false + required: - compatible - entry-latency-us @@ -658,4 +706,150 @@ examples: }; }; + - | + // Example 3 (RISC-V 64-bit, 4-cpu systems, two clusters): + + cpus { + #size-cells = <0>; + #address-cells = <1>; + + cpu@0 { + device_type = "cpu"; + compatible = "riscv"; + reg = <0x0>; + riscv,isa = "rv64imafdc"; + mmu-type = "riscv,sv48"; + cpu-idle-states = <&CPU_RET_0_0 &CPU_NONRET_0_0 + &CLUSTER_RET_0 &CLUSTER_NONRET_0>; + + cpu_intc0: interrupt-controller { + #interrupt-cells = <1>; + compatible = "riscv,cpu-intc"; + interrupt-controller; + }; + }; + + cpu@1 { + device_type = "cpu"; + compatible = "riscv"; + reg = <0x1>; + riscv,isa = "rv64imafdc"; + mmu-type = "riscv,sv48"; + cpu-idle-states = <&CPU_RET_0_0 &CPU_NONRET_0_0 + &CLUSTER_RET_0 &CLUSTER_NONRET_0>; + + cpu_intc1: interrupt-controller { + #interrupt-cells = <1>; + compatible = "riscv,cpu-intc"; + interrupt-controller; + }; + }; + + cpu@10 { + device_type = "cpu"; + compatible = "riscv"; + reg = <0x10>; + riscv,isa = "rv64imafdc"; + mmu-type = "riscv,sv48"; + cpu-idle-states = <&CPU_RET_1_0 &CPU_NONRET_1_0 + &CLUSTER_RET_1 &CLUSTER_NONRET_1>; + + cpu_intc10: interrupt-controller { + #interrupt-cells = <1>; + compatible = "riscv,cpu-intc"; + interrupt-controller; + }; + }; + + cpu@11 { + device_type = "cpu"; + compatible = "riscv"; + reg = <0x11>; + riscv,isa = "rv64imafdc"; + mmu-type = "riscv,sv48"; + cpu-idle-states = <&CPU_RET_1_0 &CPU_NONRET_1_0 + &CLUSTER_RET_1 &CLUSTER_NONRET_1>; + + cpu_intc11: interrupt-controller { + #interrupt-cells = <1>; + compatible = "riscv,cpu-intc"; + interrupt-controller; + }; + }; + + idle-states { + CPU_RET_0_0: cpu-retentive-0-0 { + compatible = "riscv,idle-state"; + riscv,sbi-suspend-param = <0x10000000>; + entry-latency-us = <20>; + exit-latency-us = <40>; + min-residency-us = <80>; + }; + + CPU_NONRET_0_0: cpu-nonretentive-0-0 { + compatible = "riscv,idle-state"; + riscv,sbi-suspend-param = <0x90000000>; + entry-latency-us = <250>; + exit-latency-us = <500>; + min-residency-us = <950>; + }; + + CLUSTER_RET_0: cluster-retentive-0 { + compatible = "riscv,idle-state"; + riscv,sbi-suspend-param = <0x11000000>; + local-timer-stop; + entry-latency-us = <50>; + exit-latency-us = <100>; + min-residency-us = <250>; + wakeup-latency-us = <130>; + }; + + CLUSTER_NONRET_0: cluster-nonretentive-0 { + compatible = "riscv,idle-state"; + riscv,sbi-suspend-param = <0x91000000>; + local-timer-stop; + entry-latency-us = <600>; + exit-latency-us = <1100>; + min-residency-us = <2700>; + wakeup-latency-us = <1500>; + }; + + CPU_RET_1_0: cpu-retentive-1-0 { + compatible = "riscv,idle-state"; + riscv,sbi-suspend-param = <0x10000010>; + entry-latency-us = <20>; + exit-latency-us = <40>; + min-residency-us = <80>; + }; + + CPU_NONRET_1_0: cpu-nonretentive-1-0 { + compatible = "riscv,idle-state"; + riscv,sbi-suspend-param = <0x90000010>; + entry-latency-us = <250>; + exit-latency-us = <500>; + min-residency-us = <950>; + }; + + CLUSTER_RET_1: cluster-retentive-1 { + compatible = "riscv,idle-state"; + riscv,sbi-suspend-param = <0x11000010>; + local-timer-stop; + entry-latency-us = <50>; + exit-latency-us = <100>; + min-residency-us = <250>; + wakeup-latency-us = <130>; + }; + + CLUSTER_NONRET_1: cluster-nonretentive-1 { + compatible = "riscv,idle-state"; + riscv,sbi-suspend-param = <0x91000010>; + local-timer-stop; + entry-latency-us = <600>; + exit-latency-us = <1100>; + min-residency-us = <2700>; + wakeup-latency-us = <1500>; + }; + }; + }; + ... diff --git a/Documentation/devicetree/bindings/dma/mediatek,uart-dma.yaml b/Documentation/devicetree/bindings/dma/mediatek,uart-dma.yaml new file mode 100644 index 000000000000..54d68fc688b5 --- /dev/null +++ b/Documentation/devicetree/bindings/dma/mediatek,uart-dma.yaml @@ -0,0 +1,122 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/dma/mediatek,uart-dma.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: MediaTek UART APDMA controller + +maintainers: + - Long Cheng <long.cheng@mediatek.com> + +description: | + The MediaTek UART APDMA controller provides DMA capabilities + for the UART peripheral bus. + +allOf: + - $ref: "dma-controller.yaml#" + +properties: + compatible: + oneOf: + - items: + - enum: + - mediatek,mt2712-uart-dma + - mediatek,mt8516-uart-dma + - const: mediatek,mt6577-uart-dma + - enum: + - mediatek,mt6577-uart-dma + + reg: + minItems: 1 + maxItems: 16 + + interrupts: + description: | + TX, RX interrupt lines for each UART APDMA channel + minItems: 1 + maxItems: 16 + + clocks: + description: Must contain one entry for the APDMA main clock + maxItems: 1 + + clock-names: + const: apdma + + "#dma-cells": + const: 1 + description: | + The first cell specifies the UART APDMA channel number + + dma-requests: + description: | + Number of virtual channels of the UART APDMA controller + maximum: 16 + + mediatek,dma-33bits: + type: boolean + description: Enable 33-bits UART APDMA support + +required: + - compatible + - reg + - interrupts + +additionalProperties: false + +if: + not: + required: + - dma-requests +then: + properties: + interrupts: + maxItems: 8 + reg: + maxItems: 8 + +examples: + - | + #include <dt-bindings/interrupt-controller/arm-gic.h> + #include <dt-bindings/clock/mt2712-clk.h> + soc { + #address-cells = <2>; + #size-cells = <2>; + + apdma: dma-controller@11000400 { + compatible = "mediatek,mt2712-uart-dma", + "mediatek,mt6577-uart-dma"; + reg = <0 0x11000400 0 0x80>, + <0 0x11000480 0 0x80>, + <0 0x11000500 0 0x80>, + <0 0x11000580 0 0x80>, + <0 0x11000600 0 0x80>, + <0 0x11000680 0 0x80>, + <0 0x11000700 0 0x80>, + <0 0x11000780 0 0x80>, + <0 0x11000800 0 0x80>, + <0 0x11000880 0 0x80>, + <0 0x11000900 0 0x80>, + <0 0x11000980 0 0x80>; + interrupts = <GIC_SPI 103 IRQ_TYPE_LEVEL_LOW>, + <GIC_SPI 104 IRQ_TYPE_LEVEL_LOW>, + <GIC_SPI 105 IRQ_TYPE_LEVEL_LOW>, + <GIC_SPI 106 IRQ_TYPE_LEVEL_LOW>, + <GIC_SPI 107 IRQ_TYPE_LEVEL_LOW>, + <GIC_SPI 108 IRQ_TYPE_LEVEL_LOW>, + <GIC_SPI 109 IRQ_TYPE_LEVEL_LOW>, + <GIC_SPI 110 IRQ_TYPE_LEVEL_LOW>, + <GIC_SPI 111 IRQ_TYPE_LEVEL_LOW>, + <GIC_SPI 112 IRQ_TYPE_LEVEL_LOW>, + <GIC_SPI 113 IRQ_TYPE_LEVEL_LOW>, + <GIC_SPI 114 IRQ_TYPE_LEVEL_LOW>; + dma-requests = <12>; + clocks = <&pericfg CLK_PERI_AP_DMA>; + clock-names = "apdma"; + mediatek,dma-33bits; + #dma-cells = <1>; + }; + }; + +... diff --git a/Documentation/devicetree/bindings/dma/mtk-uart-apdma.txt b/Documentation/devicetree/bindings/dma/mtk-uart-apdma.txt deleted file mode 100644 index fef9c1eeb264..000000000000 --- a/Documentation/devicetree/bindings/dma/mtk-uart-apdma.txt +++ /dev/null @@ -1,56 +0,0 @@ -* Mediatek UART APDMA Controller - -Required properties: -- compatible should contain: - * "mediatek,mt2712-uart-dma" for MT2712 compatible APDMA - * "mediatek,mt6577-uart-dma" for MT6577 and all of the above - * "mediatek,mt8516-uart-dma", "mediatek,mt6577" for MT8516 SoC - -- reg: The base address of the APDMA register bank. - -- interrupts: A single interrupt specifier. - One interrupt per dma-requests, or 8 if no dma-requests property is present - -- dma-requests: The number of DMA channels - -- clocks : Must contain an entry for each entry in clock-names. - See ../clocks/clock-bindings.txt for details. -- clock-names: The APDMA clock for register accesses - -- mediatek,dma-33bits: Present if the DMA requires support - -Examples: - - apdma: dma-controller@11000400 { - compatible = "mediatek,mt2712-uart-dma", - "mediatek,mt6577-uart-dma"; - reg = <0 0x11000400 0 0x80>, - <0 0x11000480 0 0x80>, - <0 0x11000500 0 0x80>, - <0 0x11000580 0 0x80>, - <0 0x11000600 0 0x80>, - <0 0x11000680 0 0x80>, - <0 0x11000700 0 0x80>, - <0 0x11000780 0 0x80>, - <0 0x11000800 0 0x80>, - <0 0x11000880 0 0x80>, - <0 0x11000900 0 0x80>, - <0 0x11000980 0 0x80>; - interrupts = <GIC_SPI 103 IRQ_TYPE_LEVEL_LOW>, - <GIC_SPI 104 IRQ_TYPE_LEVEL_LOW>, - <GIC_SPI 105 IRQ_TYPE_LEVEL_LOW>, - <GIC_SPI 106 IRQ_TYPE_LEVEL_LOW>, - <GIC_SPI 107 IRQ_TYPE_LEVEL_LOW>, - <GIC_SPI 108 IRQ_TYPE_LEVEL_LOW>, - <GIC_SPI 109 IRQ_TYPE_LEVEL_LOW>, - <GIC_SPI 110 IRQ_TYPE_LEVEL_LOW>, - <GIC_SPI 111 IRQ_TYPE_LEVEL_LOW>, - <GIC_SPI 112 IRQ_TYPE_LEVEL_LOW>, - <GIC_SPI 113 IRQ_TYPE_LEVEL_LOW>, - <GIC_SPI 114 IRQ_TYPE_LEVEL_LOW>; - dma-requests = <12>; - clocks = <&pericfg CLK_PERI_AP_DMA>; - clock-names = "apdma"; - mediatek,dma-33bits; - #dma-cells = <1>; - }; diff --git a/Documentation/devicetree/bindings/dma/renesas,rz-dmac.yaml b/Documentation/devicetree/bindings/dma/renesas,rz-dmac.yaml index 7a4f415d74dc..1e25c5b0fb4d 100644 --- a/Documentation/devicetree/bindings/dma/renesas,rz-dmac.yaml +++ b/Documentation/devicetree/bindings/dma/renesas,rz-dmac.yaml @@ -4,7 +4,7 @@ $id: http://devicetree.org/schemas/dma/renesas,rz-dmac.yaml# $schema: http://devicetree.org/meta-schemas/core.yaml# -title: Renesas RZ/G2L DMA Controller +title: Renesas RZ/{G2L,G2UL,V2L} DMA Controller maintainers: - Biju Das <biju.das.jz@bp.renesas.com> @@ -16,7 +16,9 @@ properties: compatible: items: - enum: + - renesas,r9a07g043-dmac # RZ/G2UL - renesas,r9a07g044-dmac # RZ/G2{L,LC} + - renesas,r9a07g054-dmac # RZ/V2L - const: renesas,rz-dmac reg: diff --git a/Documentation/devicetree/bindings/gpio/sifive,gpio.yaml b/Documentation/devicetree/bindings/gpio/sifive,gpio.yaml index 427c5873f96a..939e31c48081 100644 --- a/Documentation/devicetree/bindings/gpio/sifive,gpio.yaml +++ b/Documentation/devicetree/bindings/gpio/sifive,gpio.yaml @@ -79,7 +79,7 @@ examples: interrupts = <7>, <8>, <9>, <10>, <11>, <12>, <13>, <14>, <15>, <16>, <17>, <18>, <19>, <20>, <21>, <22>; reg = <0x10060000 0x1000>; - clocks = <&tlclk PRCI_CLK_TLCLK>; + clocks = <&tlclk FU540_PRCI_CLK_TLCLK>; gpio-controller; #gpio-cells = <2>; interrupt-controller; diff --git a/Documentation/devicetree/bindings/hwlock/ti,omap-hwspinlock.yaml b/Documentation/devicetree/bindings/hwlock/ti,omap-hwspinlock.yaml index ae1b37dbee75..0a955c7b9706 100644 --- a/Documentation/devicetree/bindings/hwlock/ti,omap-hwspinlock.yaml +++ b/Documentation/devicetree/bindings/hwlock/ti,omap-hwspinlock.yaml @@ -39,39 +39,8 @@ additionalProperties: false examples: - | - /* OMAP4 SoCs */ - hwspinlock: spinlock@4a0f6000 { + spinlock@4a0f6000 { compatible = "ti,omap4-hwspinlock"; reg = <0x4a0f6000 0x1000>; #hwlock-cells = <1>; }; - - - | - / { - /* K3 AM65x SoCs */ - model = "Texas Instruments K3 AM654 SoC"; - compatible = "ti,am654-evm", "ti,am654"; - #address-cells = <2>; - #size-cells = <2>; - - bus@100000 { - compatible = "simple-bus"; - #address-cells = <2>; - #size-cells = <2>; - ranges = <0x00 0x00100000 0x00 0x00100000 0x00 0x00020000>, /* ctrl mmr */ - <0x00 0x30800000 0x00 0x30800000 0x00 0x0bc00000>; /* Main NavSS */ - - bus@30800000 { - compatible = "simple-mfd"; - #address-cells = <2>; - #size-cells = <2>; - ranges = <0x00 0x30800000 0x00 0x30800000 0x00 0x0bc00000>; - - spinlock@30e00000 { - compatible = "ti,am654-hwspinlock"; - reg = <0x00 0x30e00000 0x00 0x1000>; - #hwlock-cells = <1>; - }; - }; - }; - }; diff --git a/Documentation/devicetree/bindings/input/mediatek,mt6779-keypad.yaml b/Documentation/devicetree/bindings/input/mediatek,mt6779-keypad.yaml new file mode 100644 index 000000000000..b1770640f94b --- /dev/null +++ b/Documentation/devicetree/bindings/input/mediatek,mt6779-keypad.yaml @@ -0,0 +1,77 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/input/mediatek,mt6779-keypad.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Mediatek's Keypad Controller device tree bindings + +maintainers: + - Fengping Yu <fengping.yu@mediatek.com> + +allOf: + - $ref: "/schemas/input/matrix-keymap.yaml#" + +description: | + Mediatek's Keypad controller is used to interface a SoC with a matrix-type + keypad device. The keypad controller supports multiple row and column lines. + A key can be placed at each intersection of a unique row and a unique column. + The keypad controller can sense a key-press and key-release and report the + event using a interrupt to the cpu. + +properties: + compatible: + oneOf: + - const: mediatek,mt6779-keypad + - items: + - enum: + - mediatek,mt6873-keypad + - const: mediatek,mt6779-keypad + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + clocks: + maxItems: 1 + + clock-names: + items: + - const: kpd + + wakeup-source: + description: use any event on keypad as wakeup event + type: boolean + + debounce-delay-ms: + maximum: 256 + default: 16 + +required: + - compatible + - reg + - interrupts + - clocks + - clock-names + +additionalProperties: false + +examples: + - | + #include <dt-bindings/input/input.h> + #include <dt-bindings/interrupt-controller/arm-gic.h> + + soc { + #address-cells = <2>; + #size-cells = <2>; + + keyboard@10010000 { + compatible = "mediatek,mt6779-keypad"; + reg = <0 0x10010000 0 0x1000>; + interrupts = <GIC_SPI 75 IRQ_TYPE_EDGE_FALLING>; + clocks = <&clk26m>; + clock-names = "kpd"; + }; + }; diff --git a/Documentation/devicetree/bindings/input/mtk-pmic-keys.txt b/Documentation/devicetree/bindings/input/mtk-pmic-keys.txt index 535d92885372..9d00f2a8e13a 100644 --- a/Documentation/devicetree/bindings/input/mtk-pmic-keys.txt +++ b/Documentation/devicetree/bindings/input/mtk-pmic-keys.txt @@ -9,7 +9,10 @@ For MT6397/MT6323 MFD bindings see: Documentation/devicetree/bindings/mfd/mt6397.txt Required properties: -- compatible: "mediatek,mt6397-keys" or "mediatek,mt6323-keys" +- compatible: Should be one of: + - "mediatek,mt6397-keys" + - "mediatek,mt6323-keys" + - "mediatek,mt6358-keys" - linux,keycodes: See Documentation/devicetree/bindings/input/input.yaml Optional Properties: diff --git a/Documentation/devicetree/bindings/input/touchscreen/imagis,ist3038c.yaml b/Documentation/devicetree/bindings/input/touchscreen/imagis,ist3038c.yaml new file mode 100644 index 000000000000..e3a2b871e50c --- /dev/null +++ b/Documentation/devicetree/bindings/input/touchscreen/imagis,ist3038c.yaml @@ -0,0 +1,74 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/input/touchscreen/imagis,ist3038c.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Imagis IST30XXC family touchscreen controller bindings + +maintainers: + - Markuss Broks <markuss.broks@gmail.com> + +allOf: + - $ref: touchscreen.yaml# + +properties: + $nodename: + pattern: "^touchscreen@[0-9a-f]+$" + + compatible: + enum: + - imagis,ist3038c + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + vdd-supply: + description: Power supply regulator for the chip + + vddio-supply: + description: Power supply regulator for the I2C bus + + touchscreen-size-x: true + touchscreen-size-y: true + touchscreen-fuzz-x: true + touchscreen-fuzz-y: true + touchscreen-inverted-x: true + touchscreen-inverted-y: true + touchscreen-swapped-x-y: true + +additionalProperties: false + +required: + - compatible + - reg + - interrupts + - touchscreen-size-x + - touchscreen-size-y + +examples: + - | + #include <dt-bindings/interrupt-controller/irq.h> + i2c { + #address-cells = <1>; + #size-cells = <0>; + touchscreen@50 { + compatible = "imagis,ist3038c"; + reg = <0x50>; + interrupt-parent = <&gpio>; + interrupts = <13 IRQ_TYPE_EDGE_FALLING>; + vdd-supply = <&ldo1_reg>; + vddio-supply = <&ldo2_reg>; + touchscreen-size-x = <720>; + touchscreen-size-y = <1280>; + touchscreen-fuzz-x = <10>; + touchscreen-fuzz-y = <10>; + touchscreen-inverted-x; + touchscreen-inverted-y; + }; + }; + +... diff --git a/Documentation/devicetree/bindings/mfd/google,cros-ec.yaml b/Documentation/devicetree/bindings/mfd/google,cros-ec.yaml index d8b495f71282..afec0bd2f1de 100644 --- a/Documentation/devicetree/bindings/mfd/google,cros-ec.yaml +++ b/Documentation/devicetree/bindings/mfd/google,cros-ec.yaml @@ -85,6 +85,10 @@ properties: ec-pwm: $ref: "/schemas/pwm/google,cros-ec-pwm.yaml#" + deprecated: true + + pwm: + $ref: "/schemas/pwm/google,cros-ec-pwm.yaml#" keyboard-controller: $ref: "/schemas/input/google,cros-ec-keyb.yaml#" diff --git a/Documentation/devicetree/bindings/net/qcom,ethqos.txt b/Documentation/devicetree/bindings/net/qcom,ethqos.txt index fcf5035810b5..1f5746849a71 100644 --- a/Documentation/devicetree/bindings/net/qcom,ethqos.txt +++ b/Documentation/devicetree/bindings/net/qcom,ethqos.txt @@ -7,7 +7,9 @@ This device has following properties: Required properties: -- compatible: Should be qcom,qcs404-ethqos" +- compatible: Should be one of: + "qcom,qcs404-ethqos" + "qcom,sm8150-ethqos" - reg: Address and length of the register set for the device diff --git a/Documentation/devicetree/bindings/pci/sifive,fu740-pcie.yaml b/Documentation/devicetree/bindings/pci/sifive,fu740-pcie.yaml index 392f0ab488c2..195e6afeb169 100644 --- a/Documentation/devicetree/bindings/pci/sifive,fu740-pcie.yaml +++ b/Documentation/devicetree/bindings/pci/sifive,fu740-pcie.yaml @@ -104,7 +104,7 @@ examples: <0x0 0x0 0x0 0x2 &plic0 58>, <0x0 0x0 0x0 0x3 &plic0 59>, <0x0 0x0 0x0 0x4 &plic0 60>; - clocks = <&prci PRCI_CLK_PCIE_AUX>; + clocks = <&prci FU740_PRCI_CLK_PCIE_AUX>; resets = <&prci 4>; pwren-gpios = <&gpio 5 0>; reset-gpios = <&gpio 8 0>; diff --git a/Documentation/devicetree/bindings/pwm/allwinner,sun4i-a10-pwm.yaml b/Documentation/devicetree/bindings/pwm/allwinner,sun4i-a10-pwm.yaml index 800d511502c4..e93e935564fb 100644 --- a/Documentation/devicetree/bindings/pwm/allwinner,sun4i-a10-pwm.yaml +++ b/Documentation/devicetree/bindings/pwm/allwinner,sun4i-a10-pwm.yaml @@ -52,33 +52,36 @@ properties: resets: maxItems: 1 -if: - properties: - compatible: - contains: - const: allwinner,sun50i-h6-pwm - -then: - properties: - clocks: - maxItems: 2 - - clock-names: - items: - - const: mod - - const: bus - - required: - - clock-names - - resets - -else: - properties: - clocks: - maxItems: 1 + +allOf: + - $ref: pwm.yaml# + + - if: + properties: + compatible: + contains: + const: allwinner,sun50i-h6-pwm + + then: + properties: + clocks: + maxItems: 2 + + clock-names: + items: + - const: mod + - const: bus + + required: + - clock-names + - resets + + else: + properties: + clocks: + maxItems: 1 required: - - "#pwm-cells" - compatible - reg - clocks diff --git a/Documentation/devicetree/bindings/pwm/brcm,bcm7038-pwm.yaml b/Documentation/devicetree/bindings/pwm/brcm,bcm7038-pwm.yaml index 4080e098f746..119de3d7f9dd 100644 --- a/Documentation/devicetree/bindings/pwm/brcm,bcm7038-pwm.yaml +++ b/Documentation/devicetree/bindings/pwm/brcm,bcm7038-pwm.yaml @@ -28,7 +28,6 @@ properties: required: - compatible - reg - - "#pwm-cells" - clocks additionalProperties: false diff --git a/Documentation/devicetree/bindings/pwm/google,cros-ec-pwm.yaml b/Documentation/devicetree/bindings/pwm/google,cros-ec-pwm.yaml index 4cfbffd8414a..7ab6912a845f 100644 --- a/Documentation/devicetree/bindings/pwm/google,cros-ec-pwm.yaml +++ b/Documentation/devicetree/bindings/pwm/google,cros-ec-pwm.yaml @@ -16,6 +16,9 @@ description: | An EC PWM node should be only found as a sub-node of the EC node (see Documentation/devicetree/bindings/mfd/google,cros-ec.yaml). +allOf: + - $ref: pwm.yaml# + properties: compatible: const: google,cros-ec-pwm @@ -39,7 +42,7 @@ examples: compatible = "google,cros-ec-spi"; reg = <0>; - cros_ec_pwm: ec-pwm { + cros_ec_pwm: pwm { compatible = "google,cros-ec-pwm"; #pwm-cells = <1>; }; diff --git a/Documentation/devicetree/bindings/pwm/imx-pwm.yaml b/Documentation/devicetree/bindings/pwm/imx-pwm.yaml index 379d693889f6..b3da4e629341 100644 --- a/Documentation/devicetree/bindings/pwm/imx-pwm.yaml +++ b/Documentation/devicetree/bindings/pwm/imx-pwm.yaml @@ -9,6 +9,9 @@ title: Freescale i.MX PWM controller maintainers: - Philipp Zabel <p.zabel@pengutronix.de> +allOf: + - $ref: pwm.yaml# + properties: "#pwm-cells": description: | @@ -59,7 +62,6 @@ properties: maxItems: 1 required: - - "#pwm-cells" - compatible - reg - clocks diff --git a/Documentation/devicetree/bindings/pwm/imx-tpm-pwm.yaml b/Documentation/devicetree/bindings/pwm/imx-tpm-pwm.yaml index fe9ef42544f1..8bef9dfeba9a 100644 --- a/Documentation/devicetree/bindings/pwm/imx-tpm-pwm.yaml +++ b/Documentation/devicetree/bindings/pwm/imx-tpm-pwm.yaml @@ -13,6 +13,9 @@ description: | The TPM counter and period counter are shared between multiple channels, so all channels should use same period setting. +allOf: + - $ref: pwm.yaml# + properties: "#pwm-cells": const: 3 @@ -34,7 +37,6 @@ properties: maxItems: 1 required: - - "#pwm-cells" - compatible - reg - clocks diff --git a/Documentation/devicetree/bindings/pwm/intel,keembay-pwm.yaml b/Documentation/devicetree/bindings/pwm/intel,keembay-pwm.yaml index ff6880a02ce6..ec9f6bab798c 100644 --- a/Documentation/devicetree/bindings/pwm/intel,keembay-pwm.yaml +++ b/Documentation/devicetree/bindings/pwm/intel,keembay-pwm.yaml @@ -31,7 +31,6 @@ required: - compatible - reg - clocks - - '#pwm-cells' additionalProperties: false diff --git a/Documentation/devicetree/bindings/pwm/intel,lgm-pwm.yaml b/Documentation/devicetree/bindings/pwm/intel,lgm-pwm.yaml index 11a606536169..59d7c4d864c1 100644 --- a/Documentation/devicetree/bindings/pwm/intel,lgm-pwm.yaml +++ b/Documentation/devicetree/bindings/pwm/intel,lgm-pwm.yaml @@ -9,6 +9,9 @@ title: LGM SoC PWM fan controller maintainers: - Rahul Tanwar <rtanwar@maxlinear.com> +allOf: + - $ref: pwm.yaml# + properties: compatible: const: intel,lgm-pwm diff --git a/Documentation/devicetree/bindings/pwm/iqs620a-pwm.yaml b/Documentation/devicetree/bindings/pwm/iqs620a-pwm.yaml index 1d7c27be50da..0a46af240d83 100644 --- a/Documentation/devicetree/bindings/pwm/iqs620a-pwm.yaml +++ b/Documentation/devicetree/bindings/pwm/iqs620a-pwm.yaml @@ -15,6 +15,9 @@ description: | Documentation/devicetree/bindings/mfd/iqs62x.yaml for further details as well as an example. +allOf: + - $ref: pwm.yaml# + properties: compatible: enum: @@ -25,7 +28,6 @@ properties: required: - compatible - - "#pwm-cells" additionalProperties: false diff --git a/Documentation/devicetree/bindings/pwm/mxs-pwm.yaml b/Documentation/devicetree/bindings/pwm/mxs-pwm.yaml index 8740e076061e..a34cbc13f691 100644 --- a/Documentation/devicetree/bindings/pwm/mxs-pwm.yaml +++ b/Documentation/devicetree/bindings/pwm/mxs-pwm.yaml @@ -10,6 +10,9 @@ maintainers: - Shawn Guo <shawnguo@kernel.org> - Anson Huang <anson.huang@nxp.com> +allOf: + - $ref: pwm.yaml# + properties: compatible: enum: @@ -28,7 +31,6 @@ properties: required: - compatible - reg - - "#pwm-cells" - fsl,pwm-number additionalProperties: false diff --git a/Documentation/devicetree/bindings/pwm/pwm-mtk-disp.txt b/Documentation/devicetree/bindings/pwm/pwm-mtk-disp.txt index 902b271891ae..691e58b6c223 100644 --- a/Documentation/devicetree/bindings/pwm/pwm-mtk-disp.txt +++ b/Documentation/devicetree/bindings/pwm/pwm-mtk-disp.txt @@ -6,6 +6,7 @@ Required properties: - "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. + - "mediatek,mt8183-disp-pwm": found on mt8183 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 the cell format. diff --git a/Documentation/devicetree/bindings/pwm/pwm-rockchip.yaml b/Documentation/devicetree/bindings/pwm/pwm-rockchip.yaml index 81a54a4e8e3e..a336ff9364a9 100644 --- a/Documentation/devicetree/bindings/pwm/pwm-rockchip.yaml +++ b/Documentation/devicetree/bindings/pwm/pwm-rockchip.yaml @@ -51,42 +51,44 @@ properties: required: - compatible - reg - - "#pwm-cells" - -if: - properties: - compatible: - contains: - enum: - - rockchip,rk3328-pwm - - rockchip,rv1108-pwm - -then: - properties: - clocks: - items: - - description: Used to derive the functional clock for the device. - - description: Used as the APB bus clock. - - clock-names: - items: - - const: pwm - - const: pclk - - required: - - clocks - - clock-names - -else: - properties: - clocks: - maxItems: 1 - description: - Used both to derive the functional clock - for the device and as the bus clock. - - required: - - clocks + +allOf: + - $ref: pwm.yaml# + + - if: + properties: + compatible: + contains: + enum: + - rockchip,rk3328-pwm + - rockchip,rv1108-pwm + + then: + properties: + clocks: + items: + - description: Used to derive the functional clock for the device. + - description: Used as the APB bus clock. + + clock-names: + items: + - const: pwm + - const: pclk + + required: + - clocks + - clock-names + + else: + properties: + clocks: + maxItems: 1 + description: + Used both to derive the functional clock + for the device and as the bus clock. + + required: + - clocks additionalProperties: false diff --git a/Documentation/devicetree/bindings/pwm/pwm-samsung.yaml b/Documentation/devicetree/bindings/pwm/pwm-samsung.yaml index 188679cb8b8c..fe603fb1b2cc 100644 --- a/Documentation/devicetree/bindings/pwm/pwm-samsung.yaml +++ b/Documentation/devicetree/bindings/pwm/pwm-samsung.yaml @@ -86,7 +86,6 @@ required: - clocks - clock-names - compatible - - "#pwm-cells" - reg additionalProperties: false diff --git a/Documentation/devicetree/bindings/pwm/pwm-sifive.yaml b/Documentation/devicetree/bindings/pwm/pwm-sifive.yaml index db41cd7bf150..605c1766dba8 100644 --- a/Documentation/devicetree/bindings/pwm/pwm-sifive.yaml +++ b/Documentation/devicetree/bindings/pwm/pwm-sifive.yaml @@ -21,6 +21,9 @@ description: https://github.com/sifive/sifive-blocks/tree/master/src/main/scala/devices/pwm +allOf: + - $ref: pwm.yaml# + properties: compatible: items: @@ -54,7 +57,6 @@ required: - compatible - reg - clocks - - "#pwm-cells" - interrupts additionalProperties: false diff --git a/Documentation/devicetree/bindings/pwm/pwm-tiecap.yaml b/Documentation/devicetree/bindings/pwm/pwm-tiecap.yaml index ed35b6cc48d5..3840ae709bc6 100644 --- a/Documentation/devicetree/bindings/pwm/pwm-tiecap.yaml +++ b/Documentation/devicetree/bindings/pwm/pwm-tiecap.yaml @@ -47,7 +47,6 @@ properties: required: - compatible - reg - - "#pwm-cells" - clocks - clock-names diff --git a/Documentation/devicetree/bindings/pwm/pwm-tiehrpwm.yaml b/Documentation/devicetree/bindings/pwm/pwm-tiehrpwm.yaml index ee312cb210e6..70a8f766212e 100644 --- a/Documentation/devicetree/bindings/pwm/pwm-tiehrpwm.yaml +++ b/Documentation/devicetree/bindings/pwm/pwm-tiehrpwm.yaml @@ -48,7 +48,6 @@ properties: required: - compatible - reg - - "#pwm-cells" - clocks - clock-names diff --git a/Documentation/devicetree/bindings/pwm/renesas,pwm-rcar.yaml b/Documentation/devicetree/bindings/pwm/renesas,pwm-rcar.yaml index 7ea1070b4b3a..1c94acbc2b4a 100644 --- a/Documentation/devicetree/bindings/pwm/renesas,pwm-rcar.yaml +++ b/Documentation/devicetree/bindings/pwm/renesas,pwm-rcar.yaml @@ -59,21 +59,23 @@ properties: required: - compatible - reg - - '#pwm-cells' - clocks - power-domains -if: - not: - properties: - compatible: - contains: - enum: - - renesas,pwm-r8a7778 - - renesas,pwm-r8a7779 -then: - required: - - resets +allOf: + - $ref: pwm.yaml# + + - if: + not: + properties: + compatible: + contains: + enum: + - renesas,pwm-r8a7778 + - renesas,pwm-r8a7779 + then: + required: + - resets additionalProperties: false diff --git a/Documentation/devicetree/bindings/pwm/renesas,tpu-pwm.yaml b/Documentation/devicetree/bindings/pwm/renesas,tpu-pwm.yaml index 1f5c6384182e..c6b2ab56b7fe 100644 --- a/Documentation/devicetree/bindings/pwm/renesas,tpu-pwm.yaml +++ b/Documentation/devicetree/bindings/pwm/renesas,tpu-pwm.yaml @@ -68,7 +68,6 @@ properties: required: - compatible - reg - - '#pwm-cells' - clocks - power-domains diff --git a/Documentation/devicetree/bindings/pwm/toshiba,pwm-visconti.yaml b/Documentation/devicetree/bindings/pwm/toshiba,pwm-visconti.yaml index d350f5edfb67..46622661e5fb 100644 --- a/Documentation/devicetree/bindings/pwm/toshiba,pwm-visconti.yaml +++ b/Documentation/devicetree/bindings/pwm/toshiba,pwm-visconti.yaml @@ -9,6 +9,9 @@ title: Toshiba Visconti PWM Controller maintainers: - Nobuhiro Iwamatsu <nobuhiro1.iwamatsu@toshiba.co.jp> +allOf: + - $ref: pwm.yaml# + properties: compatible: items: @@ -23,7 +26,6 @@ properties: required: - compatible - reg - - '#pwm-cells' additionalProperties: false diff --git a/Documentation/devicetree/bindings/remoteproc/mtk,scp.yaml b/Documentation/devicetree/bindings/remoteproc/mtk,scp.yaml index d21a25ee96e6..5b693a2d049c 100644 --- a/Documentation/devicetree/bindings/remoteproc/mtk,scp.yaml +++ b/Documentation/devicetree/bindings/remoteproc/mtk,scp.yaml @@ -17,6 +17,7 @@ properties: compatible: enum: - mediatek,mt8183-scp + - mediatek,mt8186-scp - mediatek,mt8192-scp - mediatek,mt8195-scp diff --git a/Documentation/devicetree/bindings/remoteproc/qcom,hexagon-v56.txt b/Documentation/devicetree/bindings/remoteproc/qcom,hexagon-v56.txt deleted file mode 100644 index 1337a3d93d35..000000000000 --- a/Documentation/devicetree/bindings/remoteproc/qcom,hexagon-v56.txt +++ /dev/null @@ -1,140 +0,0 @@ -Qualcomm Technology Inc. Hexagon v56 Peripheral Image Loader - -This document defines the binding for a component that loads and boots firmware -on the Qualcomm Technology Inc. Hexagon v56 core. - -- compatible: - Usage: required - Value type: <string> - Definition: must be one of: - "qcom,qcs404-cdsp-pil", - "qcom,sdm845-adsp-pil" - -- reg: - Usage: required - Value type: <prop-encoded-array> - Definition: must specify the base address and size of the qdsp6ss register - -- interrupts-extended: - Usage: required - Value type: <prop-encoded-array> - Definition: must list the watchdog, fatal IRQs ready, handover and - stop-ack IRQs - -- interrupt-names: - Usage: required - Value type: <stringlist> - Definition: must be "wdog", "fatal", "ready", "handover", "stop-ack" - -- clocks: - Usage: required - Value type: <prop-encoded-array> - Definition: List of phandles and clock specifier pairs for the Hexagon, - per clock-names below. - -- clock-names: - Usage: required for SDM845 ADSP - Value type: <stringlist> - Definition: List of clock input name strings sorted in the same - order as the clocks property. Definition must have - "xo", "sway_cbcr", "lpass_ahbs_aon_cbcr", - "lpass_ahbm_aon_cbcr", "qdsp6ss_xo", "qdsp6ss_sleep" - and "qdsp6ss_core". - -- clock-names: - Usage: required for QCS404 CDSP - Value type: <stringlist> - Definition: List of clock input name strings sorted in the same - order as the clocks property. Definition must have - "xo", "sway", "tbu", "bimc", "ahb_aon", "q6ss_slave", - "q6ss_master", "q6_axim". - -- power-domains: - Usage: required - Value type: <phandle> - Definition: reference to cx power domain node. - -- resets: - Usage: required - Value type: <phandle> - Definition: reference to the list of resets for the Hexagon. - -- reset-names: - Usage: required for SDM845 ADSP - Value type: <stringlist> - Definition: must be "pdc_sync" and "cc_lpass" - -- reset-names: - Usage: required for QCS404 CDSP - Value type: <stringlist> - Definition: must be "restart" - -- qcom,halt-regs: - Usage: required - Value type: <prop-encoded-array> - Definition: a phandle reference to a syscon representing TCSR followed - by the offset within syscon for Hexagon halt register. - -- memory-region: - Usage: required - Value type: <phandle> - Definition: reference to the reserved-memory for the firmware - -- qcom,smem-states: - Usage: required - Value type: <phandle> - Definition: reference to the smem state for requesting the Hexagon to - shut down - -- qcom,smem-state-names: - Usage: required - Value type: <stringlist> - Definition: must be "stop" - - -= SUBNODES -The adsp node may have an subnode named "glink-edge" that describes the -communication edge, channels and devices related to the Hexagon. -See ../soc/qcom/qcom,glink.txt for details on how to describe these. - -= EXAMPLE -The following example describes the resources needed to boot control the -ADSP, as it is found on SDM845 boards. - - remoteproc@17300000 { - compatible = "qcom,sdm845-adsp-pil"; - reg = <0x17300000 0x40c>; - - interrupts-extended = <&intc GIC_SPI 162 IRQ_TYPE_EDGE_RISING>, - <&adsp_smp2p_in 0 IRQ_TYPE_EDGE_RISING>, - <&adsp_smp2p_in 1 IRQ_TYPE_EDGE_RISING>, - <&adsp_smp2p_in 2 IRQ_TYPE_EDGE_RISING>, - <&adsp_smp2p_in 3 IRQ_TYPE_EDGE_RISING>; - interrupt-names = "wdog", "fatal", "ready", - "handover", "stop-ack"; - - clocks = <&rpmhcc RPMH_CXO_CLK>, - <&gcc GCC_LPASS_SWAY_CLK>, - <&lpasscc LPASS_Q6SS_AHBS_AON_CLK>, - <&lpasscc LPASS_Q6SS_AHBM_AON_CLK>, - <&lpasscc LPASS_QDSP6SS_XO_CLK>, - <&lpasscc LPASS_QDSP6SS_SLEEP_CLK>, - <&lpasscc LPASS_QDSP6SS_CORE_CLK>; - clock-names = "xo", "sway_cbcr", - "lpass_ahbs_aon_cbcr", - "lpass_ahbm_aon_cbcr", "qdsp6ss_xo", - "qdsp6ss_sleep", "qdsp6ss_core"; - - power-domains = <&rpmhpd SDM845_CX>; - - resets = <&pdc_reset PDC_AUDIO_SYNC_RESET>, - <&aoss_reset AOSS_CC_LPASS_RESTART>; - reset-names = "pdc_sync", "cc_lpass"; - - qcom,halt-regs = <&tcsr_mutex_regs 0x22000>; - - memory-region = <&pil_adsp_mem>; - - qcom,smem-states = <&adsp_smp2p_out 0>; - qcom,smem-state-names = "stop"; - }; diff --git a/Documentation/devicetree/bindings/remoteproc/qcom,qcs404-cdsp-pil.yaml b/Documentation/devicetree/bindings/remoteproc/qcom,qcs404-cdsp-pil.yaml new file mode 100644 index 000000000000..31413cfe10db --- /dev/null +++ b/Documentation/devicetree/bindings/remoteproc/qcom,qcs404-cdsp-pil.yaml @@ -0,0 +1,161 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/remoteproc/qcom,qcs404-cdsp-pil.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Qualcomm QCS404 CDSP Peripheral Image Loader + +maintainers: + - Bjorn Andersson <bjorn.andersson@linaro.org> + +description: + This document defines the binding for a component that loads and boots firmware + on the Qualcomm Technology Inc. CDSP (Compute DSP). + +properties: + compatible: + enum: + - qcom,qcs404-cdsp-pil + + reg: + maxItems: 1 + description: + The base address and size of the qdsp6ss register + + interrupts: + items: + - description: Watchdog interrupt + - description: Fatal interrupt + - description: Ready interrupt + - description: Handover interrupt + - description: Stop acknowledge interrupt + + interrupt-names: + items: + - const: wdog + - const: fatal + - const: ready + - const: handover + - const: stop-ack + + clocks: + items: + - description: XO clock + - description: SWAY clock + - description: TBU clock + - description: BIMC clock + - description: AHB AON clock + - description: Q6SS SLAVE clock + - description: Q6SS MASTER clock + - description: Q6 AXIM clock + + clock-names: + items: + - const: xo + - const: sway + - const: tbu + - const: bimc + - const: ahb_aon + - const: q6ss_slave + - const: q6ss_master + - const: q6_axim + + power-domains: + items: + - description: CX power domain + + resets: + items: + - description: AOSS restart + + reset-names: + items: + - const: restart + + memory-region: + maxItems: 1 + description: Reference to the reserved-memory for the Hexagon core + + qcom,halt-regs: + $ref: /schemas/types.yaml#/definitions/phandle-array + description: + Phandle reference to a syscon representing TCSR followed by the + three offsets within syscon for q6, modem and nc halt registers. + + qcom,smem-states: + $ref: /schemas/types.yaml#/definitions/phandle-array + description: States used by the AP to signal the Hexagon core + items: + - description: Stop the modem + + qcom,smem-state-names: + $ref: /schemas/types.yaml#/definitions/string + description: The names of the state bits used for SMP2P output + items: + - const: stop + +required: + - compatible + - reg + - interrupts + - interrupt-names + - clocks + - clock-names + - power-domains + - resets + - reset-names + - qcom,halt-regs + - memory-region + - qcom,smem-states + - qcom,smem-state-names + +additionalProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/arm-gic.h> + #include <dt-bindings/clock/qcom,gcc-qcs404.h> + #include <dt-bindings/power/qcom-rpmpd.h> + #include <dt-bindings/clock/qcom,turingcc-qcs404.h> + remoteproc@b00000 { + compatible = "qcom,qcs404-cdsp-pil"; + reg = <0x00b00000 0x4040>; + + interrupts-extended = <&intc GIC_SPI 229 IRQ_TYPE_EDGE_RISING>, + <&cdsp_smp2p_in 0 IRQ_TYPE_EDGE_RISING>, + <&cdsp_smp2p_in 1 IRQ_TYPE_EDGE_RISING>, + <&cdsp_smp2p_in 2 IRQ_TYPE_EDGE_RISING>, + <&cdsp_smp2p_in 3 IRQ_TYPE_EDGE_RISING>; + interrupt-names = "wdog", "fatal", "ready", + "handover", "stop-ack"; + + clocks = <&xo_board>, + <&gcc GCC_CDSP_CFG_AHB_CLK>, + <&gcc GCC_CDSP_TBU_CLK>, + <&gcc GCC_BIMC_CDSP_CLK>, + <&turingcc TURING_WRAPPER_AON_CLK>, + <&turingcc TURING_Q6SS_AHBS_AON_CLK>, + <&turingcc TURING_Q6SS_AHBM_AON_CLK>, + <&turingcc TURING_Q6SS_Q6_AXIM_CLK>; + clock-names = "xo", + "sway", + "tbu", + "bimc", + "ahb_aon", + "q6ss_slave", + "q6ss_master", + "q6_axim"; + + power-domains = <&rpmhpd SDM845_CX>; + + resets = <&gcc GCC_CDSP_RESTART>; + reset-names = "restart"; + + qcom,halt-regs = <&tcsr 0x19004>; + + memory-region = <&cdsp_fw_mem>; + + qcom,smem-states = <&cdsp_smp2p_out 0>; + qcom,smem-state-names = "stop"; + }; diff --git a/Documentation/devicetree/bindings/remoteproc/qcom,sc7280-wpss-pil.yaml b/Documentation/devicetree/bindings/remoteproc/qcom,sc7280-wpss-pil.yaml new file mode 100644 index 000000000000..2424de733ee4 --- /dev/null +++ b/Documentation/devicetree/bindings/remoteproc/qcom,sc7280-wpss-pil.yaml @@ -0,0 +1,219 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/remoteproc/qcom,sc7280-wpss-pil.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Qualcomm SC7280 WPSS Peripheral Image Loader + +maintainers: + - Bjorn Andersson <bjorn.andersson@linaro.org> + +description: + This document defines the binding for a component that loads and boots firmware + on the Qualcomm Technology Inc. WPSS. + +properties: + compatible: + enum: + - qcom,sc7280-wpss-pil + + reg: + maxItems: 1 + description: + The base address and size of the qdsp6ss register + + interrupts: + items: + - description: Watchdog interrupt + - description: Fatal interrupt + - description: Ready interrupt + - description: Handover interrupt + - description: Stop acknowledge interrupt + - description: Shutdown acknowledge interrupt + + interrupt-names: + items: + - const: wdog + - const: fatal + - const: ready + - const: handover + - const: stop-ack + - const: shutdown-ack + + clocks: + items: + - description: GCC WPSS AHB BDG Master clock + - description: GCC WPSS AHB clock + - description: GCC WPSS RSCP clock + - description: XO clock + + clock-names: + items: + - const: ahb_bdg + - const: ahb + - const: rscp + - const: xo + + power-domains: + items: + - description: CX power domain + - description: MX power domain + + power-domain-names: + items: + - const: cx + - const: mx + + resets: + items: + - description: AOSS restart + - description: PDC SYNC + + reset-names: + items: + - const: restart + - const: pdc_sync + + memory-region: + $ref: /schemas/types.yaml#/definitions/phandle + description: Reference to the reserved-memory for the Hexagon core + + firmware-name: + $ref: /schemas/types.yaml#/definitions/string + description: + The name of the firmware which should be loaded for this remote + processor. + + qcom,halt-regs: + $ref: /schemas/types.yaml#/definitions/phandle-array + description: + Phandle reference to a syscon representing TCSR followed by the + three offsets within syscon for q6, modem and nc halt registers. + + qcom,qmp: + $ref: /schemas/types.yaml#/definitions/phandle + description: Reference to the AOSS side-channel message RAM. + + qcom,smem-states: + $ref: /schemas/types.yaml#/definitions/phandle-array + description: States used by the AP to signal the Hexagon core + items: + - description: Stop the modem + + qcom,smem-state-names: + $ref: /schemas/types.yaml#/definitions/string + description: The names of the state bits used for SMP2P output + items: + - const: stop + + glink-edge: + type: object + description: | + Qualcomm G-Link subnode which represents communication edge, channels + and devices related to the ADSP. + + properties: + interrupts: + items: + - description: IRQ from WPSS to GLINK + + mboxes: + items: + - description: Mailbox for communication between APPS and WPSS + + label: + description: The names of the state bits used for SMP2P output + items: + - const: wpss + + qcom,remote-pid: + $ref: /schemas/types.yaml#/definitions/uint32 + description: ID of the shared memory used by GLINK for communication with WPSS + maxItems: 1 + + required: + - interrupts + - mboxes + - label + - qcom,remote-pid + + additionalProperties: false + +required: + - compatible + - reg + - interrupts + - interrupt-names + - clocks + - clock-names + - power-domains + - power-domain-names + - resets + - reset-names + - qcom,halt-regs + - memory-region + - qcom,qmp + - qcom,smem-states + - qcom,smem-state-names + - glink-edge + +additionalProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/arm-gic.h> + #include <dt-bindings/clock/qcom,gcc-sc7280.h> + #include <dt-bindings/clock/qcom,rpmh.h> + #include <dt-bindings/power/qcom-rpmpd.h> + #include <dt-bindings/reset/qcom,sdm845-aoss.h> + #include <dt-bindings/reset/qcom,sdm845-pdc.h> + #include <dt-bindings/mailbox/qcom-ipcc.h> + remoteproc@8a00000 { + compatible = "qcom,sc7280-wpss-pil"; + reg = <0x08a00000 0x10000>; + + interrupts-extended = <&intc GIC_SPI 587 IRQ_TYPE_EDGE_RISING>, + <&wpss_smp2p_in 0 IRQ_TYPE_EDGE_RISING>, + <&wpss_smp2p_in 1 IRQ_TYPE_EDGE_RISING>, + <&wpss_smp2p_in 2 IRQ_TYPE_EDGE_RISING>, + <&wpss_smp2p_in 3 IRQ_TYPE_EDGE_RISING>, + <&wpss_smp2p_in 7 IRQ_TYPE_EDGE_RISING>; + interrupt-names = "wdog", "fatal", "ready", "handover", + "stop-ack", "shutdown-ack"; + + clocks = <&gcc GCC_WPSS_AHB_BDG_MST_CLK>, + <&gcc GCC_WPSS_AHB_CLK>, + <&gcc GCC_WPSS_RSCP_CLK>, + <&rpmhcc RPMH_CXO_CLK>; + clock-names = "ahb_bdg", "ahb", + "rscp", "xo"; + + power-domains = <&rpmhpd SC7280_CX>, + <&rpmhpd SC7280_MX>; + power-domain-names = "cx", "mx"; + + memory-region = <&wpss_mem>; + + qcom,qmp = <&aoss_qmp>; + + qcom,smem-states = <&wpss_smp2p_out 0>; + qcom,smem-state-names = "stop"; + + resets = <&aoss_reset AOSS_CC_WCSS_RESTART>, + <&pdc_reset PDC_WPSS_SYNC_RESET>; + reset-names = "restart", "pdc_sync"; + + qcom,halt-regs = <&tcsr_mutex 0x37000>; + + glink-edge { + interrupts-extended = <&ipcc IPCC_CLIENT_WPSS + IPCC_MPROC_SIGNAL_GLINK_QMP + IRQ_TYPE_EDGE_RISING>; + mboxes = <&ipcc IPCC_CLIENT_WPSS + IPCC_MPROC_SIGNAL_GLINK_QMP>; + + label = "wpss"; + qcom,remote-pid = <13>; + }; + }; diff --git a/Documentation/devicetree/bindings/remoteproc/qcom,sdm845-adsp-pil.yaml b/Documentation/devicetree/bindings/remoteproc/qcom,sdm845-adsp-pil.yaml new file mode 100644 index 000000000000..1535bbbe25da --- /dev/null +++ b/Documentation/devicetree/bindings/remoteproc/qcom,sdm845-adsp-pil.yaml @@ -0,0 +1,160 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/remoteproc/qcom,sdm845-adsp-pil.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Qualcomm SDM845 ADSP Peripheral Image Loader + +maintainers: + - Bjorn Andersson <bjorn.andersson@linaro.org> + +description: + This document defines the binding for a component that loads and boots firmware + on the Qualcomm Technology Inc. ADSP. + +properties: + compatible: + enum: + - qcom,sdm845-adsp-pil + + reg: + maxItems: 1 + description: + The base address and size of the qdsp6ss register + + interrupts: + items: + - description: Watchdog interrupt + - description: Fatal interrupt + - description: Ready interrupt + - description: Handover interrupt + - description: Stop acknowledge interrupt + + interrupt-names: + items: + - const: wdog + - const: fatal + - const: ready + - const: handover + - const: stop-ack + + clocks: + items: + - description: XO clock + - description: SWAY clock + - description: LPASS AHBS AON clock + - description: LPASS AHBM AON clock + - description: QDSP XO clock + - description: Q6SP6SS SLEEP clock + - description: Q6SP6SS CORE clock + + clock-names: + items: + - const: xo + - const: sway_cbcr + - const: lpass_ahbs_aon_cbcr + - const: lpass_ahbm_aon_cbcr + - const: qdsp6ss_xo + - const: qdsp6ss_sleep + - const: qdsp6ss_core + + power-domains: + items: + - description: CX power domain + + resets: + items: + - description: PDC AUDIO SYNC RESET + - description: CC LPASS restart + + reset-names: + items: + - const: pdc_sync + - const: cc_lpass + + memory-region: + maxItems: 1 + description: Reference to the reserved-memory for the Hexagon core + + qcom,halt-regs: + $ref: /schemas/types.yaml#/definitions/phandle-array + description: + Phandle reference to a syscon representing TCSR followed by the + three offsets within syscon for q6, modem and nc halt registers. + + qcom,smem-states: + $ref: /schemas/types.yaml#/definitions/phandle-array + description: States used by the AP to signal the Hexagon core + items: + - description: Stop the modem + + qcom,smem-state-names: + $ref: /schemas/types.yaml#/definitions/string + description: The names of the state bits used for SMP2P output + items: + - const: stop + +required: + - compatible + - reg + - interrupts + - interrupt-names + - clocks + - clock-names + - power-domains + - resets + - reset-names + - qcom,halt-regs + - memory-region + - qcom,smem-states + - qcom,smem-state-names + +additionalProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/arm-gic.h> + #include <dt-bindings/clock/qcom,rpmh.h> + #include <dt-bindings/clock/qcom,gcc-sdm845.h> + #include <dt-bindings/clock/qcom,lpass-sdm845.h> + #include <dt-bindings/power/qcom-rpmpd.h> + #include <dt-bindings/reset/qcom,sdm845-pdc.h> + #include <dt-bindings/reset/qcom,sdm845-aoss.h> + remoteproc@17300000 { + compatible = "qcom,sdm845-adsp-pil"; + reg = <0x17300000 0x40c>; + + interrupts-extended = <&intc GIC_SPI 162 IRQ_TYPE_EDGE_RISING>, + <&adsp_smp2p_in 0 IRQ_TYPE_EDGE_RISING>, + <&adsp_smp2p_in 1 IRQ_TYPE_EDGE_RISING>, + <&adsp_smp2p_in 2 IRQ_TYPE_EDGE_RISING>, + <&adsp_smp2p_in 3 IRQ_TYPE_EDGE_RISING>; + interrupt-names = "wdog", "fatal", "ready", + "handover", "stop-ack"; + + clocks = <&rpmhcc RPMH_CXO_CLK>, + <&gcc GCC_LPASS_SWAY_CLK>, + <&lpasscc LPASS_Q6SS_AHBS_AON_CLK>, + <&lpasscc LPASS_Q6SS_AHBM_AON_CLK>, + <&lpasscc LPASS_QDSP6SS_XO_CLK>, + <&lpasscc LPASS_QDSP6SS_SLEEP_CLK>, + <&lpasscc LPASS_QDSP6SS_CORE_CLK>; + clock-names = "xo", "sway_cbcr", + "lpass_ahbs_aon_cbcr", + "lpass_ahbm_aon_cbcr", "qdsp6ss_xo", + "qdsp6ss_sleep", "qdsp6ss_core"; + + power-domains = <&rpmhpd SDM845_CX>; + + resets = <&pdc_reset PDC_AUDIO_SYNC_RESET>, + <&aoss_reset AOSS_CC_LPASS_RESTART>; + reset-names = "pdc_sync", "cc_lpass"; + + qcom,halt-regs = <&tcsr_mutex_regs 0x22000>; + + memory-region = <&pil_adsp_mem>; + + qcom,smem-states = <&adsp_smp2p_out 0>; + qcom,smem-state-names = "stop"; + }; diff --git a/Documentation/devicetree/bindings/riscv/cpus.yaml b/Documentation/devicetree/bindings/riscv/cpus.yaml index aa5fb64d57eb..f62f646bc695 100644 --- a/Documentation/devicetree/bindings/riscv/cpus.yaml +++ b/Documentation/devicetree/bindings/riscv/cpus.yaml @@ -99,6 +99,12 @@ properties: - compatible - interrupt-controller + cpu-idle-states: + $ref: '/schemas/types.yaml#/definitions/phandle-array' + description: | + List of phandles to idle state nodes supported + by this hart (see ./idle-states.yaml). + required: - riscv,isa - interrupt-controller diff --git a/Documentation/devicetree/bindings/rtc/allwinner,sun6i-a31-rtc.yaml b/Documentation/devicetree/bindings/rtc/allwinner,sun6i-a31-rtc.yaml index beeb90e55727..0b767fec39d8 100644 --- a/Documentation/devicetree/bindings/rtc/allwinner,sun6i-a31-rtc.yaml +++ b/Documentation/devicetree/bindings/rtc/allwinner,sun6i-a31-rtc.yaml @@ -16,16 +16,22 @@ properties: compatible: oneOf: - - const: allwinner,sun6i-a31-rtc - - const: allwinner,sun8i-a23-rtc - - const: allwinner,sun8i-h3-rtc - - const: allwinner,sun8i-r40-rtc - - const: allwinner,sun8i-v3-rtc - - const: allwinner,sun50i-h5-rtc + - enum: + - allwinner,sun6i-a31-rtc + - allwinner,sun8i-a23-rtc + - allwinner,sun8i-h3-rtc + - allwinner,sun8i-r40-rtc + - allwinner,sun8i-v3-rtc + - allwinner,sun50i-h5-rtc + - allwinner,sun50i-h6-rtc + - allwinner,sun50i-h616-rtc + - allwinner,sun50i-r329-rtc - items: - const: allwinner,sun50i-a64-rtc - const: allwinner,sun8i-h3-rtc - - const: allwinner,sun50i-h6-rtc + - items: + - const: allwinner,sun20i-d1-rtc + - const: allwinner,sun50i-r329-rtc reg: maxItems: 1 @@ -37,7 +43,12 @@ properties: - description: RTC Alarm 1 clocks: - maxItems: 1 + minItems: 1 + maxItems: 4 + + clock-names: + minItems: 1 + maxItems: 4 clock-output-names: minItems: 1 @@ -85,6 +96,7 @@ allOf: enum: - allwinner,sun8i-h3-rtc - allwinner,sun50i-h5-rtc + - allwinner,sun50i-h6-rtc then: properties: @@ -96,19 +108,68 @@ allOf: properties: compatible: contains: - const: allwinner,sun50i-h6-rtc + const: allwinner,sun50i-h616-rtc then: properties: - clock-output-names: + clocks: minItems: 3 maxItems: 3 + items: + - description: Bus clock for register access + - description: 24 MHz oscillator + - description: 32 kHz clock from the CCU + + clock-names: + minItems: 3 + maxItems: 3 + items: + - const: bus + - const: hosc + - const: pll-32k + + required: + - clocks + - clock-names - if: properties: compatible: contains: - const: allwinner,sun8i-r40-rtc + const: allwinner,sun50i-r329-rtc + + then: + properties: + clocks: + minItems: 3 + maxItems: 4 + items: + - description: Bus clock for register access + - description: 24 MHz oscillator + - description: AHB parent for internal SPI clock + - description: External 32768 Hz oscillator + + clock-names: + minItems: 3 + maxItems: 4 + items: + - const: bus + - const: hosc + - const: ahb + - const: ext-osc32k + + required: + - clocks + - clock-names + + - if: + properties: + compatible: + contains: + enum: + - allwinner,sun8i-r40-rtc + - allwinner,sun50i-h616-rtc + - allwinner,sun50i-r329-rtc then: properties: @@ -127,7 +188,6 @@ required: - compatible - reg - interrupts - - clock-output-names additionalProperties: false diff --git a/Documentation/devicetree/bindings/rtc/atmel,at91sam9-rtc.txt b/Documentation/devicetree/bindings/rtc/atmel,at91sam9-rtc.txt deleted file mode 100644 index 3f0e2a5950eb..000000000000 --- a/Documentation/devicetree/bindings/rtc/atmel,at91sam9-rtc.txt +++ /dev/null @@ -1,25 +0,0 @@ -Atmel AT91SAM9260 Real Time Timer - -Required properties: -- compatible: should be one of the following: - - "atmel,at91sam9260-rtt" - - "microchip,sam9x60-rtt", "atmel,at91sam9260-rtt" -- reg: should encode the memory region of the RTT controller -- interrupts: rtt alarm/event interrupt -- clocks: should contain the 32 KHz slow clk that will drive the RTT block. -- atmel,rtt-rtc-time-reg: should encode the GPBR register used to store - the time base when the RTT is used as an RTC. - The first cell should point to the GPBR node and the second one - encode the offset within the GPBR block (or in other words, the - GPBR register used to store the time base). - - -Example: - -rtt@fffffd20 { - compatible = "atmel,at91sam9260-rtt"; - reg = <0xfffffd20 0x10>; - interrupts = <1 4 7>; - clocks = <&clk32k>; - atmel,rtt-rtc-time-reg = <&gpbr 0x0>; -}; diff --git a/Documentation/devicetree/bindings/rtc/atmel,at91sam9260-rtt.yaml b/Documentation/devicetree/bindings/rtc/atmel,at91sam9260-rtt.yaml new file mode 100644 index 000000000000..0ef1b7ff4a77 --- /dev/null +++ b/Documentation/devicetree/bindings/rtc/atmel,at91sam9260-rtt.yaml @@ -0,0 +1,69 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +# Copyright (C) 2022 Microchip Technology, Inc. and its subsidiaries +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/rtc/atmel,at91sam9260-rtt.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Atmel AT91 RTT Device Tree Bindings + +allOf: + - $ref: "rtc.yaml#" + +maintainers: + - Alexandre Belloni <alexandre.belloni@bootlin.com> + +properties: + compatible: + oneOf: + - items: + - const: atmel,at91sam9260-rtt + - items: + - const: microchip,sam9x60-rtt + - const: atmel,at91sam9260-rtt + - items: + - const: microchip,sama7g5-rtt + - const: microchip,sam9x60-rtt + - const: atmel,at91sam9260-rtt + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + clocks: + maxItems: 1 + + atmel,rtt-rtc-time-reg: + $ref: /schemas/types.yaml#/definitions/phandle-array + items: + - items: + - description: Phandle to the GPBR node. + - description: Offset within the GPBR block. + description: + Should encode the GPBR register used to store the time base when the + RTT is used as an RTC. The first cell should point to the GPBR node + and the second one encodes the offset within the GPBR block (or in + other words, the GPBR register used to store the time base). + +required: + - compatible + - reg + - interrupts + - clocks + - atmel,rtt-rtc-time-reg + +unevaluatedProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/irq.h> + + rtc@fffffd20 { + compatible = "atmel,at91sam9260-rtt"; + reg = <0xfffffd20 0x10>; + interrupts = <1 IRQ_TYPE_LEVEL_HIGH 7>; + clocks = <&clk32k>; + atmel,rtt-rtc-time-reg = <&gpbr 0x0>; + }; diff --git a/Documentation/devicetree/bindings/serial/sifive-serial.yaml b/Documentation/devicetree/bindings/serial/sifive-serial.yaml index 09aae43f65a7..b0a8871e3641 100644 --- a/Documentation/devicetree/bindings/serial/sifive-serial.yaml +++ b/Documentation/devicetree/bindings/serial/sifive-serial.yaml @@ -59,7 +59,7 @@ examples: interrupt-parent = <&plic0>; interrupts = <80>; reg = <0x10010000 0x1000>; - clocks = <&prci PRCI_CLK_TLCLK>; + clocks = <&prci FU540_PRCI_CLK_TLCLK>; }; ... diff --git a/Documentation/devicetree/bindings/timer/ingenic,tcu.yaml b/Documentation/devicetree/bindings/timer/ingenic,tcu.yaml index 7fb37eae9da7..d541cf2067bc 100644 --- a/Documentation/devicetree/bindings/timer/ingenic,tcu.yaml +++ b/Documentation/devicetree/bindings/timer/ingenic,tcu.yaml @@ -152,6 +152,7 @@ patternProperties: - enum: - ingenic,jz4740-pwm - ingenic,jz4725b-pwm + - ingenic,x1000-pwm - items: - enum: - ingenic,jz4760-pwm diff --git a/Documentation/devicetree/bindings/vendor-prefixes.yaml b/Documentation/devicetree/bindings/vendor-prefixes.yaml index 8fe2d934f949..01430973ecec 100644 --- a/Documentation/devicetree/bindings/vendor-prefixes.yaml +++ b/Documentation/devicetree/bindings/vendor-prefixes.yaml @@ -560,6 +560,8 @@ patternProperties: description: Ingenieurburo Fur Ic-Technologie (I/F/I) "^ilitek,.*": description: ILI Technology Corporation (ILITEK) + "^imagis,.*": + description: Imagis Technologies Co., Ltd. "^img,.*": description: Imagination Technologies Ltd. "^imi,.*": diff --git a/Documentation/devicetree/bindings/watchdog/renesas,wdt.yaml b/Documentation/devicetree/bindings/watchdog/renesas,wdt.yaml index 91a98ccd4226..d060438e1402 100644 --- a/Documentation/devicetree/bindings/watchdog/renesas,wdt.yaml +++ b/Documentation/devicetree/bindings/watchdog/renesas,wdt.yaml @@ -55,6 +55,11 @@ properties: - renesas,r8a779a0-wdt # R-Car V3U - const: renesas,rcar-gen3-wdt # R-Car Gen3 and RZ/G2 + - items: + - enum: + - renesas,r8a779f0-wdt # R-Car S4-8 + - const: renesas,rcar-gen4-wdt # R-Car Gen4 + reg: maxItems: 1 diff --git a/Documentation/driver-api/nvdimm/nvdimm.rst b/Documentation/driver-api/nvdimm/nvdimm.rst index 1d8302b89bd4..be8587a558e1 100644 --- a/Documentation/driver-api/nvdimm/nvdimm.rst +++ b/Documentation/driver-api/nvdimm/nvdimm.rst @@ -14,10 +14,8 @@ Version 13 Overview Supporting Documents Git Trees - LIBNVDIMM PMEM and BLK - Why BLK? - PMEM vs BLK - BLK-REGIONs, PMEM-REGIONs, Atomic Sectors, and DAX + LIBNVDIMM PMEM + PMEM-REGIONs, Atomic Sectors, and DAX Example NVDIMM Platform LIBNVDIMM Kernel Device Model and LIBNDCTL Userspace API LIBNDCTL: Context @@ -53,19 +51,12 @@ PMEM: block device composed of PMEM is capable of DAX. A PMEM address range may span an interleave of several DIMMs. -BLK: - A set of one or more programmable memory mapped apertures provided - by a DIMM to access its media. This indirection precludes the - performance benefit of interleaving, but enables DIMM-bounded failure - modes. - DPA: DIMM Physical Address, is a DIMM-relative offset. With one DIMM in the system there would be a 1:1 system-physical-address:DPA association. Once more DIMMs are added a memory controller interleave must be decoded to determine the DPA associated with a given - system-physical-address. BLK capacity always has a 1:1 relationship - with a single-DIMM's DPA range. + system-physical-address. DAX: File system extensions to bypass the page cache and block layer to @@ -84,30 +75,30 @@ BTT: Block Translation Table: Persistent memory is byte addressable. Existing software may have an expectation that the power-fail-atomicity of writes is at least one sector, 512 bytes. The BTT is an indirection - table with atomic update semantics to front a PMEM/BLK block device + table with atomic update semantics to front a PMEM block device driver and present arbitrary atomic sector sizes. LABEL: Metadata stored on a DIMM device that partitions and identifies - (persistently names) storage between PMEM and BLK. It also partitions - BLK storage to host BTTs with different parameters per BLK-partition. - Note that traditional partition tables, GPT/MBR, are layered on top of a - BLK or PMEM device. + (persistently names) capacity allocated to different PMEM namespaces. It + also indicates whether an address abstraction like a BTT is applied to + the namepsace. Note that traditional partition tables, GPT/MBR, are + layered on top of a PMEM namespace, or an address abstraction like BTT + if present, but partition support is deprecated going forward. Overview ======== -The LIBNVDIMM subsystem provides support for three types of NVDIMMs, namely, -PMEM, BLK, and NVDIMM devices that can simultaneously support both PMEM -and BLK mode access. These three modes of operation are described by -the "NVDIMM Firmware Interface Table" (NFIT) in ACPI 6. While the LIBNVDIMM -implementation is generic and supports pre-NFIT platforms, it was guided -by the superset of capabilities need to support this ACPI 6 definition -for NVDIMM resources. The bulk of the kernel implementation is in place -to handle the case where DPA accessible via PMEM is aliased with DPA -accessible via BLK. When that occurs a LABEL is needed to reserve DPA -for exclusive access via one mode a time. +The LIBNVDIMM subsystem provides support for PMEM described by platform +firmware or a device driver. On ACPI based systems the platform firmware +conveys persistent memory resource via the ACPI NFIT "NVDIMM Firmware +Interface Table" in ACPI 6. While the LIBNVDIMM subsystem implementation +is generic and supports pre-NFIT platforms, it was guided by the +superset of capabilities need to support this ACPI 6 definition for +NVDIMM resources. The original implementation supported the +block-window-aperture capability described in the NFIT, but that support +has since been abandoned and never shipped in a product. Supporting Documents -------------------- @@ -125,107 +116,38 @@ Git Trees --------- LIBNVDIMM: - https://git.kernel.org/cgit/linux/kernel/git/djbw/nvdimm.git + https://git.kernel.org/cgit/linux/kernel/git/nvdimm/nvdimm.git LIBNDCTL: https://github.com/pmem/ndctl.git -PMEM: - https://github.com/01org/prd -LIBNVDIMM PMEM and BLK -====================== +LIBNVDIMM PMEM +============== Prior to the arrival of the NFIT, non-volatile memory was described to a system in various ad-hoc ways. Usually only the bare minimum was provided, namely, a single system-physical-address range where writes are expected to be durable after a system power loss. Now, the NFIT specification standardizes not only the description of PMEM, but also -BLK and platform message-passing entry points for control and -configuration. - -For each NVDIMM access method (PMEM, BLK), LIBNVDIMM provides a block -device driver: - - 1. PMEM (nd_pmem.ko): Drives a system-physical-address range. This - range is contiguous in system memory and may be interleaved (hardware - memory controller striped) across multiple DIMMs. When interleaved the - platform may optionally provide details of which DIMMs are participating - in the interleave. - - Note that while LIBNVDIMM describes system-physical-address ranges that may - alias with BLK access as ND_NAMESPACE_PMEM ranges and those without - alias as ND_NAMESPACE_IO ranges, to the nd_pmem driver there is no - distinction. The different device-types are an implementation detail - that userspace can exploit to implement policies like "only interface - with address ranges from certain DIMMs". It is worth noting that when - aliasing is present and a DIMM lacks a label, then no block device can - be created by default as userspace needs to do at least one allocation - of DPA to the PMEM range. In contrast ND_NAMESPACE_IO ranges, once - registered, can be immediately attached to nd_pmem. - - 2. BLK (nd_blk.ko): This driver performs I/O using a set of platform - defined apertures. A set of apertures will access just one DIMM. - Multiple windows (apertures) allow multiple concurrent accesses, much like - tagged-command-queuing, and would likely be used by different threads or - different CPUs. - - The NFIT specification defines a standard format for a BLK-aperture, but - the spec also allows for vendor specific layouts, and non-NFIT BLK - implementations may have other designs for BLK I/O. For this reason - "nd_blk" calls back into platform-specific code to perform the I/O. - - One such implementation is defined in the "Driver Writer's Guide" and "DSM - Interface Example". - - -Why BLK? -======== +platform message-passing entry points for control and configuration. + +PMEM (nd_pmem.ko): Drives a system-physical-address range. This range is +contiguous in system memory and may be interleaved (hardware memory controller +striped) across multiple DIMMs. When interleaved the platform may optionally +provide details of which DIMMs are participating in the interleave. + +It is worth noting that when the labeling capability is detected (a EFI +namespace label index block is found), then no block device is created +by default as userspace needs to do at least one allocation of DPA to +the PMEM range. In contrast ND_NAMESPACE_IO ranges, once registered, +can be immediately attached to nd_pmem. This latter mode is called +label-less or "legacy". + +PMEM-REGIONs, Atomic Sectors, and DAX +------------------------------------- -While PMEM provides direct byte-addressable CPU-load/store access to -NVDIMM storage, it does not provide the best system RAS (recovery, -availability, and serviceability) model. An access to a corrupted -system-physical-address address causes a CPU exception while an access -to a corrupted address through an BLK-aperture causes that block window -to raise an error status in a register. The latter is more aligned with -the standard error model that host-bus-adapter attached disks present. - -Also, if an administrator ever wants to replace a memory it is easier to -service a system at DIMM module boundaries. Compare this to PMEM where -data could be interleaved in an opaque hardware specific manner across -several DIMMs. - -PMEM vs BLK ------------ - -BLK-apertures solve these RAS problems, but their presence is also the -major contributing factor to the complexity of the ND subsystem. They -complicate the implementation because PMEM and BLK alias in DPA space. -Any given DIMM's DPA-range may contribute to one or more -system-physical-address sets of interleaved DIMMs, *and* may also be -accessed in its entirety through its BLK-aperture. Accessing a DPA -through a system-physical-address while simultaneously accessing the -same DPA through a BLK-aperture has undefined results. For this reason, -DIMMs with this dual interface configuration include a DSM function to -store/retrieve a LABEL. The LABEL effectively partitions the DPA-space -into exclusive system-physical-address and BLK-aperture accessible -regions. For simplicity a DIMM is allowed a PMEM "region" per each -interleave set in which it is a member. The remaining DPA space can be -carved into an arbitrary number of BLK devices with discontiguous -extents. - -BLK-REGIONs, PMEM-REGIONs, Atomic Sectors, and DAX -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -One of the few -reasons to allow multiple BLK namespaces per REGION is so that each -BLK-namespace can be configured with a BTT with unique atomic sector -sizes. While a PMEM device can host a BTT the LABEL specification does -not provide for a sector size to be specified for a PMEM namespace. - -This is due to the expectation that the primary usage model for PMEM is -via DAX, and the BTT is incompatible with DAX. However, for the cases -where an application or filesystem still needs atomic sector update -guarantees it can register a BTT on a PMEM device or partition. See +For the cases where an application or filesystem still needs atomic sector +update guarantees it can register a BTT on a PMEM device or partition. See LIBNVDIMM/NDCTL: Block Translation Table "btt" @@ -236,51 +158,40 @@ For the remainder of this document the following diagram will be referenced for any example sysfs layouts:: - (a) (b) DIMM BLK-REGION + (a) (b) DIMM +-------------------+--------+--------+--------+ - +------+ | pm0.0 | blk2.0 | pm1.0 | blk2.1 | 0 region2 + +------+ | pm0.0 | free | pm1.0 | free | 0 | imc0 +--+- - - region0- - - +--------+ +--------+ - +--+---+ | pm0.0 | blk3.0 | pm1.0 | blk3.1 | 1 region3 + +--+---+ | pm0.0 | free | pm1.0 | free | 1 | +-------------------+--------v v--------+ +--+---+ | | | cpu0 | region1 +--+---+ | | | +----------------------------^ ^--------+ - +--+---+ | blk4.0 | pm1.0 | blk4.0 | 2 region4 + +--+---+ | free | pm1.0 | free | 2 | imc1 +--+----------------------------| +--------+ - +------+ | blk5.0 | pm1.0 | blk5.0 | 3 region5 + +------+ | free | pm1.0 | free | 3 +----------------------------+--------+--------+ In this platform we have four DIMMs and two memory controllers in one -socket. Each unique interface (BLK or PMEM) to DPA space is identified -by a region device with a dynamically assigned id (REGION0 - REGION5). +socket. Each PMEM interleave set is identified by a region device with +a dynamically assigned id. 1. The first portion of DIMM0 and DIMM1 are interleaved as REGION0. A single PMEM namespace is created in the REGION0-SPA-range that spans most of DIMM0 and DIMM1 with a user-specified name of "pm0.0". Some of that - interleaved system-physical-address range is reclaimed as BLK-aperture - accessed space starting at DPA-offset (a) into each DIMM. In that - reclaimed space we create two BLK-aperture "namespaces" from REGION2 and - REGION3 where "blk2.0" and "blk3.0" are just human readable names that - could be set to any user-desired name in the LABEL. + interleaved system-physical-address range is left free for + another PMEM namespace to be defined. 2. In the last portion of DIMM0 and DIMM1 we have an interleaved system-physical-address range, REGION1, that spans those two DIMMs as well as DIMM2 and DIMM3. Some of REGION1 is allocated to a PMEM namespace - named "pm1.0", the rest is reclaimed in 4 BLK-aperture namespaces (for - each DIMM in the interleave set), "blk2.1", "blk3.1", "blk4.0", and - "blk5.0". - - 3. The portion of DIMM2 and DIMM3 that do not participate in the REGION1 - interleaved system-physical-address range (i.e. the DPA address past - offset (b) are also included in the "blk4.0" and "blk5.0" namespaces. - Note, that this example shows that BLK-aperture namespaces don't need to - be contiguous in DPA-space. + named "pm1.0". This bus is provided by the kernel under the device /sys/devices/platform/nfit_test.0 when the nfit_test.ko module from - tools/testing/nvdimm is loaded. This not only test LIBNVDIMM but the - acpi_nfit.ko driver as well. + tools/testing/nvdimm is loaded. This module is a unit test for + LIBNVDIMM and the acpi_nfit.ko driver. LIBNVDIMM Kernel Device Model and LIBNDCTL Userspace API @@ -469,17 +380,14 @@ identified by an "nfit_handle" a 32-bit value where: LIBNVDIMM/LIBNDCTL: Region -------------------------- -A generic REGION device is registered for each PMEM range or BLK-aperture -set. Per the example there are 6 regions: 2 PMEM and 4 BLK-aperture -sets on the "nfit_test.0" bus. The primary role of regions are to be a -container of "mappings". A mapping is a tuple of <DIMM, -DPA-start-offset, length>. +A generic REGION device is registered for each PMEM interleave-set / +range. Per the example there are 2 PMEM regions on the "nfit_test.0" +bus. The primary role of regions are to be a container of "mappings". A +mapping is a tuple of <DIMM, DPA-start-offset, length>. -LIBNVDIMM provides a built-in driver for these REGION devices. This driver -is responsible for reconciling the aliased DPA mappings across all -regions, parsing the LABEL, if present, and then emitting NAMESPACE -devices with the resolved/exclusive DPA-boundaries for the nd_pmem or -nd_blk device driver to consume. +LIBNVDIMM provides a built-in driver for REGION devices. This driver +is responsible for all parsing LABELs, if present, and then emitting NAMESPACE +devices for the nd_pmem driver to consume. In addition to the generic attributes of "mapping"s, "interleave_ways" and "size" the REGION device also exports some convenience attributes. @@ -493,8 +401,6 @@ LIBNVDIMM: region:: struct nd_region *nvdimm_pmem_region_create(struct nvdimm_bus *nvdimm_bus, struct nd_region_desc *ndr_desc); - struct nd_region *nvdimm_blk_region_create(struct nvdimm_bus *nvdimm_bus, - struct nd_region_desc *ndr_desc); :: @@ -527,8 +433,9 @@ LIBNDCTL: region enumeration example ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Sample region retrieval routines based on NFIT-unique data like -"spa_index" (interleave set id) for PMEM and "nfit_handle" (dimm id) for -BLK:: +"spa_index" (interleave set id). + +:: static struct ndctl_region *get_pmem_region_by_spa_index(struct ndctl_bus *bus, unsigned int spa_index) @@ -544,139 +451,23 @@ BLK:: return NULL; } - static struct ndctl_region *get_blk_region_by_dimm_handle(struct ndctl_bus *bus, - unsigned int handle) - { - struct ndctl_region *region; - - ndctl_region_foreach(bus, region) { - struct ndctl_mapping *map; - - if (ndctl_region_get_type(region) != ND_DEVICE_REGION_BLOCK) - continue; - ndctl_mapping_foreach(region, map) { - struct ndctl_dimm *dimm = ndctl_mapping_get_dimm(map); - - if (ndctl_dimm_get_handle(dimm) == handle) - return region; - } - } - return NULL; - } - - -Why Not Encode the Region Type into the Region Name? ----------------------------------------------------- - -At first glance it seems since NFIT defines just PMEM and BLK interface -types that we should simply name REGION devices with something derived -from those type names. However, the ND subsystem explicitly keeps the -REGION name generic and expects userspace to always consider the -region-attributes for four reasons: - - 1. There are already more than two REGION and "namespace" types. For - PMEM there are two subtypes. As mentioned previously we have PMEM where - the constituent DIMM devices are known and anonymous PMEM. For BLK - regions the NFIT specification already anticipates vendor specific - implementations. The exact distinction of what a region contains is in - the region-attributes not the region-name or the region-devtype. - - 2. A region with zero child-namespaces is a possible configuration. For - example, the NFIT allows for a DCR to be published without a - corresponding BLK-aperture. This equates to a DIMM that can only accept - control/configuration messages, but no i/o through a descendant block - device. Again, this "type" is advertised in the attributes ('mappings' - == 0) and the name does not tell you much. - - 3. What if a third major interface type arises in the future? Outside - of vendor specific implementations, it's not difficult to envision a - third class of interface type beyond BLK and PMEM. With a generic name - for the REGION level of the device-hierarchy old userspace - implementations can still make sense of new kernel advertised - region-types. Userspace can always rely on the generic region - attributes like "mappings", "size", etc and the expected child devices - named "namespace". This generic format of the device-model hierarchy - allows the LIBNVDIMM and LIBNDCTL implementations to be more uniform and - future-proof. - - 4. There are more robust mechanisms for determining the major type of a - region than a device name. See the next section, How Do I Determine the - Major Type of a Region? - -How Do I Determine the Major Type of a Region? ----------------------------------------------- - -Outside of the blanket recommendation of "use libndctl", or simply -looking at the kernel header (/usr/include/linux/ndctl.h) to decode the -"nstype" integer attribute, here are some other options. - -1. module alias lookup -^^^^^^^^^^^^^^^^^^^^^^ - - The whole point of region/namespace device type differentiation is to - decide which block-device driver will attach to a given LIBNVDIMM namespace. - One can simply use the modalias to lookup the resulting module. It's - important to note that this method is robust in the presence of a - vendor-specific driver down the road. If a vendor-specific - implementation wants to supplant the standard nd_blk driver it can with - minimal impact to the rest of LIBNVDIMM. - - In fact, a vendor may also want to have a vendor-specific region-driver - (outside of nd_region). For example, if a vendor defined its own LABEL - format it would need its own region driver to parse that LABEL and emit - the resulting namespaces. The output from module resolution is more - accurate than a region-name or region-devtype. - -2. udev -^^^^^^^ - - The kernel "devtype" is registered in the udev database:: - - # udevadm info --path=/devices/platform/nfit_test.0/ndbus0/region0 - P: /devices/platform/nfit_test.0/ndbus0/region0 - E: DEVPATH=/devices/platform/nfit_test.0/ndbus0/region0 - E: DEVTYPE=nd_pmem - E: MODALIAS=nd:t2 - E: SUBSYSTEM=nd - - # udevadm info --path=/devices/platform/nfit_test.0/ndbus0/region4 - P: /devices/platform/nfit_test.0/ndbus0/region4 - E: DEVPATH=/devices/platform/nfit_test.0/ndbus0/region4 - E: DEVTYPE=nd_blk - E: MODALIAS=nd:t3 - E: SUBSYSTEM=nd - - ...and is available as a region attribute, but keep in mind that the - "devtype" does not indicate sub-type variations and scripts should - really be understanding the other attributes. - -3. type specific attributes -^^^^^^^^^^^^^^^^^^^^^^^^^^^ - - As it currently stands a BLK-aperture region will never have a - "nfit/spa_index" attribute, but neither will a non-NFIT PMEM region. A - BLK region with a "mappings" value of 0 is, as mentioned above, a DIMM - that does not allow I/O. A PMEM region with a "mappings" value of zero - is a simple system-physical-address range. - LIBNVDIMM/LIBNDCTL: Namespace ----------------------------- -A REGION, after resolving DPA aliasing and LABEL specified boundaries, -surfaces one or more "namespace" devices. The arrival of a "namespace" -device currently triggers either the nd_blk or nd_pmem driver to load -and register a disk/block device. +A REGION, after resolving DPA aliasing and LABEL specified boundaries, surfaces +one or more "namespace" devices. The arrival of a "namespace" device currently +triggers the nd_pmem driver to load and register a disk/block device. LIBNVDIMM: namespace ^^^^^^^^^^^^^^^^^^^^ -Here is a sample layout from the three major types of NAMESPACE where -namespace0.0 represents DIMM-info-backed PMEM (note that it has a 'uuid' -attribute), namespace2.0 represents a BLK namespace (note it has a -'sector_size' attribute) that, and namespace6.0 represents an anonymous -PMEM namespace (note that has no 'uuid' attribute due to not support a -LABEL):: +Here is a sample layout from the 2 major types of NAMESPACE where namespace0.0 +represents DIMM-info-backed PMEM (note that it has a 'uuid' attribute), and +namespace1.0 represents an anonymous PMEM namespace (note that has no 'uuid' +attribute due to not support a LABEL) + +:: /sys/devices/platform/nfit_test.0/ndbus0/region0/namespace0.0 |-- alt_name @@ -691,20 +482,7 @@ LABEL):: |-- type |-- uevent `-- uuid - /sys/devices/platform/nfit_test.0/ndbus0/region2/namespace2.0 - |-- alt_name - |-- devtype - |-- dpa_extents - |-- force_raw - |-- modalias - |-- numa_node - |-- sector_size - |-- size - |-- subsystem -> ../../../../../../bus/nd - |-- type - |-- uevent - `-- uuid - /sys/devices/platform/nfit_test.1/ndbus1/region6/namespace6.0 + /sys/devices/platform/nfit_test.1/ndbus1/region1/namespace1.0 |-- block | `-- pmem0 |-- devtype @@ -786,9 +564,9 @@ Why the Term "namespace"? LIBNVDIMM/LIBNDCTL: Block Translation Table "btt" ------------------------------------------------- -A BTT (design document: https://pmem.io/2014/09/23/btt.html) is a stacked -block device driver that fronts either the whole block device or a -partition of a block device emitted by either a PMEM or BLK NAMESPACE. +A BTT (design document: https://pmem.io/2014/09/23/btt.html) is a +personality driver for a namespace that fronts entire namespace as an +'address abstraction'. LIBNVDIMM: btt layout ^^^^^^^^^^^^^^^^^^^^^ @@ -815,7 +593,9 @@ LIBNDCTL: btt creation example Similar to namespaces an idle BTT device is automatically created per region. Each time this "seed" btt device is configured and enabled a new seed is created. Creating a BTT configuration involves two steps of -finding and idle BTT and assigning it to consume a PMEM or BLK namespace:: +finding and idle BTT and assigning it to consume a namespace. + +:: static struct ndctl_btt *get_idle_btt(struct ndctl_region *region) { @@ -863,25 +643,15 @@ For the given example above, here is the view of the objects as seen by the LIBNDCTL API:: +---+ - |CTX| +---------+ +--------------+ +---------------+ - +-+-+ +-> REGION0 +---> NAMESPACE0.0 +--> PMEM8 "pm0.0" | - | | +---------+ +--------------+ +---------------+ - +-------+ | | +---------+ +--------------+ +---------------+ - | DIMM0 <-+ | +-> REGION1 +---> NAMESPACE1.0 +--> PMEM6 "pm1.0" | - +-------+ | | | +---------+ +--------------+ +---------------+ + |CTX| + +-+-+ + | + +-------+ | + | DIMM0 <-+ | +---------+ +--------------+ +---------------+ + +-------+ | | +-> REGION0 +---> NAMESPACE0.0 +--> PMEM8 "pm0.0" | | DIMM1 <-+ +-v--+ | +---------+ +--------------+ +---------------+ - +-------+ +-+BUS0+---> REGION2 +-+-> NAMESPACE2.0 +--> ND6 "blk2.0" | - | DIMM2 <-+ +----+ | +---------+ | +--------------+ +----------------------+ - +-------+ | | +-> NAMESPACE2.1 +--> ND5 "blk2.1" | BTT2 | - | DIMM3 <-+ | +--------------+ +----------------------+ - +-------+ | +---------+ +--------------+ +---------------+ - +-> REGION3 +-+-> NAMESPACE3.0 +--> ND4 "blk3.0" | - | +---------+ | +--------------+ +----------------------+ - | +-> NAMESPACE3.1 +--> ND3 "blk3.1" | BTT1 | - | +--------------+ +----------------------+ - | +---------+ +--------------+ +---------------+ - +-> REGION4 +---> NAMESPACE4.0 +--> ND2 "blk4.0" | - | +---------+ +--------------+ +---------------+ - | +---------+ +--------------+ +----------------------+ - +-> REGION5 +---> NAMESPACE5.0 +--> ND1 "blk5.0" | BTT0 | - +---------+ +--------------+ +---------------+------+ + +-------+ +-+BUS0+-| +---------+ +--------------+ +----------------------+ + | DIMM2 <-+ +----+ +-> REGION1 +---> NAMESPACE1.0 +--> PMEM6 "pm1.0" | BTT1 | + +-------+ | | +---------+ +--------------+ +---------------+------+ + | DIMM3 <-+ + +-------+ diff --git a/Documentation/filesystems/netfs_library.rst b/Documentation/filesystems/netfs_library.rst index 4f373a8ec47b..69f00179fdfe 100644 --- a/Documentation/filesystems/netfs_library.rst +++ b/Documentation/filesystems/netfs_library.rst @@ -7,6 +7,8 @@ Network Filesystem Helper Library .. Contents: - Overview. + - Per-inode context. + - Inode context helper functions. - Buffered read helpers. - Read helper functions. - Read helper structures. @@ -28,6 +30,69 @@ Note that the library module doesn't link against local caching directly, so access must be provided by the netfs. +Per-Inode Context +================= + +The network filesystem helper library needs a place to store a bit of state for +its use on each netfs inode it is helping to manage. To this end, a context +structure is defined:: + + struct netfs_i_context { + const struct netfs_request_ops *ops; + struct fscache_cookie *cache; + }; + +A network filesystem that wants to use netfs lib must place one of these +directly after the VFS ``struct inode`` it allocates, usually as part of its +own struct. This can be done in a way similar to the following:: + + struct my_inode { + struct { + /* These must be contiguous */ + struct inode vfs_inode; + struct netfs_i_context netfs_ctx; + }; + ... + }; + +This allows netfslib to find its state by simple offset from the inode pointer, +thereby allowing the netfslib helper functions to be pointed to directly by the +VFS/VM operation tables. + +The structure contains the following fields: + + * ``ops`` + + The set of operations provided by the network filesystem to netfslib. + + * ``cache`` + + Local caching cookie, or NULL if no caching is enabled. This field does not + exist if fscache is disabled. + + +Inode Context Helper Functions +------------------------------ + +To help deal with the per-inode context, a number helper functions are +provided. Firstly, a function to perform basic initialisation on a context and +set the operations table pointer:: + + void netfs_i_context_init(struct inode *inode, + const struct netfs_request_ops *ops); + +then two functions to cast between the VFS inode structure and the netfs +context:: + + struct netfs_i_context *netfs_i_context(struct inode *inode); + struct inode *netfs_inode(struct netfs_i_context *ctx); + +and finally, a function to get the cache cookie pointer from the context +attached to an inode (or NULL if fscache is disabled):: + + struct fscache_cookie *netfs_i_cookie(struct inode *inode); + + Buffered Read Helpers ===================== @@ -70,38 +135,22 @@ Read Helper Functions Three read helpers are provided:: - void netfs_readahead(struct readahead_control *ractl, - const struct netfs_read_request_ops *ops, - void *netfs_priv); + void netfs_readahead(struct readahead_control *ractl); int netfs_readpage(struct file *file, - struct folio *folio, - const struct netfs_read_request_ops *ops, - void *netfs_priv); + struct page *page); int netfs_write_begin(struct file *file, struct address_space *mapping, loff_t pos, unsigned int len, unsigned int flags, struct folio **_folio, - void **_fsdata, - const struct netfs_read_request_ops *ops, - void *netfs_priv); - -Each corresponds to a VM operation, with the addition of a couple of parameters -for the use of the read helpers: + void **_fsdata); - * ``ops`` - - A table of operations through which the helpers can talk to the filesystem. - - * ``netfs_priv`` +Each corresponds to a VM address space operation. These operations use the +state in the per-inode context. - Filesystem private data (can be NULL). - -Both of these values will be stored into the read request structure. - -For ->readahead() and ->readpage(), the network filesystem should just jump -into the corresponding read helper; whereas for ->write_begin(), it may be a +For ->readahead() and ->readpage(), the network filesystem just point directly +at the corresponding read helper; whereas for ->write_begin(), it may be a little more complicated as the network filesystem might want to flush conflicting writes or track dirty data and needs to put the acquired folio if an error occurs after calling the helper. @@ -116,7 +165,7 @@ occurs, the request will get partially completed if sufficient data is read. Additionally, there is:: - * void netfs_subreq_terminated(struct netfs_read_subrequest *subreq, + * void netfs_subreq_terminated(struct netfs_io_subrequest *subreq, ssize_t transferred_or_error, bool was_async); @@ -132,7 +181,7 @@ Read Helper Structures The read helpers make use of a couple of structures to maintain the state of the read. The first is a structure that manages a read request as a whole:: - struct netfs_read_request { + struct netfs_io_request { struct inode *inode; struct address_space *mapping; struct netfs_cache_resources cache_resources; @@ -140,7 +189,7 @@ the read. The first is a structure that manages a read request as a whole:: loff_t start; size_t len; loff_t i_size; - const struct netfs_read_request_ops *netfs_ops; + const struct netfs_request_ops *netfs_ops; unsigned int debug_id; ... }; @@ -187,8 +236,8 @@ The above fields are the ones the netfs can use. They are: The second structure is used to manage individual slices of the overall read request:: - struct netfs_read_subrequest { - struct netfs_read_request *rreq; + struct netfs_io_subrequest { + struct netfs_io_request *rreq; loff_t start; size_t len; size_t transferred; @@ -244,32 +293,26 @@ Read Helper Operations The network filesystem must provide the read helpers with a table of operations through which it can issue requests and negotiate:: - struct netfs_read_request_ops { - void (*init_rreq)(struct netfs_read_request *rreq, struct file *file); - bool (*is_cache_enabled)(struct inode *inode); - int (*begin_cache_operation)(struct netfs_read_request *rreq); - void (*expand_readahead)(struct netfs_read_request *rreq); - bool (*clamp_length)(struct netfs_read_subrequest *subreq); - void (*issue_op)(struct netfs_read_subrequest *subreq); - bool (*is_still_valid)(struct netfs_read_request *rreq); + struct netfs_request_ops { + void (*init_request)(struct netfs_io_request *rreq, struct file *file); + int (*begin_cache_operation)(struct netfs_io_request *rreq); + void (*expand_readahead)(struct netfs_io_request *rreq); + bool (*clamp_length)(struct netfs_io_subrequest *subreq); + void (*issue_read)(struct netfs_io_subrequest *subreq); + bool (*is_still_valid)(struct netfs_io_request *rreq); int (*check_write_begin)(struct file *file, loff_t pos, unsigned len, struct folio *folio, void **_fsdata); - void (*done)(struct netfs_read_request *rreq); + void (*done)(struct netfs_io_request *rreq); void (*cleanup)(struct address_space *mapping, void *netfs_priv); }; The operations are as follows: - * ``init_rreq()`` + * ``init_request()`` [Optional] This is called to initialise the request structure. It is given the file for reference and can modify the ->netfs_priv value. - * ``is_cache_enabled()`` - - [Required] This is called by netfs_write_begin() to ask if the file is being - cached. It should return true if it is being cached and false otherwise. - * ``begin_cache_operation()`` [Optional] This is called to ask the network filesystem to call into the @@ -305,7 +348,7 @@ The operations are as follows: This should return 0 on success and an error code on error. - * ``issue_op()`` + * ``issue_read()`` [Required] The helpers use this to dispatch a subrequest to the server for reading. In the subrequest, ->start, ->len and ->transferred indicate what @@ -420,12 +463,12 @@ The network filesystem's ->begin_cache_operation() method is called to set up a cache and this must call into the cache to do the work. If using fscache, for example, the cache would call:: - int fscache_begin_read_operation(struct netfs_read_request *rreq, + int fscache_begin_read_operation(struct netfs_io_request *rreq, struct fscache_cookie *cookie); passing in the request pointer and the cookie corresponding to the file. -The netfs_read_request object contains a place for the cache to hang its +The netfs_io_request object contains a place for the cache to hang its state:: struct netfs_cache_resources { @@ -443,7 +486,7 @@ operation table looks like the following:: void (*expand_readahead)(struct netfs_cache_resources *cres, loff_t *_start, size_t *_len, loff_t i_size); - enum netfs_read_source (*prepare_read)(struct netfs_read_subrequest *subreq, + enum netfs_io_source (*prepare_read)(struct netfs_io_subrequest *subreq, loff_t i_size); int (*read)(struct netfs_cache_resources *cres, @@ -562,4 +605,5 @@ API Function Reference ====================== .. kernel-doc:: include/linux/netfs.h -.. kernel-doc:: fs/netfs/read_helper.c +.. kernel-doc:: fs/netfs/buffered_read.c +.. kernel-doc:: fs/netfs/io.c diff --git a/Documentation/kbuild/kbuild.rst b/Documentation/kbuild/kbuild.rst index 2d1fc03d346e..ef19b9c13523 100644 --- a/Documentation/kbuild/kbuild.rst +++ b/Documentation/kbuild/kbuild.rst @@ -77,6 +77,17 @@ HOSTLDLIBS ---------- Additional libraries to link against when building host programs. +.. _userkbuildflags: + +USERCFLAGS +---------- +Additional options used for $(CC) when compiling userprogs. + +USERLDFLAGS +----------- +Additional options used for $(LD) when linking userprogs. userprogs are linked +with CC, so $(USERLDFLAGS) should include "-Wl," prefix as applicable. + KBUILD_KCONFIG -------------- Set the top-level Kconfig file to the value of this environment diff --git a/Documentation/kbuild/llvm.rst b/Documentation/kbuild/llvm.rst index d32616891dcf..b854bb413164 100644 --- a/Documentation/kbuild/llvm.rst +++ b/Documentation/kbuild/llvm.rst @@ -49,17 +49,36 @@ example: :: LLVM Utilities -------------- -LLVM has substitutes for GNU binutils utilities. Kbuild supports ``LLVM=1`` -to enable them. :: - - make LLVM=1 - -They can be enabled individually. The full list of the parameters: :: +LLVM has substitutes for GNU binutils utilities. They can be enabled individually. +The full list of supported make variables:: make CC=clang LD=ld.lld AR=llvm-ar NM=llvm-nm STRIP=llvm-strip \ OBJCOPY=llvm-objcopy OBJDUMP=llvm-objdump READELF=llvm-readelf \ HOSTCC=clang HOSTCXX=clang++ HOSTAR=llvm-ar HOSTLD=ld.lld +To simplify the above command, Kbuild supports the ``LLVM`` variable:: + + make LLVM=1 + +If your LLVM tools are not available in your PATH, you can supply their +location using the LLVM variable with a trailing slash:: + + make LLVM=/path/to/llvm/ + +which will use ``/path/to/llvm/clang``, ``/path/to/llvm/ld.lld``, etc. + +If your LLVM tools have a version suffix and you want to test with that +explicit version rather than the unsuffixed executables like ``LLVM=1``, you +can pass the suffix using the ``LLVM`` variable:: + + make LLVM=-14 + +which will use ``clang-14``, ``ld.lld-14``, etc. + +``LLVM=0`` is not the same as omitting ``LLVM`` altogether, it will behave like +``LLVM=1``. If you only wish to use certain LLVM utilities, use their respective +make variables. + The integrated assembler is enabled by default. You can pass ``LLVM_IAS=0`` to disable it. diff --git a/Documentation/kbuild/makefiles.rst b/Documentation/kbuild/makefiles.rst index b008b90b92c9..11a296e52d68 100644 --- a/Documentation/kbuild/makefiles.rst +++ b/Documentation/kbuild/makefiles.rst @@ -982,6 +982,8 @@ The syntax is quite similar. The difference is to use "userprogs" instead of When linking bpfilter_umh, it will be passed the extra option -static. + From command line, :ref:`USERCFLAGS and USERLDFLAGS <userkbuildflags>` will also be used. + 5.4 When userspace programs are actually built ---------------------------------------------- diff --git a/Documentation/locking/locktypes.rst b/Documentation/locking/locktypes.rst index bfa75ea1b66a..9933faad4771 100644 --- a/Documentation/locking/locktypes.rst +++ b/Documentation/locking/locktypes.rst @@ -211,9 +211,6 @@ raw_spinlock_t and spinlock_t raw_spinlock_t -------------- -raw_spinlock_t is a strict spinning lock implementation regardless of the -kernel configuration including PREEMPT_RT enabled kernels. - raw_spinlock_t is a strict spinning lock implementation in all kernels, including PREEMPT_RT kernels. Use raw_spinlock_t only in real critical core code, low-level interrupt handling and places where disabling diff --git a/Documentation/maintainer/index.rst b/Documentation/maintainer/index.rst index f0a60435b124..3e03283c144e 100644 --- a/Documentation/maintainer/index.rst +++ b/Documentation/maintainer/index.rst @@ -12,6 +12,7 @@ additions to this manual. configure-git rebasing-and-merging pull-requests + messy-diffstat maintainer-entry-profile modifying-patches diff --git a/Documentation/maintainer/messy-diffstat.rst b/Documentation/maintainer/messy-diffstat.rst new file mode 100644 index 000000000000..c015f66d7621 --- /dev/null +++ b/Documentation/maintainer/messy-diffstat.rst @@ -0,0 +1,96 @@ +.. SPDX-License-Identifier: GPL-2.0 + +===================================== +Handling messy pull-request diffstats +===================================== + +Subsystem maintainers routinely use ``git request-pull`` as part of the +process of sending work upstream. Normally, the result includes a nice +diffstat that shows which files will be touched and how much of each will +be changed. Occasionally, though, a repository with a relatively +complicated development history will yield a massive diffstat containing a +great deal of unrelated work. The result looks ugly and obscures what the +pull request is actually doing. This document describes what is happening +and how to fix things up; it is derived from The Wisdom of Linus Torvalds, +found in Linus1_ and Linus2_. + +.. _Linus1: https://lore.kernel.org/lkml/CAHk-=wg3wXH2JNxkQi+eLZkpuxqV+wPiHhw_Jf7ViH33Sw7PHA@mail.gmail.com/ +.. _Linus2: https://lore.kernel.org/lkml/CAHk-=wgXbSa8yq8Dht8at+gxb_idnJ7X5qWZQWRBN4_CUPr=eQ@mail.gmail.com/ + +A Git development history proceeds as a series of commits. In a simplified +manner, mainline kernel development looks like this:: + + ... vM --- vN-rc1 --- vN-rc2 --- vN-rc3 --- ... --- vN-rc7 --- vN + +If one wants to see what has changed between two points, a command like +this will do the job:: + + $ git diff --stat --summary vN-rc2..vN-rc3 + +Here, there are two clear points in the history; Git will essentially +"subtract" the beginning point from the end point and display the resulting +differences. The requested operation is unambiguous and easy enough to +understand. + +When a subsystem maintainer creates a branch and commits changes to it, the +result in the simplest case is a history that looks like:: + + ... vM --- vN-rc1 --- vN-rc2 --- vN-rc3 --- ... --- vN-rc7 --- vN + | + +-- c1 --- c2 --- ... --- cN + +If that maintainer now uses ``git diff`` to see what has changed between +the mainline branch (let's call it "linus") and cN, there are still two +clear endpoints, and the result is as expected. So a pull request +generated with ``git request-pull`` will also be as expected. But now +consider a slightly more complex development history:: + + ... vM --- vN-rc1 --- vN-rc2 --- vN-rc3 --- ... --- vN-rc7 --- vN + | | + | +-- c1 --- c2 --- ... --- cN + | / + +-- x1 --- x2 --- x3 + +Our maintainer has created one branch at vN-rc1 and another at vN-rc2; the +two were then subsequently merged into c2. Now a pull request generated +for cN may end up being messy indeed, and developers often end up wondering +why. + +What is happening here is that there are no longer two clear end points for +the ``git diff`` operation to use. The development culminating in cN +started in two different places; to generate the diffstat, ``git diff`` +ends up having pick one of them and hoping for the best. If the diffstat +starts at vN-rc1, it may end up including all of the changes between there +and the second origin end point (vN-rc2), which is certainly not what our +maintainer had in mind. With all of that extra junk in the diffstat, it +may be impossible to tell what actually happened in the changes leading up +to cN. + +Maintainers often try to resolve this problem by, for example, rebasing the +branch or performing another merge with the linus branch, then recreating +the pull request. This approach tends not to lead to joy at the receiving +end of that pull request; rebasing and/or merging just before pushing +upstream is a well-known way to get a grumpy response. + +So what is to be done? The best response when confronted with this +situation is to indeed to do a merge with the branch you intend your work +to be pulled into, but to do it privately, as if it were the source of +shame. Create a new, throwaway branch and do the merge there:: + + ... vM --- vN-rc1 --- vN-rc2 --- vN-rc3 --- ... --- vN-rc7 --- vN + | | | + | +-- c1 --- c2 --- ... --- cN | + | / | | + +-- x1 --- x2 --- x3 +------------+-- TEMP + +The merge operation resolves all of the complications resulting from the +multiple beginning points, yielding a coherent result that contains only +the differences from the mainline branch. Now it will be possible to +generate a diffstat with the desired information:: + + $ git diff -C --stat --summary linus..TEMP + +Save the output from this command, then simply delete the TEMP branch; +definitely do not expose it to the outside world. Take the saved diffstat +output and edit it into the messy pull request, yielding a result that +shows what is really going on. That request can then be sent upstream. diff --git a/Documentation/networking/index.rst b/Documentation/networking/index.rst index ce017136ab05..72cf33579b78 100644 --- a/Documentation/networking/index.rst +++ b/Documentation/networking/index.rst @@ -1,12 +1,13 @@ Linux Networking Documentation ============================== +Refer to :ref:`netdev-FAQ` for a guide on netdev development process specifics. + Contents: .. toctree:: :maxdepth: 2 - netdev-FAQ af_xdp bareudp batman-adv diff --git a/Documentation/process/maintainer-handbooks.rst b/Documentation/process/maintainer-handbooks.rst index 6af1abb0da48..d783060b4cc6 100644 --- a/Documentation/process/maintainer-handbooks.rst +++ b/Documentation/process/maintainer-handbooks.rst @@ -16,3 +16,4 @@ Contents: :maxdepth: 2 maintainer-tip + maintainer-netdev diff --git a/Documentation/networking/netdev-FAQ.rst b/Documentation/process/maintainer-netdev.rst index e26532f49760..c456b5225d66 100644 --- a/Documentation/networking/netdev-FAQ.rst +++ b/Documentation/process/maintainer-netdev.rst @@ -16,12 +16,10 @@ Note that some subsystems (e.g. wireless drivers) which have a high volume of traffic have their own specific mailing lists. The netdev list is managed (like many other Linux mailing lists) through -VGER (http://vger.kernel.org/) and archives can be found below: +VGER (http://vger.kernel.org/) with archives available at +https://lore.kernel.org/netdev/ -- http://marc.info/?l=linux-netdev -- http://www.spinics.net/lists/netdev/ - -Aside from subsystems like that mentioned above, all network-related +Aside from subsystems like those mentioned above, all network-related Linux development (i.e. RFC, review, comments, etc.) takes place on netdev. @@ -37,6 +35,17 @@ for the future release. You can find the trees here: - https://git.kernel.org/pub/scm/linux/kernel/git/netdev/net.git - https://git.kernel.org/pub/scm/linux/kernel/git/netdev/net-next.git +How do I indicate which tree (net vs. net-next) my patch should be in? +---------------------------------------------------------------------- +To help maintainers and CI bots you should explicitly mark which tree +your patch is targeting. Assuming that you use git, use the prefix +flag:: + + git format-patch --subject-prefix='PATCH net-next' start..finish + +Use ``net`` instead of ``net-next`` (always lower case) in the above for +bug-fix ``net`` content. + How often do changes from these trees make it to the mainline Linus tree? ------------------------------------------------------------------------- To understand this, you need to know a bit of background information on @@ -61,8 +70,12 @@ relating to vX.Y An announcement indicating when ``net-next`` has been closed is usually sent to netdev, but knowing the above, you can predict that in advance. -IMPORTANT: Do not send new ``net-next`` content to netdev during the -period during which ``net-next`` tree is closed. +.. warning:: + Do not send new ``net-next`` content to netdev during the + period during which ``net-next`` tree is closed. + +RFC patches sent for review only are obviously welcome at any time +(use ``--subject-prefix='RFC net-next'`` with ``git format-patch``). Shortly after the two weeks have passed (and vX.Y-rc1 is released), the tree for ``net-next`` reopens to collect content for the next (vX.Y+1) @@ -90,41 +103,35 @@ Load the mainline (Linus) page here: and note the top of the "tags" section. If it is rc1, it is early in the dev cycle. If it was tagged rc7 a week ago, then a release is -probably imminent. +probably imminent. If the most recent tag is a final release tag +(without an ``-rcN`` suffix) - we are most likely in a merge window +and ``net-next`` is closed. -How do I indicate which tree (net vs. net-next) my patch should be in? ----------------------------------------------------------------------- -Firstly, think whether you have a bug fix or new "next-like" content. -Then once decided, assuming that you use git, use the prefix flag, i.e. -:: - - git format-patch --subject-prefix='PATCH net-next' start..finish - -Use ``net`` instead of ``net-next`` (always lower case) in the above for -bug-fix ``net`` content. If you don't use git, then note the only magic -in the above is just the subject text of the outgoing e-mail, and you -can manually change it yourself with whatever MUA you are comfortable -with. - -I sent a patch and I'm wondering what happened to it - how can I tell whether it got merged? --------------------------------------------------------------------------------------------- +How can I tell the status of a patch I've sent? +----------------------------------------------- Start by looking at the main patchworks queue for netdev: https://patchwork.kernel.org/project/netdevbpf/list/ The "State" field will tell you exactly where things are at with your -patch. +patch. Patches are indexed by the ``Message-ID`` header of the emails +which carried them so if you have trouble finding your patch append +the value of ``Message-ID`` to the URL above. -The above only says "Under Review". How can I find out more? -------------------------------------------------------------- +How long before my patch is accepted? +------------------------------------- Generally speaking, the patches get triaged quickly (in less than -48h). So be patient. Asking the maintainer for status updates on your +48h). But be patient, if your patch is active in patchwork (i.e. it's +listed on the project's patch list) the chances it was missed are close to zero. +Asking the maintainer for status updates on your patch is a good way to ensure your patch is ignored or pushed to the bottom of the priority list. -I submitted multiple versions of the patch series. Should I directly update patchwork for the previous versions of these patch series? --------------------------------------------------------------------------------------------------------------------------------------- -No, please don't interfere with the patch status on patchwork, leave +Should I directly update patchwork state of my own patches? +----------------------------------------------------------- +It may be tempting to help the maintainers and update the state of your +own patches when you post a new version or spot a bug. Please do not do that. +Interfering with the patch status on patchwork will only cause confusion. Leave it to the maintainer to figure out what is the most recent and current version that should be applied. If there is any doubt, the maintainer will reply and ask what should be done. @@ -135,6 +142,17 @@ No, please resend the entire patch series and make sure you do number your patches such that it is clear this is the latest and greatest set of patches that can be applied. +I have received review feedback, when should I post a revised version of the patches? +------------------------------------------------------------------------------------- +Allow at least 24 hours to pass between postings. This will ensure reviewers +from all geographical locations have a chance to chime in. Do not wait +too long (weeks) between postings either as it will make it harder for reviewers +to recall all the context. + +Make sure you address all the feedback in your new posting. Do not post a new +version of the code if the discussion about the previous version is still +ongoing, unless directly instructed by a reviewer. + I submitted multiple versions of a patch series and it looks like a version other than the last one has been accepted, what should I do? ---------------------------------------------------------------------------------------------------------------------------------------- There is no revert possible, once it is pushed out, it stays like that. @@ -165,10 +183,10 @@ it is requested that you make it look like this:: * another line of text */ -I am working in existing code that has the former comment style and not the latter. Should I submit new code in the former style or the latter? ------------------------------------------------------------------------------------------------------------------------------------------------ -Make it the latter style, so that eventually all code in the domain -of netdev is of this format. +I am working in existing code which uses non-standard formatting. Which formatting should I use? +------------------------------------------------------------------------------------------------ +Make your code follow the most recent guidelines, so that eventually all code +in the domain of netdev is in the preferred format. I found a bug that might have possible security implications or similar. Should I mail the main netdev maintainer off-list? --------------------------------------------------------------------------------------------------------------------------- @@ -180,11 +198,15 @@ as possible alternative mechanisms. What level of testing is expected before I submit my change? ------------------------------------------------------------ -If your changes are against ``net-next``, the expectation is that you -have tested by layering your changes on top of ``net-next``. Ideally -you will have done run-time testing specific to your change, but at a -minimum, your changes should survive an ``allyesconfig`` and an -``allmodconfig`` build without new warnings or failures. +At the very minimum your changes must survive an ``allyesconfig`` and an +``allmodconfig`` build with ``W=1`` set without new warnings or failures. + +Ideally you will have done run-time testing specific to your change, +and the patch series contains a set of kernel selftest for +``tools/testing/selftests/net`` or using the KUnit framework. + +You are expected to test your changes on top of the relevant networking +tree (``net`` or ``net-next``) and not e.g. a stable tree or ``linux-next``. How do I post corresponding changes to user space components? ------------------------------------------------------------- @@ -198,7 +220,7 @@ or the user space project is not reviewed on netdev include a link to a public repo where user space patches can be seen. In case user space tooling lives in a separate repository but is -reviewed on netdev (e.g. patches to `iproute2` tools) kernel and +reviewed on netdev (e.g. patches to ``iproute2`` tools) kernel and user space patches should form separate series (threads) when posted to the mailing list, e.g.:: @@ -231,18 +253,18 @@ traffic if we can help it. netdevsim is great, can I extend it for my out-of-tree tests? ------------------------------------------------------------- -No, `netdevsim` is a test vehicle solely for upstream tests. -(Please add your tests under tools/testing/selftests/.) +No, ``netdevsim`` is a test vehicle solely for upstream tests. +(Please add your tests under ``tools/testing/selftests/``.) -We also give no guarantees that `netdevsim` won't change in the future +We also give no guarantees that ``netdevsim`` won't change in the future in a way which would break what would normally be considered uAPI. Is netdevsim considered a "user" of an API? ------------------------------------------- Linux kernel has a long standing rule that no API should be added unless -it has a real, in-tree user. Mock-ups and tests based on `netdevsim` are -strongly encouraged when adding new APIs, but `netdevsim` in itself +it has a real, in-tree user. Mock-ups and tests based on ``netdevsim`` are +strongly encouraged when adding new APIs, but ``netdevsim`` in itself is **not** considered a use case/user. Any other tips to help ensure my net/net-next patch gets OK'd? diff --git a/Documentation/riscv/index.rst b/Documentation/riscv/index.rst index ea915c196048..e23b876ad6eb 100644 --- a/Documentation/riscv/index.rst +++ b/Documentation/riscv/index.rst @@ -7,7 +7,6 @@ RISC-V architecture boot-image-header vm-layout - pmu patch-acceptance features diff --git a/Documentation/sphinx/kernel_abi.py b/Documentation/sphinx/kernel_abi.py index 4392b3cb4020..b5feb5b1d905 100644 --- a/Documentation/sphinx/kernel_abi.py +++ b/Documentation/sphinx/kernel_abi.py @@ -128,6 +128,7 @@ class KernelCmd(Directive): return out def nestedParse(self, lines, fname): + env = self.state.document.settings.env content = ViewList() node = nodes.section() @@ -137,7 +138,7 @@ class KernelCmd(Directive): code_block += "\n " + l lines = code_block + "\n\n" - line_regex = re.compile("^#define LINENO (\S+)\#([0-9]+)$") + line_regex = re.compile("^\.\. LINENO (\S+)\#([0-9]+)$") ln = 0 n = 0 f = fname @@ -154,6 +155,9 @@ class KernelCmd(Directive): self.do_parse(content, node) content = ViewList() + # Add the file to Sphinx build dependencies + env.note_dependency(os.path.abspath(f)) + f = new_f # sphinx counts lines from 0 diff --git a/Documentation/sphinx/kernel_feat.py b/Documentation/sphinx/kernel_feat.py index 8138d69a6987..27b701ed3681 100644 --- a/Documentation/sphinx/kernel_feat.py +++ b/Documentation/sphinx/kernel_feat.py @@ -33,6 +33,7 @@ u""" import codecs import os +import re import subprocess import sys @@ -82,7 +83,7 @@ class KernelFeat(Directive): env = doc.settings.env cwd = path.dirname(doc.current_source) - cmd = "get_feat.pl rest --dir " + cmd = "get_feat.pl rest --enable-fname --dir " cmd += self.arguments[0] if len(self.arguments) > 1: @@ -102,7 +103,22 @@ class KernelFeat(Directive): shell_env["srctree"] = srctree lines = self.runCmd(cmd, shell=True, cwd=cwd, env=shell_env) - nodeList = self.nestedParse(lines, fname) + + line_regex = re.compile("^\.\. FILE (\S+)$") + + out_lines = "" + + for line in lines.split("\n"): + match = line_regex.search(line) + if match: + fname = match.group(1) + + # Add the file to Sphinx build dependencies + env.note_dependency(os.path.abspath(fname)) + else: + out_lines += line + "\n" + + nodeList = self.nestedParse(out_lines, fname) return nodeList def runCmd(self, cmd, **kwargs): diff --git a/Documentation/sphinx/kernel_include.py b/Documentation/sphinx/kernel_include.py index f523aa68a36b..abe768088377 100755 --- a/Documentation/sphinx/kernel_include.py +++ b/Documentation/sphinx/kernel_include.py @@ -59,6 +59,7 @@ class KernelInclude(Include): u"""KernelInclude (``kernel-include``) directive""" def run(self): + env = self.state.document.settings.env path = os.path.realpath( os.path.expandvars(self.arguments[0])) @@ -70,6 +71,8 @@ class KernelInclude(Include): self.arguments[0] = path + env.note_dependency(os.path.abspath(path)) + #return super(KernelInclude, self).run() # won't work, see HINTs in _run() return self._run() diff --git a/Documentation/sphinx/kerneldoc.py b/Documentation/sphinx/kerneldoc.py index 8189c33b9dda..9395892c7ba3 100644 --- a/Documentation/sphinx/kerneldoc.py +++ b/Documentation/sphinx/kerneldoc.py @@ -130,7 +130,7 @@ class KernelDocDirective(Directive): result = ViewList() lineoffset = 0; - line_regex = re.compile("^#define LINENO ([0-9]+)$") + line_regex = re.compile("^\.\. LINENO ([0-9]+)$") for line in lines: match = line_regex.search(line) if match: diff --git a/Documentation/sphinx/kfigure.py b/Documentation/sphinx/kfigure.py index 24d2b2addcce..cefdbb7e7523 100644 --- a/Documentation/sphinx/kfigure.py +++ b/Documentation/sphinx/kfigure.py @@ -212,7 +212,7 @@ def setupTools(app): if convert_cmd: kernellog.verbose(app, "use convert(1) from: " + convert_cmd) else: - kernellog.warn(app, + kernellog.verbose(app, "Neither inkscape(1) nor convert(1) found.\n" "For SVG to PDF conversion, " "install either Inkscape (https://inkscape.org/) (preferred) or\n" @@ -296,8 +296,10 @@ def convert_image(img_node, translator, src_fname=None): if translator.builder.format == 'latex': if not inkscape_cmd and convert_cmd is None: - kernellog.verbose(app, - "no SVG to PDF conversion available / include SVG raw.") + kernellog.warn(app, + "no SVG to PDF conversion available / include SVG raw." + "\nIncluding large raw SVGs can cause xelatex error." + "\nInstall Inkscape (preferred) or ImageMagick.") img_node.replace_self(file2literal(src_fname)) else: dst_fname = path.join(translator.builder.outdir, fname + '.pdf') diff --git a/Documentation/sphinx/requirements.txt b/Documentation/sphinx/requirements.txt index 9a35f50798a6..2c573541ab71 100644 --- a/Documentation/sphinx/requirements.txt +++ b/Documentation/sphinx/requirements.txt @@ -1,2 +1,4 @@ +# jinja2>=3.1 is not compatible with Sphinx<4.0 +jinja2<3.1 sphinx_rtd_theme Sphinx==2.4.4 diff --git a/Documentation/staging/remoteproc.rst b/Documentation/staging/remoteproc.rst index 9cccd3dd6a4b..348ee7e508ac 100644 --- a/Documentation/staging/remoteproc.rst +++ b/Documentation/staging/remoteproc.rst @@ -49,13 +49,14 @@ might also consider using dev_archdata for this). :: - void rproc_shutdown(struct rproc *rproc) + int rproc_shutdown(struct rproc *rproc) Power off a remote processor (previously booted with rproc_boot()). In case @rproc is still being used by an additional user(s), then this function will just decrement the power refcount and exit, without really powering off the device. +Returns 0 on success, and an appropriate error value otherwise. Every call to rproc_boot() must (eventually) be accompanied by a call to rproc_shutdown(). Calling rproc_shutdown() redundantly is a bug. diff --git a/Documentation/virt/uml/user_mode_linux_howto_v2.rst b/Documentation/virt/uml/user_mode_linux_howto_v2.rst index d5ad96c795f6..863f67b72c05 100644 --- a/Documentation/virt/uml/user_mode_linux_howto_v2.rst +++ b/Documentation/virt/uml/user_mode_linux_howto_v2.rst @@ -1193,6 +1193,26 @@ E.g. ``os_close_file()`` is just a wrapper around ``close()`` which ensures that the userspace function close does not clash with similarly named function(s) in the kernel part. +Using UML as a Test Platform +============================ + +UML is an excellent test platform for device driver development. As +with most things UML, "some user assembly may be required". It is +up to the user to build their emulation environment. UML at present +provides only the kernel infrastructure. + +Part of this infrastructure is the ability to load and parse fdt +device tree blobs as used in Arm or Open Firmware platforms. These +are supplied as an optional extra argument to the kernel command +line:: + + dtb=filename + +The device tree is loaded and parsed at boottime and is accessible by +drivers which query it. At this moment in time this facility is +intended solely for development purposes. UML's own devices do not +query the device tree. + Security Considerations ----------------------- diff --git a/Documentation/vm/page_owner.rst b/Documentation/vm/page_owner.rst index c4de6f8dabe9..65204d7f004f 100644 --- a/Documentation/vm/page_owner.rst +++ b/Documentation/vm/page_owner.rst @@ -125,7 +125,6 @@ Usage additional function: Cull: - -c Cull by comparing stacktrace instead of total block. --cull <rules> Specify culling rules.Culling syntax is key[,key[,...]].Choose a multi-letter key from the **STANDARD FORMAT SPECIFIERS** section. diff --git a/Documentation/vm/unevictable-lru.rst b/Documentation/vm/unevictable-lru.rst index eae3af17f2d9..b280367d6a44 100644 --- a/Documentation/vm/unevictable-lru.rst +++ b/Documentation/vm/unevictable-lru.rst @@ -52,8 +52,13 @@ The infrastructure may also be able to handle other conditions that make pages unevictable, either by definition or by circumstance, in the future. -The Unevictable Page List -------------------------- +The Unevictable LRU Page List +----------------------------- + +The Unevictable LRU page list is a lie. It was never an LRU-ordered list, but a +companion to the LRU-ordered anonymous and file, active and inactive page lists; +and now it is not even a page list. But following familiar convention, here in +this document and in the source, we often imagine it as a fifth LRU page list. The Unevictable LRU infrastructure consists of an additional, per-node, LRU list called the "unevictable" list and an associated page flag, PG_unevictable, to @@ -63,8 +68,8 @@ The PG_unevictable flag is analogous to, and mutually exclusive with, the PG_active flag in that it indicates on which LRU list a page resides when PG_lru is set. -The Unevictable LRU infrastructure maintains unevictable pages on an additional -LRU list for a few reasons: +The Unevictable LRU infrastructure maintains unevictable pages as if they were +on an additional LRU list for a few reasons: (1) We get to "treat unevictable pages just like we treat other pages in the system - which means we get to use the same code to manipulate them, the @@ -72,13 +77,11 @@ LRU list for a few reasons: of the statistics, etc..." [Rik van Riel] (2) We want to be able to migrate unevictable pages between nodes for memory - defragmentation, workload management and memory hotplug. The linux kernel + defragmentation, workload management and memory hotplug. The Linux kernel can only migrate pages that it can successfully isolate from the LRU - lists. If we were to maintain pages elsewhere than on an LRU-like list, - where they can be found by isolate_lru_page(), we would prevent their - migration, unless we reworked migration code to find the unevictable pages - itself. - + lists (or "Movable" pages: outside of consideration here). If we were to + maintain pages elsewhere than on an LRU-like list, where they can be + detected by isolate_lru_page(), we would prevent their migration. The unevictable list does not differentiate between file-backed and anonymous, swap-backed pages. This differentiation is only important while the pages are, @@ -92,8 +95,8 @@ Memory Control Group Interaction -------------------------------- The unevictable LRU facility interacts with the memory control group [aka -memory controller; see Documentation/admin-guide/cgroup-v1/memory.rst] by extending the -lru_list enum. +memory controller; see Documentation/admin-guide/cgroup-v1/memory.rst] by +extending the lru_list enum. The memory controller data structure automatically gets a per-node unevictable list as a result of the "arrayification" of the per-node LRU lists (one per @@ -143,7 +146,6 @@ These are currently used in three places in the kernel: and this mark remains for the life of the inode. (2) By SYSV SHM to mark SHM_LOCK'd address spaces until SHM_UNLOCK is called. - Note that SHM_LOCK is not required to page in the locked pages if they're swapped out; the application must touch the pages manually if it wants to ensure they're in memory. @@ -156,19 +158,19 @@ These are currently used in three places in the kernel: Detecting Unevictable Pages --------------------------- -The function page_evictable() in vmscan.c determines whether a page is +The function page_evictable() in mm/internal.h determines whether a page is evictable or not using the query function outlined above [see section :ref:`Marking address spaces unevictable <mark_addr_space_unevict>`] to check the AS_UNEVICTABLE flag. For address spaces that are so marked after being populated (as SHM regions -might be), the lock action (eg: SHM_LOCK) can be lazy, and need not populate +might be), the lock action (e.g. SHM_LOCK) can be lazy, and need not populate the page tables for the region as does, for example, mlock(), nor need it make any special effort to push any pages in the SHM_LOCK'd area to the unevictable list. Instead, vmscan will do this if and when it encounters the pages during a reclamation scan. -On an unlock action (such as SHM_UNLOCK), the unlocker (eg: shmctl()) must scan +On an unlock action (such as SHM_UNLOCK), the unlocker (e.g. shmctl()) must scan the pages in the region and "rescue" them from the unevictable list if no other condition is keeping them unevictable. If an unevictable region is destroyed, the pages are also "rescued" from the unevictable list in the process of @@ -176,7 +178,7 @@ freeing them. page_evictable() also checks for mlocked pages by testing an additional page flag, PG_mlocked (as wrapped by PageMlocked()), which is set when a page is -faulted into a VM_LOCKED vma, or found in a vma being VM_LOCKED. +faulted into a VM_LOCKED VMA, or found in a VMA being VM_LOCKED. Vmscan's Handling of Unevictable Pages @@ -186,28 +188,23 @@ If unevictable pages are culled in the fault path, or moved to the unevictable list at mlock() or mmap() time, vmscan will not encounter the pages until they have become evictable again (via munlock() for example) and have been "rescued" from the unevictable list. However, there may be situations where we decide, -for the sake of expediency, to leave a unevictable page on one of the regular +for the sake of expediency, to leave an unevictable page on one of the regular active/inactive LRU lists for vmscan to deal with. vmscan checks for such pages in all of the shrink_{active|inactive|page}_list() functions and will "cull" such pages that it encounters: that is, it diverts those pages to the -unevictable list for the node being scanned. +unevictable list for the memory cgroup and node being scanned. There may be situations where a page is mapped into a VM_LOCKED VMA, but the page is not marked as PG_mlocked. Such pages will make it all the way to -shrink_page_list() where they will be detected when vmscan walks the reverse -map in try_to_unmap(). If try_to_unmap() returns SWAP_MLOCK, -shrink_page_list() will cull the page at that point. +shrink_active_list() or shrink_page_list() where they will be detected when +vmscan walks the reverse map in page_referenced() or try_to_unmap(). The page +is culled to the unevictable list when it is released by the shrinker. To "cull" an unevictable page, vmscan simply puts the page back on the LRU list using putback_lru_page() - the inverse operation to isolate_lru_page() - after dropping the page lock. Because the condition which makes the page unevictable -may change once the page is unlocked, putback_lru_page() will recheck the -unevictable state of a page that it places on the unevictable list. If the -page has become unevictable, putback_lru_page() removes it from the list and -retries, including the page_unevictable() test. Because such a race is a rare -event and movement of pages onto the unevictable list should be rare, these -extra evictabilty checks should not occur in the majority of calls to -putback_lru_page(). +may change once the page is unlocked, __pagevec_lru_add_fn() will recheck the +unevictable state of a page before placing it on the unevictable list. MLOCKED Pages @@ -227,16 +224,25 @@ Nick posted his patch as an alternative to a patch posted by Christoph Lameter to achieve the same objective: hiding mlocked pages from vmscan. In Nick's patch, he used one of the struct page LRU list link fields as a count -of VM_LOCKED VMAs that map the page. This use of the link field for a count -prevented the management of the pages on an LRU list, and thus mlocked pages -were not migratable as isolate_lru_page() could not find them, and the LRU list -link field was not available to the migration subsystem. +of VM_LOCKED VMAs that map the page (Rik van Riel had the same idea three years +earlier). But this use of the link field for a count prevented the management +of the pages on an LRU list, and thus mlocked pages were not migratable as +isolate_lru_page() could not detect them, and the LRU list link field was not +available to the migration subsystem. -Nick resolved this by putting mlocked pages back on the lru list before +Nick resolved this by putting mlocked pages back on the LRU list before attempting to isolate them, thus abandoning the count of VM_LOCKED VMAs. When Nick's patch was integrated with the Unevictable LRU work, the count was -replaced by walking the reverse map to determine whether any VM_LOCKED VMAs -mapped the page. More on this below. +replaced by walking the reverse map when munlocking, to determine whether any +other VM_LOCKED VMAs still mapped the page. + +However, walking the reverse map for each page when munlocking was ugly and +inefficient, and could lead to catastrophic contention on a file's rmap lock, +when many processes which had it mlocked were trying to exit. In 5.18, the +idea of keeping mlock_count in Unevictable LRU list link field was revived and +put to work, without preventing the migration of mlocked pages. This is why +the "Unevictable LRU list" cannot be a linked list of pages now; but there was +no use for that linked list anyway - though its size is maintained for meminfo. Basic Management @@ -250,22 +256,18 @@ PageMlocked() functions. A PG_mlocked page will be placed on the unevictable list when it is added to the LRU. Such pages can be "noticed" by memory management in several places: - (1) in the mlock()/mlockall() system call handlers; + (1) in the mlock()/mlock2()/mlockall() system call handlers; (2) in the mmap() system call handler when mmapping a region with the MAP_LOCKED flag; (3) mmapping a region in a task that has called mlockall() with the MCL_FUTURE - flag + flag; - (4) in the fault path, if mlocked pages are "culled" in the fault path, - and when a VM_LOCKED stack segment is expanded; or + (4) in the fault path and when a VM_LOCKED stack segment is expanded; or (5) as mentioned above, in vmscan:shrink_page_list() when attempting to - reclaim a page in a VM_LOCKED VMA via try_to_unmap() - -all of which result in the VM_LOCKED flag being set for the VMA if it doesn't -already have it set. + reclaim a page in a VM_LOCKED VMA by page_referenced() or try_to_unmap(). mlocked pages become unlocked and rescued from the unevictable list when: @@ -280,51 +282,53 @@ mlocked pages become unlocked and rescued from the unevictable list when: (4) before a page is COW'd in a VM_LOCKED VMA. -mlock()/mlockall() System Call Handling ---------------------------------------- +mlock()/mlock2()/mlockall() System Call Handling +------------------------------------------------ -Both [do\_]mlock() and [do\_]mlockall() system call handlers call mlock_fixup() +mlock(), mlock2() and mlockall() system call handlers proceed to mlock_fixup() for each VMA in the range specified by the call. In the case of mlockall(), this is the entire active address space of the task. Note that mlock_fixup() is used for both mlocking and munlocking a range of memory. A call to mlock() -an already VM_LOCKED VMA, or to munlock() a VMA that is not VM_LOCKED is -treated as a no-op, and mlock_fixup() simply returns. +an already VM_LOCKED VMA, or to munlock() a VMA that is not VM_LOCKED, is +treated as a no-op and mlock_fixup() simply returns. -If the VMA passes some filtering as described in "Filtering Special Vmas" +If the VMA passes some filtering as described in "Filtering Special VMAs" below, mlock_fixup() will attempt to merge the VMA with its neighbors or split -off a subset of the VMA if the range does not cover the entire VMA. Once the -VMA has been merged or split or neither, mlock_fixup() will call -populate_vma_page_range() to fault in the pages via get_user_pages() and to -mark the pages as mlocked via mlock_vma_page(). +off a subset of the VMA if the range does not cover the entire VMA. Any pages +already present in the VMA are then marked as mlocked by mlock_page() via +mlock_pte_range() via walk_page_range() via mlock_vma_pages_range(). + +Before returning from the system call, do_mlock() or mlockall() will call +__mm_populate() to fault in the remaining pages via get_user_pages() and to +mark those pages as mlocked as they are faulted. Note that the VMA being mlocked might be mapped with PROT_NONE. In this case, get_user_pages() will be unable to fault in the pages. That's okay. If pages -do end up getting faulted into this VM_LOCKED VMA, we'll handle them in the -fault path or in vmscan. - -Also note that a page returned by get_user_pages() could be truncated or -migrated out from under us, while we're trying to mlock it. To detect this, -populate_vma_page_range() checks page_mapping() after acquiring the page lock. -If the page is still associated with its mapping, we'll go ahead and call -mlock_vma_page(). If the mapping is gone, we just unlock the page and move on. -In the worst case, this will result in a page mapped in a VM_LOCKED VMA -remaining on a normal LRU list without being PageMlocked(). Again, vmscan will -detect and cull such pages. - -mlock_vma_page() will call TestSetPageMlocked() for each page returned by -get_user_pages(). We use TestSetPageMlocked() because the page might already -be mlocked by another task/VMA and we don't want to do extra work. We -especially do not want to count an mlocked page more than once in the -statistics. If the page was already mlocked, mlock_vma_page() need do nothing -more. - -If the page was NOT already mlocked, mlock_vma_page() attempts to isolate the -page from the LRU, as it is likely on the appropriate active or inactive list -at that time. If the isolate_lru_page() succeeds, mlock_vma_page() will put -back the page - by calling putback_lru_page() - which will notice that the page -is now mlocked and divert the page to the node's unevictable list. If -mlock_vma_page() is unable to isolate the page from the LRU, vmscan will handle -it later if and when it attempts to reclaim the page. +do end up getting faulted into this VM_LOCKED VMA, they will be handled in the +fault path - which is also how mlock2()'s MLOCK_ONFAULT areas are handled. + +For each PTE (or PMD) being faulted into a VMA, the page add rmap function +calls mlock_vma_page(), which calls mlock_page() when the VMA is VM_LOCKED +(unless it is a PTE mapping of a part of a transparent huge page). Or when +it is a newly allocated anonymous page, lru_cache_add_inactive_or_unevictable() +calls mlock_new_page() instead: similar to mlock_page(), but can make better +judgments, since this page is held exclusively and known not to be on LRU yet. + +mlock_page() sets PageMlocked immediately, then places the page on the CPU's +mlock pagevec, to batch up the rest of the work to be done under lru_lock by +__mlock_page(). __mlock_page() sets PageUnevictable, initializes mlock_count +and moves the page to unevictable state ("the unevictable LRU", but with +mlock_count in place of LRU threading). Or if the page was already PageLRU +and PageUnevictable and PageMlocked, it simply increments the mlock_count. + +But in practice that may not work ideally: the page may not yet be on an LRU, or +it may have been temporarily isolated from LRU. In such cases the mlock_count +field cannot be touched, but will be set to 0 later when __pagevec_lru_add_fn() +returns the page to "LRU". Races prohibit mlock_count from being set to 1 then: +rather than risk stranding a page indefinitely as unevictable, always err with +mlock_count on the low side, so that when munlocked the page will be rescued to +an evictable LRU, then perhaps be mlocked again later if vmscan finds it in a +VM_LOCKED VMA. Filtering Special VMAs @@ -339,68 +343,48 @@ mlock_fixup() filters several classes of "special" VMAs: so there is no sense in attempting to visit them. 2) VMAs mapping hugetlbfs page are already effectively pinned into memory. We - neither need nor want to mlock() these pages. However, to preserve the - prior behavior of mlock() - before the unevictable/mlock changes - - mlock_fixup() will call make_pages_present() in the hugetlbfs VMA range to - allocate the huge pages and populate the ptes. + neither need nor want to mlock() these pages. But __mm_populate() includes + hugetlbfs ranges, allocating the huge pages and populating the PTEs. 3) VMAs with VM_DONTEXPAND are generally userspace mappings of kernel pages, - such as the VDSO page, relay channel pages, etc. These pages - are inherently unevictable and are not managed on the LRU lists. - mlock_fixup() treats these VMAs the same as hugetlbfs VMAs. It calls - make_pages_present() to populate the ptes. + such as the VDSO page, relay channel pages, etc. These pages are inherently + unevictable and are not managed on the LRU lists. __mm_populate() includes + these ranges, populating the PTEs if not already populated. + +4) VMAs with VM_MIXEDMAP set are not marked VM_LOCKED, but __mm_populate() + includes these ranges, populating the PTEs if not already populated. Note that for all of these special VMAs, mlock_fixup() does not set the VM_LOCKED flag. Therefore, we won't have to deal with them later during munlock(), munmap() or task exit. Neither does mlock_fixup() account these VMAs against the task's "locked_vm". -.. _munlock_munlockall_handling: munlock()/munlockall() System Call Handling ------------------------------------------- -The munlock() and munlockall() system calls are handled by the same functions - -do_mlock[all]() - as the mlock() and mlockall() system calls with the unlock vs -lock operation indicated by an argument. So, these system calls are also -handled by mlock_fixup(). Again, if called for an already munlocked VMA, -mlock_fixup() simply returns. Because of the VMA filtering discussed above, -VM_LOCKED will not be set in any "special" VMAs. So, these VMAs will be -ignored for munlock. +The munlock() and munlockall() system calls are handled by the same +mlock_fixup() function as mlock(), mlock2() and mlockall() system calls are. +If called to munlock an already munlocked VMA, mlock_fixup() simply returns. +Because of the VMA filtering discussed above, VM_LOCKED will not be set in +any "special" VMAs. So, those VMAs will be ignored for munlock. If the VMA is VM_LOCKED, mlock_fixup() again attempts to merge or split off the -specified range. The range is then munlocked via the function -populate_vma_page_range() - the same function used to mlock a VMA range - -passing a flag to indicate that munlock() is being performed. - -Because the VMA access protections could have been changed to PROT_NONE after -faulting in and mlocking pages, get_user_pages() was unreliable for visiting -these pages for munlocking. Because we don't want to leave pages mlocked, -get_user_pages() was enhanced to accept a flag to ignore the permissions when -fetching the pages - all of which should be resident as a result of previous -mlocking. - -For munlock(), populate_vma_page_range() unlocks individual pages by calling -munlock_vma_page(). munlock_vma_page() unconditionally clears the PG_mlocked -flag using TestClearPageMlocked(). As with mlock_vma_page(), -munlock_vma_page() use the Test*PageMlocked() function to handle the case where -the page might have already been unlocked by another task. If the page was -mlocked, munlock_vma_page() updates that zone statistics for the number of -mlocked pages. Note, however, that at this point we haven't checked whether -the page is mapped by other VM_LOCKED VMAs. - -We can't call page_mlock(), the function that walks the reverse map to -check for other VM_LOCKED VMAs, without first isolating the page from the LRU. -page_mlock() is a variant of try_to_unmap() and thus requires that the page -not be on an LRU list [more on these below]. However, the call to -isolate_lru_page() could fail, in which case we can't call page_mlock(). So, -we go ahead and clear PG_mlocked up front, as this might be the only chance we -have. If we can successfully isolate the page, we go ahead and call -page_mlock(), which will restore the PG_mlocked flag and update the zone -page statistics if it finds another VMA holding the page mlocked. If we fail -to isolate the page, we'll have left a potentially mlocked page on the LRU. -This is fine, because we'll catch it later if and if vmscan tries to reclaim -the page. This should be relatively rare. +specified range. All pages in the VMA are then munlocked by munlock_page() via +mlock_pte_range() via walk_page_range() via mlock_vma_pages_range() - the same +function used when mlocking a VMA range, with new flags for the VMA indicating +that it is munlock() being performed. + +munlock_page() uses the mlock pagevec to batch up work to be done under +lru_lock by __munlock_page(). __munlock_page() decrements the page's +mlock_count, and when that reaches 0 it clears PageMlocked and clears +PageUnevictable, moving the page from unevictable state to inactive LRU. + +But in practice that may not work ideally: the page may not yet have reached +"the unevictable LRU", or it may have been temporarily isolated from it. In +those cases its mlock_count field is unusable and must be assumed to be 0: so +that the page will be rescued to an evictable LRU, then perhaps be mlocked +again later if vmscan finds it in a VM_LOCKED VMA. Migrating MLOCKED Pages @@ -410,33 +394,38 @@ A page that is being migrated has been isolated from the LRU lists and is held locked across unmapping of the page, updating the page's address space entry and copying the contents and state, until the page table entry has been replaced with an entry that refers to the new page. Linux supports migration -of mlocked pages and other unevictable pages. This involves simply moving the -PG_mlocked and PG_unevictable states from the old page to the new page. +of mlocked pages and other unevictable pages. PG_mlocked is cleared from the +the old page when it is unmapped from the last VM_LOCKED VMA, and set when the +new page is mapped in place of migration entry in a VM_LOCKED VMA. If the page +was unevictable because mlocked, PG_unevictable follows PG_mlocked; but if the +page was unevictable for other reasons, PG_unevictable is copied explicitly. Note that page migration can race with mlocking or munlocking of the same page. -This has been discussed from the mlock/munlock perspective in the respective -sections above. Both processes (migration and m[un]locking) hold the page -locked. This provides the first level of synchronization. Page migration -zeros out the page_mapping of the old page before unlocking it, so m[un]lock -can skip these pages by testing the page mapping under page lock. +There is mostly no problem since page migration requires unmapping all PTEs of +the old page (including munlock where VM_LOCKED), then mapping in the new page +(including mlock where VM_LOCKED). The page table locks provide sufficient +synchronization. -To complete page migration, we place the new and old pages back onto the LRU -after dropping the page lock. The "unneeded" page - old page on success, new -page on failure - will be freed when the reference count held by the migration -process is released. To ensure that we don't strand pages on the unevictable -list because of a race between munlock and migration, page migration uses the -putback_lru_page() function to add migrated pages back to the LRU. +However, since mlock_vma_pages_range() starts by setting VM_LOCKED on a VMA, +before mlocking any pages already present, if one of those pages were migrated +before mlock_pte_range() reached it, it would get counted twice in mlock_count. +To prevent that, mlock_vma_pages_range() temporarily marks the VMA as VM_IO, +so that mlock_vma_page() will skip it. + +To complete page migration, we place the old and new pages back onto the LRU +afterwards. The "unneeded" page - old page on success, new page on failure - +is freed when the reference count held by the migration process is released. Compacting MLOCKED Pages ------------------------ -The unevictable LRU can be scanned for compactable regions and the default -behavior is to do so. /proc/sys/vm/compact_unevictable_allowed controls -this behavior (see Documentation/admin-guide/sysctl/vm.rst). Once scanning of the -unevictable LRU is enabled, the work of compaction is mostly handled by -the page migration code and the same work flow as described in MIGRATING -MLOCKED PAGES will apply. +The memory map can be scanned for compactable regions and the default behavior +is to let unevictable pages be moved. /proc/sys/vm/compact_unevictable_allowed +controls this behavior (see Documentation/admin-guide/sysctl/vm.rst). The work +of compaction is mostly handled by the page migration code and the same work +flow as described in Migrating MLOCKED Pages will apply. + MLOCKING Transparent Huge Pages ------------------------------- @@ -445,51 +434,44 @@ A transparent huge page is represented by a single entry on an LRU list. Therefore, we can only make unevictable an entire compound page, not individual subpages. -If a user tries to mlock() part of a huge page, we want the rest of the -page to be reclaimable. +If a user tries to mlock() part of a huge page, and no user mlock()s the +whole of the huge page, we want the rest of the page to be reclaimable. We cannot just split the page on partial mlock() as split_huge_page() can -fail and new intermittent failure mode for the syscall is undesirable. +fail and a new intermittent failure mode for the syscall is undesirable. -We handle this by keeping PTE-mapped huge pages on normal LRU lists: the -PMD on border of VM_LOCKED VMA will be split into PTE table. +We handle this by keeping PTE-mlocked huge pages on evictable LRU lists: +the PMD on the border of a VM_LOCKED VMA will be split into a PTE table. -This way the huge page is accessible for vmscan. Under memory pressure the +This way the huge page is accessible for vmscan. Under memory pressure the page will be split, subpages which belong to VM_LOCKED VMAs will be moved -to unevictable LRU and the rest can be reclaimed. +to the unevictable LRU and the rest can be reclaimed. + +/proc/meminfo's Unevictable and Mlocked amounts do not include those parts +of a transparent huge page which are mapped only by PTEs in VM_LOCKED VMAs. -See also comment in follow_trans_huge_pmd(). mmap(MAP_LOCKED) System Call Handling ------------------------------------- -In addition the mlock()/mlockall() system calls, an application can request -that a region of memory be mlocked supplying the MAP_LOCKED flag to the mmap() -call. There is one important and subtle difference here, though. mmap() + mlock() -will fail if the range cannot be faulted in (e.g. because mm_populate fails) -and returns with ENOMEM while mmap(MAP_LOCKED) will not fail. The mmaped -area will still have properties of the locked area - aka. pages will not get -swapped out - but major page faults to fault memory in might still happen. +In addition to the mlock(), mlock2() and mlockall() system calls, an application +can request that a region of memory be mlocked by supplying the MAP_LOCKED flag +to the mmap() call. There is one important and subtle difference here, though. +mmap() + mlock() will fail if the range cannot be faulted in (e.g. because +mm_populate fails) and returns with ENOMEM while mmap(MAP_LOCKED) will not fail. +The mmaped area will still have properties of the locked area - pages will not +get swapped out - but major page faults to fault memory in might still happen. -Furthermore, any mmap() call or brk() call that expands the heap by a -task that has previously called mlockall() with the MCL_FUTURE flag will result +Furthermore, any mmap() call or brk() call that expands the heap by a task +that has previously called mlockall() with the MCL_FUTURE flag will result in the newly mapped memory being mlocked. Before the unevictable/mlock -changes, the kernel simply called make_pages_present() to allocate pages and -populate the page table. +changes, the kernel simply called make_pages_present() to allocate pages +and populate the page table. -To mlock a range of memory under the unevictable/mlock infrastructure, the -mmap() handler and task address space expansion functions call +To mlock a range of memory under the unevictable/mlock infrastructure, +the mmap() handler and task address space expansion functions call populate_vma_page_range() specifying the vma and the address range to mlock. -The callers of populate_vma_page_range() will have already added the memory range -to be mlocked to the task's "locked_vm". To account for filtered VMAs, -populate_vma_page_range() returns the number of pages NOT mlocked. All of the -callers then subtract a non-negative return value from the task's locked_vm. A -negative return value represent an error - for example, from get_user_pages() -attempting to fault in a VMA with PROT_NONE access. In this case, we leave the -memory range accounted as locked_vm, as the protections could be changed later -and pages allocated into that region. - munmap()/exit()/exec() System Call Handling ------------------------------------------- @@ -500,81 +482,53 @@ munlock the pages if we're removing the last VM_LOCKED VMA that maps the pages. Before the unevictable/mlock changes, mlocking did not mark the pages in any way, so unmapping them required no processing. -To munlock a range of memory under the unevictable/mlock infrastructure, the -munmap() handler and task address space call tear down function -munlock_vma_pages_all(). The name reflects the observation that one always -specifies the entire VMA range when munlock()ing during unmap of a region. -Because of the VMA filtering when mlocking() regions, only "normal" VMAs that -actually contain mlocked pages will be passed to munlock_vma_pages_all(). - -munlock_vma_pages_all() clears the VM_LOCKED VMA flag and, like mlock_fixup() -for the munlock case, calls __munlock_vma_pages_range() to walk the page table -for the VMA's memory range and munlock_vma_page() each resident page mapped by -the VMA. This effectively munlocks the page, only if this is the last -VM_LOCKED VMA that maps the page. - - -try_to_unmap() --------------- - -Pages can, of course, be mapped into multiple VMAs. Some of these VMAs may -have VM_LOCKED flag set. It is possible for a page mapped into one or more -VM_LOCKED VMAs not to have the PG_mlocked flag set and therefore reside on one -of the active or inactive LRU lists. This could happen if, for example, a task -in the process of munlocking the page could not isolate the page from the LRU. -As a result, vmscan/shrink_page_list() might encounter such a page as described -in section "vmscan's handling of unevictable pages". To handle this situation, -try_to_unmap() checks for VM_LOCKED VMAs while it is walking a page's reverse -map. - -try_to_unmap() is always called, by either vmscan for reclaim or for page -migration, with the argument page locked and isolated from the LRU. Separate -functions handle anonymous and mapped file and KSM pages, as these types of -pages have different reverse map lookup mechanisms, with different locking. -In each case, whether rmap_walk_anon() or rmap_walk_file() or rmap_walk_ksm(), -it will call try_to_unmap_one() for every VMA which might contain the page. - -When trying to reclaim, if try_to_unmap_one() finds the page in a VM_LOCKED -VMA, it will then mlock the page via mlock_vma_page() instead of unmapping it, -and return SWAP_MLOCK to indicate that the page is unevictable: and the scan -stops there. - -mlock_vma_page() is called while holding the page table's lock (in addition -to the page lock, and the rmap lock): to serialize against concurrent mlock or -munlock or munmap system calls, mm teardown (munlock_vma_pages_all), reclaim, -holepunching, and truncation of file pages and their anonymous COWed pages. - - -page_mlock() Reverse Map Scan ---------------------------------- - -When munlock_vma_page() [see section :ref:`munlock()/munlockall() System Call -Handling <munlock_munlockall_handling>` above] tries to munlock a -page, it needs to determine whether or not the page is mapped by any -VM_LOCKED VMA without actually attempting to unmap all PTEs from the -page. For this purpose, the unevictable/mlock infrastructure -introduced a variant of try_to_unmap() called page_mlock(). - -page_mlock() walks the respective reverse maps looking for VM_LOCKED VMAs. When -such a VMA is found the page is mlocked via mlock_vma_page(). This undoes the -pre-clearing of the page's PG_mlocked done by munlock_vma_page. - -Note that page_mlock()'s reverse map walk must visit every VMA in a page's -reverse map to determine that a page is NOT mapped into any VM_LOCKED VMA. -However, the scan can terminate when it encounters a VM_LOCKED VMA. -Although page_mlock() might be called a great many times when munlocking a -large region or tearing down a large address space that has been mlocked via -mlockall(), overall this is a fairly rare event. +For each PTE (or PMD) being unmapped from a VMA, page_remove_rmap() calls +munlock_vma_page(), which calls munlock_page() when the VMA is VM_LOCKED +(unless it was a PTE mapping of a part of a transparent huge page). + +munlock_page() uses the mlock pagevec to batch up work to be done under +lru_lock by __munlock_page(). __munlock_page() decrements the page's +mlock_count, and when that reaches 0 it clears PageMlocked and clears +PageUnevictable, moving the page from unevictable state to inactive LRU. + +But in practice that may not work ideally: the page may not yet have reached +"the unevictable LRU", or it may have been temporarily isolated from it. In +those cases its mlock_count field is unusable and must be assumed to be 0: so +that the page will be rescued to an evictable LRU, then perhaps be mlocked +again later if vmscan finds it in a VM_LOCKED VMA. + + +Truncating MLOCKED Pages +------------------------ + +File truncation or hole punching forcibly unmaps the deleted pages from +userspace; truncation even unmaps and deletes any private anonymous pages +which had been Copied-On-Write from the file pages now being truncated. + +Mlocked pages can be munlocked and deleted in this way: like with munmap(), +for each PTE (or PMD) being unmapped from a VMA, page_remove_rmap() calls +munlock_vma_page(), which calls munlock_page() when the VMA is VM_LOCKED +(unless it was a PTE mapping of a part of a transparent huge page). + +However, if there is a racing munlock(), since mlock_vma_pages_range() starts +munlocking by clearing VM_LOCKED from a VMA, before munlocking all the pages +present, if one of those pages were unmapped by truncation or hole punch before +mlock_pte_range() reached it, it would not be recognized as mlocked by this VMA, +and would not be counted out of mlock_count. In this rare case, a page may +still appear as PageMlocked after it has been fully unmapped: and it is left to +release_pages() (or __page_cache_release()) to clear it and update statistics +before freeing (this event is counted in /proc/vmstat unevictable_pgs_cleared, +which is usually 0). Page Reclaim in shrink_*_list() ------------------------------- -shrink_active_list() culls any obviously unevictable pages - i.e. -!page_evictable(page) - diverting these to the unevictable list. +vmscan's shrink_active_list() culls any obviously unevictable pages - +i.e. !page_evictable(page) pages - diverting those to the unevictable list. However, shrink_active_list() only sees unevictable pages that made it onto the -active/inactive lru lists. Note that these pages do not have PageUnevictable -set - otherwise they would be on the unevictable list and shrink_active_list +active/inactive LRU lists. Note that these pages do not have PageUnevictable +set - otherwise they would be on the unevictable list and shrink_active_list() would never see them. Some examples of these unevictable pages on the LRU lists are: @@ -586,20 +540,15 @@ Some examples of these unevictable pages on the LRU lists are: when an application accesses the page the first time after SHM_LOCK'ing the segment. - (3) mlocked pages that could not be isolated from the LRU and moved to the - unevictable list in mlock_vma_page(). - -shrink_inactive_list() also diverts any unevictable pages that it finds on the -inactive lists to the appropriate node's unevictable list. + (3) pages still mapped into VM_LOCKED VMAs, which should be marked mlocked, + but events left mlock_count too low, so they were munlocked too early. -shrink_inactive_list() should only see SHM_LOCK'd pages that became SHM_LOCK'd -after shrink_active_list() had moved them to the inactive list, or pages mapped -into VM_LOCKED VMAs that munlock_vma_page() couldn't isolate from the LRU to -recheck via page_mlock(). shrink_inactive_list() won't notice the latter, -but will pass on to shrink_page_list(). +vmscan's shrink_inactive_list() and shrink_page_list() also divert obviously +unevictable pages found on the inactive lists to the appropriate memory cgroup +and node unevictable list. -shrink_page_list() again culls obviously unevictable pages that it could -encounter for similar reason to shrink_inactive_list(). Pages mapped into -VM_LOCKED VMAs but without PG_mlocked set will make it all the way to -try_to_unmap(). shrink_page_list() will divert them to the unevictable list -when try_to_unmap() returns SWAP_MLOCK, as discussed above. +rmap's page_referenced_one(), called via vmscan's shrink_active_list() or +shrink_page_list(), and rmap's try_to_unmap_one() called via shrink_page_list(), +check for (3) pages still mapped into VM_LOCKED VMAs, and call mlock_vma_page() +to correct them. Such pages are culled to the unevictable list when released +by the shrinker. |