[PATCH v3 0/3] Convert Microchip's HLCDC Text based DT bindings to JSON schema

[PATCH v3 0/3] Convert Microchip's HLCDC Text based DT bindings to JSON schema

[Dharma Balasubiramani]

Converted the text bindings to YAML and validated them individually using following commands

$ make dt_binding_check DT_SCHEMA_FILES=Documentation/devicetree/bindings/
$ make dtbs_check DT_SCHEMA_FILES=Documentation/devicetree/bindings/

changelogs are available in respective patches.

Dharma Balasubiramani (3):
  dt-bindings: display: convert Atmel's HLCDC to DT schema
  dt-bindings: atmel,hlcdc: convert pwm bindings to json-schema
  dt-bindings: mfd: atmel,hlcdc: Convert to DT schema format

 .../atmel/atmel,hlcdc-display-controller.yaml | 84 ++++++++++++++++
 .../bindings/display/atmel/hlcdc-dc.txt       | 75 --------------
 .../devicetree/bindings/mfd/atmel,hlcdc.yaml  | 97 +++++++++++++++++++
 .../devicetree/bindings/mfd/atmel-hlcdc.txt   | 56 -----------
 .../bindings/pwm/atmel,hlcdc-pwm.yaml         | 44 +++++++++
 .../bindings/pwm/atmel-hlcdc-pwm.txt          | 29 ------
 6 files changed, 225 insertions(+), 160 deletions(-)
 create mode 100644 Documentation/devicetree/bindings/display/atmel/atmel,hlcdc-display-controller.yaml
 delete mode 100644 Documentation/devicetree/bindings/display/atmel/hlcdc-dc.txt
 create mode 100644 Documentation/devicetree/bindings/mfd/atmel,hlcdc.yaml
 delete mode 100644 Documentation/devicetree/bindings/mfd/atmel-hlcdc.txt
 create mode 100644 Documentation/devicetree/bindings/pwm/atmel,hlcdc-pwm.yaml
 delete mode 100644 Documentation/devicetree/bindings/pwm/atmel-hlcdc-pwm.txt

-- 
2.25.1

[PATCH v3 1/3] dt-bindings: display: convert Atmel's HLCDC to DT schema

[Dharma Balasubiramani]

Convert the existing DT binding to DT schema of the Atmel's HLCDC display
controller.

Signed-off-by: Dharma Balasubiramani <dharma.b@microchip.com>
---
changelog
v2 -> v3
- Remove '|' in description, as there is no formatting to preserve.
- Ref video-interfaces as endpoint.
- Remove ref and description for bus-width.
- Add new line before the child node in example.
- Remove 'example 2', as it is not required for just one additional property.
v1 -> v2
- Remove the explicit copyrights.
- Modify filename like compatible.
- Modify title (drop words like binding/driver).
- Modify description actually describing the hardware and not the driver.
- Remove pinctrl properties which aren't required.
- Ref endpoint and not endpoint-base.
- Drop redundant info about bus-width description and add ref to video-interfaces.
- Move 'additionalProperties' after 'Required'.
- Drop parent node and it's other sub-device node which are not related here.
- Add compatible to example 2 and add comments that bus-width is the diff between two examples.
---
 .../atmel/atmel,hlcdc-display-controller.yaml | 84 +++++++++++++++++++
 .../bindings/display/atmel/hlcdc-dc.txt       | 75 -----------------
 2 files changed, 84 insertions(+), 75 deletions(-)
 create mode 100644 Documentation/devicetree/bindings/display/atmel/atmel,hlcdc-display-controller.yaml
 delete mode 100644 Documentation/devicetree/bindings/display/atmel/hlcdc-dc.txt

diff --git a/Documentation/devicetree/bindings/display/atmel/atmel,hlcdc-display-controller.yaml b/Documentation/devicetree/bindings/display/atmel/atmel,hlcdc-display-controller.yaml
new file mode 100644
index 000000000000..0c0871cb85f1
--- /dev/null
+++ b/Documentation/devicetree/bindings/display/atmel/atmel,hlcdc-display-controller.yaml
@@ -0,0 +1,84 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/display/atmel/atmel,hlcdc-display-controller.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Atmel's High LCD Controller (HLCDC)
+
+maintainers:
+  - Nicolas Ferre <nicolas.ferre@microchip.com>
+  - Alexandre Belloni <alexandre.belloni@bootlin.com>
+  - Claudiu Beznea <claudiu.beznea@tuxon.dev>
+
+description:
+  The LCD Controller (LCDC) consists of logic for transferring LCD image
+  data from an external display buffer to a TFT LCD panel. The LCDC has one
+  display input buffer per layer that fetches pixels through the single bus
+  host interface and a look-up table to allow palletized display
+  configurations.
+
+properties:
+  compatible:
+    const: atmel,hlcdc-display-controller
+
+  '#address-cells':
+    const: 1
+
+  '#size-cells':
+    const: 0
+
+  port@0:
+    $ref: /schemas/graph.yaml#/$defs/port-base
+    unevaluatedProperties: false
+    description:
+      Output endpoint of the controller, connecting the LCD panel signals.
+
+    properties:
+      '#address-cells':
+        const: 1
+
+      '#size-cells':
+        const: 0
+
+      reg:
+        maxItems: 1
+
+      endpoint:
+        $ref: /schemas/media/video-interfaces.yaml#
+        unevaluatedProperties: false
+        description:
+          Endpoint connecting the LCD panel signals.
+
+        properties:
+          bus-width:
+            enum: [ 12, 16, 18, 24 ]
+
+required:
+  - '#address-cells'
+  - '#size-cells'
+  - compatible
+  - port@0
+
+additionalProperties: false
+
+examples:
+  - |
+    display-controller {
+      compatible = "atmel,hlcdc-display-controller";
+      pinctrl-names = "default";
+      pinctrl-0 = <&pinctrl_lcd_base &pinctrl_lcd_rgb888>;
+      #address-cells = <1>;
+      #size-cells = <0>;
+
+      port@0 {
+        #address-cells = <1>;
+        #size-cells = <0>;
+        reg = <0>;
+
+        hlcdc_panel_output: endpoint@0 {
+          reg = <0>;
+          remote-endpoint = <&panel_input>;
+        };
+      };
+    };
diff --git a/Documentation/devicetree/bindings/display/atmel/hlcdc-dc.txt b/Documentation/devicetree/bindings/display/atmel/hlcdc-dc.txt
deleted file mode 100644
index 923aea25344c..000000000000
--- a/Documentation/devicetree/bindings/display/atmel/hlcdc-dc.txt
+++ /dev/null
@@ -1,75 +0,0 @@
-Device-Tree bindings for Atmel's HLCDC (High LCD Controller) DRM driver
-
-The Atmel HLCDC Display Controller is subdevice of the HLCDC MFD device.
-See ../../mfd/atmel-hlcdc.txt for more details.
-
-Required properties:
- - compatible: value should be "atmel,hlcdc-display-controller"
- - pinctrl-names: the pin control state names. Should contain "default".
- - pinctrl-0: should contain the default pinctrl states.
- - #address-cells: should be set to 1.
- - #size-cells: should be set to 0.
-
-Required children nodes:
- Children nodes are encoding available output ports and their connections
- to external devices using the OF graph representation (see ../graph.txt).
- At least one port node is required.
-
-Optional properties in grandchild nodes:
- Any endpoint grandchild node may specify a desired video interface
- according to ../../media/video-interfaces.txt, specifically
- - bus-width: recognized values are <12>, <16>, <18> and <24>, and
-   override any output mode selection heuristic, forcing "rgb444",
-   "rgb565", "rgb666" and "rgb888" respectively.
-
-Example:
-
-	hlcdc: hlcdc@f0030000 {
-		compatible = "atmel,sama5d3-hlcdc";
-		reg = <0xf0030000 0x2000>;
-		interrupts = <36 IRQ_TYPE_LEVEL_HIGH 0>;
-		clocks = <&lcdc_clk>, <&lcdck>, <&clk32k>;
-		clock-names = "periph_clk","sys_clk", "slow_clk";
-
-		hlcdc-display-controller {
-			compatible = "atmel,hlcdc-display-controller";
-			pinctrl-names = "default";
-			pinctrl-0 = <&pinctrl_lcd_base &pinctrl_lcd_rgb888>;
-			#address-cells = <1>;
-			#size-cells = <0>;
-
-			port@0 {
-				#address-cells = <1>;
-				#size-cells = <0>;
-				reg = <0>;
-
-				hlcdc_panel_output: endpoint@0 {
-					reg = <0>;
-					remote-endpoint = <&panel_input>;
-				};
-			};
-		};
-
-		hlcdc_pwm: hlcdc-pwm {
-			compatible = "atmel,hlcdc-pwm";
-			pinctrl-names = "default";
-			pinctrl-0 = <&pinctrl_lcd_pwm>;
-			#pwm-cells = <3>;
-		};
-	};
-
-Example 2: With a video interface override to force rgb565; as above
-but with these changes/additions:
-
-	&hlcdc {
-		hlcdc-display-controller {
-			pinctrl-names = "default";
-			pinctrl-0 = <&pinctrl_lcd_base &pinctrl_lcd_rgb565>;
-
-			port@0 {
-				hlcdc_panel_output: endpoint@0 {
-					bus-width = <16>;
-				};
-			};
-		};
-	};
-- 
2.25.1

[PATCH v3 2/3] dt-bindings: atmel,hlcdc: convert pwm bindings to json-schema

[Dharma Balasubiramani]

Convert device tree bindings for Atmel's HLCDC PWM controller to YAML
format.

Signed-off-by: Dharma Balasubiramani <dharma.b@microchip.com>
Reviewed-by: Conor Dooley <conor.dooley@microchip.com>
---
changelog
v2 -> v3
- Remove '|' in description, as there is no formatting to preserve.
- Delete the description for pwm-cells.
- Drop the label for pwm node as it not used.
v1 -> v2
- Remove the explicit copyrights.
- Modify title (not include words like binding/driver).
- Modify description actually describing the hardware and not the driver.
- Remove pinctrl properties which aren't required.
- Drop parent node and it's other sub-device node which are not related here.
---
 .../bindings/pwm/atmel,hlcdc-pwm.yaml         | 44 +++++++++++++++++++
 .../bindings/pwm/atmel-hlcdc-pwm.txt          | 29 ------------
 2 files changed, 44 insertions(+), 29 deletions(-)
 create mode 100644 Documentation/devicetree/bindings/pwm/atmel,hlcdc-pwm.yaml
 delete mode 100644 Documentation/devicetree/bindings/pwm/atmel-hlcdc-pwm.txt

diff --git a/Documentation/devicetree/bindings/pwm/atmel,hlcdc-pwm.yaml b/Documentation/devicetree/bindings/pwm/atmel,hlcdc-pwm.yaml
new file mode 100644
index 000000000000..4f4cc21fe4f7
--- /dev/null
+++ b/Documentation/devicetree/bindings/pwm/atmel,hlcdc-pwm.yaml
@@ -0,0 +1,44 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/pwm/atmel,hlcdc-pwm.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Atmel's HLCDC's PWM controller
+
+maintainers:
+  - Nicolas Ferre <nicolas.ferre@microchip.com>
+  - Alexandre Belloni <alexandre.belloni@bootlin.com>
+  - Claudiu Beznea <claudiu.beznea@tuxon.dev>
+
+description:
+  The LCDC integrates a Pulse Width Modulation (PWM) Controller. This block
+  generates the LCD contrast control signal (LCD_PWM) that controls the
+  display's contrast by software. LCDC_PWM is an 8-bit PWM signal that can be
+  converted to an analog voltage with a simple passive filter. LCD display
+  panels have different backlight specifications in terms of minimum/maximum
+  values for PWM frequency. If the LCDC PWM frequency range does not match the
+  LCD display panel, it is possible to use the standalone PWM Controller to
+  drive the backlight.
+
+properties:
+  compatible:
+    const: atmel,hlcdc-pwm
+
+  "#pwm-cells":
+    const: 3
+
+required:
+  - compatible
+  - "#pwm-cells"
+
+additionalProperties: false
+
+examples:
+  - |
+    pwm {
+      compatible = "atmel,hlcdc-pwm";
+      pinctrl-names = "default";
+      pinctrl-0 = <&pinctrl_lcd_pwm>;
+      #pwm-cells = <3>;
+    };
diff --git a/Documentation/devicetree/bindings/pwm/atmel-hlcdc-pwm.txt b/Documentation/devicetree/bindings/pwm/atmel-hlcdc-pwm.txt
deleted file mode 100644
index afa501bf7f94..000000000000
--- a/Documentation/devicetree/bindings/pwm/atmel-hlcdc-pwm.txt
+++ /dev/null
@@ -1,29 +0,0 @@
-Device-Tree bindings for Atmel's HLCDC (High-end LCD Controller) PWM driver
-
-The Atmel HLCDC PWM is subdevice of the HLCDC MFD device.
-See ../mfd/atmel-hlcdc.txt for more details.
-
-Required properties:
- - compatible: value should be one of the following:
-   "atmel,hlcdc-pwm"
- - pinctr-names: the pin control state names. Should contain "default".
- - pinctrl-0: should contain the pinctrl states described by pinctrl
-   default.
- - #pwm-cells: should be set to 3. This PWM chip use the default 3 cells
-   bindings defined in pwm.yaml in this directory.
-
-Example:
-
-	hlcdc: hlcdc@f0030000 {
-		compatible = "atmel,sama5d3-hlcdc";
-		reg = <0xf0030000 0x2000>;
-		clocks = <&lcdc_clk>, <&lcdck>, <&clk32k>;
-		clock-names = "periph_clk","sys_clk", "slow_clk";
-
-		hlcdc_pwm: hlcdc-pwm {
-			compatible = "atmel,hlcdc-pwm";
-			pinctrl-names = "default";
-			pinctrl-0 = <&pinctrl_lcd_pwm>;
-			#pwm-cells = <3>;
-		};
-	};
-- 
2.25.1

[PATCH v3 3/3] dt-bindings: mfd: atmel,hlcdc: Convert to DT schema format

[Dharma Balasubiramani]

Convert the atmel,hlcdc binding to DT schema format.

Adjust the clock-names property to clarify that the LCD controller expects
one of these clocks (either sys_clk or lvds_pll_clk to be present but not
both) along with the slow_clk and periph_clk. This alignment with the actual
hardware requirements will enable accurate device tree configuration for
systems using the HLCDC IP.

Signed-off-by: Dharma Balasubiramani <dharma.b@microchip.com>
---
changelog
v2 -> v3
- Rename hlcdc-display-controller and hlcdc-pwm to generic names.
- Modify the description by removing the unwanted comments and '|'.
- Modify clock-names simpler.
v1 -> v2
- Remove the explicit copyrights.
- Modify title (not include words like binding/driver).
- Modify description actually describing the hardware and not the driver.
- Add details of lvds_pll addition in commit message.
- Ref endpoint and not endpoint-base.
- Fix coding style.
...
 .../devicetree/bindings/mfd/atmel,hlcdc.yaml  | 97 +++++++++++++++++++
 .../devicetree/bindings/mfd/atmel-hlcdc.txt   | 56 -----------
 2 files changed, 97 insertions(+), 56 deletions(-)
 create mode 100644 Documentation/devicetree/bindings/mfd/atmel,hlcdc.yaml
 delete mode 100644 Documentation/devicetree/bindings/mfd/atmel-hlcdc.txt

