Re: [PATCH 1/2] dt-bindings: iio: magnetometer: add ti tmag5273 documentation file

From: Krzysztof Kozlowski
Date: Tue Nov 15 2022 - 03:21:27 EST


On 15/11/2022 08:37, Gerald Loacker wrote:
> Add bindings documentation file for TI TMAG5273.

Subject - drop "documentation file".

>
> Signed-off-by: Gerald Loacker <gerald.loacker@xxxxxxxxxxxxxx>
> ---
> .../iio/magnetometer/ti,tmag5273.yaml | 72 +++++++++++++++++++
> MAINTAINERS | 6 ++
> 2 files changed, 78 insertions(+)
> create mode 100644 Documentation/devicetree/bindings/iio/magnetometer/ti,tmag5273.yaml
>
> diff --git a/Documentation/devicetree/bindings/iio/magnetometer/ti,tmag5273.yaml b/Documentation/devicetree/bindings/iio/magnetometer/ti,tmag5273.yaml
> new file mode 100644
> index 000000000000..2f5b0a4d2f40
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/iio/magnetometer/ti,tmag5273.yaml
> @@ -0,0 +1,72 @@
> +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
> +%YAML 1.2
> +---
> +$id: http://devicetree.org/schemas/iio/magnetometer/ti,tmag5273.yaml#
> +$schema: http://devicetree.org/meta-schemas/core.yaml#
> +
> +title: TI TMAG5273 Low-Power Linear 3D Hall-Effect Sensor
> +
> +maintainers:
> + - Gerald Loacker <gerald.loacker@xxxxxxxxxxxxxx>
> +
> +description:
> + The TI TMAG5273 is a low-power linear 3D Hall-effect sensor. This device
> + integrates three independent Hall-effect sensors in the X, Y, and Z axes.
> + The device has an integrated temperature sensor available. The TMAG5273
> + can be configured through the I2C interface to enable any combination of
> + magnetic axes and temperature measurements. An integrated angle calculation
> + engine (CORDIC) provides full 360° angular position information for both
> + on-axis and off-axis angle measurement topologies. The angle calculation is
> + performed using two user-selected magnetic axes.
> +
> +properties:
> + $nodename:
> + pattern: '^magnetometer@[0-9a-f]+$'

Device schemas do not need to enforce the names.

> +
> + compatible:
> + const: ti,tmag5273
> +
> + reg:
> + maxItems: 1
> +
> + "#io-channel-cells":
> + const: 1
> +
> + ti,angle-enable:

ti,angle-measurement

> + description:
> + Enables angle measurement in the selected plane.
> + 0 = OFF
> + 1 = X-Y (default)
> + 2 = Y-Z
> + 3 = X-Z

Why not strings which are easier for humans? off/x-y/y-z/x-z? How anyone
reading DTS can remember what is "3" in this and in thousands of other
devices?

> + $ref: /schemas/types.yaml#/definitions/uint32
> + minimum: 0
> + maximum: 3

default: 1

> +
> + vcc-supply:
> + description:
> + A regulator providing 1.7 V to 3.6 V supply voltage on the VCC pin,
> + typically 3.3 V.
> +
> +required:
> + - compatible
> + - reg
> + - vcc-supply
> +
> +additionalProperties: false
> +
> +examples:
> + - |
> + i2c-0 {

Just: i2c


Best regards,
Krzysztof