Staging: IIO: Add generic ring buffer support to the IIO core

This provides a unified interface for hardware and software
ring buffers.

Changes since V2:
* Moved to a more consistent structure.  Now the ring buffer
  has an associated struct device which is a child of the
  relevant iio_dev.  This in turn has two children, one
  for the event interface and one for the access interface.
  These two interfaces are now managed via cdev structures.

* Numerous minor cleanups

Signed-off-by: Jonathan Cameron <jic23@cam.ac.uk>
Signed-off-by: Greg Kroah-Hartman <gregkh@suse.de>

4 files changed, 858 insertions, 0 deletions

diff --git a/drivers/staging/iio/Kconfig b/drivers/staging/iio/Kconfig
index 309eb38ba391..e554a9e0bf7e 100644
--- a/drivers/staging/iio/Kconfig
+++ b/drivers/staging/iio/Kconfig
@@ -11,6 +11,12 @@ menuconfig IIO
 	  Documentation/industrialio for more information.
 if IIO
 
+config IIO_RING_BUFFER
+	bool "Enable ring buffer support within IIO"
+	help
+	  Provide core support for various ring buffer based data
+	  acquisition methods.
+
 source "drivers/staging/iio/accel/Kconfig"
 source "drivers/staging/iio/adc/Kconfig"
 source "drivers/staging/iio/light/Kconfig"
diff --git a/drivers/staging/iio/Makefile b/drivers/staging/iio/Makefile
index 14c661b339db..670b8f33c02e 100644
--- a/drivers/staging/iio/Makefile
+++ b/drivers/staging/iio/Makefile
@@ -4,6 +4,7 @@
 
 obj-$(CONFIG_IIO) += industrialio.o
 industrialio-y := industrialio-core.o
+industrialio-$(CONFIG_IIO_RING_BUFFER) += industrialio-ring.o
 
 obj-y += accel/
 obj-y += adc/
