Linux设备驱动之IIO子系统——IIO框架及IIO数据结构

由于需要对ADC进行驱动设计，因此学习了一下Linux驱动的IIO子系统。本文翻译自《Linux Device Drivers Development 》–John Madieu，本人水平有限，若有错误请大家指出。

IIO Framework

工业I / O（IIO）是专用于模数转换器（ADC）和数模转换器（DAC）的内核子系统。随着越来越多的具有不同代码实现的传感器（具有模拟到数字或数字到模拟，功能的测量设备）分散在内核源上，收集它们变得必要。这就是IIO框架以通用的方式所做的事情。自2009年以来，Jonathan Cameron和Linux-IIO社区一直在开发它。
　　
　　加速度计，陀螺仪，电流/电压测量芯片，光传感器，压力传感器等都属于IIO系列器件。

IIO模型基于设备和通道架构：

设备代表芯片本身。它是层次结构的顶级。

通道代表设备的单个采集线。设备可以具有一个或多个通道。例如，加速度计是具有三个通道的装置，每个通道对应一个轴（X，Y和Z）。

IIO芯片是物理和硬件传感器/转换器。它作为字符设备（当支持触发缓冲时）暴露给用户空间，以及包含一组文件的sysfs目录条目，其中一些文件代表通道。单个通道用单个sysfs文件条目表示。

下面是从用户空间与IIO驱动程序交互的两种方式：

/sys/bus/iio/iio:deviceX/:表示传感器及其通道
/dev/iio:deviceX: 表示导出设备事件和数据缓冲区的字符设备

IIO框架架构和布局

上图显示了如何在内核和用户空间之间组织IIO框架。驱动程序使用IIO核心公开的一组工具和API来管理硬件并向IIO核心报告处理。然后，IIO子系统通过sysfs接口和字符设备将整个底层机制抽象到用户空间，用户可以在其上执行系统调用。

IIO API分布在多个头文件中，如下所示：

#include <linux/iio/iio.h>    /* mandatory */
#include <linux/iio/sysfs.h>  /* mandatory since sysfs is used */
#include <linux/iio/events.h> /* For advanced users, to manage iio events */
#include <linux/iio/buffer.h> /* mandatory to use triggered buffers */
#include <linux/iio/trigger.h>/* Only if you implement trigger in your driver (rarely used)*/

在以下文章中，我们将描述和处理IIO框架的每个概念，例如

遍历其数据结构（设备，通道等）
触发缓冲支持和连续捕获，以及其sysfs接口
探索现有的IIO触发器
以单次模式或连续模式捕获数据
列出可用于帮助开发人员测试其设备的可用工具

（一）：IIO data structures：IIO数据结构

IIO设备在内核中表示为struct iio_dev结构体的一个实例，并由struct iio_info结构体描述。所有重要的IIO结构都在include/linux/iio/iio.h中定义。

iio_dev structure（iio_dev结构）

该结构代表IIO设备，描述设备和驱动程序。它告诉我们：

设备上有多少个通道？

设备可以在哪些模式下运行：单次，触发缓冲？
这个驱动程序可以使用哪些hooks钩子？

代码

struct iio_dev {[...]int modes;int currentmode;struct device dev;struct iio_buffer *buffer;int scan_bytes;const unsigned long *available_scan_masks;const unsigned long *active_scan_mask;bool scan_timestamp;struct iio_trigger *trig;struct iio_poll_func *pollfunc;struct iio_chan_spec const *channels;int num_channels;const char *name;const struct iio_info *info;const struct iio_buffer_setup_ops *setup_ops;struct cdev chrdev;};

完整的结构在IIO头文件中定义。我们将不感兴趣的字段在此处删除。

modes: 这表示设备支持的不同模式。支持的模式有：
INDIO_DIRECT_MODE表示设备提供的sysfs接口。
INDIO_BUFFER_TRIGGERED表示设备支持硬件触发器。使用iio_triggered_buffer_setup（）函数设置触发缓冲区时，此模式会自动添加到设备中。
INDIO_BUFFER_HARDWARE表示设备具有硬件缓冲区。
INDIO_ALL_BUFFER_MODES是上述两者的联合。

