Skip to content
GitLab
Projects
Groups
Snippets
/
Help
Help
Support
Community forum
Keyboard shortcuts
?
Submit feedback
Contribute to GitLab
Sign in / Register
Toggle navigation
Menu
Open sidebar
François Revol
firmware
Commits
8fec99bb
Verified
Commit
8fec99bb
authored
Jul 18, 2019
by
Rahix
Browse files
docs: Document sensor streams
Signed-off-by:
Rahix
<
rahix@rahix.de
>
parent
5459eead
Changes
3
Hide whitespace changes
Inline
Side-by-side
Documentation/epicardium/sensor-streams.rst
0 → 100644
View file @
8fec99bb
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
View file @
8fec99bb
...
...
@@ -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
View file @
8fec99bb
...
...
@@ -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
)();
};
...
...
Write
Preview
Supports
Markdown
0%
Try again
or
attach a new file
.
Cancel
You are about to add
0
people
to the discussion. Proceed with caution.
Finish editing this message first!
Cancel
Please
register
or
sign in
to comment