[PATCH 0/4] iio: missing ABI documentation

[PATCH 0/4] iio: missing ABI documentation

[Peter Meerwald]

Hi,

this tried to document some ABI in use for a long time but never
properly documented; I think it is beneficial to say what things
are supposed to be even while certain existing drivers may violate
it

this is meant as an RFC

cheers, p.

Peter Meerwald (4):
  iio: Add intensity including ir and both modifiers to ABI
    documentation ex-post
  iio: Add ABI documentation for illuminance
  iio: Add ABI documentation for proximity
  iio: Fix spelling of illuminance in gp2ap020a00f driver

 Documentation/ABI/testing/sysfs-bus-iio | 29 +++++++++++++++++++++++++++++
 drivers/iio/light/gp2ap020a00f.c        |  8 ++++----
 2 files changed, 33 insertions(+), 4 deletions(-)

-- 
1.9.1

[PATCH 1/4] iio: Add intensity including ir and both modifiers to ABI documentation ex-post

[Peter Meerwald]

intensity has been in use for a long time but never documented
it is beneficial to document what this is supposed to be

Signed-off-by: Peter Meerwald <pmeerw@pmeerw.net>
---
 Documentation/ABI/testing/sysfs-bus-iio | 10 ++++++++++
 1 file changed, 10 insertions(+)

diff --git a/Documentation/ABI/testing/sysfs-bus-iio b/Documentation/ABI/testing/sysfs-bus-iio
index ca3d3b7..9669c1f 100644
--- a/Documentation/ABI/testing/sysfs-bus-iio
+++ b/Documentation/ABI/testing/sysfs-bus-iio
@@ -895,6 +895,16 @@ Description:
 		on-chip EEPROM. After power-up or chip reset the device will
 		automatically load the saved configuration.
 
+What:		/sys/.../iio:deviceX/in_intensityY_raw
+What:		/sys/.../iio:deviceX/in_intensityY_ir_raw
+What:		/sys/.../iio:deviceX/in_intensityY_both_raw
+KernelVersion:	3.4
+Contact:	linux-iio@vger.kernel.org
+Description:
+		Unit-less light intensity. Modifiers both and ir indicate
+		that measurements contains visible and infrared light
+		components or just infrared light, respectively.
+
 What:		/sys/.../iio:deviceX/in_intensity_red_integration_time
 What:		/sys/.../iio:deviceX/in_intensity_green_integration_time
 What:		/sys/.../iio:deviceX/in_intensity_blue_integration_time
-- 
1.9.1

[PATCH 2/4] iio: Add ABI documentation for illuminance

[Peter Meerwald]

has been in use for a long time, but never documented;
state that this measurement should be in lux (drivers may feel
different about this)

Signed-off-by: Peter Meerwald <pmeerw@pmeerw.net>
---
 Documentation/ABI/testing/sysfs-bus-iio | 9 +++++++++
 1 file changed, 9 insertions(+)

diff --git a/Documentation/ABI/testing/sysfs-bus-iio b/Documentation/ABI/testing/sysfs-bus-iio
index 9669c1f..a9757dc 100644
--- a/Documentation/ABI/testing/sysfs-bus-iio
+++ b/Documentation/ABI/testing/sysfs-bus-iio
@@ -895,6 +895,15 @@ Description:
 		on-chip EEPROM. After power-up or chip reset the device will
 		automatically load the saved configuration.
 
+What:		/sys/.../iio:deviceX/in_illuminanceY_input
+What:		/sys/.../iio:deviceX/in_illuminanceY_raw
+What:		/sys/.../iio:deviceX/in_illuminanceY_mean_raw
+KernelVersion:	3.4
+Contact:	linux-iio@vger.kernel.org
+Description:
+		Illuminance measurement, units after application of scale
+		and offset are lux.
+
 What:		/sys/.../iio:deviceX/in_intensityY_raw
 What:		/sys/.../iio:deviceX/in_intensityY_ir_raw
 What:		/sys/.../iio:deviceX/in_intensityY_both_raw
-- 
1.9.1

[PATCH 3/4] iio: Add ABI documentation for proximity

[Peter Meerwald]

