| Message ID | 20210207123720.8357-1-hdegoede@redhat.com (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
| Series | [1/2] iio: documentation: Document proximity sensor label use | expand |
On Sun, 2021-02-07 at 13:37 +0100, Hans de Goede wrote: > Add an entry to Documentation/ABI/testing/sysfs-bus-iio for > the new device and channel 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 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. Both patches in the series look fine to me. Is IIO the interface you plan on using to implement the lap detection for the thinkpad_acpi driver? If so, don't forget to set the "nearlevel" property as well. I'll probably have to write a new iio-sensor-proxy driver for those as well, without the hardware. That'll be interesting ;) Cheers
Hi, On 2/8/21 2:40 PM, Bastien Nocera wrote: > On Sun, 2021-02-07 at 13:37 +0100, Hans de Goede wrote: >> Add an entry to Documentation/ABI/testing/sysfs-bus-iio for >> the new device and channel 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 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. > > Both patches in the series look fine to me. Thank you for checking. > Is IIO the interface you plan on using to implement the lap detection > for the thinkpad_acpi driver? ATM both the lap detection and the palmrest proximity detection are already available using thinkpad_acpi specific sysfs attributes: [hans@x1 linux]$ cat /sys/bus/platform/devices/thinkpad_acpi/dytc_lapmode 0 [hans@x1 linux]$ cat /sys/bus/platform/devices/thinkpad_acpi/palmsensor 1 Which I think you are already aware of ? These will not be going anywhere since dropping these would be a userspace ABI break. With that said, yes the plan is to extend the thinkpad_acpi driver to also report lap / palmrest proximity through IIO using these labels. With the idea being that if other drivers / vendor firmwares also will export similar readings that those will then also use IIO with these labels for this, so that there is one unified / driver independent interface which userspace can use to get these readings. > If so, don't forget to set the "nearlevel" property as well. Ack, I'll make sure that you are on the Cc when the patches for this get posted. Regards, Hans
On Mon, 2021-02-08 at 14:50 +0100, Hans de Goede wrote: > Hi, > > On 2/8/21 2:40 PM, Bastien Nocera wrote: > > On Sun, 2021-02-07 at 13:37 +0100, Hans de Goede wrote: > > > Add an entry to Documentation/ABI/testing/sysfs-bus-iio for > > > the new device and channel 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 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. > > > > Both patches in the series look fine to me. > > Thank you for checking. > > > Is IIO the interface you plan on using to implement the lap > > detection > > for the thinkpad_acpi driver? > > ATM both the lap detection and the palmrest proximity detection are > already available using thinkpad_acpi specific sysfs attributes: > > [hans@x1 linux]$ cat > /sys/bus/platform/devices/thinkpad_acpi/dytc_lapmode > 0 > [hans@x1 linux]$ cat > /sys/bus/platform/devices/thinkpad_acpi/palmsensor > 1 > > Which I think you are already aware of ? I didn't know those actually landed upstream (or I didn't remember), I was waiting on the SW_LAP_PROXIMITY input device method to land: https://gitlab.freedesktop.org/hadess/power-profiles-daemon/-/merge_requests/42 That's abandoned, right? > These will not be going > anywhere since dropping these would be a userspace ABI break. > > With that said, yes the plan is to extend the thinkpad_acpi driver > to also report lap / palmrest proximity through IIO using these > labels. OK, good to know. I've filed: https://gitlab.freedesktop.org/hadess/iio-sensor-proxy/-/issues/321 so we can eventually export more than a single proximity sensor through the D-Bus interface in the future. Cheers
Hi, On 2/8/21 3:16 PM, Bastien Nocera wrote: > On Mon, 2021-02-08 at 14:50 +0100, Hans de Goede wrote: >> Hi, >> >> On 2/8/21 2:40 PM, Bastien Nocera wrote: >>> On Sun, 2021-02-07 at 13:37 +0100, Hans de Goede wrote: >>>> Add an entry to Documentation/ABI/testing/sysfs-bus-iio for >>>> the new device and channel 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 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. >>> >>> Both patches in the series look fine to me. >> >> Thank you for checking. >> >>> Is IIO the interface you plan on using to implement the lap >>> detection >>> for the thinkpad_acpi driver? >> >> ATM both the lap detection and the palmrest proximity detection are >> already available using thinkpad_acpi specific sysfs attributes: >> >> [hans@x1 linux]$ cat >> /sys/bus/platform/devices/thinkpad_acpi/dytc_lapmode >> 0 >> [hans@x1 linux]$ cat >> /sys/bus/platform/devices/thinkpad_acpi/palmsensor >> 1 >> >> Which I think you are already aware of ? > > I didn't know those actually landed upstream (or I didn't remember), I > was waiting on the SW_LAP_PROXIMITY input device method to land: > https://gitlab.freedesktop.org/hadess/power-profiles-daemon/-/merge_requests/42 > > That's abandoned, right? Yes that has been abandoned, sorry. >> These will not be going >> anywhere since dropping these would be a userspace ABI break. >> >> With that said, yes the plan is to extend the thinkpad_acpi driver >> to also report lap / palmrest proximity through IIO using these >> labels. > > OK, good to know. > > I've filed: > https://gitlab.freedesktop.org/hadess/iio-sensor-proxy/-/issues/321 > so we can eventually export more than a single proximity sensor through > the D-Bus interface in the future. Ok. Regards, Hans
On Sun, 7 Feb 2021 13:37:19 +0100 Hans de Goede <hdegoede@redhat.com> wrote: > Add an entry to Documentation/ABI/testing/sysfs-bus-iio for > the new device and channel 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 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> > --- > Documentation/ABI/testing/sysfs-bus-iio | 41 +++++++++++++++++++++++++ > 1 file changed, 41 insertions(+) > > diff --git a/Documentation/ABI/testing/sysfs-bus-iio b/Documentation/ABI/testing/sysfs-bus-iio > index 35289d47d6cb..f2f090f8bd2f 100644 > --- a/Documentation/ABI/testing/sysfs-bus-iio > +++ b/Documentation/ABI/testing/sysfs-bus-iio > @@ -33,6 +33,47 @@ Description: > Description of the physical chip / device for device X. > Typically a part number. > > +What: /sys/bus/iio/devices/iio:deviceX/label > +What: /sys/bus/iio/devices/iio:deviceX/in_*_label > +What: /sys/bus/iio/devices/iio:deviceX/out_*_label I was a bit in two minds about this from an organizational point of view. 1) Whether to separate the general label where position tends to make sense from the channel labels. May be something we want to do in future but we can probably let that go for now. 2) Whether to allow such broad wild cards for the channels. Whilst in theory any channel can have a label we normally only document ABI that actually exists (mostly to know what we might break if we change anything :) Still I can't see any way we can change this without breakage so in this one case let's let the broad wild card go in. This comes unstuck on the fact it overlaps with existing more specific Docs. So can you pull the channel part out of here for v2. /sys/bus/iio/devices/iio:deviceX/in_voltageY_label /sys/bus/iio/devices/iio:deviceX/in_anglY_label The reason to keep these separate is that they will often contain a bit more info about specific driver ABI (because of the issues with duplicating ABI documentation in multiple files) so I'd rather we didn't end up with this one item having many pages of info. Jonathan Jonathan > +KernelVersion: 5.8 > +Contact: linux-iio@vger.kernel.org > +Description: > + Optional symbolic label for a device or a channel. > + This is useful for userspace to be able to better identify an > + individual device or channel. > + > + 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
Hi, On 2/12/21 7:46 PM, Jonathan Cameron wrote: > On Sun, 7 Feb 2021 13:37:19 +0100 > Hans de Goede <hdegoede@redhat.com> wrote: > >> Add an entry to Documentation/ABI/testing/sysfs-bus-iio for >> the new device and channel 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 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> >> --- >> Documentation/ABI/testing/sysfs-bus-iio | 41 +++++++++++++++++++++++++ >> 1 file changed, 41 insertions(+) >> >> diff --git a/Documentation/ABI/testing/sysfs-bus-iio b/Documentation/ABI/testing/sysfs-bus-iio >> index 35289d47d6cb..f2f090f8bd2f 100644 >> --- a/Documentation/ABI/testing/sysfs-bus-iio >> +++ b/Documentation/ABI/testing/sysfs-bus-iio >> @@ -33,6 +33,47 @@ Description: >> Description of the physical chip / device for device X. >> Typically a part number. >> >> +What: /sys/bus/iio/devices/iio:deviceX/label >> +What: /sys/bus/iio/devices/iio:deviceX/in_*_label >> +What: /sys/bus/iio/devices/iio:deviceX/out_*_label > > I was a bit in two minds about this from an organizational point of view. > 1) Whether to separate the general label where position tends to make sense > from the channel labels. May be something we want to do in future but we can probably > let that go for now. > 2) Whether to allow such broad wild cards for the channels. > Whilst in theory any channel can have a label we normally only document ABI > that actually exists (mostly to know what we might break if we change anything :) > Still I can't see any way we can change this without breakage so in this > one case let's let the broad wild card go in. > > This comes unstuck on the fact it overlaps with existing more specific Docs. > > So can you pull the channel part out of here for v2. > /sys/bus/iio/devices/iio:deviceX/in_voltageY_label > /sys/bus/iio/devices/iio:deviceX/in_anglY_label The problem is that these labels may either be used on a whole device, which is certainly the case with the accelerometers in patch 2/2 where the x y and z channels obviously all are either "accel-base" or "accel-display". Where as for proximity sensors the labels could be either applied at the device level, or at a channel level. The existing chromebook proximity usage is applying a label for this at the device level. This does mean that atm all users of this are using device-level labels; and maybe I'm reading too much in your request. I guess that for now I can just drop these lines for v2 : What: /sys/bus/iio/devices/iio:deviceX/in_*_label What: /sys/bus/iio/devices/iio:deviceX/out_*_label Is that what you have in mind ? Or do you want me to split this up in a proximity sensor case and an accel case, and group both cases together with other proximity / accel sensor attributes ? Regards, Hans > Jonathan >> +KernelVersion: 5.8 >> +Contact: linux-iio@vger.kernel.org >> +Description: >> + Optional symbolic label for a device or a channel. >> + This is useful for userspace to be able to better identify an >> + individual device or channel. >> + >> + 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 >
On Fri, 12 Feb 2021 19:58:47 +0100 Hans de Goede <hdegoede@redhat.com> wrote: > Hi, > > On 2/12/21 7:46 PM, Jonathan Cameron wrote: > > On Sun, 7 Feb 2021 13:37:19 +0100 > > Hans de Goede <hdegoede@redhat.com> wrote: > > > >> Add an entry to Documentation/ABI/testing/sysfs-bus-iio for > >> the new device and channel 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 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> > >> --- > >> Documentation/ABI/testing/sysfs-bus-iio | 41 +++++++++++++++++++++++++ > >> 1 file changed, 41 insertions(+) > >> > >> diff --git a/Documentation/ABI/testing/sysfs-bus-iio b/Documentation/ABI/testing/sysfs-bus-iio > >> index 35289d47d6cb..f2f090f8bd2f 100644 > >> --- a/Documentation/ABI/testing/sysfs-bus-iio > >> +++ b/Documentation/ABI/testing/sysfs-bus-iio > >> @@ -33,6 +33,47 @@ Description: > >> Description of the physical chip / device for device X. > >> Typically a part number. > >> > >> +What: /sys/bus/iio/devices/iio:deviceX/label > >> +What: /sys/bus/iio/devices/iio:deviceX/in_*_label > >> +What: /sys/bus/iio/devices/iio:deviceX/out_*_label > > > > I was a bit in two minds about this from an organizational point of view. > > 1) Whether to separate the general label where position tends to make sense > > from the channel labels. May be something we want to do in future but we can probably > > let that go for now. > > 2) Whether to allow such broad wild cards for the channels. > > Whilst in theory any channel can have a label we normally only document ABI > > that actually exists (mostly to know what we might break if we change anything :) > > Still I can't see any way we can change this without breakage so in this > > one case let's let the broad wild card go in. > > > > This comes unstuck on the fact it overlaps with existing more specific Docs. > > > > So can you pull the channel part out of here for v2. > > /sys/bus/iio/devices/iio:deviceX/in_voltageY_label > > /sys/bus/iio/devices/iio:deviceX/in_anglY_label > > The problem is that these labels may either be used on a whole device, > which is certainly the case with the accelerometers in patch 2/2 where > the x y and z channels obviously all are either "accel-base" or > "accel-display". > > Where as for proximity sensors the labels could be either applied at the > device level, or at a channel level. > > The existing chromebook proximity usage is applying a label for this > at the device level. > > This does mean that atm all users of this are using device-level labels; Not at all, but some (possibly all?) are separately documented in two existing entries. The generic version you propose overlaps with them and that is what I'd like to avoid. We could group these into the same 'catch all' element, but I suspect the text will just grow too large over time, so I'd like to keep them as broken up as possible. What: /sys/bus/iio/devices/iio:deviceX/in_voltageY_label What: /sys/bus/iio/devices/iio:deviceX/out_voltageY_label What: /sys/bus/iio/devices/iio:deviceX/in_anglY_label > and maybe I'm reading too much in your request. I guess that for now > I can just drop these lines for v2 : > > What: /sys/bus/iio/devices/iio:deviceX/in_*_label > What: /sys/bus/iio/devices/iio:deviceX/out_*_label > > Is that what you have in mind ? > > Or do you want me to split this up in a proximity sensor case and an > accel case, and group both cases together with other proximity / accel > sensor attributes ? Yes, that would be ideal for the cases where we have separate channel labels, but if we aren't using them today, lets introduce them when they are needed. Jonathan > > Regards, > > Hans > > > > > > Jonathan > >> +KernelVersion: 5.8 > >> +Contact: linux-iio@vger.kernel.org > >> +Description: > >> + Optional symbolic label for a device or a channel. > >> + This is useful for userspace to be able to better identify an > >> + individual device or channel. > >> + > >> + 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 > > >
Hi, On 2/15/21 1:39 PM, Jonathan Cameron wrote: > On Fri, 12 Feb 2021 19:58:47 +0100 > Hans de Goede <hdegoede@redhat.com> wrote: > >> Hi, >> >> On 2/12/21 7:46 PM, Jonathan Cameron wrote: >>> On Sun, 7 Feb 2021 13:37:19 +0100 >>> Hans de Goede <hdegoede@redhat.com> wrote: >>> >>>> Add an entry to Documentation/ABI/testing/sysfs-bus-iio for >>>> the new device and channel 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 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> >>>> --- >>>> Documentation/ABI/testing/sysfs-bus-iio | 41 +++++++++++++++++++++++++ >>>> 1 file changed, 41 insertions(+) >>>> >>>> diff --git a/Documentation/ABI/testing/sysfs-bus-iio b/Documentation/ABI/testing/sysfs-bus-iio >>>> index 35289d47d6cb..f2f090f8bd2f 100644 >>>> --- a/Documentation/ABI/testing/sysfs-bus-iio >>>> +++ b/Documentation/ABI/testing/sysfs-bus-iio >>>> @@ -33,6 +33,47 @@ Description: >>>> Description of the physical chip / device for device X. >>>> Typically a part number. >>>> >>>> +What: /sys/bus/iio/devices/iio:deviceX/label >>>> +What: /sys/bus/iio/devices/iio:deviceX/in_*_label >>>> +What: /sys/bus/iio/devices/iio:deviceX/out_*_label >>> >>> I was a bit in two minds about this from an organizational point of view. >>> 1) Whether to separate the general label where position tends to make sense >>> from the channel labels. May be something we want to do in future but we can probably >>> let that go for now. >>> 2) Whether to allow such broad wild cards for the channels. >>> Whilst in theory any channel can have a label we normally only document ABI >>> that actually exists (mostly to know what we might break if we change anything :) >>> Still I can't see any way we can change this without breakage so in this >>> one case let's let the broad wild card go in. >>> >>> This comes unstuck on the fact it overlaps with existing more specific Docs. >>> >>> So can you pull the channel part out of here for v2. >>> /sys/bus/iio/devices/iio:deviceX/in_voltageY_label >>> /sys/bus/iio/devices/iio:deviceX/in_anglY_label >> >> The problem is that these labels may either be used on a whole device, >> which is certainly the case with the accelerometers in patch 2/2 where >> the x y and z channels obviously all are either "accel-base" or >> "accel-display". >> >> Where as for proximity sensors the labels could be either applied at the >> device level, or at a channel level. >> >> The existing chromebook proximity usage is applying a label for this >> at the device level. >> >> This does mean that atm all users of this are using device-level labels; > > Not at all, but some (possibly all?) are separately documented in two > existing entries. The generic version you propose overlaps with them > and that is what I'd like to avoid. > > We could group these into the same 'catch all' element, but I suspect > the text will just grow too large over time, so I'd like to keep them > as broken up as possible. > > What: /sys/bus/iio/devices/iio:deviceX/in_voltageY_label > What: /sys/bus/iio/devices/iio:deviceX/out_voltageY_label > > What: /sys/bus/iio/devices/iio:deviceX/in_anglY_label > >> and maybe I'm reading too much in your request. I guess that for now >> I can just drop these lines for v2 : >> >> What: /sys/bus/iio/devices/iio:deviceX/in_*_label >> What: /sys/bus/iio/devices/iio:deviceX/out_*_label >> >> Is that what you have in mind ? >> >> Or do you want me to split this up in a proximity sensor case and an >> accel case, and group both cases together with other proximity / accel >> sensor attributes ? > > Yes, that would be ideal for the cases where we have separate > channel labels, but if we aren't using them today, lets introduce them > when they are needed. Right, so atm we do not have any channel labels only device labels, which means there is only 1 "What:". What: /sys/bus/iio/devices/iio:deviceX/label For which v1 (this version) of this series adds a single large text block which covers both proximity and accelerometers. So just to be clear, you want me to split this, resulting in 2 entries with identical "What:" labels: What: /sys/bus/iio/devices/iio:deviceX/label And then group the 2 text blocks together with other proximity sensor attributes, resp. other accelerometer attributes ? Regards, Hans > > Jonathan > > >> >> Regards, >> >> Hans >> >> >> >> >>> Jonathan >>>> +KernelVersion: 5.8 >>>> +Contact: linux-iio@vger.kernel.org >>>> +Description: >>>> + Optional symbolic label for a device or a channel. >>>> + This is useful for userspace to be able to better identify an >>>> + individual device or channel. >>>> + >>>> + 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 >>> >> >
On Mon, 15 Feb 2021 13:55:09 +0100 Hans de Goede <hdegoede@redhat.com> wrote: > Hi, > > On 2/15/21 1:39 PM, Jonathan Cameron wrote: > > On Fri, 12 Feb 2021 19:58:47 +0100 > > Hans de Goede <hdegoede@redhat.com> wrote: > > > >> Hi, > >> > >> On 2/12/21 7:46 PM, Jonathan Cameron wrote: > >>> On Sun, 7 Feb 2021 13:37:19 +0100 > >>> Hans de Goede <hdegoede@redhat.com> wrote: > >>> > >>>> Add an entry to Documentation/ABI/testing/sysfs-bus-iio for > >>>> the new device and channel 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 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> > >>>> --- > >>>> Documentation/ABI/testing/sysfs-bus-iio | 41 +++++++++++++++++++++++++ > >>>> 1 file changed, 41 insertions(+) > >>>> > >>>> diff --git a/Documentation/ABI/testing/sysfs-bus-iio b/Documentation/ABI/testing/sysfs-bus-iio > >>>> index 35289d47d6cb..f2f090f8bd2f 100644 > >>>> --- a/Documentation/ABI/testing/sysfs-bus-iio > >>>> +++ b/Documentation/ABI/testing/sysfs-bus-iio > >>>> @@ -33,6 +33,47 @@ Description: > >>>> Description of the physical chip / device for device X. > >>>> Typically a part number. > >>>> > >>>> +What: /sys/bus/iio/devices/iio:deviceX/label > >>>> +What: /sys/bus/iio/devices/iio:deviceX/in_*_label > >>>> +What: /sys/bus/iio/devices/iio:deviceX/out_*_label > >>> > >>> I was a bit in two minds about this from an organizational point of view. > >>> 1) Whether to separate the general label where position tends to make sense > >>> from the channel labels. May be something we want to do in future but we can probably > >>> let that go for now. > >>> 2) Whether to allow such broad wild cards for the channels. > >>> Whilst in theory any channel can have a label we normally only document ABI > >>> that actually exists (mostly to know what we might break if we change anything :) > >>> Still I can't see any way we can change this without breakage so in this > >>> one case let's let the broad wild card go in. > >>> > >>> This comes unstuck on the fact it overlaps with existing more specific Docs. > >>> > >>> So can you pull the channel part out of here for v2. > >>> /sys/bus/iio/devices/iio:deviceX/in_voltageY_label > >>> /sys/bus/iio/devices/iio:deviceX/in_anglY_label > >> > >> The problem is that these labels may either be used on a whole device, > >> which is certainly the case with the accelerometers in patch 2/2 where > >> the x y and z channels obviously all are either "accel-base" or > >> "accel-display". > >> > >> Where as for proximity sensors the labels could be either applied at the > >> device level, or at a channel level. > >> > >> The existing chromebook proximity usage is applying a label for this > >> at the device level. > >> > >> This does mean that atm all users of this are using device-level labels; > > > > Not at all, but some (possibly all?) are separately documented in two > > existing entries. The generic version you propose overlaps with them > > and that is what I'd like to avoid. > > > > We could group these into the same 'catch all' element, but I suspect > > the text will just grow too large over time, so I'd like to keep them > > as broken up as possible. > > > > What: /sys/bus/iio/devices/iio:deviceX/in_voltageY_label > > What: /sys/bus/iio/devices/iio:deviceX/out_voltageY_label > > > > What: /sys/bus/iio/devices/iio:deviceX/in_anglY_label > > > >> and maybe I'm reading too much in your request. I guess that for now > >> I can just drop these lines for v2 : > >> > >> What: /sys/bus/iio/devices/iio:deviceX/in_*_label > >> What: /sys/bus/iio/devices/iio:deviceX/out_*_label > >> > >> Is that what you have in mind ? > >> > >> Or do you want me to split this up in a proximity sensor case and an > >> accel case, and group both cases together with other proximity / accel > >> sensor attributes ? > > > > Yes, that would be ideal for the cases where we have separate > > channel labels, but if we aren't using them today, lets introduce them > > when they are needed. > > Right, so atm we do not have any channel labels only device labels, > which means there is only 1 "What:". > > What: /sys/bus/iio/devices/iio:deviceX/label > > For which v1 (this version) of this series adds a single large > text block which covers both proximity and accelerometers. > > So just to be clear, you want me to split this, resulting in 2 > entries with identical "What:" labels: > > What: /sys/bus/iio/devices/iio:deviceX/label > > And then group the 2 text blocks together with other proximity > sensor attributes, resp. other accelerometer attributes ? No, sorry I wasn't clear. 1 entry only for the /label version (as we can't have repeats without breaking inclusion in the html docs). For the ones where we can be more specific keep them separate when we add them. i.e. in_proximityX_label vs in_accel_x_label Jonathan > > Regards, > > Hans > > > > > > > > > > > Jonathan > > > > > >> > >> Regards, > >> > >> Hans > >> > >> > >> > >> > >>> Jonathan > >>>> +KernelVersion: 5.8 > >>>> +Contact: linux-iio@vger.kernel.org > >>>> +Description: > >>>> + Optional symbolic label for a device or a channel. > >>>> + This is useful for userspace to be able to better identify an > >>>> + individual device or channel. > >>>> + > >>>> + 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 --git a/Documentation/ABI/testing/sysfs-bus-iio b/Documentation/ABI/testing/sysfs-bus-iio index 35289d47d6cb..f2f090f8bd2f 100644 --- a/Documentation/ABI/testing/sysfs-bus-iio +++ b/Documentation/ABI/testing/sysfs-bus-iio @@ -33,6 +33,47 @@ Description: Description of the physical chip / device for device X. Typically a part number. +What: /sys/bus/iio/devices/iio:deviceX/label +What: /sys/bus/iio/devices/iio:deviceX/in_*_label +What: /sys/bus/iio/devices/iio:deviceX/out_*_label +KernelVersion: 5.8 +Contact: linux-iio@vger.kernel.org +Description: + Optional symbolic label for a device or a channel. + This is useful for userspace to be able to better identify an + individual device or channel. + + 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
Add an entry to Documentation/ABI/testing/sysfs-bus-iio for the new device and channel 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 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> --- Documentation/ABI/testing/sysfs-bus-iio | 41 +++++++++++++++++++++++++ 1 file changed, 41 insertions(+)