Staging: IIO: Add generic ring buffer support to the IIO core
authorJonathan Cameron <jic23@cam.ac.uk>
Tue, 18 Aug 2009 17:06:24 +0000 (18:06 +0100)
committerGreg Kroah-Hartman <gregkh@suse.de>
Tue, 15 Sep 2009 19:02:24 +0000 (12:02 -0700)
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>
drivers/staging/iio/Kconfig
drivers/staging/iio/Makefile
drivers/staging/iio/industrialio-ring.c [new file with mode: 0644]
drivers/staging/iio/ring_generic.h [new file with mode: 0644]

index 309eb38ba39137b0ee831865cd6f9f93ec513850..e554a9e0bf7e849810bb5ae595998f796e4a79e7 100644 (file)
@@ -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"
index 14c661b339db713afcc33a63309f52cc98acdf98..670b8f33c02e11c76f7a7ce331a79493f8f7402c 100644 (file)
@@ -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 (file)
index 0000000..ebe5ccc
--- /dev/null
@@ -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 (file)
index 0000000..d926189
--- /dev/null
@@ -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_ */