Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) client-ip=2620:137:e000::1:20;
Message-ID: <6ef58f1f-ee8a-b060-6fda-d1388b3ede6d@foss.st.com>
Date:   Tue, 28 Jun 2022 19:01:42 +0200
MIME-Version: 1.0
User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:91.0) Gecko/20100101
 Thunderbird/91.9.1
Subject: Re: [PATCH 1/4] dt-bindings: usb: typec: add bindings for stm32g0
 controller
Content-Language: en-US
To:     Krzysztof Kozlowski <krzysztof.kozlowski@linaro.org>,
        <robh+dt@kernel.org>, <heikki.krogerus@linux.intel.com>,
        <gregkh@linuxfoundation.org>
CC:     <krzysztof.kozlowski+dt@linaro.org>, <devicetree@vger.kernel.org>,
        <linux-usb@vger.kernel.org>, <linux-kernel@vger.kernel.org>,
        <linux-stm32@st-md-mailman.stormreply.com>,
        <amelie.delaunay@foss.st.com>, <alexandre.torgue@foss.st.com>
References: <20220624155413.399190-1-fabrice.gasnier@foss.st.com>
 <20220624155413.399190-2-fabrice.gasnier@foss.st.com>
 <ddb0e946-c955-1404-c1cd-c2548f34ec35@linaro.org>
 <845d6817-d2e4-7925-f7f5-da1102514636@foss.st.com>
 <286633b2-43d2-655e-b3f1-54bf5c7a4a21@linaro.org>
From:   Fabrice Gasnier <fabrice.gasnier@foss.st.com>
In-Reply-To: <286633b2-43d2-655e-b3f1-54bf5c7a4a21@linaro.org>
Content-Type: text/plain; charset="UTF-8"
Content-Transfer-Encoding: 7bit
Precedence: bulk

On 6/28/22 12:28, Krzysztof Kozlowski wrote:
> On 27/06/2022 16:21, Fabrice Gasnier wrote:
>> On 6/24/22 18:16, Krzysztof Kozlowski wrote:
>>> On 24/06/2022 17:54, Fabrice Gasnier wrote:
>>>> This patch adds DT schema documentation for the STM32G0 Type-C controller.
>>>
>>> No "This patch"
>>
>> Hi Krzysztof,
>>
>> ack,
>>
>>>
>>> https://elixir.bootlin.com/linux/v5.17.1/source/Documentation/process/submitting-patches.rst#L95
>>>
>>>> STM32G0 provides an integrated USB Type-C and power delivery interface.
>>>> It can be programmed with a firmware to handle UCSI protocol over I2C
>>>> interface. A GPIO is used as an interrupt line.
>>>> It may be used as a wakeup source, so use optional "wakeup-source" and
>>>> "power-domains" properties to support wakeup.
>>>>
>>>> Signed-off-by: Fabrice Gasnier <fabrice.gasnier@foss.st.com>
>>>> ---
>>>>  .../bindings/usb/st,typec-stm32g0.yaml        | 83 +++++++++++++++++++
>>>>  1 file changed, 83 insertions(+)
>>>>  create mode 100644 Documentation/devicetree/bindings/usb/st,typec-stm32g0.yaml
>>>>
>>>> diff --git a/Documentation/devicetree/bindings/usb/st,typec-stm32g0.yaml b/Documentation/devicetree/bindings/usb/st,typec-stm32g0.yaml
>>>> new file mode 100644
>>>> index 0000000000000..b2729bd015a1a
>>>> --- /dev/null
>>>> +++ b/Documentation/devicetree/bindings/usb/st,typec-stm32g0.yaml
>>>> @@ -0,0 +1,83 @@
>>>> +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
>>>> +%YAML 1.2
>>>> +---
>>>> +$id: "http://devicetree.org/schemas/usb/st,typec-stm32g0.yaml#"
>>>> +$schema: "http://devicetree.org/meta-schemas/core.yaml#"
>>>
>>> No quotes.
>>
>> ack,
>>
>>>
>>>> +
>>>> +title: STMicroelectronics STM32G0 Type-C controller bindings
>>>
>>> s/bindings//
>>
>> ack,
>>
>>>
>>>> +
>>>> +description: |
>>>> +  The STM32G0 MCU can be programmed to control Type-C connector(s) through I2C
>>>> +  typically using the UCSI protocol over I2C, with a dedicated alert
>>>> +  (interrupt) pin.
>>>> +
>>>> +maintainers:
>>>> +  - Fabrice Gasnier <fabrice.gasnier@foss.st.com>
>>>> +
>>>> +properties:
>>>> +  compatible:
>>>> +    const: st,stm32g0-typec
>>>> +
>>>> +  reg:
>>>> +    maxItems: 1
>>>> +
>>>> +  interrupts:
>>>> +    maxItems: 1
>>>> +
>>>> +  connector:
>>>> +    type: object> +    allOf:
>>>> +      - $ref: ../connector/usb-connector.yaml#
>>>
>>> Full path, so /schemas/connector/...
>>>
>>> unevaluatedProperties: false

Hi Krzysztof,

I Just figured out usb-connector schema has "additionalProperties:
true". Adding "unevaluatedProperties: false" here seem to be useless.
At least at my end, this make any dummy property added in the example
below to be validated without error by the schema.

