Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) client-ip=2620:137:e000::1:20;
Message-ID: <f52dcb6d-30ec-3d49-7e28-9761462d4799@wolfvision.net>
Date:   Thu, 17 Nov 2022 17:12:33 +0100
User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:102.0) Gecko/20100101
 Thunderbird/102.4.2
Subject: Re: [PATCH 1/2] dt-bindings: iio: magnetometer: add ti tmag5273
 documentation file
To:     Jonathan Cameron <Jonathan.Cameron@Huawei.com>
Cc:     linux-iio@vger.kernel.org, devicetree@vger.kernel.org,
        linux-kernel@vger.kernel.org, Jonathan Cameron <jic23@kernel.org>,
        Lars-Peter Clausen <lars@metafoo.de>,
        Rob Herring <robh+dt@kernel.org>,
        Krzysztof Kozlowski <krzysztof.kozlowski+dt@linaro.org>,
        Andy Shevchenko <andriy.shevchenko@linux.intel.com>,
        Nikita Yushchenko <nikita.yoush@cogentembedded.com>,
        Jakob Hauser <jahau@rocketmail.com>,
        Michael Riesch <michael.riesch@wolfvision.net>
References: <20221115073718.2377311-1-gerald.loacker@wolfvision.net>
 <20221115073718.2377311-2-gerald.loacker@wolfvision.net>
 <20221115174355.00004a01@Huawei.com>
