Jonathan Cameron | 44d8b35 | 2011-05-18 14:42:40 +0100 | [diff] [blame^] | 1 | Buffer support within IIO |
Jonathan Cameron | c57f1ba | 2009-08-18 18:06:32 +0100 | [diff] [blame] | 2 | |
| 3 | This document is intended as a general overview of the functionality |
Jonathan Cameron | 44d8b35 | 2011-05-18 14:42:40 +0100 | [diff] [blame^] | 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. |
Jonathan Cameron | c57f1ba | 2009-08-18 18:06:32 +0100 | [diff] [blame] | 8 | |
Jonathan Cameron | 44d8b35 | 2011-05-18 14:42:40 +0100 | [diff] [blame^] | 9 | A given buffer implementation typically embeds a struct |
Jonathan Cameron | c57f1ba | 2009-08-18 18:06:32 +0100 | [diff] [blame] | 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 | |
Jonathan Cameron | 44d8b35 | 2011-05-18 14:42:40 +0100 | [diff] [blame^] | 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 |
Jonathan Cameron | c57f1ba | 2009-08-18 18:06:32 +0100 | [diff] [blame] | 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 |
Jonathan Cameron | 44d8b35 | 2011-05-18 14:42:40 +0100 | [diff] [blame^] | 23 | as much buffer functionality as possible. Note almost all of these |
Jonathan Cameron | c57f1ba | 2009-08-18 18:06:32 +0100 | [diff] [blame] | 24 | are optional. |
| 25 | |
| 26 | mark_in_use, unmark_in_use |
Jonathan Cameron | 44d8b35 | 2011-05-18 14:42:40 +0100 | [diff] [blame^] | 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) |
Jonathan Cameron | c57f1ba | 2009-08-18 18:06:32 +0100 | [diff] [blame] | 29 | |
| 30 | store_to |
Jonathan Cameron | 44d8b35 | 2011-05-18 14:42:40 +0100 | [diff] [blame^] | 31 | If possible, push data to the buffer. |
Jonathan Cameron | c57f1ba | 2009-08-18 18:06:32 +0100 | [diff] [blame] | 32 | |
| 33 | read_last |
Jonathan Cameron | 44d8b35 | 2011-05-18 14:42:40 +0100 | [diff] [blame^] | 34 | If possible, get the most recent scan from the buffer (without removal). |
Jonathan Cameron | c57f1ba | 2009-08-18 18:06:32 +0100 | [diff] [blame] | 35 | This provides polling like functionality whilst the ring buffering is in |
| 36 | use without a separate read from the device. |
| 37 | |
Jonathan Cameron | 44d8b35 | 2011-05-18 14:42:40 +0100 | [diff] [blame^] | 38 | rip_first_n |
| 39 | The primary buffer reading function. Note that it may well not return |
| 40 | as much data as requested. |
Jonathan Cameron | c57f1ba | 2009-08-18 18:06:32 +0100 | [diff] [blame] | 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 |
Jonathan Cameron | 44d8b35 | 2011-05-18 14:42:40 +0100 | [diff] [blame^] | 46 | the buffer this will trigger it. |
Jonathan Cameron | c57f1ba | 2009-08-18 18:06:32 +0100 | [diff] [blame] | 47 | |
Manuel Stahl | 5770b8f | 2010-08-31 11:32:53 +0200 | [diff] [blame] | 48 | get_bytes_per_datum, set_bytes_per_datum |
| 49 | Get/set the number of bytes for a complete scan. (All samples + timestamp) |
Jonathan Cameron | c57f1ba | 2009-08-18 18:06:32 +0100 | [diff] [blame] | 50 | |
| 51 | get_length / set_length |
Jonathan Cameron | 44d8b35 | 2011-05-18 14:42:40 +0100 | [diff] [blame^] | 52 | Get/set the number of complete scans that may be held by the buffer. |
Jonathan Cameron | c57f1ba | 2009-08-18 18:06:32 +0100 | [diff] [blame] | 53 | |
| 54 | is_enabled |
| 55 | Query if ring buffer is in use |
| 56 | enable |
| 57 | Start the ring buffer. |