diff --git a/Documentation/devicetree/bindings/mfd/atmel,hlcdc.yaml b/Documentation/devicetree/bindings/mfd/atmel,hlcdc.yaml
new file mode 100644
index 000000000000..eccc998ac42c
--- /dev/null
+++ b/Documentation/devicetree/bindings/mfd/atmel,hlcdc.yaml
@@ -0,0 +1,97 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/mfd/atmel,hlcdc.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Atmel's HLCD Controller
+
+maintainers:
+  - Nicolas Ferre <nicolas.ferre@microchip.com>
+  - Alexandre Belloni <alexandre.belloni@bootlin.com>
+  - Claudiu Beznea <claudiu.beznea@tuxon.dev>
+
+description:
+  The Atmel HLCDC (HLCD Controller) IP available on Atmel SoCs exposes two
+  subdevices, a PWM chip and a Display Controller.
+
+properties:
+  compatible:
+    enum:
+      - atmel,at91sam9n12-hlcdc
+      - atmel,at91sam9x5-hlcdc
+      - atmel,sama5d2-hlcdc
+      - atmel,sama5d3-hlcdc
+      - atmel,sama5d4-hlcdc
+      - microchip,sam9x60-hlcdc
+      - microchip,sam9x75-xlcdc
+
+  reg:
+    maxItems: 1
+
+  interrupts:
+    maxItems: 1
+
+  clocks:
+    maxItems: 3
+
+  clock-names:
+    items:
+      - const: periph_clk
+      - enum: [sys_clk, lvds_pll_clk]
+      - const: slow_clk
+
+  display-controller:
+    $ref: /schemas/display/atmel/atmel,hlcdc-display-controller.yaml
+
+  pwm:
+    $ref: /schemas/pwm/atmel,hlcdc-pwm.yaml
+
+required:
+  - compatible
+  - reg
+  - clocks
+  - clock-names
+  - interrupts
+
+additionalProperties: false
+
+examples:
+  - |
+    #include <dt-bindings/clock/at91.h>
+    #include <dt-bindings/dma/at91.h>
+    #include <dt-bindings/interrupt-controller/arm-gic.h>
+
+    lcd_controller: lcd-controller@f0030000 {
+      compatible = "atmel,sama5d3-hlcdc";
+      reg = <0xf0030000 0x2000>;
+      clocks = <&lcdc_clk>, <&lcdck>, <&clk32k>;
+      clock-names = "periph_clk", "sys_clk", "slow_clk";
+      interrupts = <36 IRQ_TYPE_LEVEL_HIGH 0>;
+
+      display-controller {
+        compatible = "atmel,hlcdc-display-controller";
+        pinctrl-names = "default";
+        pinctrl-0 = <&pinctrl_lcd_base &pinctrl_lcd_rgb888>;
+        #address-cells = <1>;
+        #size-cells = <0>;
+
+        port@0 {
+          #address-cells = <1>;
+          #size-cells = <0>;
+          reg = <0>;
+
+          hlcdc_panel_output: endpoint@0 {
+            reg = <0>;
+            remote-endpoint = <&panel_input>;
+          };
+        };
+      };
+
+      pwm {
+        compatible = "atmel,hlcdc-pwm";
+        pinctrl-names = "default";
+        pinctrl-0 = <&pinctrl_lcd_pwm>;
+        #pwm-cells = <3>;
+      };
+    };
diff --git a/Documentation/devicetree/bindings/mfd/atmel-hlcdc.txt b/Documentation/devicetree/bindings/mfd/atmel-hlcdc.txt
deleted file mode 100644
index 7de696eefaed..000000000000
--- a/Documentation/devicetree/bindings/mfd/atmel-hlcdc.txt
+++ /dev/null
@@ -1,56 +0,0 @@
-Device-Tree bindings for Atmel's HLCDC (High LCD Controller) MFD driver
-
-Required properties:
- - compatible: value should be one of the following:
-   "atmel,at91sam9n12-hlcdc"
-   "atmel,at91sam9x5-hlcdc"
-   "atmel,sama5d2-hlcdc"
-   "atmel,sama5d3-hlcdc"
-   "atmel,sama5d4-hlcdc"
-   "microchip,sam9x60-hlcdc"
-   "microchip,sam9x75-xlcdc"
- - reg: base address and size of the HLCDC device registers.
- - clock-names: the name of the 3 clocks requested by the HLCDC device.
-   Should contain "periph_clk", "sys_clk" and "slow_clk".
- - clocks: should contain the 3 clocks requested by the HLCDC device.
- - interrupts: should contain the description of the HLCDC interrupt line
-
-The HLCDC IP exposes two subdevices:
- - a PWM chip: see ../pwm/atmel-hlcdc-pwm.txt
- - a Display Controller: see ../display/atmel/hlcdc-dc.txt
-
-Example:
-
-	hlcdc: hlcdc@f0030000 {
-		compatible = "atmel,sama5d3-hlcdc";
-		reg = <0xf0030000 0x2000>;
-		clocks = <&lcdc_clk>, <&lcdck>, <&clk32k>;
-		clock-names = "periph_clk","sys_clk", "slow_clk";
-		interrupts = <36 IRQ_TYPE_LEVEL_HIGH 0>;
-
-		hlcdc-display-controller {
-			compatible = "atmel,hlcdc-display-controller";
-			pinctrl-names = "default";
-			pinctrl-0 = <&pinctrl_lcd_base &pinctrl_lcd_rgb888>;
-			#address-cells = <1>;
-			#size-cells = <0>;
-
-			port@0 {
-				#address-cells = <1>;
-				#size-cells = <0>;
-				reg = <0>;
-
-				hlcdc_panel_output: endpoint@0 {
-					reg = <0>;
-					remote-endpoint = <&panel_input>;
-				};
-			};
-		};
-
-		hlcdc_pwm: hlcdc-pwm {
-			compatible = "atmel,hlcdc-pwm";
-			pinctrl-names = "default";
-			pinctrl-0 = <&pinctrl_lcd_pwm>;
-			#pwm-cells = <3>;
-		};
-	};
-- 
2.25.1

Re: [PATCH v3 2/3] dt-bindings: atmel,hlcdc: convert pwm bindings to json-schema

[Uwe Kleine-König]

[-- Attachment #1: Type: text/plain, Size: 731 bytes --]

Hello,

On Thu, Jan 18, 2024 at 02:56:11PM +0530, Dharma Balasubiramani wrote:
> Convert device tree bindings for Atmel's HLCDC PWM controller to YAML
> format.
> 
> Signed-off-by: Dharma Balasubiramani <dharma.b@microchip.com>
> Reviewed-by: Conor Dooley <conor.dooley@microchip.com>

Reviewed-by: Uwe Kleine-König <u.kleine-koenig@pengutronix.de>

I will update the short log to

	dt-bindings: pwm: atmel,hlcdc: Convert bindings to json-schema

to match my preferences (unless you object) and apply for next after the
merge window.

Best regards
Uwe

-- 
Pengutronix e.K.                           | Uwe Kleine-König            |
Industrial Linux Solutions                 | https://www.pengutronix.de/ |

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 488 bytes --]

Re: [PATCH v3 1/3] dt-bindings: display: convert Atmel's HLCDC to DT schema

[Conor Dooley]

