[PATCH v2 2/3] dt-bindings: iio: st,st-sensors: add st,fullscale-milligauss

[Herman van Hazendonk]

Add an optional st,fullscale-milligauss property that selects the
initial magnetometer full-scale range at probe time, expressed in
milligauss.

The motivating case is the LSM303DLH magnetometer on the HP TouchPad
(apq8060 / tenderloin) where the kernel's chip-default +/-1.3 G range
saturates the X axis to the chip's 0xF000 overflow sentinel out of
probe, because the chip is mounted close to surrounding power planes
and picks up enough DC bias to exceed the smallest range.

The chip is not wedged by the saturation: a sysfs write of a wider
range to in_magn_x_scale recovers it on the next conversion, and a
UDEV rule on add of the IIO device is a viable steady-state
workaround. What the DT property buys is the probe-time window: the
in-tree consumers we use (sensorfw's iio-sensors-adaptor and the
geomagnetic / orientation services on top of it) start polling
in_magn_x_raw essentially as soon as the device node appears and
treat the 0xF000 sentinel as a legitimate sample. Until a UDEV rule
fires and commits the wider range, every read returns the stuck
sentinel, and on slow-boot paths the consumer may have already
cached a bogus calibration baseline by the time UDEV catches up.

st,fullscale-milligauss lets the device tree declare a wider
initial range up-front so the correct range is in effect before any
IIO consumer can open the device, and keeps the board-specific
magnetometer calibration alongside the rest of the hardware
description rather than splitting it between DTS and per-distro
UDEV rules.

The full property name is spelled out rather than abbreviated to
"-mg" because this same binding file already covers ST accelerometers
where the conventional shorthand "mg" reads as milli-g (acceleration);
the explicit "-milligauss" suffix makes the unit unambiguous if a
similar tunable is ever introduced for the accel/gyro/pressure
families.

The property is scoped to magnetometer compatibles via allOf/if-then
clauses, with per-family enum lists of the accepted milligauss
values (1300..8100 for LSM303DLH/DLHC/DLM, 4000..16000 for
LIS3MDL/LSM9DS1/LSM303C). LSM303AGR / LIS2MDL / IIS2MDC have a
single fixed full-scale (15000 mg) with no register to switch
ranges, so the property is rejected outright for them. DTSes that
misspell the value, place the property on an accelerometer /
gyroscope / pressure node, or set it on a fixed-FS magnetometer
fail dt_binding_check rather than emitting a runtime warning.

The property is purely additive: if absent, drivers fall back to
their existing chip default. No existing in-tree DTS is affected.

Assisted-by: Claude:claude-opus-4-7 dt_binding_check checkpatch
Assisted-by: Sashiko:claude-opus-4-7
Signed-off-by: Herman van Hazendonk <github.com@xxxxxxxxxx>
---
 .../devicetree/bindings/iio/st,st-sensors.yaml     | 71 ++++++++++++++++++++++
 1 file changed, 71 insertions(+)

diff --git a/Documentation/devicetree/bindings/iio/st,st-sensors.yaml b/Documentation/devicetree/bindings/iio/st,st-sensors.yaml
index a1a958215cdb..f0805604c849 100644
--- a/Documentation/devicetree/bindings/iio/st,st-sensors.yaml
+++ b/Documentation/devicetree/bindings/iio/st,st-sensors.yaml
@@ -126,6 +126,13 @@ properties:
   mount-matrix:
     description: an optional 3x3 mounting rotation matrix.
 
+  st,fullscale-milligauss:
+    description:
+      Initial magnetometer full-scale at probe time, in milligauss.
+      Per-chip allowed values are enumerated in the allOf clauses
+      below.
+    $ref: /schemas/types.yaml#/definitions/uint32
+
 allOf:
   - if:
       properties:
@@ -163,6 +170,70 @@ allOf:
           maxItems: 1
         st,drdy-int-pin: false
 
+  # Per-chip enum lists for st,fullscale-milligauss. Out-of-range
+  # values fail dt_binding_check instead of being demoted to a
+  # runtime warning by the driver.
+  - if:
+      properties:
+        compatible:
+          contains:
+            enum:
+              - st,lsm303dlh-magn
+              - st,lsm303dlhc-magn
+              - st,lsm303dlm-magn
+    then:
+      properties:
+        st,fullscale-milligauss:
+          enum: [1300, 1900, 2500, 4000, 4700, 5600, 8100]
+
+  - if:
+      properties:
+        compatible:
+          contains:
+            enum:
+              - st,lis3mdl-magn
+              - st,lsm303c-magn
+              - st,lsm9ds1-magn
+    then:
+      properties:
+        st,fullscale-milligauss:
+          enum: [4000, 8000, 12000, 16000]
+
+  # Single fixed full-scale, no register to switch: reject.
+  - if:
+      properties:
+        compatible:
+          contains:
+            enum:
+              - st,iis2mdc
+              - st,lis2mdl
+              - st,lsm303agr-magn
+    then:
+      properties:
+        st,fullscale-milligauss: false
+
+  # Reject st,fullscale-milligauss on non-magnetometer compatibles.
+  # Keep this enum in sync with the three magn clauses above when
+  # adding a new magnetometer compatible.
+  - if:
+      not:
+        properties:
+          compatible:
+            contains:
+              enum:
+                - st,iis2mdc
+                - st,lis2mdl
+                - st,lis3mdl-magn
+                - st,lsm303agr-magn
+                - st,lsm303c-magn
+                - st,lsm303dlh-magn
+                - st,lsm303dlhc-magn
+                - st,lsm303dlm-magn
+                - st,lsm9ds1-magn
+    then:
+      properties:
+        st,fullscale-milligauss: false
+
 required:
   - compatible
   - reg

-- 
2.43.0