docs: Document sensor streams

Signed-off-by: Rahix <rahix@rahix.de>

Documentation/epicardium/sensor-streams.rst

+Sensor Streams
+==============
+Sensor drivers can make their data available to core 1 in a stream-like format.
+This allows batch-reading many samples and shoud reduce pressure on the
+Epicardium API this way.  Sensor streams are read on core 1 using
+:c:func:`epic_stream_read`.
+
+This page intends to document how to add this stream interface to a sensor driver.
+It also serves as a reference of existing streams.  For that, take a look at the
+definitions in the :c:type:`stream_descriptor` enum.
+
+Adding a new Stream
+-------------------
+The list of possible sensor streams must be known at compile time.  Each stream
+gets a unique ID in the :c:type:`stream_descriptor` enum.  Please do not assign
+IDs manually but instead let the enum assign sequencial IDs.  :c:macro:`SD_MAX`
+must always be the highest stream ID.  Additionally, please document what this
+stream is for using a doc-comment so it shows up on this page.
+
+When a sensor driver enables data collection, it should also register its
+respective stream.  This is done using a :c:type:`stream_info` object.  Pass
+this object to :c:func:`stream_register` to make your stream available.  Your
+driver must guarantee the :c:member:`stream_info.queue` handle to be valid until
+deregistration using :c:func:`stream_deregister`.
+
+Definitions
+-----------
+
+.. c:autodoc:: epicardium/modules/stream.h

Documentation/index.rst

@@ -35,6 +35,7 @@ Last but not least, if you want to start hacking the lower-level firmware, the
    debugger
    pycardium-guide
    memorymap
+   epicardium/sensor-streams
 
 .. toctree::
    :maxdepth: 1
@@ -43,5 +44,3 @@ Last but not least, if you want to start hacking the lower-level firmware, the
    epicardium/overview
    epicardium/api
    epicardium-guide
-
-

epicardium/modules/stream.h

@@ -10,18 +10,37 @@
 /**
  * **Stream Descriptors**:
  *
- *    All supported streams have to have a unique ID in this list.  ``SD_MAX``
- *    must be greater than or equal to the highest defined ID.  Please keep IDs
- *    in sequential order.
+ *    All supported streams have to have a unique ID in this list.  :c:macro:`SD_MAX`
+ *    must be greater than or equal to the highest defined ID.  Please keep IDs in
+ *    sequential order.
  */
 enum stream_descriptor {
 	/** Highest descriptor must always be ``SD_MAX``. */
 	SD_MAX,
 };
 
+/**
+ * Stream Information Object.
+ *
+ * This struct contains the information necessary for :c:func:`epic_stream_read`
+ * to read from a sensor's stream.  This consists of:
+ */
 struct stream_info {
+	/**
+	 * A FreeRTOS queue handle.
+	 *
+	 * Management of this queue is the sensor drivers responsibility.
+	 */
 	QueueHandle_t queue;
+	/** The size of one data packet (= queue element). */
 	size_t item_size;
+	/**
+	 * An optional function to call before performing the read.
+	 *
+	 * ``poll_stream()`` is intended for sensors who passively collect data.
+	 * A sensor driver might for example retrieve the latest samples in this
+	 * function instead of actively polling in a task loop.
+	 */
 	int (*poll_stream)();
 };