Should this be updated in usb-connector.yaml instead ?

Shall I omit it here in the end ?

>>
>> ack,
>>
>>>
>>>> +
>>>> +  firmware-name:
>>>> +    description: |
>>>> +      Should contain the name of the default firmware image
>>>> +      file located on the firmware search path
>>>> +
>>>> +  wakeup-source: true
>>>> +  power-domains: true
>>>
>>> maxItems
>>
>> Do you mean maxItems regarding the "power-domains" property ?
> 
> Yes.
> 
>> This will depend on the user platform, where it's used as an I2C device.
>> So I'm not sure this can / should be specified here.
>> Could please you clarify ?
> 
> Then maybe this property is not valid here. Power domains usually are
> used for blocks of a SoC, having common power source and power gating.
> In your case it looks much more like a regulator supply.

This property is used in our implementation to refer to SOC PM domain
for GPIO that is used to wakeup the system. This isn't only a regulator,
this PM domain serves various IPs such as I2C, GPIO, UART... (it manages
regulator and clocks used in low power).

I can limit to 1 item if this is fine for you ?

e.g. maxItems: 1

> 
>>
>>>
>>>> +
>>>> +required:
>>>> +  - compatible
>>>> +  - reg
>>>> +  - interrupts
>>>> +
>>>> +additionalProperties: false
>>>> +
>>>> +examples:
>>>> +  - |
>>>> +    #include <dt-bindings/interrupt-controller/irq.h>
>>>> +    i2c5 {
>>>
>>> Just "i2c"
>>
>> ack,
>>
>>>
>>>> +      #address-cells = <1>;
>>>> +      #size-cells = <0>;
>>>> +
>>>> +      stm32g0@53 {
>>>
>>> Generic node name describing class of the device.
>>
>>
>> I wasn't aware of generic node name for an I2C device (not talking of
>> the controller). I may have missed it.
>>
>> Could you please clarify ?
> 
> The class of a device is not a I2C device. I2C is just a bus. For
> example the generic name for Power Management IC connected over I2C
> (quite common case) is "pmic".
> 
> For USB HCD controllers the generic name is "usb". For USB
> ports/connectors this is "connector". So what is your hardware?
> "interface" is a bit too unspecific to figure it out.

Thanks, I better understand your point now.

A common definition for the hardware here could be "USB Type-C PD
controller". I'll improve this schema title by the way.

I had a quick look in various .dts files. I could find mainly:
- typec-portc@hh
- usb-typec@hh
- typec@hh

Not sure if this has already been discussed in other reviews, it lacks
the "controller" idea in the naming IMHO.
Perhaps something like "typec-pd-controller" or
"usb-typec-pd-controller" could be used here ?

Otherwise, I could adopt the shortest "typec" name if it's fine for you ?

> 
>>
>>>
>>>> +        compatible = "st,stm32g0-typec";
>>>> +        reg = <0x53>;
>>>> +        /* Alert pin on GPIO PE12 */
>>>> +        interrupts = <12 IRQ_TYPE_EDGE_FALLING>;
>>>> +        interrupt-parent = <&gpioe>;
>>>> +
>>>> +        /* Example with one type-C connector */
>>>> +        connector {
>>>> +          compatible = "usb-c-connector";
>>>> +          label = "USB-C";
>>>> +
>>>> +          port {
>>>
>>> This does not look like proper schema of connector.yaml.
>>
>> This refers to graph.yaml [1], where similar example is seen [2].
>>
>> https://github.com/devicetree-org/dt-schema/blob/main/dtschema/schemas/graph.yaml#L79
>>
>> https://github.com/devicetree-org/dt-schema/blob/main/dtschema/schemas/graph.yaml#L207
> 
> Just look at the usb-conector schema. It's different. You miss ports.
> Maybe other properties as well.


(I may miss something, and got confused around port/ports earlier)
The graph properties seems to allow both the 'port' and 'ports' syntax
thanks to the graph definition.
The "port" syntax is also used in other typec controller schemas.

There's only one port in this example. Of course other example could use
two or more ports (like for USB HS / SS / aux) which would require using
the "ports" node (with port@0/1/2 childs).

I can adopt the "ports" node if you prefer. As I see it just doesn't
bring much in the current example (The only drawback is this adds one
indentation/node level w.r.t. the bellow example, so not a big deal).

Please advise,

Thanks for reviewing,
Best Regards,
Fabrice

> 
>>
>>     device-1 {
>>         port {
>>             device_1_output: endpoint {
>>                 remote-endpoint = <&device_2_input>;
>>             };
>>         };
>>     };
>>     device-2 {
>>         port {
>>             device_2_input: endpoint {
>>                 remote-endpoint = <&device_1_output>;
>>             };
>>         };
>>     };
>>
>>
>> Could you please clarify this point too ?
>>
>>>
>>>> +            con_usb_c_ep: endpoint {
>>>> +              remote-endpoint = <&usbotg_hs_ep>;
>>>> +            };
>>>> +          };
>>>> +        };
>>>> +      };
>>>> +    };
>>>> +
>>>> +    usbotg_hs {
>>>
>>> Generic node names, no underscores in node names.
>>
>> ack, I guess you'd recommend "usb" here. I'll update it.
> 
> Yes, looks like usb.
> 
> 
> Best regards,
> Krzysztof