Re: [PATCH v2 2/6] dt-bindings: interconnect: Add property to set BCM TCS wait behavior

[Mike Tipton]

On 7/10/2020 9:31 AM, Rob Herring wrote:
> On Thu, Jul 09, 2020 at 06:56:48PM -0700, Mike Tipton wrote:
> > Add "qcom,tcs-wait" property to set which TCS should wait for completion
> > when triggering.
> >
> > Signed-off-by: Mike Tipton <mdtipton@xxxxxxxxxxxxxx>
> > ---
> >   .../bindings/interconnect/qcom,bcm-voter.yaml       | 13 +++++++++++++
> >   1 file changed, 13 insertions(+)
> >
> > diff --git a/Documentation/devicetree/bindings/interconnect/qcom,bcm-voter.yaml b/Documentation/devicetree/bindings/interconnect/qcom,bcm-voter.yaml
> > index 5971fc1df08d..f0c3d6b01831 100644
> > --- a/Documentation/devicetree/bindings/interconnect/qcom,bcm-voter.yaml
> > +++ b/Documentation/devicetree/bindings/interconnect/qcom,bcm-voter.yaml
> > @@ -21,6 +21,16 @@ properties:
> >       enum:
> >         - qcom,bcm-voter
> >   
> > +  qcom,tcs-wait:
> > +    description: |
> > +      Optional mask of which TCSs (Triggered Command Sets) wait for completion
> > +      upon triggering. In most cases, it's necessary to wait in both the AMC
> > +      and WAKE sets to ensure resources are available before use. If a specific
> > +      RSC and its use cases can ensure sufficient delay by other means, then
> > +      this can be overridden to reduce latencies.
>
> I have no idea what any of this means to provide any meaningful comment.
>
> > +    $ref: /schemas/types.yaml#/definitions/uint32
> > +    default: QCOM_ICC_TAG_ACTIVE_ONLY
>
> Can't use defines here.

What's the recommended alternative? The meaning isn't obvious as a raw 
number (3). We expect the defines to be used in the dt files themselves 
(see example below). Is this just a restriction for the `default` 
documentation specifically? I could just mention the default behavior in 
the description I suppose, but that seems to defeat the purpose of 
having a separate `default` key.

> > +
> >   required:
> >     - compatible
> >   
> > @@ -39,7 +49,10 @@ examples:
> >     # as defined in Documentation/devicetree/bindings/soc/qcom/rpmh-rsc.txt
> >     - |
> >   
> > +    #include <dt-bindings/interconnect/qcom,icc.h>
> > +
> >       disp_bcm_voter: bcm_voter {
> >           compatible = "qcom,bcm-voter";
> > +        qcom,tcs-wait = <QCOM_ICC_TAG_AMC>;
> >       };
> >   ...
> > --
> > The Qualcomm Innovation Center, Inc. is a member of the Code Aurora Forum,
> > a Linux Foundation Collaborative Project