From dc66af56c1140ba40bbb3f6cd950e61b2cd86373 Mon Sep 17 00:00:00 2001 From: Ichthyostega Date: Sun, 12 Jul 2026 03:36:28 +0200 Subject: [PATCH] Documentation skeleton to complement the example code ...reusing the template from the "Video Output" example code last year --- FrOSCon26/FrOSCon.26.mm | 50 +++++++++++++++++++ FrOSCon26/examples/README | 83 ++++++++++++++++++++++++++++++++ FrOSCon26/research/DemoSpec.txt | 31 ++++++++++++ FrOSCon26/research/Resources.txt | 57 ++++++++++++++++++++++ 4 files changed, 221 insertions(+) create mode 100644 FrOSCon26/examples/README create mode 100644 FrOSCon26/research/DemoSpec.txt create mode 100644 FrOSCon26/research/Resources.txt diff --git a/FrOSCon26/FrOSCon.26.mm b/FrOSCon26/FrOSCon.26.mm index 1d12846..4e7e14d 100644 --- a/FrOSCon26/FrOSCon.26.mm +++ b/FrOSCon26/FrOSCon.26.mm @@ -663,6 +663,9 @@ + + + @@ -766,6 +769,27 @@ + + + + + + + + + + + +

+ Ist notwendig für andere Sprach-Bindings oder ältere Compiler; dadurch hat dann natürlich jeder Call einen Overhead +

+ + + + + + + @@ -840,10 +864,36 @@ + + + + + + + + + + + + + + + + + +

+ Hatte immer die Fehlermeldung "build misconfigured" (o.ä). Hab lange rumgesucht, denn alle Settings waren effektiv gleich wie beim »VideoOutput«-Projekt. Bis ich dann im .project-File gesehen hab, daß auch noch ein C-Builder konfiguriert worden war (möglichweise ein Toolchain-Default). +