[-- Attachment #1: Type: text/plain, Size: 768 bytes --]

On Thu, Jan 18, 2024 at 02:56:10PM +0530, Dharma Balasubiramani wrote:
> Convert the existing DT binding to DT schema of the Atmel's HLCDC display
> controller.
> 
> Signed-off-by: Dharma Balasubiramani <dharma.b@microchip.com>
> ---
> changelog
> v2 -> v3
> - Remove '|' in description, as there is no formatting to preserve.
> - Ref video-interfaces as endpoint.
> - Remove ref and description for bus-width.
> - Add new line before the child node in example.

> - Remove 'example 2', as it is not required for just one additional property.

Rob's comment on the previous version was:
| Just 1 extra property doesn't justify 2 examples.
| 
| In any case, drop the partial examples and just have 1 complete example 
| in the MFD binding schema.


[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 228 bytes --]

Re: [PATCH v3 3/3] dt-bindings: mfd: atmel,hlcdc: Convert to DT schema format

[Conor Dooley]

[-- Attachment #1: Type: text/plain, Size: 3167 bytes --]

On Thu, Jan 18, 2024 at 02:56:12PM +0530, Dharma Balasubiramani wrote:
> Convert the atmel,hlcdc binding to DT schema format.
> 
> Adjust the clock-names property to clarify that the LCD controller expects
> one of these clocks (either sys_clk or lvds_pll_clk to be present but not
> both) along with the slow_clk and periph_clk. This alignment with the actual
> hardware requirements will enable accurate device tree configuration for
> systems using the HLCDC IP.
> 
> Signed-off-by: Dharma Balasubiramani <dharma.b@microchip.com>
> ---
> changelog
> v2 -> v3
> - Rename hlcdc-display-controller and hlcdc-pwm to generic names.
> - Modify the description by removing the unwanted comments and '|'.
> - Modify clock-names simpler.
> v1 -> v2
> - Remove the explicit copyrights.
> - Modify title (not include words like binding/driver).
> - Modify description actually describing the hardware and not the driver.
> - Add details of lvds_pll addition in commit message.
> - Ref endpoint and not endpoint-base.
> - Fix coding style.
> ...
>  .../devicetree/bindings/mfd/atmel,hlcdc.yaml  | 97 +++++++++++++++++++
>  .../devicetree/bindings/mfd/atmel-hlcdc.txt   | 56 -----------
>  2 files changed, 97 insertions(+), 56 deletions(-)
>  create mode 100644 Documentation/devicetree/bindings/mfd/atmel,hlcdc.yaml
>  delete mode 100644 Documentation/devicetree/bindings/mfd/atmel-hlcdc.txt
> 
> diff --git a/Documentation/devicetree/bindings/mfd/atmel,hlcdc.yaml b/Documentation/devicetree/bindings/mfd/atmel,hlcdc.yaml
> new file mode 100644
> index 000000000000..eccc998ac42c
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/mfd/atmel,hlcdc.yaml
> @@ -0,0 +1,97 @@
> +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
> +%YAML 1.2
> +---
> +$id: http://devicetree.org/schemas/mfd/atmel,hlcdc.yaml#
> +$schema: http://devicetree.org/meta-schemas/core.yaml#
> +
> +title: Atmel's HLCD Controller
> +
> +maintainers:
> +  - Nicolas Ferre <nicolas.ferre@microchip.com>
> +  - Alexandre Belloni <alexandre.belloni@bootlin.com>
> +  - Claudiu Beznea <claudiu.beznea@tuxon.dev>
> +
> +description:
> +  The Atmel HLCDC (HLCD Controller) IP available on Atmel SoCs exposes two
> +  subdevices, a PWM chip and a Display Controller.
> +
> +properties:
> +  compatible:
> +    enum:
> +      - atmel,at91sam9n12-hlcdc
> +      - atmel,at91sam9x5-hlcdc
> +      - atmel,sama5d2-hlcdc
> +      - atmel,sama5d3-hlcdc
> +      - atmel,sama5d4-hlcdc
> +      - microchip,sam9x60-hlcdc
> +      - microchip,sam9x75-xlcdc
> +
> +  reg:
> +    maxItems: 1
> +
> +  interrupts:
> +    maxItems: 1
> +
> +  clocks:
> +    maxItems: 3

Hmm, one thing I probably should have said on the previous version, but
I missed somehow: It would be good to add an items list to the clocks
property here to explain what the 3 clocks are/are used for - especially
since there is additional complexity being added here to use either the
sys or lvds clocks.

Thanks,
Conor.

> +
> +  clock-names:
> +    items:
> +      - const: periph_clk
> +      - enum: [sys_clk, lvds_pll_clk]
> +      - const: slow_clk

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 228 bytes --]

Re: [PATCH v3 0/3] Convert Microchip's HLCDC Text based DT bindings to JSON schema

[Sam Ravnborg]

Hi Dharma et al.

On Thu, Jan 18, 2024 at 02:56:09PM +0530, Dharma Balasubiramani wrote:
> Converted the text bindings to YAML and validated them individually using following commands
> 
> $ make dt_binding_check DT_SCHEMA_FILES=Documentation/devicetree/bindings/
> $ make dtbs_check DT_SCHEMA_FILES=Documentation/devicetree/bindings/
> 
> changelogs are available in respective patches.
> 
> Dharma Balasubiramani (3):
>   dt-bindings: display: convert Atmel's HLCDC to DT schema
>   dt-bindings: atmel,hlcdc: convert pwm bindings to json-schema
>   dt-bindings: mfd: atmel,hlcdc: Convert to DT schema format

I know this is a bit late to ask - sorry in advance.

The binding describes the single IP block as a multi functional device,
but it is a single IP block that includes the display controller and a
simple pwm that can be used for contrast or backlight.

If we ignore the fact that the current drivers for hlcdc uses an mfd
abstraction, is this then the optimal way to describe the HW?


In one of my stale git tree I converted atmel lcdc to DT, and here
I used:

+  "#pwm-cells":
+    description:
+      This PWM chip use the default 3 cells bindings
+      defined in ../../pwm/pwm.yaml.
+    const: 3
+
+  clocks:
+    maxItems: 2
+
+  clock-names:
+    maxItems: 2
+    items:
+      - const: lcdc_clk
+      - const: hclk

This proved to be a simple way to describe the HW.

To make the DT binding backward compatible you likely need to add a few
compatible that otherwise would have been left out - but that should do
the trick.

The current atmel hlcdc driver that is split in three is IMO an
over-engineering, and the driver could benefit merging it all in one.
And the binding should not prevent this.

	Sam

Re: [PATCH v3 1/3] dt-bindings: display: convert Atmel's HLCDC to DT schema

[Dharma.B]

On 18/01/24 9:01 pm, Conor Dooley wrote:
> On Thu, Jan 18, 2024 at 02:56:10PM +0530, Dharma Balasubiramani wrote:
>> Convert the existing DT binding to DT schema of the Atmel's HLCDC display
>> controller.
>>
>> Signed-off-by: Dharma Balasubiramani<dharma.b@microchip.com>
>> ---
>> changelog
>> v2 -> v3
>> - Remove '|' in description, as there is no formatting to preserve.
>> - Ref video-interfaces as endpoint.
>> - Remove ref and description for bus-width.
>> - Add new line before the child node in example.
>> - Remove 'example 2', as it is not required for just one additional property.
> Rob's comment on the previous version was:
> | Just 1 extra property doesn't justify 2 examples.
> |
> | In any case, drop the partial examples and just have 1 complete example
> | in the MFD binding schema.
> 
Okay understood, I will include the 'bus-width' in the example.
-- 
With Best Regards,
Dharma B.

Re: [PATCH v3 3/3] dt-bindings: mfd: atmel,hlcdc: Convert to DT schema format

[Dharma.B]

On 18/01/24 9:10 pm, Conor Dooley wrote:
> On Thu, Jan 18, 2024 at 02:56:12PM +0530, Dharma Balasubiramani wrote:
>> Convert the atmel,hlcdc binding to DT schema format.
>>
>> Adjust the clock-names property to clarify that the LCD controller expects
>> one of these clocks (either sys_clk or lvds_pll_clk to be present but not
>> both) along with the slow_clk and periph_clk. This alignment with the actual
>> hardware requirements will enable accurate device tree configuration for
>> systems using the HLCDC IP.
>>
>> Signed-off-by: Dharma Balasubiramani<dharma.b@microchip.com>
>> ---
>> changelog
>> v2 -> v3
>> - Rename hlcdc-display-controller and hlcdc-pwm to generic names.
>> - Modify the description by removing the unwanted comments and '|'.
>> - Modify clock-names simpler.
>> v1 -> v2
>> - Remove the explicit copyrights.
>> - Modify title (not include words like binding/driver).
>> - Modify description actually describing the hardware and not the driver.
>> - Add details of lvds_pll addition in commit message.
>> - Ref endpoint and not endpoint-base.
>> - Fix coding style.
>> ...
>>   .../devicetree/bindings/mfd/atmel,hlcdc.yaml  | 97 +++++++++++++++++++
>>   .../devicetree/bindings/mfd/atmel-hlcdc.txt   | 56 -----------
>>   2 files changed, 97 insertions(+), 56 deletions(-)
>>   create mode 100644 Documentation/devicetree/bindings/mfd/atmel,hlcdc.yaml
>>   delete mode 100644 Documentation/devicetree/bindings/mfd/atmel-hlcdc.txt
>>
>> diff --git a/Documentation/devicetree/bindings/mfd/atmel,hlcdc.yaml b/Documentation/devicetree/bindings/mfd/atmel,hlcdc.yaml
>> new file mode 100644
>> index 000000000000..eccc998ac42c
>> --- /dev/null
>> +++ b/Documentation/devicetree/bindings/mfd/atmel,hlcdc.yaml
>> @@ -0,0 +1,97 @@
>> +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
>> +%YAML 1.2
>> +---
>> +$id:http://devicetree.org/schemas/mfd/atmel,hlcdc.yaml#
>> +$schema:http://devicetree.org/meta-schemas/core.yaml#
>> +
>> +title: Atmel's HLCD Controller
>> +
>> +maintainers:
>> +  - Nicolas Ferre<nicolas.ferre@microchip.com>
>> +  - Alexandre Belloni<alexandre.belloni@bootlin.com>
>> +  - Claudiu Beznea<claudiu.beznea@tuxon.dev>
>> +
>> +description:
>> +  The Atmel HLCDC (HLCD Controller) IP available on Atmel SoCs exposes two
>> +  subdevices, a PWM chip and a Display Controller.
>> +
>> +properties:
>> +  compatible:
>> +    enum:
>> +      - atmel,at91sam9n12-hlcdc
>> +      - atmel,at91sam9x5-hlcdc
>> +      - atmel,sama5d2-hlcdc
>> +      - atmel,sama5d3-hlcdc
>> +      - atmel,sama5d4-hlcdc
>> +      - microchip,sam9x60-hlcdc
>> +      - microchip,sam9x75-xlcdc
>> +
>> +  reg:
>> +    maxItems: 1
>> +
>> +  interrupts:
>> +    maxItems: 1
>> +
>> +  clocks:
>> +    maxItems: 3
> Hmm, one thing I probably should have said on the previous version, but
> I missed somehow: It would be good to add an items list to the clocks
> property here to explain what the 3 clocks are/are used for - especially
> since there is additional complexity being added here to use either the
> sys or lvds clocks.
May I inquire if this approach is likely to be effective?

   clocks:
     items:
       - description: peripheral clock
       - description: generic clock or lvds pll clock
           Once the LVDS PLL is enabled, the pixel clock is used as the
           clock for LCDC, so its GCLK is no longer needed.
       - description: slow clock
     maxItems: 3

-- 
With Best Regards,
Dharma B.
> 
> Thanks,
> Conor.
> 
>> +
>> +  clock-names:
>> +    items:
>> +      - const: periph_clk
>> +      - enum: [sys_clk, lvds_pll_clk]
>> +      - const: slow_clk

Re: [PATCH v3 0/3] Convert Microchip's HLCDC Text based DT bindings to JSON schema

[Dharma.B]

Hi Sam,
On 19/01/24 1:00 am, Sam Ravnborg wrote:
> [You don't often get email from sam@ravnborg.org. Learn why this is important at https://aka.ms/LearnAboutSenderIdentification ]
> 
> EXTERNAL EMAIL: Do not click links or open attachments unless you know the content is safe
> 
> Hi Dharma et al.
> 
> On Thu, Jan 18, 2024 at 02:56:09PM +0530, Dharma Balasubiramani wrote:
>> Converted the text bindings to YAML and validated them individually using following commands
>>
>> $ make dt_binding_check DT_SCHEMA_FILES=Documentation/devicetree/bindings/
>> $ make dtbs_check DT_SCHEMA_FILES=Documentation/devicetree/bindings/
>>
>> changelogs are available in respective patches.
>>
>> Dharma Balasubiramani (3):
>>    dt-bindings: display: convert Atmel's HLCDC to DT schema
>>    dt-bindings: atmel,hlcdc: convert pwm bindings to json-schema
>>    dt-bindings: mfd: atmel,hlcdc: Convert to DT schema format
> 
> I know this is a bit late to ask - sorry in advance.
> 
> The binding describes the single IP block as a multi functional device,
> but it is a single IP block that includes the display controller and a
> simple pwm that can be used for contrast or backlight.
yes.
> 
> If we ignore the fact that the current drivers for hlcdc uses an mfd
> abstraction, is this then the optimal way to describe the HW?
> 
> 
> In one of my stale git tree I converted atmel lcdc to DT, and here
Are you referring the "bindings/display/atmel,lcdc.txt"?
> I used:
> 
> +  "#pwm-cells":
> +    description:
> +      This PWM chip use the default 3 cells bindings
> +      defined in ../../pwm/pwm.yaml.
> +    const: 3
> +
> +  clocks:
> +    maxItems: 2
> +
> +  clock-names:
> +    maxItems: 2
> +    items:
> +      - const: lcdc_clk
> +      - const: hclk
> 
> This proved to be a simple way to describe the HW.
> 
> To make the DT binding backward compatible you likely need to add a few
> compatible that otherwise would have been left out - but that should do
> the trick.
again you mean the compatibles from atmel,lcdc binding?
> 
> The current atmel hlcdc driver that is split in three is IMO an
> over-engineering, and the driver could benefit merging it all in one.
> And the binding should not prevent this.
could you please confirm if my understanding is correct: you want a 
unified display binding that encompasses the properties of the two 
subdevices (display controller and pwm), eliminating the need to 
reference them in additional bindings?
> 
>          Sam

-- 
With Best Regards,
Dharma B.

Re: [PATCH v3 3/3] dt-bindings: mfd: atmel,hlcdc: Convert to DT schema format

[Conor Dooley]

[-- Attachment #1: Type: text/plain, Size: 4333 bytes --]

On Fri, Jan 19, 2024 at 03:32:49AM +0000, Dharma.B@microchip.com wrote:
> On 18/01/24 9:10 pm, Conor Dooley wrote:
> > On Thu, Jan 18, 2024 at 02:56:12PM +0530, Dharma Balasubiramani wrote:
> >> Convert the atmel,hlcdc binding to DT schema format.
> >>
> >> Adjust the clock-names property to clarify that the LCD controller expects
> >> one of these clocks (either sys_clk or lvds_pll_clk to be present but not
> >> both) along with the slow_clk and periph_clk. This alignment with the actual
> >> hardware requirements will enable accurate device tree configuration for
> >> systems using the HLCDC IP.
> >>
> >> Signed-off-by: Dharma Balasubiramani<dharma.b@microchip.com>
> >> ---
> >> changelog
> >> v2 -> v3
> >> - Rename hlcdc-display-controller and hlcdc-pwm to generic names.
> >> - Modify the description by removing the unwanted comments and '|'.
> >> - Modify clock-names simpler.
> >> v1 -> v2
> >> - Remove the explicit copyrights.
> >> - Modify title (not include words like binding/driver).
> >> - Modify description actually describing the hardware and not the driver.
> >> - Add details of lvds_pll addition in commit message.
> >> - Ref endpoint and not endpoint-base.
> >> - Fix coding style.
> >> ...
> >>   .../devicetree/bindings/mfd/atmel,hlcdc.yaml  | 97 +++++++++++++++++++
> >>   .../devicetree/bindings/mfd/atmel-hlcdc.txt   | 56 -----------
> >>   2 files changed, 97 insertions(+), 56 deletions(-)
> >>   create mode 100644 Documentation/devicetree/bindings/mfd/atmel,hlcdc.yaml
> >>   delete mode 100644 Documentation/devicetree/bindings/mfd/atmel-hlcdc.txt
> >>
> >> diff --git a/Documentation/devicetree/bindings/mfd/atmel,hlcdc.yaml b/Documentation/devicetree/bindings/mfd/atmel,hlcdc.yaml
> >> new file mode 100644
> >> index 000000000000..eccc998ac42c
> >> --- /dev/null
> >> +++ b/Documentation/devicetree/bindings/mfd/atmel,hlcdc.yaml
> >> @@ -0,0 +1,97 @@
> >> +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
> >> +%YAML 1.2
> >> +---
> >> +$id:http://devicetree.org/schemas/mfd/atmel,hlcdc.yaml#
> >> +$schema:http://devicetree.org/meta-schemas/core.yaml#
> >> +
> >> +title: Atmel's HLCD Controller
> >> +
> >> +maintainers:
> >> +  - Nicolas Ferre<nicolas.ferre@microchip.com>
> >> +  - Alexandre Belloni<alexandre.belloni@bootlin.com>
> >> +  - Claudiu Beznea<claudiu.beznea@tuxon.dev>
> >> +
> >> +description:
> >> +  The Atmel HLCDC (HLCD Controller) IP available on Atmel SoCs exposes two
> >> +  subdevices, a PWM chip and a Display Controller.
> >> +
> >> +properties:
> >> +  compatible:
> >> +    enum:
> >> +      - atmel,at91sam9n12-hlcdc
> >> +      - atmel,at91sam9x5-hlcdc
> >> +      - atmel,sama5d2-hlcdc
> >> +      - atmel,sama5d3-hlcdc
> >> +      - atmel,sama5d4-hlcdc
> >> +      - microchip,sam9x60-hlcdc
> >> +      - microchip,sam9x75-xlcdc
> >> +
> >> +  reg:
> >> +    maxItems: 1
> >> +
> >> +  interrupts:
> >> +    maxItems: 1
> >> +
> >> +  clocks:
> >> +    maxItems: 3
> > Hmm, one thing I probably should have said on the previous version, but
> > I missed somehow: It would be good to add an items list to the clocks
> > property here to explain what the 3 clocks are/are used for - especially
> > since there is additional complexity being added here to use either the
> > sys or lvds clocks.
> May I inquire if this approach is likely to be effective?
> 
>    clocks:
>      items:
>        - description: peripheral clock
>        - description: generic clock or lvds pll clock
>            Once the LVDS PLL is enabled, the pixel clock is used as the
>            clock for LCDC, so its GCLK is no longer needed.
>        - description: slow clock
>      maxItems: 3

Hmm that sounds very suspect to me. "Once the lvdspll is enabled the
generic clock is no longer needed" sounds like both clocks can be provided
to the IP on different pins and their provision is not mutually
exclusive, just that the IP will only actually use one at a time. If
that is the case, then this patch is nott correct and the binding should
allow for 4 clocks, with both the generic clock and the lvds pll being
present in the DT at the same time.

I vaguely recall internal discussion about this problem some time back
but the details all escape me.

Thanks,
Conor.

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 228 bytes --]

Re: [PATCH v3 2/3] dt-bindings: atmel,hlcdc: convert pwm bindings to json-schema

[Rob Herring]

On Thu, Jan 18, 2024 at 02:56:11PM +0530, Dharma Balasubiramani wrote:
> Convert device tree bindings for Atmel's HLCDC PWM controller to YAML
> format.
> 
> Signed-off-by: Dharma Balasubiramani <dharma.b@microchip.com>
> Reviewed-by: Conor Dooley <conor.dooley@microchip.com>
> ---
> changelog
> v2 -> v3
> - Remove '|' in description, as there is no formatting to preserve.
> - Delete the description for pwm-cells.
> - Drop the label for pwm node as it not used.
> v1 -> v2
> - Remove the explicit copyrights.
> - Modify title (not include words like binding/driver).
> - Modify description actually describing the hardware and not the driver.
> - Remove pinctrl properties which aren't required.
> - Drop parent node and it's other sub-device node which are not related here.
> ---
>  .../bindings/pwm/atmel,hlcdc-pwm.yaml         | 44 +++++++++++++++++++
>  .../bindings/pwm/atmel-hlcdc-pwm.txt          | 29 ------------
>  2 files changed, 44 insertions(+), 29 deletions(-)
>  create mode 100644 Documentation/devicetree/bindings/pwm/atmel,hlcdc-pwm.yaml
>  delete mode 100644 Documentation/devicetree/bindings/pwm/atmel-hlcdc-pwm.txt
> 
> diff --git a/Documentation/devicetree/bindings/pwm/atmel,hlcdc-pwm.yaml b/Documentation/devicetree/bindings/pwm/atmel,hlcdc-pwm.yaml
> new file mode 100644
> index 000000000000..4f4cc21fe4f7
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/pwm/atmel,hlcdc-pwm.yaml
> @@ -0,0 +1,44 @@
> +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
> +%YAML 1.2
> +---
> +$id: http://devicetree.org/schemas/pwm/atmel,hlcdc-pwm.yaml#
> +$schema: http://devicetree.org/meta-schemas/core.yaml#
> +
> +title: Atmel's HLCDC's PWM controller
> +
> +maintainers:
> +  - Nicolas Ferre <nicolas.ferre@microchip.com>
> +  - Alexandre Belloni <alexandre.belloni@bootlin.com>
> +  - Claudiu Beznea <claudiu.beznea@tuxon.dev>
> +
> +description:
> +  The LCDC integrates a Pulse Width Modulation (PWM) Controller. This block
> +  generates the LCD contrast control signal (LCD_PWM) that controls the
> +  display's contrast by software. LCDC_PWM is an 8-bit PWM signal that can be
> +  converted to an analog voltage with a simple passive filter. LCD display
> +  panels have different backlight specifications in terms of minimum/maximum
> +  values for PWM frequency. If the LCDC PWM frequency range does not match the
> +  LCD display panel, it is possible to use the standalone PWM Controller to
> +  drive the backlight.
> +
> +properties:
> +  compatible:
> +    const: atmel,hlcdc-pwm
> +
> +  "#pwm-cells":
> +    const: 3
> +
> +required:
> +  - compatible
> +  - "#pwm-cells"
> +
> +additionalProperties: false
> +
> +examples:
> +  - |
> +    pwm {
> +      compatible = "atmel,hlcdc-pwm";
> +      pinctrl-names = "default";
> +      pinctrl-0 = <&pinctrl_lcd_pwm>;
> +      #pwm-cells = <3>;
> +    };

Move the example to the MFD schema. Or just drop if already there.

Rob

Re: [PATCH v3 0/3] Convert Microchip's HLCDC Text based DT bindings to JSON schema

[Rob Herring]

On Thu, Jan 18, 2024 at 08:30:40PM +0100, Sam Ravnborg wrote:
> Hi Dharma et al.
> 
> On Thu, Jan 18, 2024 at 02:56:09PM +0530, Dharma Balasubiramani wrote:
> > Converted the text bindings to YAML and validated them individually using following commands
> > 
> > $ make dt_binding_check DT_SCHEMA_FILES=Documentation/devicetree/bindings/
> > $ make dtbs_check DT_SCHEMA_FILES=Documentation/devicetree/bindings/
> > 
> > changelogs are available in respective patches.
> > 
> > Dharma Balasubiramani (3):
> >   dt-bindings: display: convert Atmel's HLCDC to DT schema
> >   dt-bindings: atmel,hlcdc: convert pwm bindings to json-schema
> >   dt-bindings: mfd: atmel,hlcdc: Convert to DT schema format
> 
> I know this is a bit late to ask - sorry in advance.
> 
> The binding describes the single IP block as a multi functional device,
> but it is a single IP block that includes the display controller and a
> simple pwm that can be used for contrast or backlight.
> 
> If we ignore the fact that the current drivers for hlcdc uses an mfd
> abstraction, is this then the optimal way to describe the HW?
> 
> 
> In one of my stale git tree I converted atmel lcdc to DT, and here
> I used:
> 
> +  "#pwm-cells":
> +    description:
> +      This PWM chip use the default 3 cells bindings
> +      defined in ../../pwm/pwm.yaml.
> +    const: 3
> +
> +  clocks:
> +    maxItems: 2
> +
> +  clock-names:
> +    maxItems: 2
> +    items:
> +      - const: lcdc_clk
> +      - const: hclk
> 
> This proved to be a simple way to describe the HW.
> 
> To make the DT binding backward compatible you likely need to add a few
> compatible that otherwise would have been left out - but that should do
> the trick.
> 
> The current atmel hlcdc driver that is split in three is IMO an
> over-engineering, and the driver could benefit merging it all in one.
> And the binding should not prevent this.

I agree on all this, but a conversion is not really the time to redesign 
things. Trust me, I've wanted to on lots of conversions. It should be 
possible to simplify the driver side while keeping the DT as-is. Just 
make the display driver bind to the MFD node instead. After that, then 
one could look at flattening everything to 1 node.

Rob

Re: [PATCH v3 0/3] Convert Microchip's HLCDC Text based DT bindings to JSON schema

[Sam Ravnborg]

Hi Dharma,

On Fri, Jan 19, 2024 at 08:41:04AM +0000, Dharma.B@microchip.com wrote:
> Hi Sam,
> On 19/01/24 1:00 am, Sam Ravnborg wrote:
> > [You don't often get email from sam@ravnborg.org. Learn why this is important at https://aka.ms/LearnAboutSenderIdentification ]
> > 
> > EXTERNAL EMAIL: Do not click links or open attachments unless you know the content is safe
> > 
> > Hi Dharma et al.
> > 
> > On Thu, Jan 18, 2024 at 02:56:09PM +0530, Dharma Balasubiramani wrote:
> >> Converted the text bindings to YAML and validated them individually using following commands
> >>
> >> $ make dt_binding_check DT_SCHEMA_FILES=Documentation/devicetree/bindings/
> >> $ make dtbs_check DT_SCHEMA_FILES=Documentation/devicetree/bindings/
> >>
> >> changelogs are available in respective patches.
> >>
> >> Dharma Balasubiramani (3):
> >>    dt-bindings: display: convert Atmel's HLCDC to DT schema
> >>    dt-bindings: atmel,hlcdc: convert pwm bindings to json-schema
> >>    dt-bindings: mfd: atmel,hlcdc: Convert to DT schema format
> > 
> > I know this is a bit late to ask - sorry in advance.
> > 
> > The binding describes the single IP block as a multi functional device,
> > but it is a single IP block that includes the display controller and a
> > simple pwm that can be used for contrast or backlight.
> yes.
> > 
> > If we ignore the fact that the current drivers for hlcdc uses an mfd
> > abstraction, is this then the optimal way to describe the HW?
> > 
> > 
> > In one of my stale git tree I converted atmel lcdc to DT, and here
> Are you referring the "bindings/display/atmel,lcdc.txt"?
Correct.

> > I used:
> > 
> > +  "#pwm-cells":
> > +    description:
> > +      This PWM chip use the default 3 cells bindings
> > +      defined in ../../pwm/pwm.yaml.
> > +    const: 3
> > +
> > +  clocks:
> > +    maxItems: 2
> > +
> > +  clock-names:
> > +    maxItems: 2
> > +    items:
> > +      - const: lcdc_clk
> > +      - const: hclk
> > 
> > This proved to be a simple way to describe the HW.
> > 
> > To make the DT binding backward compatible you likely need to add a few
> > compatible that otherwise would have been left out - but that should do
> > the trick.
> again you mean the compatibles from atmel,lcdc binding?

If the new binding describes the full IP, as I suggest, then I assume
you need to add the compatible "atmel,hlcdc-pwm" to be backward
compatible. Otherwise users assuming the old binding will fail to find
the pwm info. I am not sure how important this is - but at least then
the device trees can be updated out of sync with the current users.

I hope this explains what I tried to say, otherwise do not hesitate to
get back to me.

	Sam

Re: [PATCH v3 2/3] dt-bindings: atmel,hlcdc: convert pwm bindings to json-schema

[Uwe Kleine-König]

[-- Attachment #1: Type: text/plain, Size: 881 bytes --]

Hello,

On Thu, Jan 18, 2024 at 11:16:49AM +0100, Uwe Kleine-König wrote:
> On Thu, Jan 18, 2024 at 02:56:11PM +0530, Dharma Balasubiramani wrote:
> > Convert device tree bindings for Atmel's HLCDC PWM controller to YAML
> > format.
> > 
> > Signed-off-by: Dharma Balasubiramani <dharma.b@microchip.com>
> > Reviewed-by: Conor Dooley <conor.dooley@microchip.com>
> 
> Reviewed-by: Uwe Kleine-König <u.kleine-koenig@pengutronix.de>
> 
> I will update the short log to
> 
> 	dt-bindings: pwm: atmel,hlcdc: Convert bindings to json-schema
> 
> to match my preferences (unless you object) and apply for next after the
> merge window.

Dropped from my todo-list after Rob's feedback.

Best regards
Uwe


-- 
Pengutronix e.K.                           | Uwe Kleine-König            |
Industrial Linux Solutions                 | https://www.pengutronix.de/ |

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 488 bytes --]

Re: [PATCH v3 0/3] Convert Microchip's HLCDC Text based DT bindings to JSON schema

[Sam Ravnborg]

Hi Dharma & Rob.

> > To make the DT binding backward compatible you likely need to add a few
> > compatible that otherwise would have been left out - but that should do
> > the trick.
> > 
> > The current atmel hlcdc driver that is split in three is IMO an
> > over-engineering, and the driver could benefit merging it all in one.
> > And the binding should not prevent this.
> 
> I agree on all this, but a conversion is not really the time to redesign 
> things. Trust me, I've wanted to on lots of conversions. It should be 
> possible to simplify the driver side while keeping the DT as-is. Just 
> make the display driver bind to the MFD node instead. After that, then 
> one could look at flattening everything to 1 node.

Understood and thinking a bit about it fully agreed as well.
Dharma - please see my comments only as ideas for the future, and
ignore them in this fine rewrite you do.

	Sam

Re: [PATCH v3 3/3] dt-bindings: mfd: atmel,hlcdc: Convert to DT schema format

[Dharma.B]

Hi Conor,
On 19/01/24 5:33 pm, Conor Dooley - M52691 wrote:
> On Fri, Jan 19, 2024 at 03:32:49AM +0000, Dharma.B@microchip.com wrote:
>> On 18/01/24 9:10 pm, Conor Dooley wrote:
>>> On Thu, Jan 18, 2024 at 02:56:12PM +0530, Dharma Balasubiramani wrote:
>>>> Convert the atmel,hlcdc binding to DT schema format.
>>>>
>>>> Adjust the clock-names property to clarify that the LCD controller expects
>>>> one of these clocks (either sys_clk or lvds_pll_clk to be present but not
>>>> both) along with the slow_clk and periph_clk. This alignment with the actual
>>>> hardware requirements will enable accurate device tree configuration for
>>>> systems using the HLCDC IP.
>>>>
>>>> Signed-off-by: Dharma Balasubiramani<dharma.b@microchip.com>
>>>> ---
>>>> changelog
>>>> v2 -> v3
>>>> - Rename hlcdc-display-controller and hlcdc-pwm to generic names.
>>>> - Modify the description by removing the unwanted comments and '|'.
>>>> - Modify clock-names simpler.
>>>> v1 -> v2
>>>> - Remove the explicit copyrights.
>>>> - Modify title (not include words like binding/driver).
>>>> - Modify description actually describing the hardware and not the driver.
>>>> - Add details of lvds_pll addition in commit message.
>>>> - Ref endpoint and not endpoint-base.
>>>> - Fix coding style.
>>>> ...
>>>>    .../devicetree/bindings/mfd/atmel,hlcdc.yaml  | 97 +++++++++++++++++++
>>>>    .../devicetree/bindings/mfd/atmel-hlcdc.txt   | 56 -----------
>>>>    2 files changed, 97 insertions(+), 56 deletions(-)
>>>>    create mode 100644 Documentation/devicetree/bindings/mfd/atmel,hlcdc.yaml
>>>>    delete mode 100644 Documentation/devicetree/bindings/mfd/atmel-hlcdc.txt
>>>>
>>>> diff --git a/Documentation/devicetree/bindings/mfd/atmel,hlcdc.yaml b/Documentation/devicetree/bindings/mfd/atmel,hlcdc.yaml
>>>> new file mode 100644
>>>> index 000000000000..eccc998ac42c
>>>> --- /dev/null
>>>> +++ b/Documentation/devicetree/bindings/mfd/atmel,hlcdc.yaml
>>>> @@ -0,0 +1,97 @@
>>>> +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
>>>> +%YAML 1.2
>>>> +---
>>>> +$id:http://devicetree.org/schemas/mfd/atmel,hlcdc.yaml#
>>>> +$schema:http://devicetree.org/meta-schemas/core.yaml#
>>>> +
>>>> +title: Atmel's HLCD Controller
>>>> +
>>>> +maintainers:
>>>> +  - Nicolas Ferre<nicolas.ferre@microchip.com>
>>>> +  - Alexandre Belloni<alexandre.belloni@bootlin.com>
>>>> +  - Claudiu Beznea<claudiu.beznea@tuxon.dev>
>>>> +
>>>> +description:
>>>> +  The Atmel HLCDC (HLCD Controller) IP available on Atmel SoCs exposes two
>>>> +  subdevices, a PWM chip and a Display Controller.
>>>> +
>>>> +properties:
>>>> +  compatible:
>>>> +    enum:
>>>> +      - atmel,at91sam9n12-hlcdc
>>>> +      - atmel,at91sam9x5-hlcdc
>>>> +      - atmel,sama5d2-hlcdc
>>>> +      - atmel,sama5d3-hlcdc
>>>> +      - atmel,sama5d4-hlcdc
>>>> +      - microchip,sam9x60-hlcdc
>>>> +      - microchip,sam9x75-xlcdc
>>>> +
>>>> +  reg:
>>>> +    maxItems: 1
>>>> +
>>>> +  interrupts:
>>>> +    maxItems: 1
>>>> +
>>>> +  clocks:
>>>> +    maxItems: 3
>>> Hmm, one thing I probably should have said on the previous version, but
>>> I missed somehow: It would be good to add an items list to the clocks
>>> property here to explain what the 3 clocks are/are used for - especially
>>> since there is additional complexity being added here to use either the
>>> sys or lvds clocks.
>> May I inquire if this approach is likely to be effective?
>>
>>     clocks:
>>       items:
>>         - description: peripheral clock
>>         - description: generic clock or lvds pll clock
>>             Once the LVDS PLL is enabled, the pixel clock is used as the
>>             clock for LCDC, so its GCLK is no longer needed.
>>         - description: slow clock
>>       maxItems: 3
> 
> Hmm that sounds very suspect to me. "Once the lvdspll is enabled the
> generic clock is no longer needed" sounds like both clocks can be provided
> to the IP on different pins and their provision is not mutually
> exclusive, just that the IP will only actually use one at a time. If
> that is the case, then this patch is nott correct and the binding should
> allow for 4 clocks, with both the generic clock and the lvds pll being
> present in the DT at the same time.
> 
> I vaguely recall internal discussion about this problem some time back
> but the details all escape me.

Let's delve deeper into the clock configuration for LCDC_PCK.

Considering the flexibility of the design, it appears that both clocks, 
sys_clk (generic clock) and lvds_pll_clk, can indeed be provided to the 
IP simultaneously. The crucial aspect, however, is that the IP will 
utilize only one of these clocks at any given time. This aligns with the 
specific requirements of the application, where the choice of clock 
depends on whether the LVDS interface or MIPI/DSI is in use.

To ensure proper configuration of the pixel clock period, we need to 
distinctly identify which clocks are being utilized. For instance, in 
the LVDS interface scenario, the lvds_pll_clk is essential, resulting in 
LCDC_PCK being set to the source clock. Conversely, in the MIPI/DSI 
case, the LCDC GCLK is required, leading to LCDC_PCK being defined as 
source clock/CLKDIV+2.

Considering the potential coexistence of sys_clk and lvds_pll_clk in the 
Device Tree (DT), we may need to introduce an additional flag in the DT. 
This flag could serve as a clear indicator of whether the LVDS interface 
or MIPI/DSI is being employed. As we discussed to drop this flag and 
just have any one of the clocks I believe that this approach provides a 
sensible and scalable solution, allowing for a comprehensive 
representation of the clocking configuration.
> 
> Thanks,
> Conor.

-- 
With Best Regards,
Dharma B.

Re: [PATCH v3 0/3] Convert Microchip's HLCDC Text based DT bindings to JSON schema

[Dharma.B]

On 20/01/24 6:53 pm, Sam Ravnborg wrote:
> [You don't often get email from sam@ravnborg.org. Learn why this is important at https://aka.ms/LearnAboutSenderIdentification ]
> 
> EXTERNAL EMAIL: Do not click links or open attachments unless you know the content is safe
> Hi Sam & Rob,
> Hi Dharma & Rob.
> 
>>> To make the DT binding backward compatible you likely need to add a few
>>> compatible that otherwise would have been left out - but that should do
>>> the trick.
>>>
>>> The current atmel hlcdc driver that is split in three is IMO an
>>> over-engineering, and the driver could benefit merging it all in one.
>>> And the binding should not prevent this.
>>
>> I agree on all this, but a conversion is not really the time to redesign
>> things. Trust me, I've wanted to on lots of conversions. It should be
>> possible to simplify the driver side while keeping the DT as-is. Just
>> make the display driver bind to the MFD node instead. After that, then
>> one could look at flattening everything to 1 node.
> 
> Understood and thinking a bit about it fully agreed as well.
> Dharma - please see my comments only as ideas for the future, and
> ignore them in this fine rewrite you do.
> 
>          Sam
Based on your insights, I'm contemplating the decision to merge Patch 2 
[PWM binding] with Patch 3[MFD binding]. It seems redundant given that 
we already have a PWM node example in the MFD binding.

Instead of introducing a new PWM binding,
   pwm:
     $ref: /schemas/pwm/atmel,hlcdc-pwm.yaml

I will update the existing MFD binding as follows:

properties:
   compatible:
     const: atmel,hlcdc-pwm

   "#pwm-cells":
     const: 3

required:
   - compatible
   - "#pwm-cells"

-- 
With Best Regards,
Dharma B.

Re: [PATCH v3 3/3] dt-bindings: mfd: atmel,hlcdc: Convert to DT schema format

[Conor Dooley]

[-- Attachment #1: Type: text/plain, Size: 6649 bytes --]

On Mon, Jan 22, 2024 at 03:38:41AM +0000, Dharma.B@microchip.com wrote:
> Hi Conor,
> On 19/01/24 5:33 pm, Conor Dooley - M52691 wrote:
> > On Fri, Jan 19, 2024 at 03:32:49AM +0000, Dharma.B@microchip.com wrote:
> >> On 18/01/24 9:10 pm, Conor Dooley wrote:
> >>> On Thu, Jan 18, 2024 at 02:56:12PM +0530, Dharma Balasubiramani wrote:
> >>>> Convert the atmel,hlcdc binding to DT schema format.
> >>>>
> >>>> Adjust the clock-names property to clarify that the LCD controller expects
> >>>> one of these clocks (either sys_clk or lvds_pll_clk to be present but not
> >>>> both) along with the slow_clk and periph_clk. This alignment with the actual
> >>>> hardware requirements will enable accurate device tree configuration for
> >>>> systems using the HLCDC IP.
> >>>>
> >>>> Signed-off-by: Dharma Balasubiramani<dharma.b@microchip.com>
> >>>> ---
> >>>> changelog
> >>>> v2 -> v3
> >>>> - Rename hlcdc-display-controller and hlcdc-pwm to generic names.
> >>>> - Modify the description by removing the unwanted comments and '|'.
> >>>> - Modify clock-names simpler.
> >>>> v1 -> v2
> >>>> - Remove the explicit copyrights.
> >>>> - Modify title (not include words like binding/driver).
> >>>> - Modify description actually describing the hardware and not the driver.
> >>>> - Add details of lvds_pll addition in commit message.
> >>>> - Ref endpoint and not endpoint-base.
> >>>> - Fix coding style.
> >>>> ...
> >>>>    .../devicetree/bindings/mfd/atmel,hlcdc.yaml  | 97 +++++++++++++++++++
> >>>>    .../devicetree/bindings/mfd/atmel-hlcdc.txt   | 56 -----------
> >>>>    2 files changed, 97 insertions(+), 56 deletions(-)
> >>>>    create mode 100644 Documentation/devicetree/bindings/mfd/atmel,hlcdc.yaml
> >>>>    delete mode 100644 Documentation/devicetree/bindings/mfd/atmel-hlcdc.txt
> >>>>
> >>>> diff --git a/Documentation/devicetree/bindings/mfd/atmel,hlcdc.yaml b/Documentation/devicetree/bindings/mfd/atmel,hlcdc.yaml
> >>>> new file mode 100644
> >>>> index 000000000000..eccc998ac42c
> >>>> --- /dev/null
> >>>> +++ b/Documentation/devicetree/bindings/mfd/atmel,hlcdc.yaml
> >>>> @@ -0,0 +1,97 @@
> >>>> +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
> >>>> +%YAML 1.2
> >>>> +---
> >>>> +$id:http://devicetree.org/schemas/mfd/atmel,hlcdc.yaml#
> >>>> +$schema:http://devicetree.org/meta-schemas/core.yaml#
> >>>> +
> >>>> +title: Atmel's HLCD Controller
> >>>> +
> >>>> +maintainers:
> >>>> +  - Nicolas Ferre<nicolas.ferre@microchip.com>
> >>>> +  - Alexandre Belloni<alexandre.belloni@bootlin.com>
> >>>> +  - Claudiu Beznea<claudiu.beznea@tuxon.dev>
> >>>> +
> >>>> +description:
> >>>> +  The Atmel HLCDC (HLCD Controller) IP available on Atmel SoCs exposes two
> >>>> +  subdevices, a PWM chip and a Display Controller.
> >>>> +
> >>>> +properties:
> >>>> +  compatible:
> >>>> +    enum:
> >>>> +      - atmel,at91sam9n12-hlcdc
> >>>> +      - atmel,at91sam9x5-hlcdc
> >>>> +      - atmel,sama5d2-hlcdc
> >>>> +      - atmel,sama5d3-hlcdc
> >>>> +      - atmel,sama5d4-hlcdc
> >>>> +      - microchip,sam9x60-hlcdc
> >>>> +      - microchip,sam9x75-xlcdc
> >>>> +
> >>>> +  reg:
> >>>> +    maxItems: 1
> >>>> +
> >>>> +  interrupts:
> >>>> +    maxItems: 1
> >>>> +
> >>>> +  clocks:
> >>>> +    maxItems: 3
> >>> Hmm, one thing I probably should have said on the previous version, but
> >>> I missed somehow: It would be good to add an items list to the clocks
> >>> property here to explain what the 3 clocks are/are used for - especially
> >>> since there is additional complexity being added here to use either the
> >>> sys or lvds clocks.
> >> May I inquire if this approach is likely to be effective?
> >>
> >>     clocks:
> >>       items:
> >>         - description: peripheral clock
> >>         - description: generic clock or lvds pll clock
> >>             Once the LVDS PLL is enabled, the pixel clock is used as the
> >>             clock for LCDC, so its GCLK is no longer needed.
> >>         - description: slow clock
> >>       maxItems: 3
> > 
> > Hmm that sounds very suspect to me. "Once the lvdspll is enabled the
> > generic clock is no longer needed" sounds like both clocks can be provided
> > to the IP on different pins and their provision is not mutually
> > exclusive, just that the IP will only actually use one at a time. If
> > that is the case, then this patch is nott correct and the binding should
> > allow for 4 clocks, with both the generic clock and the lvds pll being
> > present in the DT at the same time.
> > 
> > I vaguely recall internal discussion about this problem some time back
> > but the details all escape me.
> 
> Let's delve deeper into the clock configuration for LCDC_PCK.
> 
> Considering the flexibility of the design, it appears that both clocks, 
> sys_clk (generic clock) and lvds_pll_clk, can indeed be provided to the 
> IP simultaneously. The crucial aspect, however, is that the IP will 
> utilize only one of these clocks at any given time. This aligns with the 
> specific requirements of the application, where the choice of clock 
> depends on whether the LVDS interface or MIPI/DSI is in use.

If both clocks can physically be provided to the IP then both of them
should be in the dt. The hcldc appears to me to be a part of the SoC and
the clock routing to the IP is likely fixed.

> To ensure proper configuration of the pixel clock period, we need to 
> distinctly identify which clocks are being utilized. For instance, in 
> the LVDS interface scenario, the lvds_pll_clk is essential, resulting in 
> LCDC_PCK being set to the source clock. Conversely, in the MIPI/DSI 
> case, the LCDC GCLK is required, leading to LCDC_PCK being defined as 
> source clock/CLKDIV+2.
> 
> Considering the potential coexistence of sys_clk and lvds_pll_clk in the 
> Device Tree (DT), we may need to introduce an additional flag in the DT. 
> This flag could serve as a clear indicator of whether the LVDS interface 
> or MIPI/DSI is being employed. As we discussed to drop this flag and 
> just have any one of the clocks I believe that this approach provides a 
> sensible and scalable solution, allowing for a comprehensive 
> representation of the clocking configuration.

This is probably a question for the folks on the DRM or media side of
things, but is it not possible to determine based on the endpoint what
protocol is required?
I know that on the media side of things there's an endpoint property
that can be used to specific the bus-type - is there an equivalent
property for DRM stuff?

Cheers,
Conor.

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 228 bytes --]

Re: [PATCH v3 0/3] Convert Microchip's HLCDC Text based DT bindings to JSON schema

[Sam Ravnborg]

Hi Dharma
On Mon, Jan 22, 2024 at 03:52:17AM +0000, Dharma.B@microchip.com wrote:
> On 20/01/24 6:53 pm, Sam Ravnborg wrote:
> > [You don't often get email from sam@ravnborg.org. Learn why this is important at https://aka.ms/LearnAboutSenderIdentification ]
> > 
> > EXTERNAL EMAIL: Do not click links or open attachments unless you know the content is safe
> > Hi Sam & Rob,
> > Hi Dharma & Rob.
> > 
> >>> To make the DT binding backward compatible you likely need to add a few
> >>> compatible that otherwise would have been left out - but that should do
> >>> the trick.
> >>>
> >>> The current atmel hlcdc driver that is split in three is IMO an
> >>> over-engineering, and the driver could benefit merging it all in one.
> >>> And the binding should not prevent this.
> >>
> >> I agree on all this, but a conversion is not really the time to redesign
> >> things. Trust me, I've wanted to on lots of conversions. It should be
> >> possible to simplify the driver side while keeping the DT as-is. Just
> >> make the display driver bind to the MFD node instead. After that, then
> >> one could look at flattening everything to 1 node.
> > 
> > Understood and thinking a bit about it fully agreed as well.
> > Dharma - please see my comments only as ideas for the future, and
> > ignore them in this fine rewrite you do.
> > 
> >          Sam
> Based on your insights, I'm contemplating the decision to merge Patch 2 
> [PWM binding] with Patch 3[MFD binding]. It seems redundant given that 
> we already have a PWM node example in the MFD binding.
> 
> Instead of introducing a new PWM binding,
>    pwm:
>      $ref: /schemas/pwm/atmel,hlcdc-pwm.yaml
> 
> I will update the existing MFD binding as follows:
> 
> properties:
>    compatible:
>      const: atmel,hlcdc-pwm
> 
>    "#pwm-cells":
>      const: 3
> 
> required:
>    - compatible
>    - "#pwm-cells"
> 
Good idea, this looks like a nice simplification.

	Sam

Re: [PATCH v3 0/3] Convert Microchip's HLCDC Text based DT bindings to JSON schema

[Sam Ravnborg]

Hi Dharma,
On Mon, Jan 22, 2024 at 03:52:17AM +0000, Dharma.B@microchip.com wrote:
> On 20/01/24 6:53 pm, Sam Ravnborg wrote:
> > [You don't often get email from sam@ravnborg.org. Learn why this is important at https://aka.ms/LearnAboutSenderIdentification ]
> > 
> > EXTERNAL EMAIL: Do not click links or open attachments unless you know the content is safe
> > Hi Sam & Rob,
> > Hi Dharma & Rob.
> > 
> >>> To make the DT binding backward compatible you likely need to add a few
> >>> compatible that otherwise would have been left out - but that should do
> >>> the trick.
> >>>
> >>> The current atmel hlcdc driver that is split in three is IMO an
> >>> over-engineering, and the driver could benefit merging it all in one.
> >>> And the binding should not prevent this.
> >>
> >> I agree on all this, but a conversion is not really the time to redesign
> >> things. Trust me, I've wanted to on lots of conversions. It should be
> >> possible to simplify the driver side while keeping the DT as-is. Just
> >> make the display driver bind to the MFD node instead. After that, then
> >> one could look at flattening everything to 1 node.
> > 
> > Understood and thinking a bit about it fully agreed as well.
> > Dharma - please see my comments only as ideas for the future, and
> > ignore them in this fine rewrite you do.
> > 
> >          Sam
> Based on your insights, I'm contemplating the decision to merge Patch 2 
> [PWM binding] with Patch 3[MFD binding]. It seems redundant given that 
> we already have a PWM node example in the MFD binding.
> 
> Instead of introducing a new PWM binding,
>    pwm:
>      $ref: /schemas/pwm/atmel,hlcdc-pwm.yaml
> 
> I will update the existing MFD binding as follows:
> 
> properties:
>    compatible:
>      const: atmel,hlcdc-pwm
> 
>    "#pwm-cells":
>      const: 3
> 
> required:
>    - compatible
>    - "#pwm-cells"
> 
As already commented, this looks nice.
But as Rob said, this should be a 1:1 conversion from text to yaml,
and then clean-up can come in the second step.

	Sam

Re: [PATCH v3 3/3] dt-bindings: mfd: atmel,hlcdc: Convert to DT schema format

[Dharma.B]

Hi Conor & All,

On 22/01/24 2:46 pm, Conor Dooley wrote:
> On Mon, Jan 22, 2024 at 03:38:41AM +0000,Dharma.B@microchip.com  wrote:
>> Hi Conor,
>> On 19/01/24 5:33 pm, Conor Dooley - M52691 wrote:
>>> On Fri, Jan 19, 2024 at 03:32:49AM +0000,Dharma.B@microchip.com  wrote:
>>>> On 18/01/24 9:10 pm, Conor Dooley wrote:
>>>>> On Thu, Jan 18, 2024 at 02:56:12PM +0530, Dharma Balasubiramani wrote:
>>>>>> Convert the atmel,hlcdc binding to DT schema format.
>>>>>>
>>>>>> Adjust the clock-names property to clarify that the LCD controller expects
>>>>>> one of these clocks (either sys_clk or lvds_pll_clk to be present but not
>>>>>> both) along with the slow_clk and periph_clk. This alignment with the actual
>>>>>> hardware requirements will enable accurate device tree configuration for
>>>>>> systems using the HLCDC IP.
>>>>>>
>>>>>> Signed-off-by: Dharma Balasubiramani<dharma.b@microchip.com>
>>>>>> ---
>>>>>> changelog
>>>>>> v2 -> v3
>>>>>> - Rename hlcdc-display-controller and hlcdc-pwm to generic names.
>>>>>> - Modify the description by removing the unwanted comments and '|'.
>>>>>> - Modify clock-names simpler.
>>>>>> v1 -> v2
>>>>>> - Remove the explicit copyrights.
>>>>>> - Modify title (not include words like binding/driver).
>>>>>> - Modify description actually describing the hardware and not the driver.
>>>>>> - Add details of lvds_pll addition in commit message.
>>>>>> - Ref endpoint and not endpoint-base.
>>>>>> - Fix coding style.
>>>>>> ...
>>>>>>     .../devicetree/bindings/mfd/atmel,hlcdc.yaml  | 97 +++++++++++++++++++
>>>>>>     .../devicetree/bindings/mfd/atmel-hlcdc.txt   | 56 -----------
>>>>>>     2 files changed, 97 insertions(+), 56 deletions(-)
>>>>>>     create mode 100644 Documentation/devicetree/bindings/mfd/atmel,hlcdc.yaml
>>>>>>     delete mode 100644 Documentation/devicetree/bindings/mfd/atmel-hlcdc.txt
>>>>>>
>>>>>> diff --git a/Documentation/devicetree/bindings/mfd/atmel,hlcdc.yaml b/Documentation/devicetree/bindings/mfd/atmel,hlcdc.yaml
>>>>>> new file mode 100644
>>>>>> index 000000000000..eccc998ac42c
>>>>>> --- /dev/null
>>>>>> +++ b/Documentation/devicetree/bindings/mfd/atmel,hlcdc.yaml
>>>>>> @@ -0,0 +1,97 @@
>>>>>> +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
>>>>>> +%YAML 1.2
>>>>>> +---
>>>>>> +$id:http://devicetree.org/schemas/mfd/atmel,hlcdc.yaml#
>>>>>> +$schema:http://devicetree.org/meta-schemas/core.yaml#
>>>>>> +
>>>>>> +title: Atmel's HLCD Controller
>>>>>> +
>>>>>> +maintainers:
>>>>>> +  - Nicolas Ferre<nicolas.ferre@microchip.com>
>>>>>> +  - Alexandre Belloni<alexandre.belloni@bootlin.com>
>>>>>> +  - Claudiu Beznea<claudiu.beznea@tuxon.dev>
>>>>>> +
>>>>>> +description:
>>>>>> +  The Atmel HLCDC (HLCD Controller) IP available on Atmel SoCs exposes two
>>>>>> +  subdevices, a PWM chip and a Display Controller.
>>>>>> +
>>>>>> +properties:
>>>>>> +  compatible:
>>>>>> +    enum:
>>>>>> +      - atmel,at91sam9n12-hlcdc
>>>>>> +      - atmel,at91sam9x5-hlcdc
>>>>>> +      - atmel,sama5d2-hlcdc
>>>>>> +      - atmel,sama5d3-hlcdc
>>>>>> +      - atmel,sama5d4-hlcdc
>>>>>> +      - microchip,sam9x60-hlcdc
>>>>>> +      - microchip,sam9x75-xlcdc
>>>>>> +
>>>>>> +  reg:
>>>>>> +    maxItems: 1
>>>>>> +
>>>>>> +  interrupts:
>>>>>> +    maxItems: 1
>>>>>> +
>>>>>> +  clocks:
>>>>>> +    maxItems: 3
>>>>> Hmm, one thing I probably should have said on the previous version, but
>>>>> I missed somehow: It would be good to add an items list to the clocks
>>>>> property here to explain what the 3 clocks are/are used for - especially
>>>>> since there is additional complexity being added here to use either the
>>>>> sys or lvds clocks.
>>>> May I inquire if this approach is likely to be effective?
>>>>
>>>>      clocks:
>>>>        items:
>>>>          - description: peripheral clock
>>>>          - description: generic clock or lvds pll clock
>>>>              Once the LVDS PLL is enabled, the pixel clock is used as the
>>>>              clock for LCDC, so its GCLK is no longer needed.
>>>>          - description: slow clock
>>>>        maxItems: 3
>>> Hmm that sounds very suspect to me. "Once the lvdspll is enabled the
>>> generic clock is no longer needed" sounds like both clocks can be provided
>>> to the IP on different pins and their provision is not mutually
>>> exclusive, just that the IP will only actually use one at a time. If
>>> that is the case, then this patch is nott correct and the binding should
>>> allow for 4 clocks, with both the generic clock and the lvds pll being
>>> present in the DT at the same time.
>>>
>>> I vaguely recall internal discussion about this problem some time back
>>> but the details all escape me.
>> Let's delve deeper into the clock configuration for LCDC_PCK.
>>
>> Considering the flexibility of the design, it appears that both clocks,
>> sys_clk (generic clock) and lvds_pll_clk, can indeed be provided to the
>> IP simultaneously. The crucial aspect, however, is that the IP will
>> utilize only one of these clocks at any given time. This aligns with the
>> specific requirements of the application, where the choice of clock
>> depends on whether the LVDS interface or MIPI/DSI is in use.
> If both clocks can physically be provided to the IP then both of them
> should be in the dt. The hcldc appears to me to be a part of the SoC and
> the clock routing to the IP is likely fixed.
> 
>> To ensure proper configuration of the pixel clock period, we need to
>> distinctly identify which clocks are being utilized. For instance, in
>> the LVDS interface scenario, the lvds_pll_clk is essential, resulting in
>> LCDC_PCK being set to the source clock. Conversely, in the MIPI/DSI
>> case, the LCDC GCLK is required, leading to LCDC_PCK being defined as
>> source clock/CLKDIV+2.
>>
>> Considering the potential coexistence of sys_clk and lvds_pll_clk in the
>> Device Tree (DT), we may need to introduce an additional flag in the DT.
>> This flag could serve as a clear indicator of whether the LVDS interface
>> or MIPI/DSI is being employed. As we discussed to drop this flag and
>> just have any one of the clocks I believe that this approach provides a
>> sensible and scalable solution, allowing for a comprehensive
>> representation of the clocking configuration.
> This is probably a question for the folks on the DRM or media side of
> things, but is it not possible to determine based on the endpoint what
> protocol is required?
> I know that on the media side of things there's an endpoint property
> that can be used to specific the bus-type - is there an equivalent
> property for DRM stuff?

Yes, it can be done.
I will have the lvds pll in the lvds DT node.
I will just convert the existing text binding to yaml without this 
additonal lvds pll clock.

-- 
Thanks,
Dharma B.
> 
> Cheers,
> Conor.

Re: [PATCH v3 0/3] Convert Microchip's HLCDC Text based DT bindings to JSON schema

[Dharma.B]

On 22/01/24 9:34 pm, Sam Ravnborg wrote:
> [You don't often get email from sam@ravnborg.org. Learn why this is important at https://aka.ms/LearnAboutSenderIdentification ]
> 
> EXTERNAL EMAIL: Do not click links or open attachments unless you know the content is safe
> 
> Hi Dharma,
> On Mon, Jan 22, 2024 at 03:52:17AM +0000, Dharma.B@microchip.com wrote:
>> On 20/01/24 6:53 pm, Sam Ravnborg wrote:
>>> [You don't often get email from sam@ravnborg.org. Learn why this is important at https://aka.ms/LearnAboutSenderIdentification ]
>>>
>>> EXTERNAL EMAIL: Do not click links or open attachments unless you know the content is safe
>>> Hi Sam & Rob,
>>> Hi Dharma & Rob.
>>>
>>>>> To make the DT binding backward compatible you likely need to add a few
>>>>> compatible that otherwise would have been left out - but that should do
>>>>> the trick.
>>>>>
>>>>> The current atmel hlcdc driver that is split in three is IMO an
>>>>> over-engineering, and the driver could benefit merging it all in one.
>>>>> And the binding should not prevent this.
>>>>
>>>> I agree on all this, but a conversion is not really the time to redesign
>>>> things. Trust me, I've wanted to on lots of conversions. It should be
>>>> possible to simplify the driver side while keeping the DT as-is. Just
>>>> make the display driver bind to the MFD node instead. After that, then
>>>> one could look at flattening everything to 1 node.
>>>
>>> Understood and thinking a bit about it fully agreed as well.
>>> Dharma - please see my comments only as ideas for the future, and
>>> ignore them in this fine rewrite you do.
>>>
>>>           Sam
>> Based on your insights, I'm contemplating the decision to merge Patch 2
>> [PWM binding] with Patch 3[MFD binding]. It seems redundant given that
>> we already have a PWM node example in the MFD binding.
>>
>> Instead of introducing a new PWM binding,
>>     pwm:
>>       $ref: /schemas/pwm/atmel,hlcdc-pwm.yaml
>>
>> I will update the existing MFD binding as follows:
>>
>> properties:
>>     compatible:
>>       const: atmel,hlcdc-pwm
>>
>>     "#pwm-cells":
>>       const: 3
>>
>> required:
>>     - compatible
>>     - "#pwm-cells"
>>
> As already commented, this looks nice.
> But as Rob said, this should be a 1:1 conversion from text to yaml,
> and then clean-up can come in the second step.

Fine, I will send v4 with no changes in [PATCH 2] PWM binding, I will 
send another separate patch for this clean up.

-- 
Thanks,
Dharma B.

> 
>          Sam

Re: [PATCH v3 2/3] dt-bindings: atmel,hlcdc: convert pwm bindings to json-schema

[Dharma.B]

Hi Rob,
On 20/01/24 1:15 am, Rob Herring wrote:
> EXTERNAL EMAIL: Do not click links or open attachments unless you know the content is safe
> 
> On Thu, Jan 18, 2024 at 02:56:11PM +0530, Dharma Balasubiramani wrote:
>> Convert device tree bindings for Atmel's HLCDC PWM controller to YAML
>> format.
>>
>> Signed-off-by: Dharma Balasubiramani <dharma.b@microchip.com>
>> Reviewed-by: Conor Dooley <conor.dooley@microchip.com>
>> ---
>> changelog
>> v2 -> v3
>> - Remove '|' in description, as there is no formatting to preserve.
>> - Delete the description for pwm-cells.
>> - Drop the label for pwm node as it not used.
>> v1 -> v2
>> - Remove the explicit copyrights.
>> - Modify title (not include words like binding/driver).
>> - Modify description actually describing the hardware and not the driver.
>> - Remove pinctrl properties which aren't required.
>> - Drop parent node and it's other sub-device node which are not related here.
>> ---
>>   .../bindings/pwm/atmel,hlcdc-pwm.yaml         | 44 +++++++++++++++++++
>>   .../bindings/pwm/atmel-hlcdc-pwm.txt          | 29 ------------
>>   2 files changed, 44 insertions(+), 29 deletions(-)
>>   create mode 100644 Documentation/devicetree/bindings/pwm/atmel,hlcdc-pwm.yaml
>>   delete mode 100644 Documentation/devicetree/bindings/pwm/atmel-hlcdc-pwm.txt
>>
>> diff --git a/Documentation/devicetree/bindings/pwm/atmel,hlcdc-pwm.yaml b/Documentation/devicetree/bindings/pwm/atmel,hlcdc-pwm.yaml
>> new file mode 100644
>> index 000000000000..4f4cc21fe4f7
>> --- /dev/null
>> +++ b/Documentation/devicetree/bindings/pwm/atmel,hlcdc-pwm.yaml
>> @@ -0,0 +1,44 @@
>> +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
>> +%YAML 1.2
>> +---
>> +$id: http://devicetree.org/schemas/pwm/atmel,hlcdc-pwm.yaml#
>> +$schema: http://devicetree.org/meta-schemas/core.yaml#
>> +
>> +title: Atmel's HLCDC's PWM controller
>> +
>> +maintainers:
>> +  - Nicolas Ferre <nicolas.ferre@microchip.com>
>> +  - Alexandre Belloni <alexandre.belloni@bootlin.com>
>> +  - Claudiu Beznea <claudiu.beznea@tuxon.dev>
>> +
>> +description:
>> +  The LCDC integrates a Pulse Width Modulation (PWM) Controller. This block
>> +  generates the LCD contrast control signal (LCD_PWM) that controls the
>> +  display's contrast by software. LCDC_PWM is an 8-bit PWM signal that can be
>> +  converted to an analog voltage with a simple passive filter. LCD display
>> +  panels have different backlight specifications in terms of minimum/maximum
>> +  values for PWM frequency. If the LCDC PWM frequency range does not match the
>> +  LCD display panel, it is possible to use the standalone PWM Controller to
>> +  drive the backlight.
>> +
>> +properties:
>> +  compatible:
>> +    const: atmel,hlcdc-pwm
>> +
>> +  "#pwm-cells":
>> +    const: 3
>> +
>> +required:
>> +  - compatible
>> +  - "#pwm-cells"
>> +
>> +additionalProperties: false
>> +
>> +examples:
>> +  - |
>> +    pwm {
>> +      compatible = "atmel,hlcdc-pwm";
>> +      pinctrl-names = "default";
>> +      pinctrl-0 = <&pinctrl_lcd_pwm>;
>> +      #pwm-cells = <3>;
>> +    };
> 
> Move the example to the MFD schema. Or just drop if already there.

As Sam suggested I will send v4 series with this binding as it is and 
will send the clean up patch later.

-- 
Thanks,
Dharma B.
> 
> Rob

Re: [PATCH v3 3/3] dt-bindings: mfd: atmel,hlcdc: Convert to DT schema format

[Conor Dooley]

[-- Attachment #1: Type: text/plain, Size: 7937 bytes --]

On Wed, Jan 24, 2024 at 05:18:26AM +0000, Dharma.B@microchip.com wrote:
> Hi Conor & All,
> 
> On 22/01/24 2:46 pm, Conor Dooley wrote:
> > On Mon, Jan 22, 2024 at 03:38:41AM +0000,Dharma.B@microchip.com  wrote:
> >> Hi Conor,
> >> On 19/01/24 5:33 pm, Conor Dooley - M52691 wrote:
> >>> On Fri, Jan 19, 2024 at 03:32:49AM +0000,Dharma.B@microchip.com  wrote:
> >>>> On 18/01/24 9:10 pm, Conor Dooley wrote:
> >>>>> On Thu, Jan 18, 2024 at 02:56:12PM +0530, Dharma Balasubiramani wrote:
> >>>>>> Convert the atmel,hlcdc binding to DT schema format.
> >>>>>>
> >>>>>> Adjust the clock-names property to clarify that the LCD controller expects
> >>>>>> one of these clocks (either sys_clk or lvds_pll_clk to be present but not
> >>>>>> both) along with the slow_clk and periph_clk. This alignment with the actual
> >>>>>> hardware requirements will enable accurate device tree configuration for
> >>>>>> systems using the HLCDC IP.
> >>>>>>
> >>>>>> Signed-off-by: Dharma Balasubiramani<dharma.b@microchip.com>
> >>>>>> ---
> >>>>>> changelog
> >>>>>> v2 -> v3
> >>>>>> - Rename hlcdc-display-controller and hlcdc-pwm to generic names.
> >>>>>> - Modify the description by removing the unwanted comments and '|'.
> >>>>>> - Modify clock-names simpler.
> >>>>>> v1 -> v2
> >>>>>> - Remove the explicit copyrights.
> >>>>>> - Modify title (not include words like binding/driver).
> >>>>>> - Modify description actually describing the hardware and not the driver.
> >>>>>> - Add details of lvds_pll addition in commit message.
> >>>>>> - Ref endpoint and not endpoint-base.
> >>>>>> - Fix coding style.
> >>>>>> ...
> >>>>>>     .../devicetree/bindings/mfd/atmel,hlcdc.yaml  | 97 +++++++++++++++++++
> >>>>>>     .../devicetree/bindings/mfd/atmel-hlcdc.txt   | 56 -----------
> >>>>>>     2 files changed, 97 insertions(+), 56 deletions(-)
> >>>>>>     create mode 100644 Documentation/devicetree/bindings/mfd/atmel,hlcdc.yaml
> >>>>>>     delete mode 100644 Documentation/devicetree/bindings/mfd/atmel-hlcdc.txt
> >>>>>>
> >>>>>> diff --git a/Documentation/devicetree/bindings/mfd/atmel,hlcdc.yaml b/Documentation/devicetree/bindings/mfd/atmel,hlcdc.yaml
> >>>>>> new file mode 100644
> >>>>>> index 000000000000..eccc998ac42c
> >>>>>> --- /dev/null
> >>>>>> +++ b/Documentation/devicetree/bindings/mfd/atmel,hlcdc.yaml
> >>>>>> @@ -0,0 +1,97 @@
> >>>>>> +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
> >>>>>> +%YAML 1.2
> >>>>>> +---
> >>>>>> +$id:http://devicetree.org/schemas/mfd/atmel,hlcdc.yaml#
> >>>>>> +$schema:http://devicetree.org/meta-schemas/core.yaml#
> >>>>>> +
> >>>>>> +title: Atmel's HLCD Controller
> >>>>>> +
> >>>>>> +maintainers:
> >>>>>> +  - Nicolas Ferre<nicolas.ferre@microchip.com>
> >>>>>> +  - Alexandre Belloni<alexandre.belloni@bootlin.com>
> >>>>>> +  - Claudiu Beznea<claudiu.beznea@tuxon.dev>
> >>>>>> +
> >>>>>> +description:
> >>>>>> +  The Atmel HLCDC (HLCD Controller) IP available on Atmel SoCs exposes two
> >>>>>> +  subdevices, a PWM chip and a Display Controller.
> >>>>>> +
> >>>>>> +properties:
> >>>>>> +  compatible:
> >>>>>> +    enum:
> >>>>>> +      - atmel,at91sam9n12-hlcdc
> >>>>>> +      - atmel,at91sam9x5-hlcdc
> >>>>>> +      - atmel,sama5d2-hlcdc
> >>>>>> +      - atmel,sama5d3-hlcdc
> >>>>>> +      - atmel,sama5d4-hlcdc
> >>>>>> +      - microchip,sam9x60-hlcdc
> >>>>>> +      - microchip,sam9x75-xlcdc
> >>>>>> +
> >>>>>> +  reg:
> >>>>>> +    maxItems: 1
> >>>>>> +
> >>>>>> +  interrupts:
> >>>>>> +    maxItems: 1
> >>>>>> +
> >>>>>> +  clocks:
> >>>>>> +    maxItems: 3
> >>>>> Hmm, one thing I probably should have said on the previous version, but
> >>>>> I missed somehow: It would be good to add an items list to the clocks
> >>>>> property here to explain what the 3 clocks are/are used for - especially
> >>>>> since there is additional complexity being added here to use either the
> >>>>> sys or lvds clocks.
> >>>> May I inquire if this approach is likely to be effective?
> >>>>
> >>>>      clocks:
> >>>>        items:
> >>>>          - description: peripheral clock
> >>>>          - description: generic clock or lvds pll clock
> >>>>              Once the LVDS PLL is enabled, the pixel clock is used as the
> >>>>              clock for LCDC, so its GCLK is no longer needed.
> >>>>          - description: slow clock
> >>>>        maxItems: 3
> >>> Hmm that sounds very suspect to me. "Once the lvdspll is enabled the
> >>> generic clock is no longer needed" sounds like both clocks can be provided
> >>> to the IP on different pins and their provision is not mutually
> >>> exclusive, just that the IP will only actually use one at a time. If
> >>> that is the case, then this patch is nott correct and the binding should
> >>> allow for 4 clocks, with both the generic clock and the lvds pll being
> >>> present in the DT at the same time.
> >>>
> >>> I vaguely recall internal discussion about this problem some time back
> >>> but the details all escape me.
> >> Let's delve deeper into the clock configuration for LCDC_PCK.
> >>
> >> Considering the flexibility of the design, it appears that both clocks,
> >> sys_clk (generic clock) and lvds_pll_clk, can indeed be provided to the
> >> IP simultaneously. The crucial aspect, however, is that the IP will
> >> utilize only one of these clocks at any given time. This aligns with the
> >> specific requirements of the application, where the choice of clock
> >> depends on whether the LVDS interface or MIPI/DSI is in use.
> > If both clocks can physically be provided to the IP then both of them
> > should be in the dt. The hcldc appears to me to be a part of the SoC and
> > the clock routing to the IP is likely fixed.
> > 
> >> To ensure proper configuration of the pixel clock period, we need to
> >> distinctly identify which clocks are being utilized. For instance, in
> >> the LVDS interface scenario, the lvds_pll_clk is essential, resulting in
> >> LCDC_PCK being set to the source clock. Conversely, in the MIPI/DSI
> >> case, the LCDC GCLK is required, leading to LCDC_PCK being defined as
> >> source clock/CLKDIV+2.
> >>
> >> Considering the potential coexistence of sys_clk and lvds_pll_clk in the
> >> Device Tree (DT), we may need to introduce an additional flag in the DT.
> >> This flag could serve as a clear indicator of whether the LVDS interface
> >> or MIPI/DSI is being employed. As we discussed to drop this flag and
> >> just have any one of the clocks I believe that this approach provides a
> >> sensible and scalable solution, allowing for a comprehensive
> >> representation of the clocking configuration.
> > This is probably a question for the folks on the DRM or media side of
> > things, but is it not possible to determine based on the endpoint what
> > protocol is required?
> > I know that on the media side of things there's an endpoint property
> > that can be used to specific the bus-type - is there an equivalent
> > property for DRM stuff?
> 
> Yes, it can be done.
> I will have the lvds pll in the lvds DT node.
> I will just convert the existing text binding to yaml without this 
> additonal lvds pll clock.

If the lvds pll is an input to the hlcdc, you need to add it here.
From your description earlier it does sound like it is an input to
the hlcdc, but now you are claiming that it is not.

I don't know your hardware, so I have no idea which of the two is
correct, but it sounds like the former. Without digging into how this
works my assumption about the hardware here looks like is that the lvds
controller is a clock provider, and that the lvds controller's clock is
an optional input for the hlcdc.

Can you please explain what provides the lvds pll clock and show an
example of how you think the devictree would look with "the lvds pll in
the lvds dt node"?

Thanks,
Conor.


[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 228 bytes --]

Re: [PATCH v3 3/3] dt-bindings: mfd: atmel,hlcdc: Convert to DT schema format

[Dharma.B]

Hi Conor,
On 24/01/24 10:09 pm, Conor Dooley wrote:
> On Wed, Jan 24, 2024 at 05:18:26AM +0000,Dharma.B@microchip.com  wrote:
>> Hi Conor & All,
>>
>> On 22/01/24 2:46 pm, Conor Dooley wrote:
>>> On Mon, Jan 22, 2024 at 03:38:41AM +0000,Dharma.B@microchip.com   wrote:
>>>> Hi Conor,
>>>> On 19/01/24 5:33 pm, Conor Dooley - M52691 wrote:
>>>>> On Fri, Jan 19, 2024 at 03:32:49AM +0000,Dharma.B@microchip.com   wrote:
>>>>>> On 18/01/24 9:10 pm, Conor Dooley wrote:
>>>>>>> On Thu, Jan 18, 2024 at 02:56:12PM +0530, Dharma Balasubiramani wrote:
>>>>>>>> Convert the atmel,hlcdc binding to DT schema format.
>>>>>>>>
>>>>>>>> Adjust the clock-names property to clarify that the LCD controller expects
>>>>>>>> one of these clocks (either sys_clk or lvds_pll_clk to be present but not
>>>>>>>> both) along with the slow_clk and periph_clk. This alignment with the actual
>>>>>>>> hardware requirements will enable accurate device tree configuration for
>>>>>>>> systems using the HLCDC IP.
>>>>>>>>
>>>>>>>> Signed-off-by: Dharma Balasubiramani<dharma.b@microchip.com>
>>>>>>>> ---
>>>>>>>> changelog
>>>>>>>> v2 -> v3
>>>>>>>> - Rename hlcdc-display-controller and hlcdc-pwm to generic names.
>>>>>>>> - Modify the description by removing the unwanted comments and '|'.
>>>>>>>> - Modify clock-names simpler.
>>>>>>>> v1 -> v2
>>>>>>>> - Remove the explicit copyrights.
>>>>>>>> - Modify title (not include words like binding/driver).
>>>>>>>> - Modify description actually describing the hardware and not the driver.
>>>>>>>> - Add details of lvds_pll addition in commit message.
>>>>>>>> - Ref endpoint and not endpoint-base.
>>>>>>>> - Fix coding style.
>>>>>>>> ...
>>>>>>>>      .../devicetree/bindings/mfd/atmel,hlcdc.yaml  | 97 +++++++++++++++++++
>>>>>>>>      .../devicetree/bindings/mfd/atmel-hlcdc.txt   | 56 -----------
>>>>>>>>      2 files changed, 97 insertions(+), 56 deletions(-)
>>>>>>>>      create mode 100644 Documentation/devicetree/bindings/mfd/atmel,hlcdc.yaml
>>>>>>>>      delete mode 100644 Documentation/devicetree/bindings/mfd/atmel-hlcdc.txt
>>>>>>>>
>>>>>>>> diff --git a/Documentation/devicetree/bindings/mfd/atmel,hlcdc.yaml b/Documentation/devicetree/bindings/mfd/atmel,hlcdc.yaml
>>>>>>>> new file mode 100644
>>>>>>>> index 000000000000..eccc998ac42c
>>>>>>>> --- /dev/null
>>>>>>>> +++ b/Documentation/devicetree/bindings/mfd/atmel,hlcdc.yaml
>>>>>>>> @@ -0,0 +1,97 @@
>>>>>>>> +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
>>>>>>>> +%YAML 1.2
>>>>>>>> +---
>>>>>>>> +$id:http://devicetree.org/schemas/mfd/atmel,hlcdc.yaml#
>>>>>>>> +$schema:http://devicetree.org/meta-schemas/core.yaml#
>>>>>>>> +
>>>>>>>> +title: Atmel's HLCD Controller
>>>>>>>> +
>>>>>>>> +maintainers:
>>>>>>>> +  - Nicolas Ferre<nicolas.ferre@microchip.com>
>>>>>>>> +  - Alexandre Belloni<alexandre.belloni@bootlin.com>
>>>>>>>> +  - Claudiu Beznea<claudiu.beznea@tuxon.dev>
>>>>>>>> +
>>>>>>>> +description:
>>>>>>>> +  The Atmel HLCDC (HLCD Controller) IP available on Atmel SoCs exposes two
>>>>>>>> +  subdevices, a PWM chip and a Display Controller.
>>>>>>>> +
>>>>>>>> +properties:
>>>>>>>> +  compatible:
>>>>>>>> +    enum:
>>>>>>>> +      - atmel,at91sam9n12-hlcdc
>>>>>>>> +      - atmel,at91sam9x5-hlcdc
>>>>>>>> +      - atmel,sama5d2-hlcdc
>>>>>>>> +      - atmel,sama5d3-hlcdc
>>>>>>>> +      - atmel,sama5d4-hlcdc
>>>>>>>> +      - microchip,sam9x60-hlcdc
>>>>>>>> +      - microchip,sam9x75-xlcdc
>>>>>>>> +
>>>>>>>> +  reg:
>>>>>>>> +    maxItems: 1
>>>>>>>> +
>>>>>>>> +  interrupts:
>>>>>>>> +    maxItems: 1
>>>>>>>> +
>>>>>>>> +  clocks:
>>>>>>>> +    maxItems: 3
>>>>>>> Hmm, one thing I probably should have said on the previous version, but
>>>>>>> I missed somehow: It would be good to add an items list to the clocks
>>>>>>> property here to explain what the 3 clocks are/are used for - especially
>>>>>>> since there is additional complexity being added here to use either the
>>>>>>> sys or lvds clocks.
>>>>>> May I inquire if this approach is likely to be effective?
>>>>>>
>>>>>>       clocks:
>>>>>>         items:
>>>>>>           - description: peripheral clock
>>>>>>           - description: generic clock or lvds pll clock
>>>>>>               Once the LVDS PLL is enabled, the pixel clock is used as the
>>>>>>               clock for LCDC, so its GCLK is no longer needed.
>>>>>>           - description: slow clock
>>>>>>         maxItems: 3
>>>>> Hmm that sounds very suspect to me. "Once the lvdspll is enabled the
>>>>> generic clock is no longer needed" sounds like both clocks can be provided
>>>>> to the IP on different pins and their provision is not mutually
>>>>> exclusive, just that the IP will only actually use one at a time. If
>>>>> that is the case, then this patch is nott correct and the binding should
>>>>> allow for 4 clocks, with both the generic clock and the lvds pll being
>>>>> present in the DT at the same time.
>>>>>
>>>>> I vaguely recall internal discussion about this problem some time back
>>>>> but the details all escape me.
>>>> Let's delve deeper into the clock configuration for LCDC_PCK.
>>>>
>>>> Considering the flexibility of the design, it appears that both clocks,
>>>> sys_clk (generic clock) and lvds_pll_clk, can indeed be provided to the
>>>> IP simultaneously. The crucial aspect, however, is that the IP will
>>>> utilize only one of these clocks at any given time. This aligns with the
>>>> specific requirements of the application, where the choice of clock
>>>> depends on whether the LVDS interface or MIPI/DSI is in use.
>>> If both clocks can physically be provided to the IP then both of them
>>> should be in the dt. The hcldc appears to me to be a part of the SoC and
>>> the clock routing to the IP is likely fixed.
>>>
>>>> To ensure proper configuration of the pixel clock period, we need to
>>>> distinctly identify which clocks are being utilized. For instance, in
>>>> the LVDS interface scenario, the lvds_pll_clk is essential, resulting in
>>>> LCDC_PCK being set to the source clock. Conversely, in the MIPI/DSI
>>>> case, the LCDC GCLK is required, leading to LCDC_PCK being defined as
>>>> source clock/CLKDIV+2.
>>>>
>>>> Considering the potential coexistence of sys_clk and lvds_pll_clk in the
>>>> Device Tree (DT), we may need to introduce an additional flag in the DT.
>>>> This flag could serve as a clear indicator of whether the LVDS interface
>>>> or MIPI/DSI is being employed. As we discussed to drop this flag and
>>>> just have any one of the clocks I believe that this approach provides a
>>>> sensible and scalable solution, allowing for a comprehensive
>>>> representation of the clocking configuration.
>>> This is probably a question for the folks on the DRM or media side of
>>> things, but is it not possible to determine based on the endpoint what
>>> protocol is required?
>>> I know that on the media side of things there's an endpoint property
>>> that can be used to specific the bus-type - is there an equivalent
>>> property for DRM stuff?
>> Yes, it can be done.
>> I will have the lvds pll in the lvds DT node.
>> I will just convert the existing text binding to yaml without this
>> additonal lvds pll clock.
> If the lvds pll is an input to the hlcdc, you need to add it here.
>  From your description earlier it does sound like it is an input to
> the hlcdc, but now you are claiming that it is not.

The LVDS PLL serves as an input to both the LCDC and LVDSC, with the 
LVDS_PLL multiplied by 7 for the Pixel clock to the LVDS PHY, and 
LVDS_PLL divided by 7 for the Pixel clock to the LCDC.

I am inclined to believe that appropriately configuring and enabling it 
in the LVDS driver would be the appropriate course of action.

> 
> I don't know your hardware, so I have no idea which of the two is
> correct, but it sounds like the former. Without digging into how this
> works my assumption about the hardware here looks like is that the lvds
> controller is a clock provider,

It's a PLL clock from PMC.

> and that the lvds controller's clock is
> an optional input for the hlcdc.

Again it's a PLL clock from PMC.

Please refer Section 39.3 
https://ww1.microchip.com/downloads/aemDocuments/documents/MPU32/ProductDocuments/DataSheets/SAM9X7-Series-Data-Sheet-DS60001813.pdf

> 
> Can you please explain what provides the lvds pll clock and show an
> example of how you think the devictree would look with "the lvds pll in
> the lvds dt node"?

Sure, Please see the below example

The typical lvds node will look like

                 lvds_controller: lvds-controller@f8060000 {
                         compatible = "microchip,sam9x7-lvds";
                         reg = <0xf8060000 0x100>;
                         interrupts = <56 IRQ_TYPE_LEVEL_HIGH 0>;
                         clocks = <&pmc PMC_TYPE_PERIPHERAL 56>, <&pmc 
PMC_TYPE_CORE PMC_LVDSPLL>;
                         clock-names = "pclk", "lvds_pll_clk";
                         status = "disabled";
                 };

-- 
With Best Regards,
Dharma B.
> 
> Thanks,
> Conor.
> 

Re: [PATCH v3 3/3] dt-bindings: mfd: atmel,hlcdc: Convert to DT schema format

[Conor Dooley]

[-- Attachment #1: Type: text/plain, Size: 2517 bytes --]


> > If the lvds pll is an input to the hlcdc, you need to add it here.
> >  From your description earlier it does sound like it is an input to
> > the hlcdc, but now you are claiming that it is not.
> 
> The LVDS PLL serves as an input to both the LCDC and LVDSC

Then it should be an input to both the LCDC and LVDSC in the devicetree.

> with the 
> LVDS_PLL multiplied by 7 for the Pixel clock to the LVDS PHY, and 

Are you sure? The diagram doesn't show a multiplier, the 7x comment
there seems to be showing relations?

> LVDS_PLL divided by 7 for the Pixel clock to the LCDC.

> I am inclined to believe that appropriately configuring and enabling it 
> in the LVDS driver would be the appropriate course of action.

We're talking about bindings here, not drivers, but I would imagine that
if two peripherals are using the same clock then both of them should be
getting a reference to and enabling that clock so that the clock
framework can correctly track the users.

> > I don't know your hardware, so I have no idea which of the two is
> > correct, but it sounds like the former. Without digging into how this
> > works my assumption about the hardware here looks like is that the lvds
> > controller is a clock provider,
> 
> It's a PLL clock from PMC.
> 
> > and that the lvds controller's clock is
> > an optional input for the hlcdc.
> 
> Again it's a PLL clock from PMC.
> 
> Please refer Section 39.3 
> https://ww1.microchip.com/downloads/aemDocuments/documents/MPU32/ProductDocuments/DataSheets/SAM9X7-Series-Data-Sheet-DS60001813.pdf

It is not the same exact clock as you pointed out above though, so the
by 7 divider should be modelled.

> > Can you please explain what provides the lvds pll clock and show an
> > example of how you think the devictree would look with "the lvds pll in
> > the lvds dt node"?
> 
> Sure, Please see the below example
> 
> The typical lvds node will look like
> 
>                  lvds_controller: lvds-controller@f8060000 {
>                          compatible = "microchip,sam9x7-lvds";
>                          reg = <0xf8060000 0x100>;
>                          interrupts = <56 IRQ_TYPE_LEVEL_HIGH 0>;
>                          clocks = <&pmc PMC_TYPE_PERIPHERAL 56>, <&pmc 
> PMC_TYPE_CORE PMC_LVDSPLL>;
>                          clock-names = "pclk", "lvds_pll_clk";
>                          status = "disabled";
>                  };

In isolation, this looks fine.

Cheers,
Conor.

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 228 bytes --]

Re: [PATCH v3 3/3] dt-bindings: mfd: atmel,hlcdc: Convert to DT schema format

[Dharma.B]

Hi Conor,

On 25/01/24 1:57 pm, Conor Dooley - M52691 wrote:
> 
>>> If the lvds pll is an input to the hlcdc, you need to add it here.
>>>   From your description earlier it does sound like it is an input to
>>> the hlcdc, but now you are claiming that it is not.
>>
>> The LVDS PLL serves as an input to both the LCDC and LVDSC
> 
> Then it should be an input to both the LCDC and LVDSC in the devicetree.

For the LVDSC to operate, the presence of the LVDS PLL is crucial. However, in the case of the LCDC, LVDS PLL is not essential for its operation unless LVDS interface is used and when it is used lvds driver will take care of preparing and enabling the LVDS PLL.

Consequently, it seems that there might not be any significant actions we can take within the LCD driver regarding the LVDS PLL.

If there are no intentions to utilize it within the driver, is it necessary to explicitly designate it as an input in the device tree?

If yes, I will update the bindings with optional LVDS PLL clock.

clock-names:
  items:
    - const: periph_clk
    - const: sys_clk
    - const: slow_clk
    - const: lvds_pll  # Optional clock


> 
>> with the
>> LVDS_PLL multiplied by 7 for the Pixel clock to the LVDS PHY, and
> 
> Are you sure? The diagram doesn't show a multiplier, the 7x comment
> there seems to be showing relations?

Sorry, 
LVDS PLL = (PCK * 7) goes to LVDSC PHY
PCK = (LVDS PLL / 7) goes to LCDC

> 
>> LVDS_PLL divided by 7 for the Pixel clock to the LCDC.
> 
>> I am inclined to believe that appropriately configuring and enabling it
>> in the LVDS driver would be the appropriate course of action.
> 
> We're talking about bindings here, not drivers, but I would imagine that
> if two peripherals are using the same clock then both of them should be
> getting a reference to and enabling that clock so that the clock
> framework can correctly track the users.
> 
>>> I don't know your hardware, so I have no idea which of the two is
>>> correct, but it sounds like the former. Without digging into how this
>>> works my assumption about the hardware here looks like is that the lvds
>>> controller is a clock provider,
>>
>> It's a PLL clock from PMC.
>>
>>> and that the lvds controller's clock is
>>> an optional input for the hlcdc.
>>
>> Again it's a PLL clock from PMC.
>>
>> Please refer Section 39.3
>> https://ww1.microchip.com/downloads/aemDocuments/documents/MPU32/ProductDocuments/DataSheets/SAM9X7-Series-Data-Sheet-DS60001813.pdf
> 
> It is not the same exact clock as you pointed out above though, so the
> by 7 divider should be modelled.

Modelled in mfd binding? If possible, could you please provide an example for better clarity? Thank you.

> 
>>> Can you please explain what provides the lvds pll clock and show an
>>> example of how you think the devictree would look with "the lvds pll in
>>> the lvds dt node"?
>>
>> Sure, Please see the below example
>>
>> The typical lvds node will look like
>>
>>                   lvds_controller: lvds-controller@f8060000 {
>>                           compatible = "microchip,sam9x7-lvds";
>>                           reg = <0xf8060000 0x100>;
>>                           interrupts = <56 IRQ_TYPE_LEVEL_HIGH 0>;
>>                           clocks = <&pmc PMC_TYPE_PERIPHERAL 56>, <&pmc
>> PMC_TYPE_CORE PMC_LVDSPLL>;
>>                           clock-names = "pclk", "lvds_pll_clk";
>>                           status = "disabled";
>>                   };
> 
> In isolation, this looks fine.
> 
> Cheers,
> Conor.
-- 
With Best Regards,
Dharma B.

Re: [PATCH v3 3/3] dt-bindings: mfd: atmel,hlcdc: Convert to DT schema format

[Conor Dooley]

[-- Attachment #1: Type: text/plain, Size: 3841 bytes --]

On Fri, Jan 26, 2024 at 02:22:42PM +0000, Dharma.B@microchip.com wrote:
> On 25/01/24 1:57 pm, Conor Dooley - M52691 wrote:
> > 
> >>> If the lvds pll is an input to the hlcdc, you need to add it here.
> >>>   From your description earlier it does sound like it is an input to
> >>> the hlcdc, but now you are claiming that it is not.
> >>
> >> The LVDS PLL serves as an input to both the LCDC and LVDSC
> > 
> > Then it should be an input to both the LCDC and LVDSC in the devicetree.
> 
> For the LVDSC to operate, the presence of the LVDS PLL is crucial. However, in the case of the LCDC, LVDS PLL is not essential for its operation unless LVDS interface is used and when it is used lvds driver will take care of preparing and enabling the LVDS PLL.

Please fix your line wrapping, not sure what's going on here, but these
lines are super long.

> Consequently, it seems that there might not be any significant actions we can take within the LCD driver regarding the LVDS PLL.

You should be getting a reference to the clock and calling enable on it
etc, even if the LVDSC is also doing so. That will allow the clock
framework to correctly track users.

> If there are no intentions to utilize it within the driver, is it necessary to explicitly designate it as an input in the device tree?

The binding describes the hardware, so yes it should be there. What the
driver implementation does with the clock is not relevant. That said, I
think the driver should actually be using it, as I wrote above.

> 
> If yes, I will update the bindings with optional LVDS PLL clock.
> 
> clock-names:
>   items:
>     - const: periph_clk
>     - const: sys_clk
>     - const: slow_clk
>     - const: lvds_pll  # Optional clock

This looks correct, but the comment is not needed. Setting minItems: 3
does this for you.

> >> with the
> >> LVDS_PLL multiplied by 7 for the Pixel clock to the LVDS PHY, and
> > 
> > Are you sure? The diagram doesn't show a multiplier, the 7x comment
> > there seems to be showing relations?
> 
> Sorry, 
> LVDS PLL = (PCK * 7) goes to LVDSC PHY
> PCK = (LVDS PLL / 7) goes to LCDC

I'll take your word for it :)

> >> LVDS_PLL divided by 7 for the Pixel clock to the LCDC.
> > 
> >> I am inclined to believe that appropriately configuring and enabling it
> >> in the LVDS driver would be the appropriate course of action.
> > 
> > We're talking about bindings here, not drivers, but I would imagine that
> > if two peripherals are using the same clock then both of them should be
> > getting a reference to and enabling that clock so that the clock
> > framework can correctly track the users.
> > 
> >>> I don't know your hardware, so I have no idea which of the two is
> >>> correct, but it sounds like the former. Without digging into how this
> >>> works my assumption about the hardware here looks like is that the lvds
> >>> controller is a clock provider,
> >>
> >> It's a PLL clock from PMC.
> >>
> >>> and that the lvds controller's clock is
> >>> an optional input for the hlcdc.
> >>
> >> Again it's a PLL clock from PMC.
> >>
> >> Please refer Section 39.3
> >> https://ww1.microchip.com/downloads/aemDocuments/documents/MPU32/ProductDocuments/DataSheets/SAM9X7-Series-Data-Sheet-DS60001813.pdf
> > 
> > It is not the same exact clock as you pointed out above though, so the
> > by 7 divider should be modelled.
> 
> Modelled in mfd binding? If possible, could you please provide an example for better clarity? Thank you.

Whatever node corresponds to the register range controlling this PLL
should be a "clock-controller" (like any other clock provider does).
Your PMC should have this property. I don't know if the correct location
is the mfd node or somewhere else, you'll have to check your docs.

Thanks,
Conor.

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 228 bytes --]

Re: [PATCH v3 3/3] dt-bindings: mfd: atmel,hlcdc: Convert to DT schema format

[Dharma.B]

Hi Conor,

On 26/01/24 9:03 pm, Conor Dooley wrote:
> On Fri, Jan 26, 2024 at 02:22:42PM +0000,Dharma.B@microchip.com  wrote:
>> On 25/01/24 1:57 pm, Conor Dooley - M52691 wrote:
>>>>> If the lvds pll is an input to the hlcdc, you need to add it here.
>>>>>    From your description earlier it does sound like it is an input to
>>>>> the hlcdc, but now you are claiming that it is not.
>>>> The LVDS PLL serves as an input to both the LCDC and LVDSC
>>> Then it should be an input to both the LCDC and LVDSC in the devicetree.
>> For the LVDSC to operate, the presence of the LVDS PLL is crucial. However, in the case of the LCDC, LVDS PLL is not essential for its operation unless LVDS interface is used and when it is used lvds driver will take care of preparing and enabling the LVDS PLL.
> Please fix your line wrapping, not sure what's going on here, but these
> lines are super long.
> 
>> Consequently, it seems that there might not be any significant actions we can take within the LCD driver regarding the LVDS PLL.
> You should be getting a reference to the clock and calling enable on it
> etc, even if the LVDSC is also doing so. That will allow the clock
> framework to correctly track users.
> 
>> If there are no intentions to utilize it within the driver, is it necessary to explicitly designate it as an input in the device tree?
> The binding describes the hardware, so yes it should be there. What the
> driver implementation does with the clock is not relevant. That said, I
> think the driver should actually be using it, as I wrote above.
> 
>> If yes, I will update the bindings with optional LVDS PLL clock.
>>
>> clock-names:
>>    items:
>>      - const: periph_clk
>>      - const: sys_clk
>>      - const: slow_clk
>>      - const: lvds_pll  # Optional clock
> This looks correct, but the comment is not needed. Setting minItems: 3
> does this for you.
Sure, thanks.
> 
>>>> with the
>>>> LVDS_PLL multiplied by 7 for the Pixel clock to the LVDS PHY, and
>>> Are you sure? The diagram doesn't show a multiplier, the 7x comment
>>> there seems to be showing relations?
>> Sorry,
>> LVDS PLL = (PCK * 7) goes to LVDSC PHY
>> PCK = (LVDS PLL / 7) goes to LCDC
> I'll take your word for it 🙂
> 
>>>> LVDS_PLL divided by 7 for the Pixel clock to the LCDC.
>>>> I am inclined to believe that appropriately configuring and enabling it
>>>> in the LVDS driver would be the appropriate course of action.
>>> We're talking about bindings here, not drivers, but I would imagine that
>>> if two peripherals are using the same clock then both of them should be
>>> getting a reference to and enabling that clock so that the clock
>>> framework can correctly track the users.
>>>
>>>>> I don't know your hardware, so I have no idea which of the two is
>>>>> correct, but it sounds like the former. Without digging into how this
>>>>> works my assumption about the hardware here looks like is that the lvds
>>>>> controller is a clock provider,
>>>> It's a PLL clock from PMC.
>>>>
>>>>> and that the lvds controller's clock is
>>>>> an optional input for the hlcdc.
>>>> Again it's a PLL clock from PMC.
>>>>
>>>> Please refer Section 39.3
>>>> https://ww1.microchip.com/downloads/aemDocuments/documents/MPU32/ProductDocuments/DataSheets/SAM9X7-Series-Data-Sheet-DS60001813.pdf
>>> It is not the same exact clock as you pointed out above though, so the
>>> by 7 divider should be modelled.
>> Modelled in mfd binding? If possible, could you please provide an example for better clarity? Thank you.
> Whatever node corresponds to the register range controlling this PLL
> should be a "clock-controller" (like any other clock provider does).
> Your PMC should have this property. I don't know if the correct location
> is the mfd node or somewhere else, you'll have to check your docs.
Sure, Noted. I'll do that in separate patch.
---
I will proceed with updating the clock names to include "lvds pll" and 
adjusting the clocks minitems to 3. Does this seem appropriate to you?

Please let me know if there are any additional considerations or 
specific aspects that require attention.

-- 
With Best Regards,
Dharma B.
> 
> Thanks,
> Conor.

Re: [PATCH v3 3/3] dt-bindings: mfd: atmel,hlcdc: Convert to DT schema format

[Conor Dooley]

[-- Attachment #1: Type: text/plain, Size: 367 bytes --]

On Mon, Jan 29, 2024 at 03:41:22AM +0000, Dharma.B@microchip.com wrote:
> I will proceed with updating the clock names to include "lvds pll" and 
> adjusting the clocks minitems to 3. Does this seem appropriate to you?
> 
> Please let me know if there are any additional considerations or 
> specific aspects that require attention.

That seems okay, thanks.

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 228 bytes --]