Re: [v2 06/10] iio: document bno055 private sysfs attributes

From: Jonathan Cameron <jic23@kernel.org>
To: Andrea Merello <andrea.merello@gmail.com>
Cc: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>,
	linux-iio <linux-iio@vger.kernel.org>,
	linux-kernel <linux-kernel@vger.kernel.org>,
	devicetree <devicetree@vger.kernel.org>,
	Lars-Peter Clausen <lars@metafoo.de>,
	Rob Herring <robh+dt@kernel.org>,
	Andy Shevchenko <andy.shevchenko@gmail.com>,
	Matt Ranostay <matt.ranostay@konsulko.com>,
	Alexandru Ardelean <ardeleanalex@gmail.com>,
	Jacopo Mondi <jacopo@jmondi.org>,
	Andrea Merello <andrea.merello@iit.it>
Subject: Re: [v2 06/10] iio: document bno055 private sysfs attributes
Date: Sat, 15 Jan 2022 15:27:49 +0000	[thread overview]
Message-ID: <20220115152749.173b7172@jic23-huawei> (raw)
In-Reply-To: <CAN8YU5NO5mcrPa5ZCB3XnAb=3N3cyXZUT=gH5G+EbnM-En0a3Q@mail.gmail.com>

On Tue, 4 Jan 2022 12:42:40 +0100
Andrea Merello <andrea.merello@gmail.com> wrote:

> Sorry for the huge delay...

No problem though I may have forgotten some of the discussion!

> 
> > There is still a units question though.  Should we express the ranges
> > in _processed or _raw units?  Or do we make it explicit and call it
> > rangeprocessed for example?  For some devices the range will naturally
> > be expressed as the range of ADC raw values, so there is definite room
> > for confusion if we don't make it clear in the name.
> >
> > I'm open to other suggestions of how we name this to avoid falling into
> > any heffalump traps.  
> 
> You are right: this might lead to confusion.. Making it explicit in
> the name seems a good idea.
> 
> I've looked at other iio sysfs attributes in the DOC.  It seems  that
> "thesh" and "roc" attributes allows for both preprocessed and raw
> data: I found e.g. "<type>[Y][_name]_<raw|input>_thresh_value", but
> the related "what" entries written above all seem to omit both "_raw"
> and "_input"; I don't understand why.

Excellent point.  That documentation is garbage.  Events are meant
to pick it up implicitly from the related channel _raw or _input.
I don't remember them ever having raw or input in their naming but
it's possible they did right at the beginning before the ABI was anywhere
near stable.  Gah. I dread to think how long that that has been wrong.

> 
> In any case, maybe we can stick to that already-existent naming schema?

It doesn't exist really the docs are wrong.  

> 
> Assuming the pattern is correct, then wouldn't it be
> "in_accel_raw_range"  (or "in_accel_x_raw_range", in case it could
> have different values for each axis) or "in_accel_input_range" in case
> range applies to preprocessed vals, etc ?

Tricky corner but I'd go with no, because the pattern is

direction_type_infotype

and in this case the infotype is rangeraw. We've not been totally consistent
on whether we allow spaces in infotype or not.  Intially we always did but then
some of the userspace folks asked us to stop doing so because it requires
all userspace software to have an explicit list rather than just adding
controls to some GUI based on generic parsing.  Hohum. Historical decisions that
lead to messy interfaces... *sigh*

Nearest to what you have here though are peak_raw and mean_raw
though those are odd in of themselves in that they are basically special forms
of _raw rather than something else that is in _raw units...

So I think range_raw postfix is the best bet.

Jonathan

>

> 
> Andrea