[PATCH v2 resend 0/2] iio: documentation: Document proximity/accel sensor label use

[PATCH v2 resend 0/2] iio: documentation: Document proximity/accel sensor label use

[Hans de Goede]

Hi Jonathan,

AFAICT the v2 of this series is ready for merging, but I'm not seeing it here:
https://git.kernel.org/pub/scm/linux/kernel/git/jic23/iio.git/log/?h=testing

Hence this resend.

Regards,

Hans



Hans de Goede (2):
  iio: documentation: Document proximity sensor label use
  iio: documentation: Document accelerometer label use

 Documentation/ABI/testing/sysfs-bus-iio | 46 +++++++++++++++++++++++++
 1 file changed, 46 insertions(+)

-- 
2.30.2

[PATCH v2 resend 1/2] iio: documentation: Document proximity sensor label use

[Hans de Goede]

Add an entry to Documentation/ABI/testing/sysfs-bus-iio for
the new device label sysfs-attribute support.

And document the standardized labels which may be used with proximity
sensors to hint userspace about the intended use of the sensor.

Using labels to differentiate between the multiple proximity sensors
which a modern laptop/tablet may have was discussed in this thread:
https://lore.kernel.org/linux-iio/9f9b0ff6-3bf1-63c4-eb36-901cecd7c4d9@redhat.com/

As mentioned there the "proximity-wifi*" labels are already being used
in this manner on some chromebooks, see e.g.:
arch/arm64/boot/dts/qcom/sc7180-trogdor.dtsi
arch/arm64/boot/dts/qcom/sc7180-trogdor-lte-sku.dtsi

And the "proximity-palmrest" and "proximity-lap" labels are intended
to be used with the lap and palmrest sensors found in recent Lenovo
ThinkPad models.

Cc: Dmitry Torokhov <dmitry.torokhov@gmail.com>
Cc: Mark Pearson <mpearson@lenovo.com>
Cc: Bastien Nocera <hadess@hadess.net>
Signed-off-by: Hans de Goede <hdegoede@redhat.com>
---
Changes in v2:
- Drop the too generic:
  What:           /sys/bus/iio/devices/iio:deviceX/in_*_label
  What:           /sys/bus/iio/devices/iio:deviceX/out_*_label
  lines from the newly added documentation, if/when we start
  using channel-labels with proximity sensors then those should
  get a separate in_proximityX_label documentation.
---
 Documentation/ABI/testing/sysfs-bus-iio | 39 +++++++++++++++++++++++++
 1 file changed, 39 insertions(+)

diff --git a/Documentation/ABI/testing/sysfs-bus-iio b/Documentation/ABI/testing/sysfs-bus-iio
index d957f5da5c04..7379e40d862d 100644
--- a/Documentation/ABI/testing/sysfs-bus-iio
+++ b/Documentation/ABI/testing/sysfs-bus-iio
@@ -33,6 +33,45 @@ Description:
 		Description of the physical chip / device for device X.
 		Typically a part number.
 
+What:		/sys/bus/iio/devices/iio:deviceX/label
+KernelVersion:	5.8
+Contact:	linux-iio@vger.kernel.org
+Description:
+		Optional symbolic label for a device.
+		This is useful for userspace to be able to better identify an
+		individual device.
+
+		The contents of the label are free-form, but there are some
+		standardized uses:
+
+		For proximity sensors which give the proximity (of a person) to
+		a certain wlan or wwan antenna the following standardized labels
+		are used:
+
+		* "proximity-wifi"
+		* "proximity-lte"
+		* "proximity-wifi-lte"
+		* "proximity-wifi-left"
+		* "proximity-wifi-right"
+
+		These are used to indicate to userspace that these proximity
+		sensors may be used to tune transmit power to ensure that
+		Specific Absorption Rate (SAR) limits are honored.
+		The "-left" and "-right" labels are for devices with multiple
+		antennas.
+
+		In some laptops/tablets the standardized proximity sensor labels
+		instead	indicate proximity to a specific part of the device:
+
+		* "proximity-palmrest" indicates proximity to the keyboard's palmrest
+		* "proximity-palmrest-left" indicates proximity to the left part of the palmrest
+		* "proximity-palmrest-right" indicates proximity to the right part of the palmrest
+		* "proximity-lap" indicates the device is being used on someone's lap
+
+		Note "proximity-lap" is special in that its value may be
+		calculated by firmware from other sensor readings, rather then
+		being a raw sensor reading.
+
 What:		/sys/bus/iio/devices/iio:deviceX/current_timestamp_clock
 KernelVersion:	4.5
 Contact:	linux-iio@vger.kernel.org
