drivers/staging/iio/Documentation/ring.txt

   1 Ring buffer support within IIO
   2
   3 This document is intended as a general overview of the functionality
   4 a ring buffer may supply and how it is specified within IIO.  For more
   5 specific information on a given ring buffer implementation, see the
   6 comments in the source code.  Note that the intention is to allow
   7 some drivers to specify ring buffers choice at probe or runtime, but
   8 for now the selection is hard coded within a given driver.
   9
  10 A given ring buffer implementation typically embedded a struct
  11 iio_ring_buffer and it is a pointer to this that is provided to the
  12 IIO core. Access to the embedding structure is typically done via
  13 container_of functions.
  14
  15 struct iio_ring_buffer contains 4 function pointers
  16 (preenable, postenable, predisable, postdisable).
  17 These are used to perform implementation specific steps on either side
  18 of the core changing it's current mode to indicate that the ring buffer
  19 is enabled or disabled (along with enabling triggering etc as appropriate).
  20
  21 Also in struct iio_ring_buffer is a struct iio_ring_access_funcs.
  22 The function pointers within here are used to allow the core to handle
  23 as much ring buffer functionality as possible. Note almost all of these
  24 are optional.
  25
  26 mark_in_use, unmark_in_use
  27   Basically indicate that not changes should be made to the ring
  28   buffer state that will effect the form of the data being captures
  29   (e.g. scan elements or length)
  30
  31 store_to
  32   If possible, push data to ring buffer.
  33
  34 read_last
  35   If possible get the most recent entry from the buffer (without removal).
  36   This provides polling like functionality whilst the ring buffering is in
  37   use without a separate read from the device.
  38
  39 rip_lots
  40   The primary ring buffer reading function. Note that it may well not return
  41   as much data as requested.  The deadoffset is used to indicate that some
  42   initial data in the data array is not guaranteed to be valid.
  43
  44 mark_param_changed
  45   Used to indicate that something has changed. Used in conjunction with
  46 request_update
  47   If parameters have changed that require reinitialization or configuration of
  48   the ring buffer this will trigger it.
  49
  50 get_bpd, set_bpd
  51   Get/set the number of bytes for a given reading (single element, not sample set)
  52   The value of bps (bytes per set) is created from a combination of this and the
  53   enabled scan elements.
  54
  55 get_length / set_length
  56   Get/set the number of sample sets that may be held by the buffer.
  57
  58 is_enabled
  59   Query if ring buffer is in use
  60 enable
  61   Start the ring buffer.