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;
MIME-Version: 1.0
References: <1658123163-10039-1-git-send-email-u0084500@gmail.com>
 <1658123163-10039-4-git-send-email-u0084500@gmail.com> <20220718180441.1363d2a6@jic23-huawei>
In-Reply-To: <20220718180441.1363d2a6@jic23-huawei>
From:   ChiYuan Huang <u0084500@gmail.com>
Date:   Tue, 19 Jul 2022 14:12:21 +0800
Message-ID: <CADiBU3_Nb4Rio3Z7L-907TB1Gvq6d5_GSP6Av5ZjHzhoDtcEZA@mail.gmail.com>
Subject: Re: [PATCH v7 3/3] Documentation: ABI: testing: rtq6056: Update ABI docs
To:     Jonathan Cameron <jic23@kernel.org>
Cc:     Rob Herring <robh+dt@kernel.org>,
        Krzysztof Kozlowski <krzysztof.kozlowski+dt@linaro.org>,
        Lars-Peter Clausen <lars@metafoo.de>,
        cy_huang <cy_huang@richtek.com>,
        linux-iio <linux-iio@vger.kernel.org>,
        lkml <linux-kernel@vger.kernel.org>,
        "open list:OPEN FIRMWARE AND FLATTENED DEVICE TREE BINDINGS" 
        <devicetree@vger.kernel.org>
Content-Type: text/plain; charset="UTF-8"
Content-Transfer-Encoding: quoted-printable
Precedence: bulk

Jonathan Cameron <jic23@kernel.org> =E6=96=BC 2022=E5=B9=B47=E6=9C=8819=E6=
=97=A5 =E9=80=B1=E4=BA=8C =E5=87=8C=E6=99=A812:54=E5=AF=AB=E9=81=93=EF=BC=
=9A
>
> On Mon, 18 Jul 2022 13:46:03 +0800
> cy_huang <u0084500@gmail.com> wrote:
>
> > From: ChiYuan Huang <cy_huang@richtek.com>
> >
> > Add documentation for the usage of voltage channel integration time.
> >
> > Signed-off-by: ChiYuan Huang <cy_huang@richtek.com>
> > ---
> >  Documentation/ABI/testing/sysfs-bus-iio | 10 ++++++++++
> >  1 file changed, 10 insertions(+)
> >
> > diff --git a/Documentation/ABI/testing/sysfs-bus-iio b/Documentation/AB=
I/testing/sysfs-bus-iio
> > index d4ccc68..1f7d327 100644
> > --- a/Documentation/ABI/testing/sysfs-bus-iio
> > +++ b/Documentation/ABI/testing/sysfs-bus-iio
> > @@ -2030,3 +2030,13 @@ Description:
> >               Available range for the forced calibration value, express=
ed as:
> >
> >               - a range specified as "[min step max]"
> > +
> > +What:                /sys/bus/iio/devices/iio:deviceX/in_voltageY_inte=
gration_time
> > +KernelVersion:       5.20
> > +Contact:     linux-iio@vger.kernel.org
> > +Description:
> > +             For voltage sensing hardware, there may be different time=
 between
> > +             channel conversion and sample update. 'Integration time' =
is used to
> > +             specify the channel internal conversion time. And sample =
update
> > +             interval is equal to average sample count multiple integr=
ation time.
> > +             Unit as microsecond.
>
> Whilst I did suggest moving this to this file, I also suggested that it w=
as the
> wrong interface to use.  For similar cases we've used in_voltageY_samplin=
g_frequency
> in the past because this isn't really an integration time, but rather a r=
eflection of
> a bunch of other stuff that makes up the conversion time.  In IIO we chos=
e a long
> time ago to use 1/conversion_time as the exposed interface =3D=3D samplin=
g_frequency
>
> So, unless there is a strong reason to do otherwise, drop the overall sam=
pling_frequency
> attribute and use per channel ones instead.  Then update the main documen=
tation
> to make this usecase clear. Something in the block
> https://elixir.bootlin.com/linux/latest/source/Documentation/ABI/testing/=
sysfs-bus-iio#L89
> like adding the in_voltageY_sampling_frequency entry to the What: list an=
d a
> sentence at the end that says something like:
>
> "Some devices have separate controls of sampling frequency for individual=
 channels.
> If multiple channels are enabled in a scan, then the sampling_frequency o=
f the the
> scan may be computed from the per channel sampling_frequencies."
>
From my case, I need to specify
in_voltageX_sampling_frequency/in_powerY_sampling_frequency/
in_currentZ_sampling_frequency.

And describe all in the same sentence.
Can I directly copy the sentence that you described above?
I read the comment. The sentence that you wrote seems more generic.

If any misunderstanding, please correct me.
> Not something to put in the documentation, but for devices which do simul=
taneous sampling
> it is very unlikely we'll have per channel sampling frequencies so there =
isn't an
> ambiguity. The alternative we 'could' consider is to allow both overall s=
ampling_frequency
> and per channel in_voltageY_sampling_frequency but that is a bad idea bec=
ause the
> ABI (and most userspace software) assumes that more specific attributes o=
verride the
> values of more generic ones (rather than them having different meanings a=
s would be
> the case here).
>
> Jonathan