From nobody Mon Feb 9 06:40:26 2026 Received: from mx0a-00128a01.pphosted.com (mx0a-00128a01.pphosted.com [148.163.135.77]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 032451803D; Tue, 13 Feb 2024 08:17:56 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=148.163.135.77 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1707812278; cv=none; b=dLMl1SQeLBavDy4brloyxw71+U3a8icgz9F4IJDvv4UTsNZ0A8bvjkmtdsP1w7W+rOKb1jmk9qCK6iMHmN70I91tuUMM74q4AHe3j/je7g/JorVjES9MZ4OI2Ax8y2xSxvqyHpbc66bX7sW7PMIpSAnFgfvmYbCHkVH/yfB3dtg= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1707812278; c=relaxed/simple; bh=2LPM9xehDtHRXCEaDf/EFwMKT44BxFMzqxeDwpYhRgg=; h=From:To:CC:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=jiSpWwXoQoGuLR19Lw+flYymABKeoaaFNvYCJ9+V55mdEzKcCffj9BQdTzp1y1e3QvNpUppxlVfwu+SSxAEMrwxIYVmAWt8lfr7ZxUDUx+4/jTA3F3w5LeyMLOfoi/RWI5D/mVGt+QJ4AOUpEZ3nK1cN7zuJo+qrd1BnRsVTJT8= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=analog.com; spf=pass smtp.mailfrom=analog.com; dkim=pass (2048-bit key) header.d=analog.com header.i=@analog.com header.b=Tm8ZE6O/; arc=none smtp.client-ip=148.163.135.77 Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=analog.com Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=analog.com Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=analog.com header.i=@analog.com header.b="Tm8ZE6O/" Received: from pps.filterd (m0167088.ppops.net [127.0.0.1]) by mx0a-00128a01.pphosted.com (8.17.1.24/8.17.1.24) with ESMTP id 41D7pL7N028931; Tue, 13 Feb 2024 03:17:42 -0500 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=analog.com; h= from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding:content-type; s=DKIM; bh=CwhGNlHoDNSJ9sXx6xc2y1ZwD5Ps1hKjERoLq7p5dcM=; b=Tm8ZE6O/a6AI PxMUCr3T6LmJuoEGQkZE7l4AkEqQNVeV4dTR9jkAeifdC588QtA97Zn9L2QmeBa8 ZaAWpjeJL7CQgHlhL21Dbvz+kk0qlt7/5NsbPHSdEhHuiC8pi5BdmwFcmrK26umV fYE4aWjG4esor5XGbjQEDUk/WlXo+izHHpqYfBRFORk9A5+Y0aWYrwSp3pYOI0KT 7Pn+QZbKQhGatQ64aoE0SyUG5ZryddALZbv6vXEVxOsxmlD5GF0NRHY9T7npWTIN 7yg6Jnzmfy5BOfOURjiVyWxuNGpS9D79znJTU6pbE2EiAyYRPGlAYBd8+JMjb5G6 sOv7KK1yow== Received: from nwd2mta4.analog.com ([137.71.173.58]) by mx0a-00128a01.pphosted.com (PPS) with ESMTPS id 3w6pwkr27k-1 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=NOT); Tue, 13 Feb 2024 03:17:41 -0500 (EST) Received: from ASHBMBX8.ad.analog.com (ASHBMBX8.ad.analog.com [10.64.17.5]) by nwd2mta4.analog.com (8.14.7/8.14.7) with ESMTP id 41D8HeMN020758 (version=TLSv1/SSLv3 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=FAIL); Tue, 13 Feb 2024 03:17:40 -0500 Received: from ASHBCASHYB4.ad.analog.com (10.64.17.132) by ASHBMBX8.ad.analog.com (10.64.17.5) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.2.986.14; Tue, 13 Feb 2024 03:17:39 -0500 Received: from ASHBMBX8.ad.analog.com (10.64.17.5) by ASHBCASHYB4.ad.analog.com (10.64.17.132) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.2.986.14; Tue, 13 Feb 2024 03:17:39 -0500 Received: from zeus.spd.analog.com (10.66.68.11) by ashbmbx8.ad.analog.com (10.64.17.5) with Microsoft SMTP Server id 15.2.986.14 via Frontend Transport; Tue, 13 Feb 2024 03:17:39 -0500 Received: from rbolboac.ad.analog.com ([10.48.65.135]) by zeus.spd.analog.com (8.15.1/8.15.1) with ESMTP id 41D8HPZC025896; Tue, 13 Feb 2024 03:17:31 -0500 From: Ramona Gradinariu To: , , , , , CC: Ramona Gradinariu Subject: [PATCH v4 1/3] docs: iio: Refactor index.rst Date: Tue, 13 Feb 2024 10:17:18 +0200 Message-ID: <20240213081720.17549-2-ramona.gradinariu@analog.com> X-Mailer: git-send-email 2.34.1 In-Reply-To: <20240213081720.17549-1-ramona.gradinariu@analog.com> References: <20240213081720.17549-1-ramona.gradinariu@analog.com> Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-ADIRuleOP-NewSCL: Rule Triggered X-Proofpoint-GUID: PL0Rnihg7T4kBoqyL20Q863WfBV3dY6T X-Proofpoint-ORIG-GUID: PL0Rnihg7T4kBoqyL20Q863WfBV3dY6T X-Proofpoint-Virus-Version: vendor=baseguard engine=ICAP:2.0.272,Aquarius:18.0.1011,Hydra:6.0.619,FMLib:17.11.176.26 definitions=2024-02-13_04,2024-02-12_03,2023-05-22_02 X-Proofpoint-Spam-Details: rule=outbound_notspam policy=outbound score=0 impostorscore=0 suspectscore=0 mlxlogscore=899 mlxscore=0 malwarescore=0 bulkscore=0 priorityscore=1501 adultscore=0 phishscore=0 lowpriorityscore=0 spamscore=0 clxscore=1015 classifier=spam adjust=0 reason=mlx scancount=1 engine=8.19.0-2401310000 definitions=main-2402130064 Content-Type: text/plain; charset="utf-8" Refactor index.rst such that it contains a section for generic documentation and a section for Kernel Drivers documentation. Signed-off-by: Ramona Gradinariu --- changes in v4: - no changes Documentation/iio/index.rst | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/Documentation/iio/index.rst b/Documentation/iio/index.rst index 1b7292c58cd0..db341b45397f 100644 --- a/Documentation/iio/index.rst +++ b/Documentation/iio/index.rst @@ -9,6 +9,11 @@ Industrial I/O iio_configfs - ep93xx_adc +Industrial I/O Kernel Drivers +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D + +.. toctree:: + :maxdepth: 1 bno055 + ep93xx_adc -- 2.34.1 From nobody Mon Feb 9 06:40:26 2026 Received: from mx0a-00128a01.pphosted.com (mx0a-00128a01.pphosted.com [148.163.135.77]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 8656218021; Tue, 13 Feb 2024 08:17:55 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=148.163.135.77 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1707812277; cv=none; b=P8o4rMLbtgCDX9Hx5NVP3e1514NlWe+oGEXTUw+QhsL0ulfW/rpc6cbrtLz5jCdz9Lnd8s8NJ6QkMaEnYoLwLQa9cHY6xLQdykXoXvBjlNlPhwdKi1KGNA2pCOH0wyWLKfsZPtC1GIwU5qujHLMXLO0CHpGntkTRpxqQ6C6EJkk= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1707812277; c=relaxed/simple; bh=qz1KjHhNg6NGtRHQ3eDGvhUY5yJSnHhvVMJmlHHPcPI=; h=From:To:CC:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=RJku8zgC9wqgzcxOw4Du+3GtLQZRKozQTaPWIjsaZzjIgue3jesT9ePlIcnLak7L3noaYu0QFjjY/pbkUeiJ4SChYSEfVRW2Wcxw/+ts+VlnAQbRmc3U1YKhlWFzSAu/xY4ecJcrSAha+i4R+H6yxPjBvZyIPF1AAYWlYrW2rdg= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=analog.com; spf=pass smtp.mailfrom=analog.com; dkim=pass (2048-bit key) header.d=analog.com header.i=@analog.com header.b=hUqdw0ZV; arc=none smtp.client-ip=148.163.135.77 Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=analog.com Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=analog.com Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=analog.com header.i=@analog.com header.b="hUqdw0ZV" Received: from pps.filterd (m0167089.ppops.net [127.0.0.1]) by mx0a-00128a01.pphosted.com (8.17.1.24/8.17.1.24) with ESMTP id 41D502ds030222; Tue, 13 Feb 2024 03:17:41 -0500 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=analog.com; h= from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding:content-type; s=DKIM; bh=DnAfRvcipg12KYQjy36NDZKbfT9A/4H/WBdI7PSYYKM=; b=hUqdw0ZVh7nr x6VwTd5kbV+dx51TuQcAUUDst1Hvhl/e8UdPhaca+/NxyzKm9Ny+ujng8VLCXTbX NuiuAaLWIqNH5zXBlQvt9+VTCuh8aEXb+eGJK6RWUF0DmhNxu69aLZlNCv5adriA V2FtNPppJnj4158+mCJB+fp7IGkNLa7yx1a8/WQ4q/CQ8bZKSkblS9NMjORQF1Lx E7sHr1TaTsGXISMzt2yfBXGuFg79Bq0N/jQ6irRDn09CwuHMtjBgEdcqxvbsEwUf Sgzi02cY1kbwWeypbbnxK40RD5ejb/HpibTEAg0XBhmAnD6xWbHNPOnArmhsVJPk uRagz3JW5g== Received: from nwd2mta3.analog.com ([137.71.173.56]) by mx0a-00128a01.pphosted.com (PPS) with ESMTPS id 3w6pur7w0u-1 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=NOT); Tue, 13 Feb 2024 03:17:41 -0500 (EST) Received: from ASHBMBX9.ad.analog.com (ASHBMBX9.ad.analog.com [10.64.17.10]) by nwd2mta3.analog.com (8.14.7/8.14.7) with ESMTP id 41D8HeqK056227 (version=TLSv1/SSLv3 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=FAIL); Tue, 13 Feb 2024 03:17:40 -0500 Received: from ASHBMBX8.ad.analog.com (10.64.17.5) by ASHBMBX9.ad.analog.com (10.64.17.10) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.2.986.14; Tue, 13 Feb 2024 03:17:38 -0500 Received: from zeus.spd.analog.com (10.66.68.11) by ashbmbx8.ad.analog.com (10.64.17.5) with Microsoft SMTP Server id 15.2.986.14 via Frontend Transport; Tue, 13 Feb 2024 03:17:38 -0500 Received: from rbolboac.ad.analog.com ([10.48.65.135]) by zeus.spd.analog.com (8.15.1/8.15.1) with ESMTP id 41D8HPZD025896; Tue, 13 Feb 2024 03:17:32 -0500 From: Ramona Gradinariu To: , , , , , CC: Ramona Gradinariu Subject: [PATCH v4 2/3] docs: iio: add documentation for device buffers Date: Tue, 13 Feb 2024 10:17:19 +0200 Message-ID: <20240213081720.17549-3-ramona.gradinariu@analog.com> X-Mailer: git-send-email 2.34.1 In-Reply-To: <20240213081720.17549-1-ramona.gradinariu@analog.com> References: <20240213081720.17549-1-ramona.gradinariu@analog.com> Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-ADIRuleOP-NewSCL: Rule Triggered X-Proofpoint-GUID: N3xqqzablP9scW1B7oe3OQ1FmiteJyxq X-Proofpoint-ORIG-GUID: N3xqqzablP9scW1B7oe3OQ1FmiteJyxq X-Proofpoint-Virus-Version: vendor=baseguard engine=ICAP:2.0.272,Aquarius:18.0.1011,Hydra:6.0.619,FMLib:17.11.176.26 definitions=2024-02-13_04,2024-02-12_03,2023-05-22_02 X-Proofpoint-Spam-Details: rule=outbound_notspam policy=outbound score=0 lowpriorityscore=0 clxscore=1015 phishscore=0 spamscore=0 mlxlogscore=999 suspectscore=0 priorityscore=1501 adultscore=0 impostorscore=0 mlxscore=0 bulkscore=0 malwarescore=0 classifier=spam adjust=0 reason=mlx scancount=1 engine=8.19.0-2401310000 definitions=main-2402130064 Content-Type: text/plain; charset="utf-8" Add documentation for IIO device buffers describing buffer attributes and how data is structured in buffers using scan elements. Signed-off-by: Ramona Gradinariu --- changes in v4: - documented multiple buffer support - reworked scan elements section - added reference to ABI docs Documentation/iio/iio_devbuf.rst | 125 +++++++++++++++++++++++++++++++ Documentation/iio/index.rst | 1 + 2 files changed, 126 insertions(+) create mode 100644 Documentation/iio/iio_devbuf.rst diff --git a/Documentation/iio/iio_devbuf.rst b/Documentation/iio/iio_devbu= f.rst new file mode 100644 index 000000000000..e99143efb4d7 --- /dev/null +++ b/Documentation/iio/iio_devbuf.rst @@ -0,0 +1,125 @@ +.. SPDX-License-Identifier: GPL-2.0 + +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D +Industrial IIO device buffers +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D + +1. Overview +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +The Industrial I/O core offers a way for continuous data capture based on a +trigger source. Multiple data channels can be read at once from +/dev/iio:deviceX character device node, thus reducing the CPU load. + +Devices with buffer support feature an additional sub-folder in the +/sys/bus/iio/devices/deviceX/ folder hierarchy, called bufferY, where Y de= faults +to 0, for devices with a single buffer. + +2. Buffer attributes +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +An IIO buffer has an associated attributes directory under +/sys/bus/iio/iio:deviceX/bufferY/. The attributes are described below. + +Length +------ + +Read / Write attribute which states the total number of data samples (capa= city) +that can be stored by the buffer. + +Enable +------ + +Read / Write attribute which starts / stops the buffer capture. This file = should +be written last, after length and selection of scan elements. + +Watermark +--------- + +Read / Write positive integer attribute specifying the maximum number of s= can +elements to wait for. + +Poll will block until the watermark is reached. + +Blocking read will wait until the minimum between the requested read amoun= t or +the low water mark is available. + +Non-blocking read will retrieve the available samples from the buffer even= if +there are less samples then watermark level. This allows the application to +block on poll with a timeout and read the available samples after the time= out +expires and thus have a maximum delay guarantee. + +Data available +-------------- + +Read-only attribute indicating the bytes of data available in the buffer. = In the +case of an output buffer, this indicates the amount of empty space availab= le to +write data to. In the case of an input buffer, this indicates the amount o= f data +available for reading. + +Scan elements +------------- + +The meta information associated with a channel reading placed in a buffer = is +called a scan element. The scan elements are configurable per buffer, thus= they +are exposed to userspace applications via the /sys/bus/iio/iio:deviceX/buf= ferY/ +directory. The scan elements attributes are presented below. + +**_en** + +Read/ Write attribute used for enabling a channel. If and only if its value +is non zero, then a triggered capture will contain data samples for this +channel. + +**_index** + +Read-only positive integer attribute specifying the position of the channe= l in +the buffer. Note these are not dependent on what is enabled and may not be +contiguous. Thus for user-space to establish the full layout these must be= used +in conjunction with all _en attributes to establish which channels are pre= sent, +and the relevant _type attributes to establish the data storage format. + +**_type** + +Read-only attribute containing the description of the scan element data st= orage +within the buffer and hence the form in which it is read from user space. = Format +is [be|le]:[s|u]bits/storagebits[Xrepeat][>>shift], where: + +- **be** or **le** specifies big or little endian. +- **s** or **u**, specifies if signed (2's complement) or unsigned. +- **bits**, is the number of valid data bits. +- **storagebits**, is the number of bits (after padding) that it occupies = in the + buffer. +- **repeat**, specifies the number of bits/storagebits repetitions. When t= he + repeat element is 0 or 1, then the repeat value is omitted. +- **shift**, if specified, is the shift that needs to be applied prior to + masking out unused bits. + +For example, a driver for a 3-axis accelerometer with 12 bit resolution wh= ere +data is stored in two 8-bits registers as follows: + +.. code-block:: bash + + 7 6 5 4 3 2 1 0 + +---+---+---+---+---+---+---+---+ + |D3 |D2 |D1 |D0 | X | X | X | X | (LOW byte, address 0x06) + +---+---+---+---+---+---+---+---+ + + 7 6 5 4 3 2 1 0 + +---+---+---+---+---+---+---+---+ + |D11|D10|D9 |D8 |D7 |D6 |D5 |D4 | (HIGH byte, address 0x07) + +---+---+---+---+---+---+---+---+ + +will have the following scan element type for each axis: + +.. code-block:: bash + + $ cat /sys/bus/iio/devices/iio:device0/buffer0/in_accel_y_type + le:s12/16>>4 + +A user space application will interpret data samples read from the buffer = as two +byte little endian signed data, that needs a 4 bits right shift before mas= king +out the 12 valid bits of data. + +Please see Documentation/ABI/testing/sysfs-bus-iio for a complete descript= ion of +the attributes. diff --git a/Documentation/iio/index.rst b/Documentation/iio/index.rst index db341b45397f..206a0aff5ca1 100644 --- a/Documentation/iio/index.rst +++ b/Documentation/iio/index.rst @@ -8,6 +8,7 @@ Industrial I/O :maxdepth: 1 iio_configfs + iio_devbuf Industrial I/O Kernel Drivers =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D -- 2.34.1 From nobody Mon Feb 9 06:40:26 2026 Received: from mx0a-00128a01.pphosted.com (mx0a-00128a01.pphosted.com [148.163.135.77]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 86510224D2; Tue, 13 Feb 2024 08:17:59 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=148.163.135.77 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1707812281; cv=none; b=Cmf9ieOmEHa/JF09c9Hg6QfObSYJr1LeKpZJ11WdJY5uvEwExrkpEAkO4djGre74JgNrBlfqbMY1tcQKPUqi9BFQrKZEjPLY8DPZufl523a9R2bu6ZuMYI65/FtuTx4ntTtlS/anA91cWmyDTtUTqpfmNSVaG1uYNv6lg8+I5pQ= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1707812281; c=relaxed/simple; bh=RSQJNxVZJiEPMKq+K+YWhveqK1PRfsOvRs7OqStA3KM=; h=From:To:CC:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=snFLPrCNIJkR8DOHXt5xKlK2xUg2CTj63KYj2VPG37s4A9f1CGy3M4+DGFrt5AfHXJ9ZscM40PoO4z4PJ+fI4ubVlIq91P4luhwzPgbHqHfkatuL6TUxwRuhwB7gcoZ7rKu9xABtTUX1tLf8a9yehWZLV71hbLqzGnlQlNb0wyQ= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=analog.com; spf=pass smtp.mailfrom=analog.com; dkim=pass (2048-bit key) header.d=analog.com header.i=@analog.com header.b=nTFtm+vZ; arc=none smtp.client-ip=148.163.135.77 Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=analog.com Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=analog.com Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=analog.com header.i=@analog.com header.b="nTFtm+vZ" Received: from pps.filterd (m0167089.ppops.net [127.0.0.1]) by mx0a-00128a01.pphosted.com (8.17.1.24/8.17.1.24) with ESMTP id 41D5DFod031510; Tue, 13 Feb 2024 03:17:44 -0500 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=analog.com; h= from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-type:content-transfer-encoding; s=DKIM; bh=T1nIzmhDwvbpQj/V5XOyknY0HdAsRB+mfrIK3JqVbEY=; b=nTFtm+vZRCQE 7Fgc2CWsum7s+aC2mkI3Wv7k+enJkiRnEGqPwvM2VLmVQG6yzutRswFvngtJDCvG y3M42eup0zA7JpFP5PQKG4yFLVbVwPqaz0f0bU9OykEW4vB/xmzgmbu1/rOCOA6P q5Z/BxNXEqZVvbD4g6cOP8uisHDJGErC1A9p7fZmTgo0bfTUNEw7xUl5szo4NYxZ vRbcQROjYIOMUA1/L66VY2j8EYTeL4zQb33DTD/4wQaiH9ICTd+ieM6M64PhHQTw bK6UUv2ZYxdmd50/aiowOjGKkXjOYBhhRpFxXPDsb04nI4UMJfSn0stPws5fvZO8 HQEr023NEQ== Received: from nwd2mta3.analog.com ([137.71.173.56]) by mx0a-00128a01.pphosted.com (PPS) with ESMTPS id 3w6pur7w0x-1 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=NOT); Tue, 13 Feb 2024 03:17:44 -0500 (EST) Received: from ASHBMBX9.ad.analog.com (ASHBMBX9.ad.analog.com [10.64.17.10]) by nwd2mta3.analog.com (8.14.7/8.14.7) with ESMTP id 41D8HgNf056232 (version=TLSv1/SSLv3 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=FAIL); Tue, 13 Feb 2024 03:17:42 -0500 Received: from ASHBCASHYB4.ad.analog.com (10.64.17.132) by ASHBMBX9.ad.analog.com (10.64.17.10) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.2.986.14; Tue, 13 Feb 2024 03:17:41 -0500 Received: from ASHBMBX9.ad.analog.com (10.64.17.10) by ASHBCASHYB4.ad.analog.com (10.64.17.132) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.2.986.14; Tue, 13 Feb 2024 03:17:41 -0500 Received: from zeus.spd.analog.com (10.66.68.11) by ashbmbx9.ad.analog.com (10.64.17.10) with Microsoft SMTP Server id 15.2.986.14 via Frontend Transport; Tue, 13 Feb 2024 03:17:41 -0500 Received: from rbolboac.ad.analog.com ([10.48.65.135]) by zeus.spd.analog.com (8.15.1/8.15.1) with ESMTP id 41D8HPZE025896; Tue, 13 Feb 2024 03:17:33 -0500 From: Ramona Gradinariu To: , , , , , CC: Ramona Gradinariu Subject: [PATCH v4 3/3] docs: iio: add documentation for adis16475 driver Date: Tue, 13 Feb 2024 10:17:20 +0200 Message-ID: <20240213081720.17549-4-ramona.gradinariu@analog.com> X-Mailer: git-send-email 2.34.1 In-Reply-To: <20240213081720.17549-1-ramona.gradinariu@analog.com> References: <20240213081720.17549-1-ramona.gradinariu@analog.com> Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable X-ADIRuleOP-NewSCL: Rule Triggered X-Proofpoint-GUID: TUr3JhttarqdnpX74364gse-vHLaSwYz X-Proofpoint-ORIG-GUID: TUr3JhttarqdnpX74364gse-vHLaSwYz X-Proofpoint-Virus-Version: vendor=baseguard engine=ICAP:2.0.272,Aquarius:18.0.1011,Hydra:6.0.619,FMLib:17.11.176.26 definitions=2024-02-13_04,2024-02-12_03,2023-05-22_02 X-Proofpoint-Spam-Details: rule=outbound_notspam policy=outbound score=0 lowpriorityscore=0 clxscore=1015 phishscore=0 spamscore=0 mlxlogscore=999 suspectscore=0 priorityscore=1501 adultscore=0 impostorscore=0 mlxscore=0 bulkscore=0 malwarescore=0 classifier=spam adjust=0 reason=mlx scancount=1 engine=8.19.0-2401310000 definitions=main-2402130064 Add documentation for adis16475 driver which describes the driver device files and shows how the user may use the ABI for various scenarios (configuration, measurement, etc.). Signed-off-by: Ramona Gradinariu --- changes in v4: - fixed typos - added IIO interfacing tools section Documentation/iio/adis16475.rst | 406 ++++++++++++++++++++++++++++++++ Documentation/iio/index.rst | 1 + 2 files changed, 407 insertions(+) create mode 100644 Documentation/iio/adis16475.rst diff --git a/Documentation/iio/adis16475.rst b/Documentation/iio/adis16475.= rst new file mode 100644 index 000000000000..720995acbe24 --- /dev/null +++ b/Documentation/iio/adis16475.rst @@ -0,0 +1,406 @@ +.. SPDX-License-Identifier: GPL-2.0 + +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D +ADIS16475 driver +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +This driver supports Analog Device's IMUs on SPI bus. + +1. Supported devices +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +* `ADIS16465 `_ +* `ADIS16467 `_ +* `ADIS16470 `_ +* `ADIS16475 `_ +* `ADIS16477 `_ +* `ADIS16500 `_ +* `ADIS16505 `_ +* `ADIS16507 `_ + +Each supported device is a precision, miniature microelectromechanical sys= tem +(MEMS) inertial measurement unit (IMU) that includes a triaxial gyroscope = and a +triaxial accelerometer. Each inertial sensor in the IMU device combines wi= th +signal conditioning that optimizes dynamic performance. The factory calibr= ation +characterizes each sensor for sensitivity, bias, alignment, linear acceler= ation +(gyroscope bias), and point of percussion (accelerometer location). As a r= esult, +each sensor has dynamic compensation formulas that provide accurate sensor +measurements over a broad set of conditions. + +2. Device attributes +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +Accelerometer, gyroscope measurements are always provided. Furthermore, the +driver offers the capability to retrieve the delta angle and the delta vel= ocity +measurements computed by the device. + +The delta angle measurements represent a calculation of angular displaceme= nt +between each sample update, while the delta velocity measurements represen= t a +calculation of linear velocity change between each sample update. + +Finally, temperature data are provided which show a coarse measurement of +the temperature inside of the IMU device. This data is most useful for +monitoring relative changes in the thermal environment. + +The signal chain of each inertial sensor (accelerometers and gyroscopes) +includes the application of unique correction formulas, which are derived = from +extensive characterization of bias, sensitivity, alignment, response to li= near +acceleration (gyroscopes), and point of percussion (accelerometer location) +over a temperature range of =E2=88=9240=C2=B0C to +85=C2=B0C, for each ADI= S device. These +correction formulas are not accessible, but users do have the opportunity = to +adjust the bias for each sensor individually through the calibbias attribu= te. + +Each IIO device, has a device folder under /sys/bus/iio/devices/iio:device= X, +where X is the IIO index of the device. Under these folders reside a set of +device files, depending on the characteristics and features of the hardware +device in questions. These files are consistently generalized and document= ed in +the IIO ABI documentation. + +The following tables show the adis16475 related device files, found in the +specific device folder path /sys/bus/iio/devices/iio:deviceX. + ++-------------------------------------------+-----------------------------= -----------------------------+ +| 3-Axis Accelerometer related device files | Description = | ++-------------------------------------------+-----------------------------= -----------------------------+ +| in_accel_scale | Scale for the accelerometer = channels. | ++-------------------------------------------+-----------------------------= -----------------------------+ +| in_accel_x_calibbias | Calibration offset for the X= -axis accelerometer channel. | ++-------------------------------------------+-----------------------------= -----------------------------+ +| in_accel_calibbias_x | x-axis acceleration offset c= orrection | ++-------------------------------------------+-----------------------------= -----------------------------+ +| in_accel_x_raw | Raw X-axis accelerometer cha= nnel value. | ++-------------------------------------------+-----------------------------= -----------------------------+ +| in_accel_calibbias_y | y-axis acceleration offset c= orrection | ++-------------------------------------------+-----------------------------= -----------------------------+ +| in_accel_y_raw | Raw Y-axis accelerometer cha= nnel value. | ++-------------------------------------------+-----------------------------= -----------------------------+ +| in_accel_z_calibbias | Calibration offset for the Z= -axis accelerometer channel. | ++-------------------------------------------+-----------------------------= -----------------------------+ +| in_accel_z_raw | Raw Z-axis accelerometer cha= nnel value. | ++-------------------------------------------+-----------------------------= -----------------------------+ +| in_deltavelocity_scale | Scale for delta velocity cha= nnels. | ++-------------------------------------------+-----------------------------= -----------------------------+ +| in_deltavelocity_x_raw | Raw X-axis delta velocity ch= annel value. | ++-------------------------------------------+-----------------------------= -----------------------------+ +| in_deltavelocity_y_raw | Raw Y-axis delta velocity ch= annel value. | ++-------------------------------------------+-----------------------------= -----------------------------+ +| in_deltavelocity_z_raw | Raw Z-axis delta velocity ch= annel value. | ++-------------------------------------------+-----------------------------= -----------------------------+ + ++---------------------------------------+---------------------------------= ---------------------+ +| 3-Axis Gyroscope related device files | Description = | ++---------------------------------------+---------------------------------= ---------------------+ +| in_anglvel_scale | Scale for the gyroscope channels= . | ++---------------------------------------+---------------------------------= ---------------------+ +| in_anglvel_x_calibbias | Calibration offset for the X-axi= s gyroscope channel. | ++---------------------------------------+---------------------------------= ---------------------+ +| in_anglvel_calibbias_x | x-axis gyroscope offset correcti= on | ++---------------------------------------+---------------------------------= ---------------------+ +| in_anglvel_x_raw | Raw X-axis gyroscope channel val= ue. | ++---------------------------------------+---------------------------------= ---------------------+ +| in_anglvel_calibbias_y | y-axis gyroscope offset correcti= on | ++---------------------------------------+---------------------------------= ---------------------+ +| in_anglvel_y_raw | Raw Y-axis gyroscope channel val= ue. | ++---------------------------------------+---------------------------------= ---------------------+ +| in_anglvel_z_calibbias | Calibration offset for the Z-axi= s gyroscope channel. | ++---------------------------------------+---------------------------------= ---------------------+ +| in_anglvel_z_raw | Raw Z-axis gyroscope channel val= ue. | ++---------------------------------------+---------------------------------= ---------------------+ +| in_deltaangl_scale | Scale for delta angle channels. = | ++---------------------------------------+---------------------------------= ---------------------+ +| in_deltaangl_x_raw | Raw X-axis delta angle channel v= alue. | ++---------------------------------------+---------------------------------= ---------------------+ +| in_deltaangl_y_raw | Raw Y-axis delta angle channel v= alue. | ++---------------------------------------+---------------------------------= ---------------------+ +| in_deltaangl_z_raw | Raw Z-axis delta angle channel v= alue. | ++---------------------------------------+---------------------------------= ---------------------+ + ++----------------------------------+--------------------------------------= -----+ +| Temperature sensor related files | Description = | ++----------------------------------+--------------------------------------= -----+ +| in_temp0_raw | Raw temperature channel value. = | ++----------------------------------+--------------------------------------= -----+ +| in_temp0_scale | Scale for the temperature sensor chan= nel. | ++----------------------------------+--------------------------------------= -----+ + ++-------------------------------+-----------------------------------------= ----------------+ +| Miscellaneous device files | Description = | ++-------------------------------+-----------------------------------------= ----------------+ +| name | Name of the IIO device. = | ++-------------------------------+-----------------------------------------= ----------------+ +| sampling_frequency | Currently selected sample rate. = | ++-------------------------------+-----------------------------------------= ----------------+ +| filter_low_pass_3db_frequency | Bandwidth for the accelerometer and gyro= scope channels. | ++-------------------------------+-----------------------------------------= ----------------+ + +The following table shows the adis16475 related device debug files, found = in the +specific device debug folder path /sys/kernel/debug/iio/iio:deviceX. + ++----------------------+--------------------------------------------------= -----------------------+ +| Debugfs device files | Description = | ++----------------------+--------------------------------------------------= -----------------------+ +| serial_number | The serial number of the chip in hexadecimal form= at. | ++----------------------+--------------------------------------------------= -----------------------+ +| product_id | Chip specific product id (e.g. 16475, 16500, 1650= 5, etc.). | ++----------------------+--------------------------------------------------= -----------------------+ +| flash_count | The number of flash writes performed on the devic= e. | ++----------------------+--------------------------------------------------= -----------------------+ +| firmware_revision | String containing the firmware revision in the fo= llowing format ##.##. | ++----------------------+--------------------------------------------------= -----------------------+ +| firmware_date | String containing the firmware date in the follow= ing format mm-dd-yyyy. | ++----------------------+--------------------------------------------------= -----------------------+ + +Channels processed values +------------------------- + +A channel value can be read from its _raw attribute. The value returned is= the +raw value as reported by the devices. To get the processed value of the ch= annel, +apply the following formula: + +.. code-block:: bash + + processed value =3D (_raw + _offset) * _scale + +Where _offset and _scale are device attributes. If no _offset attribute is +present, simply assume its value is 0. + +The adis16475 driver offers data for 5 types of channels, the table below = shows +the measurement units for the processed value, which are defined by the IIO +framework: + ++-------------------------------------+---------------------------+ +| Channel type | Measurement unit | ++-------------------------------------+---------------------------+ +| Acceleration on X, Y, and Z axis | Meters per Second squared | ++-------------------------------------+---------------------------+ +| Angular velocity on X, Y and Z axis | Radians per second | ++-------------------------------------+---------------------------+ +| Delta velocity on X. Y, and Z axis | Meters per Second | ++-------------------------------------+---------------------------+ +| Delta angle on X, Y, and Z axis | Radians | ++-------------------------------------+---------------------------+ +| Temperature | Millidegrees Celsius | ++-------------------------------------+---------------------------+ + +Usage examples +-------------- + +Show device name: + +.. code-block:: bash + + root:/sys/bus/iio/devices/iio:device0> cat name + adis16505-2 + +Show accelerometer channels value: + +.. code-block:: bash + + root:/sys/bus/iio/devices/iio:device0> cat in_accel_x_raw + -275924 + root:/sys/bus/iio/devices/iio:device0> cat in_accel_y_raw + -30142222 + root:/sys/bus/iio/devices/iio:device0> cat in_accel_z_raw + 261265769 + root:/sys/bus/iio/devices/iio:device0> cat in_accel_scale + 0.000000037 + +- X-axis acceleration =3D in_accel_x_raw * in_accel_scale =3D =E2=88=920.0= 10209188 m/s^2 +- Y-axis acceleration =3D in_accel_y_raw * in_accel_scale =3D =E2=88=921.1= 15262214 m/s^2 +- Z-axis acceleration =3D in_accel_z_raw * in_accel_scale =3D 9.666833453 = m/s^2 + +Show gyroscope channels value: + +.. code-block:: bash + + root:/sys/bus/iio/devices/iio:device0> cat in_anglvel_x_raw + -3324626 + root:/sys/bus/iio/devices/iio:device0> cat in_anglvel_y_raw + 1336980 + root:/sys/bus/iio/devices/iio:device0> cat in_anglvel_z_raw + -602983 + root:/sys/bus/iio/devices/iio:device0> cat in_anglvel_scale + 0.000000006 + +- X-axis angular velocity =3D in_anglvel_x_raw * in_anglvel_scale =3D =E2= =88=920.019947756 rad/s +- Y-axis angular velocity =3D in_anglvel_y_raw * in_anglvel_scale =3D 0.00= 802188 rad/s +- Z-axis angular velocity =3D in_anglvel_z_raw * in_anglvel_scale =3D =E2= =88=920.003617898 rad/s + +Set calibration offset for accelerometer channels: + +.. code-block:: bash + + root:/sys/bus/iio/devices/iio:device0> cat in_accel_x_calibbias + 0 + + root:/sys/bus/iio/devices/iio:device0> echo 5000 > in_accel_x_cali= bbias + root:/sys/bus/iio/devices/iio:device0> cat in_accel_x_calibbias + 5000 + +Set calibration offset for gyroscope channels: + +.. code-block:: bash + + root:/sys/bus/iio/devices/iio:device0> cat in_anglvel_y_calibbias + 0 + + root:/sys/bus/iio/devices/iio:device0> echo -5000 > in_anglvel_y_c= alibbias + root:/sys/bus/iio/devices/iio:device0> cat in_anglvel_y_calibbias + -5000 + +Set sampling frequency: + +.. code-block:: bash + + root:/sys/bus/iio/devices/iio:device0> cat sampling_frequency + 2000.000000 + + root:/sys/bus/iio/devices/iio:device0> echo 1000 > sampling_freque= ncy + 1000.000000 + +Set bandwidth for accelerometer and gyroscope: + +.. code-block:: bash + + root:/sys/bus/iio/devices/iio:device0> cat filter_low_pass_3db_fre= quency + 720 + + root:/sys/bus/iio/devices/iio:device0> echo 360 > filter_low_pass_= 3db_frequency + root:/sys/bus/iio/devices/iio:device0> cat filter_low_pass_3db_fre= quency + 360 + +Show serial number: + +.. code-block:: bash + + root:/sys/kernel/debug/iio/iio:device0> cat serial_number + 0x04f9 + +Show product id: + +.. code-block:: bash + + root:/sys/kernel/debug/iio/iio:device0> cat product_id + 16505 + +Show flash count: + +.. code-block:: bash + + root:/sys/kernel/debug/iio/iio:device0> cat flash_count + 150 + +Show firmware revision: + +.. code-block:: bash + + root:/sys/kernel/debug/iio/iio:device0> cat firmware_revision + 1.6 + +Show firmware date: + +.. code-block:: bash + + root:/sys/kernel/debug/iio/iio:device0> cat firmware_date + 06-27-2019 + +3. Device buffers +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +This driver supports IIO buffers. + +All devices support retrieving the raw acceleration, gyroscope and tempera= ture +measurements using buffers. + +The following device families also support retrieving the delta velocity, = delta +angle and temperature measurements using buffers: + - ADIS16477 + - ADIS16500 + - ADIS16505 + - ADIS16507 + +However, when retrieving acceleration or gyroscope data using buffers, del= ta +readings will not be available and vice versa. + +Usage examples +-------------- + +Set device trigger in current_trigger, if not already set: + +.. code-block:: bash + + root:/sys/bus/iio/devices/iio:device0> cat trigger/current_trigger + + root:/sys/bus/iio/devices/iio:device0> echo adis16505-2-dev0 > tri= gger/current_trigger + root:/sys/bus/iio/devices/iio:device0> cat trigger/current_trigger + adis16505-2-dev0 + +Select channels for buffer read: + +.. code-block:: bash + + root:/sys/bus/iio/devices/iio:device0> echo 1 > scan_elements/in_d= eltavelocity_x_en + root:/sys/bus/iio/devices/iio:device0> echo 1 > scan_elements/in_d= eltavelocity_y_en + root:/sys/bus/iio/devices/iio:device0> echo 1 > scan_elements/in_d= eltavelocity_z_en + root:/sys/bus/iio/devices/iio:device0> echo 1 > scan_elements/in_t= emp0_en + +Set the number of samples to be stored in the buffer: + +.. code-block:: bash + + root:/sys/bus/iio/devices/iio:device0> echo 10 > buffer/length + +Enable buffer readings: + +.. code-block:: bash + + root:/sys/bus/iio/devices/iio:device0> echo 1 > buffer/enable + +Obtain buffered data: + +.. code-block:: bash + + root:/sys/bus/iio/devices/iio:device0> hexdump -C /dev/iio\:device0 + ... + 00001680 01 1f 00 00 ff ff fe ef 00 00 47 bf 00 03 35 55 |.....= .....G...5U| + 00001690 01 1f 00 00 ff ff ff d9 00 00 46 f1 00 03 35 35 |.....= .....F...55| + 000016a0 01 1f 00 00 ff ff fe fc 00 00 46 cb 00 03 35 7b |.....= .....F...5{| + 000016b0 01 1f 00 00 ff ff fe 41 00 00 47 0d 00 03 35 8b |.....= ..A..G...5.| + 000016c0 01 1f 00 00 ff ff fe 37 00 00 46 b4 00 03 35 90 |.....= ..7..F...5.| + 000016d0 01 1d 00 00 ff ff fe 5a 00 00 45 d7 00 03 36 08 |.....= ..Z..E...6.| + 000016e0 01 1b 00 00 ff ff fe fb 00 00 45 e7 00 03 36 60 |.....= .....E...6`| + 000016f0 01 1a 00 00 ff ff ff 17 00 00 46 bc 00 03 36 de |.....= .....F...6.| + 00001700 01 1a 00 00 ff ff fe 59 00 00 46 d7 00 03 37 b8 |.....= ..Y..F...7.| + 00001710 01 1a 00 00 ff ff fe ae 00 00 46 95 00 03 37 ba |.....= .....F...7.| + 00001720 01 1a 00 00 ff ff fe c5 00 00 46 63 00 03 37 9f |.....= .....Fc..7.| + 00001730 01 1a 00 00 ff ff fe 55 00 00 46 89 00 03 37 c1 |.....= ..U..F...7.| + 00001740 01 1a 00 00 ff ff fe 31 00 00 46 aa 00 03 37 f7 |.....= ..1..F...7.| + ... + +See Documentation/iio/iio_devbuf.rst for more information about how buffer= ed +data is structured. + +4. IIO Interfacing Tools +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +Linux Kernel Tools +------------------ + +Linux Kernel provides some user space tools that can be used to retrieve d= ata +from IIO sysfs: + +* lsiio: example application that provides a list of IIO devices and trigg= ers +* iio_event_monitor: example application that reads events from an IIO dev= ice + and prints them +* iio_generic_buffer: example application that reads data from buffer +* iio_utils: set of APIs, typically used to access sysfs files. + +LibIIO +------ + +LibIIO is a C/C++ library that provides generic access to IIO devices. The +library abstracts the low-level details of the hardware, and provides a si= mple +yet complete programming interface that can be used for advanced projects. + +For more information about LibIIO, please see: +https://github.com/analogdevicesinc/libiio diff --git a/Documentation/iio/index.rst b/Documentation/iio/index.rst index 206a0aff5ca1..30b09eefe75e 100644 --- a/Documentation/iio/index.rst +++ b/Documentation/iio/index.rst @@ -16,5 +16,6 @@ Industrial I/O Kernel Drivers .. toctree:: :maxdepth: 1 + adis16475 bno055 ep93xx_adc -- 2.34.1