On Wed, 22 Sep 2021 11:22:31 +0200 Miquel Raynal <miquel.raynal@xxxxxxxxxxx> wrote: > Hello IIO folks, > > I am currently writing a blog post trying to explain the situation that > I had with the max1027 driver [1] and possibly try to explain the logic > behind the changes that Jonathan/Nuno requested. As part of this work, I > tried to understand (and explain?) the meaning of the mode definitions > and if they were needed or not, but just looking at the code was not > enough for me to really understand. > > While digging into the IIO core, I realized that many definitions and > helpers had no comments explaining their use. I could not find any > documentation about the kernel API in general neither (while the > userspace side is well documented). > > I asked yesterday on #linux-iio but got no answers so I am also asking > here in case there are knowledgeable people willing to explain what > each of these definition actually mean and how they should be used: > https://elixir.bootlin.com/linux/latest/source/include/linux/iio/iio.h#L319 > > I am ready to send a patch upstream to add the necessary comment > so that these explanations do not stay on the mailing list only. I'll have a go, but definitely would like others to sanity check my explanations before we add them to the docs. Thanks for offering to do that btw and blog sounds like a great plan. This stuff looks to have bitrotted pretty badly. > /* Device operating modes */ > #define INDIO_DIRECT_MODE 0x01 This one simply means there is a sysfs poll mode. We don't actually check anywhere if it is set for a driver so it's possible there are drivers out there that should have this set and don't. That might change in future if we have a reason to start checking. It is used internally in the state management to indicate that we are not currently in one of the buffered modes. That's really just a place holder though for 'not one one of the other options' > #define INDIO_BUFFER_TRIGGERED 0x02 This is the most common mode when dealing with buffers. It indicates there is an explicit trigger being used and so we should attach a poll func when enabling the buffer. There is a subtlety on this one. If a device supports both this and BUFFER_SOFTWARE (which typically means there is a FIFO or similar and hence no explicit per scan trigger is exposed) then the mode setting will use this if a trigger has been set, but otherwise use the INDIO_BUFFER_HARDWARE or INDIO_BUFFER_SOFTWARE as appropriate (which normally means INDIO_BUFFER_SOFTWARE) > #define INDIO_BUFFER_SOFTWARE 0x04 So this case is (now) misleadingly named. It's typically used for FIFO cases. (Naming is because it used to reflect the presence of a KFIFO as opposed to directly accessing a hardware FIFO). Basically this means we get the data in a kfifo but not one scan at a time if watermarks set to greater than 1. > #define INDIO_BUFFER_HARDWARE 0x08 An odd corner case similar to INDIO_BUFFER_SOFTWARE but with more restrictions that exists for some unusual devices in which we are representing a flow of data we can't actually see from software. Used for some cases were a consumer driver is actually accessing the data via some back channel. I think we also use it for DMA buffers because they have very similar restrictions (no DEMUX in software). What doesn't help is the meaning of this changed over time. A long time back IIRC it reflected a mode in which userspace was reading directly from fifos on a device. These days we always route through a kfifo to give us more flexibility. > #define INDIO_EVENT_TRIGGERED 0x10 There are devices (well 1 anyway) that use triggers to drive capture of data that only results in events. In that particular case it's a threshold detector. It uses some of the same intrastructure as INDIO_BUFFER_TRIGGERED. > #define INDIO_HARDWARE_TRIGGERED 0x20 Ah, this one I'd forgotten about. Its stm32 only (so far) and that has a lot of internal data paths. So we can have triggers that result in data capture and IIRC can be routed to multiple components. So we wire it up in a similar fashion to a IIO trigger but none of the management of interrupts / pollfuncs etc is relevant as it's all hardware mediated and distributed. I'm not sure how easy it will be to distill that into brief documentation. If others want to contribute and point out what I got wrong above that would be great. This was very much an aspect that evolved rather than conformed to an original plan unfortunately and so is perhaps less than ideal, but hard to unwind. Jonathan > > Thanks, > Miquèl > > [1] https://lore.kernel.org/linux-iio/20210918180918.6908bbd9@jic23-huawei/
