[PATCH v2 00/10] iio mount matrix - revitalize missing bindings documentation and provide code for bmc150, bmg160, bma180, itg3200, hmc584x

[PATCH v2 00/10] iio mount matrix - revitalize missing bindings documentation and provide code for bmc150, bmg160, bma180, itg3200, hmc584x

[H. Nikolaus Schaller]

Fixes V2:
* make get_mount_matrix() functions more readable (use temp variable)
  (suggested by Jonathan and Andy)
* add these readability improvements also for ak8975 and mpu6050
  (suggested by Jonathan and Andy)
* squash bindings documentation into single commit for better discussion
  (suggested by Linus)
* FOR DISCUSSION: add some more clarifications to the bindings documentation
  and an attempt to define the magnetometer orientation
* add "iio: Allow to read mount matrix from ACPI" to the beginning of
  the series to make it compile
  (suggested by Andy)
* replace of_iio_read_mount_matrix() by iio_read_mount_matrix()
  (required by "iio: Allow to read mount matrix from ACPI")
* drop patch to convert bma180 to devm (potential race)
  (suggested by Jonathan)

PATCH V1 2019-02-20 15:01:02:
This patch series adds the mount-matrix to several iio sensor drivers
used in handheld devices.

The mount-matrix translates the quite arbitrary orientation of the sensor
on some printed circuit board to user-tangible orientation in handheld
devices that relates to typical screen orientation.

There was a bindings documentation by Linus Walleij but the patch
did not make it into mainline. Therefore I resend it here.

Next I have added some clarifications (at least I hope it clarifies)
in a second patch.

Finally, the patch set implements the hooks for the mount matrix
in several iio drivers: bmc150, bma180, bmg160, itg3200, hmc5843.
This includes also one patch for the bma180 to convert it to devm API.

We use them in different variants of the omap3-gta04 so a separate
patch set will provide device tree additions for them.


Andy Shevchenko (1):
  iio: Allow to read mount matrix from ACPI

H. Nikolaus Schaller (8):
  iio: accel: bmc150: add mount matrix support
  iio: accel: bma180: add mount matrix support
  iio: gyro: bmg160: add mount matrix support
  iio: gyro: itg3200: add mount matrix support
  iio: magnetometer: bmc150: add mount matrix support
  iio: magnetometer: hmc5843: add mount matrix support
  iio: mpu6050: improve code readability
  iio: ak8975: improve code readability

Linus Walleij (1):
  iio: document bindings for mounting matrices

 .../devicetree/bindings/iio/mount-matrix.txt  | 204 ++++++++++++++++++
 drivers/iio/accel/bma180.c                    |  18 +-
 drivers/iio/accel/bmc150-accel-core.c         |  21 ++
 drivers/iio/accel/kxsd9.c                     |   4 +-
 drivers/iio/gyro/bmg160_core.c                |  21 ++
 drivers/iio/gyro/itg3200_core.c               |  20 ++
 drivers/iio/gyro/mpu3050-core.c               |   3 +-
 drivers/iio/imu/inv_mpu6050/inv_mpu_core.c    |  10 +-
 drivers/iio/industrialio-core.c               |  46 ++--
 drivers/iio/magnetometer/ak8974.c             |   5 +-
 drivers/iio/magnetometer/ak8975.c             |  13 +-
 drivers/iio/magnetometer/bmc150_magn.c        |  21 ++
 drivers/iio/magnetometer/hmc5843.h            |   1 +
 drivers/iio/magnetometer/hmc5843_core.c       |  20 +-
 include/linux/iio/gyro/itg3200.h              |   1 +
 include/linux/iio/iio.h                       |   4 +-
 16 files changed, 361 insertions(+), 51 deletions(-)
 create mode 100644 Documentation/devicetree/bindings/iio/mount-matrix.txt

-- 
2.19.1

[PATCH v2 01/10] iio: Allow to read mount matrix from ACPI

[H. Nikolaus Schaller]

From: Andy Shevchenko <andriy.shevchenko@linux.intel.com>

Currently mount matrix is allowed in Device Tree, though there is
no technical issue to extend it to support ACPI.

Convert the function to use device_property_read_string_array() and
thus allow to read mount matrix from ACPI if available.

Example of use in _DSD method:

  Name (_DSD, Package ()
  {
     ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
     Package ()
     {
        Package () { "mount-matrix", Package() {
                "1", "0",     "0",
                "0", "0.866", "0.5",
                "0", "-0.5",  "0.866",
        } },
     }
  })

At the same time drop the "of" prefix from its name and
convert current users.

No functional change intended.

Signed-off-by: Andy Shevchenko <andriy.shevchenko@linux.intel.com>
---
 drivers/iio/accel/kxsd9.c                  |  4 +-
 drivers/iio/gyro/mpu3050-core.c            |  3 +-
 drivers/iio/imu/inv_mpu6050/inv_mpu_core.c |  4 +-
 drivers/iio/industrialio-core.c            | 46 +++++++++-------------
 drivers/iio/magnetometer/ak8974.c          |  5 +--
 drivers/iio/magnetometer/ak8975.c          |  5 +--
 include/linux/iio/iio.h                    |  4 +-
 7 files changed, 28 insertions(+), 43 deletions(-)