-- 
2.30.2

[PATCH v2 resend 2/2] iio: documentation: Document accelerometer label use

[Hans de Goede]

Some 2-in-1 laptops / convertibles with 360° (yoga-style) hinges,
have 2 accelerometers, 1 in their base and 1 in their display.

In many cases the kernel can detect the location of each accelerometer
based on e.g. information from the ACPI tables.

It is important for userspace to know the location of the 2 accelerometers.
Rather then adding a new sysfs-attribute for this we can relay this
information to userspace by using standardized label strings for this.
This mirrors how this is done for proximity sensors.

This commit documents 2 new standardized label strings for this purpose:
"accel-base"
"accel-display"

Note the "base" and "display" suffixes were chosen to match the values
used for the systemd/udev hwdb.d/60-sensor.hwdb file's ACCEL_LOCATION
property.

Cc: Dmitry Torokhov <dmitry.torokhov@gmail.com>
Cc: Mark Pearson <mpearson@lenovo.com>
Cc: Bastien Nocera <hadess@hadess.net>
Signed-off-by: Hans de Goede <hdegoede@redhat.com>
---
 Documentation/ABI/testing/sysfs-bus-iio | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/Documentation/ABI/testing/sysfs-bus-iio b/Documentation/ABI/testing/sysfs-bus-iio
index 7379e40d862d..b7529bca83f5 100644
--- a/Documentation/ABI/testing/sysfs-bus-iio
+++ b/Documentation/ABI/testing/sysfs-bus-iio
@@ -72,6 +72,13 @@ Description:
 		calculated by firmware from other sensor readings, rather then
 		being a raw sensor reading.
 
+		For accelerometers used in 2-in-1s with 360° (yoga-style) hinges,
+		which have an accelerometer in both their base and their display,
+		the following standardized labels are used:
+
+		* "accel-base"
+		* "accel-display"
+
 What:		/sys/bus/iio/devices/iio:deviceX/current_timestamp_clock
 KernelVersion:	4.5
 Contact:	linux-iio@vger.kernel.org
-- 
2.30.2

Re: [PATCH v2 resend 0/2] iio: documentation: Document proximity/accel sensor label use

[Hans de Goede]

Hi,

Ugh, I messed up the "To:" list for this resend, sorry, please ignore.

Regards,

Hans



On 4/5/21 10:39 PM, Hans de Goede wrote:
> Hi Jonathan,
> 
> AFAICT the v2 of this series is ready for merging, but I'm not seeing it here:
> https://git.kernel.org/pub/scm/linux/kernel/git/jic23/iio.git/log/?h=testing
> 
> Hence this resend.
> 
> Regards,
> 
> Hans
> 
> 
> 
> Hans de Goede (2):
>   iio: documentation: Document proximity sensor label use
>   iio: documentation: Document accelerometer label use
> 
>  Documentation/ABI/testing/sysfs-bus-iio | 46 +++++++++++++++++++++++++
>  1 file changed, 46 insertions(+)
> 

RE: iio: documentation: Document proximity/accel sensor label use

[bluez.test.bot]