From:   Gerald Loacker <gerald.loacker@wolfvision.net>
Organization: WolfVision GmbH
In-Reply-To: <20221115174355.00004a01@Huawei.com>
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
MIME-Version: 1.0
X-MS-Exchange-AntiSpam-MessageData-ChunkCount: 1
X-MS-Exchange-AntiSpam-MessageData-0: =?utf-8?B?cjJkU0NmZWVtekJnZG9vTnBwSFUzQ2R3SVBwVjlnRHpRaGU5cDRPU0tLUHhN?=
 =?utf-8?B?Mzc2YjdqTUJ2aDI0QTlSalp3WnEveEZYcW5lVE5MVGNFeVFlSEd2TEtxdWI4?=
 =?utf-8?B?RmpmQ2kyVkMrN0g3NEI2SUtxRVBTQjJDbUFnVGFpL082a25GUkhqd0g1Z2hj?=
 =?utf-8?B?SmRiRjBkWktHbnI2SkR2R0NQUXNIRElWbms4Z3h1M3NWU2UxclYwVHVyNUYr?=
 =?utf-8?B?emNXNUY3N3ZaalJSL2RxZnNQNno4Ujhuc0JpRnJ4eHh5Z1NsQ3lxeWpWTXlB?=
 =?utf-8?B?WndtNUhFTXhrakZvL1gvQzhmMjBURnFqejAwVVNlS0p2QitxbW4zOXRiSVRS?=
 =?utf-8?B?d1VjL29SYzliSTNWRVYyUkpZTE5KcjhkM1p6RzRZZWJsZFJMd0l1dDRiSkZ0?=
 =?utf-8?B?NHpOOGdxQlNSZk9CQkVscEhqTEtCTGozeHdJZW5oSTZZakQ5aWZ3ZC9JSnA5?=
 =?utf-8?B?V2VPK0w5M2xnZ1JvQkxweHUvM2s0cVoyNVR0elFYS0hwWWJlUHBRQUNNSjYv?=
 =?utf-8?B?UHF6ZHVCT1Z0cHU5QXplcVBsS08zVldXbHhVa2FlYVUxbWVCTGFoYUdxSlBX?=
 =?utf-8?B?UVlkenFqTUJGVmhvRTNtMzNCK25XYkYxSkFOT2VtTkYrV042THBMMXYxMS9R?=
 =?utf-8?B?NnRPcmFDc25Wc05GbTU4RTJGN0JVVFN1bVRZWVIvcXJxZjdHbFVadWtDcExW?=
 =?utf-8?B?YTNFVVk2QUpjUmRBUjkyaWlSc0M1a1M1RGtGdE5CNm53RzdQNTM4ZGdRYzlk?=
 =?utf-8?B?dUh2eitrK3JpOGFlS1BzUUdINzZtRXlzTnlDcXNmRWFhc3ZJMWFUaXlGRGpw?=
 =?utf-8?B?WlI2Q0Z4UmFnR0RVWUZiR2lSY0I2cUVwYVB6NmpGWlBpakFDNlZjOEp3K1pQ?=
 =?utf-8?B?L2ZRYW5ETXJnbTVpamV1OTFtR3Z2ZkVlcDltMFJyd0hKYmxyb3ZIay9JaGtw?=
 =?utf-8?B?bTJPM1ZmMWxWTm9TRXVjQkxLVVo4STBuMDZ0b1BreGM5cWQwTGlRemcvaElh?=
 =?utf-8?B?Rjdicjczc2RiWGd5K2NOckxEQ2dTQm9pUStJTlY1Zk1BR3VnSjRGaytBWFp5?=
 =?utf-8?B?K0crSXQ2bFRHWlRPWDNDajhBcEhGUGZtN2s4Mlhxem1OU0M4ZnJVV1hlVW5E?=
 =?utf-8?B?eUtNZ0Z4SW5peVo3YUZpZFdpbXM4U3pXTGp0YUUxRXZRVjJ3T0ZJVkNtcktv?=
 =?utf-8?B?TnRTMkYrbFBZSFlkNmZ6TCt6NlZvcFdlUkZYakUzTFlSTmNEbCt1R2dXOUtU?=
 =?utf-8?B?OE9wYmp0WWp4emxydXd6Y29WUTVHcmo4d0ZITFd2R0F1WFBlV0ZrdnJKVlNQ?=
 =?utf-8?B?SE1tNGpVenJ4NkUvSUN6YkV3SHoxL1pqMW5hQUViWGFZQXc5MUlzTzBHRlVr?=
 =?utf-8?B?cmF6WWNMUFpaaGpiclhPM0VFS0VtWUVVWVM0dkZ3TUdyaWpYY1Rla1pnS2dV?=
 =?utf-8?B?MjUxb3piWWUzeW41TFU5eFRPclFhMTV0alBCV1lWamU0YUgyQ1B0QXBIOU05?=
 =?utf-8?B?SWpONHNKT2FhdHpYOWRYNmtNZndzUkpBYnhXUk05b2RISmY4Y2NMRm9STXU2?=
 =?utf-8?B?SmxMSUx3WEowK2g4NllLMFRKOUxpdHJySUNTSndqcVBMOVBWdjRsUjNjR2Y1?=
 =?utf-8?B?WjE1c2ltZ3MzV2NwRDNhNDU1WGJ6Szh4UE1HaEI4YzBuT2twaTVBdW5VaGNX?=
 =?utf-8?B?ZU9LYWV4Z3k5YnBGVU5SNkVxZFNtMTg3RTdHbDhXWlp5em54UmNPTVdZdnZW?=
 =?utf-8?B?YUJqaUdxTTFGajkxbEthRVFUY2lQaVUrcUZWOTdHSlI0STBJaE03QUMrR0s5?=
 =?utf-8?B?RitYRlh5Y1ppZ0VMNnNVb0d0MzFqNENFbHJ5UlRNRUtiZ1BWVDhTNmdsNjFN?=
 =?utf-8?B?TmxkM3RiMmZ0eVA0VHJTM1hQN2ZxRGlhSUwvYURPZ0FXREIzam9RQ0ozbjNN?=
 =?utf-8?B?Sk1CUEFNaElQVUQveW5KVGIzNldJWDB4dmZXWjJPZVZmTWs3OXR6bklVNUZ6?=
 =?utf-8?B?YUVEYVNnT2tXQUVIS3c3RDM1c3RqakxWT0JDYUpTK1RiK1lZL1dkd0Jldktv?=
 =?utf-8?B?SUovOG1rTEgzc2VSTWFXOHhxekJRQnBDa0xhSVBPZ1lybWdkZmExWkJPRCtI?=
 =?utf-8?B?bTFZLzlaR3o4VU4wOEtJRlQ2RTkra1l5UzU2M0hnVDZxQnFobWJjTEtpSEpQ?=
 =?utf-8?B?Nmc9PQ==?=
X-OriginatorOrg: wolfvision.net
X-MS-Exchange-CrossTenant-Network-Message-Id: ca2b5613-be17-471c-e955-08dac8b68b8e
X-MS-Exchange-CrossTenant-AuthSource: VI1PR08MB4544.eurprd08.prod.outlook.com
X-MS-Exchange-CrossTenant-AuthAs: Internal
X-MS-Exchange-CrossTenant-OriginalArrivalTime: 17 Nov 2022 16:12:37.9692
 (UTC)
X-MS-Exchange-CrossTenant-FromEntityHeader: Hosted
X-MS-Exchange-CrossTenant-Id: e94ec9da-9183-471e-83b3-51baa8eb804f
X-MS-Exchange-CrossTenant-MailboxType: HOSTED
X-MS-Exchange-CrossTenant-UserPrincipalName: ayrQo8X4fHcOrA6rFpiLZ+LwCs/VRaLy3Hv87H0PvLEA3XfmhxIgf1YXbLzuxveuPe4/Hw/cuM7f3UbV6ILgW6q2szjqBiUy3yj6UqCXECs=
X-MS-Exchange-Transport-CrossTenantHeadersStamped: AS2PR08MB9641
X-Spam-Status: No, score=-2.1 required=5.0 tests=BAYES_00,DKIM_SIGNED,
        DKIM_VALID,DKIM_VALID_AU,DKIM_VALID_EF,NICE_REPLY_A,RCVD_IN_DNSWL_NONE,
        RCVD_IN_MSPIKE_H2,SPF_HELO_PASS,SPF_PASS autolearn=ham
        autolearn_force=no version=3.4.6
