drivers/staging/iio/ring_sw.h

   1 /* The industrial I/O simple minimally locked ring buffer.
   2  *
   3  * Copyright (c) 2008 Jonathan Cameron
   4  *
   5  * This program is free software; you can redistribute it and/or modify it
   6  * under the terms of the GNU General Public License version 2 as published by
   7  * the Free Software Foundation.
   8  *
   9  * This code is deliberately kept separate from the main industrialio I/O core
  10  * as it is intended that in the future a number of different software ring
  11  * buffer implementations will exist with different characteristics to suit
  12  * different applications.
  13  *
  14  * This particular one was designed for a data capture application where it was
  15  * particularly important that no userspace reads would interrupt the capture
  16  * process. To this end the ring is not locked during a read.
  17  *
  18  * Comments on this buffer design welcomed. It's far from efficient and some of
  19  * my understanding of the effects of scheduling on this are somewhat limited.
  20  * Frankly, to my mind, this is the current weak point in the industrial I/O
  21  * patch set.
  22  */
  23
  24 #ifndef _IIO_RING_SW_H_
  25 #define _IIO_RING_SW_H_
  26 /* NEEDS COMMENTS */
  27 /* The intention is that this should be a separate module from the iio core.
  28  * This is a bit like supporting algorithms dependent on what the device
  29  * driver requests - some may support multiple options */
  30
  31
  32 #include <linux/autoconf.h>
  33 #include "iio.h"
  34 #include "ring_generic.h"
  35
  36 #if defined CONFIG_IIO_SW_RING || defined CONFIG_IIO_SW_RING_MODULE
  37
  38 /**
  39  * iio_create_sw_rb() software ring buffer allocation
  40  * @r:          pointer to ring buffer pointer
  41  **/
  42 int iio_create_sw_rb(struct iio_ring_buffer **r);
  43
  44 /**
  45  * iio_init_sw_rb() initialize the software ring buffer
  46  * @r:          pointer to a software ring buffer created by an
  47  *              iio_create_sw_rb call.
  48  **/
  49 int iio_init_sw_rb(struct iio_ring_buffer *r, struct iio_dev *indio_dev);
  50 /**
  51  * iio_exit_sw_rb() reverse what was done in iio_init_sw_rb
  52  **/
  53 void iio_exit_sw_rb(struct iio_ring_buffer *r);
  54
  55 /**
  56  * iio_free_sw_rb() free memory occupied by the core ring buffer struct
  57  **/
  58 void iio_free_sw_rb(struct iio_ring_buffer *r);
  59
  60 /**
  61  * iio_mark_sw_rb_in_use() reference counting to prevent incorrect chances
  62  **/
  63 void iio_mark_sw_rb_in_use(struct iio_ring_buffer *r);
  64
  65 /**
  66  *  iio_unmark_sw_rb_in_use() notify the ring buffer that we don't care anymore
  67  **/
  68 void iio_unmark_sw_rb_in_use(struct iio_ring_buffer *r);
  69
  70 /**
  71  * iio_read_last_from_sw_rb() attempt to read the last stored datum from the rb
  72  **/
  73 int iio_read_last_from_sw_rb(struct iio_ring_buffer *r, u8 *data);
  74
  75 /**
  76  * iio_store_to_sw_rb() store a new datum to the ring buffer
  77  * @rb: pointer to ring buffer instance
  78  * @data:       the datum to be stored including timestamp if relevant.
  79  * @timestamp:  timestamp which will be attached to buffer events if relevant.
  80  **/
  81 int iio_store_to_sw_rb(struct iio_ring_buffer *r, u8 *data, s64 timestamp);
  82
  83 /**
  84  * iio_rip_sw_rb() attempt to read data from the ring buffer
  85  * @r:                  ring buffer instance
  86  * @count:              number of datum's to try and read
  87  * @data:               where the data will be stored.
  88  * @dead_offset:        how much of the stored data was possibly invalidated by
  89  *                      the end of the copy.
  90  **/
  91 int iio_rip_sw_rb(struct iio_ring_buffer *r,
  92                   size_t count,
  93                   u8 **data,
  94                   int *dead_offset);
  95
  96 /**
  97  * iio_request_update_sw_rb() update params if update needed
  98  **/
  99 int iio_request_update_sw_rb(struct iio_ring_buffer *r);
 100
 101 /**
 102  * iio_mark_update_needed_sw_rb() tell the ring buffer it needs a param update
 103  **/
 104 int iio_mark_update_needed_sw_rb(struct iio_ring_buffer *r);
 105
 106
 107 /**
 108  * iio_get_bpd_sw_rb() get the datum size in bytes
 109  **/
 110 int iio_get_bpd_sw_rb(struct iio_ring_buffer *r);
 111
 112 /**
 113  * iio_set_bpd_sw_rb() set the datum size in bytes
 114  **/
 115 int iio_set_bpd_sw_rb(struct iio_ring_buffer *r, size_t bpd);
 116
 117 /**
 118  * iio_get_length_sw_rb() get how many datums the rb may contain
 119  **/
 120 int iio_get_length_sw_rb(struct iio_ring_buffer *r);
 121
 122 /**
 123  * iio_set_length_sw_rb() set how many datums the rb may contain
 124  **/
 125 int iio_set_length_sw_rb(struct iio_ring_buffer *r, int length);
 126
 127 /**
 128  * iio_ring_sw_register_funcs() helper function to set up rb access
 129  **/
 130 static inline void iio_ring_sw_register_funcs(struct iio_ring_access_funcs *ra)
 131 {
 132         ra->mark_in_use = &iio_mark_sw_rb_in_use;
 133         ra->unmark_in_use = &iio_unmark_sw_rb_in_use;
 134
 135         ra->store_to = &iio_store_to_sw_rb;
 136         ra->read_last = &iio_read_last_from_sw_rb;
 137         ra->rip_lots = &iio_rip_sw_rb;
 138
 139         ra->mark_param_change = &iio_mark_update_needed_sw_rb;
 140         ra->request_update = &iio_request_update_sw_rb;
 141
 142         ra->get_bpd = &iio_get_bpd_sw_rb;
 143         ra->set_bpd = &iio_set_bpd_sw_rb;
 144
 145         ra->get_length = &iio_get_length_sw_rb;
 146         ra->set_length = &iio_set_length_sw_rb;
 147 };
 148
 149 /**
 150  * struct iio_sw_ring_buffer - software ring buffer
 151  * @buf:                generic ring buffer elements
 152  * @data:               the ring buffer memory
 153  * @read_p:             read pointer (oldest available)
 154  * @write_p:            write pointer
 155  * @last_written_p:     read pointer (newest available)
 156  * @half_p:             half buffer length behind write_p (event generation)
 157  * @use_count:          reference count to prevent resizing when in use
 158  * @update_needed:      flag to indicated change in size requested
 159  * @use_lock:           lock to prevent change in size when in use
 160  *
 161  * Note that the first element of all ring buffers must be a
 162  * struct iio_ring_buffer.
 163 **/
 164
 165 struct iio_sw_ring_buffer {
 166         struct iio_ring_buffer  buf;
 167         unsigned char           *data;
 168         unsigned char           *read_p;
 169         unsigned char           *write_p;
 170         unsigned char           *last_written_p;
 171         /* used to act as a point at which to signal an event */
 172         unsigned char           *half_p;
 173         int                     use_count;
 174         int                     update_needed;
 175         spinlock_t              use_lock;
 176 };
 177
 178 #define iio_to_sw_ring(r) container_of(r, struct iio_sw_ring_buffer, buf)
 179
 180 struct iio_ring_buffer *iio_sw_rb_allocate(struct iio_dev *indio_dev);
 181 void iio_sw_rb_free(struct iio_ring_buffer *ring);
 182
 183
 184
 185 #else /* CONFIG_IIO_RING_BUFFER*/
 186 static inline void iio_ring_sw_register_funcs(struct iio_ring_access_funcs *ra)
 187 {};
 188 #endif /* !CONFIG_IIO_RING_BUFFER */
 189 #endif /* _IIO_RING_SW_H_ */