From: Alexandru Ardelean <email@example.com>
To: <firstname.lastname@example.org>, <email@example.com>
Cc: <firstname.lastname@example.org>, <Michael.Hennerich@analog.com>,
Alexandru Ardelean <email@example.com>
Subject: [PATCH v4 2/6] Documentation: iio: add doc for high-speed buffer API
Date: Wed, 17 Feb 2021 09:36:34 +0200 [thread overview]
Message-ID: <firstname.lastname@example.org> (raw)
This change takes the comment from the commit that introduces the IIO
high-speed buffer API, and formats it into rst format.
Signed-off-by: Alexandru Ardelean <email@example.com>
Documentation/iio/iio_high_speed_buffers.rst | 100 +++++++++++++++++++
Documentation/iio/index.rst | 2 +
include/uapi/linux/iio/buffer.h | 5 +
3 files changed, 107 insertions(+)
create mode 100644 Documentation/iio/iio_high_speed_buffers.rst
diff --git a/Documentation/iio/iio_high_speed_buffers.rst b/Documentation/iio/iio_high_speed_buffers.rst
new file mode 100644
@@ -0,0 +1,100 @@
+Industrial IO High-Speed Buffer API
+Industrial IO supports access to buffers via an mmap interface. The
+advantage of the mmap based interface compared to the read() based
+interface is that it avoids an extra copy of the data between kernel and
+userspace. This is particular useful for high-speed devices which produce
+several megabytes or even gigabytes of data per second.
+The data for the mmap interface is managed at the granularity of so called
+blocks. A block is a contiguous region of memory (at the moment both
+physically and virtually contiguous). Reducing the granularity from byte
+level to block level is done to reduce the userspace-kernelspace
+synchronization overhead since performing syscalls for each byte at a
+data-rate of a few megabytes is not feasible.
+This of course leads to a slightly increased latency. For this reason an
+application can choose the size of the blocks as well as how many blocks it
+allocates. E.g. two blocks would be a traditional double buffering scheme.
+But using a higher number might be necessary to avoid underflow/overflow
+situations in the presence of scheduling latencies.
+A block can either be owned by kernel space or userspace. When owned by
+userspace it is safe to access the data in the block and process it. When
+owned by kernel space the block can be in one of 3 states:
+* It can be in the incoming queue where all blocks submitted from userspace
+ are placed and are waiting to be processed by the kernel driver.
+* It can be currently being processed by the kernel driver, this means it is
+ actively placing capturing data in it (usually using DMA).
+* Or it can be in the outgoing queue where all blocks that have been
+ processed by the kernel are placed. Userspace can dequeue the blocks as
+As part of the interface 5 IOCTLs are used to manage the blocks and exchange
+them between userspace and kernelspace. The IOCTLs can be accessed through
+a open file descriptor to a IIO device.
+* **IIO_BUFFER_BLOCK_ALLOC_IOCTL(struct iio_buffer_block_alloc_req *)**:
+ Allocates new blocks. Can be called multiple times if necessary. A newly
+ allocated block is initially owned by userspace.
+ Frees all previously allocated blocks. If the backing memory of a block is
+ still in use by a kernel driver (i.e. active DMA transfer) it will be
+ freed once the kernel driver has released it.
+* **IIO_BUFFER_BLOCK_QUERY_IOCTL(struct iio_buffer_block *)**:
+ Queries information about a block. The id of the block about which
+ information is to be queried needs to be set by userspace.
+* **IIO_BUFFER_BLOCK_ENQUEUE_IOCTL(struct iio_buffer_block *)**:
+ Places a block on the incoming queue. This transfers ownership of the
+ block from userspace to kernelspace. Userspace must populate the id field
+ of the block to indicate which block to enqueue.
+* **IIO_BUFFER_BLOCK_DEQUEUE_IOCTL(struct iio_buffer_block *)**:
+ Removes the first block from the outgoing queue. This transfers ownership
+ of the block from kernelspace to userspace. Kernelspace will populate all
+ fields of the block. If the queue is empty and the file descriptor is set
+ to blocking the IOCTL will block until a new block is available on the
+ outgoing queue.
+To access the data stored in a block by userspace the block must be mapped
+to the process's memory. This is done by calling mmap() on the IIO device
+file descriptor. Each block has a unique offset assigned to it which should
+be passed to the mmap interface. E.g.
+ mmap(0, block.size, PROT_READ | PROT_WRITE, MAP_SHARED, fd,
+A typical workflow for the new interface is:
+ foreach block
+ BLOCK_QUERY block
+ mmap block.data.offset
+ BLOCK_ENQUEUE block
+ enable buffer
+ while !done
+ BLOCK_DEQUEUE block
+ process data
+ BLOCK_ENQUEUE block
+ disable buffer
diff --git a/Documentation/iio/index.rst b/Documentation/iio/index.rst
index 58b7a4ebac51..aaba78770b47 100644
@@ -9,4 +9,6 @@ Industrial I/O
diff --git a/include/uapi/linux/iio/buffer.h b/include/uapi/linux/iio/buffer.h
index d18692d14aa5..5ec8a4fa3332 100644
@@ -7,6 +7,11 @@
+ * See for more details:
+ * Documentation/iio/iio_high_speed_buffers.rst
* struct iio_buffer_block_alloc_req - Descriptor for allocating IIO buffer blocks
* @type: type of block(s) to allocate (currently unused, reserved)
next prev parent reply other threads:[~2021-02-17 7:35 UTC|newest]
Thread overview: 9+ messages / expand[flat|nested] mbox.gz Atom feed top
2021-02-17 7:36 [PATCH v4 0/6] iio: core: Add mmap interface infrastructure Alexandru Ardelean
2021-02-17 7:36 ` [PATCH v4 1/6] " Alexandru Ardelean
2021-02-17 7:36 ` Alexandru Ardelean [this message]
2021-02-17 7:36 ` [PATCH v4 3/6] iio: buffer-dma: split iio_dma_buffer_fileio_free() function Alexandru Ardelean
2021-02-17 7:36 ` [PATCH v4 4/6] iio: buffer-dma: reduce the type of block.size to u32 Alexandru Ardelean
2021-02-17 7:36 ` [PATCH v4 5/6] iio: buffer-dma: Add mmap support Alexandru Ardelean
2021-02-17 7:36 ` [PATCH v4 6/6] tools: iio: add example for high-speed buffer support Alexandru Ardelean
2021-02-18 13:10 ` [PATCH v4 0/6] iio: core: Add mmap interface infrastructure Jonathan Cameron
2021-02-27 17:52 ` Jonathan Cameron
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).