X-Spam-Checker-Version: SpamAssassin 3.4.6 (2021-04-09) on
        lindbergh.monkeyblade.net
Precedence: bulk
List-ID: <linux-kernel.vger.kernel.org>
X-Mailing-List: linux-kernel@vger.kernel.org


Am 15.11.2022 um 18:43 schrieb Jonathan Cameron:
> On Tue, 15 Nov 2022 08:37:17 +0100
> Gerald Loacker <gerald.loacker@wolfvision.net> wrote:
> 
>> Add bindings documentation file for TI TMAG5273.
>>
>> Signed-off-by: Gerald Loacker <gerald.loacker@wolfvision.net>
>> ---
>>  .../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: https://eur04.safelinks.protection.outlook.com/?url=http%3A%2F%2Fdevicetree.org%2Fschemas%2Fiio%2Fmagnetometer%2Fti%2Ctmag5273.yaml%23&amp;data=05%7C01%7Cgerald.loacker%40wolfvision.net%7C9788e9788f344fcff9b808dac730f926%7Ce94ec9da9183471e83b351baa8eb804f%7C1%7C0%7C638041310400330990%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C3000%7C%7C%7C&amp;sdata=nczO1QC74gD6eGXAkm%2B6LRrc7fyEsr62r%2B3aoW%2Bcfu4%3D&amp;reserved=0
>> +$schema: https://eur04.safelinks.protection.outlook.com/?url=http%3A%2F%2Fdevicetree.org%2Fmeta-schemas%2Fcore.yaml%23&amp;data=05%7C01%7Cgerald.loacker%40wolfvision.net%7C9788e9788f344fcff9b808dac730f926%7Ce94ec9da9183471e83b351baa8eb804f%7C1%7C0%7C638041310400330990%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C3000%7C%7C%7C&amp;sdata=raKUiSntfhvdSSnqiR1Wm%2Fqr9cI3XEu5HCprqvISlLE%3D&amp;reserved=0
>> +
>> +title: TI TMAG5273 Low-Power Linear 3D Hall-Effect Sensor
>> +
>> +maintainers:
>> +  - Gerald Loacker <gerald.loacker@wolfvision.net>
>> +
>> +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]+$'
> 
> What Krzysztof said on this ;)
> 
>> +
>> +  compatible:
>> +    const: ti,tmag5273
>> +
>> +  reg:
>> +    maxItems: 1
>> +
>> +  "#io-channel-cells":
>> +    const: 1
>> +
>> +  ti,angle-enable:
>> +    description:
>> +      Enables angle measurement in the selected plane.
>> +      0 = OFF
>> +      1 = X-Y (default)
>> +      2 = Y-Z
>> +      3 = X-Z
> 
> This feels like something we should be configuring at runtime rather that
> DT, or is it driven by board design or similar?
> 

We use this sensor for a zoom wheel application, there is an EVM from TI
for this as well. So this is for setting the mounting position of the wheel.

>> +    $ref: /schemas/types.yaml#/definitions/uint32
>> +    minimum: 0
>> +    maximum: 3
>> +
>> +  vcc-supply:
>> +    description:
>> +      A regulator providing 1.7 V to 3.6 V supply voltage on the VCC pin,
>> +      typically 3.3 V.
>> +
> 
> The dt binding should attempt to describe the hardware, not what we happen
> to support in the driver so far. So I'd expect to also see an interrupt.
> That way if someone ships a dts file today, and we enable it sometime in the
> future they will be ready for it.
>

Is it fine to add just the description without example then? The
interrupt has many options such as low active or low pulse.

>> +required:
>> +  - compatible
>> +  - reg
>> +  - vcc-supply
> 
> Ah. This is presumably as side effect of having the driver set the voltage.
> Normally we only need to 'require' a supply if we need to read it's voltage
> (for scaling on ADCs and similar). That's not the case here so I wouldn't
> expect to see it.
> 
>> +
>> +additionalProperties: false
>> +
>> +examples:
>> +  - |
>> +    i2c-0 {
>> +        #address-cells = <1>;
>> +        #size-cells = <0>;
>> +
>> +        magnetometer@35 {
>> +            compatible = "ti,tmag5273";
>> +            reg = <0x35>;
>> +            #io-channel-cells = <1>;
>> +            ti,angle-enable = <3>;
>> +            vcc-supply = <&vcc3v3>;
>> +        };
>> +    };
>> +...
> 
> 

Thanks for the review,
Gerald