currentmode: 这表示设备实际使用的模式

dev: 这表示IIO设备所依赖的struct设备（根据Linux设备型号）。

buffer: 这是您的数据缓冲区，在使用触发缓冲区模式时会推送到用户空间。
使用iio_triggered_buffer_setup函数启用触发缓冲区支持时，它会自动分配并与您的设备关联。

scan_bytes: 这是捕获并馈送到缓冲区的字节数。当从用户空间使用触发缓冲区时，缓冲区应至少为indio->
scan_bytes字节大。

available_scan_masks: 这是允许的位掩码的可选数组。

使用触发缓冲器时，可以启用通道捕获并将其馈入IIO缓冲区。如果您不想允许某些通道启用，则应仅使用允许的通道填充此数组。以下是为加速度计（带有X，Y和Z通道）提供扫描掩码的示例：

/** Bitmasks 0x7 (0b111) and 0 (0b000) are allowed.* It means one can enable none or all of them.* one can't for example enable only channel X and Y*/static const unsigned long my_scan_masks[] = {0x7, 0};
indio_dev->available_scan_masks = my_scan_masks;

active_scan_mask: 这是启用通道的位掩码。只有来自这些通道的数据能被推入缓冲区。例如，对于8通道ADC转换器，如果只启用第一个（0），第三个（2）和最后一个（7）通道，则位掩码将为0b10000101（0x85）。active_scan_mask将设置为0x85。然后，驱动程序可以使用for_each_set_bit宏遍历每个设置位，根据通道获取数据，并填充缓冲区。
scan_timestamp: 这告诉我们是否将捕获时间戳推入缓冲区。如果为true，则将时间戳作为缓冲区的最后一个元素。时间戳大8字节（64位）。
trig: 这是当前设备触发器（支持缓冲模式时）。
pollfunc:这是在接收的触发器上运行的函数。
channels: 这表示通道规范结构，用于描述设备具有的每个通道。
num_channels: 这表示通道中指定的通道数。
name: 这表示设备名称。
info: 来自驱动程序的回调和持续信息。
setup_ops: 启用/禁用缓冲区之前和之后调用的回调函数集。这个结构在include / linux / iio / iio.h中定义，

如下所示：

struct iio_buffer_setup_ops {int (* preenable) (struct iio_dev *);int (* postenable) (struct iio_dev *);int (* predisable) (struct iio_dev *);int (* postdisable) (struct iio_dev *);bool (* validate_scan_mask) (struct iio_dev *indio_dev,const unsigned long *scan_mask);
};

setup_ops: 如果未指定，则IIO内核使用drivers / iio / buffer /industrialio-triggered-buffer.c中定义的缺省iio_triggered_buffer_setup_ops。
chrdev: 这是由IIO核心创建的关联字符设备。

用于为IIO设备分配内存的函数是iio_device_alloc（）：

struct iio_dev * iio_device_alloc(int sizeof_priv)
///struct iio_dev *devm_iio_device_alloc(struct device *dev, int sizeof_priv)
/* Resource-managed iio_device_alloc()*/
/*Managed iio_device_alloc. iio_dev allocated with this function is automatically freed on driver detach.
If an iio_dev allocated with this function needs to be freed separately, devm_iio_device_free() must be used. */

dev是为其分配iio_dev的设备，sizeof_priv是用于为任何私有结构分配的内存空间。这样，传递每个设备（私有）数据结构非常简单。如果分配失败，该函数返回NULL：

struct iio_dev *indio_dev;
struct my_private_data *data;
indio_dev = iio_device_alloc(sizeof(*data));
if (!indio_dev)return -ENOMEM;
/*data is given the address of reserved momory for private data */
data = iio_priv(indio_dev);

在分配IIO设备存储器之后，下一步是填充不同的字段。完成后，必须使用iio_device_register函数向IIO子系统注册设备：