has been in use for a long time, but never documented
proximity is unit-less, except otherwise stated, see e.g.
the as3935 driver where it is meter

Signed-off-by: Peter Meerwald <pmeerw@pmeerw.net>
---
 Documentation/ABI/testing/sysfs-bus-iio | 10 ++++++++++
 1 file changed, 10 insertions(+)

diff --git a/Documentation/ABI/testing/sysfs-bus-iio b/Documentation/ABI/testing/sysfs-bus-iio
index a9757dc..ed202b3 100644
--- a/Documentation/ABI/testing/sysfs-bus-iio
+++ b/Documentation/ABI/testing/sysfs-bus-iio
@@ -895,6 +895,16 @@ Description:
 		on-chip EEPROM. After power-up or chip reset the device will
 		automatically load the saved configuration.
 
+What:		/sys/.../iio:deviceX/in_proximity_raw
+What:		/sys/.../iio:deviceX/in_proximity_input
+What:		/sys/.../iio:deviceX/in_proximityY_raw
+KernelVersion:	3.4
+Contact:	linux-iio@vger.kernel.org
+Description:
+		Unit-less proximity measurement indicating that some
+		object is near the sensor, usually be observing
+		reflectivity of infrared or ultrasound emitted.
+
 What:		/sys/.../iio:deviceX/in_illuminanceY_input
 What:		/sys/.../iio:deviceX/in_illuminanceY_raw
 What:		/sys/.../iio:deviceX/in_illuminanceY_mean_raw
-- 
1.9.1

[PATCH 4/4] iio: Fix spelling of illuminance in gp2ap020a00f driver

[Peter Meerwald]

Cc: Jacek Anaszewski <j.anaszewski@samsung.com>
Signed-off-by: Peter Meerwald <pmeerw@pmeerw.net>
---
 drivers/iio/light/gp2ap020a00f.c | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/drivers/iio/light/gp2ap020a00f.c b/drivers/iio/light/gp2ap020a00f.c
index 5ea4a03..04bdb85 100644
--- a/drivers/iio/light/gp2ap020a00f.c
+++ b/drivers/iio/light/gp2ap020a00f.c
@@ -5,13 +5,13 @@
  * IIO features supported by the driver:
  *
  * Read-only raw channels:
- *   - illiminance_clear [lux]
- *   - illiminance_ir
+ *   - illuminance_clear [lux]
+ *   - illuminance_ir
  *   - proximity
  *
  * Triggered buffer:
- *   - illiminance_clear
- *   - illiminance_ir
+ *   - illuminance_clear
+ *   - illuminance_ir
  *   - proximity
  *
  * Events:
-- 
1.9.1

Re: [PATCH 1/4] iio: Add intensity including ir and both modifiers to ABI documentation ex-post

[Jonathan Cameron]

On 02/05/14 16:54, Peter Meerwald wrote:
> intensity has been in use for a long time but never documented
> it is beneficial to document what this is supposed to be
>
> Signed-off-by: Peter Meerwald <pmeerw@pmeerw.net>
Oops. I think added intensity in the first place though might have been in the
tsl2563 driver rather than my tsl2561 driver from prehistory of IIO.

Thanks for your work on filling in the gaps!

Applied to the togreg branch of iio.git

J
> ---
>   Documentation/ABI/testing/sysfs-bus-iio | 10 ++++++++++
>   1 file changed, 10 insertions(+)
>
> diff --git a/Documentation/ABI/testing/sysfs-bus-iio b/Documentation/ABI/testing/sysfs-bus-iio
> index ca3d3b7..9669c1f 100644
> --- a/Documentation/ABI/testing/sysfs-bus-iio
> +++ b/Documentation/ABI/testing/sysfs-bus-iio
> @@ -895,6 +895,16 @@ Description:
>   		on-chip EEPROM. After power-up or chip reset the device will
>   		automatically load the saved configuration.
>
> +What:		/sys/.../iio:deviceX/in_intensityY_raw
> +What:		/sys/.../iio:deviceX/in_intensityY_ir_raw
> +What:		/sys/.../iio:deviceX/in_intensityY_both_raw
> +KernelVersion:	3.4
> +Contact:	linux-iio@vger.kernel.org
> +Description:
> +		Unit-less light intensity. Modifiers both and ir indicate
> +		that measurements contains visible and infrared light
> +		components or just infrared light, respectively.
> +
>   What:		/sys/.../iio:deviceX/in_intensity_red_integration_time
>   What:		/sys/.../iio:deviceX/in_intensity_green_integration_time
>   What:		/sys/.../iio:deviceX/in_intensity_blue_integration_time
>

