Merge branch 'clk/mxs-for-3.6' of git://git.linaro.org/people/shawnguo/linux-2.6...

[deliverable/linux.git] / drivers / staging / iio / Documentation / device.txt

IIO Device drivers

This is not intended to provide a comprehensive guide to writing an
IIO device driver.  For further information see the drivers within the
subsystem.

The crucial structure for device drivers in iio is iio_dev.

First allocate one using:

struct iio_dev *indio_dev = iio_device_alloc(sizeof(struct chip_state));
where chip_state is a structure of local state data for this instance of
the chip.

That data can be accessed using iio_priv(struct iio_dev *)

Then fill in the following:

- indio_dev->dev.parent
	Struct device associated with the underlying hardware.
- indio_dev->name
	Name of the device being driven - made available as the name
	attribute in sysfs.

- indio_dev->info
	pointer to a structure with elements that tend to be fixed for
	large sets of different parts supported by a given driver.
	This contains:
	* info->driver_module:
		Set to THIS_MODULE. Used to ensure correct ownership
		of various resources allocate by the core.
	* info->event_attrs:
		Attributes used to enable / disable hardware events.
	* info->attrs:
		General device attributes. Typically used for the weird
		and the wonderful bits not covered by the channel specification.
	* info->read_raw:
		Raw data reading function. Used for both raw channel access
		and for associate parameters such as offsets and scales.
	* info->write_raw:
		Raw value writing function. Used for writable device values such
		as DAC values and caliboffset.
	* info->read_event_config:
		Typically only set if there are some interrupt lines.  This
		is used to read if an on sensor event detector is enabled.
	* info->write_event_config:
		Enable / disable an on sensor event detector.
	* info->read_event_value:
		Read value associated with on sensor event detectors. Note that
		the meaning of the returned value is dependent on the event
		type.
	* info->write_event_value:
		Write the value associated with on sensor event detectors. E.g.
		a threshold above which an interrupt occurs.  Note that the
		meaning of the value to be set is event type dependant.

- indio_dev->modes:
	Specify whether direct access and / or ring buffer access is supported.
- indio_dev->ring:
	An optional associated buffer.
- indio_dev->pollfunc:
	Poll function related elements. This controls what occurs when a trigger
	to which this device is attached sends an event.
- indio_dev->channels:
	Specification of device channels. Most attributes etc are built
	form this spec.
- indio_dev->num_channels:
	How many channels are there?

Once these are set up, a call to iio_device_register(indio_dev),
will register the device with the iio core.

Worth noting here is that, if a ring buffer is to be used, it can be
allocated prior to registering the device with the iio-core, but must
be registered afterwards (otherwise the whole parentage of devices
gets confused)

On remove, iio_device_unregister(indio_dev) will remove the device from
the core, and iio_device_free will clean up.