int iio_device_register(struct iio_dev *indio_dev)//devm_iio_device_register(dev, indio_dev)
/* Resource-managed iio_device_register() */

在执行此功能后，设备将准备好接受来自用户空间的请求。反向操作（通常在释放函数中完成）是iio_device_unregister（）：

void iio_device_unregister(struct iio_dev *indio_dev)
// void devm_iio_device_unregister(struct device * dev, struct iio_dev * indio_dev)一旦取消注册，iio_device_alloc分配的内存可以用iio_device_free释放：void iio_device_free(struct iio_dev *iio_dev)
// void devm_iio_device_free(struct device * dev, struct iio_dev * iio_dev)

给定IIO设备作为参数，可以通过以下方式检索私有数据：

struct my_private_data *the_data = iio_priv(indio_dev);

iio_info structure：iio_info结构体

struct iio_info结构用于声明IIO内核使用的钩子，以读取/写入通道/属性值：

struct iio_info {struct module *driver_module;const struct attribute_group *attrs;int (*read_raw)(struct iio_dev *indio_dev,struct iio_chan_spec const *chan,int *val, int *val2, long mask);int (*write_raw)(struct iio_dev *indio_dev,struct iio_chan_spec const *chan,int val, int val2, long mask);[...]};

driver_module: 这是用于确保chrdev正确拥有的模块结构，通常设置为THIS_MODULE。
attrs: 这表示设备属性。
read_raw: 这是用户读取设备sysfs文件属性时的回调运行。 mask参数是一个位掩码，它允许我们知道请求了哪种类型的值。
channel参数让我们知道相关的通道。它可以是采样频率，用于将原始值转换为可用值的比例，或原始值本身。
write_raw: 这是用于将值写入设备的回调。例如，可以使用它来设置采样频率。

以下代码显示了如何设置struct iio_info结构：

