[PATCH v2 RESEND 1/5] dt-bindings: soc: samsung: Add Exynos USI bindings

[Sam Protsenko]

On Sat, 4 Dec 2021 at 13:28, Krzysztof Kozlowski
<krzysztof.kozlowski at canonical.com> wrote:
>
> On 03/12/2021 21:40, Rob Herring wrote:
> > On Fri, Dec 3, 2021 at 1:36 PM Sam Protsenko <semen.protsenko at linaro.org> wrote:
> >>
> >> On Tue, 30 Nov 2021 at 21:31, Rob Herring <robh at kernel.org> wrote:
> >>>
> >>> On Tue, Nov 30, 2021 at 01:13:21PM +0200, Sam Protsenko wrote:
> >>>> Add constants for choosing USIv2 configuration mode in device tree.
> >>>> Those are further used in USI driver to figure out which value to write
> >>>> into SW_CONF register. Also document USIv2 IP-core bindings.
> >>>>
> >>>> Signed-off-by: Sam Protsenko <semen.protsenko at linaro.org>
> >>>> ---
> >>>> Changes in v2:
> >>>>   - Combined dt-bindings doc and dt-bindings header patches
> >>>>   - Added i2c node to example in bindings doc
> >>>>   - Added mentioning of shared internal circuits
> >>>>   - Added USI_V2_NONE value to bindings header
> >>>>
> >>>>  .../bindings/soc/samsung/exynos-usi.yaml      | 135 ++++++++++++++++++
> >>>>  include/dt-bindings/soc/samsung,exynos-usi.h  |  17 +++
> >>>>  2 files changed, 152 insertions(+)
> >>>>  create mode 100644 Documentation/devicetree/bindings/soc/samsung/exynos-usi.yaml
> >>>>  create mode 100644 include/dt-bindings/soc/samsung,exynos-usi.h
> >>>>
> >>>> diff --git a/Documentation/devicetree/bindings/soc/samsung/exynos-usi.yaml b/Documentation/devicetree/bindings/soc/samsung/exynos-usi.yaml
> >>>> new file mode 100644
> >>>> index 000000000000..a822bc62b3cd
> >>>> --- /dev/null
> >>>> +++ b/Documentation/devicetree/bindings/soc/samsung/exynos-usi.yaml
> >>>> @@ -0,0 +1,135 @@
> >>>> +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
> >>>> +%YAML 1.2
> >>>> +---
> >>>> +$id: http://devicetree.org/schemas/soc/samsung/exynos-usi.yaml#
> >>>> +$schema: http://devicetree.org/meta-schemas/core.yaml#
> >>>> +
> >>>> +title: Samsung's Exynos USI (Universal Serial Interface) binding
> >>>> +
> >>>> +maintainers:
> >>>> +  - Sam Protsenko <semen.protsenko at linaro.org>
> >>>> +  - Krzysztof Kozlowski <krzysztof.kozlowski at canonical.com>
> >>>> +
> >>>> +description: |
> >>>> +  USI IP-core provides selectable serial protocol (UART, SPI or High-Speed I2C).
> >>>> +  USI shares almost all internal circuits within each protocol, so only one
> >>>> +  protocol can be chosen at a time. USI is modeled as a node with zero or more
> >>>> +  child nodes, each representing a serial sub-node device. The mode setting
> >>>> +  selects which particular function will be used.
> >>>> +
> >>>> +  Refer to next bindings documentation for information on protocol subnodes that
> >>>> +  can exist under USI node:
> >>>> +
> >>>> +  [1] Documentation/devicetree/bindings/serial/samsung_uart.yaml
> >>>> +  [2] Documentation/devicetree/bindings/i2c/i2c-exynos5.txt
> >>>> +  [3] Documentation/devicetree/bindings/spi/spi-samsung.txt
> >>>> +
> >>>> +properties:
> >>>> +  $nodename:
> >>>> +    pattern: "^usi@[0-9a-f]+$"
> >>>> +
> >>>> +  compatible:
> >>>> +    const: samsung,exynos-usi-v2
> >>>
> >>> Use SoC based compatibles.
> >>>
> >>
> >> In this particular case, I'd really prefer to have it like this. Most
> >> likely we'll only have USIv1 and USIv1 in the end, and I think that
> >> would be more clear to have USI version in compatible, rather than SoC
> >> name. Please let me know if you have a strong opinion on this one --
> >> if so I'll re-send.
> >
> > Fine if you have some evidence the ratio of versions to SoC are much
> > more than 1:1 and the versions correspond to something (IOW, you
> > aren't making them up).
> >
> > We went down the version # path with QCom and in the end about every
> > SoC had a different version.
>
> I am against v1/v2 versions. The documentation in Samsung was always
> poor in that matter. There were mistakes or confusions so it wasn't
> always obvious which IP-block version comes with which SoC. Not
> mentioning that several contributors do not have access to Samsung
> datasheets and they submit code based on GPL compliance packages, so
> they won't know which version they have for given SoC.
>
> OTOH there is no single benefit of using USI v1/v2, except "liking".
>

Ok, I'll do as you ask. In general I agree, but I still think in this
particular case using "usi" in compatible is feasible. Anyway, I have
no strong opinion on this one, and it's easy to rework.

> Best regards,
> Krzysztof