diff --git a/drivers/staging/iio/industrialio-ring.c b/drivers/staging/iio/industrialio-ring.c
new file mode 100644
index 000000000000..ebe5cccb4034
--- /dev/null
+++ b/drivers/staging/iio/industrialio-ring.c
@@ -0,0 +1,568 @@
+/* The industrial I/O core
+ *
+ * Copyright (c) 2008 Jonathan Cameron
+ *
+ * This program is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License version 2 as published by
+ * the Free Software Foundation.
+ *
+ * Handling of ring allocation / resizing.
+ *
+ *
+ * Things to look at here.
+ * - Better memory allocation techniques?
+ * - Alternative access techniques?
+ */
+#include <linux/kernel.h>
+#include <linux/device.h>
+#include <linux/interrupt.h>
+#include <linux/fs.h>
+#include <linux/poll.h>
+#include <linux/module.h>
+#include <linux/cdev.h>
+#include <linux/idr.h>
+
+#include "iio.h"
+#include "ring_generic.h"
+
+/* IDR for ring buffer identifier */
+static DEFINE_IDR(iio_ring_idr);
+/* IDR for ring event identifier */
+static DEFINE_IDR(iio_ring_event_idr);
+/* IDR for ring access identifier */
+static DEFINE_IDR(iio_ring_access_idr);
+
+int iio_push_ring_event(struct iio_ring_buffer *ring_buf,
+		       int event_code,
+		       s64 timestamp)
+{
+	return __iio_push_event(&ring_buf->ev_int,
+			       event_code,
+			       timestamp,
+			       &ring_buf->shared_ev_pointer);
+}
+EXPORT_SYMBOL(iio_push_ring_event);
+
+int iio_push_or_escallate_ring_event(struct iio_ring_buffer *ring_buf,
+				    int event_code,
+				    s64 timestamp)
+{
+	if (ring_buf->shared_ev_pointer.ev_p)
+		__iio_change_event(ring_buf->shared_ev_pointer.ev_p,
+				   event_code,
+				   timestamp);
+	else
+		return iio_push_ring_event(ring_buf,
+					  event_code,
+					  timestamp);
+	return 0;
+}
+EXPORT_SYMBOL(iio_push_or_escallate_ring_event);
+
+/**
+ * iio_ring_open() chrdev file open for ring buffer access
+ *
+ * This function relies on all ring buffer implementations having an
+ * iio_ring_buffer as their first element.
+ **/
+int iio_ring_open(struct inode *inode, struct file *filp)
+{
+	struct iio_handler *hand
+		= container_of(inode->i_cdev, struct iio_handler, chrdev);
+	struct iio_ring_buffer *rb = hand->private;
+
+	filp->private_data = hand->private;
+	if (rb->access.mark_in_use)
+		rb->access.mark_in_use(rb);
+
+	return 0;
+}
+
+/**
+ * iio_ring_release() -chrdev file close ring buffer access
+ *
+ * This function relies on all ring buffer implementations having an
+ * iio_ring_buffer as their first element.
+ **/
+int iio_ring_release(struct inode *inode, struct file *filp)
+{
+	struct cdev *cd = inode->i_cdev;
+	struct iio_handler *hand = iio_cdev_to_handler(cd);
+	struct iio_ring_buffer *rb = hand->private;
+
+	clear_bit(IIO_BUSY_BIT_POS, &rb->access_handler.flags);
+	if (rb->access.unmark_in_use)
+		rb->access.unmark_in_use(rb);
+
+	return 0;
+}
+
+/**
+ * iio_ring_rip_outer() chrdev read for ring buffer access
+ *
+ * This function relies on all ring buffer implementations having an
+ * iio_ring _bufer as their first element.
+ **/
+ssize_t iio_ring_rip_outer(struct file *filp,
+			   char *buf,
+			   size_t count,
+			   loff_t *f_ps)
+{
+	struct iio_ring_buffer *rb = filp->private_data;
+	int ret, dead_offset, copied;
+	u8 *data;
+	/* rip lots must exist. */
+	if (!rb->access.rip_lots)
+		return -EINVAL;
+	copied = rb->access.rip_lots(rb, count, &data, &dead_offset);
+
+	if (copied < 0) {
+		ret = copied;
+		goto error_ret;
+	}
+	if (copy_to_user(buf, data + dead_offset, copied))  {
+		ret =  -EFAULT;
+		goto error_free_data_cpy;
+	}
+	/* In clever ring buffer designs this may not need to be freed.
+	 * When such a design exists I'll add this to ring access funcs.
+	 */
+	kfree(data);
+
+	return copied;
+
+error_free_data_cpy:
+	kfree(data);
+error_ret:
+	return ret;
+}
+
+static const struct file_operations iio_ring_fileops = {
+	.read = iio_ring_rip_outer,
+	.release = iio_ring_release,
+	.open = iio_ring_open,
+	.owner = THIS_MODULE,
+};
+
+/**
+ * __iio_request_ring_buffer_event_chrdev() allocate ring event chrdev
+ * @buf:	ring buffer whose event chrdev we are allocating
+ * @owner:	the module who owns the ring buffer (for ref counting)
+ * @dev:	device with which the chrdev is associated
+ **/
+static inline int
+__iio_request_ring_buffer_event_chrdev(struct iio_ring_buffer *buf,
+				       int id,
+				       struct module *owner,
+				       struct device *dev)
+{
+	int ret;
+	ret = iio_get_new_idr_val(&iio_ring_event_idr);
+	if (ret < 0)
+		goto error_ret;
+	else
+		buf->ev_int.id = ret;
+
+	snprintf(buf->ev_int._name, 20,
+		 "ring_event_line%d",
+		 buf->ev_int.id);
+	ret = iio_setup_ev_int(&(buf->ev_int),
+			       buf->ev_int._name,
+			       owner,
+			       dev);
+	if (ret)
+		goto error_free_id;
+	return 0;
+
+error_free_id:
+	iio_free_idr_val(&iio_ring_event_idr, buf->ev_int.id);
+error_ret:
+	return ret;
+}
+
+static inline void
+__iio_free_ring_buffer_event_chrdev(struct iio_ring_buffer *buf)
+{
+	iio_free_ev_int(&(buf->ev_int));
+	iio_free_idr_val(&iio_ring_event_idr, buf->ev_int.id);
+}
+
+static void iio_ring_access_release(struct device *dev)
+{
+	struct iio_ring_buffer *buf
+		= access_dev_to_iio_ring_buffer(dev);
+	cdev_del(&buf->access_handler.chrdev);
+	iio_device_free_chrdev_minor(MINOR(dev->devt));
+}
+
+static struct device_type iio_ring_access_type = {
+	.release = iio_ring_access_release,
+};
+
+static inline int
+__iio_request_ring_buffer_access_chrdev(struct iio_ring_buffer *buf,
+					int id,
+					struct module *owner)
+{
+	int ret, minor;
+
+	buf->access_handler.flags = 0;
+
+	buf->access_dev.parent = &buf->dev;
+	buf->access_dev.class = &iio_class;
+	buf->access_dev.type = &iio_ring_access_type;
+	device_initialize(&buf->access_dev);
+
+	minor = iio_device_get_chrdev_minor();
+	if (minor < 0) {
+		ret = minor;
+		goto error_device_put;
+	}
+	buf->access_dev.devt = MKDEV(MAJOR(iio_devt), minor);
+
+	ret = iio_get_new_idr_val(&iio_ring_access_idr);
+	if (ret < 0)
+		goto error_device_put;
+	else
+		buf->access_id = ret;
+	dev_set_name(&buf->access_dev, "ring_access%d", buf->access_id);
+	ret = device_add(&buf->access_dev);
+	if (ret < 0) {
+		printk(KERN_ERR "failed to add the ring access dev\n");
+		goto error_free_idr;
+	}
+
+	cdev_init(&buf->access_handler.chrdev, &iio_ring_fileops);
+	buf->access_handler.chrdev.owner = owner;
+
+	ret = cdev_add(&buf->access_handler.chrdev, buf->access_dev.devt, 1);
+	if (ret) {
+		printk(KERN_ERR "failed to allocate ring access chrdev\n");
+		goto error_device_unregister;
+	}
+	return 0;
+error_device_unregister:
+	device_unregister(&buf->access_dev);
+error_free_idr:
+	iio_free_idr_val(&iio_ring_access_idr, buf->access_id);
+error_device_put:
+	put_device(&buf->access_dev);
+
+	return ret;
+}
+
+static void __iio_free_ring_buffer_access_chrdev(struct iio_ring_buffer *buf)
+{
+	iio_free_idr_val(&iio_ring_access_idr, buf->access_id);
+	device_unregister(&buf->access_dev);
+}
+
+void iio_ring_buffer_init(struct iio_ring_buffer *ring,
+			  struct iio_dev *dev_info)
+{
+	if (ring->access.mark_param_change)
+		ring->access.mark_param_change(ring);
+	ring->indio_dev = dev_info;
+	ring->ev_int.private = ring;
+	ring->access_handler.private = ring;
+}
+EXPORT_SYMBOL(iio_ring_buffer_init);
+
+int iio_ring_buffer_register(struct iio_ring_buffer *ring)
+{
+	int ret;
+	ret = iio_get_new_idr_val(&iio_ring_idr);
+	if (ret < 0)
+		goto error_ret;
+	else
+		ring->id = ret;
+
+	dev_set_name(&ring->dev, "ring_buffer%d", ring->id);
+	ret = device_add(&ring->dev);
+	if (ret)
+		goto error_free_id;
+
+	ret = __iio_request_ring_buffer_event_chrdev(ring,
+						     0,
+						     ring->owner,
+						     &ring->dev);
+	if (ret)
+		goto error_remove_device;
+
+	ret = __iio_request_ring_buffer_access_chrdev(ring,
+						      0,
+						      ring->owner);
+
+	if (ret)
+		goto error_free_ring_buffer_event_chrdev;
+
+	return ret;
+error_free_ring_buffer_event_chrdev:
+	__iio_free_ring_buffer_event_chrdev(ring);
+error_remove_device:
+	device_del(&ring->dev);
+error_free_id:
+	iio_free_idr_val(&iio_ring_idr, ring->id);
+error_ret:
+	return ret;
+}
+EXPORT_SYMBOL(iio_ring_buffer_register);
+
+void iio_ring_buffer_unregister(struct iio_ring_buffer *ring)
+{
+	__iio_free_ring_buffer_access_chrdev(ring);
+	__iio_free_ring_buffer_event_chrdev(ring);
+	device_del(&ring->dev);
+	iio_free_idr_val(&iio_ring_idr, ring->id);
+}
+EXPORT_SYMBOL(iio_ring_buffer_unregister);
+
+ssize_t iio_read_ring_length(struct device *dev,
+			     struct device_attribute *attr,
+			     char *buf)
+{
+	int len = 0;
+	struct iio_ring_buffer *ring = dev_get_drvdata(dev);
+
+	if (ring->access.get_length)
+		len = sprintf(buf, "%d\n",
+			      ring->access.get_length(ring));
+
+	return len;
+}
+EXPORT_SYMBOL(iio_read_ring_length);
+
+ ssize_t iio_write_ring_length(struct device *dev,
+			       struct device_attribute *attr,
+			       const char *buf,
+			       size_t len)
+{
+	int ret;
+	ulong val;
+	struct iio_ring_buffer *ring = dev_get_drvdata(dev);
+	ret = strict_strtoul(buf, 10, &val);
+	if (ret)
+		return ret;
+
+	if (ring->access.get_length)
+		if (val == ring->access.get_length(ring))
+			return len;
+
+	if (ring->access.set_length) {
+		ring->access.set_length(ring, val);
+		if (ring->access.mark_param_change)
+			ring->access.mark_param_change(ring);
+	}
+
+	return len;
+}
+EXPORT_SYMBOL(iio_write_ring_length);
+
+ssize_t iio_read_ring_bps(struct device *dev,
+			  struct device_attribute *attr,
+			  char *buf)
+{
+	int len = 0;
+	struct iio_ring_buffer *ring = dev_get_drvdata(dev);
+
+	if (ring->access.get_bpd)
+		len = sprintf(buf, "%d\n",
+			      ring->access.get_bpd(ring));
+
+	return len;
+}
+EXPORT_SYMBOL(iio_read_ring_bps);
+
+ssize_t iio_store_ring_enable(struct device *dev,
+			      struct device_attribute *attr,
+			      const char *buf,
+			      size_t len)
+{
+	int ret;
+	bool requested_state, current_state;
+	int previous_mode;
+	struct iio_ring_buffer *ring = dev_get_drvdata(dev);
+	struct iio_dev *dev_info = ring->indio_dev;
+
+	mutex_lock(&dev_info->mlock);
+	previous_mode = dev_info->currentmode;
+	requested_state = !(buf[0] == '0');
+	current_state = !!(previous_mode & INDIO_ALL_RING_MODES);
+	if (current_state == requested_state) {
+		printk(KERN_INFO "iio-ring, current state requested again\n");
+		goto done;
+	}
+	if (requested_state) {
+		if (ring->preenable) {
+			ret = ring->preenable(dev_info);
+			if (ret) {
+				printk(KERN_ERR
+				       "Buffer not started:"
+				       "ring preenable failed\n");
+				goto error_ret;
+			}
+		}
+		if (ring->access.request_update) {
+			ret = ring->access.request_update(ring);
+			if (ret) {
+				printk(KERN_INFO
+				       "Buffer not started:"
+				       "ring parameter update failed\n");
+				goto error_ret;
+			}
+		}
+		if (ring->access.mark_in_use)
+			ring->access.mark_in_use(ring);
+		/* Definitely possible for devices to support both of these.*/
+		if (dev_info->modes & INDIO_RING_TRIGGERED) {
+			if (!dev_info->trig) {
+				printk(KERN_INFO
+				       "Buffer not started: no trigger\n");
+				ret = -EINVAL;
+				if (ring->access.unmark_in_use)
+					ring->access.unmark_in_use(ring);
+				goto error_ret;
+			}
+			dev_info->currentmode = INDIO_RING_TRIGGERED;
+		} else if (dev_info->modes & INDIO_RING_HARDWARE_BUFFER)
+			dev_info->currentmode = INDIO_RING_HARDWARE_BUFFER;
+		else { /* should never be reached */
+			ret = -EINVAL;
+			goto error_ret;
+		}
+
+		if (ring->postenable) {
+
+			ret = ring->postenable(dev_info);
+			if (ret) {
+				printk(KERN_INFO
+				       "Buffer not started:"
+				       "postenable failed\n");
+				if (ring->access.unmark_in_use)
+					ring->access.unmark_in_use(ring);
+				dev_info->currentmode = previous_mode;
+				if (ring->postdisable)
+					ring->postdisable(dev_info);
+				goto error_ret;
+			}
+		}
+	} else {
+		if (ring->predisable) {
+			ret = ring->predisable(dev_info);
+			if (ret)
+				goto error_ret;
+		}
+		if (ring->access.unmark_in_use)
+			ring->access.unmark_in_use(ring);
+		dev_info->currentmode = INDIO_DIRECT_MODE;
+		if (ring->postdisable) {
+			ret = ring->postdisable(dev_info);
+			if (ret)
+				goto error_ret;
+		}
+	}
+done:
+	mutex_unlock(&dev_info->mlock);
+	return len;
+
+error_ret:
+	mutex_unlock(&dev_info->mlock);
+	return ret;
+}
+EXPORT_SYMBOL(iio_store_ring_enable);
+ssize_t iio_show_ring_enable(struct device *dev,
+				    struct device_attribute *attr,
+				    char *buf)
+{
+	struct iio_ring_buffer *ring = dev_get_drvdata(dev);
+	return sprintf(buf, "%d\n", !!(ring->indio_dev->currentmode
+				       & INDIO_ALL_RING_MODES));
+}
+EXPORT_SYMBOL(iio_show_ring_enable);
+
+ssize_t iio_scan_el_show(struct device *dev,
+			 struct device_attribute *attr,
+			 char *buf)
+{
+	int ret;
+	struct iio_dev *indio_dev = dev_get_drvdata(dev);
+	struct iio_scan_el *this_el = to_iio_scan_el(attr);
+
+	ret = iio_scan_mask_query(indio_dev, this_el->number);
+	if (ret < 0)
+		return ret;
+	return sprintf(buf, "%d\n", ret);
+}
+EXPORT_SYMBOL(iio_scan_el_show);
+
+ssize_t iio_scan_el_store(struct device *dev,
+			  struct device_attribute *attr,
+			  const char *buf,
+			  size_t len)
+{
+	int ret = 0;
+	bool state;
+	struct iio_dev *indio_dev = dev_get_drvdata(dev);
+	struct iio_scan_el *this_el = to_iio_scan_el(attr);
+
+	state = !(buf[0] == '0');
+	mutex_lock(&indio_dev->mlock);
+	if (indio_dev->currentmode == INDIO_RING_TRIGGERED) {
+		ret = -EBUSY;
+		goto error_ret;
+	}
+	ret = iio_scan_mask_query(indio_dev, this_el->number);
+	if (ret < 0)
+		goto error_ret;
+	if (!state && ret) {
+		ret = iio_scan_mask_clear(indio_dev, this_el->number);
+		if (ret)
+			goto error_ret;
+		indio_dev->scan_count--;
+	} else if (state && !ret) {
+		ret = iio_scan_mask_set(indio_dev, this_el->number);
+		if (ret)
+			goto error_ret;
+		indio_dev->scan_count++;
+	}
+	if (this_el->set_state)
+		ret = this_el->set_state(this_el, indio_dev, state);
+error_ret:
+	mutex_unlock(&indio_dev->mlock);
+
+	return ret ? ret : len;
+
+}
+EXPORT_SYMBOL(iio_scan_el_store);
+
+ssize_t iio_scan_el_ts_show(struct device *dev,
+			    struct device_attribute *attr,
+			    char *buf)
+{
+	struct iio_dev *indio_dev = dev_get_drvdata(dev);
+	return sprintf(buf, "%d\n", indio_dev->scan_timestamp);
+}
+EXPORT_SYMBOL(iio_scan_el_ts_show);
+
+ssize_t iio_scan_el_ts_store(struct device *dev,
+			     struct device_attribute *attr,
+			     const char *buf,
+			     size_t len)
+{
+	int ret = 0;
+	struct iio_dev *indio_dev = dev_get_drvdata(dev);
+	bool state;
+	state = !(buf[0] == '0');
+	mutex_lock(&indio_dev->mlock);
+	if (indio_dev->currentmode == INDIO_RING_TRIGGERED) {
+		ret = -EBUSY;
+		goto error_ret;
+	}
+	indio_dev->scan_timestamp = state;
+error_ret:
+	mutex_unlock(&indio_dev->mlock);
+
+	return ret ? ret : len;
+}
+EXPORT_SYMBOL(iio_scan_el_ts_store);
+
diff --git a/drivers/staging/iio/ring_generic.h b/drivers/staging/iio/ring_generic.h
new file mode 100644
index 000000000000..d9261897f332
--- /dev/null
+++ b/drivers/staging/iio/ring_generic.h
@@ -0,0 +1,283 @@
+/* The industrial I/O core - generic ring buffer interfaces.
+ *
+ * Copyright (c) 2008 Jonathan Cameron
+ *
+ * This program is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License version 2 as published by
+ * the Free Software Foundation.
+ */
+
+#ifndef _IIO_RING_GENERIC_H_
+#define _IIO_RING_GENERIC_H_
+#include "iio.h"
+
+struct iio_handler;
+struct iio_ring_buffer;
+struct iio_dev;
+
+/**
+ * iio_push_ring_event() - ring buffer specific push to event chrdev
+ * @ring_buf:		ring buffer that is the event source
+ * @event_code:		event indentification code
+ * @timestamp:		time of event
+ **/
+int iio_push_ring_event(struct iio_ring_buffer *ring_buf,
+			int event_code,
+			s64 timestamp);
+/**
+ * iio_push_or_escallate_ring_event() -	escallate or add as appropriate
+ *
+ * Typical usecase is to escallate a 50% ring full to 75% full if noone has yet
+ * read the first event. Clearly the 50% full is no longer of interest in
+ * typical use case.
+ **/
+int iio_push_or_escallate_ring_event(struct iio_ring_buffer *ring_buf,
+				     int event_code,
+				     s64 timestamp);
+
+/**
+ * struct iio_ring_access_funcs - access functions for ring buffers.
+ * @create:		perform allocation
+ * @init:		get ring buffer ready for use
+ * @_exit:		reverse steps in init
+ * @_free:		deallocate ring buffer
+ * @mark_in_use:	reference counting, typically to prevent module removal
+ * @unmark_in_use:	reduce reference count when no longer using ring buffer
+ * @store_to:		actually store stuff to the ring buffer
+ * @read_last:		get the last element stored
+ * @rip_lots:		try to get a specified number of elements (must exist)
+ * @mark_param_change:	notify ring that some relevant parameter has changed
+ *			Often this means the underlying storage may need to
+ *			change.
+ * @request_update:	if a parameter change has been marked, update underlying
+ *			storage.
+ * @get_bpd:		get current bytes per datum
+ * @set_bpd:		set number of bytes per datum
+ * @get_length:		get number of datums in ring
+ * @set_length:		set number of datums in ring
+ * @is_enabled:		query if ring is currently being used
+ * @enable:		enable the ring
+ *
+ * The purpose of this structure is to make the ring buffer element
+ * modular as event for a given driver, different usecases may require
+ * different ring designs (space efficiency vs speed for example.
+ *
+ * It is worth noting that a given ring implementation may only support a small
+ * proportion of these functions.  The core code 'should' cope fine with any of
+ * them not existing.
+ **/
+struct iio_ring_access_funcs {
+	void (*mark_in_use)(struct iio_ring_buffer *ring);
+	void (*unmark_in_use)(struct iio_ring_buffer *ring);
+
+	int (*store_to)(struct iio_ring_buffer *ring, u8 *data, s64 timestamp);
+	int (*read_last)(struct iio_ring_buffer *ring, u8 *data);
+	int (*rip_lots)(struct iio_ring_buffer *ring,
+			size_t count,
+			u8 **data,
+			int *dead_offset);
+
+	int (*mark_param_change)(struct iio_ring_buffer *ring);
+	int (*request_update)(struct iio_ring_buffer *ring);
+
+	int (*get_bpd)(struct iio_ring_buffer *ring);
+	int (*set_bpd)(struct iio_ring_buffer *ring, size_t bpd);
+	int (*get_length)(struct iio_ring_buffer *ring);
+	int (*set_length)(struct iio_ring_buffer *ring, int length);
+
+	int (*is_enabled)(struct iio_ring_buffer *ring);
+	int (*enable)(struct iio_ring_buffer *ring);
+};
+
+/**
+ * struct iio_ring_buffer - general ring buffer structure
+ * @length:		[DEVICE]number of datums in ring
+ * @bpd:		[DEVICE]size of individual datum including timestamp
+ * @loopcount:		[INTERN]number of times the ring has looped
+ * @access_minor_name:	[INTERN]store of name of the access chrdev minor number
+ *			sysfs attribute
+ * @access_handler:	[INTERN]chrdev access handling
+ * @event_minor_name:	[INTERN]store of name of the event chrdev minor number
+ *			sysfs attribute
+ * @ev_int:		[INTERN]chrdev interface for the event chrdev
+ * @shared_ev_pointer:	[INTERN]the shared event pointer to allow escalation of
+ *			events
+ * @ring_access:	[DRIVER]ring access functions associated with the
+ *			implementation.
+ * @ring_prenable:	[DRIVER] function to run prior to marking ring enabled
+ * @ring_postenable:	[DRIVER] function to run after marking ring enabled
+ * @ring_predisable:	[DRIVER] function to run prior to marking ring disabled
+ * @ring_postdisable:	[DRIVER] function to run after marking ring disabled
+  **/
+struct iio_ring_buffer {
+	struct device dev;
+	struct device access_dev;
+	struct iio_dev *indio_dev;
+	struct module *owner;
+	int				id;
+	int				access_id;
+	int				length;
+	int				bpd;
+	int				loopcount;
+	struct iio_handler		access_handler;
+	struct iio_event_interface	ev_int;
+	struct iio_shared_ev_pointer	shared_ev_pointer;
+	struct iio_ring_access_funcs	access;
+	int				(*preenable)(struct iio_dev *);
+	int				(*postenable)(struct iio_dev *);
+	int				(*predisable)(struct iio_dev *);
+	int				(*postdisable)(struct iio_dev *);
+
+};
+void iio_ring_buffer_init(struct iio_ring_buffer *ring,
+			  struct iio_dev *dev_info);
+
+/**
+ * __iio_init_ring_buffer() - initialize common elements of ring buffers.
+ **/
+static inline void __iio_init_ring_buffer(struct iio_ring_buffer *ring,
+				 int bytes_per_datum, int length)
+{
+	ring->bpd = bytes_per_datum;
+	ring->length = length;
+	ring->loopcount = 0;
+	ring->shared_ev_pointer.ev_p = 0;
+	ring->shared_ev_pointer.lock =
+		__SPIN_LOCK_UNLOCKED(ring->shared_ev_pointer->loc);
+}
+
+/**
+ * struct iio_scan_el - an individual element of a scan
+ * @dev_attr:		control attribute (if directly controllable)
+ * @number:		unique identifier of element (used for bit mask)
+ * @bit_count:		number of bits in scan element
+ * @label:		useful data for the scan el (often reg address)
+ * @set_state:		for some devices datardy signals are generated
+ *			for any enabled lines.  This allows unwanted lines
+ *			to be disabled and hence not get in the way.
+ **/
+struct iio_scan_el {
+	struct device_attribute		dev_attr;
+	unsigned int			number;
+	int				bit_count;
+	unsigned int			label;
+
+	int (*set_state)(struct iio_scan_el *scanel,
+			 struct iio_dev *dev_info,
+			 bool state);
+};
+
+#define to_iio_scan_el(_dev_attr)				\
+	container_of(_dev_attr, struct iio_scan_el, dev_attr);
+
+/**
+ * iio_scan_el_store() - sysfs scan element selection interface.
+ *
+ * A generic function used to enable various scan elements.  In some
+ * devices explicit read commands for each channel mean this is merely
+ * a software switch.  In others this must actively disable the channel.
+ * Complexities occur when this interacts with data ready type triggers
+ * which may not reset unless every channel that is enabled is explicitly
+ * read.
+ **/
+ssize_t iio_scan_el_store(struct device *dev, struct device_attribute *attr,
+			  const char *buf, size_t len);
+/**
+ * iio_scal_el_show() -	sysfs interface to query whether a scan element is
+ *			is enabled or not.
+ **/
+ssize_t iio_scan_el_show(struct device *dev, struct device_attribute *attr,
+			 char *buf);
+/**
+ * IIO_SCAN_EL: - declare and initialize a scan element without control func
+ * @_name:	identifying name. Resulting struct is iio_scan_el_##_name,
+ *		sysfs element, scan_en_##_name.
+ * @_number:	unique id number for the scan element.
+ * @_bits:	number of bits in the scan element result (used in mixed bit
+ *		length devices).
+ * @_label:	indentification variable used by drivers.  Often a reg address.
+ **/
+#define IIO_SCAN_EL(_name, _number, _bits, _label)			\
+	struct iio_scan_el iio_scan_el_##_name = {			\
+		.dev_attr = __ATTR(scan_en_##_name,			\
+				   S_IRUGO | S_IWUSR,			\
+				   iio_scan_el_show,			\
+				   iio_scan_el_store),			\
+		.mask = (1 << _number),					\
+		.bit_count = _bits,					\
+		.label = _label,					\
+	}
+
+ssize_t iio_scan_el_ts_store(struct device *dev, struct device_attribute *attr,
+			     const char *buf, size_t len);
+
+ssize_t iio_scan_el_ts_show(struct device *dev, struct device_attribute *attr,
+			    char *buf);
+/**
+ * IIO_SCAN_EL_C: - declare and initialize a scan element with a control func
+ *
+ * @_controlfunc: function used to notify hardware of whether state changes
+ **/
+#define IIO_SCAN_EL_C(_name, _number, _bits, _label, _controlfunc)	\
+	struct iio_scan_el iio_scan_el_##_name = {			\
+		.dev_attr = __ATTR(scan_en_##_name,			\
+				   S_IRUGO | S_IWUSR,			\
+				   iio_scan_el_show,			\
+				   iio_scan_el_store),			\
+		.number =  _number,					\
+		.bit_count = _bits,					\
+		.label = _label,					\
+		.set_state = _controlfunc,				\
+	}
+/**
+ * IIO_SCAN_EL_TIMESTAMP: - declare a special scan element for timestamps
+ *
+ * Odd one out. Handled slightly differently from other scan elements.
+ **/
+#define IIO_SCAN_EL_TIMESTAMP					\
+	struct iio_scan_el iio_scan_el_timestamp = {		\
+		.dev_attr = __ATTR(scan_en_timestamp,		\
+				   S_IRUGO | S_IWUSR,		\
+				   iio_scan_el_ts_show,		\
+				   iio_scan_el_ts_store),	\
+	}
+
+static inline void iio_put_ring_buffer(struct iio_ring_buffer *ring)
+{
+	put_device(&ring->dev);
+};
+
+#define to_iio_ring_buffer(d)			\
+	container_of(d, struct iio_ring_buffer, dev)
+#define access_dev_to_iio_ring_buffer(d)			\
+	container_of(d, struct iio_ring_buffer, access_dev)
+int iio_ring_buffer_register(struct iio_ring_buffer *ring);
+void iio_ring_buffer_unregister(struct iio_ring_buffer *ring);
+
+ssize_t iio_read_ring_length(struct device *dev,
+			     struct device_attribute *attr,
+			     char *buf);
+ssize_t iio_write_ring_length(struct device *dev,
+			      struct device_attribute *attr,
+			      const char *buf,
+			      size_t len);
+ssize_t iio_read_ring_bps(struct device *dev,
+			  struct device_attribute *attr,
+			  char *buf);
+ssize_t iio_store_ring_enable(struct device *dev,
+			      struct device_attribute *attr,
+			      const char *buf,
+			      size_t len);
+ssize_t iio_show_ring_enable(struct device *dev,
+			     struct device_attribute *attr,
+			     char *buf);
+#define IIO_RING_LENGTH_ATTR DEVICE_ATTR(length, S_IRUGO | S_IWUSR,	\
+					 iio_read_ring_length,		\
+					 iio_write_ring_length)
+#define IIO_RING_BPS_ATTR DEVICE_ATTR(bps, S_IRUGO | S_IWUSR,	\
+				      iio_read_ring_bps, NULL)
+#define IIO_RING_ENABLE_ATTR DEVICE_ATTR(ring_enable, S_IRUGO | S_IWUSR, \
+					 iio_show_ring_enable,		\
+					 iio_store_ring_enable)
+
+#endif /* _IIO_RING_GENERIC_H_ */