Skip to contentSkip to conversation

iio: documentation: Document proximity sensor label use

PATCH Superseded Hans de Goede 2 participants 3 messages Feb 15, 2021 – Feb 18, 2021 IIO

lore
Share & tools
lore
#0 lore raw

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

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/[email protected]/

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 <[email protected]>
Cc Mark Pearson <[email protected]>
Cc Bastien Nocera <[email protected]>

---
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(+)
Documentation/ABI/testing/sysfs-bus-iio +39 -0
index 35289d47d6cb..364f842350ab 100644
@@ -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:	[email protected]
+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:	[email protected]
Signature · 1 line
2.30.1
#1 lore raw

PATCH v2 2/2 iio: documentation: Document accelerometer label use

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 <[email protected]>
Cc Mark Pearson <[email protected]>
Cc Bastien Nocera <[email protected]>
---
 Documentation/ABI/testing/sysfs-bus-iio | 7 +++++++
 1 file changed, 7 insertions(+)
Documentation/ABI/testing/sysfs-bus-iio +7 -0
index 364f842350ab..5764f100d33d 100644
@@ -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:	[email protected]
Signature · 1 line
2.30.1
maintainer
#2 lore raw
In reply to Hans de Goede
Quoted 15 lines · On Mon, 15 Feb 2021 20:10:02 +0100 Hans de Goede <[email protected]> wrote:

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/[email protected]/

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

Quoted 8 lines

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 <[email protected]>
Cc Mark Pearson <[email protected]>
Cc Bastien Nocera <[email protected]>

Great thanks.

Series applied to the togreg branch of iio.git and pushed out as testing for the autobuilders to ignore.

Jonathan

Quoted 62 lines

---
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(+)
Documentation/ABI/testing/sysfs-bus-iio +39 -0
index 35289d47d6cb..364f842350ab 100644
@@ -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:	[email protected]
+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:	[email protected]