1Ring buffer support within IIO 2 3This document is intended as a general overview of the functionality 4a ring buffer may supply and how it is specified within IIO. For more 5specific information on a given ring buffer implementation, see the 6comments in the source code. Note that the intention is to allow 7some drivers to specify ring buffers choice at probe or runtime, but 8for now the selection is hard coded within a given driver. 9 10A given ring buffer implementation typically embedded a struct 11iio_ring_buffer and it is a pointer to this that is provided to the 12IIO core. Access to the embedding structure is typically done via 13container_of functions. 14 15struct iio_ring_buffer contains 4 function pointers 16(preenable, postenable, predisable, postdisable). 17These are used to perform implementation specific steps on either side 18of the core changing it's current mode to indicate that the ring buffer 19is enabled or disabled (along with enabling triggering etc as appropriate). 20 21Also in struct iio_ring_buffer is a struct iio_ring_access_funcs. 22The function pointers within here are used to allow the core to handle 23as much ring buffer functionality as possible. Note almost all of these 24are optional. 25 26mark_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 31store_to 32 If possible, push data to ring buffer. 33 34read_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 39rip_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 44mark_param_changed 45 Used to indicate that something has changed. Used in conjunction with 46request_update 47 If parameters have changed that require reinitialization or configuration of 48 the ring buffer this will trigger it. 49 50get_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 55get_length / set_length 56 Get/set the number of sample sets that may be held by the buffer. 57 58is_enabled 59 Query if ring buffer is in use 60enable 61 Start the ring buffer. 62