static const struct iio_info iio_dummy_info = {.driver_module = THIS_MODULE,.read_raw = &iio_dummy_read_raw,.write_raw = &iio_dummy_write_raw,
[...]/** Provide device type specific interface functions and* constant data. 提供设备类型特定的接口功能和常量数据。*/
indio_dev->info = &iio_dummy_info;

IIO channels：IIO通道

通道代表单条采集线。例如加速度计具有3个通道（X，Y，Z），因为每个轴代表单个采集线。 struct iio_chan_spec是表示和描述内核中单个通道的结构：

 struct iio_chan_spec {enum iio_chan_type type;int channel;int channel2;unsigned long address;int scan_index;struct {charsign;u8 realbits;u8 storagebits;u8 shift;u8 repeat;enum iio_endian endianness;} scan_type;long info_mask_separate;long info_mask_shared_by_type;long info_mask_shared_by_dir;long info_mask_shared_by_all;const struct iio_event_spec *event_spec;unsigned int num_event_specs;const struct iio_chan_spec_ext_info *ext_info;const char *extend_name;const char *datasheet_name;unsigned modified:1;unsigned indexed:1;unsigned output:1;unsigned differential:1;};

各个参数意义：

type: 这指定了通道的测量类型。在电压测量的情况下，它应该是IIO_VOLTAGE。对于光传感器，它是IIO_LIGHT。对于加速度计，使用IIO_ACCEL。所有可用类型都在include / uapi / linux / iio /types.h中定义，如enum iio_chan_type。要为给定转换器编写驱动程序，请查看该文件以查看每个通道所属的类型。
channel: 这指定.indexed设置为1时的通道索引。
channel2: 这指定.modified设置为1时的通道修饰。
modified: 这指定是否将修饰符应用于此通道属性名称。在这种情况下，修饰符设置在.channel2中。（例如，IIO_MOD_X，IIO_MOD_Y，IIO_MOD_Z是关于xyz轴的轴向传感器的修改器）。可用修饰符列表在内核IIO头中定义为枚举iio_modifier。修饰符只会破坏sysfs中的通道属性名称，而不是值。
indexed: 这指定通道属性名称是否具有索引。如果是，则在.channel字段中指定索引。
scan_index and scan_type: 当使用缓冲区触发器时，这些字段用于标识缓冲区中的元素。
scan_index设置缓冲区内捕获的通道的位置。具有较低scan_index的通道将放置在具有较高索引的通道之前。将.scan_index设置为-1将阻止通道进行缓冲捕获（scan_elements目录中没有条目）。

暴露给用户空间的通道sysfs属性以位掩码的形式指定。根据共享信息，可以将属性设置为以下掩码之一：

info_mask_separate 将属性标记为特定于此通
info_mask_shared_by_type 将该属性标记为由相同类型的所有通道共享。导出的信息由相同类型的所有通道共享。
info_mask_shared_by_dir 将属性标记为由同一方向的所有通道共享。导出的信息由同一方向的所有通道共享。
info_mask_shared_by_all 将属性标记为所有通道共享，无论其类型或方向如何。导出的信息由所有渠道共享。

用于枚举这些属性的位掩码都在include / linux / iio / iio.h中定义：

enum iio_chan_info_enum {IIO_CHAN_INFO_RAW = 0,IIO_CHAN_INFO_PROCESSED,IIO_CHAN_INFO_SCALE,IIO_CHAN_INFO_OFFSET,IIO_CHAN_INFO_CALIBSCALE,[...]IIO_CHAN_INFO_SAMP_FREQ,IIO_CHAN_INFO_FREQUENCY,IIO_CHAN_INFO_PHASE,IIO_CHAN_INFO_HARDWAREGAIN,IIO_CHAN_INFO_HYSTERESIS,[...]
};

字节序字段应为以下之一：

enum iio_endian {IIO_CPU,IIO_BE,IIO_LE,};

Channel attribute naming conventions：通道属性命名约定

属性的名称由IIO核心自动生成，具有以下模式：{direction} _ {type} _ {index} _ {modifier} _ {info_mask}：

direction方向对应于属性方向，

根据drivers / iio / industrialio-core.c中的struct iio_direction结构：

static const char * const iio_direction[] = {[0] = "in",[1] = "out",
};

type对应于通道类型

根据char数组const iio_chan_type_name_spec：

static const char * const iio_chan_type_name_spec[] = {[IIO_VOLTAGE] = "voltage",[IIO_CURRENT] = "current",[IIO_POWER] = "power",[IIO_ACCEL] = "accel",[...][IIO_UVINDEX] = "uvindex",[IIO_ELECTRICALCONDUCTIVITY] = "electricalconductivity",[IIO_COUNT] = "count",[IIO_INDEX] = "index",[IIO_GRAVITY]  = "gravity",
};

index 索引模式取决于是否设置了通道.indexed字段。如果设置，索引将从.channel字段中获取，以替换{index}模式。
modifier 模式取决于通道所设置的.modified字段。

如果设置，修饰符将从.channel2字段中获取，{modifier}模式将根据char数组struct iio_modifier_names结构替换：

static const char * const iio_modifier_names[] = {[IIO_MOD_X] = "x",[IIO_MOD_Y] = "y",[IIO_MOD_Z] = "z",[IIO_MOD_X_AND_Y] = "x&y",[IIO_MOD_X_AND_Z] = "x&z",[IIO_MOD_Y_AND_Z] = "y&z",[...][IIO_MOD_CO2] = "co2",[IIO_MOD_VOC] = "voc",
};

info_mask取决于char数组iio_chan_info_postfix中的通道信息掩码

，私有或共享索引值：

/* relies on pairs of these shared then separate依赖于这些共享的对,然后分离*/
static const char * const iio_chan_info_postfix[] = {[IIO_CHAN_INFO_RAW] = "raw",[IIO_CHAN_INFO_PROCESSED] = "input",[IIO_CHAN_INFO_SCALE] = "scale",[IIO_CHAN_INFO_CALIBBIAS] = "calibbias",[...][IIO_CHAN_INFO_SAMP_FREQ] = "sampling_frequency",[IIO_CHAN_INFO_FREQUENCY] = "frequency",[...]
};

Distinguishing channels通道区分

当每种通道类型有多个数据通道时，您可能会遇到麻烦。困境将是：如何识别它们。有两种解决方案：索引和修饰符。

使用索引：给定具有一个通道线的ADC器件，不需要索引。通道定义如下：

static const struct iio_chan_spec adc_channels[] = {{.type = IIO_VOLTAGE,.info_mask_separate = BIT(IIO_CHAN_INFO_RAW),},
}

由前面描述的通道产生的属性名称将是in_voltage_raw。

/sys/bus/iio/iio:deviceX/in_voltage_raw
现在让我们看一下有4个甚至8个通道的转换器。我们如何识别它们？解决方案是使用索引。将.indexed字段设置为1将使用.channel值替换{index}模式来替换通道属性名称：

  static const struct iio_chan_spec adc_channels[] = {{.type = IIO_VOLTAGE,.indexed = 1,.channel = 0,.info_mask_separate = BIT(IIO_CHAN_INFO_RAW),},{.type = IIO_VOLTAGE,.indexed = 1,.channel = 1,.info_mask_separate = BIT(IIO_CHAN_INFO_RAW),},{.type = IIO_VOLTAGE,.indexed = 1,.channel = 2,.info_mask_separate = BIT(IIO_CHAN_INFO_RAW),},{.type = IIO_VOLTAGE,.indexed = 1,.channel = 3,.info_mask_separate = BIT(IIO_CHAN_INFO_RAW),},
}

生成的通道属性为：

 /sys/bus/iio/iio:deviceX/in_voltage0_raw
/sys/bus/iio/iio:deviceX/in_voltage1_raw
/sys/bus/iio/iio:deviceX/in_voltage2_raw
/sys/bus/iio/iio:deviceX/in_voltage3_raw

使用修饰符：给定一个带有两个通道的光传感器 - 一个用于红外光，一个用于红外和可见光，没有索引或修改器，属性名称将为in_intensity_raw。在这里使用索引可能容易出错，因为使用in_intensity0_ir_raw和in_intensity1_ir_raw是没有意义的。使用修饰符将有助于提供有意义的属性名称。通道的定义如下：

static const struct iio_chan_spec mylight_channels[] = {{.type = IIO_INTENSITY,.modified = 1,.channel2 = IIO_MOD_LIGHT_IR,.info_mask_separate = BIT(IIO_CHAN_INFO_RAW),.info_mask_shared = BIT(IIO_CHAN_INFO_SAMP_FREQ),},{.type = IIO_INTENSITY,.modified = 1,.channel2 = IIO_MOD_LIGHT_BOTH,.info_mask_separate = BIT(IIO_CHAN_INFO_RAW),.info_mask_shared = BIT(IIO_CHAN_INFO_SAMP_FREQ),},{.type = IIO_LIGHT,.info_mask_separate = BIT(IIO_CHAN_INFO_PROCESSED),.info_mask_shared =BIT(IIO_CHAN_INFO_SAMP_FREQ),},}

属性结果：

/sys/bus/iio/iio:deviceX/in_intensity_ir_raw 用于测量IR强度的通道
/sys/bus/iio/iio:deviceX/in_intensity_both_raw用于测量红外和可见光的通道
/sys/bus/iio/iio:deviceX/in_illuminance_input用于处理后的数据
/sys/bus/iio/iio:deviceX/sampling_frequency 用于采样频率，由所有人共享

这也适用于加速度计，我们将在案例研究中进一步了解。现在，让我们总结一下我们到目前为止在虚拟IIO驱动程序中讨论过的内容。

Putting it all together总结

让我们总结一下迄今为止我们在一个简单的虚拟驱动器中看到的内容，它将暴露出四个电压通道。我们将忽略read（）或write（）函数：

#include <linux/init.h>
#include <linux/module.h>
#include <linux/kernel.h>
#include <linux/platform_device.h>
#include <linux/interrupt.h>
#include <linux/of.h>
#include <linux/iio/iio.h>
#include <linux/iio/sysfs.h>
#include <linux/iio/events.h>
#include <linux/iio/buffer.h>#define FAKE_VOLTAGE_CHANNEL(num)                  \{                                               \.type = IIO_VOLTAGE,                      \.indexed = 1,                             \.channel = (num),                         \.address = (num),                         \.info_mask_separate = BIT(IIO_CHAN_INFO_RAW),   \.info_mask_shared_by_type =BIT(IIO_CHAN_INFO_SCALE) \}struct my_private_data {int foo;int bar;struct mutex lock;
};static int fake_read_raw(struct iio_dev *indio_dev,struct iio_chan_spec const *channel, int *val,int *val2, long mask)
{return 0;
}static int fake_write_raw(struct iio_dev *indio_dev,struct iio_chan_spec const *chan,int val, int val2, long mask)
{return 0;
}static const struct iio_chan_spec fake_channels[] = {FAKE_VOLTAGE_CHANNEL(0),FAKE_VOLTAGE_CHANNEL(1), FAKE_VOLTAGE_CHANNEL(2),FAKE_VOLTAGE_CHANNEL(3),};static const struct of_device_id iio_dummy_ids[] = {{ .compatible = "packt,iio-dummy-random", },{ /* sentinel */ }
};static const struct iio_info fake_iio_info = {.read_raw = fake_read_raw,.write_raw        = fake_write_raw,.driver_module = THIS_MODULE,
};static int my_pdrv_probe (struct platform_device *pdev)
{struct iio_dev *indio_dev;struct my_private_data *data;indio_dev = devm_iio_device_alloc(&pdev->dev, sizeof(*data));if (!indio_dev) {dev_err(&pdev->dev, "iio allocation failed!\n");return -ENOMEM;}data = iio_priv(indio_dev);mutex_init(&data->lock);indio_dev->dev.parent = &pdev->dev;indio_dev->info = &fake_iio_info;indio_dev->name = KBUILD_MODNAME;indio_dev->modes = INDIO_DIRECT_MODE;indio_dev->channels = fake_channels;indio_dev->num_channels = ARRAY_SIZE(fake_channels);indio_dev->available_scan_masks = 0xF;iio_device_register(indio_dev);platform_set_drvdata(pdev, indio_dev);return 0;
}
static void my_pdrv_remove(struct platform_device *pdev)
{struct iio_dev *indio_dev = platform_get_drvdata(pdev);iio_device_unregister(indio_dev);
}
static struct platform_driver mypdrv = {.probe      = my_pdrv_probe,.remove     = my_pdrv_remove,.driver     = {.name     = "iio-dummy-random",.of_match_table = of_match_ptr(iio_dummy_ids),  .owner    = THIS_MODULE,},
};
module_platform_driver(mypdrv);
MODULE_AUTHOR("John Madieu <john.madieu@gmail.com>");
MODULE_LICENSE("GPL");

加载上述模块后, 我们将有以下输出, 显示我们的设备确实对应于我们已注册的平台设备:

 ~# ls -l /sys/bus/iio/devices/
lrwxrwxrwx 1 root root 0 Jul 31 20:26 iio:device0 -> ../../../devices/platform/iio-dummy-random.0/iio:device0
lrwxrwxrwx 1 root root 0 Jul 31 20:23 iio_sysfs_trigger -> ../../../devices/iio_sysfs_trigger

下面的列表显示了此设备的通道及其名称, 这些通道与我们在驱动程序中描述的内容完全对应:

 ~# ls /sys/bus/iio/devices/iio\:device0/
dev in_voltage2_raw name uevent
in_voltage0_raw in_voltage3_raw power
in_voltage1_raw in_voltage_scale subsystem
~# cat /sys/bus/iio/devices/iio:device0/name
iio_dummy_random