| Buffer support within IIO |
| |
| This document is intended as a general overview of the functionality |
| a buffer may supply and how it is specified within IIO. For more |
| specific information on a given buffer implementation, see the |
| comments in the source code. Note that some drivers allow buffer |
| implementation to be selected at compile time via Kconfig options. |
| |
| A given buffer implementation typically embeds a struct |
| iio_ring_buffer and it is a pointer to this that is provided to the |
| IIO core. Access to the embedding structure is typically done via |
| container_of functions. |
| |
| struct iio_ring_buffer contains a struct iio_ring_setup_ops *setup_ops |
| which in turn contains the 4 function pointers |
| (preenable, postenable, predisable and postdisable). |
| These are used to perform device specific steps on either side |
| of the core changing it's current mode to indicate that the buffer |
| is enabled or disabled (along with enabling triggering etc as appropriate). |
| |
| Also in struct iio_ring_buffer is a struct iio_ring_access_funcs. |
| The function pointers within here are used to allow the core to handle |
| as much buffer functionality as possible. Note almost all of these |
| are optional. |
| |
| mark_in_use, unmark_in_use |
| Basically indicate that not changes should be made to the buffer state that |
| will effect the form of the data being captures (e.g. scan elements or length) |
| |
| store_to |
| If possible, push data to the buffer. |
| |
| read_last |
| If possible, get the most recent scan from the buffer (without removal). |
| This provides polling like functionality whilst the ring buffering is in |
| use without a separate read from the device. |
| |
| rip_first_n |
| The primary buffer reading function. Note that it may well not return |
| as much data as requested. |
| |
| mark_param_changed |
| Used to indicate that something has changed. Used in conjunction with |
| request_update |
| If parameters have changed that require reinitialization or configuration of |
| the buffer this will trigger it. |
| |
| get_bytes_per_datum, set_bytes_per_datum |
| Get/set the number of bytes for a complete scan. (All samples + timestamp) |
| |
| get_length / set_length |
| Get/set the number of complete scans that may be held by the buffer. |
| |
| is_enabled |
| Query if ring buffer is in use |
| enable |
| Start the ring buffer. |