Nishant Malpani

A layman, sort of

© 2022. Credits.

Sketching a Silhouette for ADXRS290’s Driver - Part 1 of 2

GSoC 2020 [ 0x02 ]

[  gsoc-2020  linux-kernel  iio  device-drivers  adxrs290-gyro  ] 27 Jun 2020

My take on kicking off writing the driver support for ADXRS290 gyroscope in the Linux kernel is to first sketch an outline of how the driver is supposed to look in the IIO subsystem, the silhouette, and once that is accepted, proceed with “coloring” the intricate details of the driver. Although I assume the reader to be familiar with the Linux Device Model (LDM), I nevertheless drop some resources for the same in this tutorial (?) for the reader to dive into. In this post, I also unravel the ingredients that make up the IIO subsystem in an attempt to reason why it is the suitable home for our gyroscope. Ending the first part, I hypothesize an outline of how the IIO driver support for ADXRS290 would look like.

The Linux Device Model (LDM) framework introduced by Patrick Mochel in v2.5 circa. 2001, borrows from the object-oriented concepts of self-similarity and encapsulation. It introduced abstract entities, or “objects”, such as device, driver, bus, class, etc. Indulging into the LDM being my initial plan was discarded because I felt I was fading away from the primary purpose of introducing laymen and potential future GSoCers to the IIO subsystem by enabling them to take a ride with me alongside my GSoC’20 project with the Linux Foundation; don’t get me wrong here, understanding the underlying LDM is absolutely pivotal for crafting device drivers for the Linux kernel, which is why I concluded to drop in some resources for the same, at the least. A separate blog-post was my Plan-B, to educate my readers (which is a pointer to NULL) about the LDM but I suppose I wouldn’t be doing justice to the complex yet magnificent anatomy of the LDM because, to be honest, I haven’t myself completely understood the LDM and its design choices (Yes, I’m very aware of where I stand on the Dunning-Kruger effect’s plot). Anyways, let me not keep you hanging here for long, you have a lot of reading to do (wink wink):

With this, one should get a fairly basic understanding of the underlying LDM - how it builds on the existing kobjects framework for the heirarchical structure and hence provide object management mechanisms, how sysfs exposes devices and their attributes to the userspace and how logical relations manifest in the sysfs through symlinks, how the bus matches a driver to “bind” to a device, why device-drivers are bus-specific (struct device_driver is typically embedded within higher-level, bus-specific structure - an instance of struct bus_type), how hotplugging is handled which leads into the kernel creating a kobject on-the-fly, etc.

Phew, into IIO we go now.

I had briefed about the IIO subsystem in my introductory GSoC blog. More on what IIO brings to the table can be acquired from drivers/staging/iio/Documentation/overview.txt and the elaborate talk by Jonathon Cameron (author and maintainer of IIO!) at the Embedded Linux Conference 2018. My attempt at what I gather about the functionality of IIO:

A visual brief about the functionalities of IIO is displayed below (taken from another great read: Daniel Baluta’s Slides on IIO)

IIO arch overview
IIO Architecture Overview

Of course there’s lot more to understand about IIO and its “features” - what all channels to expose, integrating multiple consumers for a trigger for concurrent data sampling, intuitively understand events and when to use one, etc. - it will all be tackled in an incremental way over a few blog-posts.

With this succinct overview, I hope you’ve convinced yourself on why IIO should shelter ADXRS290 gyroscope’s driver. If not, it is left as an exercise to the reade…naah, I can shed some empathy for you’ve come so long :P

If you’ve skimmed through the datasheet of ADXRS290, can you imagine how IIO could assist us with the range of functionalities it provides? I can think of how we can setup up IIO channels for reading angular velocity data (one for each axis - roll & pitch) and for reading temperature data. To configure the programmable band-pass filter inherent to the ADXRS290, we can set up IIO device attributes - one for the low-pass filter’s 3db frequency and one for the high-pass filter’s 3db frequency (we will have to check the ABI, sys-bus-iio, to equip existing attributes and their expected physical units and not invent our own unless its absolutely needed). Going ahead, we can also provide buffer support and possibly a triggered buffer support where the trigger is generated at the SYNC/ASEL pin (if the SYNC bits are set to 0b01 in the DATA_READY register of ADXRS290). The trigger once consumed can push angular velocity data of both the axes into kfifo (software) buffers (as there are no hardware buffers present in ADXRS290). All this speculation might be incorrect once we deeply understand IIO device-drivers and the development practises employed by the IIO community; all I wanted to communicate is how I’d originally go about utilising the elements of IIO to provide support for a sensor I’ve been handed over for the first time, which indeed is the case! :D

Continued…