[deliverable/linux.git] / Documentation / iio / iio_configfs.txt

Industrial IIO configfs support

1. Overview

Configfs is a filesystem-based manager of kernel objects. IIO uses some
objects that could be easily configured using configfs (e.g.: devices,
triggers).

See Documentation/filesystems/configfs/configfs.txt for more information
about how configfs works.

2. Usage

In order to use configfs support in IIO we need to select it at compile
time via CONFIG_IIO_CONFIGFS config option.

Then, mount the configfs filesystem (usually under /config directory):

$ mkdir /config
$ mount -t configfs none /config

At this point, all default IIO groups will be created and can be accessed
under /config/iio. Next chapters will describe available IIO configuration
objects.

3. Software triggers

One of the IIO default configfs groups is the "triggers" group. It is
automagically accessible when the configfs is mounted and can be found
under /config/iio/triggers.

IIO software triggers implementation offers support for creating multiple
trigger types. A new trigger type is usually implemented as a separate
kernel module following the interface in include/linux/iio/sw_trigger.h:

/*
 * drivers/iio/trigger/iio-trig-sample.c
 * sample kernel module implementing a new trigger type
 */
#include <linux/iio/sw_trigger.h>


static struct iio_sw_trigger *iio_trig_sample_probe(const char *name)
{
	/*
	 * This allocates and registers an IIO trigger plus other
	 * trigger type specific initialization.
	 */
}

static int iio_trig_hrtimer_remove(struct iio_sw_trigger *swt)
{
	/*
	 * This undoes the actions in iio_trig_sample_probe
	 */
}

static const struct iio_sw_trigger_ops iio_trig_sample_ops = {
	.probe		= iio_trig_sample_probe,
	.remove		= iio_trig_sample_remove,
};

static struct iio_sw_trigger_type iio_trig_sample = {
	.name = "trig-sample",
	.owner = THIS_MODULE,
	.ops = &iio_trig_sample_ops,
};

module_iio_sw_trigger_driver(iio_trig_sample);

Each trigger type has its own directory under /config/iio/triggers. Loading
iio-trig-sample module will create 'trig-sample' trigger type directory
/config/iio/triggers/trig-sample.

We support the following interrupt sources (trigger types):
	* hrtimer, uses high resolution timers as interrupt source

3.1 Hrtimer triggers creation and destruction

Loading iio-trig-hrtimer module will register hrtimer trigger types allowing
users to create hrtimer triggers under /config/iio/triggers/hrtimer.

e.g:

$ mkdir /config/triggers/hrtimer/instance1
$ rmdir /config/triggers/hrtimer/instance1

Each trigger can have one or more attributes specific to the trigger type.

3.2 "hrtimer" trigger types attributes

"hrtimer" trigger type doesn't have any configurable attribute from /config dir.
It does introduce the sampling_frequency attribute to trigger directory.
Commit	Line	Data
4c3e2a40 DB	1	Industrial IIO configfs support
	2
	3	1. Overview
	4
	5	Configfs is a filesystem-based manager of kernel objects. IIO uses some
	6	objects that could be easily configured using configfs (e.g.: devices,
	7	triggers).
	8
	9	See Documentation/filesystems/configfs/configfs.txt for more information
	10	about how configfs works.
	11
	12	2. Usage
	13
	14	In order to use configfs support in IIO we need to select it at compile
	15	time via CONFIG_IIO_CONFIGFS config option.
	16
	17	Then, mount the configfs filesystem (usually under /config directory):
	18
	19	$ mkdir /config
	20	$ mount -t configfs none /config
	21
	22	At this point, all default IIO groups will be created and can be accessed
	23	under /config/iio. Next chapters will describe available IIO configuration
	24	objects.
	25
	26	3. Software triggers
	27
	28	One of the IIO default configfs groups is the "triggers" group. It is
	29	automagically accessible when the configfs is mounted and can be found
	30	under /config/iio/triggers.
	31
	32	IIO software triggers implementation offers support for creating multiple
	33	trigger types. A new trigger type is usually implemented as a separate
	34	kernel module following the interface in include/linux/iio/sw_trigger.h:
	35
	36	/*
	37	* drivers/iio/trigger/iio-trig-sample.c
	38	* sample kernel module implementing a new trigger type
	39	*/
	40	#include <linux/iio/sw_trigger.h>
	41
	42
	43	static struct iio_sw_trigger iio_trig_sample_probe(const char name)
	44	{
	45	/*
	46	* This allocates and registers an IIO trigger plus other
	47	* trigger type specific initialization.
	48	*/
	49	}
	50
	51	static int iio_trig_hrtimer_remove(struct iio_sw_trigger *swt)
	52	{
	53	/*
	54	* This undoes the actions in iio_trig_sample_probe
	55	*/
	56	}
	57
	58	static const struct iio_sw_trigger_ops iio_trig_sample_ops = {
	59	.probe = iio_trig_sample_probe,
	60	.remove = iio_trig_sample_remove,
	61	};
	62
	63	static struct iio_sw_trigger_type iio_trig_sample = {
	64	.name = "trig-sample",
65	.owner = THIS_MODULE,
66	.ops = &iio_trig_sample_ops,
67	};
68
69	module_iio_sw_trigger_driver(iio_trig_sample);
70
71	Each trigger type has its own directory under /config/iio/triggers. Loading
72	iio-trig-sample module will create 'trig-sample' trigger type directory
73	/config/iio/triggers/trig-sample.
74
75	We support the following interrupt sources (trigger types):
76	* hrtimer, uses high resolution timers as interrupt source
77
78	3.1 Hrtimer triggers creation and destruction
79
80	Loading iio-trig-hrtimer module will register hrtimer trigger types allowing
81	users to create hrtimer triggers under /config/iio/triggers/hrtimer.
82
83	e.g:
84
85	$ mkdir /config/triggers/hrtimer/instance1
86	$ rmdir /config/triggers/hrtimer/instance1
87
88	Each trigger can have one or more attributes specific to the trigger type.
89
90	3.2 "hrtimer" trigger types attributes
91
92	"hrtimer" trigger type doesn't have any configurable attribute from /config dir.
93	It does introduce the sampling_frequency attribute to trigger directory.