+ + + + + + diff --git a/FrOSCon26/examples/README b/FrOSCon26/examples/README new file mode 100644 index 0000000..e9a5ca9 --- /dev/null +++ b/FrOSCon26/examples/README @@ -0,0 +1,83 @@ +IO_URING and Video Output Example Code +====================================== +:revision: 1.0 +:author: Hermann Voßeler +:date: 8/2026 + + +This directory contains a example code to demonstrate reading data blocks +continuously using the io_uring kernel interface. The loaded data is then +fed to a video display pipeline based on OpenGL / EGL + +[red yellow-background]#Publish on Lumiera.org# +//// +TIP: This demo code has been published on + link:https://lumiera.org/research/videoDisplay/index.html[Lumiera.org] +//// + + +Building the code +----------------- +As convenience, a CMake build system is provided, defining all library prerequisites. + +A typical invocation for a complete build might be... + +[source,sh] +-------------- +cmake -S examples -B build +cmake --build build -- -j4 + +# clean tree with... +cmake --build build --target clean +-------------- + +TIP: The `-j4` option tells make to use 4 cores concurrently to speed up the build. + Furthermore, you might want to configure further options with a graphical GUI, + e.g: `cmake-gui build`; this way you can configure individual library dependencies + to point to custom locations. + +Use at least GCC-14 +~~~~~~~~~~~~~~~~~~~ +[red yellow-background]#TODO: still relevant?# +Some older C++ compilers seem to have problems with a `constexpr` function used in 'commons.hpp'. +Either comment out the line with the static assertion, or use at least GCC-14, which can be +configured for CMake with + +----- +cmake -S examples -B build -DCMAKE_CXX_COMPILER=g++-14 +----- + + +Dependencies +~~~~~~~~~~~~ +Although the prime objective of this demo is to show how to read a sequence of data blocks using io_uring, +the practical example uses this technology to display video frames with an OpenGL pipeline. The framework +is a simple GTK-3 application that integrates OpenGL through EGL (with GLEW). This explains why you +need several distinct groups of dependencies to build the code. The build system only mentions the +top-level dependencies; so either you have to install further transitive dependencies manually, or +(preferrably) you might want to rely on the _package manager_ of a Linux distribution. +The following list shows how to install the dependencies on Debian / Ubuntu. + +Basic build environment:: ++ +----------- +apt install build-essential cmake +----------- ++ +Lib-uring:: ++ +----------- +apt install liburing-dev +----------- ++ +Build a GTK-3 application with C++:: ++ +----------- +apt install libgtkmm-3.0-dev +----------- ++ +EGL Video Display:: ++ +----------- +apt install libx11-dev libglew-dev libegl-dev libgl-dev +----------- diff --git a/FrOSCon26/research/DemoSpec.txt b/FrOSCon26/research/DemoSpec.txt new file mode 100644 index 0000000..d8ac6bf --- /dev/null +++ b/FrOSCon26/research/DemoSpec.txt @@ -0,0 +1,31 @@ +Specification for the Demo +========================== +:Date: Summer 2026 +:Author: Ichthyostega +:toc: +:toclevels: 3 + +This specification is the result of our research and provides a short summary of the relevant +aspects of io_uring. Furthermore, the specific design of the demo code is explained and motivated. + +[red yellow-background]#TBW# + + +IO_URING kernel interface +------------------------- + +Liburing +~~~~~~~~ +This helper library provides a thin wrapper to encapsulate most of the minute technical details +related to the ringbuffers. The kernel interface as such is defined in a rather indirect way, +so that most data definitions are exposed dynamically, at runtime in the form of relative field +offsets. Also the structure of the ringbuffers is not defined directly as a data type; rather +the well-known low-level C implementation of a index based ringbuffer is assumed like a coding +template. Working with such a structure requires solid knowledge in system programming, including +the proper usage of memory barriers. The Liburing handles all those tricky details behind a function +based interface, that should be much more familiar to most programmers. + +To avoid a performance penalty due to this indirection and encapsulation, Liburing is defined +to a large extent in the form of _static inline functions_. A variant called `liburing-ffi` is provided +as alternative for cross-language bindings and for usage with older compilers, providing an definition +and binary symbol for each function; obviously using these explicit calls adds a noticeable penalty. diff --git a/FrOSCon26/research/Resources.txt b/FrOSCon26/research/Resources.txt new file mode 100644 index 0000000..2d6e501 --- /dev/null +++ b/FrOSCon26/research/Resources.txt @@ -0,0 +1,57 @@ +Links and Resources +=================== + + +Topic: Kernel and IO +-------------------- + + +Asynchronous IO +~~~~~~~~~~~~~~~ + - TODO + + + + +IO_URING +-------- +Introduction +~~~~~~~~~~~~ + * https://unixism.net/loti/[»Lord of the uring«] + + +Reference +~~~~~~~~~ + * https://unixism.net/loti/ref-liburing/index.html[Overview (liburing)] + + ** https://unixism.net/loti/ref-liburing/submission.html[Submission and Submission helpers] + ** Liburing provides _submission helpers_ for common Kernel IO calls... + + - https://unixism.net/loti/ref-liburing/submission.html#c.io_uring_prep_nop[io_uring_prep_nop] + - https://unixism.net/loti/ref-liburing/submission.html#c.io_uring_prep_read[io_uring_prep_read] + - https://unixism.net/loti/ref-liburing/submission.html#c.io_uring_prep_write[io_uring_prep_write] + - https://unixism.net/loti/ref-liburing/submission.html#c.io_uring_prep_readv[io_uring_prep_readv] + - https://unixism.net/loti/ref-liburing/submission.html#c.io_uring_prep_read_fixed[io_uring_prep_read_fixed] + - https://unixism.net/loti/ref-liburing/submission.html#c.io_uring_prep_writev[io_uring_prep_writev] + - https://unixism.net/loti/ref-liburing/submission.html#c.io_uring_prep_write_fixed[io_uring_prep_write_fixed] + - https://unixism.net/loti/ref-liburing/submission.html#c.io_uring_prep_fsync[io_uring_prep_fsync] + - https://unixism.net/loti/ref-liburing/submission.html#c.io_uring_prep_close[io_uring_prep_close] + - https://unixism.net/loti/ref-liburing/submission.html#c.io_uring_prep_openat[io_uring_prep_openat] + - https://unixism.net/loti/ref-liburing/submission.html#c.io_uring_prep_openat2[io_uring_prep_openat2] + - https://unixism.net/loti/ref-liburing/submission.html#c.io_uring_prep_fallocate[io_uring_prep_fallocate] + - https://unixism.net/loti/ref-liburing/submission.html#c.io_uring_prep_statx[io_uring_prep_statx] + - https://unixism.net/loti/ref-liburing/submission.html#c.io_uring_prep_fadvise[io_uring_prep_fadvise] + - https://unixism.net/loti/ref-liburing/submission.html#c.io_uring_prep_madvise[io_uring_prep_madvise] + - https://unixism.net/loti/ref-liburing/submission.html#c.io_uring_prep_splice[io_uring_prep_splice] + - https://unixism.net/loti/ref-liburing/submission.html#c.io_uring_prep_recvmsg[io_uring_prep_recvmsg] + - https://unixism.net/loti/ref-liburing/submission.html#c.io_uring_prep_sendmsg[io_uring_prep_sendmsg] + - https://unixism.net/loti/ref-liburing/submission.html#c.io_uring_prep_recv[io_uring_prep_recv] + - https://unixism.net/loti/ref-liburing/submission.html#c.io_uring_prep_send[io_uring_prep_send] + - https://unixism.net/loti/ref-liburing/submission.html#c.io_uring_prep_accept[io_uring_prep_accept] + - https://unixism.net/loti/ref-liburing/submission.html#c.io_uring_prep_connect[io_uring_prep_connect] + - https://unixism.net/loti/ref-liburing/submission.html#c.io_uring_prep_epoll_ctl[io_uring_prep_epoll_ctl] + - https://unixism.net/loti/ref-liburing/submission.html#c.io_uring_prep_poll_add[io_uring_prep_poll_add] + - https://unixism.net/loti/ref-liburing/submission.html#c.io_uring_prep_poll_remove[io_uring_prep_poll_remove] + + +[purple]#maybe more resources regarding the low-level API...?#