diff mbox series

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

Message ID 20210215191003.698888-1-hdegoede@redhat.com (mailing list archive)
State New
Headers show
Series [v2,1/2] iio: documentation: Document proximity sensor label use | expand

Commit Message

Hans de Goede Feb. 15, 2021, 7:10 p.m. UTC
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(+)

Comments

Jonathan Cameron Feb. 18, 2021, 1:31 p.m. UTC | #1
On Mon, 15 Feb 2021 20:10:02 +0100
Hans de Goede <hdegoede@redhat.com> 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/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>
Great thanks.

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

Jonathan

> ---
> 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 35289d47d6cb..364f842350ab 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
diff mbox series

Patch

diff --git a/Documentation/ABI/testing/sysfs-bus-iio b/Documentation/ABI/testing/sysfs-bus-iio
index 35289d47d6cb..364f842350ab 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