| Message ID | 20230109050152.316606-2-dmitry.baryshkov@linaro.org |
|---|---|
| State | Changes Requested, archived |
| Headers | show |
| Series | dt-bindings: display/msm: convert MDP5 schema to YAML format | expand |
| Context | Check | Description |
|---|---|---|
| robh/checkpatch | warning | total: 0 errors, 3 warnings, 138 lines checked |
| robh/patch-applied | success | |
| robh/dtbs-check | warning | build log |
| robh/dt-meta-schema | success |
On 2023-01-09 07:01:49, Dmitry Baryshkov wrote: > Convert the mdp5.txt into the yaml format. Changes to the existing (txt) schema: > - MSM8996 has additional "iommu" clock, define it separately > - Add new properties used on some of platforms: > - interconnects, interconnect-names > - iommus > - power-domains > - operating-points-v2, opp-table > > Signed-off-by: Dmitry Baryshkov <dmitry.baryshkov@linaro.org> > --- > .../devicetree/bindings/display/msm/mdp5.txt | 132 ----------------- > .../bindings/display/msm/qcom,mdp5.yaml | 138 ++++++++++++++++++ > 2 files changed, 138 insertions(+), 132 deletions(-) > delete mode 100644 Documentation/devicetree/bindings/display/msm/mdp5.txt > create mode 100644 Documentation/devicetree/bindings/display/msm/qcom,mdp5.yaml > > diff --git a/Documentation/devicetree/bindings/display/msm/mdp5.txt b/Documentation/devicetree/bindings/display/msm/mdp5.txt > deleted file mode 100644 > index 65d03c58dee6..000000000000 > --- a/Documentation/devicetree/bindings/display/msm/mdp5.txt > +++ /dev/null > @@ -1,132 +0,0 @@ > -Qualcomm adreno/snapdragon MDP5 display controller > - > -Description: > - > -This is the bindings documentation for the MDP5 display > -controller found in SoCs like MSM8974, APQ8084, MSM8916, MSM8994 and MSM8996. > - > -MDP5: > -Required properties: > -- compatible: > - * "qcom,mdp5" - MDP5 > -- reg: Physical base address and length of the controller's registers. > -- reg-names: The names of register regions. The following regions are required: > - * "mdp_phys" > -- interrupts: Interrupt line from MDP5 to MDSS interrupt controller. > -- clocks: device clocks. See ../clocks/clock-bindings.txt for details. > -- clock-names: the following clocks are required. > -- * "bus" > -- * "iface" > -- * "core" > -- * "vsync" > -- ports: contains the list of output ports from MDP. These connect to interfaces > - that are external to the MDP hardware, such as HDMI, DSI, EDP etc (LVDS is a > - special case since it is a part of the MDP block itself). > - > - Each output port contains an endpoint that describes how it is connected to an > - external interface. These are described by the standard properties documented > - here: > - Documentation/devicetree/bindings/graph.txt > - Documentation/devicetree/bindings/media/video-interfaces.txt > - > - The availability of output ports can vary across SoC revisions: > - > - For MSM8974 and APQ8084: > - Port 0 -> MDP_INTF0 (eDP) > - Port 1 -> MDP_INTF1 (DSI1) > - Port 2 -> MDP_INTF2 (DSI2) > - Port 3 -> MDP_INTF3 (HDMI) > - > - For MSM8916: > - Port 0 -> MDP_INTF1 (DSI1) > - > - For MSM8994 and MSM8996: > - Port 0 -> MDP_INTF1 (DSI1) > - Port 1 -> MDP_INTF2 (DSI2) > - Port 2 -> MDP_INTF3 (HDMI) > - > -Optional properties: > -- clock-names: the following clocks are optional: > - * "lut" > - * "tbu" > - * "tbu_rt" > - > -Example: > - > -/ { > - ... > - > - mdss: mdss@1a00000 { > - compatible = "qcom,mdss"; > - reg = <0x1a00000 0x1000>, > - <0x1ac8000 0x3000>; > - reg-names = "mdss_phys", "vbif_phys"; > - > - power-domains = <&gcc MDSS_GDSC>; > - > - clocks = <&gcc GCC_MDSS_AHB_CLK>, > - <&gcc GCC_MDSS_AXI_CLK>, > - <&gcc GCC_MDSS_VSYNC_CLK>; > - clock-names = "iface", > - "bus", > - "vsync" > - > - interrupts = <0 72 0>; > - > - interrupt-controller; > - #interrupt-cells = <1>; > - > - #address-cells = <1>; > - #size-cells = <1>; > - ranges; > - > - mdp: mdp@1a01000 { > - compatible = "qcom,mdp5"; > - reg = <0x1a01000 0x90000>; > - reg-names = "mdp_phys"; > - > - interrupt-parent = <&mdss>; > - interrupts = <0 0>; > - > - clocks = <&gcc GCC_MDSS_AHB_CLK>, > - <&gcc GCC_MDSS_AXI_CLK>, > - <&gcc GCC_MDSS_MDP_CLK>, > - <&gcc GCC_MDSS_VSYNC_CLK>; > - clock-names = "iface", > - "bus", > - "core", > - "vsync"; > - > - ports { > - #address-cells = <1>; > - #size-cells = <0>; > - > - port@0 { > - reg = <0>; > - mdp5_intf1_out: endpoint { > - remote-endpoint = <&dsi0_in>; > - }; > - }; > - }; > - }; > - > - dsi0: dsi@1a98000 { > - ... > - ports { > - ... > - port@0 { > - reg = <0>; > - dsi0_in: endpoint { > - remote-endpoint = <&mdp5_intf1_out>; > - }; > - }; > - ... > - }; > - ... > - }; > - > - dsi_phy0: dsi-phy@1a98300 { > - ... > - }; > - }; > -}; > diff --git a/Documentation/devicetree/bindings/display/msm/qcom,mdp5.yaml b/Documentation/devicetree/bindings/display/msm/qcom,mdp5.yaml > new file mode 100644 > index 000000000000..cbcbe8b47e9b > --- /dev/null > +++ b/Documentation/devicetree/bindings/display/msm/qcom,mdp5.yaml > @@ -0,0 +1,138 @@ > +# SPDX-License-Identifier: GPL-2.0-only or BSD-2-Clause > +%YAML 1.2 > +--- > +$id: http://devicetree.org/schemas/display/msm/qcom,mdp5.yaml# > +$schema: http://devicetree.org/meta-schemas/core.yaml# > + > +title: Qualcomm Adreno/Snapdragon Mobile Display controller (MDP5) > + > +description: > > + MDP5 display controller found in SoCs like MSM8974, APQ8084, MSM8916, MSM8994 > + and MSM8996. > + > +maintainers: > + - Dmitry Baryshkov <dmitry.baryshkov@linaro.org> > + - Rob Clark <robdclark@gmail.com> > + > +properties: > + compatible: > + const: qcom,mdp5 > + > + reg: > + maxItems: 1 > + > + reg-names: > + items: > + - const: mdp_phys > + > + interrupts: > + maxItems: 1 > + > + clocks: > + minItems: 4 > + maxItems: 7 > + > + clock-names: > + oneOf: > + - minItems: 4 > + items: > + - const: iface > + - const: bus > + - const: core > + - const: vsync > + - const: lut > + - const: tbu > + - const: tbu_rt > + #MSM8996 has additional iommu clock > + - items: > + - const: iface > + - const: bus > + - const: core > + - const: iommu > + - const: vsync > + > + interconnects: > + minItems: 1 > + items: > + - description: Interconnect path from mdp0 (or a single mdp) port to the data bus > + - description: Interconnect path from mdp1 port to the data bus > + - description: Interconnect path from rotator port to the data bus > + > + interconnect-names: > + minItems: 1 > + items: > + - const: mdp0-mem > + - const: mdp1-mem > + - const: rotator-mem > + > + iommus: > + items: > + - description: Phandle to apps_smmu node with SID mask for Hard-Fail port0 As Krzysztof has said many times, these documents describe the hardware, not the DT format. Drop the "phandle" part. > + power-domains: > + maxItems: 1 > + > + operating-points-v2: true > + opp-table: > + type: object > + > + ports: > + $ref: /schemas/graph.yaml#/properties/ports > + description: | Should multiline descriptions be treated as a oneline string with `>`? > + Contains the list of output ports from DPU device. These ports > + connect to interfaces that are external to the DPU hardware, > + such as DSI, DP etc. MDP5 devices support up to 4 ports:: How do these double colons render? Is this intentional? - Marijn > + one or two DSI ports, HDMI and eDP. > + > + patternProperties: > + "^port@[0-3]+$": > + $ref: /schemas/graph.yaml#/properties/port > + > + # at least one port is required > + required: > + - port@0 > + > +required: > + - compatible > + - reg > + - reg-names > + - clocks > + - clock-names > + - ports > + > +additionalProperties: false > + > +examples: > + - | > + #include <dt-bindings/clock/qcom,gcc-msm8916.h> > + #include <dt-bindings/interrupt-controller/arm-gic.h> > + display-controller@1a01000 { > + compatible = "qcom,mdp5"; > + reg = <0x1a01000 0x90000>; > + reg-names = "mdp_phys"; > + > + interrupt-parent = <&mdss>; > + interrupts = <0>; > + > + clocks = <&gcc GCC_MDSS_AHB_CLK>, > + <&gcc GCC_MDSS_AXI_CLK>, > + <&gcc GCC_MDSS_MDP_CLK>, > + <&gcc GCC_MDSS_VSYNC_CLK>; > + clock-names = "iface", > + "bus", > + "core", > + "vsync"; > + > + ports { > + #address-cells = <1>; > + #size-cells = <0>; > + > + port@0 { > + reg = <0>; > + endpoint { > + remote-endpoint = <&dsi0_in>; > + }; > + }; > + }; > + }; > +... > -- > 2.39.0 >
On Mon, 09 Jan 2023 07:01:49 +0200, Dmitry Baryshkov wrote: > Convert the mdp5.txt into the yaml format. Changes to the existing (txt) schema: > - MSM8996 has additional "iommu" clock, define it separately > - Add new properties used on some of platforms: > - interconnects, interconnect-names > - iommus > - power-domains > - operating-points-v2, opp-table > > Signed-off-by: Dmitry Baryshkov <dmitry.baryshkov@linaro.org> > --- > .../devicetree/bindings/display/msm/mdp5.txt | 132 ----------------- > .../bindings/display/msm/qcom,mdp5.yaml | 138 ++++++++++++++++++ > 2 files changed, 138 insertions(+), 132 deletions(-) > delete mode 100644 Documentation/devicetree/bindings/display/msm/mdp5.txt > create mode 100644 Documentation/devicetree/bindings/display/msm/qcom,mdp5.yaml > Running 'make dtbs_check' with the schema in this patch gives the following warnings. Consider if they are expected or the schema is incorrect. These may not be new warnings. Note that it is not yet a requirement to have 0 warnings for dtbs_check. This will change in the future. Full log is available here: https://patchwork.ozlabs.org/project/devicetree-bindings/patch/20230109050152.316606-2-dmitry.baryshkov@linaro.org mdp@1a01000: compatible:0: 'qcom,mdp5' was expected arch/arm64/boot/dts/qcom/sdm632-fairphone-fp3.dtb mdp@1a01000: compatible: ['qcom,msm8953-mdp5', 'qcom,mdp5'] is too long arch/arm64/boot/dts/qcom/sdm632-fairphone-fp3.dtb
On 09/01/2023 09:49, Marijn Suijten wrote: > On 2023-01-09 07:01:49, Dmitry Baryshkov wrote: >> Convert the mdp5.txt into the yaml format. Changes to the existing (txt) schema: >> - MSM8996 has additional "iommu" clock, define it separately >> - Add new properties used on some of platforms: >> - interconnects, interconnect-names >> - iommus >> - power-domains >> - operating-points-v2, opp-table >> >> Signed-off-by: Dmitry Baryshkov <dmitry.baryshkov@linaro.org> >> --- >> .../devicetree/bindings/display/msm/mdp5.txt | 132 ----------------- >> .../bindings/display/msm/qcom,mdp5.yaml | 138 ++++++++++++++++++ >> 2 files changed, 138 insertions(+), 132 deletions(-) >> delete mode 100644 Documentation/devicetree/bindings/display/msm/mdp5.txt >> create mode 100644 Documentation/devicetree/bindings/display/msm/qcom,mdp5.yaml >> >> diff --git a/Documentation/devicetree/bindings/display/msm/mdp5.txt b/Documentation/devicetree/bindings/display/msm/mdp5.txt >> deleted file mode 100644 >> index 65d03c58dee6..000000000000 >> --- a/Documentation/devicetree/bindings/display/msm/mdp5.txt >> +++ /dev/null >> @@ -1,132 +0,0 @@ >> -Qualcomm adreno/snapdragon MDP5 display controller >> - >> -Description: >> - >> -This is the bindings documentation for the MDP5 display >> -controller found in SoCs like MSM8974, APQ8084, MSM8916, MSM8994 and MSM8996. >> - >> -MDP5: >> -Required properties: >> -- compatible: >> - * "qcom,mdp5" - MDP5 >> -- reg: Physical base address and length of the controller's registers. >> -- reg-names: The names of register regions. The following regions are required: >> - * "mdp_phys" >> -- interrupts: Interrupt line from MDP5 to MDSS interrupt controller. >> -- clocks: device clocks. See ../clocks/clock-bindings.txt for details. >> -- clock-names: the following clocks are required. >> -- * "bus" >> -- * "iface" >> -- * "core" >> -- * "vsync" >> -- ports: contains the list of output ports from MDP. These connect to interfaces >> - that are external to the MDP hardware, such as HDMI, DSI, EDP etc (LVDS is a >> - special case since it is a part of the MDP block itself). >> - >> - Each output port contains an endpoint that describes how it is connected to an >> - external interface. These are described by the standard properties documented >> - here: >> - Documentation/devicetree/bindings/graph.txt >> - Documentation/devicetree/bindings/media/video-interfaces.txt >> - >> - The availability of output ports can vary across SoC revisions: >> - >> - For MSM8974 and APQ8084: >> - Port 0 -> MDP_INTF0 (eDP) >> - Port 1 -> MDP_INTF1 (DSI1) >> - Port 2 -> MDP_INTF2 (DSI2) >> - Port 3 -> MDP_INTF3 (HDMI) >> - >> - For MSM8916: >> - Port 0 -> MDP_INTF1 (DSI1) >> - >> - For MSM8994 and MSM8996: >> - Port 0 -> MDP_INTF1 (DSI1) >> - Port 1 -> MDP_INTF2 (DSI2) >> - Port 2 -> MDP_INTF3 (HDMI) >> - >> -Optional properties: >> -- clock-names: the following clocks are optional: >> - * "lut" >> - * "tbu" >> - * "tbu_rt" >> - >> -Example: >> - >> -/ { >> - ... >> - >> - mdss: mdss@1a00000 { >> - compatible = "qcom,mdss"; >> - reg = <0x1a00000 0x1000>, >> - <0x1ac8000 0x3000>; >> - reg-names = "mdss_phys", "vbif_phys"; >> - >> - power-domains = <&gcc MDSS_GDSC>; >> - >> - clocks = <&gcc GCC_MDSS_AHB_CLK>, >> - <&gcc GCC_MDSS_AXI_CLK>, >> - <&gcc GCC_MDSS_VSYNC_CLK>; >> - clock-names = "iface", >> - "bus", >> - "vsync" >> - >> - interrupts = <0 72 0>; >> - >> - interrupt-controller; >> - #interrupt-cells = <1>; >> - >> - #address-cells = <1>; >> - #size-cells = <1>; >> - ranges; >> - >> - mdp: mdp@1a01000 { >> - compatible = "qcom,mdp5"; >> - reg = <0x1a01000 0x90000>; >> - reg-names = "mdp_phys"; >> - >> - interrupt-parent = <&mdss>; >> - interrupts = <0 0>; >> - >> - clocks = <&gcc GCC_MDSS_AHB_CLK>, >> - <&gcc GCC_MDSS_AXI_CLK>, >> - <&gcc GCC_MDSS_MDP_CLK>, >> - <&gcc GCC_MDSS_VSYNC_CLK>; >> - clock-names = "iface", >> - "bus", >> - "core", >> - "vsync"; >> - >> - ports { >> - #address-cells = <1>; >> - #size-cells = <0>; >> - >> - port@0 { >> - reg = <0>; >> - mdp5_intf1_out: endpoint { >> - remote-endpoint = <&dsi0_in>; >> - }; >> - }; >> - }; >> - }; >> - >> - dsi0: dsi@1a98000 { >> - ... >> - ports { >> - ... >> - port@0 { >> - reg = <0>; >> - dsi0_in: endpoint { >> - remote-endpoint = <&mdp5_intf1_out>; >> - }; >> - }; >> - ... >> - }; >> - ... >> - }; >> - >> - dsi_phy0: dsi-phy@1a98300 { >> - ... >> - }; >> - }; >> -}; >> diff --git a/Documentation/devicetree/bindings/display/msm/qcom,mdp5.yaml b/Documentation/devicetree/bindings/display/msm/qcom,mdp5.yaml >> new file mode 100644 >> index 000000000000..cbcbe8b47e9b >> --- /dev/null >> +++ b/Documentation/devicetree/bindings/display/msm/qcom,mdp5.yaml >> @@ -0,0 +1,138 @@ >> +# SPDX-License-Identifier: GPL-2.0-only or BSD-2-Clause >> +%YAML 1.2 >> +--- >> +$id: http://devicetree.org/schemas/display/msm/qcom,mdp5.yaml# >> +$schema: http://devicetree.org/meta-schemas/core.yaml# >> + >> +title: Qualcomm Adreno/Snapdragon Mobile Display controller (MDP5) >> + >> +description: > >> + MDP5 display controller found in SoCs like MSM8974, APQ8084, MSM8916, MSM8994 >> + and MSM8996. >> + >> +maintainers: >> + - Dmitry Baryshkov <dmitry.baryshkov@linaro.org> >> + - Rob Clark <robdclark@gmail.com> >> + >> +properties: >> + compatible: >> + const: qcom,mdp5 >> + >> + reg: >> + maxItems: 1 >> + >> + reg-names: >> + items: >> + - const: mdp_phys >> + >> + interrupts: >> + maxItems: 1 >> + >> + clocks: >> + minItems: 4 >> + maxItems: 7 >> + >> + clock-names: >> + oneOf: >> + - minItems: 4 >> + items: >> + - const: iface >> + - const: bus >> + - const: core >> + - const: vsync >> + - const: lut >> + - const: tbu >> + - const: tbu_rt >> + #MSM8996 has additional iommu clock >> + - items: >> + - const: iface >> + - const: bus >> + - const: core >> + - const: iommu >> + - const: vsync >> + >> + interconnects: >> + minItems: 1 >> + items: >> + - description: Interconnect path from mdp0 (or a single mdp) port to the data bus >> + - description: Interconnect path from mdp1 port to the data bus >> + - description: Interconnect path from rotator port to the data bus >> + >> + interconnect-names: >> + minItems: 1 >> + items: >> + - const: mdp0-mem >> + - const: mdp1-mem >> + - const: rotator-mem >> + >> + iommus: >> + items: >> + - description: Phandle to apps_smmu node with SID mask for Hard-Fail port0 > > As Krzysztof has said many times, these documents describe the hardware, > not the DT format. Drop the "phandle" part. Ack > >> + power-domains: >> + maxItems: 1 >> + >> + operating-points-v2: true >> + opp-table: >> + type: object >> + >> + ports: >> + $ref: /schemas/graph.yaml#/properties/ports >> + description: | > > Should multiline descriptions be treated as a oneline string with `>`? Ack, I'm fine with either of them, let's use the > > >> + Contains the list of output ports from DPU device. These ports >> + connect to interfaces that are external to the DPU hardware, >> + such as DSI, DP etc. MDP5 devices support up to 4 ports:: > > How do these double colons render? Is this intentional? double colons is an escape for a single colon if I remember correcly. BTW: how to render the DT schema? > > - Marijn > >> + one or two DSI ports, HDMI and eDP. >> + >> + patternProperties: >> + "^port@[0-3]+$": >> + $ref: /schemas/graph.yaml#/properties/port >> + >> + # at least one port is required >> + required: >> + - port@0 >> + >> +required: >> + - compatible >> + - reg >> + - reg-names >> + - clocks >> + - clock-names >> + - ports >> + >> +additionalProperties: false >> + >> +examples: >> + - | >> + #include <dt-bindings/clock/qcom,gcc-msm8916.h> >> + #include <dt-bindings/interrupt-controller/arm-gic.h> >> + display-controller@1a01000 { >> + compatible = "qcom,mdp5"; >> + reg = <0x1a01000 0x90000>; >> + reg-names = "mdp_phys"; >> + >> + interrupt-parent = <&mdss>; >> + interrupts = <0>; >> + >> + clocks = <&gcc GCC_MDSS_AHB_CLK>, >> + <&gcc GCC_MDSS_AXI_CLK>, >> + <&gcc GCC_MDSS_MDP_CLK>, >> + <&gcc GCC_MDSS_VSYNC_CLK>; >> + clock-names = "iface", >> + "bus", >> + "core", >> + "vsync"; >> + >> + ports { >> + #address-cells = <1>; >> + #size-cells = <0>; >> + >> + port@0 { >> + reg = <0>; >> + endpoint { >> + remote-endpoint = <&dsi0_in>; >> + }; >> + }; >> + }; >> + }; >> +... >> -- >> 2.39.0 >>
On 2023-01-10 06:40:27, Dmitry Baryshkov wrote: > On 09/01/2023 09:49, Marijn Suijten wrote: > > On 2023-01-09 07:01:49, Dmitry Baryshkov wrote: <snip> > >> + description: | > > > > Should multiline descriptions be treated as a oneline string with `>`? > > Ack, I'm fine with either of them, let's use the > > > > > >> + Contains the list of output ports from DPU device. These ports > >> + connect to interfaces that are external to the DPU hardware, > >> + such as DSI, DP etc. MDP5 devices support up to 4 ports:: > > > > How do these double colons render? Is this intentional? > > double colons is an escape for a single colon if I remember correcly. I thought no escaping was necessary here, especially since this is already a value - it is a multiline string. > BTW: how to render the DT schema? I'm not sure if there's currently any rendering tool to view these docs in a "friendly" manner, e.g. an html page, or whether they're only used as specifications for DT validation. - Marijn
On 12/01/2023 00:29, Marijn Suijten wrote: > On 2023-01-10 06:40:27, Dmitry Baryshkov wrote: >> On 09/01/2023 09:49, Marijn Suijten wrote: >>> On 2023-01-09 07:01:49, Dmitry Baryshkov wrote: > <snip> >>>> + description: | >>> >>> Should multiline descriptions be treated as a oneline string with `>`? >> >> Ack, I'm fine with either of them, let's use the > >> >>> >>>> + Contains the list of output ports from DPU device. These ports >>>> + connect to interfaces that are external to the DPU hardware, >>>> + such as DSI, DP etc. MDP5 devices support up to 4 ports:: >>> >>> How do these double colons render? Is this intentional? >> >> double colons is an escape for a single colon if I remember correcly. > > I thought no escaping was necessary here, especially since this is > already a value - it is a multiline string. I was mostly following examples, grep :: through the dt-bindings. > >> BTW: how to render the DT schema? > > I'm not sure if there's currently any rendering tool to view these docs > in a "friendly" manner, e.g. an html page, or whether they're only used > as specifications for DT validation. Probably there will be one at some point. It might make good addition to devicetree.org. > > - Marijn
On 2023-01-12 00:31:33, Dmitry Baryshkov wrote: > On 12/01/2023 00:29, Marijn Suijten wrote: > > On 2023-01-10 06:40:27, Dmitry Baryshkov wrote: > >> On 09/01/2023 09:49, Marijn Suijten wrote: > >>> On 2023-01-09 07:01:49, Dmitry Baryshkov wrote: > > <snip> > >>>> + description: | > >>> > >>> Should multiline descriptions be treated as a oneline string with `>`? > >> > >> Ack, I'm fine with either of them, let's use the > > >> > >>> > >>>> + Contains the list of output ports from DPU device. These ports > >>>> + connect to interfaces that are external to the DPU hardware, > >>>> + such as DSI, DP etc. MDP5 devices support up to 4 ports:: > >>> > >>> How do these double colons render? Is this intentional? > >> > >> double colons is an escape for a single colon if I remember correcly. > > > > I thought no escaping was necessary here, especially since this is > > already a value - it is a multiline string. > > I was mostly following examples, grep :: through the dt-bindings. Saw that, maybe these "freeform" description strings are intended to be RST to support more elaborate rendering if/when that happens? > >> BTW: how to render the DT schema? > > > > I'm not sure if there's currently any rendering tool to view these docs > > in a "friendly" manner, e.g. an html page, or whether they're only used > > as specifications for DT validation. > > Probably there will be one at some point. It might make good addition to > devicetree.org. Would be super cool to have some "interactive" / properly rendered/colored docs up there for DT :) - Marijn
On Wed, Jan 11, 2023 at 11:35:53PM +0100, Marijn Suijten wrote: > On 2023-01-12 00:31:33, Dmitry Baryshkov wrote: > > On 12/01/2023 00:29, Marijn Suijten wrote: > > > On 2023-01-10 06:40:27, Dmitry Baryshkov wrote: > > >> On 09/01/2023 09:49, Marijn Suijten wrote: > > >>> On 2023-01-09 07:01:49, Dmitry Baryshkov wrote: > > > <snip> > > >>>> + description: | > > >>> > > >>> Should multiline descriptions be treated as a oneline string with `>`? Depends if you want to keep paragraphs. Generally, we use '|' or nothing. If just a colon (or ???), then I think you want '>'. I get tired of saying to drop unnecessary '|' in reviews. It would be nice to analyze the text to check what's needed automatically. > > >> Ack, I'm fine with either of them, let's use the > > > >> > > >>> > > >>>> + Contains the list of output ports from DPU device. These ports > > >>>> + connect to interfaces that are external to the DPU hardware, > > >>>> + such as DSI, DP etc. MDP5 devices support up to 4 ports:: > > >>> > > >>> How do these double colons render? Is this intentional? > > >> > > >> double colons is an escape for a single colon if I remember correcly. > > > > > > I thought no escaping was necessary here, especially since this is > > > already a value - it is a multiline string. > > > > I was mostly following examples, grep :: through the dt-bindings. > > Saw that, maybe these "freeform" description strings are intended to be > RST to support more elaborate rendering if/when that happens? No, though some experiments have been done in that regard. It seemed to work. > > >> BTW: how to render the DT schema? > > > > > > I'm not sure if there's currently any rendering tool to view these docs > > > in a "friendly" manner, e.g. an html page, or whether they're only used > > > as specifications for DT validation. > > > > Probably there will be one at some point. It might make good addition to > > devicetree.org. > > Would be super cool to have some "interactive" / properly > rendered/colored docs up there for DT :) One of the original goals was to transform the DT spec to schema docs and then generate the spec from the schemas. There's tools that do json-schema to docs already. They may just work. I haven't looked at them though as that's not really my itch and I simply don't have time. Maybe if we stop reviewing schemas for a while. Rob
On 12/01/2023 23:50, Rob Herring wrote: > On Wed, Jan 11, 2023 at 11:35:53PM +0100, Marijn Suijten wrote: >> On 2023-01-12 00:31:33, Dmitry Baryshkov wrote: >>> On 12/01/2023 00:29, Marijn Suijten wrote: >>>> On 2023-01-10 06:40:27, Dmitry Baryshkov wrote: >>>>> On 09/01/2023 09:49, Marijn Suijten wrote: >>>>>> On 2023-01-09 07:01:49, Dmitry Baryshkov wrote: >>>> <snip> >>>>>>> + description: | >>>>>> >>>>>> Should multiline descriptions be treated as a oneline string with `>`? > > Depends if you want to keep paragraphs. Generally, we use '|' or > nothing. If just a colon (or ???), then I think you want '>'. Ack, thanks for the explanation. I'll fix this for v6. > > I get tired of saying to drop unnecessary '|' in reviews. It would be > nice to analyze the text to check what's needed automatically. > > -- With best wishes Dmitry
On 2023-01-12 15:50:15, Rob Herring wrote: > On Wed, Jan 11, 2023 at 11:35:53PM +0100, Marijn Suijten wrote: > > On 2023-01-12 00:31:33, Dmitry Baryshkov wrote: > > > On 12/01/2023 00:29, Marijn Suijten wrote: > > > > On 2023-01-10 06:40:27, Dmitry Baryshkov wrote: > > > >> On 09/01/2023 09:49, Marijn Suijten wrote: > > > >>> On 2023-01-09 07:01:49, Dmitry Baryshkov wrote: > > > > <snip> > > > >>>> + description: | > > > >>> > > > >>> Should multiline descriptions be treated as a oneline string with `>`? > > Depends if you want to keep paragraphs. Generally, we use '|' or > nothing. If just a colon (or ???), then I think you want '>'. But doesn't that also affect how lines within paragraphs are flowed? Arguably it's only GitHub that doesn't "ignore" manual single newlines, the Markdown (and maybe also RST?) spec AFAIK state that multiline blocks will be turned into a single paragraph (automatically reflowing to width). > I get tired of saying to drop unnecessary '|' in reviews. It would be > nice to analyze the text to check what's needed automatically. And that's just one of the many things... > > > >> Ack, I'm fine with either of them, let's use the > > > > >> > > > >>> > > > >>>> + Contains the list of output ports from DPU device. These ports > > > >>>> + connect to interfaces that are external to the DPU hardware, > > > >>>> + such as DSI, DP etc. MDP5 devices support up to 4 ports:: > > > >>> > > > >>> How do these double colons render? Is this intentional? > > > >> > > > >> double colons is an escape for a single colon if I remember correcly. > > > > > > > > I thought no escaping was necessary here, especially since this is > > > > already a value - it is a multiline string. > > > > > > I was mostly following examples, grep :: through the dt-bindings. > > > > Saw that, maybe these "freeform" description strings are intended to be > > RST to support more elaborate rendering if/when that happens? > > No, though some experiments have been done in that regard. It seemed to > work. Hmm, the question is what format description blocks should adhere to, and if a double colon here makes sense and/or is required? > > > >> BTW: how to render the DT schema? > > > > > > > > I'm not sure if there's currently any rendering tool to view these docs > > > > in a "friendly" manner, e.g. an html page, or whether they're only used > > > > as specifications for DT validation. > > > > > > Probably there will be one at some point. It might make good addition to > > > devicetree.org. > > > > Would be super cool to have some "interactive" / properly > > rendered/colored docs up there for DT :) > > One of the original goals was to transform the DT spec to schema docs > and then generate the spec from the schemas. > > There's tools that do json-schema to docs already. They may just work. I > haven't looked at them though as that's not really my itch and I simply > don't have time. Maybe if we stop reviewing schemas for a while. Sure, as above we shoudn't have to render anything now nor any time soon, but it would be helpful to know what kind of format to adhere to in description blocks. - Marijn
diff --git a/Documentation/devicetree/bindings/display/msm/mdp5.txt b/Documentation/devicetree/bindings/display/msm/mdp5.txt deleted file mode 100644 index 65d03c58dee6..000000000000 --- a/Documentation/devicetree/bindings/display/msm/mdp5.txt +++ /dev/null @@ -1,132 +0,0 @@ -Qualcomm adreno/snapdragon MDP5 display controller - -Description: - -This is the bindings documentation for the MDP5 display -controller found in SoCs like MSM8974, APQ8084, MSM8916, MSM8994 and MSM8996. - -MDP5: -Required properties: -- compatible: - * "qcom,mdp5" - MDP5 -- reg: Physical base address and length of the controller's registers. -- reg-names: The names of register regions. The following regions are required: - * "mdp_phys" -- interrupts: Interrupt line from MDP5 to MDSS interrupt controller. -- clocks: device clocks. See ../clocks/clock-bindings.txt for details. -- clock-names: the following clocks are required. -- * "bus" -- * "iface" -- * "core" -- * "vsync" -- ports: contains the list of output ports from MDP. These connect to interfaces - that are external to the MDP hardware, such as HDMI, DSI, EDP etc (LVDS is a - special case since it is a part of the MDP block itself). - - Each output port contains an endpoint that describes how it is connected to an - external interface. These are described by the standard properties documented - here: - Documentation/devicetree/bindings/graph.txt - Documentation/devicetree/bindings/media/video-interfaces.txt - - The availability of output ports can vary across SoC revisions: - - For MSM8974 and APQ8084: - Port 0 -> MDP_INTF0 (eDP) - Port 1 -> MDP_INTF1 (DSI1) - Port 2 -> MDP_INTF2 (DSI2) - Port 3 -> MDP_INTF3 (HDMI) - - For MSM8916: - Port 0 -> MDP_INTF1 (DSI1) - - For MSM8994 and MSM8996: - Port 0 -> MDP_INTF1 (DSI1) - Port 1 -> MDP_INTF2 (DSI2) - Port 2 -> MDP_INTF3 (HDMI) - -Optional properties: -- clock-names: the following clocks are optional: - * "lut" - * "tbu" - * "tbu_rt" - -Example: - -/ { - ... - - mdss: mdss@1a00000 { - compatible = "qcom,mdss"; - reg = <0x1a00000 0x1000>, - <0x1ac8000 0x3000>; - reg-names = "mdss_phys", "vbif_phys"; - - power-domains = <&gcc MDSS_GDSC>; - - clocks = <&gcc GCC_MDSS_AHB_CLK>, - <&gcc GCC_MDSS_AXI_CLK>, - <&gcc GCC_MDSS_VSYNC_CLK>; - clock-names = "iface", - "bus", - "vsync" - - interrupts = <0 72 0>; - - interrupt-controller; - #interrupt-cells = <1>; - - #address-cells = <1>; - #size-cells = <1>; - ranges; - - mdp: mdp@1a01000 { - compatible = "qcom,mdp5"; - reg = <0x1a01000 0x90000>; - reg-names = "mdp_phys"; - - interrupt-parent = <&mdss>; - interrupts = <0 0>; - - clocks = <&gcc GCC_MDSS_AHB_CLK>, - <&gcc GCC_MDSS_AXI_CLK>, - <&gcc GCC_MDSS_MDP_CLK>, - <&gcc GCC_MDSS_VSYNC_CLK>; - clock-names = "iface", - "bus", - "core", - "vsync"; - - ports { - #address-cells = <1>; - #size-cells = <0>; - - port@0 { - reg = <0>; - mdp5_intf1_out: endpoint { - remote-endpoint = <&dsi0_in>; - }; - }; - }; - }; - - dsi0: dsi@1a98000 { - ... - ports { - ... - port@0 { - reg = <0>; - dsi0_in: endpoint { - remote-endpoint = <&mdp5_intf1_out>; - }; - }; - ... - }; - ... - }; - - dsi_phy0: dsi-phy@1a98300 { - ... - }; - }; -}; diff --git a/Documentation/devicetree/bindings/display/msm/qcom,mdp5.yaml b/Documentation/devicetree/bindings/display/msm/qcom,mdp5.yaml new file mode 100644 index 000000000000..cbcbe8b47e9b --- /dev/null +++ b/Documentation/devicetree/bindings/display/msm/qcom,mdp5.yaml @@ -0,0 +1,138 @@ +# SPDX-License-Identifier: GPL-2.0-only or BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/display/msm/qcom,mdp5.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Qualcomm Adreno/Snapdragon Mobile Display controller (MDP5) + +description: > + MDP5 display controller found in SoCs like MSM8974, APQ8084, MSM8916, MSM8994 + and MSM8996. + +maintainers: + - Dmitry Baryshkov <dmitry.baryshkov@linaro.org> + - Rob Clark <robdclark@gmail.com> + +properties: + compatible: + const: qcom,mdp5 + + reg: + maxItems: 1 + + reg-names: + items: + - const: mdp_phys + + interrupts: + maxItems: 1 + + clocks: + minItems: 4 + maxItems: 7 + + clock-names: + oneOf: + - minItems: 4 + items: + - const: iface + - const: bus + - const: core + - const: vsync + - const: lut + - const: tbu + - const: tbu_rt + #MSM8996 has additional iommu clock + - items: + - const: iface + - const: bus + - const: core + - const: iommu + - const: vsync + + interconnects: + minItems: 1 + items: + - description: Interconnect path from mdp0 (or a single mdp) port to the data bus + - description: Interconnect path from mdp1 port to the data bus + - description: Interconnect path from rotator port to the data bus + + interconnect-names: + minItems: 1 + items: + - const: mdp0-mem + - const: mdp1-mem + - const: rotator-mem + + iommus: + items: + - description: Phandle to apps_smmu node with SID mask for Hard-Fail port0 + + power-domains: + maxItems: 1 + + operating-points-v2: true + opp-table: + type: object + + ports: + $ref: /schemas/graph.yaml#/properties/ports + description: | + Contains the list of output ports from DPU device. These ports + connect to interfaces that are external to the DPU hardware, + such as DSI, DP etc. MDP5 devices support up to 4 ports:: + one or two DSI ports, HDMI and eDP. + + patternProperties: + "^port@[0-3]+$": + $ref: /schemas/graph.yaml#/properties/port + + # at least one port is required + required: + - port@0 + +required: + - compatible + - reg + - reg-names + - clocks + - clock-names + - ports + +additionalProperties: false + +examples: + - | + #include <dt-bindings/clock/qcom,gcc-msm8916.h> + #include <dt-bindings/interrupt-controller/arm-gic.h> + display-controller@1a01000 { + compatible = "qcom,mdp5"; + reg = <0x1a01000 0x90000>; + reg-names = "mdp_phys"; + + interrupt-parent = <&mdss>; + interrupts = <0>; + + clocks = <&gcc GCC_MDSS_AHB_CLK>, + <&gcc GCC_MDSS_AXI_CLK>, + <&gcc GCC_MDSS_MDP_CLK>, + <&gcc GCC_MDSS_VSYNC_CLK>; + clock-names = "iface", + "bus", + "core", + "vsync"; + + ports { + #address-cells = <1>; + #size-cells = <0>; + + port@0 { + reg = <0>; + endpoint { + remote-endpoint = <&dsi0_in>; + }; + }; + }; + }; +...
Convert the mdp5.txt into the yaml format. Changes to the existing (txt) schema: - MSM8996 has additional "iommu" clock, define it separately - Add new properties used on some of platforms: - interconnects, interconnect-names - iommus - power-domains - operating-points-v2, opp-table Signed-off-by: Dmitry Baryshkov <dmitry.baryshkov@linaro.org> --- .../devicetree/bindings/display/msm/mdp5.txt | 132 ----------------- .../bindings/display/msm/qcom,mdp5.yaml | 138 ++++++++++++++++++ 2 files changed, 138 insertions(+), 132 deletions(-) delete mode 100644 Documentation/devicetree/bindings/display/msm/mdp5.txt create mode 100644 Documentation/devicetree/bindings/display/msm/qcom,mdp5.yaml