[-- Attachment #1: Type: text/plain, Size: 2295 bytes --]

This is automated email and please do not reply to this email!

Dear submitter,

Thank you for submitting the patches to the linux bluetooth mailing list.
This is a CI test results with your patch series:
PW Link:https://patchwork.kernel.org/project/bluetooth/list/?series=461019

---Test result---

##############################
Test: CheckPatch - FAIL
iio: documentation: Document proximity sensor label use
WARNING: Possible unwrapped commit description (prefer a maximum 75 chars per line)
#14: 
https://lore.kernel.org/linux-iio/9f9b0ff6-3bf1-63c4-eb36-901cecd7c4d9@redhat.com/

total: 0 errors, 1 warnings, 45 lines checked

NOTE: For some of the reported defects, checkpatch may be able to
      mechanically convert to the typical style using --fix or --fix-inplace.

"[PATCH] iio: documentation: Document proximity sensor label use" has style problems, please review.

NOTE: If any of the errors are false positives, please report
      them to the maintainer, see CHECKPATCH in MAINTAINERS.


##############################
Test: CheckGitLint - FAIL
iio: documentation: Document proximity sensor label use
11: B1 Line exceeds max length (82>80): "https://lore.kernel.org/linux-iio/9f9b0ff6-3bf1-63c4-eb36-901cecd7c4d9@redhat.com/"


##############################
Test: CheckBuildK - PASS


##############################
Test: CheckTestRunner: Setup - PASS


##############################
Test: CheckTestRunner: l2cap-tester - PASS
Total: 40, Passed: 34 (85.0%), Failed: 0, Not Run: 6

##############################
Test: CheckTestRunner: bnep-tester - PASS
Total: 1, Passed: 1 (100.0%), Failed: 0, Not Run: 0

##############################
Test: CheckTestRunner: mgmt-tester - PASS
Total: 416, Passed: 402 (96.6%), Failed: 0, Not Run: 14

##############################
Test: CheckTestRunner: rfcomm-tester - PASS
Total: 9, Passed: 9 (100.0%), Failed: 0, Not Run: 0

##############################
Test: CheckTestRunner: sco-tester - PASS
Total: 8, Passed: 8 (100.0%), Failed: 0, Not Run: 0

##############################
Test: CheckTestRunner: smp-tester - PASS
Total: 8, Passed: 8 (100.0%), Failed: 0, Not Run: 0

##############################
Test: CheckTestRunner: userchan-tester - PASS
Total: 3, Passed: 3 (100.0%), Failed: 0, Not Run: 0



---
Regards,
Linux Bluetooth


[-- Attachment #2: l2cap-tester.log --]
[-- Type: application/octet-stream, Size: 43341 bytes --]

[-- Attachment #3: bnep-tester.log --]
[-- Type: application/octet-stream, Size: 3531 bytes --]

[-- Attachment #4: mgmt-tester.log --]
[-- Type: application/octet-stream, Size: 546679 bytes --]

[-- Attachment #5: rfcomm-tester.log --]
[-- Type: application/octet-stream, Size: 11651 bytes --]

[-- Attachment #6: sco-tester.log --]
[-- Type: application/octet-stream, Size: 9887 bytes --]

[-- Attachment #7: smp-tester.log --]
[-- Type: application/octet-stream, Size: 11798 bytes --]

[-- Attachment #8: userchan-tester.log --]
[-- Type: application/octet-stream, Size: 5429 bytes --]

Re: [PATCH v2 resend 2/2] iio: documentation: Document accelerometer label use

[Bastien Nocera]

On Mon, 2021-04-05 at 22:39 +0200, Hans de Goede wrote:
> Some 2-in-1 laptops / convertibles with 360° (yoga-style) hinges,
> have 2 accelerometers, 1 in their base and 1 in their display.
> 
> In many cases the kernel can detect the location of each
> accelerometer
> based on e.g. information from the ACPI tables.
> 
> It is important for userspace to know the location of the 2
> accelerometers.
> Rather then adding a new sysfs-attribute for this we can relay this
> information to userspace by using standardized label strings for
> this.
> This mirrors how this is done for proximity sensors.
> 
> This commit documents 2 new standardized label strings for this
> purpose:
> "accel-base"
> "accel-display"

If we have a combined proximity and accelerometer sensor (which
wouldn't be unheard off with sensor hubs being used), how are multiple
labels, say "proximity-wifi" and "accel-base" documented?

I think that it might be worth using a separate sysfs attribute for
this, say "location" which would have "display" or "base" as a value,
and which iio-sensor-proxy could already consume.

This would also make it easier to funnel values from DeviceTree or ACPI
to udev and/or a single sysfs kernel attribute one-to-one.

Cheers

> 
> Note the "base" and "display" suffixes were chosen to match the
> values
> used for the systemd/udev hwdb.d/60-sensor.hwdb file's ACCEL_LOCATION
> property.
> 
> Cc: Dmitry Torokhov <dmitry.torokhov@gmail.com>
> Cc: Mark Pearson <mpearson@lenovo.com>
> Cc: Bastien Nocera <hadess@hadess.net>
> Signed-off-by: Hans de Goede <hdegoede@redhat.com>
> ---
>  Documentation/ABI/testing/sysfs-bus-iio | 7 +++++++
>  1 file changed, 7 insertions(+)
> 
> diff --git a/Documentation/ABI/testing/sysfs-bus-iio
> b/Documentation/ABI/testing/sysfs-bus-iio
> index 7379e40d862d..b7529bca83f5 100644
> --- a/Documentation/ABI/testing/sysfs-bus-iio
> +++ b/Documentation/ABI/testing/sysfs-bus-iio
> @@ -72,6 +72,13 @@ Description:
>                 calculated by firmware from other sensor readings,
> rather then
>                 being a raw sensor reading.
>  
> +               For accelerometers used in 2-in-1s with 360° (yoga-
> style) hinges,
> +               which have an accelerometer in both their base and
> their display,
> +               the following standardized labels are used:
> +
> +               * "accel-base"
> +               * "accel-display"
> +
>  What:          /sys/bus/iio/devices/iio:deviceX/current_timestamp_cl
> ock
>  KernelVersion: 4.5
>  Contact:       linux-iio@vger.kernel.org

Re: [PATCH v2 resend 2/2] iio: documentation: Document accelerometer label use

[Hans de Goede]

Hi,

On 4/16/21 12:56 PM, Bastien Nocera wrote:
> On Mon, 2021-04-05 at 22:39 +0200, Hans de Goede wrote:
>> Some 2-in-1 laptops / convertibles with 360° (yoga-style) hinges,
>> have 2 accelerometers, 1 in their base and 1 in their display.
>>
>> In many cases the kernel can detect the location of each
>> accelerometer
>> based on e.g. information from the ACPI tables.
>>
>> It is important for userspace to know the location of the 2
>> accelerometers.
>> Rather then adding a new sysfs-attribute for this we can relay this
>> information to userspace by using standardized label strings for
>> this.
>> This mirrors how this is done for proximity sensors.
>>
>> This commit documents 2 new standardized label strings for this
>> purpose:
>> "accel-base"
>> "accel-display"
> 
> If we have a combined proximity and accelerometer sensor (which
> wouldn't be unheard off with sensor hubs being used), how are multiple
> labels, say "proximity-wifi" and "accel-base" documented?

Sensor hubs typically use one iio device per sensor, see e.g.
how HID-sensors work. And if a device which does not use separate
iio-devices per sensor shows up then the plan is to use per
channel-labels which are already supported by iio.

Regards,

Hans



>> Note the "base" and "display" suffixes were chosen to match the
>> values
>> used for the systemd/udev hwdb.d/60-sensor.hwdb file's ACCEL_LOCATION
>> property.
>>
>> Cc: Dmitry Torokhov <dmitry.torokhov@gmail.com>
>> Cc: Mark Pearson <mpearson@lenovo.com>
>> Cc: Bastien Nocera <hadess@hadess.net>
>> Signed-off-by: Hans de Goede <hdegoede@redhat.com>
>> ---
>>  Documentation/ABI/testing/sysfs-bus-iio | 7 +++++++
>>  1 file changed, 7 insertions(+)
>>
>> diff --git a/Documentation/ABI/testing/sysfs-bus-iio
>> b/Documentation/ABI/testing/sysfs-bus-iio
>> index 7379e40d862d..b7529bca83f5 100644
>> --- a/Documentation/ABI/testing/sysfs-bus-iio
>> +++ b/Documentation/ABI/testing/sysfs-bus-iio
>> @@ -72,6 +72,13 @@ Description:
>>                 calculated by firmware from other sensor readings,
>> rather then
>>                 being a raw sensor reading.
>>  
>> +               For accelerometers used in 2-in-1s with 360° (yoga-
>> style) hinges,
>> +               which have an accelerometer in both their base and
>> their display,
>> +               the following standardized labels are used:
>> +
>> +               * "accel-base"
>> +               * "accel-display"
>> +
>>  What:          /sys/bus/iio/devices/iio:deviceX/current_timestamp_cl
>> ock
>>  KernelVersion: 4.5
>>  Contact:       linux-iio@vger.kernel.org
> 
> 

Re: [PATCH v2 resend 2/2] iio: documentation: Document accelerometer label use

[Bastien Nocera]

On Fri, 2021-04-16 at 13:05 +0200, Hans de Goede wrote:
> Hi,
> 
> On 4/16/21 12:56 PM, Bastien Nocera wrote:
> > On Mon, 2021-04-05 at 22:39 +0200, Hans de Goede wrote:
> > > Some 2-in-1 laptops / convertibles with 360° (yoga-style) hinges,
> > > have 2 accelerometers, 1 in their base and 1 in their display.
> > > 
> > > In many cases the kernel can detect the location of each
> > > accelerometer
> > > based on e.g. information from the ACPI tables.
> > > 
> > > It is important for userspace to know the location of the 2
> > > accelerometers.
> > > Rather then adding a new sysfs-attribute for this we can relay
> > > this
> > > information to userspace by using standardized label strings for
> > > this.
> > > This mirrors how this is done for proximity sensors.
> > > 
> > > This commit documents 2 new standardized label strings for this
> > > purpose:
> > > "accel-base"
> > > "accel-display"
> > 
> > If we have a combined proximity and accelerometer sensor (which
> > wouldn't be unheard off with sensor hubs being used), how are
> > multiple
> > labels, say "proximity-wifi" and "accel-base" documented?
> 
> Sensor hubs typically use one iio device per sensor, see e.g.
> how HID-sensors work. And if a device which does not use separate
> iio-devices per sensor shows up then the plan is to use per
> channel-labels which are already supported by iio.

OK.

> 
> Regards,
> 
> Hans
> 
> 
> 
> > > Note the "base" and "display" suffixes were chosen to match the
> > > values
> > > used for the systemd/udev hwdb.d/60-sensor.hwdb file's
> > > ACCEL_LOCATION
> > > property.
> > > 
> > > Cc: Dmitry Torokhov <dmitry.torokhov@gmail.com>
> > > Cc: Mark Pearson <mpearson@lenovo.com>
> > > Cc: Bastien Nocera <hadess@hadess.net>
> > > Signed-off-by: Hans de Goede <hdegoede@redhat.com>
> > > ---
> > >  Documentation/ABI/testing/sysfs-bus-iio | 7 +++++++
> > >  1 file changed, 7 insertions(+)
> > > 
> > > diff --git a/Documentation/ABI/testing/sysfs-bus-iio
> > > b/Documentation/ABI/testing/sysfs-bus-iio
> > > index 7379e40d862d..b7529bca83f5 100644
> > > --- a/Documentation/ABI/testing/sysfs-bus-iio
> > > +++ b/Documentation/ABI/testing/sysfs-bus-iio
> > > @@ -72,6 +72,13 @@ Description:
> > >                 calculated by firmware from other sensor
> > > readings,
> > > rather then
> > >                 being a raw sensor reading.
> > >  
> > > +               For accelerometers used in 2-in-1s with 360°
> > > (yoga-
> > > style) hinges,
> > > +               which have an accelerometer in both their base
> > > and
> > > their display,
> > > +               the following standardized labels are used:
> > > +
> > > +               * "accel-base"
> > > +               * "accel-display"
> > > +
> > >  What:          /sys/bus/iio/devices/iio:deviceX/current_timestam
> > > p_cl
> > > ock
> > >  KernelVersion: 4.5
> > >  Contact:       linux-iio@vger.kernel.org
> > 
> > 
> 

Re: [PATCH v2 resend 0/2] iio: documentation: Document proximity/accel sensor label use

[Hans de Goede]

Hi,

On 4/6/21 10:41 AM, Jonathan Cameron wrote:
> On Mon,  5 Apr 2021 22:42:22 +0200
> Hans de Goede <hdegoede@redhat.com> wrote:
> 
>> Hi Jonathan,
>>
>> AFAICT the v2 of this series is ready for merging, but I'm not seeing it here:
>> https://git.kernel.org/pub/scm/linux/kernel/git/jic23/iio.git/log/?h=testing
> 
> It's there.  Was part of a pull request earlier this cycle I think and so
> may be somewhat buried in the history.
> 
> https://git.kernel.org/pub/scm/linux/kernel/git/jic23/iio.git/commit/Documentation/ABI/testing/sysfs-bus-iio?h=testing&id=9a6df4b1ab0e467f23ccdcbb82700cfb3eaf44a3

Good to know that it is already there.

I already was a bit surprised I couldn't find it, because I remembered you
explicitly saying that you were going to merge it. I guess I should have
searched a little bit harder before the resend, sorry about the noise.

Regards,

Hans

Re: [PATCH v2 resend 0/2] iio: documentation: Document proximity/accel sensor label use

[Jonathan Cameron]

On Mon,  5 Apr 2021 22:42:22 +0200
Hans de Goede <hdegoede@redhat.com> wrote:

> Hi Jonathan,
> 
> AFAICT the v2 of this series is ready for merging, but I'm not seeing it here:
> https://git.kernel.org/pub/scm/linux/kernel/git/jic23/iio.git/log/?h=testing

It's there.  Was part of a pull request earlier this cycle I think and so
may be somewhat buried in the history.

https://git.kernel.org/pub/scm/linux/kernel/git/jic23/iio.git/commit/Documentation/ABI/testing/sysfs-bus-iio?h=testing&id=9a6df4b1ab0e467f23ccdcbb82700cfb3eaf44a3

> 
> Hence this resend.
> 
> Regards,
> 
> Hans
> 
> 
> 
> Hans de Goede (2):
>   iio: documentation: Document proximity sensor label use
>   iio: documentation: Document accelerometer label use
> 
>  Documentation/ABI/testing/sysfs-bus-iio | 46 +++++++++++++++++++++++++
>  1 file changed, 46 insertions(+)
> 

[PATCH v2 resend 0/2] iio: documentation: Document proximity/accel sensor label use

[Hans de Goede]

Hi Jonathan,

AFAICT the v2 of this series is ready for merging, but I'm not seeing it here:
https://git.kernel.org/pub/scm/linux/kernel/git/jic23/iio.git/log/?h=testing

Hence this resend.

Regards,

Hans



Hans de Goede (2):
  iio: documentation: Document proximity sensor label use
  iio: documentation: Document accelerometer label use

 Documentation/ABI/testing/sysfs-bus-iio | 46 +++++++++++++++++++++++++
 1 file changed, 46 insertions(+)

-- 
2.30.2