diff --git a/drivers/iio/accel/kxsd9.c b/drivers/iio/accel/kxsd9.c
index 0c0df4fce420..70c60db62247 100644
--- a/drivers/iio/accel/kxsd9.c
+++ b/drivers/iio/accel/kxsd9.c
@@ -420,9 +420,7 @@ int kxsd9_common_probe(struct device *dev,
 	indio_dev->available_scan_masks = kxsd9_scan_masks;
 
 	/* Read the mounting matrix, if present */
-	ret = of_iio_read_mount_matrix(dev,
-				       "mount-matrix",
-				       &st->orientation);
+	ret = iio_read_mount_matrix(dev, "mount-matrix", &st->orientation);
 	if (ret)
 		return ret;
 
diff --git a/drivers/iio/gyro/mpu3050-core.c b/drivers/iio/gyro/mpu3050-core.c
index 77fac81a3adc..8200e48f561b 100644
--- a/drivers/iio/gyro/mpu3050-core.c
+++ b/drivers/iio/gyro/mpu3050-core.c
@@ -1149,8 +1149,7 @@ int mpu3050_common_probe(struct device *dev,
 	mpu3050->divisor = 99;
 
 	/* Read the mounting matrix, if present */
-	ret = of_iio_read_mount_matrix(dev, "mount-matrix",
-				       &mpu3050->orientation);
+	ret = iio_read_mount_matrix(dev, "mount-matrix", &mpu3050->orientation);
 	if (ret)
 		return ret;
 
diff --git a/drivers/iio/imu/inv_mpu6050/inv_mpu_core.c b/drivers/iio/imu/inv_mpu6050/inv_mpu_core.c
index 1e428c196a82..533d1f8321ac 100644
--- a/drivers/iio/imu/inv_mpu6050/inv_mpu_core.c
+++ b/drivers/iio/imu/inv_mpu6050/inv_mpu_core.c
@@ -990,8 +990,8 @@ int inv_mpu_core_probe(struct regmap *regmap, int irq, const char *name,
 
 	pdata = dev_get_platdata(dev);
 	if (!pdata) {
-		result = of_iio_read_mount_matrix(dev, "mount-matrix",
-						  &st->orientation);
+		result = iio_read_mount_matrix(dev, "mount-matrix",
+					       &st->orientation);
 		if (result) {
 			dev_err(dev, "Failed to retrieve mounting matrix %d\n",
 				result);
diff --git a/drivers/iio/industrialio-core.c b/drivers/iio/industrialio-core.c
index 4f5cd9f60870..0a40f1df49c7 100644
--- a/drivers/iio/industrialio-core.c
+++ b/drivers/iio/industrialio-core.c
@@ -19,6 +19,7 @@
 #include <linux/device.h>
 #include <linux/fs.h>
 #include <linux/poll.h>
+#include <linux/property.h>
 #include <linux/sched.h>
 #include <linux/wait.h>
 #include <linux/cdev.h>
@@ -525,8 +526,8 @@ ssize_t iio_show_mount_matrix(struct iio_dev *indio_dev, uintptr_t priv,
 EXPORT_SYMBOL_GPL(iio_show_mount_matrix);
 
 /**
- * of_iio_read_mount_matrix() - retrieve iio device mounting matrix from
- *                              device-tree "mount-matrix" property
+ * iio_read_mount_matrix() - retrieve iio device mounting matrix from
+ *                           device "mount-matrix" property
  * @dev:	device the mounting matrix property is assigned to
  * @propname:	device specific mounting matrix property name
  * @matrix:	where to store retrieved matrix
@@ -536,40 +537,29 @@ EXPORT_SYMBOL_GPL(iio_show_mount_matrix);
  *
  * Return: 0 if success, or a negative error code on failure.
  */
-#ifdef CONFIG_OF
-int of_iio_read_mount_matrix(const struct device *dev,
-			     const char *propname,
-			     struct iio_mount_matrix *matrix)
+int iio_read_mount_matrix(struct device *dev, const char *propname,
+			  struct iio_mount_matrix *matrix)
 {
-	if (dev->of_node) {
-		int err = of_property_read_string_array(dev->of_node,
-				propname, matrix->rotation,
-				ARRAY_SIZE(iio_mount_idmatrix.rotation));
+	size_t len = ARRAY_SIZE(iio_mount_idmatrix.rotation);
+	int err;
 
-		if (err == ARRAY_SIZE(iio_mount_idmatrix.rotation))
-			return 0;
+	err = device_property_read_string_array(dev, propname,
+						matrix->rotation, len);
+	if (err == len)
+		return 0;
 
-		if (err >= 0)
-			/* Invalid number of matrix entries. */
-			return -EINVAL;
+	if (err >= 0)
+		/* Invalid number of matrix entries. */
+		return -EINVAL;
 
-		if (err != -EINVAL)
-			/* Invalid matrix declaration format. */
-			return err;
-	}
+	if (err != -EINVAL)
+		/* Invalid matrix declaration format. */
+		return err;
 
 	/* Matrix was not declared at all: fallback to identity. */
 	return iio_setup_mount_idmatrix(dev, matrix);
 }
-#else
-int of_iio_read_mount_matrix(const struct device *dev,
-			     const char *propname,
-			     struct iio_mount_matrix *matrix)
-{
-	return iio_setup_mount_idmatrix(dev, matrix);
-}
-#endif
-EXPORT_SYMBOL(of_iio_read_mount_matrix);
+EXPORT_SYMBOL(iio_read_mount_matrix);
 
 static ssize_t __iio_format_value(char *buf, size_t len, unsigned int type,
 				  int size, const int *vals)
diff --git a/drivers/iio/magnetometer/ak8974.c b/drivers/iio/magnetometer/ak8974.c
index 93be1f4c0f27..f4d0a6c0fde7 100644
--- a/drivers/iio/magnetometer/ak8974.c
+++ b/drivers/iio/magnetometer/ak8974.c
@@ -733,9 +733,8 @@ static int ak8974_probe(struct i2c_client *i2c,
 	ak8974->i2c = i2c;
 	mutex_init(&ak8974->lock);
 
-	ret = of_iio_read_mount_matrix(&i2c->dev,
-				       "mount-matrix",
-				       &ak8974->orientation);
+	ret = iio_read_mount_matrix(&i2c->dev, "mount-matrix",
+				    &ak8974->orientation);
 	if (ret)
 		return ret;
 
diff --git a/drivers/iio/magnetometer/ak8975.c b/drivers/iio/magnetometer/ak8975.c
index d430b80808ef..db7214ac514c 100644
--- a/drivers/iio/magnetometer/ak8975.c
+++ b/drivers/iio/magnetometer/ak8975.c
@@ -911,9 +911,8 @@ static int ak8975_probe(struct i2c_client *client,
 	data->eoc_irq = 0;
 
 	if (!pdata) {
-		err = of_iio_read_mount_matrix(&client->dev,
-					       "mount-matrix",
-					       &data->orientation);
+		err = iio_read_mount_matrix(&client->dev, "mount-matrix",
+					    &data->orientation);
 		if (err)
 			return err;
 	} else
diff --git a/include/linux/iio/iio.h b/include/linux/iio/iio.h
index a74cb177dc6f..bb10c1bee301 100644
--- a/include/linux/iio/iio.h
+++ b/include/linux/iio/iio.h
@@ -130,8 +130,8 @@ struct iio_mount_matrix {
 
 ssize_t iio_show_mount_matrix(struct iio_dev *indio_dev, uintptr_t priv,
 			      const struct iio_chan_spec *chan, char *buf);
-int of_iio_read_mount_matrix(const struct device *dev, const char *propname,
-			     struct iio_mount_matrix *matrix);
+int iio_read_mount_matrix(struct device *dev, const char *propname,
+			  struct iio_mount_matrix *matrix);
 
 typedef const struct iio_mount_matrix *
 	(iio_get_mount_matrix_t)(const struct iio_dev *indio_dev,
-- 
2.19.1

[PATCH v2 02/10] iio: document bindings for mounting matrices

[H. Nikolaus Schaller]

From: Linus Walleij <linus.walleij@linaro.org>

The mounting matrix for sensors was introduced in
commit dfc57732ad38 ("iio:core: mounting matrix support")

However the device tree bindings are very terse and since this is
a widely applicable property, we need a proper binding for it
that the other bindings can reference. This will also be useful
for other operating systems and sensor engineering at large.

I think all 3D sensors should support it, the current situation
is probably that the mounting information is confined in magic
userspace components rather than using the mounting matrix, which
is not good for portability and reuse.

Cc: Linus Walleij <linus.walleij@linaro.org>
Cc: Gregor Boirie <gregor.boirie@parrot.com>
Cc: Sebastian Reichel <sre@kernel.org>
Cc: Samu Onkalo <samu.onkalo@intel.com>
Cc: devicetree@vger.kernel.org
Signed-off-by: Linus Walleij <linus.walleij@linaro.org>
Signed-off-by: H. Nikolaus Schaller <hns@goldelico.com>
---
 .../devicetree/bindings/iio/mount-matrix.txt  | 204 ++++++++++++++++++
 1 file changed, 204 insertions(+)
 create mode 100644 Documentation/devicetree/bindings/iio/mount-matrix.txt

diff --git a/Documentation/devicetree/bindings/iio/mount-matrix.txt b/Documentation/devicetree/bindings/iio/mount-matrix.txt
new file mode 100644
index 000000000000..1b64c8b1f689
--- /dev/null
+++ b/Documentation/devicetree/bindings/iio/mount-matrix.txt
@@ -0,0 +1,204 @@
+For discussion. Unclear are:
+* is the definition of +/- values practical or counterintuitive?
+* are the definitions unambiguous and easy to follow?
+* are the examples correct?
+* should we have HOWTO engineer a correct matrix for a new device (without comparing to a different one)?
+
+====
+
+
+Mounting matrix
+
+The mounting matrix is a device tree property used to orient any IIO device
+that produce three-dimensional data in relation to the world where it is
+deployed.
+
+The purpose of the mounting matrix is to translate the sensor frame of
+reference into the device frame of reference using a translation matrix as
+defined in linear algebra.
+
+The typical usecase is that where a component has an internal representation
+of the (x,y,z) triplets, such as different registers to read these coordinates,
+and thus implying that the component should be mounted in a certain orientation
+relative to some specific device frame of reference.
+
+For example a device with some kind of screen, where the user is supposed to
+interact with the environment using an accelerometer, gyroscope or magnetometer
+mounted on the same chassis as this screen, will likely take the screen as
+reference to (x,y,z) orientation, with (x,y) corresponding to these axes on the
+screen and (z) being depth, the axis perpendicular to the screen.
+
+For a screen you probably want (x) coordinates to go from negative on the left
+to positive on the right, (y) from negative on the bottom to positive on top
+and (z) depth to be negative under the screen and positive in front of it,
+toward the face of the user.
+
+A sensor can be mounted in any angle along the axes relative to the frame of
+reference. This means that the sensor may be flipped upside-down, left-right,
+or tilted at any angle relative to the frame of reference.
+
+Another frame of reference is how the device with its sensor relates to the
+external world, the environment where the device is deployed. Usually the data
+from the sensor is used to figure out how the device is oriented with respect
+to this world. When using the mounting matrix, the sensor and device orientation
+becomes identical and we can focus on the data as it relates to the surrounding
+world.
+
+Device-to-world examples for some three-dimensional sensor types:
+
+- Accelerometers have their world frame of reference toward the center of
+  gravity, usually to the core of the planet. A reading of the (x,y,z) values
+  from the sensor will give a projection of the gravity vector through the
+  device relative to the center of the planet, i.e. relative to its surface at
+  this point. Up and down in the world relative to the device frame of
+  reference can thus be determined. and users would likely expect a value of
+  9.81 m/s^2 upwards along the (z) axis, i.e. out of the screen when the device
+  is held with its screen flat on the planets surface and 0 on the other axes,
+  as the gravity vector is projected 1:1 onto the sensors (z)-axis.
+
+  If you tilt the device, the g vector virtually coming out of the display
+  is projected onto the (x,y) plane of the display panel.
+
+  Example:
+
+         ^ z: +g                   ^ z: >0
+         !                        /!
+         ! x=y=0                 / ! x: > 0
+     +--------+             +--------+
+     !        !             !        !
+     +--------+             +--------+
+         !                    /
+         !                   /
+         v                  v
+      center of         center of
+       gravity           gravity
+
+
+  If the device is tilted to the left, you get a positive x value. If you point
+  its top towards surface, you get a negative y axis.
+
+     (---------)
+     !         !           y: -g
+     !         !             ^
+     !         !             !
+     !         !
+     !         !  x: +g <- z: +g  -> x: -g
+     ! 1  2  3 !
+     ! 4  5  6 !             !
+     ! 7  8  9 !             v
+     ! *  0  # !           y: +g
+     (---------)
+
+
+- Magnetometers (compasses) have their world frame of reference relative to the
+  geomagnetic field. The system orientation vis-a-vis the world is defined with
+  respect to the local earth geomagnetic reference frame where (y) is in the
+  ground plane and positive towards magnetic North, (x) is in the ground plane,
+  perpendicular to the North axis and positive towards the East and (z) is
+  perpendicular to the ground plane and positive upwards.
+
+
+     ^^^ North: y > 0
+
+     (---------)
+     !         !
+     !         !
+     !         !
+     !         !  >
+     !         !  > North: x > 0
+     ! 1  2  3 !  >
+     ! 4  5  6 !
+     ! 7  8  9 !
+     ! *  0  # !
+     (---------)
+
+  Since the geomagnetic field is not uniform this definition fails if we come
+  closer to the poles.
+
+  Sensors and driver can not and should not take care of this because there
+  are complex calculations and empirical data to be taken care of. We leave
+  this up to user space.
+
+  The definition we take:
+
+  If the device is placed at the equator and the top is pointing north, the
+  display is readable by a person standing upright on the earth surface, this
+  defines a positive y value.
+
+
+- Gyroscopes detects the movement relative the device itself. The angular
+  velocity is defined as orthogonal to the plane of rotation, so if you put the
+  device on a flat surface and spin it around the z axis (such as rotating a
+  device with a screen lying flat on a table), you should get a negative value
+  along the (z) axis if rotated clockwise, and a positive value if rotated
+  counter-clockwise according to the right-hand rule.
+
+
+     (---------)     y > 0
+     !         !     v---\
+     !         !
+     !         !
+     !         !      <--\
+     !         !         ! z > 0
+     ! 1  2  3 !       --/
+     ! 4  5  6 !
+     ! 7  8  9 !
+     ! *  0  # !
+     (---------)
+
+
+So unless the sensor is ideally mounted, we need a means to indicate the
+relative orientation of any given sensor of this type with respect to the
+frame of reference.
+
+To achieve this, use the device tree property "mount-matrix" for the sensor.
+
+This supplies a 3x3 rotation matrix in the strict linear algebraic sense,
+to orient the senor axes relative to a desired point of reference. This means
+the resulting values from the sensor, after scaling to proper units, should be
+multiplied by this matrix to give the proper vectors values in three-dimensional
+space, relative to the device or world point of reference.
+
+For more information, consult:
+https://en.wikipedia.org/wiki/Rotation_matrix
+
+The mounting matrix has the layout:
+
+ (mxx, myx, mzx)
+ (mxy, myy, mzy)
+ (mxz, myz, mzz)
+
+Values are intended to be multiplied as:
+
+  x' = mxx * x + myx * y + mzx * z
+  y' = mxy * x + myy * y + mzy * z
+  z' = mxz * x + myz * y + mzz * z
+
+It is represented as an array of strings containing the real values for
+producing the transformation matrix. The real values use a decimal point and
+a minus (-) to indicate a negative value.
+
+Examples:
+
+Identity matrix (nothing happens to the coordinates, which means the device was
+mechanically mounted in an ideal way and we need no transformation):
+
+mount-matrix = "1", "0", "0",
+               "0", "1", "0",
+               "0", "0", "1";
+
+The sensor is mounted 30 degrees (Pi/6 radians) tilted along the X axis, so we
+compensate by performing a -30 degrees rotation around the X axis:
+
+mount-matrix = "1", "0", "0",
+               "0", "0.866", "0.5",
+               "0", "-0.5", "0.866";
+
+The sensor is flipped 180 degrees (Pi radians) around the Z axis, i.e. mounted
+upside-down:
+
+mount-matrix = "0.998", "0.054", "0",
+               "-0.054", "0.998", "0",
+               "0", "0", "1";
+
+???: this does not match "180 degrees" - factors indicate ca. 3 degrees compensation
-- 
2.19.1

[PATCH v2 03/10] iio: accel: bmc150: add mount matrix support

[H. Nikolaus Schaller]

This patch allows to read a mount-matrix device tree
property and report to user-space or in-kernel iio
clients.

Signed-off-by: H. Nikolaus Schaller <hns@goldelico.com>
---
 drivers/iio/accel/bmc150-accel-core.c | 21 +++++++++++++++++++++
 1 file changed, 21 insertions(+)

diff --git a/drivers/iio/accel/bmc150-accel-core.c b/drivers/iio/accel/bmc150-accel-core.c
index 383c802eb5b8..b4e2d9b04e1d 100644
--- a/drivers/iio/accel/bmc150-accel-core.c
+++ b/drivers/iio/accel/bmc150-accel-core.c
@@ -204,6 +204,7 @@ struct bmc150_accel_data {
 	int ev_enable_state;
 	int64_t timestamp, old_timestamp; /* Only used in hw fifo mode. */
 	const struct bmc150_accel_chip_info *chip_info;
+	struct iio_mount_matrix orientation;
 };
 
 static const struct {
@@ -796,6 +797,20 @@ static ssize_t bmc150_accel_get_fifo_state(struct device *dev,
 	return sprintf(buf, "%d\n", state);
 }
 
+static const struct iio_mount_matrix *
+bmc150_accel_get_mount_matrix(const struct iio_dev *indio_dev,
+				const struct iio_chan_spec *chan)
+{
+	struct bmc150_accel_data *data = iio_priv(indio_dev);
+
+	return &data->orientation;
+}
+
+static const struct iio_chan_spec_ext_info bmc150_accel_ext_info[] = {
+	IIO_MOUNT_MATRIX(IIO_SHARED_BY_DIR, bmc150_accel_get_mount_matrix),
+	{ }
+};
+
 static IIO_CONST_ATTR(hwfifo_watermark_min, "1");
 static IIO_CONST_ATTR(hwfifo_watermark_max,
 		      __stringify(BMC150_ACCEL_FIFO_LENGTH));
@@ -978,6 +993,7 @@ static const struct iio_event_spec bmc150_accel_event = {
 		.shift = 16 - (bits),					\
 		.endianness = IIO_LE,					\
 	},								\
+	.ext_info = bmc150_accel_ext_info,				\
 	.event_spec = &bmc150_accel_event,				\
 	.num_event_specs = 1						\
 }
@@ -1555,6 +1571,11 @@ int bmc150_accel_core_probe(struct device *dev, struct regmap *regmap, int irq,
 
 	data->regmap = regmap;
 
+	ret = iio_read_mount_matrix(dev, "mount-matrix",
+				     &data->orientation);
+	if (ret)
+		return ret;
+
 	ret = bmc150_accel_chip_init(data);
 	if (ret < 0)
 		return ret;
-- 
2.19.1

[PATCH v2 04/10] iio: accel: bma180: add mount matrix support

[H. Nikolaus Schaller]

This patch allows to read a mount-matrix device tree
property and report to user-space or in-kernel iio
clients.

Signed-off-by: H. Nikolaus Schaller <hns@goldelico.com>
---
 drivers/iio/accel/bma180.c | 18 +++++++++++++++++-
 1 file changed, 17 insertions(+), 1 deletion(-)

diff --git a/drivers/iio/accel/bma180.c b/drivers/iio/accel/bma180.c
index cb9765a3de60..f9720a1e8a7c 100644
--- a/drivers/iio/accel/bma180.c
+++ b/drivers/iio/accel/bma180.c
@@ -116,6 +116,7 @@ struct bma180_data {
 	struct i2c_client *client;
 	struct iio_trigger *trig;
 	const struct bma180_part_info *part_info;
+	struct iio_mount_matrix orientation;
 	struct mutex mutex;
 	bool sleep_state;
 	int scale;
@@ -561,6 +562,15 @@ static int bma180_set_power_mode(struct iio_dev *indio_dev,
 	return ret;
 }
 
+static const struct iio_mount_matrix *
+bma180_accel_get_mount_matrix(const struct iio_dev *indio_dev,
+				const struct iio_chan_spec *chan)
+{
+	struct bma180_data *data = iio_priv(indio_dev);
+
+	return &data->orientation;
+}
+
 static const struct iio_enum bma180_power_mode_enum = {
 	.items = bma180_power_modes,
 	.num_items = ARRAY_SIZE(bma180_power_modes),
@@ -571,7 +581,8 @@ static const struct iio_enum bma180_power_mode_enum = {
 static const struct iio_chan_spec_ext_info bma180_ext_info[] = {
 	IIO_ENUM("power_mode", true, &bma180_power_mode_enum),
 	IIO_ENUM_AVAILABLE("power_mode", &bma180_power_mode_enum),
-	{ },
+	IIO_MOUNT_MATRIX(IIO_SHARED_BY_DIR, bma180_accel_get_mount_matrix),
+	{ }
 };
 
 #define BMA180_ACC_CHANNEL(_axis, _bits) {				\
@@ -722,6 +733,11 @@ static int bma180_probe(struct i2c_client *client,
 		chip = id->driver_data;
 	data->part_info = &bma180_part_info[chip];
 
+	ret = iio_read_mount_matrix(&client->dev, "mount-matrix",
+				&data->orientation);
+	if (ret)
+		return ret;
+
 	ret = data->part_info->chip_config(data);
 	if (ret < 0)
 		goto err_chip_disable;
-- 
2.19.1

[PATCH v2 05/10] iio: gyro: bmg160: add mount matrix support

[H. Nikolaus Schaller]

This patch allows to read a mount-matrix device tree
property and report to user-space or in-kernel iio
clients.

Signed-off-by: H. Nikolaus Schaller <hns@goldelico.com>
---
 drivers/iio/gyro/bmg160_core.c | 21 +++++++++++++++++++++
 1 file changed, 21 insertions(+)

diff --git a/drivers/iio/gyro/bmg160_core.c b/drivers/iio/gyro/bmg160_core.c
index 63ca31628a93..e7b38adee39a 100644
--- a/drivers/iio/gyro/bmg160_core.c
+++ b/drivers/iio/gyro/bmg160_core.c
@@ -102,6 +102,7 @@ struct bmg160_data {
 	struct regmap *regmap;
 	struct iio_trigger *dready_trig;
 	struct iio_trigger *motion_trig;
+	struct iio_mount_matrix orientation;
 	struct mutex mutex;
 	s16 buffer[8];
 	u32 dps_range;
@@ -794,6 +795,20 @@ static int bmg160_write_event_config(struct iio_dev *indio_dev,
 	return 0;
 }
 
+static const struct iio_mount_matrix *
+bmg160_get_mount_matrix(const struct iio_dev *indio_dev,
+			 const struct iio_chan_spec *chan)
+{
+	struct bmg160_data *data = iio_priv(indio_dev);
+
+	return &data->orientation;
+}
+
+static const struct iio_chan_spec_ext_info bmg160_ext_info[] = {
+	IIO_MOUNT_MATRIX(IIO_SHARED_BY_DIR, bmg160_get_mount_matrix),
+	{ }
+};
+
 static IIO_CONST_ATTR_SAMP_FREQ_AVAIL("100 200 400 1000 2000");
 
 static IIO_CONST_ATTR(in_anglvel_scale_available,
@@ -831,6 +846,7 @@ static const struct iio_event_spec bmg160_event = {
 		.storagebits = 16,					\
 		.endianness = IIO_LE,					\
 	},								\
+	.ext_info = bmg160_ext_info,					\
 	.event_spec = &bmg160_event,					\
 	.num_event_specs = 1						\
 }
@@ -1075,6 +1091,11 @@ int bmg160_core_probe(struct device *dev, struct regmap *regmap, int irq,
 	data->irq = irq;
 	data->regmap = regmap;
 
+	ret = iio_read_mount_matrix(dev, "mount-matrix",
+				&data->orientation);
+	if (ret)
+		return ret;
+
 	ret = bmg160_chip_init(data);
 	if (ret < 0)
 		return ret;
-- 
2.19.1

[PATCH v2 06/10] iio: gyro: itg3200: add mount matrix support

[H. Nikolaus Schaller]

This patch allows to read a mount-matrix device tree
property and report to user-space or in-kernel iio
clients.

Signed-off-by: H. Nikolaus Schaller <hns@goldelico.com>
---
 drivers/iio/gyro/itg3200_core.c  | 20 ++++++++++++++++++++
 include/linux/iio/gyro/itg3200.h |  1 +
 2 files changed, 21 insertions(+)

diff --git a/drivers/iio/gyro/itg3200_core.c b/drivers/iio/gyro/itg3200_core.c
index 7adecb562c81..203a6be33b70 100644
--- a/drivers/iio/gyro/itg3200_core.c
+++ b/drivers/iio/gyro/itg3200_core.c
@@ -242,6 +242,20 @@ static int itg3200_initial_setup(struct iio_dev *indio_dev)
 	return ret;
 }
 
+static const struct iio_mount_matrix *
+itg3200_get_mount_matrix(const struct iio_dev *indio_dev,
+			  const struct iio_chan_spec *chan)
+{
+	struct itg3200 *data = iio_priv(indio_dev);
+
+	return &data->orientation;
+}
+
+static const struct iio_chan_spec_ext_info itg3200_ext_info[] = {
+	IIO_MOUNT_MATRIX(IIO_SHARED_BY_DIR, itg3200_get_mount_matrix),
+	{ }
+};
+
 #define ITG3200_ST						\
 	{ .sign = 's', .realbits = 16, .storagebits = 16, .endianness = IIO_BE }
 
@@ -255,6 +269,7 @@ static int itg3200_initial_setup(struct iio_dev *indio_dev)
 	.address = ITG3200_REG_GYRO_ ## _mod ## OUT_H, \
 	.scan_index = ITG3200_SCAN_GYRO_ ## _mod, \
 	.scan_type = ITG3200_ST, \
+	.ext_info = itg3200_ext_info, \
 }
 
 static const struct iio_chan_spec itg3200_channels[] = {
@@ -297,6 +312,11 @@ static int itg3200_probe(struct i2c_client *client,
 
 	st = iio_priv(indio_dev);
 
+	ret = iio_read_mount_matrix(&client->dev, "mount-matrix",
+				&st->orientation);
+	if (ret)
+		return ret;
+
 	i2c_set_clientdata(client, indio_dev);
 	st->i2c = client;
 
diff --git a/include/linux/iio/gyro/itg3200.h b/include/linux/iio/gyro/itg3200.h
index 2a820850f284..0a30fddccfb3 100644
--- a/include/linux/iio/gyro/itg3200.h
+++ b/include/linux/iio/gyro/itg3200.h
@@ -104,6 +104,7 @@
 struct itg3200 {
 	struct i2c_client	*i2c;
 	struct iio_trigger	*trig;
+	struct iio_mount_matrix orientation;
 };
 
 enum ITG3200_SCAN_INDEX {
-- 
2.19.1

[PATCH v2 07/10] iio: magnetometer: bmc150: add mount matrix support

[H. Nikolaus Schaller]

This patch allows to read a mount-matrix device tree
property and report to user-space or in-kernel iio
clients.

Signed-off-by: H. Nikolaus Schaller <hns@goldelico.com>
---
 drivers/iio/magnetometer/bmc150_magn.c | 21 +++++++++++++++++++++
 1 file changed, 21 insertions(+)

diff --git a/drivers/iio/magnetometer/bmc150_magn.c b/drivers/iio/magnetometer/bmc150_magn.c
index d91cb845e3d6..b0d8b036d9bb 100644
--- a/drivers/iio/magnetometer/bmc150_magn.c
+++ b/drivers/iio/magnetometer/bmc150_magn.c
@@ -143,6 +143,7 @@ struct bmc150_magn_data {
 	 */
 	struct mutex mutex;
 	struct regmap *regmap;
+	struct iio_mount_matrix orientation;
 	/* 4 x 32 bits for x, y z, 4 bytes align, 64 bits timestamp */
 	s32 buffer[6];
 	struct iio_trigger *dready_trig;
@@ -612,6 +613,20 @@ static ssize_t bmc150_magn_show_samp_freq_avail(struct device *dev,
 	return len;
 }
 
+static const struct iio_mount_matrix *
+bmc150_magn_get_mount_matrix(const struct iio_dev *indio_dev,
+			      const struct iio_chan_spec *chan)
+{
+	struct bmc150_magn_data *data = iio_priv(indio_dev);
+
+	return &data->orientation;
+}
+
+static const struct iio_chan_spec_ext_info bmc150_magn_ext_info[] = {
+	IIO_MOUNT_MATRIX(IIO_SHARED_BY_DIR, bmc150_magn_get_mount_matrix),
+	{ }
+};
+
 static IIO_DEV_ATTR_SAMP_FREQ_AVAIL(bmc150_magn_show_samp_freq_avail);
 
 static struct attribute *bmc150_magn_attributes[] = {
@@ -638,6 +653,7 @@ static const struct attribute_group bmc150_magn_attrs_group = {
 		.storagebits = 32,					\
 		.endianness = IIO_LE					\
 	},								\
+	.ext_info = bmc150_magn_ext_info,				\
 }
 
 static const struct iio_chan_spec bmc150_magn_channels[] = {
@@ -861,6 +877,11 @@ int bmc150_magn_probe(struct device *dev, struct regmap *regmap,
 	data->irq = irq;
 	data->dev = dev;
 
+	ret = iio_read_mount_matrix(dev, "mount-matrix",
+				&data->orientation);
+	if (ret)
+		return ret;
+
 	if (!name && ACPI_HANDLE(dev))
 		name = bmc150_magn_match_acpi_device(dev);
 
-- 
2.19.1

[PATCH v2 08/10] iio: magnetometer: hmc5843: add mount matrix support

[H. Nikolaus Schaller]

This patch allows to read a mount-matrix device tree
property and report to user-space or in-kernel iio
clients.

Signed-off-by: H. Nikolaus Schaller <hns@goldelico.com>
---
 drivers/iio/magnetometer/hmc5843.h      |  1 +
 drivers/iio/magnetometer/hmc5843_core.c | 20 ++++++++++++++++++--
 2 files changed, 19 insertions(+), 2 deletions(-)

diff --git a/drivers/iio/magnetometer/hmc5843.h b/drivers/iio/magnetometer/hmc5843.h
index a75224cf99df..e3e22d2508d3 100644
--- a/drivers/iio/magnetometer/hmc5843.h
+++ b/drivers/iio/magnetometer/hmc5843.h
@@ -43,6 +43,7 @@ struct hmc5843_data {
 	struct mutex lock;
 	struct regmap *regmap;
 	const struct hmc5843_chip_info *variant;
+	struct iio_mount_matrix orientation;
 	__be16 buffer[8];
 };
 
diff --git a/drivers/iio/magnetometer/hmc5843_core.c b/drivers/iio/magnetometer/hmc5843_core.c
index ada142fb7aa3..05629ec56d80 100644
--- a/drivers/iio/magnetometer/hmc5843_core.c
+++ b/drivers/iio/magnetometer/hmc5843_core.c
@@ -237,6 +237,15 @@ int hmc5843_set_measurement_configuration(struct iio_dev *indio_dev,
 	return hmc5843_set_meas_conf(data, meas_conf);
 }
 
+static const struct iio_mount_matrix *
+hmc5843_get_mount_matrix(const struct iio_dev *indio_dev,
+			  const struct iio_chan_spec *chan)
+{
+	struct hmc5843_data *data = iio_priv(indio_dev);
+
+	return &data->orientation;
+}
+
 static const struct iio_enum hmc5843_meas_conf_enum = {
 	.items = hmc5843_meas_conf_modes,
 	.num_items = ARRAY_SIZE(hmc5843_meas_conf_modes),
@@ -247,7 +256,8 @@ static const struct iio_enum hmc5843_meas_conf_enum = {
 static const struct iio_chan_spec_ext_info hmc5843_ext_info[] = {
 	IIO_ENUM("meas_conf", true, &hmc5843_meas_conf_enum),
 	IIO_ENUM_AVAILABLE("meas_conf", &hmc5843_meas_conf_enum),
-	{ },
+	IIO_MOUNT_MATRIX(IIO_SHARED_BY_DIR, hmc5843_get_mount_matrix),
+	{ }
 };
 
 static const struct iio_enum hmc5983_meas_conf_enum = {
@@ -260,7 +270,8 @@ static const struct iio_enum hmc5983_meas_conf_enum = {
 static const struct iio_chan_spec_ext_info hmc5983_ext_info[] = {
 	IIO_ENUM("meas_conf", true, &hmc5983_meas_conf_enum),
 	IIO_ENUM_AVAILABLE("meas_conf", &hmc5983_meas_conf_enum),
-	{ },
+	IIO_MOUNT_MATRIX(IIO_SHARED_BY_DIR, hmc5843_get_mount_matrix),
+	{ }
 };
 
 static
@@ -635,6 +646,11 @@ int hmc5843_common_probe(struct device *dev, struct regmap *regmap,
 	data->variant = &hmc5843_chip_info_tbl[id];
 	mutex_init(&data->lock);
 
+	ret = iio_read_mount_matrix(dev, "mount-matrix",
+				&data->orientation);
+	if (ret)
+		return ret;
+
 	indio_dev->dev.parent = dev;
 	indio_dev->name = name;
 	indio_dev->info = &hmc5843_info;
-- 
2.19.1

[PATCH v2 09/10] iio: mpu6050: improve code readability

[H. Nikolaus Schaller]

- use temporary variable in get_mount_matrix()
- remove , after { }

Signed-off-by: H. Nikolaus Schaller <hns@goldelico.com>
---
 drivers/iio/imu/inv_mpu6050/inv_mpu_core.c | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/drivers/iio/imu/inv_mpu6050/inv_mpu_core.c b/drivers/iio/imu/inv_mpu6050/inv_mpu_core.c
index 533d1f8321ac..e7721b6fb441 100644
--- a/drivers/iio/imu/inv_mpu6050/inv_mpu_core.c
+++ b/drivers/iio/imu/inv_mpu6050/inv_mpu_core.c
@@ -765,12 +765,14 @@ static const struct iio_mount_matrix *
 inv_get_mount_matrix(const struct iio_dev *indio_dev,
 		     const struct iio_chan_spec *chan)
 {
-	return &((struct inv_mpu6050_state *)iio_priv(indio_dev))->orientation;
+	struct inv_mpu6050_state *data = iio_priv(indio_dev);
+
+	return &data->orientation;
 }
 
 static const struct iio_chan_spec_ext_info inv_ext_info[] = {
 	IIO_MOUNT_MATRIX(IIO_SHARED_BY_TYPE, inv_get_mount_matrix),
-	{ },
+	{ }
 };
 
 #define INV_MPU6050_CHAN(_type, _channel2, _index)                    \
-- 
2.19.1

[PATCH v2 10/10] iio: ak8975: improve code readability

[H. Nikolaus Schaller]

- use temporary variable in get_mount_matrix()
- remove , after { }

Signed-off-by: H. Nikolaus Schaller <hns@goldelico.com>
---
 drivers/iio/magnetometer/ak8975.c | 8 +++++---
 1 file changed, 5 insertions(+), 3 deletions(-)

diff --git a/drivers/iio/magnetometer/ak8975.c b/drivers/iio/magnetometer/ak8975.c
index db7214ac514c..43d08c089792 100644
--- a/drivers/iio/magnetometer/ak8975.c
+++ b/drivers/iio/magnetometer/ak8975.c
@@ -746,12 +746,14 @@ static const struct iio_mount_matrix *
 ak8975_get_mount_matrix(const struct iio_dev *indio_dev,
 			const struct iio_chan_spec *chan)
 {
-	return &((struct ak8975_data *)iio_priv(indio_dev))->orientation;
+	struct ak8975_data *data = iio_priv(indio_dev);
+
+	return &data->orientation;
 }
 
 static const struct iio_chan_spec_ext_info ak8975_ext_info[] = {
 	IIO_MOUNT_MATRIX(IIO_SHARED_BY_DIR, ak8975_get_mount_matrix),
-	{ },
+	{ }
 };
 
 #define AK8975_CHANNEL(axis, index)					\
@@ -792,7 +794,7 @@ static const struct acpi_device_id ak_acpi_match[] = {
 	{"AK09911", AK09911},
 	{"AKM9911", AK09911},
 	{"AK09912", AK09912},
-	{ },
+	{ }
 };
 MODULE_DEVICE_TABLE(acpi, ak_acpi_match);
 #endif
-- 
2.19.1

Re: [PATCH v2 00/10] iio mount matrix - revitalize missing bindings documentation and provide code for bmc150, bmg160, bma180, itg3200, hmc584x

[Andy Shevchenko]

On Thu, Feb 21, 2019 at 7:04 PM H. Nikolaus Schaller <hns@goldelico.com> wrote:
>
> Fixes V2:
> * make get_mount_matrix() functions more readable (use temp variable)
>   (suggested by Jonathan and Andy)
> * add these readability improvements also for ak8975 and mpu6050
>   (suggested by Jonathan and Andy)
> * squash bindings documentation into single commit for better discussion
>   (suggested by Linus)
> * FOR DISCUSSION: add some more clarifications to the bindings documentation
>   and an attempt to define the magnetometer orientation
> * add "iio: Allow to read mount matrix from ACPI" to the beginning of
>   the series to make it compile
>   (suggested by Andy)
> * replace of_iio_read_mount_matrix() by iio_read_mount_matrix()
>   (required by "iio: Allow to read mount matrix from ACPI")
> * drop patch to convert bma180 to devm (potential race)
>   (suggested by Jonathan)
>
> PATCH V1 2019-02-20 15:01:02:
> This patch series adds the mount-matrix to several iio sensor drivers
> used in handheld devices.
>
> The mount-matrix translates the quite arbitrary orientation of the sensor
> on some printed circuit board to user-tangible orientation in handheld
> devices that relates to typical screen orientation.
>
> There was a bindings documentation by Linus Walleij but the patch
> did not make it into mainline. Therefore I resend it here.
>
> Next I have added some clarifications (at least I hope it clarifies)
> in a second patch.
>
> Finally, the patch set implements the hooks for the mount matrix
> in several iio drivers: bmc150, bma180, bmg160, itg3200, hmc5843.
> This includes also one patch for the bma180 to convert it to devm API.
>
> We use them in different variants of the omap3-gta04 so a separate
> patch set will provide device tree additions for them.
>

Thank you, it looks nice.
FWIW,
Reviewed-by: Andy Shevchenko <andy.shevchenko@gmail.com>


>
> Andy Shevchenko (1):
>   iio: Allow to read mount matrix from ACPI
>
> H. Nikolaus Schaller (8):
>   iio: accel: bmc150: add mount matrix support
>   iio: accel: bma180: add mount matrix support
>   iio: gyro: bmg160: add mount matrix support
>   iio: gyro: itg3200: add mount matrix support
>   iio: magnetometer: bmc150: add mount matrix support
>   iio: magnetometer: hmc5843: add mount matrix support
>   iio: mpu6050: improve code readability
>   iio: ak8975: improve code readability
>
> Linus Walleij (1):
>   iio: document bindings for mounting matrices
>
>  .../devicetree/bindings/iio/mount-matrix.txt  | 204 ++++++++++++++++++
>  drivers/iio/accel/bma180.c                    |  18 +-
>  drivers/iio/accel/bmc150-accel-core.c         |  21 ++
>  drivers/iio/accel/kxsd9.c                     |   4 +-
>  drivers/iio/gyro/bmg160_core.c                |  21 ++
>  drivers/iio/gyro/itg3200_core.c               |  20 ++
>  drivers/iio/gyro/mpu3050-core.c               |   3 +-
>  drivers/iio/imu/inv_mpu6050/inv_mpu_core.c    |  10 +-
>  drivers/iio/industrialio-core.c               |  46 ++--
>  drivers/iio/magnetometer/ak8974.c             |   5 +-
>  drivers/iio/magnetometer/ak8975.c             |  13 +-
>  drivers/iio/magnetometer/bmc150_magn.c        |  21 ++
>  drivers/iio/magnetometer/hmc5843.h            |   1 +
>  drivers/iio/magnetometer/hmc5843_core.c       |  20 +-
>  include/linux/iio/gyro/itg3200.h              |   1 +
>  include/linux/iio/iio.h                       |   4 +-
>  16 files changed, 361 insertions(+), 51 deletions(-)
>  create mode 100644 Documentation/devicetree/bindings/iio/mount-matrix.txt
>
> --
> 2.19.1
>


-- 
With Best Regards,
Andy Shevchenko

Re: [PATCH v2 00/10] iio mount matrix - revitalize missing bindings documentation and provide code for bmc150, bmg160, bma180, itg3200, hmc584x

[Linus Walleij]

On Thu, Feb 21, 2019 at 6:03 PM H. Nikolaus Schaller <hns@goldelico.com> wrote:

> Fixes V2:
> * make get_mount_matrix() functions more readable (use temp variable)
>   (suggested by Jonathan and Andy)
> * add these readability improvements also for ak8975 and mpu6050
>   (suggested by Jonathan and Andy)
> * squash bindings documentation into single commit for better discussion
>   (suggested by Linus)
> * FOR DISCUSSION: add some more clarifications to the bindings documentation
>   and an attempt to define the magnetometer orientation
> * add "iio: Allow to read mount matrix from ACPI" to the beginning of
>   the series to make it compile
>   (suggested by Andy)
> * replace of_iio_read_mount_matrix() by iio_read_mount_matrix()
>   (required by "iio: Allow to read mount matrix from ACPI")
> * drop patch to convert bma180 to devm (potential race)
>   (suggested by Jonathan)

I'm a big fan of this series and I really like what you did with my old
patch!
Reviewed-by: Linus Walleij <linus.walleij@linaro.org>

Yours,
Linus Walleij

Re: [PATCH v2 02/10] iio: document bindings for mounting matrices

[Rob Herring]

On Thu, 21 Feb 2019 18:02:47 +0100, "H. Nikolaus Schaller" wrote:
> From: Linus Walleij <linus.walleij@linaro.org>
> 
> The mounting matrix for sensors was introduced in
> commit dfc57732ad38 ("iio:core: mounting matrix support")
> 
> However the device tree bindings are very terse and since this is
> a widely applicable property, we need a proper binding for it
> that the other bindings can reference. This will also be useful
> for other operating systems and sensor engineering at large.
> 
> I think all 3D sensors should support it, the current situation
> is probably that the mounting information is confined in magic
> userspace components rather than using the mounting matrix, which
> is not good for portability and reuse.
> 
> Cc: Linus Walleij <linus.walleij@linaro.org>
> Cc: Gregor Boirie <gregor.boirie@parrot.com>
> Cc: Sebastian Reichel <sre@kernel.org>
> Cc: Samu Onkalo <samu.onkalo@intel.com>
> Cc: devicetree@vger.kernel.org
> Signed-off-by: Linus Walleij <linus.walleij@linaro.org>
> Signed-off-by: H. Nikolaus Schaller <hns@goldelico.com>
> ---
>  .../devicetree/bindings/iio/mount-matrix.txt  | 204 ++++++++++++++++++
>  1 file changed, 204 insertions(+)
>  create mode 100644 Documentation/devicetree/bindings/iio/mount-matrix.txt
> 

Reviewed-by: Rob Herring <robh@kernel.org>

Re: [PATCH v2 02/10] iio: document bindings for mounting matrices

[Jonathan Corbet]

On Thu, 21 Feb 2019 18:02:47 +0100
"H. Nikolaus Schaller" <hns@goldelico.com> wrote:

> From: Linus Walleij <linus.walleij@linaro.org>
> 
> The mounting matrix for sensors was introduced in
> commit dfc57732ad38 ("iio:core: mounting matrix support")
> 
> However the device tree bindings are very terse and since this is
> a widely applicable property, we need a proper binding for it
> that the other bindings can reference. This will also be useful
> for other operating systems and sensor engineering at large.
> 
> I think all 3D sensors should support it, the current situation
> is probably that the mounting information is confined in magic
> userspace components rather than using the mounting matrix, which
> is not good for portability and reuse.
> 
> Cc: Linus Walleij <linus.walleij@linaro.org>
> Cc: Gregor Boirie <gregor.boirie@parrot.com>
> Cc: Sebastian Reichel <sre@kernel.org>
> Cc: Samu Onkalo <samu.onkalo@intel.com>
> Cc: devicetree@vger.kernel.org
> Signed-off-by: Linus Walleij <linus.walleij@linaro.org>
> Signed-off-by: H. Nikolaus Schaller <hns@goldelico.com>
> ---
>  .../devicetree/bindings/iio/mount-matrix.txt  | 204 ++++++++++++++++++
>  1 file changed, 204 insertions(+)
>  create mode 100644 Documentation/devicetree/bindings/iio/mount-matrix.txt

So forgive me, but I have to ask: what are the chances of getting this
file in RST format?  It's 99% of the way there now, finishing the job
would allow it to be integrated into our docs tree.

It should probably have an SPDX line too.

Thanks,

jon

Re: [PATCH v2 02/10] iio: document bindings for mounting matrices

[Linus Walleij]

Hi Jon,

On Mon, Feb 25, 2019 at 5:32 PM Jonathan Corbet <corbet@lwn.net> wrote:

> >  .../devicetree/bindings/iio/mount-matrix.txt  | 204 ++++++++++++++++++

So this is a device tree binding.

> So forgive me, but I have to ask: what are the chances of getting this
> file in RST format?  It's 99% of the way there now, finishing the job
> would allow it to be integrated into our docs tree.
>
> It should probably have an SPDX line too.

The recent direction of the Device Tree bindings are not in the RST
direction but in the direction of using another formal structure: YAML
schemas.

See e.g. Documentation/devicetree/bindings/example-schema.yaml

The YAML schema makes it possible to verify device trees and examples
inside the bindings to the specification using a context-free grammar.

If we can join the RST and YAML ambitions is a good question. RST
has nice typesetting properties, YAML has nice grammatic properties.

Yours,
Linus Walleij

Re: [PATCH v2 02/10] iio: document bindings for mounting matrices

[Jonathan Corbet]

On Mon, 25 Feb 2019 19:24:36 +0100
Linus Walleij <linus.walleij@linaro.org> wrote:

> > >  .../devicetree/bindings/iio/mount-matrix.txt  | 204 ++++++++++++++++++  
> 
> So this is a device tree binding.

Ah, duh, I blame caffeine deficiency.  Ignore me, sorry for the noise.

jon

Re: [PATCH v2 02/10] iio: document bindings for mounting matrices

[Rob Herring]

On Mon, Feb 25, 2019 at 12:24 PM Linus Walleij <linus.walleij@linaro.org> wrote:
>
> Hi Jon,
>
> On Mon, Feb 25, 2019 at 5:32 PM Jonathan Corbet <corbet@lwn.net> wrote:
>
> > >  .../devicetree/bindings/iio/mount-matrix.txt  | 204 ++++++++++++++++++
>
> So this is a device tree binding.
>
> > So forgive me, but I have to ask: what are the chances of getting this
> > file in RST format?  It's 99% of the way there now, finishing the job
> > would allow it to be integrated into our docs tree.
> >
> > It should probably have an SPDX line too.
>
> The recent direction of the Device Tree bindings are not in the RST
> direction but in the direction of using another formal structure: YAML
> schemas.
>
> See e.g. Documentation/devicetree/bindings/example-schema.yaml
>
> The YAML schema makes it possible to verify device trees and examples
> inside the bindings to the specification using a context-free grammar.
>
> If we can join the RST and YAML ambitions is a good question. RST
> has nice typesetting properties, YAML has nice grammatic properties.

In fact there has been some experimentation there. The 'description'
portion of DT schema can be RST. And the rest being structured data
could be transformed to RST. Grant did some experiments there. The
idea being to generate the DT spec from schema (rather than integrate
into the kernel docs). But not much progress there and it's not
something I'm spending time on ATM.

Rob

Re: [PATCH v2 01/10] iio: Allow to read mount matrix from ACPI

[Jonathan Cameron]

On Thu, 21 Feb 2019 18:02:46 +0100
"H. Nikolaus Schaller" <hns@goldelico.com> wrote:

> From: Andy Shevchenko <andriy.shevchenko@linux.intel.com>
> 
> Currently mount matrix is allowed in Device Tree, though there is
> no technical issue to extend it to support ACPI.
> 
> Convert the function to use device_property_read_string_array() and
> thus allow to read mount matrix from ACPI if available.
> 
> Example of use in _DSD method:
> 
>   Name (_DSD, Package ()
>   {
>      ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
>      Package ()
>      {
>         Package () { "mount-matrix", Package() {
>                 "1", "0",     "0",
>                 "0", "0.866", "0.5",
>                 "0", "-0.5",  "0.866",
>         } },
>      }
>   })
> 
> At the same time drop the "of" prefix from its name and
> convert current users.
> 
> No functional change intended.
> 
> Signed-off-by: Andy Shevchenko <andriy.shevchenko@linux.intel.com>
I'm not so very fussed about this one as Andy had posted it to the
list previously, but in theory you should have added your signed-off-by
as an intermediate person who handled the patch.

Otherwise, great and applied to the togreg branch of iio.git and
pushed out as testing for the autobuilders to see if we got anything
wrong.

Thanks,

Jonathan

> ---
>  drivers/iio/accel/kxsd9.c                  |  4 +-
>  drivers/iio/gyro/mpu3050-core.c            |  3 +-
>  drivers/iio/imu/inv_mpu6050/inv_mpu_core.c |  4 +-
>  drivers/iio/industrialio-core.c            | 46 +++++++++-------------
>  drivers/iio/magnetometer/ak8974.c          |  5 +--
>  drivers/iio/magnetometer/ak8975.c          |  5 +--
>  include/linux/iio/iio.h                    |  4 +-
>  7 files changed, 28 insertions(+), 43 deletions(-)
> 
> diff --git a/drivers/iio/accel/kxsd9.c b/drivers/iio/accel/kxsd9.c
> index 0c0df4fce420..70c60db62247 100644
> --- a/drivers/iio/accel/kxsd9.c
> +++ b/drivers/iio/accel/kxsd9.c
> @@ -420,9 +420,7 @@ int kxsd9_common_probe(struct device *dev,
>  	indio_dev->available_scan_masks = kxsd9_scan_masks;
>  
>  	/* Read the mounting matrix, if present */
> -	ret = of_iio_read_mount_matrix(dev,
> -				       "mount-matrix",
> -				       &st->orientation);
> +	ret = iio_read_mount_matrix(dev, "mount-matrix", &st->orientation);
>  	if (ret)
>  		return ret;
>  
> diff --git a/drivers/iio/gyro/mpu3050-core.c b/drivers/iio/gyro/mpu3050-core.c
> index 77fac81a3adc..8200e48f561b 100644
> --- a/drivers/iio/gyro/mpu3050-core.c
> +++ b/drivers/iio/gyro/mpu3050-core.c
> @@ -1149,8 +1149,7 @@ int mpu3050_common_probe(struct device *dev,
>  	mpu3050->divisor = 99;
>  
>  	/* Read the mounting matrix, if present */
> -	ret = of_iio_read_mount_matrix(dev, "mount-matrix",
> -				       &mpu3050->orientation);
> +	ret = iio_read_mount_matrix(dev, "mount-matrix", &mpu3050->orientation);
>  	if (ret)
>  		return ret;
>  
> diff --git a/drivers/iio/imu/inv_mpu6050/inv_mpu_core.c b/drivers/iio/imu/inv_mpu6050/inv_mpu_core.c
> index 1e428c196a82..533d1f8321ac 100644
> --- a/drivers/iio/imu/inv_mpu6050/inv_mpu_core.c
> +++ b/drivers/iio/imu/inv_mpu6050/inv_mpu_core.c
> @@ -990,8 +990,8 @@ int inv_mpu_core_probe(struct regmap *regmap, int irq, const char *name,
>  
>  	pdata = dev_get_platdata(dev);
>  	if (!pdata) {
> -		result = of_iio_read_mount_matrix(dev, "mount-matrix",
> -						  &st->orientation);
> +		result = iio_read_mount_matrix(dev, "mount-matrix",
> +					       &st->orientation);
>  		if (result) {
>  			dev_err(dev, "Failed to retrieve mounting matrix %d\n",
>  				result);
> diff --git a/drivers/iio/industrialio-core.c b/drivers/iio/industrialio-core.c
> index 4f5cd9f60870..0a40f1df49c7 100644
> --- a/drivers/iio/industrialio-core.c
> +++ b/drivers/iio/industrialio-core.c
> @@ -19,6 +19,7 @@
>  #include <linux/device.h>
>  #include <linux/fs.h>
>  #include <linux/poll.h>
> +#include <linux/property.h>
>  #include <linux/sched.h>
>  #include <linux/wait.h>
>  #include <linux/cdev.h>
> @@ -525,8 +526,8 @@ ssize_t iio_show_mount_matrix(struct iio_dev *indio_dev, uintptr_t priv,
>  EXPORT_SYMBOL_GPL(iio_show_mount_matrix);
>  
>  /**
> - * of_iio_read_mount_matrix() - retrieve iio device mounting matrix from
> - *                              device-tree "mount-matrix" property
> + * iio_read_mount_matrix() - retrieve iio device mounting matrix from
> + *                           device "mount-matrix" property
>   * @dev:	device the mounting matrix property is assigned to
>   * @propname:	device specific mounting matrix property name
>   * @matrix:	where to store retrieved matrix
> @@ -536,40 +537,29 @@ EXPORT_SYMBOL_GPL(iio_show_mount_matrix);
>   *
>   * Return: 0 if success, or a negative error code on failure.
>   */
> -#ifdef CONFIG_OF
> -int of_iio_read_mount_matrix(const struct device *dev,
> -			     const char *propname,
> -			     struct iio_mount_matrix *matrix)
> +int iio_read_mount_matrix(struct device *dev, const char *propname,
> +			  struct iio_mount_matrix *matrix)
>  {
> -	if (dev->of_node) {
> -		int err = of_property_read_string_array(dev->of_node,
> -				propname, matrix->rotation,
> -				ARRAY_SIZE(iio_mount_idmatrix.rotation));
> +	size_t len = ARRAY_SIZE(iio_mount_idmatrix.rotation);
> +	int err;
>  
> -		if (err == ARRAY_SIZE(iio_mount_idmatrix.rotation))
> -			return 0;
> +	err = device_property_read_string_array(dev, propname,
> +						matrix->rotation, len);
> +	if (err == len)
> +		return 0;
>  
> -		if (err >= 0)
> -			/* Invalid number of matrix entries. */
> -			return -EINVAL;
> +	if (err >= 0)
> +		/* Invalid number of matrix entries. */
> +		return -EINVAL;
>  
> -		if (err != -EINVAL)
> -			/* Invalid matrix declaration format. */
> -			return err;
> -	}
> +	if (err != -EINVAL)
> +		/* Invalid matrix declaration format. */
> +		return err;
>  
>  	/* Matrix was not declared at all: fallback to identity. */
>  	return iio_setup_mount_idmatrix(dev, matrix);
>  }
> -#else
> -int of_iio_read_mount_matrix(const struct device *dev,
> -			     const char *propname,
> -			     struct iio_mount_matrix *matrix)
> -{
> -	return iio_setup_mount_idmatrix(dev, matrix);
> -}
> -#endif
> -EXPORT_SYMBOL(of_iio_read_mount_matrix);
> +EXPORT_SYMBOL(iio_read_mount_matrix);
>  
>  static ssize_t __iio_format_value(char *buf, size_t len, unsigned int type,
>  				  int size, const int *vals)
> diff --git a/drivers/iio/magnetometer/ak8974.c b/drivers/iio/magnetometer/ak8974.c
> index 93be1f4c0f27..f4d0a6c0fde7 100644
> --- a/drivers/iio/magnetometer/ak8974.c
> +++ b/drivers/iio/magnetometer/ak8974.c
> @@ -733,9 +733,8 @@ static int ak8974_probe(struct i2c_client *i2c,
>  	ak8974->i2c = i2c;
>  	mutex_init(&ak8974->lock);
>  
> -	ret = of_iio_read_mount_matrix(&i2c->dev,
> -				       "mount-matrix",
> -				       &ak8974->orientation);
> +	ret = iio_read_mount_matrix(&i2c->dev, "mount-matrix",
> +				    &ak8974->orientation);
>  	if (ret)
>  		return ret;
>  
> diff --git a/drivers/iio/magnetometer/ak8975.c b/drivers/iio/magnetometer/ak8975.c
> index d430b80808ef..db7214ac514c 100644
> --- a/drivers/iio/magnetometer/ak8975.c
> +++ b/drivers/iio/magnetometer/ak8975.c
> @@ -911,9 +911,8 @@ static int ak8975_probe(struct i2c_client *client,
>  	data->eoc_irq = 0;
>  
>  	if (!pdata) {
> -		err = of_iio_read_mount_matrix(&client->dev,
> -					       "mount-matrix",
> -					       &data->orientation);
> +		err = iio_read_mount_matrix(&client->dev, "mount-matrix",
> +					    &data->orientation);
>  		if (err)
>  			return err;
>  	} else
> diff --git a/include/linux/iio/iio.h b/include/linux/iio/iio.h
> index a74cb177dc6f..bb10c1bee301 100644
> --- a/include/linux/iio/iio.h
> +++ b/include/linux/iio/iio.h
> @@ -130,8 +130,8 @@ struct iio_mount_matrix {
>  
>  ssize_t iio_show_mount_matrix(struct iio_dev *indio_dev, uintptr_t priv,
>  			      const struct iio_chan_spec *chan, char *buf);
> -int of_iio_read_mount_matrix(const struct device *dev, const char *propname,
> -			     struct iio_mount_matrix *matrix);
> +int iio_read_mount_matrix(struct device *dev, const char *propname,
> +			  struct iio_mount_matrix *matrix);
>  
>  typedef const struct iio_mount_matrix *
>  	(iio_get_mount_matrix_t)(const struct iio_dev *indio_dev,

Re: [PATCH v2 02/10] iio: document bindings for mounting matrices

[Jonathan Cameron]

On Thu, 21 Feb 2019 18:02:47 +0100
"H. Nikolaus Schaller" <hns@goldelico.com> wrote:

> From: Linus Walleij <linus.walleij@linaro.org>
> 
> The mounting matrix for sensors was introduced in
> commit dfc57732ad38 ("iio:core: mounting matrix support")
> 
> However the device tree bindings are very terse and since this is
> a widely applicable property, we need a proper binding for it
> that the other bindings can reference. This will also be useful
> for other operating systems and sensor engineering at large.
> 
> I think all 3D sensors should support it, the current situation
> is probably that the mounting information is confined in magic
> userspace components rather than using the mounting matrix, which
> is not good for portability and reuse.
> 
> Cc: Linus Walleij <linus.walleij@linaro.org>
> Cc: Gregor Boirie <gregor.boirie@parrot.com>
> Cc: Sebastian Reichel <sre@kernel.org>
> Cc: Samu Onkalo <samu.onkalo@intel.com>
> Cc: devicetree@vger.kernel.org
> Signed-off-by: Linus Walleij <linus.walleij@linaro.org>
> Signed-off-by: H. Nikolaus Schaller <hns@goldelico.com>
Hi Nikolaus

A few minor notes inline.

> ---
>  .../devicetree/bindings/iio/mount-matrix.txt  | 204 ++++++++++++++++++
>  1 file changed, 204 insertions(+)
>  create mode 100644 Documentation/devicetree/bindings/iio/mount-matrix.txt
> 
> diff --git a/Documentation/devicetree/bindings/iio/mount-matrix.txt b/Documentation/devicetree/bindings/iio/mount-matrix.txt
> new file mode 100644
> index 000000000000..1b64c8b1f689
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/iio/mount-matrix.txt
> @@ -0,0 +1,204 @@
> +For discussion. Unclear are:
> +* is the definition of +/- values practical or counterintuitive?
> +* are the definitions unambiguous and easy to follow?
> +* are the examples correct?
> +* should we have HOWTO engineer a correct matrix for a new device (without comparing to a different one)?
> +
> +====
> +
> +
> +Mounting matrix
> +
> +The mounting matrix is a device tree property used to orient any IIO device

Minor, but DT bindings are in theory not Linux specific and IIO is, so
should be "any device"

> +that produce three-dimensional data in relation to the world where it is
> +deployed.
> +
> +The purpose of the mounting matrix is to translate the sensor frame of
> +reference into the device frame of reference using a translation matrix as
> +defined in linear algebra.
> +
> +The typical usecase is that where a component has an internal representation
> +of the (x,y,z) triplets, such as different registers to read these coordinates,
> +and thus implying that the component should be mounted in a certain orientation
> +relative to some specific device frame of reference.
> +
> +For example a device with some kind of screen, where the user is supposed to
> +interact with the environment using an accelerometer, gyroscope or magnetometer
> +mounted on the same chassis as this screen, will likely take the screen as
> +reference to (x,y,z) orientation, with (x,y) corresponding to these axes on the
> +screen and (z) being depth, the axis perpendicular to the screen.
> +
> +For a screen you probably want (x) coordinates to go from negative on the left
> +to positive on the right, (y) from negative on the bottom to positive on top
> +and (z) depth to be negative under the screen and positive in front of it,
> +toward the face of the user.
> +
> +A sensor can be mounted in any angle along the axes relative to the frame of
> +reference. This means that the sensor may be flipped upside-down, left-right,
> +or tilted at any angle relative to the frame of reference.
> +
> +Another frame of reference is how the device with its sensor relates to the
> +external world, the environment where the device is deployed. Usually the data
> +from the sensor is used to figure out how the device is oriented with respect
> +to this world. When using the mounting matrix, the sensor and device orientation
> +becomes identical and we can focus on the data as it relates to the surrounding
> +world.
> +
> +Device-to-world examples for some three-dimensional sensor types:
> +
> +- Accelerometers have their world frame of reference toward the center of
> +  gravity, usually to the core of the planet. A reading of the (x,y,z) values
> +  from the sensor will give a projection of the gravity vector through the
> +  device relative to the center of the planet, i.e. relative to its surface at
> +  this point. Up and down in the world relative to the device frame of
> +  reference can thus be determined. and users would likely expect a value of
> +  9.81 m/s^2 upwards along the (z) axis, i.e. out of the screen when the device
> +  is held with its screen flat on the planets surface and 0 on the other axes,
> +  as the gravity vector is projected 1:1 onto the sensors (z)-axis.

Nitpick: Screen is face down or face up?  Someone might think a screen is
flat when looking up at them from the floor or the other way up.
I 'think' it's face down in the following...


> +
> +  If you tilt the device, the g vector virtually coming out of the display
> +  is projected onto the (x,y) plane of the display panel.
> +
> +  Example:
> +

space after > for z. Or making it consistent anyway.
Hmm. 

> +         ^ z: +g                   ^ z: >0
> +         !                        /!
> +         ! x=y=0                 / ! x: > 0
> +     +--------+             +--------+
> +     !        !             !        !
> +     +--------+             +--------+
> +         !                    /
> +         !                   /
> +         v                  v
> +      center of         center of
> +       gravity           gravity
> +
> +
> +  If the device is tilted to the left, you get a positive x value. If you point
> +  its top towards surface, you get a negative y axis.
> +
> +     (---------)
> +     !         !           y: -g
> +     !         !             ^
> +     !         !             !
> +     !         !
> +     !         !  x: +g <- z: +g  -> x: -g
> +     ! 1  2  3 !
> +     ! 4  5  6 !             !
> +     ! 7  8  9 !             v
> +     ! *  0  # !           y: +g
> +     (---------)
> +
> +
> +- Magnetometers (compasses) have their world frame of reference relative to the
> +  geomagnetic field. The system orientation vis-a-vis the world is defined with
> +  respect to the local earth geomagnetic reference frame where (y) is in the
> +  ground plane and positive towards magnetic North, (x) is in the ground plane,
> +  perpendicular to the North axis and positive towards the East and (z) is
> +  perpendicular to the ground plane and positive upwards.
> +
> +
> +     ^^^ North: y > 0
> +
> +     (---------)
> +     !         !
> +     !         !
> +     !         !
> +     !         !  >
> +     !         !  > North: x > 0
> +     ! 1  2  3 !  >
> +     ! 4  5  6 !
> +     ! 7  8  9 !
> +     ! *  0  # !
> +     (---------)
> +
> +  Since the geomagnetic field is not uniform this definition fails if we come
> +  closer to the poles.
> +
> +  Sensors and driver can not and should not take care of this because there
> +  are complex calculations and empirical data to be taken care of. We leave
> +  this up to user space.
> +
> +  The definition we take:
> +
> +  If the device is placed at the equator and the top is pointing north, the
> +  display is readable by a person standing upright on the earth surface, this
> +  defines a positive y value.
Nice definition. <wonders how consistent it is at the equator - meh close enough :)>
> +
> +
> +- Gyroscopes detects the movement relative the device itself. The angular
> +  velocity is defined as orthogonal to the plane of rotation, so if you put the
> +  device on a flat surface and spin it around the z axis (such as rotating a
> +  device with a screen lying flat on a table), you should get a negative value
> +  along the (z) axis if rotated clockwise, and a positive value if rotated
> +  counter-clockwise according to the right-hand rule.
> +
> +
> +     (---------)     y > 0
> +     !         !     v---\
> +     !         !
> +     !         !
> +     !         !      <--\
> +     !         !         ! z > 0
> +     ! 1  2  3 !       --/
> +     ! 4  5  6 !
> +     ! 7  8  9 !
> +     ! *  0  # !
> +     (---------)
> +
> +
> +So unless the sensor is ideally mounted, we need a means to indicate the
> +relative orientation of any given sensor of this type with respect to the
> +frame of reference.
> +
> +To achieve this, use the device tree property "mount-matrix" for the sensor.
> +
> +This supplies a 3x3 rotation matrix in the strict linear algebraic sense,
> +to orient the senor axes relative to a desired point of reference. This means
> +the resulting values from the sensor, after scaling to proper units, should be
> +multiplied by this matrix to give the proper vectors values in three-dimensional
> +space, relative to the device or world point of reference.
> +
> +For more information, consult:
> +https://en.wikipedia.org/wiki/Rotation_matrix
> +
> +The mounting matrix has the layout:
> +
> + (mxx, myx, mzx)
> + (mxy, myy, mzy)
> + (mxz, myz, mzz)
> +
> +Values are intended to be multiplied as:
> +
> +  x' = mxx * x + myx * y + mzx * z
> +  y' = mxy * x + myy * y + mzy * z
> +  z' = mxz * x + myz * y + mzz * z
> +
> +It is represented as an array of strings containing the real values for
> +producing the transformation matrix. The real values use a decimal point and
> +a minus (-) to indicate a negative value.

I'd drop the decimal point and negative as both fairly obvious and this
sentence can currently be read as a decimal point is necessary for a negative.

> +
> +Examples:
> +
> +Identity matrix (nothing happens to the coordinates, which means the device was
> +mechanically mounted in an ideal way and we need no transformation):
> +
> +mount-matrix = "1", "0", "0",
> +               "0", "1", "0",
> +               "0", "0", "1";
> +
> +The sensor is mounted 30 degrees (Pi/6 radians) tilted along the X axis, so we
> +compensate by performing a -30 degrees rotation around the X axis:
> +
> +mount-matrix = "1", "0", "0",
> +               "0", "0.866", "0.5",
> +               "0", "-0.5", "0.866";
> +
> +The sensor is flipped 180 degrees (Pi radians) around the Z axis, i.e. mounted
> +upside-down:
> +
> +mount-matrix = "0.998", "0.054", "0",
> +               "-0.054", "0.998", "0",
> +               "0", "0", "1";
> +
> +???: this does not match "180 degrees" - factors indicate ca. 3 degrees compensation
Yes. Good to say this.

Very nice indeed, just these little tidy ups and I'm very happy with the
result!

Jonathan

Re: [PATCH v2 03/10] iio: accel: bmc150: add mount matrix support

[Jonathan Cameron]

On Thu, 21 Feb 2019 18:02:48 +0100
"H. Nikolaus Schaller" <hns@goldelico.com> wrote:

> This patch allows to read a mount-matrix device tree
> property and report to user-space or in-kernel iio
> clients.
> 
> Signed-off-by: H. Nikolaus Schaller <hns@goldelico.com>
Applied.

Thanks,

Jonathan

> ---
>  drivers/iio/accel/bmc150-accel-core.c | 21 +++++++++++++++++++++
>  1 file changed, 21 insertions(+)
> 
> diff --git a/drivers/iio/accel/bmc150-accel-core.c b/drivers/iio/accel/bmc150-accel-core.c
> index 383c802eb5b8..b4e2d9b04e1d 100644
> --- a/drivers/iio/accel/bmc150-accel-core.c
> +++ b/drivers/iio/accel/bmc150-accel-core.c
> @@ -204,6 +204,7 @@ struct bmc150_accel_data {
>  	int ev_enable_state;
>  	int64_t timestamp, old_timestamp; /* Only used in hw fifo mode. */
>  	const struct bmc150_accel_chip_info *chip_info;
> +	struct iio_mount_matrix orientation;
>  };
>  
>  static const struct {
> @@ -796,6 +797,20 @@ static ssize_t bmc150_accel_get_fifo_state(struct device *dev,
>  	return sprintf(buf, "%d\n", state);
>  }
>  
> +static const struct iio_mount_matrix *
> +bmc150_accel_get_mount_matrix(const struct iio_dev *indio_dev,
> +				const struct iio_chan_spec *chan)
> +{
> +	struct bmc150_accel_data *data = iio_priv(indio_dev);
> +
> +	return &data->orientation;
> +}
> +
> +static const struct iio_chan_spec_ext_info bmc150_accel_ext_info[] = {
> +	IIO_MOUNT_MATRIX(IIO_SHARED_BY_DIR, bmc150_accel_get_mount_matrix),
> +	{ }
> +};
> +
>  static IIO_CONST_ATTR(hwfifo_watermark_min, "1");
>  static IIO_CONST_ATTR(hwfifo_watermark_max,
>  		      __stringify(BMC150_ACCEL_FIFO_LENGTH));
> @@ -978,6 +993,7 @@ static const struct iio_event_spec bmc150_accel_event = {
>  		.shift = 16 - (bits),					\
>  		.endianness = IIO_LE,					\
>  	},								\
> +	.ext_info = bmc150_accel_ext_info,				\
>  	.event_spec = &bmc150_accel_event,				\
>  	.num_event_specs = 1						\
>  }
> @@ -1555,6 +1571,11 @@ int bmc150_accel_core_probe(struct device *dev, struct regmap *regmap, int irq,
>  
>  	data->regmap = regmap;
>  
> +	ret = iio_read_mount_matrix(dev, "mount-matrix",
> +				     &data->orientation);
> +	if (ret)
> +		return ret;
> +
>  	ret = bmc150_accel_chip_init(data);
>  	if (ret < 0)
>  		return ret;

Re: [PATCH v2 04/10] iio: accel: bma180: add mount matrix support

[Jonathan Cameron]

On Thu, 21 Feb 2019 18:02:49 +0100
"H. Nikolaus Schaller" <hns@goldelico.com> wrote:

> This patch allows to read a mount-matrix device tree
> property and report to user-space or in-kernel iio
> clients.
> 
> Signed-off-by: H. Nikolaus Schaller <hns@goldelico.com>
Applied.

Thanks,

Jonathan

> ---
>  drivers/iio/accel/bma180.c | 18 +++++++++++++++++-
>  1 file changed, 17 insertions(+), 1 deletion(-)
> 
> diff --git a/drivers/iio/accel/bma180.c b/drivers/iio/accel/bma180.c
> index cb9765a3de60..f9720a1e8a7c 100644
> --- a/drivers/iio/accel/bma180.c
> +++ b/drivers/iio/accel/bma180.c
> @@ -116,6 +116,7 @@ struct bma180_data {
>  	struct i2c_client *client;
>  	struct iio_trigger *trig;
>  	const struct bma180_part_info *part_info;
> +	struct iio_mount_matrix orientation;
>  	struct mutex mutex;
>  	bool sleep_state;
>  	int scale;
> @@ -561,6 +562,15 @@ static int bma180_set_power_mode(struct iio_dev *indio_dev,
>  	return ret;
>  }
>  
> +static const struct iio_mount_matrix *
> +bma180_accel_get_mount_matrix(const struct iio_dev *indio_dev,
> +				const struct iio_chan_spec *chan)
> +{
> +	struct bma180_data *data = iio_priv(indio_dev);
> +
> +	return &data->orientation;
> +}
> +
>  static const struct iio_enum bma180_power_mode_enum = {
>  	.items = bma180_power_modes,
>  	.num_items = ARRAY_SIZE(bma180_power_modes),
> @@ -571,7 +581,8 @@ static const struct iio_enum bma180_power_mode_enum = {
>  static const struct iio_chan_spec_ext_info bma180_ext_info[] = {
>  	IIO_ENUM("power_mode", true, &bma180_power_mode_enum),
>  	IIO_ENUM_AVAILABLE("power_mode", &bma180_power_mode_enum),
> -	{ },
> +	IIO_MOUNT_MATRIX(IIO_SHARED_BY_DIR, bma180_accel_get_mount_matrix),
> +	{ }
>  };
>  
>  #define BMA180_ACC_CHANNEL(_axis, _bits) {				\
> @@ -722,6 +733,11 @@ static int bma180_probe(struct i2c_client *client,
>  		chip = id->driver_data;
>  	data->part_info = &bma180_part_info[chip];
>  
> +	ret = iio_read_mount_matrix(&client->dev, "mount-matrix",
> +				&data->orientation);
> +	if (ret)
> +		return ret;
> +
>  	ret = data->part_info->chip_config(data);
>  	if (ret < 0)
>  		goto err_chip_disable;

Re: [PATCH v2 05/10] iio: gyro: bmg160: add mount matrix support

[Jonathan Cameron]

On Thu, 21 Feb 2019 18:02:50 +0100
"H. Nikolaus Schaller" <hns@goldelico.com> wrote:

> This patch allows to read a mount-matrix device tree
> property and report to user-space or in-kernel iio
> clients.
> 
> Signed-off-by: H. Nikolaus Schaller <hns@goldelico.com>
Applied.

Thanks,
> ---
>  drivers/iio/gyro/bmg160_core.c | 21 +++++++++++++++++++++
>  1 file changed, 21 insertions(+)
> 
> diff --git a/drivers/iio/gyro/bmg160_core.c b/drivers/iio/gyro/bmg160_core.c
> index 63ca31628a93..e7b38adee39a 100644
> --- a/drivers/iio/gyro/bmg160_core.c
> +++ b/drivers/iio/gyro/bmg160_core.c
> @@ -102,6 +102,7 @@ struct bmg160_data {
>  	struct regmap *regmap;
>  	struct iio_trigger *dready_trig;
>  	struct iio_trigger *motion_trig;
> +	struct iio_mount_matrix orientation;
>  	struct mutex mutex;
>  	s16 buffer[8];
>  	u32 dps_range;
> @@ -794,6 +795,20 @@ static int bmg160_write_event_config(struct iio_dev *indio_dev,
>  	return 0;
>  }
>  
> +static const struct iio_mount_matrix *
> +bmg160_get_mount_matrix(const struct iio_dev *indio_dev,
> +			 const struct iio_chan_spec *chan)
> +{
> +	struct bmg160_data *data = iio_priv(indio_dev);
> +
> +	return &data->orientation;
> +}
> +
> +static const struct iio_chan_spec_ext_info bmg160_ext_info[] = {
> +	IIO_MOUNT_MATRIX(IIO_SHARED_BY_DIR, bmg160_get_mount_matrix),
> +	{ }
> +};
> +
>  static IIO_CONST_ATTR_SAMP_FREQ_AVAIL("100 200 400 1000 2000");
>  
>  static IIO_CONST_ATTR(in_anglvel_scale_available,
> @@ -831,6 +846,7 @@ static const struct iio_event_spec bmg160_event = {
>  		.storagebits = 16,					\
>  		.endianness = IIO_LE,					\
>  	},								\
> +	.ext_info = bmg160_ext_info,					\
>  	.event_spec = &bmg160_event,					\
>  	.num_event_specs = 1						\
>  }
> @@ -1075,6 +1091,11 @@ int bmg160_core_probe(struct device *dev, struct regmap *regmap, int irq,
>  	data->irq = irq;
>  	data->regmap = regmap;
>  
> +	ret = iio_read_mount_matrix(dev, "mount-matrix",
> +				&data->orientation);
> +	if (ret)
> +		return ret;
> +
>  	ret = bmg160_chip_init(data);
>  	if (ret < 0)
>  		return ret;

Re: [PATCH v2 06/10] iio: gyro: itg3200: add mount matrix support

[Jonathan Cameron]

On Thu, 21 Feb 2019 18:02:51 +0100
"H. Nikolaus Schaller" <hns@goldelico.com> wrote:

> This patch allows to read a mount-matrix device tree
> property and report to user-space or in-kernel iio
> clients.
> 
> Signed-off-by: H. Nikolaus Schaller <hns@goldelico.com>
Applied.

Thanks,

Jonathan

> ---
>  drivers/iio/gyro/itg3200_core.c  | 20 ++++++++++++++++++++
>  include/linux/iio/gyro/itg3200.h |  1 +
>  2 files changed, 21 insertions(+)
> 
> diff --git a/drivers/iio/gyro/itg3200_core.c b/drivers/iio/gyro/itg3200_core.c
> index 7adecb562c81..203a6be33b70 100644
> --- a/drivers/iio/gyro/itg3200_core.c
> +++ b/drivers/iio/gyro/itg3200_core.c
> @@ -242,6 +242,20 @@ static int itg3200_initial_setup(struct iio_dev *indio_dev)
>  	return ret;
>  }
>  
> +static const struct iio_mount_matrix *
> +itg3200_get_mount_matrix(const struct iio_dev *indio_dev,
> +			  const struct iio_chan_spec *chan)
> +{
> +	struct itg3200 *data = iio_priv(indio_dev);
> +
> +	return &data->orientation;
> +}
> +
> +static const struct iio_chan_spec_ext_info itg3200_ext_info[] = {
> +	IIO_MOUNT_MATRIX(IIO_SHARED_BY_DIR, itg3200_get_mount_matrix),
> +	{ }
> +};
> +
>  #define ITG3200_ST						\
>  	{ .sign = 's', .realbits = 16, .storagebits = 16, .endianness = IIO_BE }
>  
> @@ -255,6 +269,7 @@ static int itg3200_initial_setup(struct iio_dev *indio_dev)
>  	.address = ITG3200_REG_GYRO_ ## _mod ## OUT_H, \
>  	.scan_index = ITG3200_SCAN_GYRO_ ## _mod, \
>  	.scan_type = ITG3200_ST, \
> +	.ext_info = itg3200_ext_info, \
>  }
>  
>  static const struct iio_chan_spec itg3200_channels[] = {
> @@ -297,6 +312,11 @@ static int itg3200_probe(struct i2c_client *client,
>  
>  	st = iio_priv(indio_dev);
>  
> +	ret = iio_read_mount_matrix(&client->dev, "mount-matrix",
> +				&st->orientation);
> +	if (ret)
> +		return ret;
> +
>  	i2c_set_clientdata(client, indio_dev);
>  	st->i2c = client;
>  
> diff --git a/include/linux/iio/gyro/itg3200.h b/include/linux/iio/gyro/itg3200.h
> index 2a820850f284..0a30fddccfb3 100644
> --- a/include/linux/iio/gyro/itg3200.h
> +++ b/include/linux/iio/gyro/itg3200.h
> @@ -104,6 +104,7 @@
>  struct itg3200 {
>  	struct i2c_client	*i2c;
>  	struct iio_trigger	*trig;
> +	struct iio_mount_matrix orientation;
>  };
>  
>  enum ITG3200_SCAN_INDEX {

Re: [PATCH v2 07/10] iio: magnetometer: bmc150: add mount matrix support

[Jonathan Cameron]

On Thu, 21 Feb 2019 18:02:52 +0100
"H. Nikolaus Schaller" <hns@goldelico.com> wrote:

> This patch allows to read a mount-matrix device tree
> property and report to user-space or in-kernel iio
> clients.
> 
> Signed-off-by: H. Nikolaus Schaller <hns@goldelico.com>
Applied.

Thanks,

Jonathan
> ---
>  drivers/iio/magnetometer/bmc150_magn.c | 21 +++++++++++++++++++++
>  1 file changed, 21 insertions(+)
> 
> diff --git a/drivers/iio/magnetometer/bmc150_magn.c b/drivers/iio/magnetometer/bmc150_magn.c
> index d91cb845e3d6..b0d8b036d9bb 100644
> --- a/drivers/iio/magnetometer/bmc150_magn.c
> +++ b/drivers/iio/magnetometer/bmc150_magn.c
> @@ -143,6 +143,7 @@ struct bmc150_magn_data {
>  	 */
>  	struct mutex mutex;
>  	struct regmap *regmap;
> +	struct iio_mount_matrix orientation;
>  	/* 4 x 32 bits for x, y z, 4 bytes align, 64 bits timestamp */
>  	s32 buffer[6];
>  	struct iio_trigger *dready_trig;
> @@ -612,6 +613,20 @@ static ssize_t bmc150_magn_show_samp_freq_avail(struct device *dev,
>  	return len;
>  }
>  
> +static const struct iio_mount_matrix *
> +bmc150_magn_get_mount_matrix(const struct iio_dev *indio_dev,
> +			      const struct iio_chan_spec *chan)
> +{
> +	struct bmc150_magn_data *data = iio_priv(indio_dev);
> +
> +	return &data->orientation;
> +}
> +
> +static const struct iio_chan_spec_ext_info bmc150_magn_ext_info[] = {
> +	IIO_MOUNT_MATRIX(IIO_SHARED_BY_DIR, bmc150_magn_get_mount_matrix),
> +	{ }
> +};
> +
>  static IIO_DEV_ATTR_SAMP_FREQ_AVAIL(bmc150_magn_show_samp_freq_avail);
>  
>  static struct attribute *bmc150_magn_attributes[] = {
> @@ -638,6 +653,7 @@ static const struct attribute_group bmc150_magn_attrs_group = {
>  		.storagebits = 32,					\
>  		.endianness = IIO_LE					\
>  	},								\
> +	.ext_info = bmc150_magn_ext_info,				\
>  }
>  
>  static const struct iio_chan_spec bmc150_magn_channels[] = {
> @@ -861,6 +877,11 @@ int bmc150_magn_probe(struct device *dev, struct regmap *regmap,
>  	data->irq = irq;
>  	data->dev = dev;
>  
> +	ret = iio_read_mount_matrix(dev, "mount-matrix",
> +				&data->orientation);
> +	if (ret)
> +		return ret;
> +
>  	if (!name && ACPI_HANDLE(dev))
>  		name = bmc150_magn_match_acpi_device(dev);
>  

Re: [PATCH v2 08/10] iio: magnetometer: hmc5843: add mount matrix support

[Jonathan Cameron]

On Thu, 21 Feb 2019 18:02:53 +0100
"H. Nikolaus Schaller" <hns@goldelico.com> wrote:

> This patch allows to read a mount-matrix device tree
> property and report to user-space or in-kernel iio
> clients.
> 
> Signed-off-by: H. Nikolaus Schaller <hns@goldelico.com>
Applied.

Thanks,

Jonathan

> ---
>  drivers/iio/magnetometer/hmc5843.h      |  1 +
>  drivers/iio/magnetometer/hmc5843_core.c | 20 ++++++++++++++++++--
>  2 files changed, 19 insertions(+), 2 deletions(-)
> 
> diff --git a/drivers/iio/magnetometer/hmc5843.h b/drivers/iio/magnetometer/hmc5843.h
> index a75224cf99df..e3e22d2508d3 100644
> --- a/drivers/iio/magnetometer/hmc5843.h
> +++ b/drivers/iio/magnetometer/hmc5843.h
> @@ -43,6 +43,7 @@ struct hmc5843_data {
>  	struct mutex lock;
>  	struct regmap *regmap;
>  	const struct hmc5843_chip_info *variant;
> +	struct iio_mount_matrix orientation;
>  	__be16 buffer[8];
>  };
>  
> diff --git a/drivers/iio/magnetometer/hmc5843_core.c b/drivers/iio/magnetometer/hmc5843_core.c
> index ada142fb7aa3..05629ec56d80 100644
> --- a/drivers/iio/magnetometer/hmc5843_core.c
> +++ b/drivers/iio/magnetometer/hmc5843_core.c
> @@ -237,6 +237,15 @@ int hmc5843_set_measurement_configuration(struct iio_dev *indio_dev,
>  	return hmc5843_set_meas_conf(data, meas_conf);
>  }
>  
> +static const struct iio_mount_matrix *
> +hmc5843_get_mount_matrix(const struct iio_dev *indio_dev,
> +			  const struct iio_chan_spec *chan)
> +{
> +	struct hmc5843_data *data = iio_priv(indio_dev);
> +
> +	return &data->orientation;
> +}
> +
>  static const struct iio_enum hmc5843_meas_conf_enum = {
>  	.items = hmc5843_meas_conf_modes,
>  	.num_items = ARRAY_SIZE(hmc5843_meas_conf_modes),
> @@ -247,7 +256,8 @@ static const struct iio_enum hmc5843_meas_conf_enum = {
>  static const struct iio_chan_spec_ext_info hmc5843_ext_info[] = {
>  	IIO_ENUM("meas_conf", true, &hmc5843_meas_conf_enum),
>  	IIO_ENUM_AVAILABLE("meas_conf", &hmc5843_meas_conf_enum),
> -	{ },
> +	IIO_MOUNT_MATRIX(IIO_SHARED_BY_DIR, hmc5843_get_mount_matrix),
> +	{ }
>  };
>  
>  static const struct iio_enum hmc5983_meas_conf_enum = {
> @@ -260,7 +270,8 @@ static const struct iio_enum hmc5983_meas_conf_enum = {
>  static const struct iio_chan_spec_ext_info hmc5983_ext_info[] = {
>  	IIO_ENUM("meas_conf", true, &hmc5983_meas_conf_enum),
>  	IIO_ENUM_AVAILABLE("meas_conf", &hmc5983_meas_conf_enum),
> -	{ },
> +	IIO_MOUNT_MATRIX(IIO_SHARED_BY_DIR, hmc5843_get_mount_matrix),
> +	{ }
>  };
>  
>  static
> @@ -635,6 +646,11 @@ int hmc5843_common_probe(struct device *dev, struct regmap *regmap,
>  	data->variant = &hmc5843_chip_info_tbl[id];
>  	mutex_init(&data->lock);
>  
> +	ret = iio_read_mount_matrix(dev, "mount-matrix",
> +				&data->orientation);
> +	if (ret)
> +		return ret;
> +
>  	indio_dev->dev.parent = dev;
>  	indio_dev->name = name;
>  	indio_dev->info = &hmc5843_info;

Re: [PATCH v2 09/10] iio: mpu6050: improve code readability

[Jonathan Cameron]

On Thu, 21 Feb 2019 18:02:54 +0100
"H. Nikolaus Schaller" <hns@goldelico.com> wrote:

> - use temporary variable in get_mount_matrix()
> - remove , after { }
> 
> Signed-off-by: H. Nikolaus Schaller <hns@goldelico.com>
Applied.

Thanks,

Jonathan

> ---
>  drivers/iio/imu/inv_mpu6050/inv_mpu_core.c | 6 ++++--
>  1 file changed, 4 insertions(+), 2 deletions(-)
> 
> diff --git a/drivers/iio/imu/inv_mpu6050/inv_mpu_core.c b/drivers/iio/imu/inv_mpu6050/inv_mpu_core.c
> index 533d1f8321ac..e7721b6fb441 100644
> --- a/drivers/iio/imu/inv_mpu6050/inv_mpu_core.c
> +++ b/drivers/iio/imu/inv_mpu6050/inv_mpu_core.c
> @@ -765,12 +765,14 @@ static const struct iio_mount_matrix *
>  inv_get_mount_matrix(const struct iio_dev *indio_dev,
>  		     const struct iio_chan_spec *chan)
>  {
> -	return &((struct inv_mpu6050_state *)iio_priv(indio_dev))->orientation;
> +	struct inv_mpu6050_state *data = iio_priv(indio_dev);
> +
> +	return &data->orientation;
>  }
>  
>  static const struct iio_chan_spec_ext_info inv_ext_info[] = {
>  	IIO_MOUNT_MATRIX(IIO_SHARED_BY_TYPE, inv_get_mount_matrix),
> -	{ },
> +	{ }
>  };
>  
>  #define INV_MPU6050_CHAN(_type, _channel2, _index)                    \

Re: [PATCH v2 10/10] iio: ak8975: improve code readability

[Jonathan Cameron]

On Thu, 21 Feb 2019 18:02:55 +0100
"H. Nikolaus Schaller" <hns@goldelico.com> wrote:

> - use temporary variable in get_mount_matrix()
> - remove , after { }
> 
> Signed-off-by: H. Nikolaus Schaller <hns@goldelico.com>
Applied.

Thanks,

Jonathan

> ---
>  drivers/iio/magnetometer/ak8975.c | 8 +++++---
>  1 file changed, 5 insertions(+), 3 deletions(-)
> 
> diff --git a/drivers/iio/magnetometer/ak8975.c b/drivers/iio/magnetometer/ak8975.c
> index db7214ac514c..43d08c089792 100644
> --- a/drivers/iio/magnetometer/ak8975.c
> +++ b/drivers/iio/magnetometer/ak8975.c
> @@ -746,12 +746,14 @@ static const struct iio_mount_matrix *
>  ak8975_get_mount_matrix(const struct iio_dev *indio_dev,
>  			const struct iio_chan_spec *chan)
>  {
> -	return &((struct ak8975_data *)iio_priv(indio_dev))->orientation;
> +	struct ak8975_data *data = iio_priv(indio_dev);
> +
> +	return &data->orientation;
>  }
>  
>  static const struct iio_chan_spec_ext_info ak8975_ext_info[] = {
>  	IIO_MOUNT_MATRIX(IIO_SHARED_BY_DIR, ak8975_get_mount_matrix),
> -	{ },
> +	{ }
>  };
>  
>  #define AK8975_CHANNEL(axis, index)					\
> @@ -792,7 +794,7 @@ static const struct acpi_device_id ak_acpi_match[] = {
>  	{"AK09911", AK09911},
>  	{"AKM9911", AK09911},
>  	{"AK09912", AK09912},
> -	{ },
> +	{ }
>  };
>  MODULE_DEVICE_TABLE(acpi, ak_acpi_match);
>  #endif

Re: [PATCH v2 00/10] iio mount matrix - revitalize missing bindings documentation and provide code for bmc150, bmg160, bma180, itg3200, hmc584x

[Jonathan Cameron]

On Fri, 22 Feb 2019 16:48:14 +0200
Andy Shevchenko <andy.shevchenko@gmail.com> wrote:

> On Thu, Feb 21, 2019 at 7:04 PM H. Nikolaus Schaller <hns@goldelico.com> wrote:
> >
> > Fixes V2:
> > * make get_mount_matrix() functions more readable (use temp variable)
> >   (suggested by Jonathan and Andy)
> > * add these readability improvements also for ak8975 and mpu6050
> >   (suggested by Jonathan and Andy)
> > * squash bindings documentation into single commit for better discussion
> >   (suggested by Linus)
> > * FOR DISCUSSION: add some more clarifications to the bindings documentation
> >   and an attempt to define the magnetometer orientation
> > * add "iio: Allow to read mount matrix from ACPI" to the beginning of
> >   the series to make it compile
> >   (suggested by Andy)
> > * replace of_iio_read_mount_matrix() by iio_read_mount_matrix()
> >   (required by "iio: Allow to read mount matrix from ACPI")
> > * drop patch to convert bma180 to devm (potential race)
> >   (suggested by Jonathan)
> >
> > PATCH V1 2019-02-20 15:01:02:
> > This patch series adds the mount-matrix to several iio sensor drivers
> > used in handheld devices.
> >
> > The mount-matrix translates the quite arbitrary orientation of the sensor
> > on some printed circuit board to user-tangible orientation in handheld
> > devices that relates to typical screen orientation.
> >
> > There was a bindings documentation by Linus Walleij but the patch
> > did not make it into mainline. Therefore I resend it here.
> >
> > Next I have added some clarifications (at least I hope it clarifies)
> > in a second patch.
> >
> > Finally, the patch set implements the hooks for the mount matrix
> > in several iio drivers: bmc150, bma180, bmg160, itg3200, hmc5843.
> > This includes also one patch for the bma180 to convert it to devm API.
> >
> > We use them in different variants of the omap3-gta04 so a separate
> > patch set will provide device tree additions for them.
> >  
> 
> Thank you, it looks nice.
> FWIW,
> Reviewed-by: Andy Shevchenko <andy.shevchenko@gmail.com>
> 

Thanks to Linus and Andy for reviews.
I've picked up all but they documentation patch.  I think
it is 'very nearly there', but would like a few really minor
tweaks.  Seemed silly to stall the other patches on that though!

Thanks,

Jonathan

Re: [PATCH v2 02/10] iio: document bindings for mounting matrices

[H. Nikolaus Schaller]

Hi Jonathan,

> Am 03.03.2019 um 16:19 schrieb Jonathan Cameron <jic23@kernel.org>:
> 
> On Thu, 21 Feb 2019 18:02:47 +0100
> "H. Nikolaus Schaller" <hns@goldelico.com> wrote:
> 
>> From: Linus Walleij <linus.walleij@linaro.org>
>> 
>> The mounting matrix for sensors was introduced in
>> commit dfc57732ad38 ("iio:core: mounting matrix support")
>> 
>> However the device tree bindings are very terse and since this is
>> a widely applicable property, we need a proper binding for it
>> that the other bindings can reference. This will also be useful
>> for other operating systems and sensor engineering at large.
>> 
>> I think all 3D sensors should support it, the current situation
>> is probably that the mounting information is confined in magic
>> userspace components rather than using the mounting matrix, which
>> is not good for portability and reuse.
>> 
>> Cc: Linus Walleij <linus.walleij@linaro.org>
>> Cc: Gregor Boirie <gregor.boirie@parrot.com>
>> Cc: Sebastian Reichel <sre@kernel.org>
>> Cc: Samu Onkalo <samu.onkalo@intel.com>
>> Cc: devicetree@vger.kernel.org
>> Signed-off-by: Linus Walleij <linus.walleij@linaro.org>
>> Signed-off-by: H. Nikolaus Schaller <hns@goldelico.com>
> Hi Nikolaus
> 
> A few minor notes inline.

> 
>> ---
>> .../devicetree/bindings/iio/mount-matrix.txt  | 204 ++++++++++++++++++
>> 1 file changed, 204 insertions(+)
>> create mode 100644 Documentation/devicetree/bindings/iio/mount-matrix.txt
>> 
>> diff --git a/Documentation/devicetree/bindings/iio/mount-matrix.txt b/Documentation/devicetree/bindings/iio/mount-matrix.txt
>> new file mode 100644
>> index 000000000000..1b64c8b1f689
>> --- /dev/null
>> +++ b/Documentation/devicetree/bindings/iio/mount-matrix.txt
>> @@ -0,0 +1,204 @@
>> +For discussion. Unclear are:
>> +* is the definition of +/- values practical or counterintuitive?
>> +* are the definitions unambiguous and easy to follow?
>> +* are the examples correct?
>> +* should we have HOWTO engineer a correct matrix for a new device (without comparing to a different one)?
>> +
>> +====
>> +
>> +
>> +Mounting matrix
>> +
>> +The mounting matrix is a device tree property used to orient any IIO device
> 
> Minor, but DT bindings are in theory not Linux specific and IIO is, so
> should be "any device"
> 
>> +that produce three-dimensional data in relation to the world where it is
>> +deployed.
>> +
>> +The purpose of the mounting matrix is to translate the sensor frame of
>> +reference into the device frame of reference using a translation matrix as
>> +defined in linear algebra.
>> +
>> +The typical usecase is that where a component has an internal representation
>> +of the (x,y,z) triplets, such as different registers to read these coordinates,
>> +and thus implying that the component should be mounted in a certain orientation
>> +relative to some specific device frame of reference.
>> +
>> +For example a device with some kind of screen, where the user is supposed to
>> +interact with the environment using an accelerometer, gyroscope or magnetometer
>> +mounted on the same chassis as this screen, will likely take the screen as
>> +reference to (x,y,z) orientation, with (x,y) corresponding to these axes on the
>> +screen and (z) being depth, the axis perpendicular to the screen.
>> +
>> +For a screen you probably want (x) coordinates to go from negative on the left
>> +to positive on the right, (y) from negative on the bottom to positive on top
>> +and (z) depth to be negative under the screen and positive in front of it,
>> +toward the face of the user.
>> +
>> +A sensor can be mounted in any angle along the axes relative to the frame of
>> +reference. This means that the sensor may be flipped upside-down, left-right,
>> +or tilted at any angle relative to the frame of reference.
>> +
>> +Another frame of reference is how the device with its sensor relates to the
>> +external world, the environment where the device is deployed. Usually the data
>> +from the sensor is used to figure out how the device is oriented with respect
>> +to this world. When using the mounting matrix, the sensor and device orientation
>> +becomes identical and we can focus on the data as it relates to the surrounding
>> +world.
>> +
>> +Device-to-world examples for some three-dimensional sensor types:
>> +
>> +- Accelerometers have their world frame of reference toward the center of
>> +  gravity, usually to the core of the planet. A reading of the (x,y,z) values
>> +  from the sensor will give a projection of the gravity vector through the
>> +  device relative to the center of the planet, i.e. relative to its surface at
>> +  this point. Up and down in the world relative to the device frame of
>> +  reference can thus be determined. and users would likely expect a value of
>> +  9.81 m/s^2 upwards along the (z) axis, i.e. out of the screen when the device
>> +  is held with its screen flat on the planets surface and 0 on the other axes,
>> +  as the gravity vector is projected 1:1 onto the sensors (z)-axis.
> 
> Nitpick: Screen is face down or face up?  Someone might think a screen is
> flat when looking up at them from the floor or the other way up.
> I 'think' it's face down in the following...
> 
> 
>> +
>> +  If you tilt the device, the g vector virtually coming out of the display
>> +  is projected onto the (x,y) plane of the display panel.
>> +
>> +  Example:
>> +
> 
> space after > for z. Or making it consistent anyway.
> Hmm. 
> 
>> +         ^ z: +g                   ^ z: >0
>> +         !                        /!
>> +         ! x=y=0                 / ! x: > 0
>> +     +--------+             +--------+
>> +     !        !             !        !
>> +     +--------+             +--------+
>> +         !                    /
>> +         !                   /
>> +         v                  v
>> +      center of         center of
>> +       gravity           gravity
>> +
>> +
>> +  If the device is tilted to the left, you get a positive x value. If you point
>> +  its top towards surface, you get a negative y axis.
>> +
>> +     (---------)
>> +     !         !           y: -g
>> +     !         !             ^
>> +     !         !             !
>> +     !         !
>> +     !         !  x: +g <- z: +g  -> x: -g
>> +     ! 1  2  3 !
>> +     ! 4  5  6 !             !
>> +     ! 7  8  9 !             v
>> +     ! *  0  # !           y: +g
>> +     (---------)
>> +
>> +
>> +- Magnetometers (compasses) have their world frame of reference relative to the
>> +  geomagnetic field. The system orientation vis-a-vis the world is defined with
>> +  respect to the local earth geomagnetic reference frame where (y) is in the
>> +  ground plane and positive towards magnetic North, (x) is in the ground plane,
>> +  perpendicular to the North axis and positive towards the East and (z) is
>> +  perpendicular to the ground plane and positive upwards.
>> +
>> +
>> +     ^^^ North: y > 0
>> +
>> +     (---------)
>> +     !         !
>> +     !         !
>> +     !         !
>> +     !         !  >
>> +     !         !  > North: x > 0
>> +     ! 1  2  3 !  >
>> +     ! 4  5  6 !
>> +     ! 7  8  9 !
>> +     ! *  0  # !
>> +     (---------)
>> +
>> +  Since the geomagnetic field is not uniform this definition fails if we come
>> +  closer to the poles.
>> +
>> +  Sensors and driver can not and should not take care of this because there
>> +  are complex calculations and empirical data to be taken care of. We leave
>> +  this up to user space.
>> +
>> +  The definition we take:
>> +
>> +  If the device is placed at the equator and the top is pointing north, the
>> +  display is readable by a person standing upright on the earth surface, this
>> +  defines a positive y value.
> Nice definition. <wonders how consistent it is at the equator - meh close enough :)>
>> +
>> +
>> +- Gyroscopes detects the movement relative the device itself. The angular
>> +  velocity is defined as orthogonal to the plane of rotation, so if you put the
>> +  device on a flat surface and spin it around the z axis (such as rotating a
>> +  device with a screen lying flat on a table), you should get a negative value
>> +  along the (z) axis if rotated clockwise, and a positive value if rotated
>> +  counter-clockwise according to the right-hand rule.
>> +
>> +
>> +     (---------)     y > 0
>> +     !         !     v---\
>> +     !         !
>> +     !         !
>> +     !         !      <--\
>> +     !         !         ! z > 0
>> +     ! 1  2  3 !       --/
>> +     ! 4  5  6 !
>> +     ! 7  8  9 !
>> +     ! *  0  # !
>> +     (---------)
>> +
>> +
>> +So unless the sensor is ideally mounted, we need a means to indicate the
>> +relative orientation of any given sensor of this type with respect to the
>> +frame of reference.
>> +
>> +To achieve this, use the device tree property "mount-matrix" for the sensor.
>> +
>> +This supplies a 3x3 rotation matrix in the strict linear algebraic sense,
>> +to orient the senor axes relative to a desired point of reference. This means
>> +the resulting values from the sensor, after scaling to proper units, should be
>> +multiplied by this matrix to give the proper vectors values in three-dimensional
>> +space, relative to the device or world point of reference.
>> +
>> +For more information, consult:
>> +https://en.wikipedia.org/wiki/Rotation_matrix
>> +
>> +The mounting matrix has the layout:
>> +
>> + (mxx, myx, mzx)
>> + (mxy, myy, mzy)
>> + (mxz, myz, mzz)
>> +
>> +Values are intended to be multiplied as:
>> +
>> +  x' = mxx * x + myx * y + mzx * z
>> +  y' = mxy * x + myy * y + mzy * z
>> +  z' = mxz * x + myz * y + mzz * z
>> +
>> +It is represented as an array of strings containing the real values for
>> +producing the transformation matrix. The real values use a decimal point and
>> +a minus (-) to indicate a negative value.
> 
> I'd drop the decimal point and negative as both fairly obvious and this
> sentence can currently be read as a decimal point is necessary for a negative.
> 
>> +
>> +Examples:
>> +
>> +Identity matrix (nothing happens to the coordinates, which means the device was
>> +mechanically mounted in an ideal way and we need no transformation):
>> +
>> +mount-matrix = "1", "0", "0",
>> +               "0", "1", "0",
>> +               "0", "0", "1";
>> +
>> +The sensor is mounted 30 degrees (Pi/6 radians) tilted along the X axis, so we
>> +compensate by performing a -30 degrees rotation around the X axis:
>> +
>> +mount-matrix = "1", "0", "0",
>> +               "0", "0.866", "0.5",
>> +               "0", "-0.5", "0.866";
>> +
>> +The sensor is flipped 180 degrees (Pi radians) around the Z axis, i.e. mounted
>> +upside-down:
>> +
>> +mount-matrix = "0.998", "0.054", "0",
>> +               "-0.054", "0.998", "0",
>> +               "0", "0", "1";
>> +
>> +???: this does not match "180 degrees" - factors indicate ca. 3 degrees compensation
> Yes. Good to say this.
> 
> Very nice indeed, just these little tidy ups and I'm very happy with the
> result!
> 
> Jonathan


Thanks for pushing the other patches forwards.

Yes, I know this needs more discussion. So I'll go through your comments in a few days and post an update just for this.

BR and thanks,
Nikolaus

Re: [PATCH v2 00/10] iio mount matrix - revitalize missing bindings documentation and provide code for bmc150, bmg160, bma180, itg3200, hmc584x

[H. Nikolaus Schaller]

Hi Jonathan,

> Am 03.03.2019 um 16:32 schrieb Jonathan Cameron <jic23@kernel.org>:
> 
> Thanks to Linus and Andy for reviews.
> I've picked up all but they documentation patch.  I think
> it is 'very nearly there', but would like a few really minor
> tweaks.  Seemed silly to stall the other patches on that though!

Seems they have stalled elsewhere since they did not yet arrive in linux-next.

The documentation patch is still on my todo list and will need a little more time
but that should not block the others.

BR and thanks,
Nikolaus

Re: [PATCH v2 00/10] iio mount matrix - revitalize missing bindings documentation and provide code for bmc150, bmg160, bma180, itg3200, hmc584x

[Jonathan Cameron]

On Thu, 4 Apr 2019 08:29:12 +0200
"H. Nikolaus Schaller" <hns@goldelico.com> wrote:

> Hi Jonathan,
> 
> > Am 03.03.2019 um 16:32 schrieb Jonathan Cameron <jic23@kernel.org>:
> > 
> > Thanks to Linus and Andy for reviews.
> > I've picked up all but they documentation patch.  I think
> > it is 'very nearly there', but would like a few really minor
> > tweaks.  Seemed silly to stall the other patches on that though!  
> 
> Seems they have stalled elsewhere since they did not yet arrive in linux-next.
The iio tree is not directly pulled into linux-next.  Hence IIO patches
only turn up there once I've sent a pull request to Greg and they have
entered the staging-next tree.

They still haven't quite made it into linux-next, but I'd imagine they
will tomorrow.

Jonathan

> 
> The documentation patch is still on my todo list and will need a little more time
> but that should not block the others.
Absolutely, this was just tree handling delays and me messing up a pull
request to slow things down even more.

Jonathan

> 
> BR and thanks,
> Nikolaus
> 

Re: [PATCH v2 02/10] iio: document bindings for mounting matrices

[Linus Walleij]

Hi H. Nikolaus,

On Thu, Feb 21, 2019 at 6:03 PM H. Nikolaus Schaller <hns@goldelico.com> wrote:

> From: Linus Walleij <linus.walleij@linaro.org>

It is fair for you to change authorship to yourself at this point.
Just keeping my Signed-off-by is sufficient.

> The mounting matrix for sensors was introduced in
> commit dfc57732ad38 ("iio:core: mounting matrix support")
>
> However the device tree bindings are very terse and since this is
> a widely applicable property, we need a proper binding for it
> that the other bindings can reference. This will also be useful
> for other operating systems and sensor engineering at large.
>
> I think all 3D sensors should support it, the current situation
> is probably that the mounting information is confined in magic
> userspace components rather than using the mounting matrix, which
> is not good for portability and reuse.
>
> Cc: Linus Walleij <linus.walleij@linaro.org>
> Cc: Gregor Boirie <gregor.boirie@parrot.com>
> Cc: Sebastian Reichel <sre@kernel.org>
> Cc: Samu Onkalo <samu.onkalo@intel.com>
> Cc: devicetree@vger.kernel.org
> Signed-off-by: Linus Walleij <linus.walleij@linaro.org>
> Signed-off-by: H. Nikolaus Schaller <hns@goldelico.com>

Did this patch fall off somewhere? I think it's really neat, even in this
form it is great help for developers. If you want I can try picking up the
comments and resend it.

Linus Walleij

Re: [PATCH v2 02/10] iio: document bindings for mounting matrices

[H. Nikolaus Schaller]

Hi Linus,

> Am 23.07.2019 um 09:42 schrieb Linus Walleij <linus.walleij@linaro.org>:
> 
> Hi H. Nikolaus,
> 
> On Thu, Feb 21, 2019 at 6:03 PM H. Nikolaus Schaller <hns@goldelico.com> wrote:
> 
>> From: Linus Walleij <linus.walleij@linaro.org>
> 
> It is fair for you to change authorship to yourself at this point.
> Just keeping my Signed-off-by is sufficient.

Well, I think my contribution is less than yours :)

> 
>> The mounting matrix for sensors was introduced in
>> commit dfc57732ad38 ("iio:core: mounting matrix support")
>> 
>> However the device tree bindings are very terse and since this is
>> a widely applicable property, we need a proper binding for it
>> that the other bindings can reference. This will also be useful
>> for other operating systems and sensor engineering at large.
>> 
>> I think all 3D sensors should support it, the current situation
>> is probably that the mounting information is confined in magic
>> userspace components rather than using the mounting matrix, which
>> is not good for portability and reuse.
>> 
>> Cc: Linus Walleij <linus.walleij@linaro.org>
>> Cc: Gregor Boirie <gregor.boirie@parrot.com>
>> Cc: Sebastian Reichel <sre@kernel.org>
>> Cc: Samu Onkalo <samu.onkalo@intel.com>
>> Cc: devicetree@vger.kernel.org
>> Signed-off-by: Linus Walleij <linus.walleij@linaro.org>
>> Signed-off-by: H. Nikolaus Schaller <hns@goldelico.com>
> 
> Did this patch fall off somewhere? I think it's really neat, even in this
> form it is great help for developers. If you want I can try picking up the
> comments and resend it.

Well, I had planned to review it again and promised to send out a new
version. But as usual this ToDo becomes hidden by always more important
tasks.

So I am fine if you can pick comments and resend it. I think there will
be others who help to make it even better in the future if the mount matrix
is more widely used.

BR,
Nikolaus

Re: [PATCH v2 02/10] iio: document bindings for mounting matrices

[Andy Shevchenko]

On Tue, Jul 23, 2019 at 09:42:59AM +0200, Linus Walleij wrote:
> On Thu, Feb 21, 2019 at 6:03 PM H. Nikolaus Schaller <hns@goldelico.com> wrote:

> > From: Linus Walleij <linus.walleij@linaro.org>
> 
> It is fair for you to change authorship to yourself at this point.
> Just keeping my Signed-off-by is sufficient.

...or Co-developed-by: can be used.

-- 
With Best Regards,
Andy Shevchenko

Re: [PATCH v2 02/10] iio: document bindings for mounting matrices

[Jonathan Cameron]

On Tue, 23 Jul 2019 11:46:49 +0200
"H. Nikolaus Schaller" <hns@goldelico.com> wrote:

> Hi Linus,
> 
> > Am 23.07.2019 um 09:42 schrieb Linus Walleij <linus.walleij@linaro.org>:
> > 
> > Hi H. Nikolaus,
> > 
> > On Thu, Feb 21, 2019 at 6:03 PM H. Nikolaus Schaller <hns@goldelico.com> wrote:
> >   
> >> From: Linus Walleij <linus.walleij@linaro.org>  
> > 
> > It is fair for you to change authorship to yourself at this point.
> > Just keeping my Signed-off-by is sufficient.  
> 
> Well, I think my contribution is less than yours :)
> 
> >   
> >> The mounting matrix for sensors was introduced in
> >> commit dfc57732ad38 ("iio:core: mounting matrix support")
> >> 
> >> However the device tree bindings are very terse and since this is
> >> a widely applicable property, we need a proper binding for it
> >> that the other bindings can reference. This will also be useful
> >> for other operating systems and sensor engineering at large.
> >> 
> >> I think all 3D sensors should support it, the current situation
> >> is probably that the mounting information is confined in magic
> >> userspace components rather than using the mounting matrix, which
> >> is not good for portability and reuse.
> >> 
> >> Cc: Linus Walleij <linus.walleij@linaro.org>
> >> Cc: Gregor Boirie <gregor.boirie@parrot.com>
> >> Cc: Sebastian Reichel <sre@kernel.org>
> >> Cc: Samu Onkalo <samu.onkalo@intel.com>
> >> Cc: devicetree@vger.kernel.org
> >> Signed-off-by: Linus Walleij <linus.walleij@linaro.org>
> >> Signed-off-by: H. Nikolaus Schaller <hns@goldelico.com>  
> > 
> > Did this patch fall off somewhere? I think it's really neat, even in this
> > form it is great help for developers. If you want I can try picking up the
> > comments and resend it.  
> 
> Well, I had planned to review it again and promised to send out a new
> version. But as usual this ToDo becomes hidden by always more important
> tasks.
> 
> So I am fine if you can pick comments and resend it. I think there will
> be others who help to make it even better in the future if the mount matrix
> is more widely used.
> 
> BR,
> Nikolaus
> 
Given the comments that 'need' any response are fairly minor, I've just
taken the view that the perfect is the enemy of the good and applied
it to the togreg branch of iio.git with some really small tweaks.

Thanks for offering to tidy this up Linus, but seems like it would be
a waste of your time for such trivial tweaks!

The only one outstanding that I haven't 'fixed' is the question I raised
on face down or face up when talking about flat on the ground.

That might want a clarifying comment.

Applied to the togreg branch of iio.git and pushed out as testing
for the autobuilders to play with it (or not as the case may be!)

Thanks,

Jonathan

Re: [PATCH v2 02/10] iio: document bindings for mounting matrices

[Linus Walleij]

On Sun, Jul 28, 2019 at 9:50 AM Jonathan Cameron <jic23@kernel.org> wrote:

> Given the comments that 'need' any response are fairly minor, I've just
> taken the view that the perfect is the enemy of the good and applied
> it to the togreg branch of iio.git with some really small tweaks.

Oh that works, too :) whoever is most annoyed will get to fix any
remaining offenders.

The quality of documentation really depends on perspective.
This weekend I read some old UNIX System V manuals
and this was "extremly professional" documentation at one
point. It wasn't very good. I think we're pretty well off with what
we have here.

Yours,
Linus Walleij