Re: [PATCH 2/4] iio: Add ABI documentation for illuminance

[Jonathan Cameron]

On 02/05/14 16:54, Peter Meerwald wrote:
> has been in use for a long time, but never documented;
> state that this measurement should be in lux (drivers may feel
> different about this)
>
> Signed-off-by: Peter Meerwald <pmeerw@pmeerw.net>
I agree that it should be in Lux.

Note that I was sure this was documented somewhere so went looking.
It was under drivers/staging/iio/Documentation/sysfs-bus-iio-light

Description agrees with yours so this patch is fine, but we should
drop the version in staging in favour of this.
Note that quite a few elements in that staging file are unlikely to
ever make it out of staging as they currently stand!

Thanks and applied to the togreg branch of iio.git

J

> ---
>   Documentation/ABI/testing/sysfs-bus-iio | 9 +++++++++
>   1 file changed, 9 insertions(+)
>
> diff --git a/Documentation/ABI/testing/sysfs-bus-iio b/Documentation/ABI/testing/sysfs-bus-iio
> index 9669c1f..a9757dc 100644
> --- a/Documentation/ABI/testing/sysfs-bus-iio
> +++ b/Documentation/ABI/testing/sysfs-bus-iio
> @@ -895,6 +895,15 @@ Description:
>   		on-chip EEPROM. After power-up or chip reset the device will
>   		automatically load the saved configuration.
>
> +What:		/sys/.../iio:deviceX/in_illuminanceY_input
> +What:		/sys/.../iio:deviceX/in_illuminanceY_raw
> +What:		/sys/.../iio:deviceX/in_illuminanceY_mean_raw
> +KernelVersion:	3.4
> +Contact:	linux-iio@vger.kernel.org
> +Description:
> +		Illuminance measurement, units after application of scale
> +		and offset are lux.
> +
>   What:		/sys/.../iio:deviceX/in_intensityY_raw
>   What:		/sys/.../iio:deviceX/in_intensityY_ir_raw
>   What:		/sys/.../iio:deviceX/in_intensityY_both_raw
>

Re: [PATCH 3/4] iio: Add ABI documentation for proximity

[Jonathan Cameron]

On 02/05/14 16:54, Peter Meerwald wrote:
> has been in use for a long time, but never documented
> proximity is unit-less, except otherwise stated, see e.g.
> the as3935 driver where it is meter
>
> Signed-off-by: Peter Meerwald <pmeerw@pmeerw.net>
Again this is documented in the staging docs.  I'd argue that the _input
form should be used if we are in meters, otherwise if scale free (like it
almost always is) then it should be the _raw form.

Still we can always evolve the docs!

Applied to the togreg branch of iio.git

Thanks,

J
> ---
>   Documentation/ABI/testing/sysfs-bus-iio | 10 ++++++++++
>   1 file changed, 10 insertions(+)
>
> diff --git a/Documentation/ABI/testing/sysfs-bus-iio b/Documentation/ABI/testing/sysfs-bus-iio
> index a9757dc..ed202b3 100644
> --- a/Documentation/ABI/testing/sysfs-bus-iio
> +++ b/Documentation/ABI/testing/sysfs-bus-iio
> @@ -895,6 +895,16 @@ Description:
>   		on-chip EEPROM. After power-up or chip reset the device will
>   		automatically load the saved configuration.
>
> +What:		/sys/.../iio:deviceX/in_proximity_raw
> +What:		/sys/.../iio:deviceX/in_proximity_input
> +What:		/sys/.../iio:deviceX/in_proximityY_raw
> +KernelVersion:	3.4
> +Contact:	linux-iio@vger.kernel.org
> +Description:
> +		Unit-less proximity measurement indicating that some
> +		object is near the sensor, usually be observing
> +		reflectivity of infrared or ultrasound emitted.
> +
>   What:		/sys/.../iio:deviceX/in_illuminanceY_input
>   What:		/sys/.../iio:deviceX/in_illuminanceY_raw
>   What:		/sys/.../iio:deviceX/in_illuminanceY_mean_raw
>

