1<?xml version="1.0" encoding="UTF-8"?> 2<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" 3 "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []> 4 5<book id="iioid"> 6 <bookinfo> 7 <title>Industrial I/O driver developer's guide </title> 8 9 <authorgroup> 10 <author> 11 <firstname>Daniel</firstname> 12 <surname>Baluta</surname> 13 <affiliation> 14 <address> 15 <email>daniel.baluta@intel.com</email> 16 </address> 17 </affiliation> 18 </author> 19 </authorgroup> 20 21 <copyright> 22 <year>2015</year> 23 <holder>Intel Corporation</holder> 24 </copyright> 25 26 <legalnotice> 27 <para> 28 This documentation is free software; you can redistribute 29 it and/or modify it under the terms of the GNU General Public 30 License version 2. 31 </para> 32 </legalnotice> 33 </bookinfo> 34 35 <toc></toc> 36 37 <chapter id="intro"> 38 <title>Introduction</title> 39 <para> 40 The main purpose of the Industrial I/O subsystem (IIO) is to provide 41 support for devices that in some sense perform either analog-to-digital 42 conversion (ADC) or digital-to-analog conversion (DAC) or both. The aim 43 is to fill the gap between the somewhat similar hwmon and input 44 subsystems. 45 Hwmon is directed at low sample rate sensors used to monitor and 46 control the system itself, like fan speed control or temperature 47 measurement. Input is, as its name suggests, focused on human interaction 48 input devices (keyboard, mouse, touchscreen). In some cases there is 49 considerable overlap between these and IIO. 50 </para> 51 <para> 52 Devices that fall into this category include: 53 <itemizedlist> 54 <listitem> 55 analog to digital converters (ADCs) 56 </listitem> 57 <listitem> 58 accelerometers 59 </listitem> 60 <listitem> 61 capacitance to digital converters (CDCs) 62 </listitem> 63 <listitem> 64 digital to analog converters (DACs) 65 </listitem> 66 <listitem> 67 gyroscopes 68 </listitem> 69 <listitem> 70 inertial measurement units (IMUs) 71 </listitem> 72 <listitem> 73 color and light sensors 74 </listitem> 75 <listitem> 76 magnetometers 77 </listitem> 78 <listitem> 79 pressure sensors 80 </listitem> 81 <listitem> 82 proximity sensors 83 </listitem> 84 <listitem> 85 temperature sensors 86 </listitem> 87 </itemizedlist> 88 Usually these sensors are connected via SPI or I2C. A common use case of the 89 sensors devices is to have combined functionality (e.g. light plus proximity 90 sensor). 91 </para> 92 </chapter> 93 <chapter id='iiosubsys'> 94 <title>Industrial I/O core</title> 95 <para> 96 The Industrial I/O core offers: 97 <itemizedlist> 98 <listitem> 99 a unified framework for writing drivers for many different types of 100 embedded sensors. 101 </listitem> 102 <listitem> 103 a standard interface to user space applications manipulating sensors. 104 </listitem> 105 </itemizedlist> 106 The implementation can be found under <filename> 107 drivers/iio/industrialio-*</filename> 108 </para> 109 <sect1 id="iiodevice"> 110 <title> Industrial I/O devices </title> 111 112<refentry id="API-struct-iio-dev"> 113<refentryinfo> 114 <title>LINUX</title> 115 <productname>Kernel Hackers Manual</productname> 116 <date>July 2017</date> 117</refentryinfo> 118<refmeta> 119 <refentrytitle><phrase>struct iio_dev</phrase></refentrytitle> 120 <manvolnum>9</manvolnum> 121 <refmiscinfo class="version">4.4.14</refmiscinfo> 122</refmeta> 123<refnamediv> 124 <refname>struct iio_dev</refname> 125 <refpurpose> 126 industrial I/O device 127 </refpurpose> 128</refnamediv> 129<refsynopsisdiv> 130 <title>Synopsis</title> 131 <programlisting> 132struct iio_dev { 133 int id; 134 int modes; 135 int currentmode; 136 struct device dev; 137 struct iio_event_interface * event_interface; 138 struct iio_buffer * buffer; 139 struct list_head buffer_list; 140 int scan_bytes; 141 struct mutex mlock; 142 const unsigned long * available_scan_masks; 143 unsigned masklength; 144 const unsigned long * active_scan_mask; 145 bool scan_timestamp; 146 unsigned scan_index_timestamp; 147 struct iio_trigger * trig; 148 struct iio_poll_func * pollfunc; 149 struct iio_poll_func * pollfunc_event; 150 struct iio_chan_spec const * channels; 151 int num_channels; 152 struct list_head channel_attr_list; 153 struct attribute_group chan_attr_group; 154 const char * name; 155 const struct iio_info * info; 156 struct mutex info_exist_lock; 157 const struct iio_buffer_setup_ops * setup_ops; 158 struct cdev chrdev; 159#define IIO_MAX_GROUPS 6 160 const struct attribute_group * groups[IIO_MAX_GROUPS + 1]; 161 int groupcounter; 162 unsigned long flags; 163#if defined(CONFIG_DEBUG_FS) 164 struct dentry * debugfs_dentry; 165 unsigned cached_reg_addr; 166#endif 167}; </programlisting> 168</refsynopsisdiv> 169 <refsect1> 170 <title>Members</title> 171 <variablelist> 172 <varlistentry> <term>id</term> 173 <listitem><para> 174[INTERN] used to identify device internally 175 </para></listitem> 176 </varlistentry> 177 <varlistentry> <term>modes</term> 178 <listitem><para> 179[DRIVER] operating modes supported by device 180 </para></listitem> 181 </varlistentry> 182 <varlistentry> <term>currentmode</term> 183 <listitem><para> 184[DRIVER] current operating mode 185 </para></listitem> 186 </varlistentry> 187 <varlistentry> <term>dev</term> 188 <listitem><para> 189[DRIVER] device structure, should be assigned a parent 190and owner 191 </para></listitem> 192 </varlistentry> 193 <varlistentry> <term>event_interface</term> 194 <listitem><para> 195[INTERN] event chrdevs associated with interrupt lines 196 </para></listitem> 197 </varlistentry> 198 <varlistentry> <term>buffer</term> 199 <listitem><para> 200[DRIVER] any buffer present 201 </para></listitem> 202 </varlistentry> 203 <varlistentry> <term>buffer_list</term> 204 <listitem><para> 205[INTERN] list of all buffers currently attached 206 </para></listitem> 207 </varlistentry> 208 <varlistentry> <term>scan_bytes</term> 209 <listitem><para> 210[INTERN] num bytes captured to be fed to buffer demux 211 </para></listitem> 212 </varlistentry> 213 <varlistentry> <term>mlock</term> 214 <listitem><para> 215[INTERN] lock used to prevent simultaneous device state 216changes 217 </para></listitem> 218 </varlistentry> 219 <varlistentry> <term>available_scan_masks</term> 220 <listitem><para> 221[DRIVER] optional array of allowed bitmasks 222 </para></listitem> 223 </varlistentry> 224 <varlistentry> <term>masklength</term> 225 <listitem><para> 226[INTERN] the length of the mask established from 227channels 228 </para></listitem> 229 </varlistentry> 230 <varlistentry> <term>active_scan_mask</term> 231 <listitem><para> 232[INTERN] union of all scan masks requested by buffers 233 </para></listitem> 234 </varlistentry> 235 <varlistentry> <term>scan_timestamp</term> 236 <listitem><para> 237[INTERN] set if any buffers have requested timestamp 238 </para></listitem> 239 </varlistentry> 240 <varlistentry> <term>scan_index_timestamp</term> 241 <listitem><para> 242[INTERN] cache of the index to the timestamp 243 </para></listitem> 244 </varlistentry> 245 <varlistentry> <term>trig</term> 246 <listitem><para> 247[INTERN] current device trigger (buffer modes) 248 </para></listitem> 249 </varlistentry> 250 <varlistentry> <term>pollfunc</term> 251 <listitem><para> 252[DRIVER] function run on trigger being received 253 </para></listitem> 254 </varlistentry> 255 <varlistentry> <term>pollfunc_event</term> 256 <listitem><para> 257[DRIVER] function run on events trigger being received 258 </para></listitem> 259 </varlistentry> 260 <varlistentry> <term>channels</term> 261 <listitem><para> 262[DRIVER] channel specification structure table 263 </para></listitem> 264 </varlistentry> 265 <varlistentry> <term>num_channels</term> 266 <listitem><para> 267[DRIVER] number of channels specified in <parameter>channels</parameter>. 268 </para></listitem> 269 </varlistentry> 270 <varlistentry> <term>channel_attr_list</term> 271 <listitem><para> 272[INTERN] keep track of automatically created channel 273attributes 274 </para></listitem> 275 </varlistentry> 276 <varlistentry> <term>chan_attr_group</term> 277 <listitem><para> 278[INTERN] group for all attrs in base directory 279 </para></listitem> 280 </varlistentry> 281 <varlistentry> <term>name</term> 282 <listitem><para> 283[DRIVER] name of the device. 284 </para></listitem> 285 </varlistentry> 286 <varlistentry> <term>info</term> 287 <listitem><para> 288[DRIVER] callbacks and constant info from driver 289 </para></listitem> 290 </varlistentry> 291 <varlistentry> <term>info_exist_lock</term> 292 <listitem><para> 293[INTERN] lock to prevent use during removal 294 </para></listitem> 295 </varlistentry> 296 <varlistentry> <term>setup_ops</term> 297 <listitem><para> 298[DRIVER] callbacks to call before and after buffer 299enable/disable 300 </para></listitem> 301 </varlistentry> 302 <varlistentry> <term>chrdev</term> 303 <listitem><para> 304[INTERN] associated character device 305 </para></listitem> 306 </varlistentry> 307 <varlistentry> <term>groups[IIO_MAX_GROUPS + 1]</term> 308 <listitem><para> 309[INTERN] attribute groups 310 </para></listitem> 311 </varlistentry> 312 <varlistentry> <term>groupcounter</term> 313 <listitem><para> 314[INTERN] index of next attribute group 315 </para></listitem> 316 </varlistentry> 317 <varlistentry> <term>flags</term> 318 <listitem><para> 319[INTERN] file ops related flags including busy flag. 320 </para></listitem> 321 </varlistentry> 322 <varlistentry> <term>debugfs_dentry</term> 323 <listitem><para> 324[INTERN] device specific debugfs dentry. 325 </para></listitem> 326 </varlistentry> 327 <varlistentry> <term>cached_reg_addr</term> 328 <listitem><para> 329[INTERN] cached register address for debugfs reads. 330 </para></listitem> 331 </varlistentry> 332 </variablelist> 333 </refsect1> 334</refentry> 335 336<refentry id="API-iio-device-alloc"> 337<refentryinfo> 338 <title>LINUX</title> 339 <productname>Kernel Hackers Manual</productname> 340 <date>July 2017</date> 341</refentryinfo> 342<refmeta> 343 <refentrytitle><phrase>iio_device_alloc</phrase></refentrytitle> 344 <manvolnum>9</manvolnum> 345 <refmiscinfo class="version">4.4.14</refmiscinfo> 346</refmeta> 347<refnamediv> 348 <refname>iio_device_alloc</refname> 349 <refpurpose> 350 allocate an iio_dev from a driver 351 </refpurpose> 352</refnamediv> 353<refsynopsisdiv> 354 <title>Synopsis</title> 355 <funcsynopsis><funcprototype> 356 <funcdef>struct iio_dev * <function>iio_device_alloc </function></funcdef> 357 <paramdef>int <parameter>sizeof_priv</parameter></paramdef> 358 </funcprototype></funcsynopsis> 359</refsynopsisdiv> 360<refsect1> 361 <title>Arguments</title> 362 <variablelist> 363 <varlistentry> 364 <term><parameter>sizeof_priv</parameter></term> 365 <listitem> 366 <para> 367 Space to allocate for private structure. 368 </para> 369 </listitem> 370 </varlistentry> 371 </variablelist> 372</refsect1> 373</refentry> 374 375<refentry id="API-iio-device-free"> 376<refentryinfo> 377 <title>LINUX</title> 378 <productname>Kernel Hackers Manual</productname> 379 <date>July 2017</date> 380</refentryinfo> 381<refmeta> 382 <refentrytitle><phrase>iio_device_free</phrase></refentrytitle> 383 <manvolnum>9</manvolnum> 384 <refmiscinfo class="version">4.4.14</refmiscinfo> 385</refmeta> 386<refnamediv> 387 <refname>iio_device_free</refname> 388 <refpurpose> 389 free an iio_dev from a driver 390 </refpurpose> 391</refnamediv> 392<refsynopsisdiv> 393 <title>Synopsis</title> 394 <funcsynopsis><funcprototype> 395 <funcdef>void <function>iio_device_free </function></funcdef> 396 <paramdef>struct iio_dev * <parameter>dev</parameter></paramdef> 397 </funcprototype></funcsynopsis> 398</refsynopsisdiv> 399<refsect1> 400 <title>Arguments</title> 401 <variablelist> 402 <varlistentry> 403 <term><parameter>dev</parameter></term> 404 <listitem> 405 <para> 406 the iio_dev associated with the device 407 </para> 408 </listitem> 409 </varlistentry> 410 </variablelist> 411</refsect1> 412</refentry> 413 414<refentry id="API-iio-device-register"> 415<refentryinfo> 416 <title>LINUX</title> 417 <productname>Kernel Hackers Manual</productname> 418 <date>July 2017</date> 419</refentryinfo> 420<refmeta> 421 <refentrytitle><phrase>iio_device_register</phrase></refentrytitle> 422 <manvolnum>9</manvolnum> 423 <refmiscinfo class="version">4.4.14</refmiscinfo> 424</refmeta> 425<refnamediv> 426 <refname>iio_device_register</refname> 427 <refpurpose> 428 register a device with the IIO subsystem 429 </refpurpose> 430</refnamediv> 431<refsynopsisdiv> 432 <title>Synopsis</title> 433 <funcsynopsis><funcprototype> 434 <funcdef>int <function>iio_device_register </function></funcdef> 435 <paramdef>struct iio_dev * <parameter>indio_dev</parameter></paramdef> 436 </funcprototype></funcsynopsis> 437</refsynopsisdiv> 438<refsect1> 439 <title>Arguments</title> 440 <variablelist> 441 <varlistentry> 442 <term><parameter>indio_dev</parameter></term> 443 <listitem> 444 <para> 445 Device structure filled by the device driver 446 </para> 447 </listitem> 448 </varlistentry> 449 </variablelist> 450</refsect1> 451</refentry> 452 453<refentry id="API-iio-device-unregister"> 454<refentryinfo> 455 <title>LINUX</title> 456 <productname>Kernel Hackers Manual</productname> 457 <date>July 2017</date> 458</refentryinfo> 459<refmeta> 460 <refentrytitle><phrase>iio_device_unregister</phrase></refentrytitle> 461 <manvolnum>9</manvolnum> 462 <refmiscinfo class="version">4.4.14</refmiscinfo> 463</refmeta> 464<refnamediv> 465 <refname>iio_device_unregister</refname> 466 <refpurpose> 467 unregister a device from the IIO subsystem 468 </refpurpose> 469</refnamediv> 470<refsynopsisdiv> 471 <title>Synopsis</title> 472 <funcsynopsis><funcprototype> 473 <funcdef>void <function>iio_device_unregister </function></funcdef> 474 <paramdef>struct iio_dev * <parameter>indio_dev</parameter></paramdef> 475 </funcprototype></funcsynopsis> 476</refsynopsisdiv> 477<refsect1> 478 <title>Arguments</title> 479 <variablelist> 480 <varlistentry> 481 <term><parameter>indio_dev</parameter></term> 482 <listitem> 483 <para> 484 Device structure representing the device. 485 </para> 486 </listitem> 487 </varlistentry> 488 </variablelist> 489</refsect1> 490</refentry> 491 492 493 <para> 494 An IIO device usually corresponds to a single hardware sensor and it 495 provides all the information needed by a driver handling a device. 496 Let's first have a look at the functionality embedded in an IIO 497 device then we will show how a device driver makes use of an IIO 498 device. 499 </para> 500 <para> 501 There are two ways for a user space application to interact 502 with an IIO driver. 503 <itemizedlist> 504 <listitem> 505 <filename>/sys/bus/iio/iio:deviceX/</filename>, this 506 represents a hardware sensor and groups together the data 507 channels of the same chip. 508 </listitem> 509 <listitem> 510 <filename>/dev/iio:deviceX</filename>, character device node 511 interface used for buffered data transfer and for events information 512 retrieval. 513 </listitem> 514 </itemizedlist> 515 </para> 516 A typical IIO driver will register itself as an I2C or SPI driver and will 517 create two routines, <function> probe </function> and <function> remove 518 </function>. At <function>probe</function>: 519 <itemizedlist> 520 <listitem>call <function>iio_device_alloc</function>, which allocates memory 521 for an IIO device. 522 </listitem> 523 <listitem> initialize IIO device fields with driver specific information 524 (e.g. device name, device channels). 525 </listitem> 526 <listitem>call <function> iio_device_register</function>, this registers the 527 device with the IIO core. After this call the device is ready to accept 528 requests from user space applications. 529 </listitem> 530 </itemizedlist> 531 At <function>remove</function>, we free the resources allocated in 532 <function>probe</function> in reverse order: 533 <itemizedlist> 534 <listitem><function>iio_device_unregister</function>, unregister the device 535 from the IIO core. 536 </listitem> 537 <listitem><function>iio_device_free</function>, free the memory allocated 538 for the IIO device. 539 </listitem> 540 </itemizedlist> 541 542 <sect2 id="iioattr"> <title> IIO device sysfs interface </title> 543 <para> 544 Attributes are sysfs files used to expose chip info and also allowing 545 applications to set various configuration parameters. For device 546 with index X, attributes can be found under 547 <filename>/sys/bus/iio/iio:deviceX/ </filename> directory. 548 Common attributes are: 549 <itemizedlist> 550 <listitem><filename>name</filename>, description of the physical 551 chip. 552 </listitem> 553 <listitem><filename>dev</filename>, shows the major:minor pair 554 associated with <filename>/dev/iio:deviceX</filename> node. 555 </listitem> 556 <listitem><filename>sampling_frequency_available</filename>, 557 available discrete set of sampling frequency values for 558 device. 559 </listitem> 560 </itemizedlist> 561 Available standard attributes for IIO devices are described in the 562 <filename>Documentation/ABI/testing/sysfs-bus-iio </filename> file 563 in the Linux kernel sources. 564 </para> 565 </sect2> 566 <sect2 id="iiochannel"> <title> IIO device channels </title> 567<refentry id="API-struct-iio-chan-spec"> 568<refentryinfo> 569 <title>LINUX</title> 570 <productname>Kernel Hackers Manual</productname> 571 <date>July 2017</date> 572</refentryinfo> 573<refmeta> 574 <refentrytitle><phrase>struct iio_chan_spec</phrase></refentrytitle> 575 <manvolnum>9</manvolnum> 576 <refmiscinfo class="version">4.4.14</refmiscinfo> 577</refmeta> 578<refnamediv> 579 <refname>struct iio_chan_spec</refname> 580 <refpurpose> 581 specification of a single channel 582 </refpurpose> 583</refnamediv> 584<refsynopsisdiv> 585 <title>Synopsis</title> 586 <programlisting> 587struct iio_chan_spec { 588 enum iio_chan_type type; 589 int channel; 590 int channel2; 591 unsigned long address; 592 int scan_index; 593 struct scan_type; 594 long info_mask_separate; 595 long info_mask_shared_by_type; 596 long info_mask_shared_by_dir; 597 long info_mask_shared_by_all; 598 const struct iio_event_spec * event_spec; 599 unsigned int num_event_specs; 600 const struct iio_chan_spec_ext_info * ext_info; 601 const char * extend_name; 602 const char * datasheet_name; 603 unsigned modified:1; 604 unsigned indexed:1; 605 unsigned output:1; 606 unsigned differential:1; 607}; </programlisting> 608</refsynopsisdiv> 609 <refsect1> 610 <title>Members</title> 611 <variablelist> 612 <varlistentry> <term>type</term> 613 <listitem><para> 614What type of measurement is the channel making. 615 </para></listitem> 616 </varlistentry> 617 <varlistentry> <term>channel</term> 618 <listitem><para> 619What number do we wish to assign the channel. 620 </para></listitem> 621 </varlistentry> 622 <varlistentry> <term>channel2</term> 623 <listitem><para> 624If there is a second number for a differential 625channel then this is it. If modified is set then the 626value here specifies the modifier. 627 </para></listitem> 628 </varlistentry> 629 <varlistentry> <term>address</term> 630 <listitem><para> 631Driver specific identifier. 632 </para></listitem> 633 </varlistentry> 634 <varlistentry> <term>scan_index</term> 635 <listitem><para> 636Monotonic index to give ordering in scans when read 637from a buffer. 638 </para></listitem> 639 </varlistentry> 640 <varlistentry> <term>scan_type</term> 641 <listitem><para> 642Sign: 's' or 'u' to specify signed or unsigned 643 </para></listitem> 644 </varlistentry> 645 <varlistentry> <term>info_mask_separate</term> 646 <listitem><para> 647What information is to be exported that is specific to 648this channel. 649 </para></listitem> 650 </varlistentry> 651 <varlistentry> <term>info_mask_shared_by_type</term> 652 <listitem><para> 653What information is to be exported that is shared 654by all channels of the same type. 655 </para></listitem> 656 </varlistentry> 657 <varlistentry> <term>info_mask_shared_by_dir</term> 658 <listitem><para> 659What information is to be exported that is shared 660by all channels of the same direction. 661 </para></listitem> 662 </varlistentry> 663 <varlistentry> <term>info_mask_shared_by_all</term> 664 <listitem><para> 665What information is to be exported that is shared 666by all channels. 667 </para></listitem> 668 </varlistentry> 669 <varlistentry> <term>event_spec</term> 670 <listitem><para> 671Array of events which should be registered for this 672channel. 673 </para></listitem> 674 </varlistentry> 675 <varlistentry> <term>num_event_specs</term> 676 <listitem><para> 677Size of the event_spec array. 678 </para></listitem> 679 </varlistentry> 680 <varlistentry> <term>ext_info</term> 681 <listitem><para> 682Array of extended info attributes for this channel. 683The array is NULL terminated, the last element should 684have its name field set to NULL. 685 </para></listitem> 686 </varlistentry> 687 <varlistentry> <term>extend_name</term> 688 <listitem><para> 689Allows labeling of channel attributes with an 690informative name. Note this has no effect codes etc, 691unlike modifiers. 692 </para></listitem> 693 </varlistentry> 694 <varlistentry> <term>datasheet_name</term> 695 <listitem><para> 696A name used in in-kernel mapping of channels. It should 697correspond to the first name that the channel is referred 698to by in the datasheet (e.g. IND), or the nearest 699possible compound name (e.g. IND-INC). 700 </para></listitem> 701 </varlistentry> 702 <varlistentry> <term>modified</term> 703 <listitem><para> 704Does a modifier apply to this channel. What these are 705depends on the channel type. Modifier is set in 706channel2. Examples are IIO_MOD_X for axial sensors about 707the 'x' axis. 708 </para></listitem> 709 </varlistentry> 710 <varlistentry> <term>indexed</term> 711 <listitem><para> 712Specify the channel has a numerical index. If not, 713the channel index number will be suppressed for sysfs 714attributes but not for event codes. 715 </para></listitem> 716 </varlistentry> 717 <varlistentry> <term>output</term> 718 <listitem><para> 719Channel is output. 720 </para></listitem> 721 </varlistentry> 722 <varlistentry> <term>differential</term> 723 <listitem><para> 724Channel is differential. 725 </para></listitem> 726 </varlistentry> 727 </variablelist> 728 </refsect1> 729<refsect1> 730<title>realbits</title> 731<para> 732 Number of valid bits of data 733</para> 734</refsect1> 735<refsect1> 736<title>storage_bits</title> 737<para> 738 Realbits + padding 739</para> 740</refsect1> 741<refsect1> 742<title>shift</title> 743<para> 744 Shift right by this before masking out 745 realbits. 746</para> 747</refsect1> 748<refsect1> 749<title>endianness</title> 750<para> 751 little or big endian 752</para> 753</refsect1> 754<refsect1> 755<title>repeat</title> 756<para> 757 Number of times real/storage bits 758 repeats. When the repeat element is 759 more than 1, then the type element in 760 sysfs will show a repeat value. 761 Otherwise, the number of repetitions is 762 omitted. 763</para> 764</refsect1> 765</refentry> 766 767 <para> 768 An IIO device channel is a representation of a data channel. An 769 IIO device can have one or multiple channels. For example: 770 <itemizedlist> 771 <listitem> 772 a thermometer sensor has one channel representing the 773 temperature measurement. 774 </listitem> 775 <listitem> 776 a light sensor with two channels indicating the measurements in 777 the visible and infrared spectrum. 778 </listitem> 779 <listitem> 780 an accelerometer can have up to 3 channels representing 781 acceleration on X, Y and Z axes. 782 </listitem> 783 </itemizedlist> 784 An IIO channel is described by the <type> struct iio_chan_spec 785 </type>. A thermometer driver for the temperature sensor in the 786 example above would have to describe its channel as follows: 787 <programlisting> 788 static const struct iio_chan_spec temp_channel[] = { 789 { 790 .type = IIO_TEMP, 791 .info_mask_separate = BIT(IIO_CHAN_INFO_PROCESSED), 792 }, 793 }; 794 795 </programlisting> 796 Channel sysfs attributes exposed to userspace are specified in 797 the form of <emphasis>bitmasks</emphasis>. Depending on their 798 shared info, attributes can be set in one of the following masks: 799 <itemizedlist> 800 <listitem><emphasis>info_mask_separate</emphasis>, attributes will 801 be specific to this channel</listitem> 802 <listitem><emphasis>info_mask_shared_by_type</emphasis>, 803 attributes are shared by all channels of the same type</listitem> 804 <listitem><emphasis>info_mask_shared_by_dir</emphasis>, attributes 805 are shared by all channels of the same direction </listitem> 806 <listitem><emphasis>info_mask_shared_by_all</emphasis>, 807 attributes are shared by all channels</listitem> 808 </itemizedlist> 809 When there are multiple data channels per channel type we have two 810 ways to distinguish between them: 811 <itemizedlist> 812 <listitem> set <emphasis> .modified</emphasis> field of <type> 813 iio_chan_spec</type> to 1. Modifiers are specified using 814 <emphasis>.channel2</emphasis> field of the same 815 <type>iio_chan_spec</type> structure and are used to indicate a 816 physically unique characteristic of the channel such as its direction 817 or spectral response. For example, a light sensor can have two channels, 818 one for infrared light and one for both infrared and visible light. 819 </listitem> 820 <listitem> set <emphasis>.indexed </emphasis> field of 821 <type>iio_chan_spec</type> to 1. In this case the channel is 822 simply another instance with an index specified by the 823 <emphasis>.channel</emphasis> field. 824 </listitem> 825 </itemizedlist> 826 Here is how we can make use of the channel's modifiers: 827 <programlisting> 828 static const struct iio_chan_spec light_channels[] = { 829 { 830 .type = IIO_INTENSITY, 831 .modified = 1, 832 .channel2 = IIO_MOD_LIGHT_IR, 833 .info_mask_separate = BIT(IIO_CHAN_INFO_RAW), 834 .info_mask_shared = BIT(IIO_CHAN_INFO_SAMP_FREQ), 835 }, 836 { 837 .type = IIO_INTENSITY, 838 .modified = 1, 839 .channel2 = IIO_MOD_LIGHT_BOTH, 840 .info_mask_separate = BIT(IIO_CHAN_INFO_RAW), 841 .info_mask_shared = BIT(IIO_CHAN_INFO_SAMP_FREQ), 842 }, 843 { 844 .type = IIO_LIGHT, 845 .info_mask_separate = BIT(IIO_CHAN_INFO_PROCESSED), 846 .info_mask_shared = BIT(IIO_CHAN_INFO_SAMP_FREQ), 847 }, 848 849 } 850 </programlisting> 851 This channel's definition will generate two separate sysfs files 852 for raw data retrieval: 853 <itemizedlist> 854 <listitem> 855 <filename>/sys/bus/iio/iio:deviceX/in_intensity_ir_raw</filename> 856 </listitem> 857 <listitem> 858 <filename>/sys/bus/iio/iio:deviceX/in_intensity_both_raw</filename> 859 </listitem> 860 </itemizedlist> 861 one file for processed data: 862 <itemizedlist> 863 <listitem> 864 <filename>/sys/bus/iio/iio:deviceX/in_illuminance_input 865 </filename> 866 </listitem> 867 </itemizedlist> 868 and one shared sysfs file for sampling frequency: 869 <itemizedlist> 870 <listitem> 871 <filename>/sys/bus/iio/iio:deviceX/sampling_frequency. 872 </filename> 873 </listitem> 874 </itemizedlist> 875 </para> 876 <para> 877 Here is how we can make use of the channel's indexing: 878 <programlisting> 879 static const struct iio_chan_spec light_channels[] = { 880 { 881 .type = IIO_VOLTAGE, 882 .indexed = 1, 883 .channel = 0, 884 .info_mask_separate = BIT(IIO_CHAN_INFO_RAW), 885 }, 886 { 887 .type = IIO_VOLTAGE, 888 .indexed = 1, 889 .channel = 1, 890 .info_mask_separate = BIT(IIO_CHAN_INFO_RAW), 891 }, 892 } 893 </programlisting> 894 This will generate two separate attributes files for raw data 895 retrieval: 896 <itemizedlist> 897 <listitem> 898 <filename>/sys/bus/iio/devices/iio:deviceX/in_voltage0_raw</filename>, 899 representing voltage measurement for channel 0. 900 </listitem> 901 <listitem> 902 <filename>/sys/bus/iio/devices/iio:deviceX/in_voltage1_raw</filename>, 903 representing voltage measurement for channel 1. 904 </listitem> 905 </itemizedlist> 906 </para> 907 </sect2> 908 </sect1> 909 910 <sect1 id="iiobuffer"> <title> Industrial I/O buffers </title> 911<refentry id="API-struct-iio-buffer"> 912<refentryinfo> 913 <title>LINUX</title> 914 <productname>Kernel Hackers Manual</productname> 915 <date>July 2017</date> 916</refentryinfo> 917<refmeta> 918 <refentrytitle><phrase>struct iio_buffer</phrase></refentrytitle> 919 <manvolnum>9</manvolnum> 920 <refmiscinfo class="version">4.4.14</refmiscinfo> 921</refmeta> 922<refnamediv> 923 <refname>struct iio_buffer</refname> 924 <refpurpose> 925 general buffer structure 926 </refpurpose> 927</refnamediv> 928<refsynopsisdiv> 929 <title>Synopsis</title> 930 <programlisting> 931struct iio_buffer { 932 int length; 933 int bytes_per_datum; 934 struct attribute_group * scan_el_attrs; 935 long * scan_mask; 936 bool scan_timestamp; 937 const struct iio_buffer_access_funcs * access; 938 struct list_head scan_el_dev_attr_list; 939 struct attribute_group scan_el_group; 940 wait_queue_head_t pollq; 941 bool stufftoread; 942 struct list_head demux_list; 943 void * demux_bounce; 944 struct list_head buffer_list; 945 struct kref ref; 946 unsigned int watermark; 947}; </programlisting> 948</refsynopsisdiv> 949 <refsect1> 950 <title>Members</title> 951 <variablelist> 952 <varlistentry> <term>length</term> 953 <listitem><para> 954[DEVICE] number of datums in buffer 955 </para></listitem> 956 </varlistentry> 957 <varlistentry> <term>bytes_per_datum</term> 958 <listitem><para> 959[DEVICE] size of individual datum including timestamp 960 </para></listitem> 961 </varlistentry> 962 <varlistentry> <term>scan_el_attrs</term> 963 <listitem><para> 964[DRIVER] control of scan elements if that scan mode 965control method is used 966 </para></listitem> 967 </varlistentry> 968 <varlistentry> <term>scan_mask</term> 969 <listitem><para> 970[INTERN] bitmask used in masking scan mode elements 971 </para></listitem> 972 </varlistentry> 973 <varlistentry> <term>scan_timestamp</term> 974 <listitem><para> 975[INTERN] does the scan mode include a timestamp 976 </para></listitem> 977 </varlistentry> 978 <varlistentry> <term>access</term> 979 <listitem><para> 980[DRIVER] buffer access functions associated with the 981implementation. 982 </para></listitem> 983 </varlistentry> 984 <varlistentry> <term>scan_el_dev_attr_list</term> 985 <listitem><para> 986[INTERN] list of scan element related attributes. 987 </para></listitem> 988 </varlistentry> 989 <varlistentry> <term>scan_el_group</term> 990 <listitem><para> 991[DRIVER] attribute group for those attributes not 992created from the iio_chan_info array. 993 </para></listitem> 994 </varlistentry> 995 <varlistentry> <term>pollq</term> 996 <listitem><para> 997[INTERN] wait queue to allow for polling on the buffer. 998 </para></listitem> 999 </varlistentry> 1000 <varlistentry> <term>stufftoread</term> 1001 <listitem><para> 1002[INTERN] flag to indicate new data. 1003 </para></listitem> 1004 </varlistentry> 1005 <varlistentry> <term>demux_list</term> 1006 <listitem><para> 1007[INTERN] list of operations required to demux the scan. 1008 </para></listitem> 1009 </varlistentry> 1010 <varlistentry> <term>demux_bounce</term> 1011 <listitem><para> 1012[INTERN] buffer for doing gather from incoming scan. 1013 </para></listitem> 1014 </varlistentry> 1015 <varlistentry> <term>buffer_list</term> 1016 <listitem><para> 1017[INTERN] entry in the devices list of current buffers. 1018 </para></listitem> 1019 </varlistentry> 1020 <varlistentry> <term>ref</term> 1021 <listitem><para> 1022[INTERN] reference count of the buffer. 1023 </para></listitem> 1024 </varlistentry> 1025 <varlistentry> <term>watermark</term> 1026 <listitem><para> 1027[INTERN] number of datums to wait for poll/read. 1028 </para></listitem> 1029 </varlistentry> 1030 </variablelist> 1031 </refsect1> 1032</refentry> 1033 1034<!-- drivers/iio/industrialio-buffer.c --> 1035<refentry id="API-iio-validate-scan-mask-onehot"> 1036<refentryinfo> 1037 <title>LINUX</title> 1038 <productname>Kernel Hackers Manual</productname> 1039 <date>July 2017</date> 1040</refentryinfo> 1041<refmeta> 1042 <refentrytitle><phrase>iio_validate_scan_mask_onehot</phrase></refentrytitle> 1043 <manvolnum>9</manvolnum> 1044 <refmiscinfo class="version">4.4.14</refmiscinfo> 1045</refmeta> 1046<refnamediv> 1047 <refname>iio_validate_scan_mask_onehot</refname> 1048 <refpurpose> 1049 Validates that exactly one channel is selected 1050 </refpurpose> 1051</refnamediv> 1052<refsynopsisdiv> 1053 <title>Synopsis</title> 1054 <funcsynopsis><funcprototype> 1055 <funcdef>bool <function>iio_validate_scan_mask_onehot </function></funcdef> 1056 <paramdef>struct iio_dev * <parameter>indio_dev</parameter></paramdef> 1057 <paramdef>const unsigned long * <parameter>mask</parameter></paramdef> 1058 </funcprototype></funcsynopsis> 1059</refsynopsisdiv> 1060<refsect1> 1061 <title>Arguments</title> 1062 <variablelist> 1063 <varlistentry> 1064 <term><parameter>indio_dev</parameter></term> 1065 <listitem> 1066 <para> 1067 the iio device 1068 </para> 1069 </listitem> 1070 </varlistentry> 1071 <varlistentry> 1072 <term><parameter>mask</parameter></term> 1073 <listitem> 1074 <para> 1075 scan mask to be checked 1076 </para> 1077 </listitem> 1078 </varlistentry> 1079 </variablelist> 1080</refsect1> 1081<refsect1> 1082<title>Description</title> 1083<para> 1084 Return true if exactly one bit is set in the scan mask, false otherwise. It 1085 can be used for devices where only one channel can be active for sampling at 1086 a time. 1087</para> 1088</refsect1> 1089</refentry> 1090 1091<refentry id="API-iio-buffer-get"> 1092<refentryinfo> 1093 <title>LINUX</title> 1094 <productname>Kernel Hackers Manual</productname> 1095 <date>July 2017</date> 1096</refentryinfo> 1097<refmeta> 1098 <refentrytitle><phrase>iio_buffer_get</phrase></refentrytitle> 1099 <manvolnum>9</manvolnum> 1100 <refmiscinfo class="version">4.4.14</refmiscinfo> 1101</refmeta> 1102<refnamediv> 1103 <refname>iio_buffer_get</refname> 1104 <refpurpose> 1105 Grab a reference to the buffer 1106 </refpurpose> 1107</refnamediv> 1108<refsynopsisdiv> 1109 <title>Synopsis</title> 1110 <funcsynopsis><funcprototype> 1111 <funcdef>struct iio_buffer * <function>iio_buffer_get </function></funcdef> 1112 <paramdef>struct iio_buffer * <parameter>buffer</parameter></paramdef> 1113 </funcprototype></funcsynopsis> 1114</refsynopsisdiv> 1115<refsect1> 1116 <title>Arguments</title> 1117 <variablelist> 1118 <varlistentry> 1119 <term><parameter>buffer</parameter></term> 1120 <listitem> 1121 <para> 1122 The buffer to grab a reference for, may be NULL 1123 </para> 1124 </listitem> 1125 </varlistentry> 1126 </variablelist> 1127</refsect1> 1128<refsect1> 1129<title>Description</title> 1130<para> 1131 Returns the pointer to the buffer that was passed into the function. 1132</para> 1133</refsect1> 1134</refentry> 1135 1136<refentry id="API-iio-buffer-put"> 1137<refentryinfo> 1138 <title>LINUX</title> 1139 <productname>Kernel Hackers Manual</productname> 1140 <date>July 2017</date> 1141</refentryinfo> 1142<refmeta> 1143 <refentrytitle><phrase>iio_buffer_put</phrase></refentrytitle> 1144 <manvolnum>9</manvolnum> 1145 <refmiscinfo class="version">4.4.14</refmiscinfo> 1146</refmeta> 1147<refnamediv> 1148 <refname>iio_buffer_put</refname> 1149 <refpurpose> 1150 Release the reference to the buffer 1151 </refpurpose> 1152</refnamediv> 1153<refsynopsisdiv> 1154 <title>Synopsis</title> 1155 <funcsynopsis><funcprototype> 1156 <funcdef>void <function>iio_buffer_put </function></funcdef> 1157 <paramdef>struct iio_buffer * <parameter>buffer</parameter></paramdef> 1158 </funcprototype></funcsynopsis> 1159</refsynopsisdiv> 1160<refsect1> 1161 <title>Arguments</title> 1162 <variablelist> 1163 <varlistentry> 1164 <term><parameter>buffer</parameter></term> 1165 <listitem> 1166 <para> 1167 The buffer to release the reference for, may be NULL 1168 </para> 1169 </listitem> 1170 </varlistentry> 1171 </variablelist> 1172</refsect1> 1173</refentry> 1174 1175 1176 <para> 1177 The Industrial I/O core offers a way for continuous data capture 1178 based on a trigger source. Multiple data channels can be read at once 1179 from <filename>/dev/iio:deviceX</filename> character device node, 1180 thus reducing the CPU load. 1181 </para> 1182 1183 <sect2 id="iiobuffersysfs"> 1184 <title>IIO buffer sysfs interface </title> 1185 <para> 1186 An IIO buffer has an associated attributes directory under <filename> 1187 /sys/bus/iio/iio:deviceX/buffer/</filename>. Here are the existing 1188 attributes: 1189 <itemizedlist> 1190 <listitem> 1191 <emphasis>length</emphasis>, the total number of data samples 1192 (capacity) that can be stored by the buffer. 1193 </listitem> 1194 <listitem> 1195 <emphasis>enable</emphasis>, activate buffer capture. 1196 </listitem> 1197 </itemizedlist> 1198 1199 </para> 1200 </sect2> 1201 <sect2 id="iiobuffersetup"> <title> IIO buffer setup </title> 1202 <para>The meta information associated with a channel reading 1203 placed in a buffer is called a <emphasis> scan element </emphasis>. 1204 The important bits configuring scan elements are exposed to 1205 userspace applications via the <filename> 1206 /sys/bus/iio/iio:deviceX/scan_elements/</filename> directory. This 1207 file contains attributes of the following form: 1208 <itemizedlist> 1209 <listitem><emphasis>enable</emphasis>, used for enabling a channel. 1210 If and only if its attribute is non zero, then a triggered capture 1211 will contain data samples for this channel. 1212 </listitem> 1213 <listitem><emphasis>type</emphasis>, description of the scan element 1214 data storage within the buffer and hence the form in which it is 1215 read from user space. Format is <emphasis> 1216 [be|le]:[s|u]bits/storagebitsXrepeat[>>shift] </emphasis>. 1217 <itemizedlist> 1218 <listitem> <emphasis>be</emphasis> or <emphasis>le</emphasis>, specifies 1219 big or little endian. 1220 </listitem> 1221 <listitem> 1222 <emphasis>s </emphasis>or <emphasis>u</emphasis>, specifies if 1223 signed (2's complement) or unsigned. 1224 </listitem> 1225 <listitem><emphasis>bits</emphasis>, is the number of valid data 1226 bits. 1227 </listitem> 1228 <listitem><emphasis>storagebits</emphasis>, is the number of bits 1229 (after padding) that it occupies in the buffer. 1230 </listitem> 1231 <listitem> 1232 <emphasis>shift</emphasis>, if specified, is the shift that needs 1233 to be applied prior to masking out unused bits. 1234 </listitem> 1235 <listitem> 1236 <emphasis>repeat</emphasis>, specifies the number of bits/storagebits 1237 repetitions. When the repeat element is 0 or 1, then the repeat 1238 value is omitted. 1239 </listitem> 1240 </itemizedlist> 1241 </listitem> 1242 </itemizedlist> 1243 For example, a driver for a 3-axis accelerometer with 12 bit 1244 resolution where data is stored in two 8-bits registers as 1245 follows: 1246 <programlisting> 1247 7 6 5 4 3 2 1 0 1248 +---+---+---+---+---+---+---+---+ 1249 |D3 |D2 |D1 |D0 | X | X | X | X | (LOW byte, address 0x06) 1250 +---+---+---+---+---+---+---+---+ 1251 1252 7 6 5 4 3 2 1 0 1253 +---+---+---+---+---+---+---+---+ 1254 |D11|D10|D9 |D8 |D7 |D6 |D5 |D4 | (HIGH byte, address 0x07) 1255 +---+---+---+---+---+---+---+---+ 1256 </programlisting> 1257 1258 will have the following scan element type for each axis: 1259 <programlisting> 1260 $ cat /sys/bus/iio/devices/iio:device0/scan_elements/in_accel_y_type 1261 le:s12/16>>4 1262 </programlisting> 1263 A user space application will interpret data samples read from the 1264 buffer as two byte little endian signed data, that needs a 4 bits 1265 right shift before masking out the 12 valid bits of data. 1266 </para> 1267 <para> 1268 For implementing buffer support a driver should initialize the following 1269 fields in <type>iio_chan_spec</type> definition: 1270 <programlisting> 1271 struct iio_chan_spec { 1272 /* other members */ 1273 int scan_index 1274 struct { 1275 char sign; 1276 u8 realbits; 1277 u8 storagebits; 1278 u8 shift; 1279 u8 repeat; 1280 enum iio_endian endianness; 1281 } scan_type; 1282 }; 1283 </programlisting> 1284 The driver implementing the accelerometer described above will 1285 have the following channel definition: 1286 <programlisting> 1287 struct struct iio_chan_spec accel_channels[] = { 1288 { 1289 .type = IIO_ACCEL, 1290 .modified = 1, 1291 .channel2 = IIO_MOD_X, 1292 /* other stuff here */ 1293 .scan_index = 0, 1294 .scan_type = { 1295 .sign = 's', 1296 .realbits = 12, 1297 .storgebits = 16, 1298 .shift = 4, 1299 .endianness = IIO_LE, 1300 }, 1301 } 1302 /* similar for Y (with channel2 = IIO_MOD_Y, scan_index = 1) 1303 * and Z (with channel2 = IIO_MOD_Z, scan_index = 2) axis 1304 */ 1305 } 1306 </programlisting> 1307 </para> 1308 <para> 1309 Here <emphasis> scan_index </emphasis> defines the order in which 1310 the enabled channels are placed inside the buffer. Channels with a lower 1311 scan_index will be placed before channels with a higher index. Each 1312 channel needs to have a unique scan_index. 1313 </para> 1314 <para> 1315 Setting scan_index to -1 can be used to indicate that the specific 1316 channel does not support buffered capture. In this case no entries will 1317 be created for the channel in the scan_elements directory. 1318 </para> 1319 </sect2> 1320 </sect1> 1321 1322 <sect1 id="iiotrigger"> <title> Industrial I/O triggers </title> 1323<refentry id="API-struct-iio-trigger"> 1324<refentryinfo> 1325 <title>LINUX</title> 1326 <productname>Kernel Hackers Manual</productname> 1327 <date>July 2017</date> 1328</refentryinfo> 1329<refmeta> 1330 <refentrytitle><phrase>struct iio_trigger</phrase></refentrytitle> 1331 <manvolnum>9</manvolnum> 1332 <refmiscinfo class="version">4.4.14</refmiscinfo> 1333</refmeta> 1334<refnamediv> 1335 <refname>struct iio_trigger</refname> 1336 <refpurpose> 1337 industrial I/O trigger device 1338 </refpurpose> 1339</refnamediv> 1340<refsynopsisdiv> 1341 <title>Synopsis</title> 1342 <programlisting> 1343struct iio_trigger { 1344 const struct iio_trigger_ops * ops; 1345 int id; 1346 const char * name; 1347 struct device dev; 1348 struct list_head list; 1349 struct list_head alloc_list; 1350 atomic_t use_count; 1351 struct irq_chip subirq_chip; 1352 int subirq_base; 1353 struct iio_subirq subirqs[CONFIG_IIO_CONSUMERS_PER_TRIGGER]; 1354 unsigned long pool[BITS_TO_LONGS(CONFIG_IIO_CONSUMERS_PER_TRIGGER)]; 1355 struct mutex pool_lock; 1356}; </programlisting> 1357</refsynopsisdiv> 1358 <refsect1> 1359 <title>Members</title> 1360 <variablelist> 1361 <varlistentry> <term>ops</term> 1362 <listitem><para> 1363[DRIVER] operations structure 1364 </para></listitem> 1365 </varlistentry> 1366 <varlistentry> <term>id</term> 1367 <listitem><para> 1368[INTERN] unique id number 1369 </para></listitem> 1370 </varlistentry> 1371 <varlistentry> <term>name</term> 1372 <listitem><para> 1373[DRIVER] unique name 1374 </para></listitem> 1375 </varlistentry> 1376 <varlistentry> <term>dev</term> 1377 <listitem><para> 1378[DRIVER] associated device (if relevant) 1379 </para></listitem> 1380 </varlistentry> 1381 <varlistentry> <term>list</term> 1382 <listitem><para> 1383[INTERN] used in maintenance of global trigger list 1384 </para></listitem> 1385 </varlistentry> 1386 <varlistentry> <term>alloc_list</term> 1387 <listitem><para> 1388[DRIVER] used for driver specific trigger list 1389 </para></listitem> 1390 </varlistentry> 1391 <varlistentry> <term>use_count</term> 1392 <listitem><para> 1393use count for the trigger 1394 </para></listitem> 1395 </varlistentry> 1396 <varlistentry> <term>subirq_chip</term> 1397 <listitem><para> 1398[INTERN] associate 'virtual' irq chip. 1399 </para></listitem> 1400 </varlistentry> 1401 <varlistentry> <term>subirq_base</term> 1402 <listitem><para> 1403[INTERN] base number for irqs provided by trigger. 1404 </para></listitem> 1405 </varlistentry> 1406 <varlistentry> <term>subirqs[CONFIG_IIO_CONSUMERS_PER_TRIGGER]</term> 1407 <listitem><para> 1408[INTERN] information about the 'child' irqs. 1409 </para></listitem> 1410 </varlistentry> 1411 <varlistentry> <term>pool[BITS_TO_LONGS(CONFIG_IIO_CONSUMERS_PER_TRIGGER)]</term> 1412 <listitem><para> 1413[INTERN] bitmap of irqs currently in use. 1414 </para></listitem> 1415 </varlistentry> 1416 <varlistentry> <term>pool_lock</term> 1417 <listitem><para> 1418[INTERN] protection of the irq pool. 1419 </para></listitem> 1420 </varlistentry> 1421 </variablelist> 1422 </refsect1> 1423</refentry> 1424 1425<!-- drivers/iio/industrialio-trigger.c --> 1426<refentry id="API-devm-iio-trigger-alloc"> 1427<refentryinfo> 1428 <title>LINUX</title> 1429 <productname>Kernel Hackers Manual</productname> 1430 <date>July 2017</date> 1431</refentryinfo> 1432<refmeta> 1433 <refentrytitle><phrase>devm_iio_trigger_alloc</phrase></refentrytitle> 1434 <manvolnum>9</manvolnum> 1435 <refmiscinfo class="version">4.4.14</refmiscinfo> 1436</refmeta> 1437<refnamediv> 1438 <refname>devm_iio_trigger_alloc</refname> 1439 <refpurpose> 1440 Resource-managed <function>iio_trigger_alloc</function> 1441 </refpurpose> 1442</refnamediv> 1443<refsynopsisdiv> 1444 <title>Synopsis</title> 1445 <funcsynopsis><funcprototype> 1446 <funcdef>struct iio_trigger * <function>devm_iio_trigger_alloc </function></funcdef> 1447 <paramdef>struct device * <parameter>dev</parameter></paramdef> 1448 <paramdef>const char * <parameter>fmt</parameter></paramdef> 1449 <paramdef> <parameter>...</parameter></paramdef> 1450 </funcprototype></funcsynopsis> 1451</refsynopsisdiv> 1452<refsect1> 1453 <title>Arguments</title> 1454 <variablelist> 1455 <varlistentry> 1456 <term><parameter>dev</parameter></term> 1457 <listitem> 1458 <para> 1459 Device to allocate iio_trigger for 1460 </para> 1461 </listitem> 1462 </varlistentry> 1463 <varlistentry> 1464 <term><parameter>fmt</parameter></term> 1465 <listitem> 1466 <para> 1467 trigger name format. If it includes format 1468 specifiers, the additional arguments following 1469 format are formatted and inserted in the resulting 1470 string replacing their respective specifiers. 1471 </para> 1472 </listitem> 1473 </varlistentry> 1474 <varlistentry> 1475 <term><parameter>...</parameter></term> 1476 <listitem> 1477 <para> 1478 variable arguments 1479 </para> 1480 </listitem> 1481 </varlistentry> 1482 </variablelist> 1483</refsect1> 1484<refsect1> 1485<title>Description</title> 1486<para> 1487 Managed iio_trigger_alloc. iio_trigger allocated with this function is 1488 automatically freed on driver detach. 1489 </para><para> 1490 1491 If an iio_trigger allocated with this function needs to be freed separately, 1492 <function>devm_iio_trigger_free</function> must be used. 1493</para> 1494</refsect1> 1495<refsect1> 1496<title>RETURNS</title> 1497<para> 1498 Pointer to allocated iio_trigger on success, NULL on failure. 1499</para> 1500</refsect1> 1501</refentry> 1502 1503<refentry id="API-devm-iio-trigger-free"> 1504<refentryinfo> 1505 <title>LINUX</title> 1506 <productname>Kernel Hackers Manual</productname> 1507 <date>July 2017</date> 1508</refentryinfo> 1509<refmeta> 1510 <refentrytitle><phrase>devm_iio_trigger_free</phrase></refentrytitle> 1511 <manvolnum>9</manvolnum> 1512 <refmiscinfo class="version">4.4.14</refmiscinfo> 1513</refmeta> 1514<refnamediv> 1515 <refname>devm_iio_trigger_free</refname> 1516 <refpurpose> 1517 Resource-managed <function>iio_trigger_free</function> 1518 </refpurpose> 1519</refnamediv> 1520<refsynopsisdiv> 1521 <title>Synopsis</title> 1522 <funcsynopsis><funcprototype> 1523 <funcdef>void <function>devm_iio_trigger_free </function></funcdef> 1524 <paramdef>struct device * <parameter>dev</parameter></paramdef> 1525 <paramdef>struct iio_trigger * <parameter>iio_trig</parameter></paramdef> 1526 </funcprototype></funcsynopsis> 1527</refsynopsisdiv> 1528<refsect1> 1529 <title>Arguments</title> 1530 <variablelist> 1531 <varlistentry> 1532 <term><parameter>dev</parameter></term> 1533 <listitem> 1534 <para> 1535 Device this iio_dev belongs to 1536 </para> 1537 </listitem> 1538 </varlistentry> 1539 <varlistentry> 1540 <term><parameter>iio_trig</parameter></term> 1541 <listitem> 1542 <para> 1543 the iio_trigger associated with the device 1544 </para> 1545 </listitem> 1546 </varlistentry> 1547 </variablelist> 1548</refsect1> 1549<refsect1> 1550<title>Description</title> 1551<para> 1552 Free iio_trigger allocated with <function>devm_iio_trigger_alloc</function>. 1553</para> 1554</refsect1> 1555</refentry> 1556 1557 <para> 1558 In many situations it is useful for a driver to be able to 1559 capture data based on some external event (trigger) as opposed 1560 to periodically polling for data. An IIO trigger can be provided 1561 by a device driver that also has an IIO device based on hardware 1562 generated events (e.g. data ready or threshold exceeded) or 1563 provided by a separate driver from an independent interrupt 1564 source (e.g. GPIO line connected to some external system, timer 1565 interrupt or user space writing a specific file in sysfs). A 1566 trigger may initiate data capture for a number of sensors and 1567 also it may be completely unrelated to the sensor itself. 1568 </para> 1569 1570 <sect2 id="iiotrigsysfs"> <title> IIO trigger sysfs interface </title> 1571 There are two locations in sysfs related to triggers: 1572 <itemizedlist> 1573 <listitem><filename>/sys/bus/iio/devices/triggerY</filename>, 1574 this file is created once an IIO trigger is registered with 1575 the IIO core and corresponds to trigger with index Y. Because 1576 triggers can be very different depending on type there are few 1577 standard attributes that we can describe here: 1578 <itemizedlist> 1579 <listitem> 1580 <emphasis>name</emphasis>, trigger name that can be later 1581 used for association with a device. 1582 </listitem> 1583 <listitem> 1584 <emphasis>sampling_frequency</emphasis>, some timer based 1585 triggers use this attribute to specify the frequency for 1586 trigger calls. 1587 </listitem> 1588 </itemizedlist> 1589 </listitem> 1590 <listitem> 1591 <filename>/sys/bus/iio/devices/iio:deviceX/trigger/</filename>, this 1592 directory is created once the device supports a triggered 1593 buffer. We can associate a trigger with our device by writing 1594 the trigger's name in the <filename>current_trigger</filename> file. 1595 </listitem> 1596 </itemizedlist> 1597 </sect2> 1598 1599 <sect2 id="iiotrigattr"> <title> IIO trigger setup</title> 1600 1601 <para> 1602 Let's see a simple example of how to setup a trigger to be used 1603 by a driver. 1604 1605 <programlisting> 1606 struct iio_trigger_ops trigger_ops = { 1607 .set_trigger_state = sample_trigger_state, 1608 .validate_device = sample_validate_device, 1609 } 1610 1611 struct iio_trigger *trig; 1612 1613 /* first, allocate memory for our trigger */ 1614 trig = iio_trigger_alloc(dev, "trig-%s-%d", name, idx); 1615 1616 /* setup trigger operations field */ 1617 trig->ops = &trigger_ops; 1618 1619 /* now register the trigger with the IIO core */ 1620 iio_trigger_register(trig); 1621 </programlisting> 1622 </para> 1623 </sect2> 1624 1625 <sect2 id="iiotrigsetup"> <title> IIO trigger ops</title> 1626<refentry id="API-struct-iio-trigger-ops"> 1627<refentryinfo> 1628 <title>LINUX</title> 1629 <productname>Kernel Hackers Manual</productname> 1630 <date>July 2017</date> 1631</refentryinfo> 1632<refmeta> 1633 <refentrytitle><phrase>struct iio_trigger_ops</phrase></refentrytitle> 1634 <manvolnum>9</manvolnum> 1635 <refmiscinfo class="version">4.4.14</refmiscinfo> 1636</refmeta> 1637<refnamediv> 1638 <refname>struct iio_trigger_ops</refname> 1639 <refpurpose> 1640 operations structure for an iio_trigger. 1641 </refpurpose> 1642</refnamediv> 1643<refsynopsisdiv> 1644 <title>Synopsis</title> 1645 <programlisting> 1646struct iio_trigger_ops { 1647 struct module * owner; 1648 int (* set_trigger_state) (struct iio_trigger *trig, bool state); 1649 int (* try_reenable) (struct iio_trigger *trig); 1650 int (* validate_device) (struct iio_trigger *trig,struct iio_dev *indio_dev); 1651}; </programlisting> 1652</refsynopsisdiv> 1653 <refsect1> 1654 <title>Members</title> 1655 <variablelist> 1656 <varlistentry> <term>owner</term> 1657 <listitem><para> 1658used to monitor usage count of the trigger. 1659 </para></listitem> 1660 </varlistentry> 1661 <varlistentry> <term>set_trigger_state</term> 1662 <listitem><para> 1663switch on/off the trigger on demand 1664 </para></listitem> 1665 </varlistentry> 1666 <varlistentry> <term>try_reenable</term> 1667 <listitem><para> 1668function to reenable the trigger when the 1669use count is zero (may be NULL) 1670 </para></listitem> 1671 </varlistentry> 1672 <varlistentry> <term>validate_device</term> 1673 <listitem><para> 1674function to validate the device when the 1675current trigger gets changed. 1676 </para></listitem> 1677 </varlistentry> 1678 </variablelist> 1679 </refsect1> 1680<refsect1> 1681<title>Description</title> 1682<para> 1683 This is typically static const within a driver and shared by 1684 instances of a given device. 1685</para> 1686</refsect1> 1687</refentry> 1688 1689 <para> 1690 Notice that a trigger has a set of operations attached: 1691 <itemizedlist> 1692 <listitem> 1693 <function>set_trigger_state</function>, switch the trigger on/off 1694 on demand. 1695 </listitem> 1696 <listitem> 1697 <function>validate_device</function>, function to validate the 1698 device when the current trigger gets changed. 1699 </listitem> 1700 </itemizedlist> 1701 </para> 1702 </sect2> 1703 </sect1> 1704 <sect1 id="iiotriggered_buffer"> 1705 <title> Industrial I/O triggered buffers </title> 1706 <para> 1707 Now that we know what buffers and triggers are let's see how they 1708 work together. 1709 </para> 1710 <sect2 id="iiotrigbufsetup"> <title> IIO triggered buffer setup</title> 1711<!-- drivers/iio/buffer/industrialio-triggered-buffer.c --> 1712<refentry id="API-iio-triggered-buffer-setup"> 1713<refentryinfo> 1714 <title>LINUX</title> 1715 <productname>Kernel Hackers Manual</productname> 1716 <date>July 2017</date> 1717</refentryinfo> 1718<refmeta> 1719 <refentrytitle><phrase>iio_triggered_buffer_setup</phrase></refentrytitle> 1720 <manvolnum>9</manvolnum> 1721 <refmiscinfo class="version">4.4.14</refmiscinfo> 1722</refmeta> 1723<refnamediv> 1724 <refname>iio_triggered_buffer_setup</refname> 1725 <refpurpose> 1726 Setup triggered buffer and pollfunc 1727 </refpurpose> 1728</refnamediv> 1729<refsynopsisdiv> 1730 <title>Synopsis</title> 1731 <funcsynopsis><funcprototype> 1732 <funcdef>int <function>iio_triggered_buffer_setup </function></funcdef> 1733 <paramdef>struct iio_dev * <parameter>indio_dev</parameter></paramdef> 1734 <paramdef>irqreturn_t (*<parameter>h</parameter>) 1735 <funcparams>int irq, void *p</funcparams></paramdef> 1736 <paramdef>irqreturn_t (*<parameter>thread</parameter>) 1737 <funcparams>int irq, void *p</funcparams></paramdef> 1738 <paramdef>const struct iio_buffer_setup_ops * <parameter>setup_ops</parameter></paramdef> 1739 </funcprototype></funcsynopsis> 1740</refsynopsisdiv> 1741<refsect1> 1742 <title>Arguments</title> 1743 <variablelist> 1744 <varlistentry> 1745 <term><parameter>indio_dev</parameter></term> 1746 <listitem> 1747 <para> 1748 IIO device structure 1749 </para> 1750 </listitem> 1751 </varlistentry> 1752 <varlistentry> 1753 <term><parameter>h</parameter></term> 1754 <listitem> 1755 <para> 1756 Function which will be used as pollfunc top half 1757 </para> 1758 </listitem> 1759 </varlistentry> 1760 <varlistentry> 1761 <term><parameter>thread</parameter></term> 1762 <listitem> 1763 <para> 1764 Function which will be used as pollfunc bottom half 1765 </para> 1766 </listitem> 1767 </varlistentry> 1768 <varlistentry> 1769 <term><parameter>setup_ops</parameter></term> 1770 <listitem> 1771 <para> 1772 Buffer setup functions to use for this device. 1773 If NULL the default setup functions for triggered 1774 buffers will be used. 1775 </para> 1776 </listitem> 1777 </varlistentry> 1778 </variablelist> 1779</refsect1> 1780<refsect1> 1781<title>Description</title> 1782<para> 1783 This function combines some common tasks which will normally be performed 1784 when setting up a triggered buffer. It will allocate the buffer and the 1785 pollfunc. 1786 </para><para> 1787 1788 Before calling this function the indio_dev structure should already be 1789 completely initialized, but not yet registered. In practice this means that 1790 this function should be called right before <function>iio_device_register</function>. 1791 </para><para> 1792 1793 To free the resources allocated by this function call 1794 <function>iio_triggered_buffer_cleanup</function>. 1795</para> 1796</refsect1> 1797</refentry> 1798 1799<refentry id="API-iio-triggered-buffer-cleanup"> 1800<refentryinfo> 1801 <title>LINUX</title> 1802 <productname>Kernel Hackers Manual</productname> 1803 <date>July 2017</date> 1804</refentryinfo> 1805<refmeta> 1806 <refentrytitle><phrase>iio_triggered_buffer_cleanup</phrase></refentrytitle> 1807 <manvolnum>9</manvolnum> 1808 <refmiscinfo class="version">4.4.14</refmiscinfo> 1809</refmeta> 1810<refnamediv> 1811 <refname>iio_triggered_buffer_cleanup</refname> 1812 <refpurpose> 1813 Free resources allocated by <function>iio_triggered_buffer_setup</function> 1814 </refpurpose> 1815</refnamediv> 1816<refsynopsisdiv> 1817 <title>Synopsis</title> 1818 <funcsynopsis><funcprototype> 1819 <funcdef>void <function>iio_triggered_buffer_cleanup </function></funcdef> 1820 <paramdef>struct iio_dev * <parameter>indio_dev</parameter></paramdef> 1821 </funcprototype></funcsynopsis> 1822</refsynopsisdiv> 1823<refsect1> 1824 <title>Arguments</title> 1825 <variablelist> 1826 <varlistentry> 1827 <term><parameter>indio_dev</parameter></term> 1828 <listitem> 1829 <para> 1830 IIO device structure 1831 </para> 1832 </listitem> 1833 </varlistentry> 1834 </variablelist> 1835</refsect1> 1836</refentry> 1837 1838<refentry id="API-struct-iio-buffer-setup-ops"> 1839<refentryinfo> 1840 <title>LINUX</title> 1841 <productname>Kernel Hackers Manual</productname> 1842 <date>July 2017</date> 1843</refentryinfo> 1844<refmeta> 1845 <refentrytitle><phrase>struct iio_buffer_setup_ops</phrase></refentrytitle> 1846 <manvolnum>9</manvolnum> 1847 <refmiscinfo class="version">4.4.14</refmiscinfo> 1848</refmeta> 1849<refnamediv> 1850 <refname>struct iio_buffer_setup_ops</refname> 1851 <refpurpose> 1852 buffer setup related callbacks 1853 </refpurpose> 1854</refnamediv> 1855<refsynopsisdiv> 1856 <title>Synopsis</title> 1857 <programlisting> 1858struct iio_buffer_setup_ops { 1859 int (* preenable) (struct iio_dev *); 1860 int (* postenable) (struct iio_dev *); 1861 int (* predisable) (struct iio_dev *); 1862 int (* postdisable) (struct iio_dev *); 1863 bool (* validate_scan_mask) (struct iio_dev *indio_dev,const unsigned long *scan_mask); 1864}; </programlisting> 1865</refsynopsisdiv> 1866 <refsect1> 1867 <title>Members</title> 1868 <variablelist> 1869 <varlistentry> <term>preenable</term> 1870 <listitem><para> 1871[DRIVER] function to run prior to marking buffer enabled 1872 </para></listitem> 1873 </varlistentry> 1874 <varlistentry> <term>postenable</term> 1875 <listitem><para> 1876[DRIVER] function to run after marking buffer enabled 1877 </para></listitem> 1878 </varlistentry> 1879 <varlistentry> <term>predisable</term> 1880 <listitem><para> 1881[DRIVER] function to run prior to marking buffer 1882disabled 1883 </para></listitem> 1884 </varlistentry> 1885 <varlistentry> <term>postdisable</term> 1886 <listitem><para> 1887[DRIVER] function to run after marking buffer disabled 1888 </para></listitem> 1889 </varlistentry> 1890 <varlistentry> <term>validate_scan_mask</term> 1891 <listitem><para> 1892[DRIVER] function callback to check whether a given 1893scan mask is valid for the device. 1894 </para></listitem> 1895 </varlistentry> 1896 </variablelist> 1897 </refsect1> 1898</refentry> 1899 1900 1901 1902 <para> 1903 A typical triggered buffer setup looks like this: 1904 <programlisting> 1905 const struct iio_buffer_setup_ops sensor_buffer_setup_ops = { 1906 .preenable = sensor_buffer_preenable, 1907 .postenable = sensor_buffer_postenable, 1908 .postdisable = sensor_buffer_postdisable, 1909 .predisable = sensor_buffer_predisable, 1910 }; 1911 1912 irqreturn_t sensor_iio_pollfunc(int irq, void *p) 1913 { 1914 pf->timestamp = iio_get_time_ns(); 1915 return IRQ_WAKE_THREAD; 1916 } 1917 1918 irqreturn_t sensor_trigger_handler(int irq, void *p) 1919 { 1920 u16 buf[8]; 1921 int i = 0; 1922 1923 /* read data for each active channel */ 1924 for_each_set_bit(bit, active_scan_mask, masklength) 1925 buf[i++] = sensor_get_data(bit) 1926 1927 iio_push_to_buffers_with_timestamp(indio_dev, buf, timestamp); 1928 1929 iio_trigger_notify_done(trigger); 1930 return IRQ_HANDLED; 1931 } 1932 1933 /* setup triggered buffer, usually in probe function */ 1934 iio_triggered_buffer_setup(indio_dev, sensor_iio_polfunc, 1935 sensor_trigger_handler, 1936 sensor_buffer_setup_ops); 1937 </programlisting> 1938 </para> 1939 The important things to notice here are: 1940 <itemizedlist> 1941 <listitem><function> iio_buffer_setup_ops</function>, the buffer setup 1942 functions to be called at predefined points in the buffer configuration 1943 sequence (e.g. before enable, after disable). If not specified, the 1944 IIO core uses the default <type>iio_triggered_buffer_setup_ops</type>. 1945 </listitem> 1946 <listitem><function>sensor_iio_pollfunc</function>, the function that 1947 will be used as top half of poll function. It should do as little 1948 processing as possible, because it runs in interrupt context. The most 1949 common operation is recording of the current timestamp and for this reason 1950 one can use the IIO core defined <function>iio_pollfunc_store_time 1951 </function> function. 1952 </listitem> 1953 <listitem><function>sensor_trigger_handler</function>, the function that 1954 will be used as bottom half of the poll function. This runs in the 1955 context of a kernel thread and all the processing takes place here. 1956 It usually reads data from the device and stores it in the internal 1957 buffer together with the timestamp recorded in the top half. 1958 </listitem> 1959 </itemizedlist> 1960 </sect2> 1961 </sect1> 1962 </chapter> 1963 <chapter id='iioresources'> 1964 <title> Resources </title> 1965 IIO core may change during time so the best documentation to read is the 1966 source code. There are several locations where you should look: 1967 <itemizedlist> 1968 <listitem> 1969 <filename>drivers/iio/</filename>, contains the IIO core plus 1970 and directories for each sensor type (e.g. accel, magnetometer, 1971 etc.) 1972 </listitem> 1973 <listitem> 1974 <filename>include/linux/iio/</filename>, contains the header 1975 files, nice to read for the internal kernel interfaces. 1976 </listitem> 1977 <listitem> 1978 <filename>include/uapi/linux/iio/</filename>, contains files to be 1979 used by user space applications. 1980 </listitem> 1981 <listitem> 1982 <filename>tools/iio/</filename>, contains tools for rapidly 1983 testing buffers, events and device creation. 1984 </listitem> 1985 <listitem> 1986 <filename>drivers/staging/iio/</filename>, contains code for some 1987 drivers or experimental features that are not yet mature enough 1988 to be moved out. 1989 </listitem> 1990 </itemizedlist> 1991 <para> 1992 Besides the code, there are some good online documentation sources: 1993 <itemizedlist> 1994 <listitem> 1995 <ulink url="http://marc.info/?l=linux-iio"> Industrial I/O mailing 1996 list </ulink> 1997 </listitem> 1998 <listitem> 1999 <ulink url="http://wiki.analog.com/software/linux/docs/iio/iio"> 2000 Analog Device IIO wiki page </ulink> 2001 </listitem> 2002 <listitem> 2003 <ulink url="https://fosdem.org/2015/schedule/event/iiosdr/"> 2004 Using the Linux IIO framework for SDR, Lars-Peter Clausen's 2005 presentation at FOSDEM </ulink> 2006 </listitem> 2007 </itemizedlist> 2008 </para> 2009 </chapter> 2010</book> 2011 2012<!-- 2013vim: softtabstop=2:shiftwidth=2:expandtab:textwidth=72 2014--> 2015