From patchwork Tue Apr 4 12:25:17 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Matti Vaittinen X-Patchwork-Id: 13199719 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by smtp.lore.kernel.org (Postfix) with ESMTP id 8272EC761A6 for ; Tue, 4 Apr 2023 12:26:18 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S234120AbjDDMZq (ORCPT ); Tue, 4 Apr 2023 08:25:46 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:34218 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S234795AbjDDMZ0 (ORCPT ); Tue, 4 Apr 2023 08:25:26 -0400 Received: from mail-lf1-x12a.google.com (mail-lf1-x12a.google.com [IPv6:2a00:1450:4864:20::12a]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id EE2ABE75; Tue, 4 Apr 2023 05:25:22 -0700 (PDT) Received: by mail-lf1-x12a.google.com with SMTP id y20so42220863lfj.2; Tue, 04 Apr 2023 05:25:22 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20210112; t=1680611121; h=in-reply-to:content-disposition:mime-version:references:message-id :subject:cc:to:from:date:from:to:cc:subject:date:message-id:reply-to; bh=ZDU+F1pTEz7orAogZEYM3SSlzH/hcRZ96/r/Tq0s37o=; b=aEOeBsszZH5JlFbVpcoaCviRe6tzX+l5bNSKVkKnFp1dTe2+iLJ2yPKc/QY9kBo1j1 XBXnTdZp4dqzgFFN2ZxdfXHBc+4wK0OVkK9WH99+uoq6tfmkbqefMKKk9pIOg7K4CuEF 7BlZiIvcAPPKSjdDTVrETXxDL/DQeHCwsQjkp1JsHVXPO4xxQpMEhAxGvQqU7XB+l4Iu F0j5kCVqEKzg5mIMmmiKYonSDZnylfeB+kpTeku/euwmYSPnZ6lQBfiz/uFvpoEm45vu THVbnjNtphm7hmvUJbYvXc0xJitzEpRy3X3cnrBHnnmkj5ivZrlflEsKGM2j0pNkIlFy V64g== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; t=1680611121; h=in-reply-to:content-disposition:mime-version:references:message-id :subject:cc:to:from:date:x-gm-message-state:from:to:cc:subject:date :message-id:reply-to; bh=ZDU+F1pTEz7orAogZEYM3SSlzH/hcRZ96/r/Tq0s37o=; b=BnKJLrnjt0J0Cw2g4bEAHVSOrSl6aGuYVLupxG8Sle5eKAPiwNj5fgQO+e70umW6ZQ SzuK5iR8ZQlDtwr5hseKsgxI5vBHmbswFtHyZKqNqxqp0dKngtFGmganI/n/DflTTBk8 F9aSNU35wd2iPSs0WE6KGeG8XYfnGULKzZVh6sMNP+M7qkihXIPU9eitUVUHVZ62zQaA bgFqfsd0tQinATmWiDogDnBHezNH/mUj+oU8C+XboiRpJki0SXhAvpGGGbIuF3kQ08z3 8xBXxzbPap7qUC7normlwZqHuvIKGkOji/EmjyIo4GOFnIvungNwuCHXxeiC/NSIsOkd crkA== X-Gm-Message-State: AAQBX9dxDNukAADdMEhKMBAx6sCzLXlSaoPLR95FiWblfpzbDHhqSZr9 NB9rSw3v2vf2h3GXHr19udU= X-Google-Smtp-Source: AKy350bai4lN1Sv512f7kHwLIM9QmUZCR1nqpnxjVoPGbJfzS0xnYeUWH9y/Oidfg7c/LQMI1mebLQ== X-Received: by 2002:a05:6512:410:b0:4e1:36a:eda5 with SMTP id u16-20020a056512041000b004e1036aeda5mr481748lfk.30.1680611121261; Tue, 04 Apr 2023 05:25:21 -0700 (PDT) Received: from fedora ([213.255.186.46]) by smtp.gmail.com with ESMTPSA id h27-20020ac2597b000000b004eae73a0530sm2295410lfp.39.2023.04.04.05.25.20 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 04 Apr 2023 05:25:20 -0700 (PDT) Date: Tue, 4 Apr 2023 15:25:17 +0300 From: Matti Vaittinen To: Matti Vaittinen , Matti Vaittinen Cc: Jonathan Cameron , Lars-Peter Clausen , linux-iio@vger.kernel.org, linux-kernel@vger.kernel.org Subject: [RESEND PATCH v2 2/3] iio: add documentation for iio_chan_info_enum Message-ID: <799dfdbe77ed562c400d76a0728153263e769198.1680610554.git.mazziesaccount@gmail.com> References: MIME-Version: 1.0 Content-Disposition: inline In-Reply-To: Precedence: bulk List-ID: X-Mailing-List: linux-iio@vger.kernel.org Values in the iio_chan_info_enum are crucial for understanding the characteristics of an IIO channel and the data delivered via IIO channel. Give a hand to developers who do their first set of IIO drivers. Add some documentation to these channel specifiers. Signed-off-by: Matti Vaittinen --- Please note that I did only add documentation for entries I am familiar with. I did still add doc placeholders for all of the enum entries to ease seeing which entries could still be documented. Hopefully this encourages people to add missing pieces of documentation. --- include/linux/iio/types.h | 46 ++++++++++++++++++++++++++++++++++++++- 1 file changed, 45 insertions(+), 1 deletion(-) diff --git a/include/linux/iio/types.h b/include/linux/iio/types.h index 82faa98c719a..c8e3288ca24b 100644 --- a/include/linux/iio/types.h +++ b/include/linux/iio/types.h @@ -35,7 +35,51 @@ enum iio_available_type { IIO_AVAIL_LIST, IIO_AVAIL_RANGE, }; - +/** + * enum iio_chan_info_enum - Information related to a IIO channel + * + * Many IIO channels have extra properties. Typically these properties can be + * read / written by user using the read_raw or write_raw callbacks in the + * struct iio_info. + * + * @IIO_CHAN_INFO_RAW: Raw channel data as provided by device. Scale + * and offset are often required to convert these + * values to meaningful units. + * @IIO_CHAN_INFO_PROCESSED: Processed data. Typically driver performs + * computations to convert device data to more + * meaningfull processed values. + * @IIO_CHAN_INFO_SCALE: Scale to be applied to data in order to convert + * it to units mandated by the channel type. + * @IIO_CHAN_INFO_OFFSET: Offset to be applied to data in order to convert + * it to units mandated by the channel type. + * @IIO_CHAN_INFO_CALIBSCALE: + * @IIO_CHAN_INFO_CALIBBIAS: + * @IIO_CHAN_INFO_PEAK: Peak value (TODO: Since measurement start?) + * @IIO_CHAN_INFO_PEAK_SCALE: Scale to be applied to the peak value in order + * to convert it to units mandated by the channel + * type. + * @IIO_CHAN_INFO_QUADRATURE_CORRECTION_RAW: + * @IIO_CHAN_INFO_AVERAGE_RAW: Average of raw values (TODO: Since measurement + * start or just for some undefined time?) + * @IIO_CHAN_INFO_SAMP_FREQ: Sampling frequency for device. + * @IIO_CHAN_INFO_FREQUENCY: + * @IIO_CHAN_INFO_PHASE: + * @IIO_CHAN_INFO_HARDWAREGAIN: Amplification applied by the hardware. + * @IIO_CHAN_INFO_HYSTERESIS: + * @IIO_CHAN_INFO_HYSTERESIS_RELATIVE: + * @IIO_CHAN_INFO_INT_TIME: Integration time. Time during which the data is + * accumulated by the device. + * @IIO_CHAN_INFO_ENABLE: + * @IIO_CHAN_INFO_CALIBHEIGHT: + * @IIO_CHAN_INFO_CALIBWEIGHT: + * @IIO_CHAN_INFO_DEBOUNCE_COUNT: + * @IIO_CHAN_INFO_DEBOUNCE_TIME: + * @IIO_CHAN_INFO_CALIBEMISSIVITY: + * @IIO_CHAN_INFO_OVERSAMPLING_RATIO: + * @IIO_CHAN_INFO_THERMOCOUPLE_TYPE: + * @IIO_CHAN_INFO_CALIBAMBIENT: + * @IIO_CHAN_INFO_ZEROPOINT: + */ enum iio_chan_info_enum { IIO_CHAN_INFO_RAW = 0, IIO_CHAN_INFO_PROCESSED, From patchwork Tue Apr 4 12:25:35 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Matti Vaittinen X-Patchwork-Id: 13199720 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by smtp.lore.kernel.org (Postfix) with ESMTP id E0E26C6FD1D for ; Tue, 4 Apr 2023 12:26:18 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S234529AbjDDMZr (ORCPT ); Tue, 4 Apr 2023 08:25:47 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:34478 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S234882AbjDDMZl (ORCPT ); Tue, 4 Apr 2023 08:25:41 -0400 Received: from mail-lf1-x12c.google.com (mail-lf1-x12c.google.com [IPv6:2a00:1450:4864:20::12c]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id E701B90; Tue, 4 Apr 2023 05:25:39 -0700 (PDT) Received: by mail-lf1-x12c.google.com with SMTP id bi9so42147005lfb.12; Tue, 04 Apr 2023 05:25:39 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20210112; t=1680611138; h=in-reply-to:content-disposition:mime-version:references:message-id :subject:cc:to:from:date:from:to:cc:subject:date:message-id:reply-to; bh=RGrcJymg+ckaukDnkYkL45EafR2fD169G3iZOtvge2g=; b=BTa8G3OTbNddd1DNHPTZfluySBVtJTcU+LjqTGxB5GfHbOu+ALGZTpnZkdDREd01Xa xAG4j6S1wYdSFnFIcY7r7wlO5MC8w6LrcRwftMKSUqnPOUK8YF1/qH/rB38MYUGa0WQY Z2TqYm9O5jOKEguCJ6pqBPUovbTIXDaenrzYamibmsPabXDQZ61Aemv6bAW4zIE1ECBX WAH5XVNBk/QVjybOCG5uWYG2lD4lkWPA0YeDvy2TT+a+hQB2gj0n+lKIAtyl0p2jC14d jci/aUVbUHzUyF5UMpW+afWtv47wIo5i7V3EmK78BkICyPi4pWzA8k5XQbP0iArVpmJe IH6g== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; t=1680611138; h=in-reply-to:content-disposition:mime-version:references:message-id :subject:cc:to:from:date:x-gm-message-state:from:to:cc:subject:date :message-id:reply-to; bh=RGrcJymg+ckaukDnkYkL45EafR2fD169G3iZOtvge2g=; b=RSBOs0AoHfYdaDm6+jTKOsS2A2vuVpt6Uimq5KVP9jVdwDSbgt0vvp8pTam8SvKGOx XmH4erMqpkgzqzIpgEpDt1/PD34wUszTDwnDQRYrhsRyDo6L2nsOsdper9f+8BW3evg4 iKOrVpRbYPB957WZYIl54Fiog09FUW1Ba0cXb1tFb7nijti2T6rP46pB4bF0F8RNJ15g sRaSmQarWrerFOYgZItxj6AI2BdtCb/kAOB+sWQ07pTJddaiMCGsjYkHmV/nV+4OlpIR egxXSZOLlG7r7f12JydFrKOQMfmkpACTUwtpsE27t0alzJ10CWM1y7aA5wraGF+3FG3G lFDQ== X-Gm-Message-State: AAQBX9fy/dEwwc+Wg6TaTLIAdpOcZkZNAGJF21rTT+XShFQBUiDjnF7K bB50gx/xyoI3yyceUvGbxAU= X-Google-Smtp-Source: AKy350Y0jpe/w9Uo3Kh8yAlk4zEOOyeI6H2j666l0rrxtXxYRejpjj+llllY0nfTyPhStpAjByRXzg== X-Received: by 2002:ac2:558d:0:b0:4e6:9b01:b92b with SMTP id v13-20020ac2558d000000b004e69b01b92bmr566067lfg.67.1680611138251; Tue, 04 Apr 2023 05:25:38 -0700 (PDT) Received: from fedora ([213.255.186.46]) by smtp.gmail.com with ESMTPSA id j27-20020ac253bb000000b004eaf8b20014sm2296281lfh.76.2023.04.04.05.25.37 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 04 Apr 2023 05:25:37 -0700 (PDT) Date: Tue, 4 Apr 2023 15:25:35 +0300 From: Matti Vaittinen To: Matti Vaittinen , Matti Vaittinen Cc: Jonathan Cameron , Lars-Peter Clausen , linux-iio@vger.kernel.org, linux-kernel@vger.kernel.org Subject: [RESEND PATCH v2 3/3] doc: Make sysfs-bus-iio doc more exact Message-ID: <4cbc9dd1dc5974f06be0c90e435970e1105f4636.1680610554.git.mazziesaccount@gmail.com> References: MIME-Version: 1.0 Content-Disposition: inline In-Reply-To: Precedence: bulk List-ID: X-Mailing-List: linux-iio@vger.kernel.org A few IIC channel descriptions explained used units as: data is in foo "that can be processed into an" [unit] value. The "can be processed into" is quite broad statement as it does not really explain what this processing means. This makes units pretty much useless. After discussion with Jonathan, it seems the units for these channels should also be well-defined as for all other channels. The processing means the standard scale and offset application that is used throughout the IIO. Let's make it more obvious by stating that the units are [unit] after scale ane offset are applied. Signed-off-by: Matti Vaittinen --- Documentation/ABI/testing/sysfs-bus-iio | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/Documentation/ABI/testing/sysfs-bus-iio b/Documentation/ABI/testing/sysfs-bus-iio index 6ba34c0d9789..b435c6f065ae 100644 --- a/Documentation/ABI/testing/sysfs-bus-iio +++ b/Documentation/ABI/testing/sysfs-bus-iio @@ -1807,8 +1807,8 @@ What: /sys/bus/iio/devices/iio:deviceX/out_resistanceX_raw KernelVersion: 4.3 Contact: linux-iio@vger.kernel.org Description: - Raw (unscaled no offset etc.) resistance reading that can be processed - into an ohm value. + Raw (unscaled no offset etc.) resistance reading. + Units after application of scale and offset are ohms. What: /sys/bus/iio/devices/iio:deviceX/heater_enable KernelVersion: 4.1.0 @@ -1894,8 +1894,9 @@ What: /sys/bus/iio/devices/iio:deviceX/in_electricalconductivity_raw KernelVersion: 4.8 Contact: linux-iio@vger.kernel.org Description: - Raw (unscaled no offset etc.) electric conductivity reading that - can be processed to siemens per meter. + Raw (unscaled no offset etc.) electric conductivity reading. + Units after application of scale and offset are siemens per + meter. What: /sys/bus/iio/devices/iio:deviceX/in_countY_raw KernelVersion: 4.10 @@ -1952,7 +1953,7 @@ KernelVersion: 4.18 Contact: linux-iio@vger.kernel.org Description: Raw (unscaled) phase difference reading from channel Y - that can be processed to radians. + Units after application of scale and offset are radians. What: /sys/bus/iio/devices/iio:deviceX/in_massconcentration_pm1_input What: /sys/bus/iio/devices/iio:deviceX/in_massconcentrationY_pm1_input