drivers/staging/iio/Documentation/ring.txt

   1 Buffer support within IIO
   2
   3 This document is intended as a general overview of the functionality
   4 a buffer may supply and how it is specified within IIO.  For more
   5 specific information on a given buffer implementation, see the
   6 comments in the source code.  Note that some drivers allow buffer
   7 implementation to be selected at compile time via Kconfig options.
   8
   9 A given buffer implementation typically embeds a struct
  10 iio_ring_buffer and it is a pointer to this that is provided to the
  11 IIO core. Access to the embedding structure is typically done via
  12 container_of functions.
  13
  14 struct iio_ring_buffer contains a struct iio_ring_setup_ops *setup_ops
  15 which in turn contains the 4 function pointers
  16 (preenable, postenable, predisable and postdisable).
  17 These are used to perform device specific steps on either side
  18 of the core changing it's current mode to indicate that the 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 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 buffer state that
  28   will effect the form of the data being captures (e.g. scan elements or length)
  29
  30 store_to
  31   If possible, push data to the buffer.
  32
  33 read_last
  34   If possible, get the most recent scan from the buffer (without removal).
  35   This provides polling like functionality whilst the ring buffering is in
  36   use without a separate read from the device.
  37
  38 rip_first_n
  39   The primary buffer reading function. Note that it may well not return
  40   as much data as requested.
  41
  42 mark_param_changed
  43   Used to indicate that something has changed. Used in conjunction with
  44 request_update
  45   If parameters have changed that require reinitialization or configuration of
  46   the buffer this will trigger it.
  47
  48 get_bytes_per_datum, set_bytes_per_datum
  49   Get/set the number of bytes for a complete scan. (All samples + timestamp)
  50
  51 get_length / set_length
  52   Get/set the number of complete scans that may be held by the buffer.
  53
  54 is_enabled
  55   Query if ring buffer is in use
  56 enable
  57   Start the ring buffer.