From 13386d1af20bf3e1a7b5e6b71716c7b59100a053 Mon Sep 17 00:00:00 2001
From: Rahix <rahix@rahix.de>
Date: Fri, 19 Jul 2019 18:10:05 +0200
Subject: [PATCH] docs: Improve stream documentation
Signed-off-by: Rahix <rahix@rahix.de>
---
epicardium/epicardium.h | 20 +++++++++++++-------
epicardium/modules/stream.h | 9 +++++----
2 files changed, 18 insertions(+), 11 deletions(-)
diff --git a/epicardium/epicardium.h b/epicardium/epicardium.h
index cc0926d1..b87cce5c 100644
--- a/epicardium/epicardium.h
+++ b/epicardium/epicardium.h
@@ -68,11 +68,18 @@ API(API_LEDS_SET, void epic_leds_set(int led, uint8_t r, uint8_t g, uint8_t b));
/**
* Read sensor data into a buffer. ``epic_stream_read()`` will read as many
- * sensor data packets as possible into ``buf`` and return as soon as possible.
- * It will poke the sensor driver once to check whether new data can be fetched.
- * If there is no new sensor data, ``epic_stream_read()`` will return ``0`` and
- * not touch ``buf``. Otherwise it will return the number of data packets which
- * were read into ``buf``.
+ * sensor samples into the provided buffer as possible and return the number of
+ * samples written. If no samples are available, ``epic_stream_read()`` will
+ * return ``0`` immediately.
+ *
+ * ``epic_stream_read()`` expects the provided buffer to have a size which is a
+ * multiple of the sample size for the given stream. For the sample-format and
+ * size, please consult the sensors documentation.
+ *
+ * Before reading the internal sensor sample queue, ``epic_stream_read()`` will
+ * call a sensor specific *poll* function to allow the sensor driver to fetch
+ * new samples from its hardware. This should, however, never take a long
+ * amount of time.
*
* :param int sd: Sensor Descriptor. You get sensor descriptors as return
* values when activating the respective sensors.
@@ -84,8 +91,7 @@ API(API_LEDS_SET, void epic_leds_set(int led, uint8_t r, uint8_t g, uint8_t b));
*
* - ``-ENODEV``: Sensor is not currently available.
* - ``-EBADF``: The given sensor descriptor is unknown.
- * - ``-EINVAL``: If ``count`` is not a multiple of the sensor data packet
- * size.
+ * - ``-EINVAL``: ``count`` is not a multiple of the sensor's sample size.
*
* **Example**:
*
diff --git a/epicardium/modules/stream.h b/epicardium/modules/stream.h
index 74741566..622aee40 100644
--- a/epicardium/modules/stream.h
+++ b/epicardium/modules/stream.h
@@ -7,8 +7,6 @@
#include "FreeRTOS.h"
#include "queue.h"
-#define STREAM_QUEUE_WAIT pdMS_TO_TICKS(10)
-
/**
* **Stream Descriptors**:
*
@@ -38,11 +36,14 @@ struct stream_info {
/** The size of one data packet (= queue element). */
size_t item_size;
/**
- * An optional function to call before performing the read.
+ * An optional function to call before performing the read. Set to
+ * ``NULL`` if unused.
*
* ``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.
+ *
+ * The function registered here should never block for a longer time.
*/
int (*poll_stream)();
};
@@ -50,7 +51,7 @@ struct stream_info {
/**
* Register a stream so it can be read from Epicardium API.
*
- * :param int sd: Stream Descriptor. Must be from the above enum.
+ * :param int sd: Stream Descriptor. Must be from the :c:type:`stream_descriptor` enum.
* :param stream_info stream: Stream info.
* :returns: ``0`` on success or a negative value on error. Possible errors:
*
--
GitLab