Re: [PATCH 3/4] iio: Add ABI documentation for proximity

[Jonathan Cameron]

On 03/05/14 11:48, Jonathan Cameron wrote:
> On 02/05/14 16:54, Peter Meerwald wrote:
>> has been in use for a long time, but never documented
>> proximity is unit-less, except otherwise stated, see e.g.
>> the as3935 driver where it is meter
>>
>> Signed-off-by: Peter Meerwald <pmeerw@pmeerw.net>
> Again this is documented in the staging docs.  I'd argue that the _input
> form should be used if we are in meters, otherwise if scale free (like it
> almost always is) then it should be the _raw form.
>
> Still we can always evolve the docs!
>
> Applied to the togreg branch of iio.git
Actually had immediate second thoughts on this, I'm going to amend it to
specify that if in _input it should be in meters.

>
> Thanks,
>
> J
>> ---
>>   Documentation/ABI/testing/sysfs-bus-iio | 10 ++++++++++
>>   1 file changed, 10 insertions(+)
>>
>> diff --git a/Documentation/ABI/testing/sysfs-bus-iio b/Documentation/ABI/testing/sysfs-bus-iio
>> index a9757dc..ed202b3 100644
>> --- a/Documentation/ABI/testing/sysfs-bus-iio
>> +++ b/Documentation/ABI/testing/sysfs-bus-iio
>> @@ -895,6 +895,16 @@ Description:
>>           on-chip EEPROM. After power-up or chip reset the device will
>>           automatically load the saved configuration.
>>
>> +What:        /sys/.../iio:deviceX/in_proximity_raw
>> +What:        /sys/.../iio:deviceX/in_proximity_input
>> +What:        /sys/.../iio:deviceX/in_proximityY_raw
>> +KernelVersion:    3.4
>> +Contact:    linux-iio@vger.kernel.org
>> +Description:
>> +        Unit-less proximity measurement indicating that some
>> +        object is near the sensor, usually be observing
>> +        reflectivity of infrared or ultrasound emitted.
>> +
>>   What:        /sys/.../iio:deviceX/in_illuminanceY_input
>>   What:        /sys/.../iio:deviceX/in_illuminanceY_raw
>>   What:        /sys/.../iio:deviceX/in_illuminanceY_mean_raw
>>
>
> --
> To unsubscribe from this list: send the line "unsubscribe linux-iio" in
> the body of a message to majordomo@vger.kernel.org
> More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH 4/4] iio: Fix spelling of illuminance in gp2ap020a00f driver

[Jonathan Cameron]

On 02/05/14 16:54, Peter Meerwald wrote:
> Cc: Jacek Anaszewski <j.anaszewski@samsung.com>
> Signed-off-by: Peter Meerwald <pmeerw@pmeerw.net>
Applied to the togreg branch of iio.git

Thanks,

J
> ---
>   drivers/iio/light/gp2ap020a00f.c | 8 ++++----
>   1 file changed, 4 insertions(+), 4 deletions(-)
>
> diff --git a/drivers/iio/light/gp2ap020a00f.c b/drivers/iio/light/gp2ap020a00f.c
> index 5ea4a03..04bdb85 100644
> --- a/drivers/iio/light/gp2ap020a00f.c
> +++ b/drivers/iio/light/gp2ap020a00f.c
> @@ -5,13 +5,13 @@
>    * IIO features supported by the driver:
>    *
>    * Read-only raw channels:
> - *   - illiminance_clear [lux]
> - *   - illiminance_ir
> + *   - illuminance_clear [lux]
> + *   - illuminance_ir
>    *   - proximity
>    *
>    * Triggered buffer:
> - *   - illiminance_clear
> - *   - illiminance_ir
> + *   - illuminance_clear
> + *   - illuminance_ir
>    *   - proximity
>    *
>    * Events:
>