Documentation skeleton to complement the example code

...reusing the template from the "Video Output" example code last year
2026-07-12 03:36:28 +02:00 · 2026-07-12 03:36:28 +02:00 · dc66af56c1
commit dc66af56c1
parent be38f2a0d1
4 changed files with 221 additions and 0 deletions
--- a/FrOSCon26/FrOSCon.26.mm
+++ b/FrOSCon26/FrOSCon.26.mm
@ -663,6 +663,9 @@
 <node CREATED="1783440926298" ID="ID_170963361" MODIFIED="1783440944465" TEXT="eine Schnittstellen-struct io_uring">
 <icon BUILTIN="ksmiletris"/>
 </node>
+<node CREATED="1783820387473" ID="ID_215295477" MODIFIED="1783820445186" TEXT="modernes C/C++ weitgehend header-only / static-inline">
+<arrowlink COLOR="#4387d9" DESTINATION="ID_569042424" ENDARROW="Default" ENDINCLINATION="-977;-775;" ID="Arrow_ID_876718032" STARTARROW="None" STARTINCLINATION="81;442;"/>
+</node>
 </node>
 <node CREATED="1783440846153" ID="ID_1052852486" MODIFIED="1783440859478" TEXT="man kann...">
 <node CREATED="1783440860347" ID="ID_134839902" MODIFIED="1783440877595" TEXT="auf den n&#xe4;chsten CQ-Entry blockend warten"/>
@ -766,6 +769,27 @@
 </node>
 </node>
 </node>
+<node CREATED="1783820353490" ID="ID_806269718" MODIFIED="1783820356649" TEXT="Detail-Themen">
+<node CREATED="1783820358773" ID="ID_492574690" MODIFIED="1783820363860" TEXT="Performance-Aspekte">
+<node CREATED="1783820364596" ID="ID_569042424" MODIFIED="1783820440351" TEXT="liburing ist komplett als static-inline definiert">
+<linktarget COLOR="#4387d9" DESTINATION="ID_569042424" ENDARROW="Default" ENDINCLINATION="-977;-775;" ID="Arrow_ID_876718032" SOURCE="ID_215295477" STARTARROW="None" STARTINCLINATION="81;442;"/>
+<node CREATED="1783820461975" ID="ID_715616295" MODIFIED="1783820480357" TEXT="mit optimiser also praktisch direkter Kernel-Aufruf"/>
+<node CREATED="1783820481050" ID="ID_1869508632" MODIFIED="1783820542141" TEXT="liburing-ffi: definiert alle calls als binary-Symbols (&#x27f9; langsamer)">
+<richcontent TYPE="NOTE"><html>
+  <head>
+    
+  </head>
+  <body>
+    <p>
+      Ist notwendig f&#252;r andere Sprach-Bindings oder &#228;ltere Compiler; dadurch hat dann nat&#252;rlich jeder Call einen Overhead
+    </p>
+  </body>
+</html>
+</richcontent>
+</node>
+</node>
+</node>
+</node>
 </node>
 </node>
 <node BACKGROUND_COLOR="#eee5c3" COLOR="#990000" CREATED="1519001955679" ID="ID_65625223" MODIFIED="1779386731937" TEXT="Demo-Inhalte">
@ -840,10 +864,36 @@
 </richcontent>
 </node>
 <node CREATED="1783788648324" ID="ID_1920636432" MODIFIED="1783788665326" TEXT="nehme sofort die Dependencies f&#xfc;r OpenGL / EGL mit dazu"/>
+<node BACKGROUND_COLOR="#c8c0b6" COLOR="#435e98" CREATED="1783819908913" ID="ID_813164182" MODIFIED="1783820014700" TEXT="Liburing">
+<font BOLD="true" NAME="SansSerif" SIZE="12"/>
+<node CREATED="1783819936485" ID="ID_15961209" MODIFIED="1783819937734" TEXT="apt install liburing-dev"/>
+<node CREATED="1783819973578" ID="ID_1822496144" MODIFIED="1783820003203" TEXT="Debian-Trixie: liburing2:amd64 2.9-1"/>
+<node CREATED="1783819939590" ID="ID_251450941" MODIFIED="1783819959674" TEXT="liburing.pc"/>
+</node>
 <node COLOR="#338800" CREATED="1783788814487" ID="ID_1955496379" MODIFIED="1783788819238" TEXT="Hello-Uring l&#xe4;uft">
 <icon BUILTIN="button_ok"/>
 </node>
 </node>
+<node COLOR="#435e98" CREATED="1783795438472" FOLDED="true" ID="ID_1695706583" MODIFIED="1783795624063" TEXT="(Eclipse-Setup)">
+<icon BUILTIN="info"/>
+<node CREATED="1783795458277" ID="ID_840412256" MODIFIED="1783795469953" TEXT="Projekt-Skelett anlegen"/>
+<node CREATED="1783795470514" ID="ID_840042890" MODIFIED="1783795474897" TEXT="einmal mit CMake bauen"/>
+<node CREATED="1783795475774" ID="ID_1250076625" MODIFIED="1783795489958" TEXT="als &quot;external builder Make&quot;-Projekt importieren"/>
+<node BACKGROUND_COLOR="#e0ceaa" COLOR="#690f14" CREATED="1783795490756" ID="ID_972729826" MODIFIED="1783795620602" TEXT="Vorsicht: brauche keinen C-Build">
+<richcontent TYPE="NOTE"><html>
+  <head>
+    
+  </head>
+  <body>
+    <p>
+      Hatte immer die Fehlermeldung &quot;build misconfigured&quot; (o.&#228;). Hab lange rumgesucht, denn alle Settings waren effektiv gleich wie beim &#187;VideoOutput&#171;-Projekt. Bis ich dann im .project-File gesehen hab, da&#223; auch noch ein C-Builder konfiguriert worden war (m&#246;glichweise ein Toolchain-Default).
+    </p>
+  </body>
+</html>
+</richcontent>
+<icon BUILTIN="messagebox_warning"/>
+</node>
+</node>
 <node CREATED="1783644343706" ID="ID_481307677" MODIFIED="1783644354828" TEXT="ein GTK-Rahmen (wie letztes Jahr)"/>
 <node CREATED="1783644357376" ID="ID_1687423764" MODIFIED="1783644363091" TEXT="ein Worker-Thread"/>
 <node CREATED="1783644382004" ID="ID_222096554" MODIFIED="1783644392847" TEXT="Handler">
--- a/FrOSCon26/examples/README
+++ 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
+-----------
--- a/FrOSCon26/research/DemoSpec.txt
+++ b/FrOSCon26/research/DemoSpec.txt
@ -0,0 +1,31 @@
+Specification for the Demo
+==========================
+:Date: Summer 2026
+:Author: Ichthyostega <Ichthyostega@web.de>
+: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.
--- a/FrOSCon26/research/Resources.txt
+++ 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...?#