[v4,2/8] dt-bindings: adc: axi-adc: deprecate 'adi,adc-dev'

'adi,adc-dev' is now deprecated and must not be used anymore. Hence,
also remove it from being required.

The reason why it's being deprecated is because the axi-adc CORE is now
an IIO service provider hardware (IIO backends) for consumers to make use
of. Before, the logic with 'adi,adc-dev' was the opposite (it was kind
of consumer referencing other nodes/devices) and that proved to be wrong
and to not scale.

Now, IIO consumers of this hardware are expected to reference it using the
io-backends property.

Signed-off-by: Nuno Sa <nuno.sa@analog.com>
---
 Documentation/devicetree/bindings/iio/adc/adi,axi-adc.yaml | 4 +---
 1 file changed, 1 insertion(+), 3 deletions(-)

On Wed, 20 Dec 2023 16:34:05 +0100
Nuno Sa <nuno.sa@analog.com> wrote:

> 'adi,adc-dev' is now deprecated and must not be used anymore. Hence,
> also remove it from being required.

With my 'specifications language' brain engaged (also know as pedantic)
I think this is a 'should' not a 'must' case. You aren't breaking
backwards compatibility just advising moving to the newer / better interface.


> 
> The reason why it's being deprecated is because the axi-adc CORE is now
> an IIO service provider hardware (IIO backends) for consumers to make use
> of. Before, the logic with 'adi,adc-dev' was the opposite (it was kind
> of consumer referencing other nodes/devices) and that proved to be wrong
> and to not scale.
> 
> Now, IIO consumers of this hardware are expected to reference it using the
> io-backends property.
> 
> Signed-off-by: Nuno Sa <nuno.sa@analog.com>
> ---
>  Documentation/devicetree/bindings/iio/adc/adi,axi-adc.yaml | 4 +---
>  1 file changed, 1 insertion(+), 3 deletions(-)
> 
> diff --git a/Documentation/devicetree/bindings/iio/adc/adi,axi-adc.yaml b/Documentation/devicetree/bindings/iio/adc/adi,axi-adc.yaml
> index 9996dd93f84b..835b40063343 100644
> --- a/Documentation/devicetree/bindings/iio/adc/adi,axi-adc.yaml
> +++ b/Documentation/devicetree/bindings/iio/adc/adi,axi-adc.yaml
> @@ -39,12 +39,12 @@ properties:
>      $ref: /schemas/types.yaml#/definitions/phandle
>      description:
>        A reference to a the actual ADC to which this FPGA ADC interfaces to.
> +    deprecated: true
>  
>  required:
>    - compatible
>    - dmas
>    - reg
> -  - adi,adc-dev

Dropping it from required is fine, but do we have a new condition where one or the other
should be required?  If so good to add the dt-binding magic to enforce that. Look
for a oneOf combined with required. There are a few IIO examples of this either or
type required. You may want to then enforce that both are not provided though I
guess we perhaps don't care - the driver will just prioritise one approach over the other.

Jonathan


>  
>  additionalProperties: false
>  
> @@ -55,7 +55,5 @@ examples:
>          reg = <0x44a00000 0x10000>;
>          dmas = <&rx_dma 0>;
>          dma-names = "rx";
> -
> -        adi,adc-dev = <&spi_adc>;
>      };
>  ...
>

On Thu, 2023-12-21 at 17:25 +0000, Jonathan Cameron wrote:
> On Wed, 20 Dec 2023 16:34:05 +0100
> Nuno Sa <nuno.sa@analog.com> wrote:
> 
> > 'adi,adc-dev' is now deprecated and must not be used anymore. Hence,
> > also remove it from being required.
> 
> With my 'specifications language' brain engaged (also know as pedantic)
> I think this is a 'should' not a 'must' case. You aren't breaking
> backwards compatibility just advising moving to the newer / better interface.
> 

Well, you surely know better than me as a native speaker :)

> 
> > 
> > The reason why it's being deprecated is because the axi-adc CORE is now
> > an IIO service provider hardware (IIO backends) for consumers to make use
> > of. Before, the logic with 'adi,adc-dev' was the opposite (it was kind
> > of consumer referencing other nodes/devices) and that proved to be wrong
> > and to not scale.
> > 
> > Now, IIO consumers of this hardware are expected to reference it using the
> > io-backends property.
> > 
> > Signed-off-by: Nuno Sa <nuno.sa@analog.com>
> > ---
> >  Documentation/devicetree/bindings/iio/adc/adi,axi-adc.yaml | 4 +---
> >  1 file changed, 1 insertion(+), 3 deletions(-)
> > 
> > diff --git a/Documentation/devicetree/bindings/iio/adc/adi,axi-adc.yaml
> > b/Documentation/devicetree/bindings/iio/adc/adi,axi-adc.yaml
> > index 9996dd93f84b..835b40063343 100644
> > --- a/Documentation/devicetree/bindings/iio/adc/adi,axi-adc.yaml
> > +++ b/Documentation/devicetree/bindings/iio/adc/adi,axi-adc.yaml
> > @@ -39,12 +39,12 @@ properties:
> >      $ref: /schemas/types.yaml#/definitions/phandle
> >      description:
> >        A reference to a the actual ADC to which this FPGA ADC interfaces to.
> > +    deprecated: true
> >  
> >  required:
> >    - compatible
> >    - dmas
> >    - reg
> > -  - adi,adc-dev
> 
> Dropping it from required is fine, but do we have a new condition where one or the
> other
> should be required?  If so good to add the dt-binding magic to enforce that. Look
> for a oneOf combined with required. There are a few IIO examples of this either or
> type required. You may want to then enforce that both are not provided though I
> guess we perhaps don't care - the driver will just prioritise one approach over the
> other.
> 

Hmm, the thing is that io-backends is applied in the frontend device (so other
binding) and in here we should only have the adi,adc-dev which is now deprecated so
I'm not sure how that would look like?

I think new users of the deprecated property are very unlikely unless they choose to
ignore the deprecated warning. As for old users (if they add the new one and don't
remove this one, the new one will have priority). But I'm still confident there are
no users of this out there :)


- Nuno Sá